StackThreads/MP: version 0.77 User's Guide

1.3: Installation

Installation consists of the following steps.

• 1: Uncompress and untar the distribution in the directory to which you want to install StackThreads. For example, if you want to install it under /usr/local/src, you put sthreads.tar.gz in /usr/local/src and type

          % gzip -dc sthreads.tar.gz | tar xf -
  

  You will find directory /usr/local/src/sthreads created. We hereafter refer to this directory as the toplevel directory.

• 2: In your .cshrc file (or in a file appropriate to your shell), set the following environment variables.
  • a: ST_DIR to the toplevel directory to which you unzipped this software.
  • b: ST_OS_TYPE to the operating system on which you use this software. Possible values are:
    • 1: solaris (for Solaris)
    • 2: irix (for IRIX)
    • 3: osf1 (for Digital UNIX)
    • 4: linux (for Linux)
    • 5: winnt (for Windows NT)
  • c: ST_CPU_TYPE to the CPU on which you use this software. Possible values are:
    • 1: sparc (for SPARC)
    • 2: mips (for MIPS)
    • 3: alpha (for Alpha)
    • 4: i386 (for Intel)
  • d: ST_THREAD_PKG to the underlying thread package. This specifies the thread package that StackThreads/MP uses. Possible values are:
    • 1: st_solaris_thread (for Solaris threads. possible only on Solaris. recommended on Solaris).
    • 2: st_pthread (for Pthreads. possible except on Windows NT. The only choice on Linux and Digital UNIX).
    • 3: st_sfork_thread (for sproc. possible only on IRIX. recommended on IRIX).
    • 4: st_nt_thread (for NT thread. possible only on NT. The only choice on NT).
    • 5: st_no_thread (for uniprocessors. available on every platform).

  Also add $(ST_DIR)/bin to your path. These variables are needed not only when you build StackThreads/MP, but also when you compile applications that use StackThreads. Here is an example startup file for csh, to use StackThreads/MP on SPARC Solaris.

         setenv ST_DIR /usr/local/src/sthreads
  @       setenv ST_THREAD_PKG st_solaris_thread
  @       setenv ST_OS_TYPE solaris
  @       setenv ST_CPU_TYPE sparc
  

  Here is an example startup for sh, to use StackThreads/MP on SPARC Solaris.

         ST_DIR=/usr/local/src/sthreads
  @       export ST_DIR
  @       ST_THREAD_PKG=st_solaris_thread
  @       export ST_THREAD_PKG
  @       ST_OS_TYPE=solaris
  @       export ST_OS_TYPE
  @       ST_CPU_TYPE=sparc
  @       export ST_CPU_TYPE
  

• 3: Compile the core library (libst.a) by:

          % cd src
  @        % make
  

  In success, this generates library file libst.a as $(ST_DIR)/lib/libst.a

• 4: Compile some utilities (libstext.a) by:

          % cd ../ext_src
  @        % make
  

  In success, this generates library file libstext.a as $(ST_DIR)/lib/libstext.a

• 5: Perform a simple test by:

          % cd ../ex/small
  @        % make
  

  It builds many small test programs. When everything is compiled successfully, run any. Most programs do not take any command line arguments and those that do display appropriate messages when invoked with no arguments. Some programs are verbose and others are not, but all programs say OK in the last line when nothing went wrong.

  On i386, program nestcall does not run successfully. This is a limitation of the current implementation with unmodified GCC. See Floating SP Problem for the description of the problem. We have a patch to GCC that fixes this problem. See Patches to GCC for how to apply patches.

  On SPARC, strpass does not run successfully. This is another limitation of the current implementation with unmodified GCC. See Structure Passing on SPARC for the description of the problem. We have a patch to GCC that fixes this problem. See Patches to GCC for how to apply patches.

  Try program bin with various number of processors. The number of processors can be specified with -nw P, where P is the number of processors. Specify a value between 1 and the number of processors you have. Generally, performance is maximized when P is the number of processors on small systems (like four processor systems) and a value slightly smaller than it on medium- or large-scale systems (like 10 or more processor systems). Giving a value higher than the number of processors is allowed, but is generally a bad idea. For example, if you have 16 processors, try:

          ./bin -nw 1
  @        ./bin -nw 5
  @        ./bin -nw 10
  @        ./bin -nw 14
  @        ./bin -nw 15
  @        ./bin -nw 16
  

• 6: Compile documents by:

          % cd ../doc
  @        % make
  

  This generates stman.dvi and stman.info. The stman.info should be copied into the directory where info files are installed in your system.

• 7: If you want to install StackThreads/MP for more than one platforms, and you want to share the source for them, you can copy directories lib, bin, and include to whatever directory you like. If you do that, run ranlib for archives and change your ST_DIR environment variable to the directory you copied them into. For example, if your StackThreads/MP source is in /usr/local/src/sthreads and you want to copy lib, bin, and include to /usr/local/lib/sthreads,

          % cd /usr/local/src/sthreads
  @        % cp -r lib bin include /usr/local/lib/sthreads
  @        % ranlib /usr/local/lib/sthreads/lib/libst.a
  @        % ranlib /usr/local/lib/sthreads/lib/libstext.a
  

  and change your ST_DIR settings to:

          setenv ST_DIR /usr/local/lib/sthreads
  

          ST_DIR=/usr/local/lib/sthreads
          export ST_DIR
  

  When you have done that, you may delete the source tree, if you ever wish to do that.

  If you are not going to use StackThreads/MP on multiple platforms, or you do not mind having a separate source tree on each platform, do not bother to copy the above directories. You can just keep them in place.

• 8: At this point, you may also apply patches to gcc. This is not mandatory (except when you use gcc 2.8.1 on SPARC, which has a simple bug in handling -mflat option), so you can normally skip it and consider applying pathces later. These patches guarantee the safety of StackThreads/MP programs compiled by gcc. The distribution includes diffs for gcc 2.7.2.3 and gcc 2.8.1, in gccpatch/gcc-2.7.2.3 and gccpatch/gcc-2.8.1, respectively. See Patches to GCC for more detail.

  Patch gcc 2.8.1 on SPARC! gcc 2.8.1 on SPARC processors has a simple bug in handling -mflat option that StackThreads/MP heavily relies upon. When you are going to use StackThreads/MP on SPARC with gcc 2.8.1, apply patches.