Building EUROPA
by Andrew Bachmann
2004-07-13

$Id: BUILDING,v 1.1 2005/10/11 22:39:23 pjarvis Exp $


- Prerequisites:

1. Jam 2.4 or higher.
   Jam is open source, and if not already installed on your system, 
   can be downloaded from: ftp://ftp.perforce.com/pub/jam/

   Although version 2.4 works, it is not recommended because using it
   will result in the entire tree being rebuilt even when it is run in a
   subdirectory.

2. gcc 3.3.3 (Though some prior versions are thought to work, only
   this one is tested regularly & automatically).

3. Java 1.4.2 or higher.

4. doxygen 1.2.x or higher should be OK (to build API documentation)
   doxygen 1.2.16 or higher is recommended. Older versions may
   not support all options.

If you are using computers in Code TC at NASA/Ames, the division's
System Group has likely already installed these programs (and versions
of them) that you will need to build EUROPA reliably.  

- Supported Platforms:

1. i686 Linux 2.4.20-31.9smp
2. sparc sun4u SunOS 5.8

* We have also successfully compiled Europa in the following platforms, but
we do not support them:
1. Cygwin: be sure to set your PATH to include the PLASMA/lib directory as
well as set your LIBRARY_PATH environment variable rather than the
LD_LIBRARY_PATH as indicated below.
2. BeOS: be sure to set your LIBRARY_PATH variable instead of
LD_LIBRARY_PATH  as indicated below.
3. Mac OSX 10.3: be sure to set your DYLD_LIBRARY_PATH instead of your
LD_LIBRARY_PATH as indicated in the instructions below.  Also set
DYLD_BIND_AT_LAUNCH=YES. (OSX 10.2 has been shown to work with static
libraries. But for shared libraries you will need a dlopen hack called
dlcompat. dlcompat does not support unloading libraries so some errors
will occur when this is attempted. PlanWorks Planner Control software
will not work with dlcompat.) In all of these cases, please ensure you 
have the appropriate versions of the requirements above.

- Getting started:

These instructions will allow you to quickly configure your system to
build Europa2 with the default build variants set to generate unoptimized, 
unprofiled, debug code using shared libraries.  See the sections 
'Performing a build', 'Configuring the build: VARIANTS', and 'Configuring 
the build: LIBRARIES' for details on build commands and configuring the 
build for different compiler variations and using different types of 
libraries.

For simplicity, these quickstart instructions assume using gcc-3.3.3, 
jam 2.5, and java jdk1.5.0. Of course, other versions that meet the 
above version requirements may be used instead.

1) Setting your PATH:

    PATH should include locations of gcc-3.3.3, Jam 2.4 or higher, 
    Java 1.4.2 or higher, and Doxygen 1.2.16 or higher.

    On a Linux system set your PATH to the relevant directories for your 
    particular system. If you don't know the locations of Jam, gcc or 
    Java on your system, you can use the find commands listed below to 
    help locate the executables. Then look for the directory the actual 
    executable is in. Often, but not always, this is a "bin" directory.

       find /usr -name gcc-3.3.3
       find /usr -name 'j2sdk1.*' -o -name 'jdk1.*'
       find /usr -name 'jam2.*'
       find /usr -name doxygen

    On the division SPARCs running SunOS 5.8, add the following paths
    to the head of your PATH environment variable for the locations of 
    gcc-3.3.3, jam v2.5rc3, java jdk1.5.0, and doxygen:
 
    /usr/local/beta/gcc-3.3.3/bin
    /usr/local/beta/bin
    /usr/local/jdk1.5.0/bin
    /usr/local/bin

    e.g. set path = (/usr/local/beta/gcc-3.3.3/bin /usr/local/beta/bin
                     /usr/local/jdk1.5.0/bin /usr/local/bin $path)

    Note that the location of the gcc-3.3.3 compiler must come before the 
    location of Jam since there is an old version of gcc in the same 
    directory as Jam.
    
2)  Setting your LD_LIBRARY_PATH:

    LD_LIBRARY_PATH should include the locations of the gcc-3.3.3 and
    Europa2 shared libraries. 

    On a Linux system set your LD_LIBRARY_PATH to the location of 
    gcc-3.3.3/lib for your particular system plus the full path to the 
    directory PLASMA/lib.

    On the division SPARCs running SunOS 5.8 set your LD_LIBRARY_PATH to:
    
    /usr/local/beta/gcc-3.3.3/lib 
    /home/me/PLASMA/lib

    where '/home/me' should be replaced by the full path to the
    directory containing the EUROPA checkout (presently, the CVS
    module and top level directory is named 'PLASMA', the name used
    during development).

    e.g. setenv LD_LIBRARY_PATH 
         "$LD_LIBRARY_PATH":/usr/local/beta/gcc-3.3.3/lib:/home/me/PLASMA/lib
        
3)  Setting your JAVA_HOME:

    JAVA_HOME should be set to the location of the J2SDK

    On a Linux system set JAVA_HOME to the location of the java sdk
    for your particular system. See "Setting your PATH" for help 
    finding this location. 

    On the division SPARCs running SunOS 5.8 set JAVA_HOME to:

      /usr/local/jdk1.5.0

      e.g. setenv JAVA_HOME /usr/local/jdk1.5.0

