Subject: Installation and maintenance of Newstar outside NFRA
Author: Marco de Vos (CMV), Henk Vosmeijer (HjV)
To: Friends of Newstar

Date: 24/11/94

Revision history 



Installation and maintenance of Newstar outside NFRA





1. About Newstar and this document


Newstar is the reduction package for WSRT data. 

It makes optimal use of the specific properties of the WSRT. 


You can use it to:



General information on Newstar operations can be found in the Newstar
Documentation. This documentation is available on-line. If you are 
familiar with World Wide Web browsers like XMosaic, you can get at the
documentation by opening http://www.nfra.nl/newstar/hlp/homepage.html

Otherwise, please send an eMail to newstar@nfra.nl for assistance.


This document is concerned with installation and maintenance of Newstar
at institutes other than the NFRA. It descibes our export policy, the
procedure for first time installation and the procedures for local 
maintenance.




2. Export policy


The master copy of the Newstar software is maintained at the NFRA in
Dwingeloo. Newstar is available for end-users on the following machines:

    
(the two-letter codes will be used in the remainder of this document)


This list may be extended with other Unix systems in future. Newstar 
can also be run on Convex (cv) systems, but this is not officially 
supported by the NFRA.


If you want to install Newstar on your institute, the Newstar group 
will assist with the first time installation of the package. We expect 
you to assign a local "Friend of Newstar" who will take care of local
maintenance, using the procedures described in this document. In case 
of problems, you can of course contact the Newstar group, who will do
it's best to solve things on a short notice. 


The Newstar maintenance at the radio-observatory in Westerbork is 
updated by the Newstar group at a weekly basis.




3. First time installation


It should be noted that the Newstar group is available for assistance
with the first time installation of Newstar. Also we can implement such
things as changes in printers and tapeunits. However, this section 
describes the installation process in full detail.



3A. Before installation


Before you can install Newstar, you have to sort out the following 
things:

You should fill out the form in Appendix A and eMail
it to newstar@nfra.nl (from this point on the Newstar group
can take care of installation).



3B. Installing the Newstar sources


You should have tar-archives  nstar_src.tar.Z   and  nstar_src_aa.tar
(where aa is the abbreviation of the architecture on which you want to 
use Newstar, you may need several nstar_src_aa.tar files) from tape or 
from anonymous ftp to  ftp.nfra.nl (directory newstar). 

To unpack this archive, use the following commands:

>>>    cd "Newstar root-directory"
>>>    mkdir src
>>>    cd src
>>>    uncompress [directory_with_archive/]nstar_src.tar.Z
>>>    tar xvf    [directory_with_archive/]nstar_src.tar
>>>    tar xvf    [directory_with_archive/]nstar_src_aa.tar




3C. Adapting to your local situation


Assign an abbreviated name for your institute (up to 5 characters). This 
name will be refered to as "xxxx" in the remainder of this document.


Your local situation will be reflected in the following files, all in 
directory  "Newstar root-directory"/src/sys

newstar_xxxx.csh   Directory structure, tape-units, some details
wngfex_xxxx.csh    Commands for printing
i_aaxxxx.csh       Fine-tuning for compilation on architecture "aa"


In general, the Newstar group will create these files based on information
supplied by you. In case you want to create the files yourself, please use
the versions for the nfra (newstar_nfra.csh etc.) as a template, since 
they are extensively documented.


In newstar_xxxx.csh you should define at least the following:

    

  1. The Newstar rootdirectory

    (setenv n_root "Newstar root-directory")

    

  2. The Newstar site

    (setenv n_site xxxx)

    

  3. The architectures you want to install Newstar for (we distribute 
some precompiled binaries and libraries for which you need only the 
versions specified here, these are in fact in nstar_src_aa.tar)   

    (setenv n_install hp/sw)

    

  4. The hosts on which Newstar has to be compiled (just one host per 
architecture please...)

    (setenv n_hosts   host1,host2)

    
