Reasonably concise startup instructions for setting up a TRANSP development account on a PPPL RHEL LINUX system. Caution: this document will need frequent updates as systems evolve. ==> Last update: D. McCune 18 Feb 2005 --------------------------------------------------------- Outline: I. Prerequisites-- Skills, Unix account, csh login script, ssh. II. Obtaining a copy of the code. III. Building the code. IV. Working with the code. Each sections ends with a short summary. --------------------------------------------------------- I. Prerequisites-- Skills, Unix account, csh login script. This document assumes some basic skills-- general familiarity with Unix (Linux) and shells; ability to edit a text file or script. Programming experience (especially fortran) will also be helpful. For basic PPPL Linux information, see http://beowulf.pppl.gov -- check out in particular the "New Falcon Cluster User Guide". A recommended text editor is GNU emacs (or xemacs), for which the text is the "GNU Emacs Manual" by Richard M. Stallman. Given these basic skills, the first steps to becoming a TRANSP developer are as follows. a) acquire a PPPL unix account, as a member of the "transp" group-- D. McCune or other TRANSP group members can sponsor you. b) use tcsh as your shell, unless you have a strong preference not to. (Available canned transp login scripts are in (t)csh, but we can accomodate users of bash or other shells with some extra work). c) modify your startup script (~/.login) to define necessary environment variables. This document is oriented to users of the most current PPPL "Red Hat Enterprise Linux" (RHEL) Linux cluster nodes. To login on such a machine, ssh portal.pppl.gov -l In order to work with TRANSP, you'll need to use a login script to define some environment variables. If you restrict your development to the new RHEL machines, the following scripts should suffice: /u/xshare/codesys/source/doc/rhel_transp_pppl.csh which will need to invoke a copy of /u/xshare/codesys/source/doc/setcpp.login ... Your best bet is to grab copies of these files: > cd > cp /u/xshare/codesys/source/doc/rhel_transp_pppl.csh ./transp.login > cp /u/xshare/codesys/source/doc/setcpp.login . and edit your ~/.login script to "source" your ~/transp.login. This script assumes that you will put the root of your TRANSP code development system in the directory ~/transp -- it is recommended that you do so. For an example of a .login script with this type of change, see ~dmccune/.login but note that the "transp.login" invoked has been extensively modified to support installations on older Unix machines at PPPL. You should examine the basic transp.login script to see what it does. The summary description is that it defines environment variables which will point to the root directories for the TRANSP source code and compiled binaries, and it sets up environment variables to enable use of math libraries (such as lapack, blas, fftw) and i/o libraries (such as MDSplus and NetCDF) upon which TRANSP depends. Your PATH variable is extended, to give access to additional programs which will be created for you when TRANSP is installed and built. The transp.login script will "source" setcpp.login, where some arcane definitions are also made to enable "mixed language programming". Essentially, this tells C/C++ where to find Fortran run-time librarires, and fortran where to find C/C++ run-time libraries. Unfortunately, these library locations change with compiler versions and operating systems setups, compiler drivers do not know how to find other languages' libraries on their own, and so, these scripts will need updating from time to time, as systems at PPPL are modernized. The recommended scripts make the proper definitions for RHEL Linux systems only. If it is necessary to work on other systems, the scripts will have to be edited to include a test for type-of-machine and then make somewhat different environment definitions depending on the results of this test. If this becomes an issue, please get advice from a TRANSP expert. For new users, the RHEL systems alone should suffice. These are the fastest, most modern Linux cluster sytems at PPPL. Dealing with the login environment is actually the most complicated part of getting started with TRANSP. =>Summary of section I.: Get a unix account; configure its login script to define environment variables needed to build and operate TRANSP, on the new PPPL RHEL Linux systems. --------------------------------------------------------- II. Obtaining a copy of the code. Background information: http://w3.pppl.gov/cppg/seminars -- Autumn 1999 -- Charles Karney -- Introduction to ssh Spring 2000 -- Charles Karney -- Upgrading from f77 to f90 Summer 2000 -- Doug McCune -- Using cvs for source code control (But note that since 1999, ssh-2 has come out, which changes things slightly as will be noted below). The TRANSP source code is stored in a "cvs repository" and is accessible from a PPPL cvs source code server, via ssh. This means that developers need to have an "ssh key", which is added to the TRANSP cvs server's list of "authorized keys", in order to gain read-write access to the source code. The procedure for getting a "type 2" ssh key is as follows: (create ~/.ssh if it does not exist) > cd ~/.ssh > ssh-keygen -t dsa and answer any questions: mainly, you need to give a pass phrase for the key, which you will need to remember in order to use the key later. For security reasons a good pass phrase should be chosen. The above step should have created two files: ~/.ssh/id_dsa.pub # this is your public key ~/.ssh/id_dsa # this is your private key: owner access -rw------- only! Send the public key to the TRANSP group (transp@pppl.gov) to have it added to the authorized keys list. You will receive acknowledgement when this is done. To test the connection to the PPPL TRANSP cvs server, do the following: > ssh -l xshare transp.pppl.gov ls repos You may be prompted for your private key passphrase. You should NOT be prompted for an xshare password. You should see in response something like this: [dmccune@sunfire02 ~/.ssh]$ ssh -l xshare transp.pppl.gov ls repos Enter passphrase for key '/u/dmccune/.ssh/id_dsa': bin bootstrap codesys config CVSROOT cvstest1 cvstest2 daemon export IDL_CALL_EXTERNAL ntcc orbit workers If this is not the result, seek help. Note that adding the "-v" option to the ssh command causes extra messages to be produce by ssh, which can be a help in debugging. If you use your ssh key a lot, you may be interested in a program, ssh-agent, which allows you to type your key's pass-phrase once, and then allows you to reuse the key many times during your login session without having to retype the pass phrase each time. However, the details of how best to do this depend on what type of desktop or lap-top system you are using to connect to the network. Your best bet initially is to get help from someone using a similar setup as yours. Once your ssh setup is working, you can use a script which invokes cvs to check out a copy of the code: > cd $TRANSPROOT > cvs checkout bootstrap > csh -f bootstrap/install.csh $TRANSPROOT The actual source code will appear in $TRANSPROOT/codesys/source/* or equivalently, $CODESYSDIR/source/* ... Some more detailed discussions of this step is contained in the file $TRANSPROOT/bootstrap/README. =>Summary of section II.: obtain an ssh key, request this key to be added to the list of folks authorized to access the TRANSP source code; follow the procedure to check out a copy of the source code. --------------------------------------------------------- III. Building the code. Many documents of varying vintage describe aspects of TRANSP and its development system -- see contents of $CODESYSDIR/source/doc. In particular, $CODESYSDIR/source/doc/unix_transp.doc contains information about building TRANSP on Unix systems. However, it is very detailed because it is oriented to a developer trying to port TRANSP to a new Unix "variant" for the first time. Since the RHEL port has already been done, a vastly simplified procedure can be followed: > rehash # needed only after initial bootstrap/install.csh run. > make_begin # command builds TRANSP "make system" components > make_sglib # command builds TRANSP legacy graphics component. > make_it_all >&! $LOGDIR/make.log & # build TRANSP & write log file (a couple of hours later) > errfilter < $LOGDIR/make.log | more (if errfilter is undefined try "rehash" and repeat). The errfilter program processes a TRANSP build log file. It will produce a reduced log file with most normal output filtered out, so that possible error messages are easier to find. It is one of more than 200 executable binaries produced by a successful TRANSP build. Over 160 subroutine libraries are built as well. See contents of $LOCAL/exe and $LOCAL/lib. On PPPL RHEL sytems TRANSP should build without error. If an error does occur, seek the advice of an experienced TRANSP developer. $CODESYSDIR/source/doc/unix_transp.doc contains some simple tests for a newly installed TRANSP, including making some fast TRANSP runs. The new developer should run these tests. =>Summary of Section III.: Follow the procedure for building the code; make some simple tests of the code. --------------------------------------------------------- IV. Working with the code. See: $CODESYSDIR/source/doc/unix_transp.doc $CODESYSDIR/source/doc/transp_devel.doc These documents are somewhat old but still give the general flavor of how to work with the code. They describe: -- how to work with cvs to receive or commit updates of the code. -- how to add a subroutine to a library. -- how to create a new library. -- how to create a new executable program. -- how to (re)define the constituent components of a program. -- how to debug programs, with precise control of what program components should be debug compiled. An experienced TRANSP developer can help orient you. PPPL TRANSP developers: Doug McCune Rob Andre Kumar Indireshkumar Christiane Ludescher