========= CXrL SHADOW 2.3.2 (Source code) Unix Installation Guide ==========

>> TOC:
    REQUIREMENTS
    GETTING SOURCE CODE
    CONFIGURATION
	Running Configure
	Checklist
    BUILD TREE
    TROUBLE SHOOTING
    CONTACT
    MAILING LIST

==========================================================================

>> REQUIREMENTS:
    compilers
	- FORTRAN 77 with some extensions. On linux/ELF, GNU G77 0.5.18 
	  or newer would do for this. f77/f2c needs too much work, so 
	  don't bother trying. The --with-gnu-f77 option to configure is
	  implied on i[45]86-*-linux machines.
	
	- C compiler. Any ANSI C compiler, eg., GNU C, Sun ANSI C. 
	  Whatever C compiler you pick, it MUST support ANSI-C.

	- C++: GNU C/C++ 2.8.1 or EGCS-1.1.x (Earlier versions won't work!) 
	  works. If you don't have GNU C++, then EXCON may not build. No 
	  biggie for most SHADOW users. Does build without errors with 
	  HP C++, SGI C++ if you have STL (Standard Template Library).
	  You can disable excon build with --without-excon option when 
	  running configure.
    
    X Windows: 
        - X Window drivers in PLPLOT graphics library (which is used by
	  PLOTXY, PRIMVS, etc) needs working X Windows includes and
	  libraries. If you don't have X and don't care, supply configure
	  with --without-x option.

    Make:
	- GNU make 3.71 or newer.
    
==========================================================================

>> GETTING SOURCE CODE:

1. Get the following from the Web/ftp server at CXrL. Follow the
   instructions at http://shadow.xraylith.wisc.edu/shadow to download
   software and get the source archive:

    - shadow-2.3.2.tar.gz -- complete source distribution. If you want
      the GUI as well, also get gui-1.1.2.tar.gz (or whatever is the
      latest version on our server)

    - gui-1.1.2.tar.gz -- The source code for GUI. I have not included
      this in the SHADOW source distribution simply because it requires
      3rd party GUI tookits that you may not have and may not want. If
      you want to build GUI as well, you should contact Mumit Khan for
      more information on Tcl/Tk and the required patches to these.

2. Pick a root where to keep the sources. It could be anywhere. I'll use
   /usr/local/src just as an example:

   % mkdir /usr/local/src
   % cd /usr/local/src

3. Unpack the archive and create the source tree:
    3.1. If you don't have have GNU TAR, but do have the GNU unzip utility:

       % gunzip -c /tmp/shadow-2.3.2 tar.gz | tar xf -

    3.2. If you have GNU TAR and GNU unzip utility:

       % gtar zxf /tmp/shadow-2.3.2.tar.gz 

Now you have a tree rooted at /usr/local/src/shadow-2.3.2.

==========================================================================

>> CONFIGURATION:

SHADOW 2.3 release uses GNU configure/autoconf utility to build the
makefiles on your system. The configure script provided basically does
the following:
    
    - hunts your system for various pre-installed headers and libraries,
      eg., FORTRAN 77 compiler, GNU C/C++ compiler, etc.
    
    - substitutes the paths for these 3rd party items in Config.mk file
      that sits at the top of the build tree. Each Makefile in the tree
      includes this file, so if something isn't quite right, you can
      simply change it in one place per package.
    
    - Create the makefiles and other misc. files (eg., .shadowrc) file.

Most likely "configure" will find all that's needed on your system without
any hand-holding, but you might need to help it along in some cases. Some
of the ways to help configure find headers/libraries etc on your system
are described below.

There are two different ways (can use both, so not mutually exclusive) you
can help configure -- via command line arguments and/or via Unix
environment variables. 


Currently the following command line options are useful for configure:
(a snippet from the output of ``configure --help'')

General options:
The following group is entirely optional -- configure should be able to
figure these out by itself. That's it's job.

  --help                  print this message
  --prefix=PREFIX         install files in PREFIX/ (eg., /usr/local/shadow)
                          (the default is `pwd`)
  --srcdir=DIR            find the sources in DIR [configure dir or ..]
  --x-includes=DIR        X include files are in DIR
  --x-libraries=DIR       X library files are in DIR
  --with-x                use the X Window System (default)
  --without-x             If you don't have X Window system installed
			  PLPLOT graphics will be built w/out X support.

SHADOW specific options:
Most of these have reasonable defaults, so you need only specify the ones
that have irritating default values.

  --with-rays=NRAYS       number of rays in SHADOW (default: 25000)
  --with-start-format=FORMAT 
                          Default format of SHADOW START files (def: GFILE)
			  The choices are GFILE and FORTRAN.

  --with-debug            compile with debug option
  --with-optimization     compile with optimization (Default)
			  The default is "-g -O" if your compiler supports
			  it or just "-O" if not.

  --with-gnu-f77          use the GNU F77 compiler. Default on machines
			  that have no other choice (eg., Windows'95/NT);
			  on machines with reasonable FORTRAN compilers,
			  configure will pick the system one (eg., xlf on
			  AIX, f77 on DECs and SUNs etc over g77 any day)
  --with-f77-save-variables
                          force compiler to save all variables. Default yes.
                          Say no if you really know what you're doing. At
			  least on alpha-dec-osf3.2, this exposes all sorts
			  bug in SHADOW. Specifying this option adds a
			  special compilation flag on most systems that 
			  support this feature (eg., -K on HPUX, -static on
			  Ultrix and IRIX, -noautomatic on Alpha/OSF).
  --with-binary-io=TYPE   use FORTRAN or C routines for unformatted I/O.
			  The default is to use FORTRAN, unless you are 
			  using g77, in which the C version performs 400%
			  better.

Miscellaneous options:
  --with-pdcurses         use PD Curses instead (default on WIN32). Not yet
			  supported on other systems.
  --with-rpath=PATH       Additional shared library resolution path. This
			  is important if you want to move SHADOW after
			  building it or distribute it to other machines.

eg., if configure cannot determine where your X Window libraries are,
you can do the following:

    % configure --x-libraries=/path/to/libraries/X11 \
        --prefix=/usr/local/shadow-2.3.2

Note the --with-rays=NRAYS option to choose the number of rays SHADOW
will build with.

The SHADOW binary distributions are built with the following options:
    
    % configure --with-optimization --prefix=/usr/local/shadow-2.3.2

On HP-PA machines running HP-UX, configure can die due to limitations in
the supplied Bourne shell (which configure uses by default). Please see
the PLATFORMS file on a workaround using Korn shell (/bin/ksh).

See the PLATFORM file for options used for distribution on each platform.

Along with the command line options described above, you can also use
Unix environment variables.  To make hunting easier, each variable 
(location of headers and libraries for most part) can be tweaked by 
using environment variables; eg., if you want to force the use of C 
compiler c89 instead of gcc or cc, eg., on a alpha-dec-osf3.2 system, 
then you could say: 

    % env CC=c89 /usr/local/src/shadow-2.3.2/configure [OTHER OPTIONS]

Here's the list of env variables you can supply to configure as of
2/27/96 in addition the ones standard configure scripts already accepts.

    CPP                 ... C Pre-processor
    CPPFLAGS            ... C/FORTRAN Pre-processor flags
    FC_CPP              ... FORTRAN Pre-processor for .F files
    FC                  ... force a particular f77 compiler (eg., xlf).
    FFLAGS              ... FORTRAN compiler flags
    CC                  ... C Compiler
    CFLAGS              ... C Compiler flags
    CXX                 ... C++ Compiler
    CXXFLAGS            ... C++ Compiler flags
    (and others ...)

>>>> Running Configure:

To get a quick feel for what options GNU configure accepts, use the
following: 

    % configure --help

The simplest way to build SHADOW is to run configure in the root of 
the source tree and then run GNU make to create the binaries.
    
    % cd /usr/local/src/shadow-2.3.2
    % configure 
    % gnumake
    % gnumake install

This will install SHADOW under /usr/local/src/shadow-2.3.2 directory. 
Now running gnumake distclean should clean out all the object code.

This simple way has 2 problems:
    
    1. clutters up the source tree with object code and binaries
    2. Building for multiple architectures from the same source is 
       messy

To avoid this, I use the following scenario:

Source tree   : /usr/local/src/shadow-2.3.2
Build tree    : /usr/local/src/shadow-2.3.2/$(ARCH) [ARCH=SUN4 for instance]
Install tree  : /usr/local/shadow-2.3.2 (aka PREFIX in --prefix=PREFIX option)

Where source tree is where you put your source code, build tree where
all the object code goes during compilation/linking and Install tree 
is where SHADOW is finally installed. The pathnames above are of course
arbitrary and you are free to choose whatever is appropriate.

eg., to build on HP,

    % mkdir /usr/local/src/shadow-2.3.2/HP
    % cd /usr/local/src/shadow-2.3.2/HP
    % /usr/local/src/shadow-2.3.2/configure --prefix=/usr/local/shadow-2.3.2 \
      --with-optimization
    % gnumake 

and if all goes well,

    % gnumake install

If you want to copy the docs and demo files over, use the following:

    % gnumake install-docs

You can now safely remove the HP directory completely, unless you want
to continue development.

If you do not specify the --prefix=DIR option, then SHADOW will be 
installed in the build tree, ie., under /usr/local/src/shadow-2.3.2/HP,
and the .shadowrc* files will reflect that.

>>>> Checklist:

==========================================================================

>> BUILD TREE:

The installation/build tree after the install looks like the following 
(let's assume that you've chosen /usr/local/shadow as the $prefix):

/usr/local/shadow-2.3.2	-- installation prefix
    .shadowrc		-- C-shell (/bin/csh) startup scripts
    .shadowrc.sh	-- Bourne (/bin/sh) startup scripts
    SHADOW_VERSION	-- tells you what release you're running
    NEWS		-- NEWS about this release
    bin/		-- binaries
    lib/		-- libraries (archives)
    data/		-- runtime data (eg., optical constants)
    demo/		-- demo files
    doc/		-- SHADOW on-line docs
    include/		-- needed headers from various packages

If you move the installation elsewhere, please remember to edit 
.shadowrc and .shadowrc.sh files to change the SHADOW_ROOT variable
to the new top-level directory. 

You can now safely delete the include directory and all the archive
libraries (*.a files) in lib directory. You should not however delete
the *.a files (archive libraries) if you intend to develop software
that uses the SHADOW libraries (eg., a program that reads/writes SHADOW 
ray files using RBEAM and WRITE_OFF subroutines).

==========================================================================

>> TROUBLE SHOOTING:

The following are some configuration problems due to system differences,
mostly due to inadequacies of the Bourne shell on various machines.

If you have trouble with configure, I suggest you run configure under
Unix script utility and email the log to SHADOW hacker-at-large.
    
    % script /tmp/configure.script
    % [RUN Configure here]
    % exit

Please also email the "config.hints" file found in the same directory.

For more detailed info, see the file PLATFORMS in the source distribution.

==========================================================================

>> CONTACT:

For more information on SHADOW, please contact Mumit Khan at
+1 608 265 6075 <khan@xraylith.wisc.edu> or Franco Cerrina at 
+1 608 263 4955 <cerrina@xraylith.wisc.edu>.

Center for X-ray Lithography
University of Wisconsin - Madison
1415 Engineering Drive
Madison WI 53706

==========================================================================

>> MAILING LIST:

There is also a mailing list for SHADOW users. To join, send a
mail to majordomo@xraylith.wisc.edu with "subscribe shadow-users"
in the body of the message. More info at the SHADOW Web site:

    http://shadow.xraylith.wisc.edu/shadow


#############

Last Updated Thu Jan 28 13:58:45 1999 Mumit Khan <khan@xraylith.wisc.edu>

############

		        ------- x --------