The order in n_install and n_hosts is arbitrary, but you best keep it
the same in both variables for your own convenience.

    

  5. Definition of tape-units

    (setenv MAG4 /dev/rmt/0mn)

    

  6. The location of the executable files and libraries if they 
should not reside on the same filesystem as the sources. 
You should create those directories yourself. If you do not 
specify directories here, they will be created automatically.


If you create any files yourself, we would like to receive a copy of them.
The files will then be included in the Newstar master.



3D. Building Newstar


If you want to make an executable installation for architecture aa, login 
on a host of that architecture and initialise the Newstar environment:

>>>    source "Newstar root-directory"/src/sys/newstar_xxxx.csh


You may have received archives nstar_exe_aa.tar or nstar_lib_aa.tar.
If aa matches the name of your architecture, you may just untar these files
in the appropriate directories to get a working system:

>>>    nup quit
>>>    cd $n_lib
>>>    uncompress [directory_with_archive/]nstar_lib_aa.tar.Z
>>>    tar xvf    [directory with_archive]/nstar_lib_aa.tar
>>>    uncompress [directory_with_archive/]nstar_lib_inc.tar.Z
>>>    tar xvf    [directory with_archive]/nstar_lib_inc.tar
>>>    cd $n_exe
>>>    uncompress [directory_with_archive/]nstar_exe_aa.tar.Z
>>>    tar xvf    [directory_with_archive/]nstar_exe_aa.tar


If you need to build Newstar from scratch, use the following commands:

>>>    nup build -u wntinc            (will give 9 errors for dsc-files which could not be 
				       translated because wntinc does not yet exist.)
>>>    nup build -u -t:exe wntinc
>>>    nup build -u all


Logs of all transactions and errors are kept in $n_src/updyymmddaa[i].log
where i is an index (e.g. upd930623sw.log, upd930623sw1.log).


If something goes wrong during the installation, the log-files will be sent
to the Newstar group by eMail. This assumes you have the  elm  mailer 
running at your institute. If you do not have it, you should supply an
alias to e.g. mail or mailx in newstar_xxxx.csh 
(add a line like alias elm 'mail -s "\!1" \!2 ')




4. Using Newstar, revisions and releases


If someone wants to run Newstar programs, the Newstar environment should
be initialised first:

>>>    source "Newstar root-directory"/src/sys/newstar_xxxx.csh


This can be safely done in a .cshrc or .login file.


You can now display the version of Newstar you are currently using:

>>>    nnews


This will display the version number first, followed by a list of 
recent changes. The version number consists of a release number followed
by a dot and a revision number. 

>>>    dwe nscan


Programs are started by typing dwe (or exe) followed by the name of the
program. This will display a line like "NSCAN$1 (v4.21) started ...".
The version number can be lower than the version displayed by nnews, since
a revision may concern only some programs. A full revision history with 
the revisions for every program can be found in the on-line documentation
(select "Revision history" from the Newstar home page presented by nhyper). 


A revision of Newstar is a series of minor changes that do not affect 
the overall operation of Newstar. Revisions are typically bug repairs,
small additions to the functionality of a program etc. They do not affect
keyword syntax and fileformats. 


A release of Newstar is issued when any of the following occured:

    

  1. A change of fileformats (so you will have to use the 
NVS "New Version" option in some programs)

  2. A change in keyword syntax (so you will have to type different 
things or change batch files in some cases)

  3. Addition of a new program, or a full rewrite of an existing one.






5. Keeping your installation up to date


In the following we assume that the Newstar environment has been initialised.


If we modify the Newstar master at NFRA, all Friends of Newstar that we
know of will receive an eMail describing the changes. This message will
also contain instructions how to upgrade your installation. 


In most cases, upgrading is done through a single command:

>>>    nup update


This in fact causes the following commands to be executed, which you may
also execute by hand:

  >>>    cd $n_import


The default directory is set to $n_import, which is the proper place to
receive new files. This keeps your current sources intact.

  >>>    nup retrieve all


