Installation instructions for SML/NJ
------------------------------------

These are instructions for installing recent "working" versions of SML/NJ.

1. If you are in a hurry (and you have network connectivity) ...
----------------------------------------------------------------

   - Pick a place to do the installation, e.g.

      $ d=/usr/share/smlnj     # or whatever you like
      $ mkdir $d
      $ cd $d

   - Download config.tgz, e.g.

      $ v=110.38               # or whatever is the version you desire
      $ wget http://ftp.research.bell-labs.com/dist/smlnj/working/$v/config.tgz

   - Gunzip and untar, e.g.

      $ gunzip <config.tgz | tar xf -

     This creates a subdirectory "config"

   - Edit the "config/targets" file to your taste.  If you leave this
     file alone, you end up with a minimal installation.

   - Run the installer, it will automatically fetch all other necessary
     tarballs:

      $ config/install.sh

     If the installer complains about not being able to fetch those
     tarballs, try step 2.1.

2. If you have a bit more time...
---------------------------------

   2.1.  If you do not have network connectivity...
   -------------------------------------------------

   - Use some other means of downloading the necessary tarballs.  Store
     them in directory $d.  Then run the installer (config/install.sh).

     Here is a table that shows which packages you will need to download
     depending on what you select in config/targets.  Take the union of
     all the packages corresponding to your selection.  Don't forget to
     include the "(always)" entry.  (<arch> and <os> should match your
     host system.)

     Keep in mind that making selections in config/targets there are
     dependencies between packages.  For example, eXene requires cml
     and cml-lib.  The installer script "knows" about these dependencies
     and will automatically calculate the transitive closure of the
     "requires" relation for you.  Still, if you do not have network
     connectivity, then you should have downloaded tarballs for the
     entire transitive closure.  (If you didn't, the installer will
     kindly remind you.)

          if you select...         |    ... you need 
      ---------------------------------------------------------------
          (always)                 | boot.<arch>-<os>.tgz
                                   | runtime.tgz
                                   |
          src-smlnj                | MLRISC.tgz
                                   | cm.tgz
                                   | compiler.tgz
                                   | smlnj-lib.tgz
                                   | ml-yacc.tgz
                                   | system.tgz
                                   |
          ml-yacc                  | ml-yacc.tgz
                                   |
          ml-lex                   | ml-lex.tgz
                                   |
          ml-burg                  | ml-burg.tgz
            requires: ml-lex       |
                                   |
          smlnj-lib                | smlnj-lib.tgz
                                   |
          pgraph-util              | cm.tgz
                                   |
          cml                      | cml.tgz
            requires: smlnj-lib    |
                                   |
          cml-lib                  | cml.tgz
                                   |
          eXene                    | eXene.tgz
            requires: cml, cml-lib |
                                   |
          ckit                     | ckit.tgz
                                   |
          ml-nlffi-lib             | ml-nlffi-lib.tgz
                                   |
          ml-nlffigen              | ml-nlffigen.tgz
            requires: smlnj-lib,   |
                      ckit         |
                                   |
          mlrisc-tools             | MLRISC.tgz
                                   |
          nowhere                  |
            requires: mlrisc-tools |
                                   |
          doc                      | - (currently unavailable)

   2.2.  Tweaking "preloads"...
   ----------------------------

    - Before running the installer (but after unpacking the config
      directory), you can customize the set of libraries that are
      pre-loaded (either directly or via CM's "autoload" mechanism).

      For this, edit config/preloads before running config/install.sh.

   2.3.  Using a different ftp server (for a step-1.-like installation)
   --------------------------------------------------------------------

    - If you have a local mirror for ftp.research.bell-labs.com/dist/smlnj,
      then you can speed up installation by pointing the automatic URL
      fetch mechanism there.  The URL of the repository is stored in
      config/srcarchiveurl.  Edit this file before running config/install.sh.

   2.4.  Using locally stored tarballs
   -----------------------------------

    - This is like step 2.3. -- except the URL in config/srcarchiveurl
      should read something like

          file:///usr/src/packages/smlnj/working/110.38

      (In other words, the URL should spell out the name of the local
      directory that happens to contain the tarballs.)

   2.5.  What needs to be on my PATH?
   ----------------------------------

   - You should include $d/bin into your PATH.

   2.6.  Which of all those files do I really need?
   ------------------------------------------------

   After the installer completes, directory $d will be full of files
   and subdirectories.  Not all of them are actually required if you want
   to use the system.

   In particular, if you are not interested in any of the source code,
   you can DELETE EVERYTHING EXCEPT:

      $d/bin
      $d/lib

   2.7.  Can I move files to another directory after the fact?
   -----------------------------------------------------------

   Yes.  But this requires two small tweaks (points 2. and 3. below).

   Here is the procedure:

   Suppose you have installed everything under $d and now you want to
   move things to some other directory $e (e.g., e=/usr/share/smlnj):

     1. Move (at least) $d/bin and $d/lib to $e:

        $ mv $d/{bin,lib} $e

     2. Edit $e/bin/.run-sml and change the value of
        the variable BIN_DIR to (the value of) $e/bin.
        (If e=/usr/share/smlnj, then the value would have to be
        /usr/share/smlnj/bin.)

     3. Before running the "sml" command, set the environment variable
        CM_PATHCONFIG to $e/lib.  You could do this globally, either
        in a system-wide .profile or even by adding a line, e.g.,

           export CM_PATHCONFIG=/usr/share/smlnj/lib

        to $e/bin/.run-sml.

        Alternatively, each user who wants to run "sml" could set the
        variable by him/herself.

   2.8 Forcing the installer to use a particular URL getter program
   ----------------------------------------------------------------

   By default, config/install.sh will attempt to use wget, curl, and lynx
   (in that order).  If you already know which of these programs you want
   the installer to use, then set the environment variable URLGETTER
   to "wget", "curl", or "lynx", respectively.

   You can also set URLGETTER to any other command "foo" as long as
   it can be invoked as

       $ foo <source> <destination>

   where <source> is the URL you want to fetch and <destination> is
   the file name where the result will be stored.

3. Troubleshooting:
-------------------

   3.1. You think you have network connectivity, but the installer fails
   ---------------------------------------------------------------------

    - You probably do not have any of the following commands available
      on your system:  wget, lynx, curl.

      Failsafe remedy:  Proceed according to step 2.1., using whatever
      other FTP client you have.

      Alternative remedy:  If you have some other command-line tool to
      fetch URLs, make a wrapper for it (if necessary) so that it can
      be invoked with precisely two arguments: <srcurl> and <dst>.
      Then set the environment variable URLGETTER to the name of this
      (wrapped) tool and try running the installer.

      Example:  Suppose you don't have wget but a wget-lookalike named
      "xget".  You could then make a shell script that wraps xget, e.g.
      using a shell script "myxget" consisting of the single line:

          exec xget -nv -O $2 $1

      Once you have myxget, simply run:

          URLGETTER=myxget config/install.sh