Development Setup

See Also: MavenInfo, wiki:Developers

Required Software

  • Cygwin (latest version)
    • For Microsoft Windows only
    • For setup details, please see CygwinSetup
  • Subversion (version 1.3 or later, version 1.4 recommended) (Online Book)
  • JDK (1.5 or later)
  • Maven (version 2.0.8+)
    • For setup details, please see MavenSetup
    • For collection of important links and information on Maven, see also MavenInfo
    • Various reports generated by mvn are very useful to glean the overall project dependencies and structure. Please see Maven Reports Page, specially the links on the right hand side table of contents for details.

Optional Software

Basic Build For the Impatient

  svn co http://svn.topazproject.org/svn/head/
  cd head
  mvn

Please see below for more info and if you plan on making any changes...

Building

  1. To build everything under head: 
      mvn clean install
    Note: if this is the first time you're building then just run mvn as the clean will fail in this case.
  2. To build the RPMs, you need to be on a redhat/fedora/centos system with rpm development tools installed. First clean out all build directories using the following command: 
    mvn clean
    Check that your source code tree is upto date and contains no surprises: 
    svn stat
    You should not see any files listed. Then rebuild everything with: 
    mvn -Ppackages,rpm
    This will produce rpm files. Use find head/packages -name '*.rpm' to find them.

Profiles

There are currently several maven profiles in use for controlling the build (profiles are enabled with '-P<profile1>,<profile2>,...'):

'packages'
enable this to build the various packages; this is in a profile because building these takes a long time and they are not usually needed during development.
'rpm'
enable this to build the rpm's; requires that the 'packages' profile also be enabled. This is in a separate profile because building rpm's only works on rpm-based linux systems.
'release'
automatically enabled when building a release.
'it'
enable this to run the ambra integration tests.
'reports'
enable this when generating reports (i.e. the running the 'site' or 'site-deploy' goals)

There are additional profiles in ambra/scripts pom.xml for running various scripts via maven - see the pom for details. For example to run RunTql.groovy using maven, use: 

mvn -Prun-tql exec:java -Dargs="-ef /tmp/example.itql" -f ambra/scripts/pom.xml

Running Ambra Locally with Embedded Mulgara and Blob-Store

The quickest and easiest way to run Ambra from your working directory is to use embedded Mulgara and SimpleBlob store instead of standalone servers for the same.

  1. Build and install everything in local repository by running this under head: 
      mvn clean install
  2. Start ambra: 
      cd ambra/webapp
  env MAVEN_OPTS="-XX:MaxPermSize=224m -Xmx128m" \
  mvn -o jetty:run \
    -Dambra.topaz.tripleStore.mulgara.baseuri=local:///topazproject \
    -Dambra.topaz.blobStore.beanName=simpleBlobStore \
    -Dambra.topaz.tripleStore.mulgara.dbDir=/tmp/ambra/mulgara_db \
    -Dambra.topaz.blobStore.simple.directory=/tmp/ambra/blob-store \
    -Dambra.services.documentManagement.ingestSourceDir=/tmp/ambra/ingest/ \
    -Dambra.services.documentManagement.ingestDestinationDir=/tmp/ambra/ingested/
    Only the first two -D... are necessary - they enable the use of an embedded mulgara and of the embedded simple-blob-store, respectively.

    The maven opts increase the default memory sizes so as to allow more restarts (there are memory leaks during the restart that cause perm gen to grow on each restart - these leaks are in 3rd-party libs and are hard to fix).

  3. Point your browser to Local Ambra and you should see the default home page.

Installing and running stuff on your local machine in the specified order

  1. To install ESUP CAS Quick Start (ecqs) single signon server:
    • mvn ant-tasks:ecqs-install
  2. To install Mulgara:
    • mvn ant-tasks:mulgara-install
  3. To install Fedora:
    • mvn ant-tasks:fedora-install
  4. To start the ESUP CAS Quick Start (ecqs) single signon server:
    • mvn ant-tasks:ecqs-start
  5. To start mulgara:
    • mvn ant-tasks:mulgara-start
  6. To start fedora (and mckoi):
    • mvn ant-tasks:fedora-start
  7. To start ambra
    • mvn jetty:run (in ambra/webapp)
  8. To stop fedora (and mckoi):
    • mvn ant-tasks:fedora-stop
  9. To stop mulgara:
    • mvn ant-tasks:mulgara-stop
  10. To stop ecqs:
    • mvn ant-tasks:ecqs-stop

Subversion Repository Design

The subversion repository is located at http://svn.topazproject.org/svn/ and can be browsed directly; to check out a working copy of the latest working code: 

  svn co http://svn.topazproject.org/svn/head/

The repository (follows the subversion guidelines) comprises of:

  • branches - Various branches to the main working code
  • head - Main working code
  • private - Private tree for developer's (sandbox)
  • tags - Tag marking various releases
  • vendor - External code/resources used by modules

Some build/run related issues

  1. Why don't the ecqs or fedora servers reflect the changes from an 'svn update' even after doing an 'mvn ant-tasks:ecqs-install' or 'mvn ant-tasks:fedora-install'?
    1. It is because, both these ant-tasks pick up the packages to install from your local maven repository (by default). Local maven repository will be updated only when you do a 'mvn install'.
  2. For the ambra project to work with ESUP CAS Quick Start, run 'mvn clean jetty:run' in the ambra/webapp directory after ESUP CAS Quick start has been installed and is running. Additionally, SSL has to be setup first on ambra. The certificate for the ambra machine has to be trusted by the CAS server. Since these are self-signed at the moment, you must import it into your local store. By default, ecqs and ambra are running on the same machine. Ambra will use the cert generated by the ecqs install process. You then just need to import that certificate into the local store, e.g. 
    keytool -import -trustcacerts
        -alias jakarta-tomcat -storepass changeit 
        -file ~/topazproject-install/esup-cas-quick-start-2.0.6-1/tmp/cert.pkcs7 
        -keystore $JAVA_HOME/jre/lib/security/cacerts
    Path to cacerts depends if you are using JDK or JRE. It could just be $JAVA_HOME/lib/security/cacerts if you're using the JRE. The default password is changeit, but you may have changed yours at some time in the past. The keytool program is typically in the bin directory of the JDK.
  3. In order for jetty to reload properly (mvn jetty:run) you need create the file src/main/resources/carol.properties in the webapp with the following contents (see also http://docs.codehaus.org/display/JETTY/JOTM ): 
    carol.start.jndi=false
carol.start.rmi=false
carol.jvm.rmi.local.call=true
carol.jndi.java.naming.factory.url.pkgs=org.mortbay.naming
    Otherwise you'll get a javax.naming.InvalidNameException: RegistryContext: can only list "".

Attachments