|
| |
bootstrap/readme
Contents
Document
$TRANSPROOT/bootstrap/README
replicated in: $PPLDATA/README & anon. ftp.: pub/transp/codata/README
on ftp.pppl.gov
-- D. McCune, last update 23 Apr 1999
dmccune@pppl.gov
Princeton Plasma Physics Laboratory
work supported by DOE contract:
DE-AC02-76-CHO-3073
01-May-2001 jec Setup info is in unix_transp.doc ( .htm )
23 Apr 1999 modification `hostname` workaround now uses
FULL_HOSTNAME, not HOSTNAME ( see anonftp.csh )
5 Jan 1999 modification: added description for setting up secure
shell (ssh) access to the code. This is
now the preferred method.
30 Nov 1995 modification: introductory documents now accessed by
anonymous ftp; source code by cvs client-
server interface. NFS-based system replaced.
28 Sep 1993 modification: extraction of named subset of TRANSP code
now supported.
Recommended files to get with anonymous ftp:
============================================
README
agreement.doc <--- please read this, our code sharing agreement.
remote_site.doc
sample.login
transp_share.doc
unix_commit.doc
unix_transp.doc
============================================================================
**prerequisites**
For information on hardware/software prerequisites for a successful
TRANSP installation, see:
$TRANSPROOT/codesys/source/doc/remote_site.doc
replicated in: $PPLDATA/remote_site.doc & anon. ftp.:
pub/transp/codata/doc/remote_site.doc
on ftp.pppl.gov
**environment definition**
A template -- in csh shell language -- is provided for definition of the
environment variables needed to install, build and operate TRANSP. See:
$TRANSPROOT/codesys/source/doc/sample.login
replicated in: $PPLDATA/sample.login & anon. ftp.:
pub/transp/codata/doc/sample.login
on ftp.pppl.gov
**installation instructions**
README provides information on how to get a copy of TRANSP sources, but
it does not describe how to compile or test these sources on your machine.
For the latter information, see:
$TRANSPROOT/codesys/source/doc/unix_transp.doc
replicated in: $PPLDATA/unix_transp.doc & anon. ftp.:
pub/transp/codata/doc/unix_transp.doc
on ftp.pppl.gov
============================================================================
TRANSP is a system for scientific analysis of tokamak experimental data.
The source code is maintained on the server machine transp.pppl.gov, at
Princeton Plasma Physics Laboratory. It is accessible by arrangement to
remote sites wishing to use the code or participate in code development
collaborations. The source code is distributed using public domain unix
source code control software (cvs and rcs).
In addition, a set of test data and generated make files is maintained in a
form accessible via anonymous ftp in ftp.pppl.gov:pub/transp/codata/download.
This data, which is not stored in the source repository, is needed to
build and test the code.
Two procedures are described:
A. Procedure to connect to cvs repository.
B. Procedure to import a copy of source code and test data.
It may be helpful to use the `sample.login' file as a guide to setting
up your environment.
---------------------------------------------
A. Procedure to connect to cvs repository:
1. Arrange for access. ** remote sites must use secure shell (ssh) ** to
connect to the PPPL TRANSP source code repository. Your system must have
ssh and associated software (ssh-keygen, daemons) installed. Your system's
ssh software must be properly configured so that your system can authenticate
its identity to remote ssh sites (a process involving use of public and
private "host keys" which, to the user, are handled automatically by ssh).
For background information on ssh, see the man pages.
In the account which is to receive a copy of the TRANSP code, use
ssh-keygen
to create a user public-key / private-key pair. This results in the
creation of a file
~/.ssh/identity.pub
which contains the user public-key. The TRANSP source code server will
need a copy of this file in order to enable establishment of an ssh
connection with authentication of user identity.
To begin the process of setting up a secure connection, send two Emails
to dmccune@pppl.gov with the following information. The 1st Email
should contain the following information:
(a) your name
(b) reason for wanting a copy of the code
(c) your unix machine name (fully qualified name, not ip address)
(d) your username (under which TRANSP will reside) on this machine.
The 2nd Email should contain an exact copy of your ~/.ssh/identity.pub --
note that the contents of this file is a single line of text which is
typically over 300 characters wide. This needs to be sent without
truncation of the text line and without insertion of extra line breaks.
These two Emails contain the necessary information for enabling the
TRANSP source code server to receive a secure connection from your
TRANSP user/developer account.
You will receive a reply when your ssh read/write access to the source
repository is enabled. The steps that must be done on the server side
are described in $TRANSPROOT/codesys/source/doc/ssh_enable.doc.
2. In order to completely set up ssh access, and to be able to help
in case of problems, the keeper of TRANSP (i.e. dmccune) will need a login
account on your machine! Please grant me such an account! You can Email
me a temporary password or call me at USA (609) 243-2731.
3. Test that your ssh connect capability is working properly. From your
TRANSP account issue the command:
ssh -l xshare transp.pppl.gov ls repos
The first time you issue this command, you are likely to get a message
to the effect of: "Host key not found ... Are you sure you want to
continue (yes/no)?". If this happens, type "yes" and then repeat the
test; the message should not recur.
You should not be prompted for a password or pass-phrase. You should
get a response to the command that looks something like this:
> ssh -l xshare transp.pppl.gov ls repos
CVSROOT
IDL_CALL_EXTERNAL
bin
bootstrap
codesys
config
cvstest1
cvstest2
daemon
export
ntcc
workers
If the test does not yield this result, seek help; send Email to
dmccune@pppl.gov. It is not possible to proceed until an automatic
secure ssh connection can be established.
4. Create an empty directory that will serve as the root of your
installed TRANSP system. Define the environment variable TRANSPROOT
to point to this directory. If convenient, use the `sample.login'
template for environment variable definitions.
5. Set up use of source code control software (assumed to be already
installed on your system):
(a) define the CVSROOT environment variable as:
xshare@transp.pppl.gov:/u/xshare/repos
(b) define the CVS_RSH environment variable to contain the path
to your secure shell (ssh) program. Typically this will be
/usr/local/bin/ssh
but this is not true on all systems! You can see where your
ssh is located by issuing the command `which ssh'.
(c) be sure that your PATH environment variable is defined so that
recent versions of the programs
cvs rcs diff gzip patch ssh
are accessible as commands. Try typing
> cvs -v
to see which version of cvs you are running (it should be 1.5
or better).
You can use the `which' command, e.g.
> which gzip
to see if the other programs are on your PATH.
Most users choose to define TRANSPROOT, CVSROOT, CVS_RSH, and PATH at
login time; the precise method for this depends on your choice of shell.
6. Check out a copy of the directory $TRANSPROOT/bootstrap:
> cd $TRANSPROOT
> cvs checkout bootstrap
When the command completes you should see something like the following
as contents of the bootstrap subdirectory:
> ls bootstrap
CVS README entar.csh install.csh readme.old
If you are unable to get this far, you should stop now and seek help
by sending Email to dmccune@pppl.gov.
If the `cvs checkout' command produces errors, you can obtain additional
information by adding the -t switch:
> cvs -t checkout bootstrap
---------------------------------------------
B. Procedure to import a copy of source code and test data:
The script `install.csh' will create the necessary directory structure
and import a copy of the source code and any needed test data and/or
make files required to build and/or test the code.
**NOTE NOTE NOTE** if when running the install.csh procedure you get the
error message
? anonftp: (hostname) does not return fully qualified name
set the environment variable FULL_HOSTNAME to the fully qualified
name (like foo.pppl.gov, not just foo) and retry install.
it means that your system has been setup such that the command `hostname`
does not return the fully qualified ip name (with domain) for your host
machine. The workaround for this is to define the environment variable
FULL_HOSTNAME to contain the fully qualified name, as described in the message.
The script can be used in either of two ways: (1) full installation of
the entire TRANSP code, or (2) partial installation of a named subset of
the TRANSP code.
1. Full installation.
> cd $TRANSPROOT
> csh -f bootstrap/install.csh $TRANSPROOT
WARNING -- this REPLACES any previously existing copy of TRANSP
under $TRANSPROOT !! If you have an existing transp version which you wish to
keep,
then enter the full directory path of the NEW version, in place of $TRANSPROOT,
as the
argument to install.csh ( cant be too careful !! jec 01-May-2001 )
2. Partial installation.
A named subset of TRANSP may be selected. As of 30 Nov 1995, the
following subset options exist:
ufiles (ufiles library and ugraf1, ugraf2, gsmoo1, gsmoo2 utilities)
ufutil (ufiles library with complete set of utilities)
ufrplot (ufiles, utilities, and rplot transp output viewer code)
xfpprf (standalone FPP code by Greg Hammett, Michel Evrard et al.)
extraction of these subsets gives you the named software plus enough of
the system to enable construction of the named software (i.e. support
programs for the make file generator, etc.). To get a named subset add
the environment variable definition
> setenv PARTIAL_TRANSP TRUE
to your login environment, then do:
> cd $TRANSPROOT
> csh -f bootstrap/install.csh $TRANSPROOT xfpprf
i.e. to select the xfpprf subset.
WARNING -- this too REPLACES any previously existing copy of TRANSP
under $TRANSPROOT !!
-------------------------------------------
Additional step (optional): create a file
$TRANSPROOT/config/csh_mail.address
and put in the file a mail address, to which you would like to have
reports mailed. Certain procedures for updating the code from the
central cvs repository involve the production of reports. If you
do not create this file, these reports are mailed to the account
named by the output of the `whoami` command.
-------------------------------------------
When done, follow the instructions in the (newly created) file
transp/source/doc/unix_transp.doc
to set up and test your newly extracted copy of TRANSP.
You can make improvements in this copy of TRANSP and publish your
improvements to the world, using cvs.
Please keep us informed of your experience and work with the code --
send mail to dmccune@pppl.gov, or call Doug at USA (609) 243-2731.
|