This document is designed for anyone wishing to obtain, build and run the X86 version of the SPIN Operating System. The document covers setting up your build environment, getting the SPIN sources, building, and booting SPIN. Information on other aspects of SPIN can be obtained on the web at: http://www.cs.washington.edu/research/projects/spin/www/.

The x86 version of SPIN needs at least a Pentium/PentiumPro class processor. The operating system uses features that are not available on 468 and below processors. We have only tried running SPIN on Intel Pentium and PentiumPro processors. Whether SPIN will work with x86 processors from other vendors is unknown.
List of known working hardware.

The fully built spin tree takes up ~220MB of disk space. This is a lot of space but if you are building SPIN on more than one machine, you only need one fully built tree. Other users can get by with a subset of the full tree. This is described later in the description of FULLTREE in below.

The build environment for X86-SPIN is currently Linux. This document was prepared using Redhat's distribution of Linux. This is not to say that other distributions won't provide the necessary environment.

Please note that the newer version of libc (glibc-2.0.x aka libc-6) is not compatible with the Modula-3 compiler used to build SPIN. For this reason you need to use a pre 5.0 version of Linux that includes libc-5. Version 4.2 is known to work.

The first thing to do is install Linux on your machine. Be sure to install the development tools so that your system has all the libraries and binaries for the build environment.

The Modula-3 distribution comes as three tar.gz files. You can either download them from one of the sites listed below or you can download them from our site by clicking on the file names a little further below. You should choose the location nearest you.

• gatekeeper.dec.com/pub/DEC/Modula-3/release-3.6/
• ftp-i3.informatik.rwth-aachen.de/pub/Modula-3/release-3.6/
• src.doc.ic.ac.uk/computing/programming/languages/modula-3/DEC/release-3.6/

The files are:

The rest of these instructions for building Modula-3 are derived from those provided by Digital at http://www.research.digital.com/SRC/modula-3/html/install-POSIX.html.

1. Unpack all the archives:

# gunzip < boot-LINUXELF.tar.gz | tar xf -
# gunzip < m3cc.tar.gz | tar xf -
# gunzip < m3.tar.gz | tar xf - 

2. (Optional)
   Remove the tar.gz files -

# rm boot-LINUXELF.tar.gz
# rm m3cc.tar.gz
# rm m3.tar.gz

3. Move m3cc to boot-LINUXELF -

# mv m3cc boot-LINUXELF

4. Next you have to configure Modula-3 for Linux by editing the template file:
   boot-LINUXELF/m3build/templates/LINUXELF. Here is an example template with changes already made, use this as a guide for understanding the instructions below. Be sure you edit this file based on your particular Linux system.
   • Define INSTALL_ROOT to be the location where you want Modula-3 installed. By default it is installed in /usr/local/; this has worked fine for us and there is a little less work during the install if you use the default location.
   • Define the location of the X libraries. In older Linux distributions, these libraries were stored in the directory "/usr/X11/lib/elf"; in newer distributions, they are stored in "/usr/X11/lib" or "/usr/X11R6/lib". If your libraries are stored in one of the latter directories rather than the former one, you should change all (eight) occurrences of the former name to the appropriate latter name.
   • Define the location of your ELF executables. In older Linux distributions they are in the directory /usr/i486-linuxelf/bin/; in newer distributions, they are stored in /usr/bin/. Look to see where the executables ar, and as are on your machine. If these executables are stored in the latter directory, you should change the two occurrences of the former directory name to the latter name.
   • Define the name of your gnu C compiler. In older Linux distributions it was gcc-elf; in newer distributions, it is named gcc. If you have a program named gcc in your executable directory (namely, the directory determined in the previous step), you should change all (nine) occurrences of the former name to the latter name.
   • Define CC, LINK, and BOOT_CC to point to your c-compiler (either cc or gcc). These are now set to either "gcc-elf" or "gcc"; change this to include the full path. For example "/usr/bin/gcc-elf" or "/usr/bin/gcc".
   • Define MAKELIB to point to your archiver (ar). This is now set to either /usr/i486-linuxelf/bin/ or "/usr/bin/ar", this may already be correct. Check the location of ar on your machine and change the definition of MAKELIB if necessary.
   • Define RANLIB to point to ranlib, which converts libraries into more efficient random-access libraries. This is currently defined as "touch". If your machine has ranlib, change this to the full path to ranlib on your machine.
   • Define ASM to point to your assembler (as). This is now set to either /usr/i486-linuxelf/bin/ or "/usr/bin/as". Check to see that this is the location of as on your machine, and make the appropriate change if it is not.
5. Wheeew...those were some confusing instructions.

Now you are ready to build.

1. Go to boot-LINUXELF, run ./m3boot, then run ./m3ship. The m3ship step will copy the essential pieces of the bootstrap system to the directories (BIN_INSTALL, LIB_INSTALL, ...) specified in m3build/templates/LINUXELF.
Note that the m3ship command will have to be executed as root.

# cd boot-LINUXELF
# ./m3boot
# ./m3ship
# cd ..

