1 HELP
The tools directory contains startup files.  All users should run
the initu.csh script in their .cshrc script.  Programmers should first
run initu.csh and then run initp.csh.  The .sh versions of these scripts
are for use by people of the sh/ksh/bash persuasion.  All the other
tools in this directory are provided for the use of programmers.
1 philosophy
XANADU has been designed with the following goals in mind:
 
 1) Source code and binary files do not need to be placed on the same
file system.  This allows computers of vastly differently architectures
(VMS and DOS) to share source files.  In general binary files do not
need to be shared between systems and thus should be place on a local
disk for faster access.
 
 2) There should be a temporary area to place new programs during testing.
 
 3) To allow people to use XANADU on different machines without the
need for a system manager to setup directory structure or an environment.
Wherever possible shell variables will be used under UNIX and logical
names under VMS.
 
 4) XANADU should not force the user to run a particular shell (such as
csh or cl).
 
The routines in the tools directory were created to assist the user in
meeting these goals.
1 implementation
All XANADU users must first define two environment variables that
describe; 1) what system they are on and 2) where the XANADU binaries
are kept.  Next all users should run an initu shell script, to define
the remaining environment variables and to add the installed XANADU
bin directory to the user's path.
 
If someone wishes to modify an existing XANADU program then that person
must also run the programmer's script initp.  initp must be run after
initu is executed.  initp defines several other environment variables
and adds the ``new'' XANADU bin directory to the user's path.  Since
the ``new'' directory is always searched first, programmers will always
run the test version if it exists.  If a test version does not exist
then the version installed in XANBIN will be used instead.
1 alib
This command should be used to compile a single Fortran routine and
place the object module into the correct xanlib library.  For example,
 
alib plt
 
would compile plt.for using the xfor routine and then place the
resulting object module into the xanlib library.  The xfor command
is used to compile the routine, thus all conventions of the xfor command
are followed.  The default library name is ${XANBIN}/lib/xanlib.a.
1 forall
This command will compile all Fortran routines in the current directory.
The xfor command is used to compile the routines, thus all conventions
of the xfor command are followed.  In general, forall is useful when
rebuilding all or a major part of XANADU.  Note, forall will NOT compile
a routine if an object module exists which is newer than the source file.
This allows forall to be restarted if had been stopped for some reason.
To ensure that forall recompiles all routines, delete all object modules
before running forall.
1 xfor
This command should be used to compile a single Fortran routine.  For
example,
 
xfor qdp
 
will compile the qdp.for program in the current directory.  You should
not provide an filename extension as xfor will automatically provide
this.  xfor searches for an extension using the following order:
`.${EXT}', `.f', `.for'.  Currently most XANADU files use the .for
extension.  In general, the .f extension should not be used, it is
provided for potential future use.  The .${EXT} is provided as a way
to create files that can only be used on one system.  For example, if
the SUN Fortran compiler contained a bug that would prevent it from
compiling qdp.for, you could create a qdp.sun that dodges the bug.
Thus on SUN systems, `xfor qdp' would compile qdp.sun, whereas on all
other systems, qdp.for would be used.
1 initp.csh
(If your default shell is sh/ksh/bash, then use initp.sh instead.)
 
You should follow the instructions initu.csh and then add the following
line to your .cshrc file after the place initu is executed:
 
source	$XANADU/tools/initu.csh
2 initp_details
Currently initp defines the following environment variables:
 
XANBIN   The location of the new directory area used for testing
FCOMPL   The name of the Fortran compiler for the system
FCOPTS   The standard options used with the Fortran compiler
PGPLOT   The names of all libraries that need to linked if PGPLOT is used
SYSLIB   The names of all system libraries that always be linked.
 
If $XANBIN/bin is not in the user's path, then $XANNEW/bin and $XANADU/tools
will both be added to the path.
1 initp.sh
(If your default shell is csh/tcsh, then use initp.csh instead.)
 
You should follow the instructions initu.sh and then add the following
line to your startup file (.profile, .bashrc, etc) after the place initu
is executed:
 
. $XANADU/tools/initu.sh
 
(Note, under bash you can replace the . command with the word source.)
2 initp_details = initp.csh initp_details
1 initu.csh
(If your default shell is sh/ksh/bash, then use initu.sh instead.)
 
All users should modify their .cshrc file to:
 
1) Define the XANADU environment variable to point to the top level
of the xanadu directory tree.
 
2) Define the EXT environment variable to define what type of system
you are currently using.
 
3) `source' the initu.csh script.
2 initu_details
The initu script currently does three things:
 
