Prerequisites

Software Prerequisites

Building GENI-ORCA

1. Create a work directory and change into it.

$ export ORCA_SRC=$HOME/orca
$ mkdir $ORCA_SRC
$ cd $ORCA_SRC

2. Due to the difference in source tree organization:

  • For Camano 3.0+ as well as Bella 2.2 follow step 2a and then proceed to step 7.
  • For Bella 2.1 and before, follow steps 2b, 3, 4, 5, 6, 7.

2a. Retrieve the source tree in its entirety (specific tagged release or trunk)

$ svn co https://geni-orca.renci.org/svn/orca/tags/<substitute release name>/ $ORCA_SRC

or for trunk

 svn co https://geni-orca.renci.org/svn/orca/trunk/ $ORCA_SRC

2b. Retrieve the bootstrap directory from subversion.

$ svn co https://geni-orca.renci.org/svn/orca/build-all/tags/<substitute release number>/ build-all

This will create the subdirectory build-all in the current directory.

NOTE1: The above command checks out the development trunk. To get the appropriate stable release follow the instructions for the release.

NOTE2: The ORCA directory structure and these instructions support versions of subversion before 1.5, which didn't have shallow extractions. Thus some of the instructions may seem unusual to svn 1.5+ users.

3. Soft link to the build.xml file.

$ ln -s build-all/build.xml build.xml

4. Use ant to get the source.

$ ant get.all

NOTE: You may get an error message about the --trust-server-cert option. Edit build-all/helper.sh file (look for the option and remove it).

5. Prepare the source tree for building

$ ant prepare.build

Note: maven will download a large number of files. It will whine about not being able to find some where it looked first, but then it will usually find them OK somewhere else. If some of the downloads fail, please retry the command (it is safe). You need to be connected to the Internet while performing this step.

6. If this is the first time you are building orca, you will need to register the certificate of our web server, so that maven can download the necessary dependencies (our server uses https). You should omit this step if you have already installed the certificate.

The web server certificate must be installed in the keystore of your java installation. To do this, we require that you set JAVA_HOME to point to the root of your java installation. Note also that $JAVA_HOME/bin must be on the path. Please do not use Open JDK, since it has issues with its keytool implementation.

Our scripts assume that your installation's keystore is under: $JAVA_HOME/lib/security/cacerts.

Note: Mac users, your JAVA_HOME should be set to something like this: /System/Library/Frameworks/JavaVM.framework/Versions/CurrentJDK/Home

If you do not require sudo to modify your installation's keystore use the following command:

$ ant get.certificate

If this fails with permission denied errors, please try the following:

$ ant get.certificate.sudo

7. Build the whole tree and install all artifacts to the local repository (the resulting jars end up in ~/.m2/repository/)

$ mvn install

NOTE 1: maven will download a large number of files. It will whine about not being able to find some where it looked first, but then it will usually find them OK somewhere else. If some of the downloads fail, please retry the command (it is safe). You need to be connected to the Internet while performing this step. Some maven tasks will whine that they have nothing to do: that is normal.

NOTE 2: if maven fails due to a unit test in one of the modules, you can install without running unit tests like so:

$ mvn install -DskipTests

Updating and rebuilding

Periodically we may update the source code for a particular release. To update your local copy of the code you can use

  • For Bella 2.2 and after
    $ cd $ORCA_SRC
    $ svn update
    
  • For Bella 2.1 and before
    $ cd $ORCA_SRC
    $ ant up
    

After the update to rebuild ORCA as a whole use

$ cd $ORCA_SRC
$ mvn install

If you have made changes to the code or notice that an update has affected only part of the tree, you can re-build only the affected project by

$ cd $ORCA_SRC/some-affected-project
$ mvn install

Actor configuration file

As of Camano 3.0 actor configuration file can be either packaged with the webapp (by modifying the file $ORCA_SRC/webapp/actor_configs/config.xml) and then packaging and deploying from source. Alternatively you can place the actor configuration file under $ORCA_HOME/config/config.xml. When both are present ORCA first checks for $ORCA_HOME/config/config.xml and if it is not present checks for config.xml packaged in the webapp.