Installation Instructions for Ufiles-related Modules Prepared by C.Ludescher-Furth -- transp_support@pppl.gov 10/01/01 **************** REVISION HISTORY **************** date Description May 15, 1999 -- Created Oct. 1, 2001 -- Use /Makefile instead of TRANSP scripts. May 07, 2004 -- Added ufile's idl functions. Index: 1. CONTENTS 2. UNPACKING INSTRUCTIONS 3. DESTINATIONS 4. BUILDING INSTRUCTIONS 4A. BUILDING libufshr 4B. Ufile IDL functions 5. TESTING INSTRUCTIONS 6. DOCUMENTATION 7. FINAL INSTALLATION ************ 1. CONTENTS: ************ This directory should contain the following files: - README -- brief description - INSTALL -- detailed installation (this file) - Makefile -- to build all all libraries and test programs ./share -- include file Make.flags, Make.local.sample ./include/fpreproc -- *.h files for cpp ./fpreproc -- scripts for pre-processing of fortran ./portlib -- internally used library ./vaxonly -- internally used library (no relation to VAX) ./sgdummy -- stubs for sglib ./generic_dummy -- stubs for netCDF and MDSplus libs ./ -- Makefile and sources for various libraries ************************** 2. UNPACKING INSTRUCTIONS: ************************** Note: Download the module(s) into an empty directory. for tarfiles: > gunzip .tar.gz > tar xvf .tar or, for zip archives: > unzip .zip **************** 3. DESTINATIONS: **************** Or where do the files go? (this refers to building and testing; see FINAL INSTALLATION for end result) When you extract the tar file you get sub directories: ./share -- include file Make.flags, Make.local.sample ./include/fpreproc -- *.h files for cpp ./fpreproc -- scripts for pre-processing of fortran ./test -- sample data for testing ./ -- Makefile and sources for various libraries The makefile will create more sub directories, lib: for the library, libxplasma.a mod: for the f90 modules obj/*: for compiled objects and pre-processed sources test: for the test programs and the sample output files. By default these directories are created in ./, which is determined by Make.flags. e.g.: if you are running Linux, and the tar file resides in $HOME/foo, the directories would be in $HOME/foo/LINUX/... You can overwrite the destination by defining OBJ, as an environment variable (e.g. export OBJ=/dir1/dir2), or with make (e.g. "make all OBJ=."). If OBJ is defined, the destinations will be $OBJ/lib and $OBJ/test. If OBJ is defined as "." then, in the example above, the destination would be $HOME/foo/lib. The rationale behind is to facilitate building for various platforms. Note: If you define OBJ as option to gmake, you have to consistently do so; e.g: gmake clean OBJ=., gmake install OBJ=. ************************* 4. BUILDING INSTRUCTIONS: ************************* Steps to do: ------------ For example, if you were to download the archives into directory /scratch/foo, to install the package, you would use the following commands: If you have downloaded tarfiles in /scratch/foo: > cd /scratch/foo > gunzip .tar.gz > tar xmvf .tar > /usr/local/bin/gmake all >& my.log & or > /usr/local/bin/gmake all OBJ=. >& my.log & If you have downloaded zip archives: > cd /scratch/foo > unzip -qo > rm .zip > /usr/local/bin/gmake all >& my.log & This will make all Ufiles-related libraries and test programs/utilities of the module(s) that you have downloaded including xtc. During the make, some compiler warnings are likely to be generated. Usually, these can be ignored. However, more serious errors should be reported to the authors. > gmake checklibs -- tells you what the makefile will do (without any action); it says which libraries it will make and which ones it already found and where. > gmake clean -- to remove objects > gmake realclean -- to remove objects and library > gmake show_makeflags -- to display make definitions Command Line Editing Feature: ----------------------------- The Makefile tries to determine if you have command line editing libraries "-lreadline -lhistory -ltermcap" and accordingly compiles portlib and links programs. If your site has a partial installment, define NO_EDITLIBS Alternatively you can modify Make.local.sample and rename it to Make.local. Porting: ======== The following architectures are supported: AIX IRIX64 HP_UX OSF1 SunOS Linux Alpha Linux CRAY Compiling on Linux: ------------------- By default the Makefile will select Lahey Fujitsu. To select a different compiler define FORTRAN_VARIANT to "Portland" "NagWare" "Fujitsu" or "Absoft" e.g.: setenv FORTRAN_VARIANT Portland (csh) FORTRAN_VARIANT=Portland; export FORTRAN_VARIANT (sh) Alternatively, FORTRAN_VARIANT can be passed directly to the gmake command, as in: gmake FORTRAN_VARIANT=Portland To use vastf90: > gmake VAST90=y To use NAG90: > gmake NAG90=y Compiling on Alpha Linux: ------------------------- The Makefile assumes the Compaq compiler and specifies the " -assume no2underscores " option. Therefor the calling user software must also be compiled with this option, or you should edit share/Make.flags to remove the option. Compiling on SUN: ----------------- The Makefile specifies the " -fast " option which includes -dalign. Therefor the calling user software must also be compiled with this option, or you should edit share/Make.flags to remove the option. ---------------------------------- If you have any problems or need to add a new architecture, the files to change are: share/Make.flags : for SGLIB and Xtc / Tek sglib/Makefile : for sglib xtctek/Makefile : for Xtc / Tek Customizing: ------------ To define custom specific installations rename share/Make.local.sample to share/Make.local and edit it accordingly. ********************* 4A. BUILDING libufshr ********************* To build a shareable image of uflib: 1. you will also need the modules TrGraf and SGlib (if you downloaded uutil, you already have everything) 2. build all libraries as described in "4. BUILDING INSTRUCTIONS" 3. make libufshr.so - cd uflib - gmake SHARED=Y so libufshr.so will be in ..//lib/libufshr.so 4. copy libufshr.so into your "site specific" library directory - the library location must be in the LD_LIBRARY_PATH of the users - if you have an MDSplus Server, it must also be in the Servers, PATH *********************** 4B. Ufile IDL functions *********************** IDL functions to read/write Ufiles are in subdirectory mdspro. Copy these functions into your "site specific" location. The location must be in the users's IDL_PATH ------------------------------ *********** 5. TESTING: *********** Data files for testing are provided in the subdirectory "test". For convenience, do a "cd" into this directory. To test Ufiles Library, use uftype: =================================== "uftype" is a user interactive Ufiles format analysis / conversion tool (for online help type /test/uftype). > cd /test > ./uftype ACS37065.ECS output should be: %UFINIT -- using root directory for temporary files: /u/xshare/ ACS37065.ECS: portable_binary 2d nsc=1 npt=65536 4096x16 [OLD VALUE: "ACS37065.ECS ..."] uftype: enter filename: enter "q" to quit ------------------------------------ To test Trgraf Module, use tgtest: ================================== "tgtest" uses SGLIB to plot data, contours, etc. See sglib/README to test SGLIB. Also, for SGLIB, TERMINAL_TYPE must be defined e.g.: TERMINAL_TYPE=XTERM > cd /test > ./tgtest @tgtest.ind ------------------------------------ To test full set of utilities: =============================== All utilities need SGLIB. See sglib/README to test SGLIB. Also, for SGLIB, TERMINAL_TYPE must be defined e.g.: TERMINAL_TYPE=XTERM The utility programs are described briefly in the "utilities" section of "Ufiles Help", an HTML version of which is accessible via the Ufiles home page. > cd /test > ./concat @concat.demo > ./extrac @extrac.demo > ./gaver1 @gaver1.demo > ./gsmoo1 @gsmoo1.demo > ./gsmoo2 @gsmoo2.demo > ./propane @propane.demo > ./sawtoo @sawtoo.demo > ./splice @splice.demo > ./splice2 @splice2.demo > ./thin1 @thin1.demo > ./thin2 @thin2.demo > ./ugraf1 @ugraf1.demo > ./ugraf2 @ugraf2.demo ************************ 6. DOCUMENTATION: ************************ Ufiles Home Page: http://w3.pppl.gov/NTCC/Ufiles NTCC Home Page: http://w3.pppl.gov/NTCC ********************** 7. FINAL INSTALLATION: ********************** Choose or create the root directory in which you wish to install the software. A common location would be /usr/ntcc, but installation can occur in any directory where you have appropriate permissions. You define your choice of root directory via PREFIX. The default for PREFIX is /usr/ntcc. The assumptions are: libraries in: $PREFIX/lib = $LIBDIR programs in: $PREFIX/bin = $BINDIR man pages in: $PREFIX/man/man3 = $MANDIR/man3 To install the software, return to the top directory (the directory, where you downloaded the tar files) and type > gmake install to install into /usr/ntcc/... > gmake install PREFIX=/dir1/dir2/ to install into /dir1/dir2/... If you want things elsewhere, you can overwrite the default with > gmake install BINDIR=/xxx LIBDIR=/yyy MANDIR=/zzz NOTE: ----- All libraries are installed following unix conventions. Users should link with: -L/lib -luflib -lufhdf, etc. Make sure users know what is. ---------- After you have installed the software, you can delete the entire tree with > cd .. > rm -r foo assuming the previous example. Note: You might wish to preserve the demo files in subdirectory "test". ---------------------------------------------------------------------------- IF YOU HAVE ANY PROBLEMS, PLEASE CONTACT: transp_support, Princeton University transp_support@pppl.gov