The advantages of generating disassembly websites from the source code
Back in the first lockdown of 2020, I started poking around inside the BBC Micro version of Elite. Pulling apart 8-bit code from a bygone era gave me a zen-like refuge from the outside world, and that's when I fell in love with the art of disassembly.
To be honest, I got carried away, but those were strange times. You can read the full story on my Elite website, but the first release back in August 2020 consisted of a huge text file containing fully buildable source code for the cassette version of BBC Micro Elite, with every single line explained. I also inserted a number of deep dives into the source, and the resulting 1.6MB text file ran to 41,274 lines of lovingly crafted homage to this epic game.
I uploaded the first version of the source to GitHub, and people liked it. I was pretty happy with how that initial release turned out, and it still looks great in an old-school terminal with an 80-column width:
Unfortunately the main source file was too large to browse properly on GitHub; you can view much larger files with GitHub these days, but back then the only option was to download the raw text file. So I knocked together a quick Python script to extract the code from the source files and produce a web-based version of the commentary, and I added a few handy features like popups with more information and linked cross-references. Take a look at the web version of the TIS2 routine - it's a lot friendlier than the vi-based version in the above screenshot.
In the process I also removed the deep dives from amongst the source code and published them on the website instead, and the results proved pretty popular (here's what people thought on Hacker News).
And then there was a second lockdown in late 2020, so I turned to the 6502 Second Processor source code and started pulling that version apart. It was obvious from early on that there was an awful lot of shared code between the BBC Micro cassette version and the 6502 Second Processor version, and after a few attempts to sync the comments between the cassette commentary and the co-processor version, I wondered if there might be a better way of doing this.
So I created a single repository to contain the source code for both versions, sharing as much content as possible between the two sources, and incorporating a build process that used conditional logic in the BeebAsm assembler source to support the building of both versions from the same repository. This grew into the library project of fully commented and buildable Elite source code at library-elite-beebasm, and I built a second Python script to generate the fully documented source code for both versions of Elite, using the library as a single source of truth. The resulting 6502 Second Processor commentary went live in early 2021, along with the script-generated 6502sp-elite-beebasm and cassette-elite-beebasm source code repositories.
And then there were seven
-------------------------
The Elite project has grown rather a lot since then. It now covers seven distinct versions of the game, and each of these has its own repository containing the fully documented and buildable source code for that version. These repositories are all generated from the central library, which now contains commented source code for all seven versions. And not only does the Elite website contain source code for all these versions, but it also has indexes, cross-references and statistics for each of those versions, as well as a section that compares the main Acornsoft releases on a line-by-line basis, so you can see exactly what the differences are between the versions.
To put this in context, at the time of writing (summer 2024), the Elite site contains 7,653 web pages. Of these, 171 are hand-crafted; this total includes over 100 deep dives, a hacks section, site information, the homepage and various pages describing the different versions of the game. The other 7,482 pages are generated by the original Python script that I originally knocked out in a hurry in September 2020, which still ingests the Elite source code repositories to create the bulk of the website that you see today.
The same script also produces the code sections of the Aviator, Revs and Lander websites, again taking the code from their respective source code repositories. Meanwhile, the second Python script that I wrote still creates the Elite source code repositories from the Elite library repository... but there are seven of them now, one for each version of Elite that I've analysed.
You can find out how these two scripts work by reading the overview of my automated scripts, and you can dive more deeply into the scripts themselves in the articles on generating websites from source code, generating source code repositories for Elite and generating code comparisons for Elite.
The advantages of scripting
---------------------------
The upshot of all of this scripting is that if I want to update, say, part of the commentary in the Elite source, then all I need to do is make my changes in just one place in the library repository, and then run a single shell script. This process updates the comment in all of the relevant source code repositories, as well as updating the comment wherever it appears in the website.
As an example, consider the BLINE circle-drawing routine, which appears in every version of Elite with only relatively minor differences between the different platforms. If I make a change to a comment in this routine, then the script will update that comment in all seven source code repositories, and it will also update the comment on 23 different pages across the website. Here's a list of all the content that gets updated:
- Source code repositories:
- Source code web pages:
- BLINE in the cassette version (individually and in context)
- BLINE in the disc version's docked code (individually and in context)
- BLINE in the disc version's flight code (individually and in context)
- BLINE in the 6502 Second Processor version (individually and in context)
- BLINE in the BBC Master version (individually and in context)
- BLINE in the Acorn Electron version (individually and in context)
- BLINE in the NES version (individually and in context)
- BLINE in Elite-A's docked code (individually and in context)
- BLINE in Elite-A's flight code (individually and in context)
- BLINE in Elite-A's encyclopedia code (individually and in context)
- BLINE in Elite-A's parasite code (individually and in context)
- Comparison web pages:
So for one small change in the library repository, the script will update seven code repositories (which may contain multiple occurrences of the updated content), 11 individual source code pages, 11 large source code pages, and one comparison web page. Updating these pages manually would be an unreliable and painful process; running a single shell script is about as easy as it gets.
On top of this, if I were to change the summary text in BLINE's header, then the script would also update the contents of the popup that you see whenever you click on the BLINE label in the source code, as this popup includes a summary of the routine. And it would do this across all pages mentioning BLINE in all seven versions, which would be a fair amount of effort if we had to do it manually.
Or to put it another way, without these scripts, then either this website would exist, or my sanity... but not both.