README CONTENTS

This file contains general information for a variety of users:

  INSTALLATION BASICS	general installation information
  GRAPE SYSTEMS		additional information for GRAPE sites
  PROGRAMMERS		information for Starlab programmers
  DEVELOPERS		information for Starlab developers
  COPYRIGHTS		ownership, attribution, and contribution


INSTALLATION BASICS

- We assume here that the variable STARLAB_PATH points to the top-
  level Starlab source directory (i.e. the one containing this file).
  GRAPE users should read the GRAPE section below before starting
  the configure/build process.

- Installation proceeds in GNU standard fashion:

	./configure --prefix=STARLAB_INSTALL_PATH --other-options
	make
	make install

  See the INSTALL file in this directory for more information.  The
  current default STARLAB_INSTALL_PATH is

	$STARLAB_PATH/usr

  and in normal circumstances no other options need be specified.

- Both STARLAB_PATH and STARLAB_INSTALL_PATH will be created as
  environment variables by the starlab_start scripts generated as
  part of the installation process.  (They are convenient, although
  neither is actually needed for routine operation of the software.)

- If you downloaded Starlab in the form of a distribution tarball
  (named starlab-version.tar.gz), the configure script should already
  exist in $STARLAB_PATH, and you can proceed directly to the above
  standard installation commands.

- However, if you obtained Starlab from the CVS archive, then the
  source tree will not include the configure script.  You will have
  to create configure (and other installation files, such as
  "Makefile.in") using the command

	autoreconf -i -f

  Starlab now makes extensive use of the GNU "autotools," aucoconf,
  autoreconf, automake, and libtool.  Unless you are sure that your
  system has versions of these tools newer than those used to build
  the package, you probably first will want to install the autotools
  found in $STARLAB_PATH/src/packages.  You can do this by hand
  (unpack the tarballs and follow the installation instructions), or
  by running the script

	install-autotools

  found in that directory.  You will also have to modify your search
  path to ensure that the directory containing the newly installed
  autotools *precedes* any system directory before proceeding with
  the Starlab installation.

  Once you have run autoreconf, you can again proceed to the standard
  installation commands given above.  Note that if you are installing
  from a tarball, you should only need autotools if you modify any of
  the "Makefile.am" templates in the source directories.

- If you prefer to install everything automatically, in all cases you
  can simply run the script

	install-starlab

  in this directory.  This script performs the various actions just
  described (including autotool installation in all cases), and in
  addition it provides timing information and attempts to clean up the
  "make" output.  It also contains workarounds and corrections for
  some known deficiencies of the configure/make proocess.

- Once the package is successfully installed, to use the Starlab tools,
  make sure that the directory

        $STARLAB_INSTALL_PATH/bin

  is in your search path, preceding any system files.  You may also
  find it useful to include the Starlab administrative directory

	$STARLAB_PATH/sbin

  Sourcing the script $STARLAB_PATH/starlab_start.csh (or its .sh
  equivalent, for bash users) will automatically set up the environment
  variables

	STARLAB_PATH
	STARLAB_INSTALL_PATH
	STARLAB		(= STARLAB_PATH, included for compatibility)
	STARLAB_VERSION

  and will also appropriately modify the search path.

GRAPE SYSTEMS

- It is very difficult for the configure script to infer automatically
  the existence of a GRAPE or to determine the appropriate GRAPE
  libraries and other settings to use.  If you have a GRAPE, you will
  have to place that information in the file

	$STARLAB_PATH/local/grape.sh

  This file is a simple shell script that sets a few variables used
  to build the Makefiles.  So that it cannot be overwritten by a new
  release after you have created it, the script itself is not distributed
  with the Starlab package.  However, a template is distributed in

	$STARLAB_PATH/local/grape.sh.template

  and a collection of examples from various GRAPE sites is contained
  in

	$STARLAB_PATH/local/grape.sh.examples

  You will have to rerun configure after creating or changing this
  script, so you will probably want to make these changes BEFORE building
  the system!  If you don't have a GRAPE, do nothing, and Starlab will
  by default build a system without GRAPE acceleration.

- If you change any of the scripts in $STARLAB_PATH/local (e.g. to
  change the name or location of the GRAPE library ), you will have to
  rerun configure in order for the changes to find their way into the
  relevant Makefiles.  Simply updating a library does not require
  reconfiguration, but note that (for now) make will not automatically
  detect the change, so you will have to explicitly rebuild all GRAPE-
  dependent programs (kira, sys_stats, scale, etc.).  It is probably
  simplest to use sremake to accomplish this (see below).
  

PROGRAMMERS

- For programmers, the Starlab header files are installed in

        $STARLAB_INSTALL_PATH/include/starlab

  and the libraries are in

        $STARLAB_INSTALL_PATH/lib/starlab

  To use them, it should be necessary only to include lines like the
  following in your Makefile (the "-l" libraries may differ -- these are
  for a dyn target):

      CPPFLAGS = -I$(STARLAB_INSTALL_PATH)/include/starlab -DHAVE_CONFIG_H
      LDLIBS   = -L$(STARLAB_INSTALL_PATH)/lib/starlab -ldyn -lnode -lstd -lm


DEVELOPERS

- The new configuration procedure produces a lot of output, which may
  become annoying if you find yourself repeatedly rebuilding programs as
  you debug them.  To reduce the volume of diagnostic information coming
  from the make process, use "make -s" or the 'smake' script found in
  $STARLAB_PATH/sbin.  Smake will build the specified target, starting
  the process at the top level (i.e. at $STARLAB_PATH), using "make -s"
  option to suppress extraneous output.

- The current configuration currently creates duplicate copies of objects
  and executables -- local versions are used to build the package, and
  these are then copied into the install directory by 'make install.'
  This can be confusing, as it is very possible to rebuild a program
  without installing it, thus creating two versions and causing confusion.
  We recommend always rebuilding libraries from the top level with

	smake libs

  which will guarantee that all local libraries are updated, and
  rebuilding programs with

	sremake program

  which will rebuild all outstanding libraries, then delete, rebuild,
  and properly install the executable.

- If the autotools are properly installed, developers should find that
  any changes made to the automake "Makefile.am" files will cause the
  relevant Makefiles to be automagically regenerated the next time make
  is involked.

- If you modify the configure.ac script in $STARLAB_PATH, you *MUST*
  run autoreconf before running configure again.


COPYRIGHTS

- see the COPYING file in this directory for information on the GPL.

- for use and attribution policies, see the README file in
  "doc/README", or

	http://www.sns.ias.edu/~starlab/policies