Version 1.9 Build 1556

News	FAQ
Search	Home

Next: Coding conventions Up: Code development Previous: Code development

Subsections

Overview of code development

This section runs through the basic operational aspects of developing code in AIPS++.

Setup

Basic AIPS++ programmer setup was described in §3.1.2. To recapitulate the main points

If you will be checking sources into and out of the AIPS++ master (i.e. an AIPS++ consortium programmer) then make sure you are a member of the AIPS++ programmer group, the conventional name of which is aips2prg.
Modify your shell's login script (.login, .profile, etc.) to invoke aipsinit (p) to define the AIPS++ environment.
Invoke mktree (p) to create an AIPS++ workspace.

The AIPS++ makefiles normally deposit binary files in the same directory as programmer source files unless you create separate directories for them. If you intend to compile sources for more than one architecture or compiler then you should create these directories. A good strategy is to maintain sources within your home directory (which presumably is backed up) and relegate the binaries to some other filesystem with more space but not backed up. Hence typically

   mkdir /bigdisk/myarea/sun4sol_gnu/{aux,bin,bindbg,lib,libdbg}
   ln -s /bigdisk/myarea/sun4sol_gnu $HOME/aips++/sun4sol_gnu

Do this for each AIPS++ architecture that you are likely to use. The AIPS++ makefiles will discover and use these directories automatically. You can use aipsinit (p) to switch between architectures at any time.

Modifying existing sources

Once your workspace is set up the AIPS++ makefiles allow you to compile system sources without having to check them out into your workspace. Programmer-oriented makefile targets are described in §11.4. Typically it is enough to invoke gmake (p) without any targets. Use

   gmake help

to get a context-sensitive summary of the AIPS++ targets for each directory. Programmer-oriented targets are discussed in section §11.4.

If you wish to modify a source file then

If you are a consortium programmer and intend to change the master source code then check out the relevant source file using ao -l (p) or rao -l (p). If you do not intend to update the master then omit the -l flag.
If you are not a consortium programmer or only wish to work within your local system then
- If a copy of the RCS repository is maintained in your installation (as indicated by the presence of the $AIPSROOT/rcs directory) and you intend to update your installation then check out the source file using co -l. If you do not intend to update the local system then omit the -l flag.
- Otherwise, if your installation does not contain a copy of the RCS source repository then simply copy the relevant system file to your workspace directory.

Once you've modified the file you can compile it in your workspace without affecting the system binaries. When you're satisfied with your changes

If you want to update the AIPS++ master check the file in with ai (p) or rai (p). If you also want to update the local slave RCS repository then do so with au (p) or rau (p). You can combine the two operations via ai -au or rai -au.
Changes need to be documented in the AIPS++ changelog file using ac (p) or rac (p).
Use ci if you only want to update the local RCS repository.
If your installation does not contain a copy of the RCS source repository then simply copy the file to the system directory.

If you want to update the system binaries you will need to issue a

   gmake allsys

This can be done from a programmer workspace (although some installations explicitly prevent this by removing write permission for aips2prg from the AIPS++ system directories).

The gmake command line - flags and variable definitions

gmake (p) has several command line options which are frequently useful for AIPS++ programmers.

-help: Print usage information and exit without processing any makefiles.
-i: Ignore all errors in commands executed to remake files.
-k: Continue as much as possible after an error. While the target that failed, and those that depend on it, cannot be remade, the other dependencies of these targets can be processed all the same.
-n: Print the commands that would be executed, but do not execute them.
-W: Pretend that the target file has just been modified. When used with the -n flag, this shows you what would happen if you were to modify that file. Without -n, it is almost the same as running a touch command on the given file before running gmake (p), except that the modification time is changed only in the imagination of gmake.

Note that the default makedefs (p) sets the -no-print-directory internally (via MAKEFLAGS) and also sets -i for system invokation but not for programmer invokation. Consult the unix manual page for gmake for further options or use

   gmake --help

Do not confuse this with

   gmake help

which is an AIPS++ target which lists AIPS++ targets. Note also that you should eschew usage of the -e option (environment variables override makefile variables) unless you fully understand its implications.

