This documents the process for producing release versions of the software.
Can You Release Yet?
Before release, you must:
- Fix all Immediate, High, and Medium priority Bugs
- Implement all Immediate and High priority Features
Or reclassify them, of course.
Most of the bug levels simply aid scheduling: Immediate priority bugs
should be fixed before High, etc. Low priority bugs are "someone should
fix this someday" type of problems; these are the only ones allowed to
move from release to release. Think of bugs at this level as analogous
BUGS section of a Unix man page: our "low" intent to fix these
problems means they may stay at this level indefinitely, acting only as
advisories to the software's users.
The Features levels may be read as:
- Immediate: ASAP, or sooner. :)
- High: Features for the upcoming release.
- Medium: Features we'll look at lifting to High for the release after that.
- Low: "Wouldn't it be nice if..."
tools/simh-update hasn't been run recently, you might want to do
that and re-test before publishing a new version.
Build the software on the version of Raspberry Pi OS we’ll use for BOSI, below. Fix any problems.
make teston the BOSI host. Fix any problems.
Repeat above on all other platforms previously known to work. Update the article to list caveats and such, or fix the problems.
(See “How the PiDP-8/i Software Is Tested” for details on the philosophy and methods behind this process.)
Publish OS/8 RK05s
Re-configure the software with default settings, remove
rebuild, and run
tools/publish-os8 to send the "final" OS/8 disk
images for this version of the software up to tangentsoft.com as
Update the date stamp in the "OS/8 RK05 Media" section of the project home page.
Trawl the Fossil timeline for user-visible changes since the last
release, and write them up in user-focused form into the
file. If a regular user of the software cannot see a given change,
it shouldn't go in the
ChangeLog.md; let it be documented via the
Immediately prior to release,
/file and similar links
should point to trunk, but immediately prior to release, re-point them
release branch, since this document describes prior releases.
Update the Release Branch
make release to check the
ChangeLog.md file changes in, merge
trunk to the
release branch, and apply a tag of the form vYYYYMMDD to
that marge checkin.
It runs entirely automatically unless an error occurs, in which case it stops immediately, so check its output for errors before continuing.
Update the Home Page Links
The zip and tarball links on the front page produce files named after the date of the release. Those dates need to be updated immediately after tagging the release, since they point at the "release" tag applied by the previous step, so they begin shipping the new release immediately after tagging it.
Start with the latest version of Raspberry Pi OS Lite on a multi-core Raspberry Pi.
If the version of the base OS has changed since the last binary OS image was created, download the new one. Be sure to update the “
$os” variable at the top of
tools/bosito match if the major version has changed.
While the OS is downloading, zero the SD card you're going to use for this, so the prior contents don't affect this process.
Blast the base OS image onto the cleaned SD card.
Boot it up on a multi-core Pi.
Log in as user
raspberry, then retreive and initialize BOSI:
$ wget https://tangentsoft.com/bosi $ chmod +x bosi $ exec sudo ./bosi init
execbit is required so that the
bosiinvocation is run as root without any processes running as
piin case the
initstep sees that user
pihasn't been changed to
usermodcommand we give to make that change will refuse to do what we ask if there are any running processes owned by user
It will either reboot the system after completing its tasks successfully or exit early, giving the reason it failed.
Log in as user
pidp8isince the prior step changed it from
pi. The password remains unchanged at this point.
Clone the software repo and build the software:
$ ./bosi build [nls]
Adding the “nls” parameter lets the slow single-core Pi build share the multicore ILS build’s OS/8 images, saving a tremendous amount of build time.
On reboot, say
top -Hto make sure the software is running and that the CPU percentages are reasonable for the platform: if the CPU is mostly idle, the simulator isn’t running, and you need to figure out why before proceeding.
You may also want to check that it is running properly with a
pidp8icommand. Is the configuration line printed by the simulator correct? Does OS/8 run? Are there any complaints from SIMH, such as about insufficient CPU power?
Do the final inside-the-image steps:
$ ./bosi prepare
After the Pi shuts down, move the SD card to a micro SD card reader plugged into the Mac¹ and say:
$ bosi image [nls]
Give "ils" as a parameter or leave it blank for the ILS image.
The prior step rewrote the SD card with the image file it created. Boot it up and make sure it still works. If you're happy with it, give this command on the Mac.
$ bosi finish [nls]
As above, the parameter can be "ils" or left off for the ILS images.
Produce the "No Lamp Simulator" Binary OS Image
Do the same series of steps above on a single-core Raspberry Pi, except
that you give "nls" parameters to the
While the NLS image uploads — the ILS image was already sent in step 7 in the first pass through the list above — compose the announcement message, and modify the front page to point to the new images. You might also need to update the approximate image sizes reported on that page. Post the announcement message and new front page once that second upload completes.
- The image production steps could just as well be done on a Linux box or on a Windows box via Cygwin or WSL, but the commands in that final stage change due to OS differences. Since this document exists primarily for use by the one who uses it, there is little point in having alternatives for other desktop OSes above. Should someone else take over maintainership, they can translate the above commands for their own desktop PC.
Copyright © 2016-2021 by Warren Young. This document is licensed under the terms of the SIMH license.