2. Now you should add BIN_INSTALL to your path. For example, if you are installing Modula-3 in /usr/local, add /usr/local/bin to your path (if it's not already there). If you're running csh, this is done by adding the following line to your .cshrc file:

setenv PATH $PATH:/usr/local/bin

If you change your .cshrc (or .tcshrc) file, you will need to reload it into your shell, and then run "rehash" to notify the shell of the changes to PATH.

# source ~/.cshrc
# rehash

3. At this point you have installed the Modula-3 compiler and driver. If everything went well and if you are pressed for space, you can now delete the bootstrap directory:

# cd ../
# rm -rf boot-LINUXELF

4. By default, the release is configured to build a large collection of packages. You only need to build the m3core and libm3 libraries. In the file m3/src/m3makefile, comment out the BuildChunk lines associated with packages other than m3core and libm3.
5. Go into the Modula-3 source directory and run m3build:

# cd m3
# m3build

Now you need to get the Linux->FreeBSD cross development tools. Some of these were created here at the UW, others might be available from the internet. Again, this step is only needed as long as we are doing development on Linux. In the future this will not be a requirement. These tools are available as a single tar.gz file from our distribution site.

• Download the file:

  bsdtools.tar.gz

  (3.7Mb)

  cross development tools

• Unpack this file:

  # gunzip < bsdtools.tar.gz | tar xf -

• (Optional) Remove the tar.gz file:

  # rm bsdtools.tar.gz

• Change to the bsdtools directory:

  # cd bsdtools

• If you installed Modula-3 in the default location, /usr/local/, then you can skip this step and go to the next.

  If you didn't install Modula-3 in /usr/local/, then in the bsdtools/Makefile:

  Change:	BUILDDIR=/usr/local
  To:	BUILDDIR=YOUR Modula-3 build directory (This is the same as INSTALL_ROOT in the LINUXELF template file above).

• Build the bsdtools: (You will have to perform this operation as root)

  # make

  This will create the following executables and place them in /usr/local/bin/ (unless you changed your "Makefile" above).

  bsd-ar	bsd-as	bsd-cc	bsd-cc1
  bsd-config	bsd-cpp	bsd-ld	bsd-nm
  bsd-ranlib	bsd-size

  This also copies three library files into /usr/local/lib/ , libc.a and libm.a, crt0.o.

• (Optional) You can now remove the bsd-tools source directory.

  # cd ..
  # rm -rf bsdtools

Install

If you already downloaded the SPIN sources you can skip down to the Pre-Build Modifications. For the rest of these instructions, I'll pretend that the SPIN source tree will be installed in /home/myspin/.

• Select where you want SPIN to reside on your system.

  #cd /home/myspin

• Get the file spin.XX.tar.gz from the SPIN distribution page, and place it in the directory you selected above; in our example this is /home/myspin. (Here XX is a release number).

• Unpack the SPIN sources:

  # gunzip < spin.XX.tar.gz | tar xf -
  

Directory Structure

As an example, I'll pretend that the SPIN sources are installed in /home/myspin/.

Pre-Build Modifications

• Edit the file: /home/myspin/spin/make.conf.

  There are seven variables that you will need to define according to the way you set up your system. You may need to install and configure your nfs server before you do this so that you know what values to use. Here are the variables and a description of their functions.

  MOUNT_POINT	This is the nfs mount point you export to the machine where you will boot SPIN. We refer to this machine as a crashbox. This will be the top-level directory underneath which your SPIN tree is located. For example, if your SPIN sources are located in /home/myspin/spin then MOUNT_POINT=/home.
  MOUNT_PAD	This is the path from MOUNT_POINT to the directory that contains your spin tree. For example, if you unpacked your SPIN sources in /home/myspin/, MOUNT_PAD is the empty string, that is, MOUNT_PAD=. However, if your source tree is further removed from MOUNT_POINT for example, if you unpacked your SPIN sources in /home/mydir/myspin/, then MOUNT_PAD=mydir/(and MOUNT_POINT=/home). DON'T FORGET THE TRAILING "/" IN THE SECOND CASE.
  FETCH_METHOD	This determines how the initial extensions are fetched at boot time. By default this is set to http. If you don't wish to set up and configure an http server then you may want to change this to nfs. Even with the default setting only the initial fetch is done via http, the rest via nfs.
  HTTP_ADDR	This defines the IP address of the http server you will use to fetch extensions during and after booting SPIN. In the two-machine scenario this will be the IP address of your development (Linux) machine. It is not absolutely necessary to use an http server for this purpose as it can all be done via nfs. See the boot set-up page for details.
  HTTP_PORT	The port number for the http server identified above.
  INSTALL_DIR	This is the path to your Modula-3 build directory. It is the same as INSTALL_ROOT in the LINUXELF template file above. If you installed Modula-3 SRC in the default location this will already be defined correctly as INSTALL_DIR=/usr/local.
  FULLTREE	This variable describes the location of a fully built SPIN tree. If you are building the entire SPIN tree on your machine, you can use the default definition - FULLTREE=$(THISTREE). If you are not building the full SPIN tree and you expect to use some portion of a remote, fully-built tree, you will need to define FULLTREE to be the path to this remote tree. This variable specifies where to find those portions of the tree that you don't have locally. The entire tree must be built on at least one node on your network.
  Take a look at an example make.conf that is based on the following environment parameters. The spin directory is located in /home/myspin. The development (Linux) machine's IP address is 128.95.2.184. Modula-3 was installed in the default location (/usr/local).

Build SPIN 

• Change directories to spin and type make!

  # cd /home/myspin/spin
  # make

The next step is to perform some set-up prior to booting your kernel.

Note: This is not part of building SPIN.

• To remove all files created as a result of building:

  #make clobber

• To remove all files created as a result of building while keeping those files necessary for building other parts of the system:

  #make clean

  This command will remove all intermediate generated files in the local and kernel trees. The object files are not removed in the user tree because they are loaded as extensions. The programs built in local remain in local's bin directory and the kernel images remain in their build directory.

• make clean in any subtree will remove only the platform-specific objects and binaries in that subtree.