---

Cosmo Build Instructions

---

Initial setup

These instructions help you set up your platform for hacking on OSAF's Java server projects. These projects utilize specific versions of particular Java tools. Only use the versions that are explicitly listed here. Using other versions will likely cause problems that we might not know how to help you solve.

Java SDK

If your operating system does not already provide it (try running java -version and/or echoing $JAVA_HOME), download and install a Java SDK (only use version 1.5 which is labeled as "5.0" on Sun's site):

1. Download a J2SE SDK release from http://java.sun.com/j2se/
   • Windows or Linux: the 1.5 SDK is available at http://java.sun.com/j2se/1.5.0/download.jsp -- don't get the NetBeans^? edition, get "JDK 5.0 Update n"
   • Mac: find Apple's version of the SDK at http://www.apple.com/support/downloads/java2se50release3.html
2. Install the J2SE SDK according to the instructions included with the release.
3. Set an environment variable JAVA_HOME to the pathname of the directory into which you installed the J2SE SDK release.
4. On Mac, you may have to change the symlink for /System/Library/Frameworks/JavaVM.framework/Versions/Current (and CurrentJDK) to the 1.5.x version of the JDK.

Maven

If your operating system does not already provide it (try running mvn -v), download and install the Maven build tool:

1. Download Maven 2.0.4 from http://maven.apache.org/download.html
2. Install Maven according to the instructions displayed at the bottom of the download page.

Get the source code

• read-only: svn co http://svn.osafoundation.org/server/cosmo/trunk cosmo
• read-write: svn co svn+ssh://svn.osafoundation.org/svn/server/cosmo/trunk cosmo

See SubversionGuidelines for more information about OSAF's Subversion repositories.

Build the app

Cosmo and it's various parts are built using Maven v2.0.4

Compiling Cosmo

The source for Cosmo can be found within the cosmo/ sub-project directory. Cosmo is a Tomcat web application so when it is "built" what is generated is either an inplace debugging target or a war file used to install into a Tomcat container. At anytime if you want to force Maven to update the SNAPSHOT jar files, use the -U option. This is needed because, by default, Maven 2 will only check for updates once a day.

To build the inplace debugging target, do the following:

• cd cosmo/
• mvn clean compile war:inplace

This will cause the various webapp pieces to be inserted into the src/main/webapp/ part of the Cosmo source tree.

To generate the Cosmo war file, do the following:

• cd cosmo/
• mvn package

You will now find a Cosmo-*.war file located in the target/ sub-directory.

You can remove all of the compiled source code and generated helper files with mvn clean.

Running Cosmo unit tests

• cd cosmo/
• mvn test

Detailed test output is generated in text and XML format to target/surefire-reports. This, and the brief console output it generates, should be more than enough to debug test failures.

You can run a single test by specifying the name of the test class as a command line option: mvn -Dtest=DavMkTicketTest test

Building Snarf

Snarf is the short, fun name for the "OSAF server bundle", which is essentially a Tomcat servlet engine pre-configured to run Cosmo. The Snarf source is located in the snarf/ sub-project directory. There's no actual Java code, so you don't have to worry about compiling or testing anything.

To generate a tarball of Snarf, which contains Tomcat and the Cosmo war file bundled together:

• cd snarf/
• mvn package

Snarf can also be generated in a form that makes debugging easier for a developer doing web-side UI work. To do this we need to tell Maven to generate an "exploded" directory:

• cd snarf/
• mvn assembly:directory

This creates in the dist/ directory a working image of what would be bundled. Due to the oddities of Maven, you will see the project name listed twice in the directory structure, e.g. dist/osaf-server-bundle-0.6-SNAPSHOT/osaf-server-bundle-0.6-SNAPSHOT/

Starting Snarf

Now you can run the server with bin/osafsrvctl start. You will want to check logs/osafsrv.log to make sure the server started correctly. You should see messages like this (along with some interspersed debug messages):

2006-11-02 13:43:29,418 INFO  [LifecycleLoggerListener] Cosmo Sharing Server 0.6-SNAPSHOT starting
2006-11-02 13:43:40,852 INFO  [DbInitializer] Creating database
2006-11-02 13:43:43,482 INFO  [DbInitializer] found schema version 0.6-SNAPSHOT
2006-11-02 13:43:43,531 INFO  [DbInitializer] Initializing database
2006-11-02 13:43:46,406 INFO  [Catalina] Server startup in 17896 ms

Now point your browser at http://localhost:8080/. If all has gone well, you will see a welcome page with a link to sign up for a Cosmo account. The base URL for Cosmo is http://localhost:8080/cosmo/.

See the server bundle Administrator's Guide for more details on running the server.

Using a relational database back-end

Using MySQL

If you want to develop against a MySQL 5.x database server rather than the default embedded Derby database, do the following:

1. Create a new database ("cosmo" for instance) in your database server. Make sure the default charset is utf8.
2. Edit $OSAFSRV_HOME/etc/cosmo.properties and change the property cosmo.hibernate.dialect to org.hibernate.dialect.MySQL5InnoDBDialect.
3. Edit $OSAFSRV_HOME/tomcat/conf/Catalina/localhost/chandler.xml, comment out the <Resource> definition for the Derby datasource, and uncomment the example <Resource> definition for the MySQL datasource. Set the datasource properties to match your database server.
4. Start Cosmo and the database schema will automatically be created the first time.

Using PostgreSQL

If you want to develop against a PostgreSQL 8.2 database server rather than the default embedded Derby database, do the following:

1. Create a new database ("cosmo" for instance) in your database server. Make sure the default charset is utf8.
2. Download the latest PostgreSQL JDBC 3 driver from http://jdbc.postgresql.org/download.html and copy to =$OSAFSRV_HOME/tomcat/common/lib.
3. Edit $OSAFSRV_HOME/etc/cosmo.properties and change the property cosmo.hibernate.dialect to org.hibernate.dialect.PostgreSQLDialect.
4. Edit $OSAFSRV_HOME/tomcat/conf/Catalina/localhost/chandler.xml comment out the <Resource> definition for the Derby datasource, and uncomment the example <Resource> definition for the PostgreSQL datasource. Set the datasource properties to match your database server.
5. Start Cosmo and the database schema will automatically be created the first time.

Hack some code

You are now set up to write code. You will probably want to observe code changes in the browser or at the command line very frequently. How you do this depends on what code you're modifying:

• If you make a change to a JSP, you should be able to reload the corresponding web page and observe the change in your browser without any further steps.

• If you make a change to a Java class or to a configuration file, you'll need to run maven war:inplace again (probably with -Dmaven.test.skip=true so that you skip the unit tests). Because you made the webapp reloadable, Tomcat will automatically sense the recompiled class or modified config file and will redeploy the webapp after a few seconds. You can see it doing this by watching $OSAFSRV_HOME/logs/osafsrv.log and looking for the startup message (the timestamp should be more recent than when you ran maven war:inplace).

Generate a release

There's a lot more to making a Cosmo release than just building a binary package. See CosmoReleaseProcess for more information.

Customize your build

Needs to be updated

Note: The following was valid when Cosmo was being built using Maven 1 but now with Maven 2 the property names and values reside in ~/.m2/settings.xml and the following has not been updated.

All customizations are made in build.properties, overriding those properties set in project.properties.

Some common development customizations:

• maven.compile.debug=on
• maven.compile.deprecation=on
• maven.compile.optimize=off

Maven downloads Tomcat 5.5.17 to build the snarf package. You can override the following properties to specify your favorite mirror and/or choose a different version of Tomcat:

• ext.tomcat.package=apache-tomcat-5.5.17
• ext.tomcat.url=http://downloads.osafoundation.org/cosmo/${ext.tomcat.package}.zip

Using the release-mode packed dojo.js

NOTE: The dojo step requires that ant be installed and available. On Ubuntu you can use apt-get install ant ant-optional

Normally during the edit/compile/test dev cycle the uncompressed dojo.js file is used so any javascript references for cosmo are pulled from the source tree, but if you are not working on the javascript side you may want to use the compressed dojo.js

• cd dojo
• mvn -Prelease install

This will generate the dojo jar file using the compressed bits. The next time you compile/test cosmo use the -U command line option with Maven to force it to update the jar dependency. Or to really force it, delete the ~/.m2/repository/org/osaf/cosmo/dojo directory tree before you build the release-mode dojo jar.

To verify you are using the proper jar, when you next do a mvn war:inplace grep for "cosmo" in the dojo.js file - if it worked you will see results.

Dependencies

Cosmo is built on top of many external frameworks, libraries, and tools. Most are pulled straight from Ibiblio's Maven repository (or a mirror), but some are found in OSAF's Maven repository which contains dependencies that we build ourselves or which aren't found on Ibiblio.

QA Test Builds

• cd latest
• ./bin/osafsvctl stop
• cd ../cosmo_0.6.1
• svn up
• cd cosmo
• mvn -Prelease clean
• mvn -Prelease package
• cd ../snarf
• mvn -Prelease clean
• mvn -Prelease package
• cp dist/osaf-server-bundle-0.6.1-tar.gz ../../
• tar xzf osaf-server-bundle-0.6.1.tar.gz
• rm -f latest
• ln -s osaf-server-bundle-0.6.1 latest
• cd latest
• ./bin/osafsvctl start