Building a Legacy Release

This page documents the steps required to build a release of the legacy version of the SML/NJ system. The parts related to uploading the release for distribution assume access to the University of Chicago Computer Science Department’s systems.

Conventions

In the discussion below, we use $VERSION to represent the release version in question (e.g., 110.99.5), $ARCH to represent the host architecture (e.g., amd64), and $OS to represent the host operating system (e.g., unix).

We also use $ROOTDIR to refer to the root of a clone of the legacy repository.

Overview

The main steps in building a release are as follows:

1. Create the directory on the University of Chicago servers to contain the release; i.e., /stage/web_static/htdocs/dist/working/$VERSION.

2. Write the $VERSION-README.adoc file and commit it. Also update the HISTORY.txt file.

3. Run the allcross script in base/system to build boot directories for all the architectures and create tarballs from them. Copy these tarballs to the dist/working/$VERSION directory created in the first step.

4. Create installers for macOS and Windows. Add these to the distribution directory.

5. Add a link to dist/working/$VERSION/$VERSION-README.html to dist/index.html.

Detailed Instructions

Building .bin Files

The first step is to generate the pre-compiled .bin files that are necessary to bootstrap the system. We typically do this step on a Unix machine (e.g., Linux or macOS).

We assume that you have a current version of SML/NJ installed and in your shell path.

1. Make sure that you have an up-to-date copy of the repository and that you have pushed all of your local changes.

2. Update the HISTORY.txt file ($ROOTDIR/doc/src/changelog/HISTORY.txt) by adding a new version section header.

   You should also check that the release notes ($ROOTDIR/doc/src/releasenotes/$VERSION-README.adoc) are complete.

   Push the changes that you made to GitHub.

3. In the $ROOTDIR directory, run the prepare-release script; e.g.,

   ./admin/prepare-release.sh -d "February 14, 2024" $VERSION

   The date argument (i.e., -d "February 14, 2024") is optional, but the version number is required. This script does most of the work of generating the files for a release (see below for details). This script produces a log of its work in the file LOG-$VERSION.

4. Assuming that there were no problems with the previous step, we can now tag the release.

   git tag -a v$VERSION -m "release $VERSION"
   git push origin tag v$VERSION

5. Create source tarballs in a scratch directory.

   mkdir tmp
   cd tmp
   ../admin/build-tar-files.sh

   The build-tar-files.sh script will make a fresh clone of the legacy repository and then use it to generate the documentation files and source tarballs.

6. Copy tarballs to the distribution directory.

Building the MSI File for Windows

Follow the steps in the win-dist README.

The prepare-release.sh Script

The admin/prepare-release.sh shell script does most of the work preparing the release tarballs. Specifically, it executes the following steps:

1. Checks for local changes that have not been staged or committed.

2. Refresh the sources by doing a git pull command and then a git push.

3. Compile the compiler to a fixed-point and install it in the bin and lib directories.

4. Update the config/version and config/releasedate files for the new release. These changes are pushed to GitHub.

5. Compile the compiler to a fixed-point again.

6. Using the new compiler, cross compile to the various targets supported by the system. This step will produce compressed tarballs of the bin files for the various targets.