Getting Started Documentation Glish Learn More Programming Contact Us
Version 1.9 Build 1556
News FAQ
Search Home

next up previous contents index
Next: Writing Glish Functions Up: General Help Previous: Getting Help

Subsections


Getting Started


Setting up your account to use AIPS++


AIPS++ user setup

The AIPS++ environment is defined via a once-only modification of your shell startup script.

Assuming that AIPS++ has been installed under /aips++, users of Bourne-like shells (sh, ksh, bash) must add the following line to their .profile file at a point after PATH (and MANPATH) are defined: 

[ -f /aips++/aipsinit.sh ] && . /aips++/aipsinit.sh

The equivalent entry in .login for C-like shells (csh, tcsh) is: 

if (-f /aips++/aipsinit.csh) source /aips++/aipsinit.csh

The aipsinit scripts define a single environment variable called AIPSPATH, and prepend the AIPS++ bin area to the PATH environment variable, and the AIPS++ doc directory to the MANPATH environment variable (There are no UNIX style man pages available, AIPS++ documentation is available on-line via the world-wide-web).

For more detailed information, see aipsinit including an explanation of AIPSPATH and a mechanism for controlling the point where the AIPS++ bin areas are added to PATH.


AIPS++ programmer setup

AIPS++ Environment Variables

Normally, AIPS++ programmers must belong to the AIPS++ programmer group (in the unix sense) in order to have permission to write to the AIPS++ source directories. The conventional name for this group is aips2prg, but it may be set up differently at your site. Consult your local AIPS++ manager.

AIPS++ programmers must invoke the aipsinit scripts from their .profile or .login files as do users. However, programming is normally done on the gnu version of AIPS++. The required incantation of aipsinit for Bourne-like shells is 

if [ -f /aips++/aipsinit.sh ]
then
   aips_ext=gnu
   . /aips++/aipsinit.sh
fi

and for C-like shells 

if (-f /aips++/aipsinit.csh) then
   set aips_ext = gnu
   source /aips++/aipsinit.csh
endif

Note that the aipsinit scripts explicitly unsets aips_ext In Socorro, the default aips_ext is gnu, so there is no need to set it.

AIPS++ Directory Tree

Programmers also need to create a shadow copy of the AIPS++ code directory tree to serve as their AIPS++ workspace. The mktree utility does this automatically: 

mkdir $HOME/aips++
cd $HOME/aips++
mktree

Apart from creating a shadow copy of the AIPS++ code directory tree, mktree creates symbolic links into the local AIPS++ rcs directory tree thereby linking the programmer's workspace directly to the local copy of the AIPS++ RCS repositories. However, do not use ci or co to check code in or out, see Checkout for instructions on how to do that.

mktree works incrementally so that if any workspace directories or RCS symbolic links are accidently deleted, or if new AIPS++ directories are created, mktree will recreate only what is necessary. For a more detailed description, see mktree

Getting started on AIPS++ programming


Checking source code in and out

Code Management Background

The first thing to realize about AIPS++ code management is that, on account of the distributed nature of AIPS++ code development, a master copy of the AIPS++ sources resides in Socorro, and some consortium sites have slave copies which are updated automatically at least once a day by the AIPS++ code distribution system (if all goes well that is - and it usually does).

RCS is used for source code management in AIPS++, refer to the unix manual page for rcsintro for more information. On both master and slave systems the AIPS++ sources reside within dual directory trees which exist under the AIPS++ root directory. One of these,  aips++/rcs, contains the RCS source code repositories, and the other,  aips++/code, contains plain-text sources. Symbolic links named RCS exist in each subdirectory of  aips++/code and point into the corresponding subdirectory of  aips++/rcs, thereby tying the two directory trees together for checkout of sources. The code distribution system updates the rcs tree, and the code tree is then updated from it. The sources under  aips++/code are used to build the AIPS++ system locally, including object libraries, executables, documentation, system databases and more.

When it comes to modifying or adding new AIPS++ sources, the RCS checkin and checkout operations must be performed directly on the master RCS repositories in Socorro. A valid but tedious way of doing this would be to rlogin to Socorro, checkout the sources you're interested in, ftp them back to your home machine, modify them, ftp them back to Socorro, and then check them back in. Alternatively, AIPS++ sources can be checked in and out, updated, or deleted via the ai, ao, au, and ax utilities running on your local machine (ax may only be run in Socorro). These commands work directly on the master AIPS++ RCS repositories via an NFS automount running across the internet which was (or should have been) set up when AIPS++ was first installed at your site. For this reason the commands may appear to execute slowly, or in some cases you may get a message to the effect that the network is down and to try again later (you will also get this message if the NFS automount was not set up properly).

