SML/NJ SVN Howto

Repository layout

The repository hosts a number of semi-independent toplevel trees:

admin -- repository administration
pages -- the web site
sml -- a rump of what used to be the entire SML/NJ source tree; it should be checked out as base (see below)
config -- shell scripts etc. for configuration and installation
MLRISC -- the MLRISC library
ckit -- the CKIT library
nlffi -- the NLFFI sources consisting of the runtime library (lib) and the generator tool (gen)

... and so forth.

Anonymous repository access

Many of the instructions below assume that you have access to the Subversion repository. If you are having trouble with access, you can do an anonymous check out using the username "anonsvn" and the password "anonsvn". For example, to check out the admin tree, you would do the following:

 $ svn co --username anonsvn https://smlnj-gforge.cs.uchicago.edu/svn/smlnj/admin admin

If prompted, use "anonsvn" for the password. Following this step, you should be able to use admin/checkout-all.sh to get the remaining source trees without trouble (see below). More information about the repository can be found at the SML/NJ GForge SCM page.

Web access to the repository

You can also browse the SML/NJ repositories using the ViewVC page for SML/NJ.

Directory layout

To compile and install SML/NJ, one needs to create a root directory (of arbitrary name, let's call it "root" for the purpose of this explanation) and then populate it with various sub-trees by checking out parts of this repository (and potentially other repositories). The default layout populates root with:

config
base
smlnj-lib
MLRISC
ml-yacc
ml-lex
nlffi
ckit
cml
eXene
ml-burg
lexgen
ml-lpt
heap2asm
smlnj-c
pgraph
trace-debug-profile

Not all of these trees are always necessary.

Suppose we have added the following shell definitions to our environment:

   gf=https://smlnj-gforge.cs.uchicago.edu/svn
   smlnj=$gf/smlnj

By default, a tree T is obtained by performing

   svn co $smlnj/T/trunk T

There currently are two exceptions to this:

   svn co $smlnj/sml/trunk base
   svn co $gf/ml-lpt/trunk ml-lpt

Scripts

We provide a small number of shell scripts to simplify the creation and maintenance of the default layout (or custom layouts that are variations of the default). These scripts are kept under Subversion control themselves (under $gf/admin). To use them, do:

   svn co $smlnj/admin admin

and put the name of the resulting admin directory (which could be located anywhere) into your shell's PATH.

checkout-all.sh

To create the default layout, use

   checkout-all.sh root

This creates the root directory and populates it as described above. Without the optional argument, checkout-all.sh does not create a new root directory and treats the current directory "." as the root instead.

If some subtrees already exist, then checkout-all.sh will skip them. This is useful when working on a custom version of one or more of the subtrees while using default versions of the remaining subtrees. To establish such a setup, first create the root directory by hand, create your custom subtrees in whatever fashion desirable, and then run checkout-all.sh to pull in any remaining subtrees from the repository.

The checkout-all.sh script takes an optional flag --export (or simply -e). The use of this flag switches from svn checkout to svn export. This is useful for obtaining a copy of the sources without Subversion meta data.

refresh-all.sh

To perform svn update on all subtrees, run

   refresh-all.sh

from within root. This command skips subtrees that are not under Subversion control. Like checkout-all.sh it takes the root directory as an optional argument, the default being the current directory.

stat-all.sh

Similarly, to perform svn stat on all subtrees, use stat-all.sh. Like the other two commands, stat-all.sh takes the root directory as an optional argument.

Commits should be done on a per-tree basis "by hand" (i.e., using svn commit and its cousins).

Recipies

The following are more detailed recipies for performing typical tasks.

I. Preparation

Assume that the path for your local smlnj development directory is the value of shell variable SMLDEV (e.g. in my case, SMLDEV=~/sml/Dev).

define some shell variables

  $ export gf=https://smlnj-gforge.cs.uchicago.edu/svn
  $ export smlnj=$gf/smlnj

In your $SMLDEV directory, create a directory gf
```
  $ cd $SMLDEV
  $ mkdir gf
```
Go to gf and checkout the admin directory
```
  $ cd gf
  $ svn co $smlnj/admin
```
This creates subdirectory gf/admin containing some shell scripts to automate checking out the full source code, checking status, etc.
Add $SMLDEV/gf/admin to your shell PATH.

Of course, you could put this checkout somewhere else, such in your personal bin file, or in /usr/local/bin if you have permission. In this case, step 4 would not be necessary.

II. To check out a working copy of the trunk smlnj code and build the compiler

Assuming you are in your development directory, create a working directory and check out the required top level subdirectories. This can be done in one step by giving checkout-all.sh a directory name as an argument, e.g.:
```
  $ checkout-all.sh smlnj
```
Change to the new working directory and run the install script:
```
  $ cd smlnj
  $ config/install.sh
```
If you do not have an existing ml-yacc in your PATH, then this may fail because of the order in which svn checks out certain ml-yacc source files. In this case, you can recover by executing
```
  $ touch ml-yacc/src/yacc.grm.sig ml-yacc/src/yacc.grm.sml
```
to make these younger than ml-yacc/src/yacc.grm. This is a temporary problem until the build scripts are modified to take care of this.

III. To check out a private development branch

In this example, the branch is named primop-branch-3, and is based on the top-level repository directory $smlnj/sml.

To check what branches exist under a top-level directory, like sml (= base), do
```
  $ svn list $smlnj/sml/branches/
```
Create target directory, here called primop3, and change to it.
```
  $ mkdir primop3
  $ cd primop3
```
In the target primop3 directory do
```
  $ svn co https://smlnj-gforge.cs.uchicago.edu/svn/smlnj/sml/branches/primop-branch-3 base
```
or (given the definition of shell variable smlnj from part I above)
```
  $ svn co $smlnj/sml/branches/primop-branch-3 base
```
This checks out the primop-branch-3 code for the sml directory, locally renamed as "base".
Run checkout-all.sh to get the rest of the source code (assuming gf/admin has been added to the PATH)
```
  $ checkout-all.sh
```
Run config/install.sh to build the compiler.

David MacQueen and Matthias Blume

Last modified: Wed Feb 18 14:53:26 CST 2009