The GUS Build System - set up
Introduction

The GUS build system is an Ant-based configuration and installation system that is used to install the GUS software and database schema. The build system is capable of tracking dependencies between related projects (for example, the PlasmoDB and AllGenes projects are separate from but depend on the main GUS project) and will install projects as necessary to satisfy these dependencies. For example, if the build system is asked to install the PlasmoDB project, it will automatically install the GUS project first (assuming that the source code for both projects has been downloaded into the user's working directory--in future the build system may be able to automate this step too.) The remainder of this document covers the steps needed to install the GUS build system and then use it to install the main GUS project.


Setting up the GUS build system

1. Check that Java is installed and your JAVA_HOME environment variable is set:
% echo $JAVA_HOME
/usr/java/j2sdk1.4.0/

If not, install the JDK and/or set JAVA_HOME accordingly. The build system has been tested on Java Standard Edition (JSE) 1.4.0 for Linux, but should work with any version of Java supported by Ant.


2. Check that Ant is installed:
% ant -help
  ant [options] [target [target2 [target3] ...]]

   Options:
     -help                  print this message
     -projecthelp           print project help information

If not, download Ant and install it according to the directions on the Ant web site. Note that the build system has been tested on Ant version 1.5.1. It is not guaranteed to work with earlier releases of Ant, because they may not support all the features required by the build system.


3. Create a directory that will house your projects:
% mkdir $HOME/projects

You may use a different name and/or location for this directory if you prefer; just make sure that you adjust the instructions in step 5 accordingly. This directory is where you will place the source code for the projects managed by the build system (including the build system itself, which is called the "install" project). The source code can either be checked out into this directory using cvs (as in step 7) or downloaded from the GUS project web site as a tar file (as in step 8.) Any files that you are developing will also be placed in this directory alongside those you have downloaded. This directory will be referred to as your PROJECT_HOME, and an environment variable of the same name will be used to record its location (step 5).


4. Create a directory from which you will run GUS and related software. This will be your GUS_HOME:
% mkdir $HOME/gus_home

As with the PROJECT_HOME, this directory can be located wherever you want, but the GUS_HOME environment variable must be set to that location (step 5.)


5. Set up your environment by placing the following in your .login or .cshrc, using the syntax appropriate for your shell (in this example we use tcsh-style syntax):
# GUS build system
setenv ANT_HOME /usr/local/pkg/ant/jakarta-ant-1.5   (i.e., where YOUR Ant is installed)
setenv JAVA_HOME /usr/java/j2sdk1.4.0/               (i.e., where YOUR Java is installed)

setenv PROJECT_HOME $HOME/projects                   (i.e., the location of YOUR PROJECT_HOME)
setenv GUS_HOME $HOME/gushome                         (i.e., the location of YOUR GUS_HOME)
setenv GUS_CONFIG_FILE $HOME/.gus.properties
setenv PATH $GUS_HOME/bin:$PROJECT_HOME/install/bin:$ANT_HOME/bin:${PATH}
setenv PERL5LIB $GUS_HOME/lib/perl

6. Make your new environment take effect by starting a new terminal session (or by using source ~/.cshrc or source ~/.login, followed by a rehash).


7. Check out the GUS and install projects from the public GUS CVS repository.
If you are a GUS developer:
% cd $PROJECT_HOME
% cvs -d :ext:cvs.sanger.ac.uk:/cvsroot/GUS co install GUS

Otherwise, go to the publicly available cvs website at http://cvsweb.sanger.ac.uk/ and follow these instructions:
    1. You should see a list of projects hosted by the CVS server. Click on the link for GUS under the heading "WebCVS Page"
    2. You should be directed to a page with links for "GUS" and "install"
    3. Follow the link named "GUS"
    4. You should see a new page that lists all the directories in the GUS project (Common, DBAdmin, GOPredict, etc.)
    5. At the bottom of this page you should see a link that says "Download this directory in tarball". Click on the word "tarball" to download the GUS project as a gzipped tar file. Unpack this tar file into your $PROJECT_HOME
    6. Use your browser's "Back" button to return to the page with the "GUS" and "install" projects
    7. Follow the link named "install"
    8. This page should also have an option to "Download this directory in tarball". Download and unpack this tarball in your $PROJECT_HOME also

Please note: future releases of the system will simplify this process for non-developers, with tar files made available in a single "download" location on the gusdb.org site.


8. Get other CBIL projects.  At a minimum you need the CBIL project (in addition to the GUS and install projects, which you should have downloaded in step 7.).  You may also get other CBIL projects as needed, but at this stage you only need the main "CBIL" project.  
If you are not at CBIL, get the CBIL project from the CBIL download site:
then install it:
% cd $PROJECT_HOME
% tar -xf CBIL-x.x.x.tar  

If you are at CBIL, get it from the internal CBIL CVS:
% cd $PROJECT_HOME
% cvs -d /ptolemy/cbil/cvs/cvsroot co CBIL


9. Set up the GUS config file:
% cp $PROJECT_HOME/install/gus.properties.sample $GUS_CONFIG_FILE
Edit the config file to reflect your personal information; this file will be read by the various GUS applications and plugins to determine such things as: which Oracle server to connect to; which Oracle logins to use for read-only and/or read-write access to the GUS database; your GUS username, default group, and default project. You may have multiple GUS config files, but will need to change your GUS_CONFIG_FILE environment variable whenever you wish to switch between them.


10. Tell the build system to install both itself (the "install" project) and also the main "GUS" project:
% build
usage:
  build AllGenes|Annotator|CBIL|DJob|DoTS|GUS|ParaDBs|PlasmoDB[/componentname]
install|installweb|package  targetDir -append [-co [version]]

% build GUS install -append

Note: the "-append" option tells the build system to continue with the installation process even if the $GUS_HOME directory already exists; this is to prevent the build system from accidentally overwriting an earlier installation.


Troubleshooting
  • I ran the command given in step 10, but it halts almost immediately with an error like this:
    "Error: You must configure the file /home/crabtree/gus_home/config/install.prop."

    This will happen whenever the build system needs configuration information from you in order to proceed. Typically the error message will tell you what action to take; in most cases you must go into a directory under your $GUS_HOME and copy a sample properties file (e.g. install.prop.sample) into a new file (e.g. install.prop). That new file should then be customized for your installation. Once that's done you can simply re-run the build command and the system should restart where it left off. If it happens again, just follow the instructions once more.



$Revision: 1.7 $ $Date: 2003/02/21 05:57:44 $ $Author: crabtree $Contact: webmaster@gusdb.org