Building a Release

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

The main steps in building a release are as follows:

• Create the directory to contain the release. E.g. in a working copy of the pages project, svn add directory dist/working/$VERSION, where n is the release number. Then commit the change, and update the web-site copy of the pages project at /stages/web_static/smlnj/htdocs.
• Write the $VERSION-README.html file and commit it. Also update the HISTORY file.
• 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.
• Export source directories and create tarballs and transfer them to the distribution directory.
• Create .dmg file for Mac OS X installation, and a Windows .zip file. (Details?). Add these to the distribution directory.
• Add a link to dist/working/$VERSION/$VERSION-README.html to dist/index.html.

Following are specific instructions for building a SML/NJ release, organized by operating system (Unix/Linux, macOS, Windows).

Building on Unix (including Linux)

Note: the script admin/prepare-release.sh will do steps 1–10.

1. Update current copy, or check out a fresh copy:

   • $ ./admin/refresh-all.sh
   • Or from a CS machine: svn co --username yourusernamehere https://smlnj-gforge/svn/smlnj/admin, then $ ./admin/checkout-all.sh.

2. Compile to fixed point:

   • $ cd base/system
   • $ ./fixpt

   This script will produce two directories: sml.boot.$ARCH-$OS and sml.bin.$ARCH-$OS.

   Note: prior to 110.79, the fixpt script left the result in directories that were indexed by iteration (e.g., sml2.bin.x86-unix). Use the "-save" option to the fixpt command to force the old behavior.

3. Generate new library and heap files.

   • $ ./makeml

4. Test the build.

   • $ ./testml

5. Install the new code (the "-clean flag removes the old libraies and heap images).

   • $ ./installml -clean
   • (To check everything — make sure everything is enabled in config/targets.)

6. Build a working installation.

   • $ cd ../..
   • $ ./config/install.sh

7. Update the version and releasedate files in the config directory.

   • $ cd config
   • $ echo $VERSION > version
   • $ echo $DATE > releasedate
   • $ svn commit -m "updating version number to $VERSION"
   • $ cd ..

8. Build to another fixed point in base/system.

   • $ cd base/system
   • $ ./fixpt

9. Repeat steps 3 through 6 above.

   • Can omit step involving testml. (Which seems broken in my notes anyway.)

10. Cross compile and generate tarballs for the bin files:

    • $ cd base/system
    • $ ./allcross

    The allcross script will cross compile for all targets and produce gzipped tar files (e.g., boot.x86-uniz.tgz).

11. Edit/update the history file.

    • ../doc/src/changelog/HISTORY.txt: Add a new version section header.

    • ../doc/src/releasenotes/: Copy previous version's README and edit; older versions give examples of format expectations.

      • Cut and paste relevant entries from HISTORY.txt and format them.
      • Also check the SML/NJ Library's change log (smlnj-lib/CHANGES), since those changes often do not make it into the HISTORY file.

      Note that since version 110.86, the README file is in AsciiDoc format. The HTML file will be generated by the build-tar-files.sh command below.

12. Tag the release.

    • $ ./admin/make-release.sh $VERSION
      Note that each major directory under smlnj has its own trunk and release branches, e.g., $smlnj/sml/trunk, $smlnj/sml/releases/release-$VERSION, except for ml-lpt, which does not have release branches.

13. Update web pages.

    • Go to the relevant SML/NJ web server directory.
      • On the UChicago CS cluster at: /stage/web_static/smlnj/htdocs/dist/working. Ideally this all under Subversion control, but this convention isn't being followed 100%.
    • Add a directory for $VERSION in dist/working.
    • Create $VERSION/index.html by copying the file from the previous release and then updating it with the correct links.
    • Define an alias for the distribution directory.
      $ release_dir=linux.cs.uchicago.edu:/stage/web_static/smlnj/htdocs/dist/working/$VERSION

14. Create source tarballs:

    • $ mkdir tmp
    • $ cd tmp
    • $ svn export https://smlnj-gforge.cs.uchicago.edu/svn/smlnj/admin
    • $ ./admin/build-tar-files.sh

15. Copy documentation into the release directory.

    • $ scp doc/doc/html/install-notes/cygwin.html $release_dir
    • $ scp doc/doc/html/install-notes/install.html $release_dir
    • $ scp doc/doc/html/install-notes/macos.html $release_dir
    • $ scp doc/doc/html/install-notes/windows.html $release_dir
    • $ scp doc/doc/html/HISTORY.html $release_dir
    • $ scp doc/doc/html/readme/$VERSION-README.html $release_dir

    Note: an alternative approach is to copy these files into a working copy of the web-pages svn repository, add and commit them, and then do an svn update on linux.cs.uchicago.edu.

16. Copy source tarballs into the release directory.

    • $ scp *.tgz $release_dir
    • $ cd ..
    • $ scp base/system/*.tgz $release_dir

    Once the files have been copied, you should ssh into linux.cs.uchicago.edu and check the file permissions, which should be "rw-rw-r--."

17. Create DMG files for Mac (See below).
18. Create MSI files for Windows (See below).
19. Sanity checks:
    • Download, install, and run tests.
20. Update links:
    • Symbolic link at /stage/web_static/smlnj/htdocs/dist/working/current
    • Table at /stage/web_static/smlnj/htdocs/dist/working/index.html
    • What's new and links in /stage/web_static/smlnj/htdocs/index.html

There is an automated script for building a signed installer for macOS (née Mac OS X). First check out from svn:

$ svn co https://smlnj-gforge.cs.uchicago.edu/svn/smlnj/osx-dist
$ cd osx-dist

The command

$ ./build-pkg.sh $VERSION

will build the signed installer package file smlnj-x86-$VERSION.pkg. To build the AMD64 installer (smlnj-amd64-$VERSION.pkg), use the -64 option when running build-pkg.sh. This script assumes that the distribution files have already been uploaded to the standard distribution site (Step 15 above) and that the targets file is initialized correctly.

The signing of the package depends on the user having the correct developer certificate. The script currently knows about John Reppy's cert, but the script can be generalized by adding other user IDs.

Instructions for older versions of the installation process can be found in the document osx-package-build.txt.

Once the installer is built, it needs to be copied to the release directory (do not forget to check permissions once the file is copied!).

• $ scp smlnj-$ARCH-$VERSION.pkg $release_dir