The other important aspect of gmake invokation is that makefile variables may be defined on the command line and these (usually) override their definition within the makefile. The makefiles use separate sets of variables for system and programmer compilations, so for example, system C++ compilations use C++DBG and C++OPT for debug and optimized compilations whereas C++FLAGS is used for programmer compilations. The default makedefs (p) sets

   ifdef OPT
      C++FLAGS  = $(C++OPT) $(EXTRA_C++FLAGS)
   else
      C++FLAGS  = $(C++DBG) $(EXTRA_C++FLAGS)
   endif

although as described in section §11.3 the site-specific makedefs may redefine this, for example as

   ifdef OPT
      C++FLAGS := -O$(OPT) -pipe
   else
      C++FLAGS := $(C++DBG)
   endif

   C++FLAGS += $(EXTRA_C++FLAGS)

Either way, this example shows three basic types of command-line variable substitutions

Variables such as OPT which are used as switches. In the second example it is used as a switch and an optimization level. It might be used as
```
      gmake OPT=2 myprog
```
The C++FLAGS variable itself can be completely redefined on the command line, for example
```
      gmake C++FLAGS="-O4 -fast -target=native" myprog
```
The EXTRA_C++FLAGS variable can be used to add extra options to C++FLAGS, for example
```
      gmake EXTRA_C++FLAGS="-fast" myprog
```

As discussed in section §12.2, a list of variables of specific interest to programmers may be obtained via

   gmake show_prg

This may be used to show the value of the variables which would be used in a particular situation, for example

   gmake OPT=2 EXTRA_C++FLAGS="-fast" show_prg

The variables of interest to programmers are described in more detail in section §11.4.

As suggested above, the site-specific makedefs (p) may be used to alter the construction of programmer variable definitions. Several conventional constructions are discussed in section §11.3. Programmers may also implement their own definitions or constructions in a personal makedefs file as discussed in the same section.

Creating new files and directories

If you want to develop a new directory in the AIPS++ hierarchy, usually to contain a class implementation module or a new application, then simply create that directory in your workspace. Likewise, new files may simply be created - the AIPS++ makefiles do not contain lists of files but use the file suffix to determine how to process a file. Recognized file suffixes are listed in section §10.6.

All AIPS++ directories (except for .dir and tmplinst directories) must contain a makefile which must be called makefile. Typically this need only include one of the generic AIPS++ makefiles (see §10.6). For example, when creating a new application the minimum requirement would be

# $Id$

   # Use the generic AIPS++ application makefile.
   #---------------------------------------------
   include $(word 1, $(AIPSPATH))/code/install/makefile.app

Once you have finished development the new directory may be checked in to the master via ai (p). However, you may receive a message to the effect that permission for the operation is denied - creation of new files and directories in many parts of the master is restricted to particular individuals since all new code must be vetted by the ``Code-Cop''.

makefiles

The makefiles which exist in the AIPS++ source directories mostly just include a generic makefile but some need to supply additional information.

For an application you often need to register any required external libraries and may also want to define some preprocessor directives as described in section §10.7:

# $Id$

   # Use the generic AIPS++ application makefile.
   #---------------------------------------------
   XLIBLIST := GLISH WCSLIB F77
   CPPMODU  := -DFOO -DBAR
   include $(word 1, $(AIPSPATH))/code/install/makefile.app

The XLIBLIST and CPPMODU variables are relevant to the app, imp, and tst makefiles.

The documentation makefile requires arguments to be specified for conversion of L^ATEX documents to HTML via latex2html. Typically

# $Id$

   # Declare latex2html flags.
   System := -split 2
   Coding := -split 3

   # Use the generic AIPS++ documentation makefile
   #----------------------------------------------
   include $(word 1, $(AIPSPATH))/code/install/makefile.doc

This example declares that latex2html should be run on System.latex and Coding.latex. No other files in the directory with a .latex suffix will be converted to HTML although they will be converted to POSTSCRIPT. At the minimum the variable of the same basename as the .latex file should specify a -split argument to latex2html, but it can also specify any other arguments recognized by it.

This example also illustrates that L^ATEX documents must have a .latex suffix to distinguish them from plain TEX documents.

Adjunct makedefs files may contain definitions (or, in principle, rules) which apply to a particular source code directory. The adjunct files are architecture-specific and are primarily intended to control compiler options on a per-sourcefile basis. This is an advanced topic discussed in section §10.5.

Overview of code development

Setup

Modifying existing sources

The gmake command line - flags and variable definitions

Creating new files and directories

makefiles

See also