1) Define XANBIN.
 
2) If PGPLOT_FONT has not been defined, then define it.
 
3) If $XANBIN/bin is not in the user's path, then add it.
 
In general XANBIN=$XANADU/$EXT/bin, however, some vendors support (OK,
support really's the wrong word) two different architectures.  It is
the job of initu to sort out these differences.
2 example
Assume you are using a SUN system and that your normal shell is csh.
The manager has created a symbolic link from /xanadu to the area where
XANADU is installed.  Thus ls -l /xanadu/lib/xanlib/ will list all
the source code files in the lib/xanlib directory.  For this case
you should add the following lines to your .cshrc file:
 
#
# XANADU stuff
setenv  XANADU /xanadu
setenv	EXT sun
source	$XANADU/tools/initu.csh
2 legal_EXT's
This section lists all currently valid possibilities for the environment
variable EXT.
 
use      for
---      ---
aix      IBM AIX system
dos      a DOS based computer (not fully supported)
hpu      HP UNIX systems
sun      SUN (either Motorola or SPARC systems)
nab      NeXT systems using the Absoft Fortran compiler
nfc      NeXT systems using the f2c Fortran compiler
ngh      NeXT systems using the Oasys (Green Hill) Fortran compiler
seq      Sequent computes (not fully supported)
ulx      Ultrix systems
vms      VMS systems
1 initu.sh
(If your default shell is csh/tcsh, then use initu.csh instead.)
 
All users should modify their startup file (.profile, .bashrc, etc.) to:
 
1) Define and export the XANADU variable to point to the top level
of the xanadu directory tree.
 
2) Define and export the EXT variable to define what type of system
you are currently using.
 
3) `source' the initu.sh script using the '.' command.
2 initu_details = initu.csh initu_details
2 example
Assume you are using a SUN system and that your normal shell is bash.
The manager has created a symbolic link from /xanadu to the area where
XANADU is installed.  Thus ls -l /xanadu/lib/xanlib/ will list all
the source code files in the lib/xanlib directory.  For this case
you should add the following lines to your .bashrc file:
 
#
# XANADU stuff
XANADU=/xanadu
EXT=sun
export EXT XANADU
source $XANADU/tools/initu.sh
2 legal_EXT's = examplele legal_EXT's
1 liball
This command will find all the object modules in the current directory
and place them into the correct xanlib.a library.  In general, this
command is only used to rebuild all or a large part of XANADU.  This
would be done by going to a library directory and typing `forall' followed
by `liball'
1 xmake
The basic idea behind xmake is to create a system independent makefile
by storing all the system dependent information in environment
variables.  To use xmake, you need to have a basic understanding of
shell/environment variables work and how they interact with the UNIX
make utility.  This is described in the shell_variables and
make_variables sections.  The xmake_variables section describes the
standard environment variables that xmake uses.  To write a portable
makefile.xan file, it is very important that these variables be used
wherever possible.
 
A single example makefile.xan is discussed in two sections.  The
commented_example topic contains the template with lots of comments
describing why things are done the way they are.  The template topic
contains an uncommented version that can be cut out of the documentation
and used.
 
The exceptions section describes how to create a system-dependent
makefile that can coexist with the generic makefile.xan.
2 shell_variables
Shell variables are common to most shells and once defined in a shell
they will remain defined until the shell exits (or they are unset).
Shell variables may or may not be exported to programs or shell scripts.
Under the Bourne shell it is impossible (for me at least) to tell
if a variable is exported or not just by looking at it (you must find
where it was defined).  Under the csh, exported variables are called
environment variables and live in a different list than the normal
shell variables.  However, within csh itself, environment variables
are treated just like shell variables.  In this guide I will call
exported shell variables `environment' variables.  Although Bourne
shell derivatives do not have `environment' variables, they can be
simulated by exporting the variable with the `export' command.  In
general, you should use a shell variable if the variable only needs
to be used by the shell itself (for example, the PATH variable).
If a shell script or program will need to use the variable, then you
should use an environment variable.
2 make_variables
It is well known that makefile can use variables.  For example if
your makefile contains the lines
 
