|
|
III. Environment Variables and Organization of Unix TRANSP FilesAs with most unix software systems, TRANSP operates under the context of a user defined environment. This environment defines the location of TRANSP files, and related installation-specific information. It is the user's responsibility to set up this environment correctly. A template is provided in the files sample.login which is available via anonymous ftp at ftp.pppl.gov:pub/transp/codata/doc. This file will have been encountered already if the README instructions were followed in order to fetch a copy of the TRANSP source code. Traditionally, the environment is imbedded directly in the user's .login or .cshrc files in the user's home directory. Alternatively, it may be placed in a file .transprc in the user's home directory. The choice depends on whether the user wants TRANSP definitions automatically upon every login. If TRANSP definitions are desired every time, the .login, .cshrc, or other initialization file for the shell of the user's choice, may be used. If TRANSP definitions are only desired occasionally, then use the .transprc file: (a) get a copy of `sample.login' (b) edit for local use, following the guidelines below. (c) rename to .transprc in the home directory (d) when you login and desire TRANSP, do (assuming csh): > source .transprc to set up the local TRANSP environment. The exact procedure may be slightly different for non-csh users. TRANSP files are found in a hierarchical directory tree. The root of this tree and the top level subdirectories of this root are expected to be identified by environment variables that are defined in the user's environment. These root environment variables are:
The definition of CODESYSDIR is $TRANSPROOT/codesys, and most documentation files are in $CODESYSDIR/source/doc (i.e. $TRANSPROOT/codesys/source/doc) with certain specially formatted (VMS legacy) files in $CODESYSDIR/doc For more detailed information on files and directories, see the document $CODESYSDIR/source/doc/unixdirs.doc This file is $CODESYSDIR/source/doc/unix_transp.doc. Transp EnvironmentIn setting up the .login environment, the following steps should be attended to. This will be easier if you use the `sample.login' file as a template. (a) define TRANSPROOT (see discussion, above).(b) NAG libraryThe TRANSP dependency on NAG has been removed; NAG_SP and NAG_DP definitions are no longer required. (c) f90/C++ mixed language codesCPP_TRAILER environment variable now required... FTN_TRAILER, FTN_MAIN environment variables Several f90 codes, including TRANSP itself, now use C++ based subroutine libraries. In order to link such codes, an environment variable which lists the C++ runtime libraries must be defined. This environment variable is called "CPP_TRAILER". To support calling fortran programs from C++ main programs and for those fortran programs which require linking with the C++ linker, the environment variables FTN_TRAILER and FTN_MAIN are required. FTN_TRAILER defines the fortran libraries needed during linking from a C++ program. FTN_MAIN defines the object file containing the fortran main() function -- it is used during linking of a fortran program with the C++ linker. As of 21Jun2004, the four main programs transp,dbtran,toric4_main and key_access_test require C++ linkage. The choice of linker (see $CODESYSDIR/csh/linkload) is based on the following prescription for a program defined in $CODESYSDIR/source/<name> fortran program - by default linked with f90 with no c++ libraries - if <name>_cpp.inf is defined in <name> directory, link with f90 and include c++ libraries defined in CPP_TRAILER - if <name>_cpp.inf and <name>_ftn.inf are defined in the <name> directory then the environment variables FTN_MAIN and FTN_TRAILER must be set and the program will be linked with g++. FTN_TRAILER should contain the linker switches pointing to the fortran libraries and FTN_MAIN should point to the object file containing the fortran main() symbol. If the environment variable FTN_LINK_WITH_F90 is set, then the f90 linker will be used as though the <name>_ftn.inf file did not exist. c++ programs - by default linked with g++ - if <name>_ftn.inf is defined in <name> directory link with g++ using the fortran libraries in FTN_TRAILER The following is a copy of a csh login script for intel linux that is currently being used to support the production system on the PPPL Unix Cluster (rga 20Aug2003). The C++ compiler referenced in the CPP_TRAILER must be consistent with the C++ compiler and library path referenced by the PATH and LD_LIBRARY_PATH environment variables (see setcpp.login) Caution-- EXPECT this to CHANGE OFTEN; this document may not be up-to-date. It would be nice if the Linux/gcc folks would clean up their handling of this, someday... (this is a copy of the intel linux part of codesys/source/doc/setcpp.login for use with gcc 3.2 and lahey-fujitsu f90 compiler 6.10c -- rga 20Aug2003): setenv CPP_TRAILER "-L/usr/local/gcc32/lib -lstdc++" setenv FTN_TRAILER "-lfj9i6 -lfj9f6 -lfj9e6 -lfst -lfccx86_6a" setenv FTN_MAIN "/usr/local/lff95/lib/fj90rt0.o" Several f90 codes, including TRANSP itself, now use C++ based subroutine libraries. In order to link such codes, an environment variable which lists the C++ runtime libraries must be defined. This environment variable is called "CPP_TRAILER". The following is a copy of a csh login script that is currently being used to support all platforms on the PPPL Unix Cluster... #! /bin/csh if ($WORKSTATION_TYPE == 'SUN') then setenv CPP_TRAILER /usr/local/lib/libstdc++.so.2.10.0 > else if ($WORKSTATION_TYPE == 'LINUX') then if ($H == 'alpha') then setenv CPP_TRAILER -lstdc++ else setenv CPP_TRAILER "-L/usr/lib/gcc-lib/i386-redhat-linux/egcs-2.91.66 -ls endif else setenv CPP_TRAILER "-liostream /usr/local/lib/libstdc++.so.2.10.0" endif (d) define the LOADER_TRAILER environment variable.Define environment variables to locate system libraries, such as NetCDF, that can be linked to the code. (But, LOADER_TRAILER can still be used as before). Here are some sample values:
Other libraries which may be required - Appropriately optimized versions of the standard freeware mathematics libraries LAPACK and BLAS should be built. Sources for these libraries can be found at http://www.netlib.org if required. The software libfftw.a, "Fastest Fourier Transform in the West", cf www.fftw.org, is required by ICRF codes and must be provided. LOADER_TRAILER options ( as from Aug 2004 ) LOADER_TRAILER may be used to add to the library search path, as shown in the example above generic_dummy This library contains dummy routines, for example to satisfy references to mdsplus libraries, if these are not available, & a reference to the library was traditionally included in LOADER_TRAILER. However, most of the external libraries are now required to build a useable version of transp, & so including generic_dummy in all builds is likely to conceal errors in the build process. It is better to add generic_dummy to the .._exe.link file , only for those executables which are known to require it. Link Errors Two linux commands to help identify link errors - a) ldd $XE/<name>
b) Tracing program links
MDSplus A note on MDS+ "include" files (Tina Ludescher May 2001, revised Aug 2004): If they are somewhere else, MDSPLUS_DIR must be defined, eg Note: The mdsplus library locations are now defined by the variable MDSPLUS ( see previous section ) , rather than in $LOADER_TRAILER as previously. $SC/System_options sets appropriate options based on the presence of MdsLib in LOADER_TRAILER, or the definition of MDSPLUS. If both are absent, mdstransp dummy routines are compiled which don't require mdsplus include files. Command line editingThis is an option that allows emacs style command line editing to be used within TRANSP's interactive command line oriented fortran programs like rplot and the ufile utilities. To activate this, 3 steps are required:(1) modify LOADER_TRAILER to pick up the free software foundation (gnu) C libraries needed (LINUX machines find the libraries in the default systems libraries area so a "-L" option won't be needed). (2) (non-LINUX machines) define an environment variable CCLIB_INCLUDE to point to the root of the directory tree where gnu's C header files are located, (3) define an environment variable GETLINE_EDITOR ...where the values assigned in steps (1) and (2) are site dependent. More details: (1) At PPPL, the appropriate LOADER_TRAILER fragment is: non-LINUX "-L/usr/local/lib -lreadline -lhistory -ltermcap" LINUX: "-lreadline -lhistory -ltermcap" These are "gnu" free software foundation libraries for C subprograms (which TRANSP uses). **Whether and where these libraries are installed may vary from system to system**; TRANSP will load without them but then interactive codes won't support command line editing. (2) Non-LINUX machines Use the environment variable CCLIB_INCLUDE to point to the directory where the "gnu" free software foundation C header files are to be found; at PPPL the correct value is /usr/local/include but this could vary from site to site. (Linux machines have the header files under /usr/include, where gcc looks by default, so, no CCLIB_INCLUDE definition is needed). (3) Set the GETLINE_EDITOR variable to any value. The build script merely checks whether or not it is defined.--CAUTION-- TRANSP may not build correctly if only a subset of steps (1, 2, 3) are carried out! Sample segment for login script:#--------------- # link to readline & history, if available... # ...assume some of LOADER_TRAILER has already been set. # if ( -d /usr/local/include/readline ) then setenv LOADER_TRAILER \ "$LOADER_TRAILER -L/usr/local/lib -lreadline -lhistory -ltermcap" setenv CCLIB_INCLUDE /usr/local/include setenv GETLINE_EDITOR TRUE else if ( $WORKSTATION_TYPE == "LINUX" ) then setenv LOADER_TRAILER "$LOADER_TRAILER -lreadline -lhistory -ltermcap" setenv GETLINE_EDITOR TRUE endif e) Set the PATH variableThe PATH environment variable must be defined to included the directories $TRANSPROOT/bin $CODESYSDIR/csh $LOCAL/exe in the search path for executable programs -- use code along the lines of `sample.login'. Also, please make the definitions: setenv XE $LOCAL/exe setenv SC $CODESYSDIR/csh setenv SB $TRANSPROOT/bin Some procedures make use of these abbreviated environment variable names. Note that PATH should include the directories containing the system binaries used for access to client-server source code control, i.e. the cvs, rcs, gzip, diff, gnu make and patch programs. It was already necessary to do this in order to import a copy of the TRANSP source code. Access to the source code control software will similarly be needed for any successful future update of the source code. Note also that with the advent of XTRANSPIN and SGLIB, one must use the GNU "make" (gmake). The `make' command should point to gmake. If this is not done at the system level it can be done by the user by including the directory $HOME/bin early on the user's PATH and setting up a link $HOME/bin/make to gmake. (f) Set the WORKSTATION_TYPEThe environment variable WORKSTATION_TYPE should be defined to identify the type of unix workstation you are running. Use $SC/test_os{_csh} to set it. Currently known types are:
If you are porting TRANSP to a new type of workstation, use its generic name as the definition of WORKSTATION_TYPE, and be prepared for some extra work as described in section III below. (g) SELECTION OF FORTRAN COMPILER TRANSP is now a fortran-90 code. There is no
longer an option to build the code using fortran-77 only. Generally, the
vendor's compiler is used. Switches are set in
$CODESYSDIR/csh/Default_options.On Intel LINUX, we recommend the fujitsu
compiler. See
http://w3.pppl.gov/~dmccune/papers-reports/linux_f90.txt and set the
environment variable
|