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
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.
Update current copy, or check out a fresh copy:
Compile to fixed point:
- $ cd base/system
- $ ./fixpt
This script will produce two directories: sml.boot.$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
Generate new library and heap files.
Test the build.
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.)
Build a working installation.
- $ cd ../..
- $ ./config/install.sh
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 ..
Build to another fixed point in base/system.
- $ cd base/system
- $ ./fixpt
Repeat steps 3 through 6 above.
- Can omit step involving testml. (Which seems broken in my notes anyway.)
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
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
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.
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
- 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.
Create source tarballs:
- $ mkdir tmp
- $ cd tmp
- $ svn export https://smlnj-gforge.cs.uchicago.edu/svn/smlnj/admin
- $ ./admin/build-tar-files.sh
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
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--."
Create DMG files for Mac (See below).
Create MSI files for Windows (See below).
- Download, install, and run tests.
- 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
Building a OS X package and dmg
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
$ ./build-pkg.sh $VERSION
will build the signed installer package file
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
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!).
where $ARCH is either x86 or amd64.
- $ scp smlnj-$ARCH-$VERSION.pkg $release_dir
Building a Windows installer (MSI)
Steps preceded by [cygwin] are performed in the cygwin shell.
Steps preceded by [vc++] are performed in the Visual C++ command
- Install cygwin (32-bit version)
- Install Visual Studio (or Visual Studio Community)
- [cygwin] create a directory to build a release. This directory path
must not contain a number or spaces.
(in my case: /home/jhr/Work/smlnj/release or c:\cygwin\home\jhr\Work\smlnj\release)
- [cygwin] in /home/jhr/Work/smlnj directory,
- $ mkdir gf
- $ export gf=https://smlnj-gforge.cs.uchicago.edu/svn
- $ export smlnj=$gf/smlnj
- $ export VERSION=xxx.yy
- $ export release_dir=linux.cs.uchicago.edu:/stage/web_static/smlnj/htdocs/dist/working/$VERSION
- [cygwin] Fetch and unbundle the config.tgz file.
- $ curl -O https://smlnj.org/dist/working/$VERSION/config.tgz
- $ tar -xzf config.tgz
- [cygwin] Prepare the files for building the Windows version.
- $ config/prepare-win-install.sh
- [vs] set SMLNJ_HOME=C:\cygwin\home\jhr\Work\smlnj\release
Define SMLNJ_HOME variable.
- [vs] chdir %SMLNJ_HOME%
- [vs] config\install.bat
- [vs] config\WinSetup\buildSetup.bat
The file smlnj.msi produced is the final installer for Windows.
This script uses the WiX Toolset
for building the installer.
- [cygwin] $ scp smlnj.msi $release_dir/smlnj-$VERSION.msi
Copy the MSI file to the distribution directory; we add a $VERSION
tag so that folks can keep multiple downloads distinct.
Remember to check the file permissions on the server after you copy the file.
Last modified: March 31, 2020