4)  Verify that gcc, Jam, Java and Doxygen are found on your system.
    Type "checkreqs" from the PLASMA directory to test for the
    correct versions. The script will offer some suggestions if the
    correct versions are not found.  Also, if you run into problems, 
    check PLASMA/System/test/autobuild, which is described briefly 
    in Appendix A.

5) Build Europa2 from the directory PLASMA by running 'jam'.
   See the "Performing a build" section below for more details.

6) Build Europa2 API documentation from the directory PLASMA/documentation
   by running 'jam documentation'.  This target will create an html
   subdirectory.  To view the documentation of the Europa2 API, bring up a
   browser on the index.html file in that subdirectory.


- Performing a build

If you run "jam" in a directory of the PLASMA tree, it will build all
files below that subdirectory, and any files in the rest of the tree
that the files in that subdirectory depend on.  This includes
libraries and test executables.

If you run "jam tests" in a directory of the PLASMA tree, it will
build and run all the tests below that subdirectory.  To build and run
all tests in the entire PLASMA tree, run "jam tests" at the PLASMA
directory.

If you run "jam clean" in a directory of the PLASMA tree, it will
remove generated files that are below that subdirectory.  To remove
generated files in the entire PLASMA tree, run "jam clean" at the
PLASMA directory.

NOTE: The default EUROPA build variant is DEV SHARED (as in
'DEV'elopment and shared libraries).  Please see below for examples of
how to set the LD_LIBRARY_PATH environment variable so the operating
system can find the EUROPA shared libraries.  Alternatively, see the
LIBRARIES configuration section.


- Configuring the build : VARIANTS

Europa2 can be built using a few variations.  The variations and
parameters of the build can be configured through environment
variables or parameters to jam.

EUROPA supports building 1 or more "variants" at the same time.  The
valid variants are:

	1. DEV - unoptimized, unprofiled, debug
	2. OPTIMIZED - optimized, unprofiled, no debug
	3. PROFILE - unoptimized, profiled, no debug
	4. CUSTOM

For example, to build an optimized build run jam like
this: (assumes bash)

% VARIANTS=OPTIMIZED jam

Or alternatively:

% jam -sVARIANTS=OPTIMIZED

The output files are named differently for each variant,
which makes it possible to build different variants at
the same time.  It is also not necessary to clean the
tree when switching variants.  Here are the naming
patterns for each of the main variants:

	DEV = <filename>_g<ext>
	OPTIMIZED = <filename>_o<ext>
	PROFILE = <filename>_p<ext>

The fourth variant, CUSTOM is a special variant which examines some
environment variables to determine the compilation flags.  These
environment variables are:

	1. EUROPA_DEBUG - use debugging
	2. EUROPA_DEBUG_MESSAGE - enable DebugMsg
	3. EUROPA_OPTIMIZED - use optimization
	4. EUROPA_PROFILE - use profiling
	5. EUROPA_WARN - use additional warnings

In the case of the CUSTOM variant, the five variables are used to
construct the name by composition.  E.g., the OPTIMIZED variant is
identical to the CUSTOM EUROPA_OPTIMIZED variant.  See the
VariantRules file for details.

The default variant is DEV, which includes EUROPA_DEBUG_MESSAGE.

To build all variants at once, see Appendix A.


- Configuring the build : LIBRARIES

The EUROPA build supports building modules as different
kinds of libraries.  The building of modules as different
kinds of libraries is also controlled through environment
variables or parameters to jam.

EUROPA supports building 1 or more library kinds at the
same time.  The valid library kinds are:

	1. STATIC - using static compile time linking (*.a)
	2. NONE - avoid using libraries (link *.o directly)
	3. SHARED - using shared compile time linking (*.so)

For example, to build without using libraries, run jam like
this: (assumes bash)

% LIBRARIES=NONE jam

Or alternatively:

% jam -sLIBRARIES=NONE

When building shared libraries, it is required to build
using position independent code, so the object files in
this case are named differently:

  SHARED = <variant>_pic.o
  STATIC/NONE = <variant>.o

Also, depending on which type of libraries are used, the
target executable names are also different.

  STATIC = <filename>[.exe]
  NONE = <filename>_no[.exe]
  SHARED = <filename>_rt[.exe]

The default library kind is SHARED.  The library kind
NONE is only recommended for situations where cyclic
dependencies exist between modules.  The library kind
SHARED is often the most space efficient.

When running with SHARED it is required to add the
EUROPA shared library directory to your library search
path.  The relevant variable depends on your platform,
and the way to set it depends on your shell.  Here is
an example for the sh and bash shells:

% LD_LIBRARY_PATH="$LD_LIBRARY_PATH":/home/me/PLASMA/lib
% export LD_LIBRARY_PATH

... where you should replace '/home/me' with the full path to the
directory containing your EUROPA checkout from CVS.

For csh and tcsh and similar shells:

% setenv LD_LIBRARY_PATH="$LD_LIBRARY_PATH":/home/me/PLASMA/lib

To build all library "styles" at once, see Appendix A.


- Getting more help

If you have difficulty with any part of these
instructions please contact the EUROPA development team
(see the README file for the address and URL).

Appendix A

The project tests building and testing EUROPA automatically overnight
using the shell script in PLASMA/System/test/autobuild via the UNIX &
Linux cron program.  See:

% System/test/autobuild -h

... for brief usage information.
