Compiling Niagara

The examples below refer to niagara_2; the same build system is currently used for niagara_3.

CVS Checkout

The Niagara CVS repository is located at /p/niagara/repository. You'll need to create a workspace to checkout Niagara into and compile it in:

% cd ~/
% mkdir niagara-ws
% cd niagara-ws
% cvs -d /p/niagara/repository get niagara_2

## for csh-like shells
% setenv CVSROOT /p/niagara/repository
## for sh-like shells
$ CVSROOT=/p/niagara/repository
$ export CVSROOT

Configuring the Build Environment

Niagara currently uses the GNU autoconf and automake facilities to support Makefile generation.

After checking-out a workspace you'll need to configure it for the GNU tools:

% cd niagara_2/src
% aclocal
% automake -a
% autoconf
% configure

configure is often broken and will get some things wrong. One of these is a really big problem; configure says that const doesn't work in the compiler and disables it. It does this via a -Dconst= in the DEFS= stanza in the Makefile. The other problem is that it doesn't think the system comes with __STDC__ header files. This isn't a big as a problem as const is, but could be better. If either of these problems happens, edit config.cache by hand to say that the compiler and/or system supports these features. After you edit config.cache you'll need to run configure again to propagate the changes.

ac_cv_c_const=${ac_cv_c_const='yes'}
ac_cv_header_stdc=${ac_cv_header_stdc='yes'}

The automake stuff doesn't work so well, and I recommend editing the resulting config.cache by hand to fix some problems and ensure that everyone is using the same tools. Below is a list of stanzas from the config.cache file; update the values to match those presented below.

ac_cv_prog_CC=${ac_cv_prog_CC='/s/gcc-2.95.3/bin/gcc'}
ac_cv_prog_CPP=${ac_cv_prog_CPP='/s/gcc-2.95.3/bin/gcc -E'}
ac_cv_prog_CXX=${ac_cv_prog_CXX='/s/gcc-2.95.3/bin/g++'}
ac_cv_prog_LEX=${ac_cv_prog_LEX='/s/flex/bin/flex'}
ac_cv_prog_YACC=${ac_cv_prog_YACC='/s/bison/bin/bison -y'}

You can avoid this hand-editing by setting some environmetn variables before running configure:

export CC=/s/gcc-2.95.3/bin/gcc
export CPP='$(CC) -E'
export CXX=/s/gcc-2.95.3/bin/g++
export LEX=/s/flex/bin/flex
export BISON='/s/bison/bin/bison -y'

At the end of Makefile.common you'll need to select the COMMON_LIBS stanza for the system you are compiling on; comment out the others. The configuration here is for Linux boxes, just because that is what most of the people on the project use by default.

Tweaking the Niagara Configuration

The top-level Makefile.common is a Makefile fragment which is included in every Makefile built in Niagara. This Makefile contains common definitions which are used throughout the system, for example locations of include files and libraries for the individual Niagara components.

This Makefile also contains configuration options, such as #defines, which tweak the behavior of Niagara. For now read the Makefile to see what these are. I plan on documenting them here later, but Makefile.common will always be the master reference.

In addition Makefile.common contains definitions of software which Niagara uses. This allows you to easily switch between different versions of this software, or to use your own special version for debugging or testing purposes. Because of this indirection you only will need to tweak a specification in this Makefile, rather than in every Makefile in the system.

Compiling onto the Local Disk

The best place to store the source code from your workspace is in AFS. In fact, if you have anything that isn't disposable, it is the only place to keep your source tree. It is increasingly common that the local disks on CS machines are not backed up -- if something happens to source on the local disk you (and the project) could loose valuable work. Keep it in AFS. There are other reasons for keeping the source in AFS. For example, I keep my source tree in AFS so I can access it and compile the same source on several architectures and operating systems. Another is so that you can give access to your source tree to another Niagara person -- even if they can't access your workstation.

Of course, if you are using a workspace for throw-away purposes, by all means check it out onto a local disk. I do it all the time. Just make sure that you don't start modifying it with changes you want to keep.

However AFS is not the best place to compile your workspace. Writes to AFS are slow. Large writes, such as binaries, are slow. The best place to compile your workspace is onto local disk. It is fast and makes good use of your fast cpu -- and it reduces network traffic. By the way, this also goes for the location of your databases -- keep them out of AFS.

For now, the way I recommend to do this is to use a symbolic link tree on the local disk. The symbolic link tree is a shadow of the source files which are in AFS. This shadow tree allows you to access source files from the compilation workspace easily. Any files created by the configuration and build will be placed on the local disk among the shadowed files.

To do this you should start out with an absolutely clean source tree. I recommend checking a new one out from CVS, rather than trying to clean up an old source tree. It is too easy for some files to be overlooked and for mistakes to happen otherwise.

First, create a build tree on the local disk:

% cd /scratch/user
% mkdir niagara-ws
% cd niagara-ws

Then make a symbolic link copy of the AFS source onto the local workspace:

% lndir ~/niagara-ws ./

After the symoblic link tree is setup, just follow the earlier build instructions. However, you follow the instructions cd-ed into the local build tree, NOT in the source tree in AFS.