Cosmo Sharing Server 0.2
                               Build Instructions


   Copyright 2005 Open Source Applications Foundation

   Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
   You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.


SETUP
=====

To set up your environment for Cosmo development, perform the
following steps:


(1) If your operating system does not already provide it, download and
    install a Java Runtime Environment (version 1.4 or later)

    * Download a JRE release from

        http://java.sun.com/j2se/

    * Install the JRE according to the instructions included with the
      release.

    * Set an environment variable JAVA_HOME to the pathname of the
      directory into which you installed the JDK release.

(2) If your operating system does not already it, download and 
    install the Maven build tool (version 1.0 or later, but NOT 2.0)

    * Download a Maven release from:

        http://maven.apache.org/

    * Install Maven according to the instructions included with the
      release.

    * Set an environment variable MAVEN_HOME to the pathname of the
      Maven installation directory.

    * Add $MAVEN_HOME/bin to your PATH.


SOURCE CODE
===========

Find instructions for accessing the Subversion repository at the Cosmo
home page (search for "Source Code Access"):

    http://wiki.osafoundation.org/bin/view/Journal/CosmoTempHome


BUILD
=====

The project descriptor is project.xml in the root directory of the
module. Additional build instructions are found in maven.xml. Default
build properties are set in project.properties. You can customize your
build by providing a build.properties file in the same directory (see
CUSTOMIZE below).

The most commonly-used goals are:

  build                compile and test all source code
  clean                remove all compiled source code and helper files
  test                 run all tests
  dist                 package the distribution
  dist-clean           remove the distribution package and helper files

All generated files are placed into the target/ subdirectory.

The build depends on several libraries from the OSAF commons
project being installed into your local Maven repository. See the OSAF
Server Commons home page for more information:

    http://wiki.osafoundation.org/bin/view/Journal/ServerCommonsTempHome


TEST
====

There aren't too many tests yet, but those that exist can be run with
'maven test'. Before doing so, however, you will need to initialize the
test database with 'maven test:dbsetup'.

If you want to build or package cosmo without running the tests (often
useful when making small incremental changes to the user interface),
you can run 'maven -Dmaven.test.skip=true build' (or whichever goal).

JUnit writes detailed test output in XML format to
target/test-reports/. This, and the brief console output it generates
should be more than enough to debug test failures.


RUN
===

'maven dist' creates a dist/ subdirectory containing an unpacked
distribution (cosmo-x.x/). You can run Cosmo right out of this
directory with 'dist/cosmo-x.x/bin/cosmoctl start'. See INSTALL.txt
for more details on running Cosmo.


RELEASE
=======

'maven dist:release' creates a packaged distribution of the Tomcat
bundle at dist/cosmo-x.x.tar.gz. A separate unbundled WAR file will
come in a future version.


CUSTOMIZE
=========

All of the following customizations are placed in build.properties,
overriding the properties set in build.properties.

Some common development customizations:

    maven.compile.debug=on
    maven.compile.deprecation=on
    maven.compile.optimize=off
    cosmo.webapp.reloadable=true
    cosmo.serverAdmin=<me@my.host>

Maven downloads a copy of Tomcat to package the bundled
distribution. You can override the following properties to specify
your favorite mirror and/or choose a different version of Tomcat (but
beware the latter - see the compatibility notes in README.txt):

    ext.tomcat.package=jakarta-tomcat-5.0.28
    ext.tomcat.url=http://www.ibiblio.org/pub/mirrors/apache/jakarta/tomcat-5/v5.0.28/bin/${ext.tomcat.package}.tar.gz


$Id$