Note carefully that although the programmer workspace created by mktree contains RCS symlinks into the local RCS slave repositories, you should never use co -l to check code out with a lock, or ci to check it back in again. This would only affect the local slave repository, your changes would not be propagated back to the master in Socorro or the other consortium sites. The RCS symlinks in programmer workspaces are provided so that you can check out sources without a lock, or use the rlog or rcsdiff commands (provided you don't mind that the local RCS repository may be out-of-date by up to a day).


Checking out source

When you check out a file using ao it is checked out from the master in Socorro. The ao script is really a front-end for the ordinary RCS co command but with built-in knowledge of the AIPS++ code management system. ao takes all the same command line options as co. In particular, you can use ao -l filename.ext to check out a file named filename.ext, locking others out of the capability to modify the file while you are working with it; and you can use ao -u to cause a checkout to be forgotten. Check the unix manual page for co for more information.


Checking in source

The checkin script, ai, operates in much the same way as ao. It is a front-end to the RCS ci command and takes the same command line options. However, ai does more. After checking the code back into the master in Socorro, it updates the local RCS slave repository by copying the master version back, and then updates the plain-text file in the AIPS++ code directory. That way the local slave copy of the AIPS++ sources is updated immediately, and you don't have to wait for the automatic update delivered by the code distribution system.


When to check in new code

Since AIPS++ is a production system, we are very concerned about the stability of the system. As a result, one should be very careful about checking in new features. The overall rules are:


Other code management utilities

On occasion it may happen that someone from another consortium site checks in some source code and you want your local slave repository to be updated immediately. The au command does this for you by copying the RCS version file from the master and then updating the plain-text copy.

Deletion of sources is handled by the ax utility. Since all deletions must be propagated to the slave copies, and also because of certain timing questions, ax can only be run on the master sources in Socorro.

For a more detailed description of the various utilities discussed, see Code management


Compiling your source code

The make system

System generation in AIPS++ is handled by a hierarchy of GNU makefiles. These makefiles are quite complex because of the complex job they have to perform, building AIPS++ on various platforms at any number of sites at which AIPS++ has been installed.

For a programmer, however, the main thing to recognize about the makefiles is their two-sided nature. Apart from rebuilding the AIPS++ system from installed sources, they also support programmer workspaces. Where a programmer has created new sources, or checked out and modified old ones, they must recompile them locally and leave the results in the programmer's private workspace. Furthermore, programmers are not required to check out associated sources, such as header files, just for the sake of the compilation. After searching unsuccessfully for a file in the programmers own workspace, the makefiles carry the search into the standard AIPS++ source code directories.


System-targets

In accordance with the dual role of the makefiles their targets are of two kinds, system-oriented and programmer-oriented. The default target of every AIPS++ makefile, all, is programmer-oriented, and recompiles everything in the programmer's workspace which is out-of-date. It is usually sufficient for programmers to invoke gmake without arguments to recompile their sources. The corresponding system-oriented target is allsys and, like all system-oriented targets, this recompiles any new sources in the standard installation without any reference whatsoever to anything in the programmer's workspace.


Programmer-targets

The programmer-oriented targets in the makefile for class implementation files and applications deserve special mention. They allow programmers to specify private include file directories via the MYINCL variable which can be defined on the command line 

   gmake MYINCL=/home/bloggs/include MyClass.o

Likewise, the applications makefile provides a MYLIBS variable which allows for private libraries. If you wanted to compile an AIPS++ application and link it to class implementation files which you had modified but not checked in, you would need to build a private library by using the programmer-oriented mylib target in the implementation makefile. You could then link your application to this using the MYLIBS variable.

The AIPS++ makefiles and the standard target names are discussed at length in makefiles

next up previous contents index
Next: Writing Glish Functions Up: General Help Previous: Getting Help   Contents   Index
Please send questions or comments about AIPS++ to aips2-request@nrao.edu.
Copyright © 1995-2000 Associated Universities Inc., Washington, D.C.
Return to AIPS++ Home Page
2006-10-15