This will make a fresh version of the file $n_src/sys/database.idx, which
gives a full description of your current installation.
Than it will retrieve the version of database.idx from the NFRA for 
comparison. Any files that need to be updated are retrieved in $n_import.
The list of files retrieved is in file  retrieved.grp.

  >>>    nup build -Update -T:^exe retrieved.grp


This will build all files just retrieved, and any files dependent on them.
No executables will be built, this will be done after the library check.

  >>>    nup clear -NConfirm


This will throw away any source files in the master system that are no 
longer needed.

  >>>    nup check l


This will check your libraries. Experience shows that escpecially on HP
workstations libraries tend to get cluttered. This will be found by the
library check. If necessary, an additional build command will be scheduled
to rebuilt modules. Objects for which no source is present are removed 
from the libraries. Duplicate entries are both removed and replaced by 
a fresh entry. Out-of-date entries are updated.

  >>>    nup check e -Update


This will check your executables. Executables that do not yet exist 
or are out-of-date with respect to the NFRA are rebuilt. Note that usually
not all versions need to be rebuilt for a new revision. Thus some programs
may show a lower version than the version shown by nnews.

  >>>    rsh HOST '( source $n_src/sys/newstar_xxxx.csh; nup update rsh)


If $n_hosts (as defined in newstar_xxxx.csh) contains more hosts, the above
command will be issued for each of them. This will carry out the build 
and check commands listed above, but not the retrieve.


The proceedings of the update command will dump a lot of output on your
screen, which is also stored in logfiles $n_src/updyymmdd[i].log (see 
above). You may want to redirect the output to a file or /dev/null.
If any errors occur, the log-file will be sent to the Newstar group by eMail.




The nup command has many more uses than the ones described above. Most of
them should not be relevant to you, since they are related to partial
rebuilds, making backups etc. In case you are interested though, you can
get more information through the command

>>>    nup help -help






Appendix 1: Questionnaire new Newstar sites


Provide the following information, and send it to newstar@nfra.nl

    


  1. Site:
    2. 

      

    1. Institute: 

      

    2. Abbreviated institute name (up to 5 char):

      

    3. Address:   

      

      

      

    4. Friend of newstar: 

      

    5. eMail address:  

      

    6. ftp node(s):    

      

    7. Phone:

      

    


  2. Platform:
    3. 

      

    1. Platform(s) and their hostname(s) on which Newstar should run: 

        

      1. Convex (cv)

      2. DEC Alpha/OSF1 (da)

      3. DECstation (dw)

      4. HP workstation (hp)

      5. SUN (sw)

      
If not in list contact to newstar@nfra.nl for possible inclusion of
your platform.

      

    2. Do platforms have a common NFS on which to place sources? 

        

      1. Yes

      2. No

      
(only if more than one platform requested at 2.1)

      

    3. Root directory for Newstar: 

      (e.g. /usr/src/newstar )

      

    4. If object-libraries should be placed on a different file system,
specify here:

      

    5. Idem executables: 

      

    6. Could you provide an account on your platform(s) in which we can
login to do some remote checks can be made? 

        

      1. Yes

      2. No

      
If YES, please specify it: 

      

    


  3. Software:
    4. 

      

    1. Are you using the standard f77, cc and ld provided with your system? 

        

      1. Yes

      2. No

      
If not, provide details on how to call them, and the switches provided)

      

    2. What is your standard command to print 132 wide ASCII files? 

      

    3. What is your standard command to plot A4-format PostScript files? 

      

    4. What is your standard command to plot A3-format PostScript files? 

      

    5. Which other plotters would you like to use? 

      (contact newstar@nfra.nl to see if support is possible)

      

    


  4. Input/Output medium:
    5. 

      

    1. Specify the device-names of the available mediums for reading/writing data?

      

    2. Specify on which medium you want to receive Newstar if you cannot 
support ftp: 

      (9track/density, Exabyte, DAT, ...)