========= CXrL SHADOW 2.3 (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.7.2 (Earlier version 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 Sun's C++, HP C++, SGI C++. 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.0.tar.gz -- complete source distribution. If you want the GUI as well, also get gui-1.1.0.tar.gz (or whatever is the latest version on our server) - gui-1.1.0.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.0 tar.gz | tar xf - 3.2. If you have GNU TAR and GNU unzip utility: % gtar zxf /tmp/shadow-2.3.0.tar.gz Now you have a tree rooted at /usr/local/src/shadow-2.3.0. ========================================================================== >> 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. 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, then you could say: % env CC=c89 /usr/local/src/shadow/configure 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 ...) 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 distribute binaries. eg., if configure cannot determine where your X Window libraries are, you can do the following: % configure --x-libraries=/path/to/libraries/X11 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 See the PLATFORM file for options used for distribution on each platform. >>>> 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.0 % configure % gnumake % gnumake install This will install SHADOW under /usr/local/src/shadow-2.3.0 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 Build tree : /usr/local/src/shadow/$(ARCH) [ARCH=SUN4 for instance] Install tree : /usr/local/shadow (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.0/HP % cd /usr/local/src/shadow-2.3.0/HP % /usr/local/src/shadow-2.3.0/configure --prefix=/usr/local/shadow % ../configure --with-optimization --prefix=/usr/local/shadow % 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.0/HP, and the .shadowrc* files will be edited accordingly. >>>> 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 -- 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. ========================================================================== >> 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 or Franco Cerrina at +1 608 263 4955 . 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 Fri Apr 11 22:24:13 1997 Mumit Khan ############ ------- x --------