[DOC] README: Improve build instructions, esp. rom.bin information

[0cjs]

• Extract URLs to references for cleaner plaintext.
• Explain the rom.bin situation, and where to go to get/build your own.
• Remove references to CC65; that's for the ROM, not the emulator.
• Add name of Debian SDL2 dev package.

[0cjs]

@mist64 I've put in a separate PR, #160, for the header reformat for README.md, since that's uncontroversial. Once that's in I'll rebase this branch on it, or I can just close that and include the commit in this branch if you prefer.

Before this branch will be ready for review I need to know if you want a separate BUILD.md file (perhaps even merging in webassembly/WebAssembly.md or if you want the current contents of BUILD.md to go back into README.md, amending the build information that was already there.

[mist64]

I'l like to have build instructions as part of README.md, but the WebAssembly part should remain in its own file.

[y2k4life]

RE: My Build Process

The link above is the process I use. It is more than changing the README.md. I did not envision my changes being merged back into this repository because of the changes to the Makefile and patching main.c file. I explain my reasoning in my README.md. Therefore I just made changes in my local repository changing the README.md to just building . It is also Linux based without testing on Mac, in theory it should work . No support to build on Windows, you can target Windows but need to build on Linux.

I would assume the goal is to build something that works. Leaving out the build process for the ROMs would not reach that goal.

Wondering how this will fit in with the changes to using CMake?

They are extensive step by step instructions without leaving anything out, geared towards Linux build environment targeting either Windows or Linux.

Might need different instructions for building on different platforms and targeting different platforms.

[y2k4life]

Giving more thoughts on the ROMs, if you build the emulator then building the ROMs is a separate processes. If you package the emulator then the ROMs are compiled. The packaging is part of the emulator.

The goal being to have a running emulator. The steps missing from my process are what to do after you build the emulator. What I do for simplicity is package the emulator then extract to a folder. After that when I build the emulator I copy the x16emu program to where I extracted the packaged emulator. But the concept is not in the instructions. Or you could build the ROMs, then build the emulator, then copy the separate pieces to folder. What files to copy and where is missing from the instructions

[0cjs]

Sorry about the close; GitHub interpreted my reworking of the branch as a request to close the PR. (TIL.)

This is now a single commit adding the appropriate information to the README and is ready for review and merge.

[0cjs]

@y2k4life So you're bringing up two good issues, but they're both beyond the scope of this PR and deserve their own issues or PRs. (Remember you can reference comments here in a new issue by using the ⋯ menu on the comment.)

Cross-building the Windows version from Linux sounds cool to me, but I'm not a Windows guy so I'm not the one to ask if this is useful or not. I would wonder about the procedures for testing that build.

Regarding the ROM image, I think the documentation updates in this PR go a long way to helping out with that. If it were going to be fully automated, the build system here might clone a copy of the x16-rom repo and kick off a build there, or get even more precise by using a Git submodule so we're recording exactly what ROM source version is supposed to work with that particular commit of the emulator. I don't know if that's really worth the effort, at least at the moment, though.

One of the things that's very helpful is to try to clearly state the high-level problem you're trying to solve and the audience it's aimed at. For this particular PR, for example, it's developers unfamiliar with this system who want to get started on building the bleeding-edge emulator and ROMs with an eye to doing further development on either one of those. I expect they will clone their own copies of both repos and, once they start doing development, fork their own copies and commit in the forks. I'm not sure for those folks that providing more automated assistance for this is of much value. (And I just realized that working in forks with simultaneous PRs for emulator changes that require ROM changes probably breaks the submodule thing.)

The most common case is probably just "hack in ROM repo, build, run .../x16emu -rom ./rom.bin," followed by "hack in emu repo, build, run ./x16emu -rom .../rom.bin." Improving that seeems at first blush to be heading towards making things more complex, rather than simpler.

If you're looking for a way that naive users can do their own bleeding-edge build, a better solution might be to have a third repo that does this, cloning both the emulator and rom repos and controlling the builds in both. I don't know if there's much of an audience for that, though.

[y2k4life]

@0cjs Trying to figure out the audience is a challenge with cross platform projects and when the build process is from one OS to the next is different. Further more is when the OS you build on can build for another OS. I'm also wondering about timing with writing the "how to build" in stone if the processes of building will change related to pull request #64. I try to evaluate all of the options and if possible find the least common denominator and write for that. But with this project it might not be so easy.

In my opinion I don't think these instruction should be in the READ.md or a separate markdown. I think they should be in the Wiki. I got some of my insperation from the last piece on this page of the Wiki Building from scratch on Mac. Start with questions and links leading to where you need to go. Just look at my README. Trying to combine a lengthy thorough instructions with release notes and features would be a lengthy README document. Now try to add instructions for CMake or Mac. I would suggest putting links in the README to the Build sections of the Wiki. Start the Wiki with question to gauge the audience. Are you on Linux? Are you doing Cross Compiling? Are you packaging the Builds? Are you on Windows? Are you using Visual Studio and CMake? Are you on a Mac?

I wanted to create a solution that might be for those that have Windows but don't use Linux often and might only have WSL. The building for Windows might be a moot point with #64.

I also want a solution that would work with what is there and only minor modifications.

What I did was create instructions that cover two scenarios/audiences using Linux. I also built the instruction with a step by step covering everything and leave nothing out. From my experience I find that I can still use very thorough instruction even though I don't need them. Knowing that others with less experience can use them as well. I just skip the parts I don't need. Like making sure Linux is up to date. Or making sure the dev tools are installed. I don't need them but others might.

I'm a Windows/Linux Guy, but not a Mac person. Which complicates things further because I'm not able to create a solution for all audiences. But I was able to cover two of them.

My approach stemmed from wanting to build the Windows version using what is in this repo and not other (unofficial) solutions. At the same time build for Linux. The instructions and the Makefile assume the building for Windows is on a Mac.

I was able to create a build process that targets both Linux and Windows from a Linux host either WSL or Linux on a machine. What I was not able to test, but in theory might work is building on a Mac. To answer the question of testing the Windows version built from Linux would follow testing the same way testing of the emulator is done for any other build processes. As of now for me that is, does it run, and does it run programs. Which it does.

I want as many people to learn and have an opportunity to learn. The 8-bit world is where I learned computers. This whole project just might be where the naive person is coming to learn. This project has so much to learn from, emulators, CPU emulation, sound chips, BASIC, assembly language. How to cross compile projects on Linux, etc... As stated before having instructions for less experienced would also work for those with more experience. Not mention there will be more to learn when this turns into actual hardware.

[0cjs]

You are absoutely correct that the build process should not be written in stone. Not only when PR #64 is pending, but at any time. Fortunately it's not written in stone; any commit that changes the process can and should update the README appropriately as well.

I strongly disagree that the core build instructions should be in the Wiki; documentation on how to use the source is as essential as the programming language source code itself, and should be kept consistent with it, so these should be kept together. Further, instructions in documentation are "executed" by a person, but a refactoring or other change may move some of the execution responsibility to the computer (via scripts or whatever), where it should make obvious sense that it should be in the repo. (In general, actually, I believe that one should use scripts rather than documentation to encode build instructions, but of course not when the script would be more fragile than developer documentation. I considered adding a script at this point, but on the balance I felt that it was better just to get this in now and learn more before proposing that.)

(I do not object to "here's what a build system is" tutorials being in the Wiki, but that's not actually information for developers; that's information for people who want to learn to be developers. Putting that in the README would probably get in the way of experienced developers.)

Consider also that a repo on GitHub forms a type of Wiki itself; the "pages" (Markdown files) are nicely rendered, can be edited, etc. For a fairly large example of this see my sedoc repo.

As far as the audience goes, look at likely and desired audiences, not every potential audience that could exist. Are we likely right now to have people doing the packaging who do not understand the current build process and the ROM issues? I'd say not, because if they don't understand that they shouldn't be doing the packaging. Thus, we need not introduce the extra complexity of handling packging for people without that knowledge right now, and instead should focus on what we need to do to get people who want to do packaging up to that level of knowledge, which is exactly one of the audiences I was aiming at with this commit. (And note that this is also the audience that wants to learn, as opposed to the audience that wants to do packaging without learning about this.)

Trying to combine a lengthy thorough instructions with release notes and features would be a lengthy README document.

Yes, and I think we all agree that too-long README documents should be avoided, which was why my first version of this commit pulled all the building information out to a separate BUILD.md file (linked from the README, of course).

But when a REAMDE is too long is a judgement call, Michael finds the current lenth of it not to be a problem, and said he prefers with this particular change not to split out the build instructions. (That's for this change; dont' take that to mean he won't want to do so in the future.) I'm fine with going along with that because he's done a lot more work on this project than I have and knows the other users and developers better than me.

At any rate, this is all getting quite off-topic for this PR, where the specific goal is a small improvement to the current documentation, so I'd suggest that if you have further thoughts on this you start a separate issue using the "Reference in new issue" option from the menu at the upper-right of this comment.

[0cjs]

@mist64 So I just wanted to check in and see if there are any changes you want made for this, or if it's ready to be merged.