FCOMPL=f77
...
      $(FCOMPL) demo.f
 
when make runs the string `$(FCOMPL)' will be replaced with `f77'
and hence the Fortran compiler will be called.  It is also possible
to override the default definition at run time if you invoke the `make'
command with a command line arguments.  Thus `make FCOMPL=xlf' will override
the definition of FCOMPL found in the makefile.  Suppose you don't define
FCOMPL in the makefile and forget to include it on the command line.
What happens then?  For this case make checks to see if there is an
environment variable `FCOMPL'.  If the environment variable is found
then it will be used.  The environment variable is only used if the
variable has not defined in the makefile or on the command line.
2 xmake_variables
As stated previously, variables defined on the make command line
override what is found in the makefile itself.  Currently xmake defines
six variables on the command line.  Wherever possible these variables
should be used in your makefile.
 
1) EXT:  This is the default extension and should be used to identify the
operating system.  Thus under VMS, EXT='vms'.  System dependent files
should be identified using EXT, such as sysio.$(EXT).
 
2) PGPLOT:  The name/location of the PGPLOT library and all other
libraries needed by PGPLOT code.  For example,
PGPLOT='${XANBIN}/lib/libpgplot.a -lX11' would be used on a system
for which PGPLOT contains an X Window driver.  Since PGPLOT may contain
things like '-lX11', the variable $(PGPLOT) must not be listed on
a dependencies line (see example below).  This should not cause a
problem since PGPLOT should not change very often.
 
3) SYSLIB:  Some systems have extra libraries that should be linked
with every program (not just programs that use PGPLOT).  This is where
they are defined.  SYSLIB will always be the last library on a link
line.  I use SYSLIB on NeXT systems to use the sharable system
libraries, as this greatly reduces the required space.
 
4) XANBIN:  This gives the top level system-dependent directory for
the developer's version.  Thus xanadu libraries should always be found
in $(XANBIN)/lib/xxx.a and the new version of the program should be
created in $(XANBIN)/bin/xxx.
 
5) FCOMPL:  This variable contains the name of the Fortran
compiler/linker for the current system.  This variable should not
be used to compile programs rather you should use the xfor command
instead.  If for some reason you cannot use xfor then you should
use $(FCOMPL) to get name of the Fortran compiler and linker for current
system.
 
6) FCOPTS:  This variable should no longer be used in the makefile.xan
file.  The xfor deals with the necessary compiler options.  If for
some reason you cannot use xfor, then use you should use $(FCOMPL)
to get name of the Fortran compiler options for current system.
 
The XANADU startup scripts define a couple of environment variables
that can also be used xmake files.  However since these variables
are not defined on the command line, they must NOT be defined in the
makefile.
 
7) XANADU:  This gives the location of the top level xanadu directory.
You should never use an absolute path name, such as /xanadu/tst, to specify
a file name, use $XANADU/tst instead.
 
8) XANBIN:  This gives the top level system-dependent directory for
the installed version.  System dependent files that we (XANADU folk)
don't routinely change can go here.  For example, the PGPLOT font
file, grfont.dat, is unlikely (ever) to change.
2 commented_example
FCOMPL =
FLOPTS =
XANLIB = $(XANBIN)/lib/xanlib.a
PGPLOT =
SYSLIB =
! Although xmake defines many variables on the command line, not all
! these variables need to be used in the makefile.  Thus, at the top
! of the makefile, I like to list the variables that are actually used
! in the current makefile.  Thus if someone decides not to use xmake
! then that person can edit the makefile and fill in the definitions for
! FCOMPL, PGPLOT, and SYSLIB.
! Currently no system needs link options, however, FLOPTS is defined
! for potential future use.
! Any routine that uses the xanlib.a library should define XANLIB
! as above.
 
all:	qdp cod
! Target `all'  should always be first, and should make all programs.
 
qdp: $(XANBIN)/bin/qdp
! New programs should always be made in the $XANBIN/bin directory.
! The above line allows users to type 'xmake qdp' instead of the longer
! 'xmake $XANBIN/bin/qdp'.
 
$(XANBIN)/bin/qdp: qdp.o $(XANLIB)
! This line lists the dependencies for the qdp program, which consists
! of one object module and the XANLIB library.  Although qdp also depends
! on PGPLOT you should not include $(PGPLOT) on the dependency line,
! since the PGPLOT variable contains other stuff such as -lX11 that
! make would not understand.  Since it is very unlikely for a program to
! use PGPLOT and not XANLIB, updating XANLIB should cause just about
! everything to be rebuilt.
 
	$(FCOMPL) -o $(XANBIN)/bin/qdp $(FLOPTS) qdp.o\
		$(XANLIB) $(PGPLOT) $(SYSLIB)
! This is the standard way to link a program that uses PGPLOT.  Note,
! the output file is created directly in the $(XANBIN)/bin directory.
! $(XANBIN)/bin should be on a local disk to cut down on network traffic.
! Also note the existence of SYSLIB.  On SUN systems this does not do
! anything, but it is needed on other systems.  Therefore always include it.
 
cod: $(XANBIN)/bin/cod $(XANLIB)
$(XANBIN)/bin/cod: cod.o $(XANLIB)
	$(FCOMPL) -o $(XANBIN)/bin/cod $(FLOPTS) cod.o $(XANLIB) $(SYSLIB)
! This gives an example of the way to make a program that does not use
! PGPLOT.  Once again SYSLIB must be included.
 
clean:
	rm -f *.o *.s
! 'xmake clean' should delete everything that xmake makes in the current
! directory.  Some systems will leave an assembler (*.s) file around
! if something fails to compile.  Therefore you should also delete these
! files.
 
.SUFFIXES: .for
.for.o:
	xfor $*
! Since all UNIX systems seem to have different names/conventions
! for the Fortran compiler, it is best to always use the xfor command
! to compile routines.
2 template
FCOMPL =
FLOPTS =
XANLIB = $(XANBIN)/lib/xanlib.a
PGPLOT =
SYSLIB =
 
all:	qdp cod
 
qdp: $(XANBIN)/bin/qdp
$(XANBIN)/bin/qdp: qdp.o $(XANLIB)
	$(FCOMPL) -o $(XANBIN)/bin/qdp $(FLOPTS) qdp.o\
		$(XANLIB) $(PGPLOT) $(SYSLIB)
 
cod: $(XANBIN)/bin/cod
$(XANBIN)/bin/cod: cod.o $(XANLIB)
	$(FCOMPL) -o $(XANBIN)/bin/cod $(FLOPTS) cod.o $(XANLIB) $(SYSLIB)
 
clean:
	rm -f *.o *.s
 
.SUFFIXES: .for
.for.o:
	xfor $*
2 exceptions
By using variables for all common system-dependent routines,
makefile.xan files can be made very general.  There are two cases
where where you might want to override the defaults.  If the default
for your system uses the optimizer, and you don't wish to optimize
your test version, then you should redefine FCOPTS (in csh use the
command "setenv FCOPTS '-u'") and then rerun xmake.  If you then
discover that your system always needs special options, then you copy
makefile.xan to makefile.${EXT} and include the options in
makefile.${EXT}.  When xmake runs it first checks to see if
makefile.${EXT} exists, and if so uses it.  Only if makefile.${EXT}
does not exists does xmake look for makefile.xan and use it.  Finally,
if xmake can find neither file, it searches for makefile (no extension)
and if found uses it, but does not define any variables.  The purpose
of this last step is for use in non-XANADU directories, where you
should be typing `make' but your fingers are conditioned to type
`xmake'.  With the above system, a directory that contains both a
makefile.sun and makefile.xan, xmake will use makefile.sun on SUN
systems, but makefile.xan on all other systems.
1 xstall
The xstall command is used to move programs and/or libraries from the
`new' programmer's area into the installed area.  To install a program
use:
 
cd $XANBIN/bin
xstall name
 
where name is replaced by the name of the program you wish to install.
This command moves the program from the $XANBIN/bin to the $XANBIN/bin
directory.  To install a library use:
 
cd $XANBIN/lib
xstall name
 
where name is replaced by the library name, for example xanlib.a.  Note,
the library will be copied from $XANBIN/lib to the $XANBIN/lib directory.
A copy is made to that makefiles will always find a version of the
library in $XANBIN/lib.  If mess up the library, you can always go back
to the installed version by copying the library back to XANBIN/lib.
