HomeDownloadsUser GuideDevelopment

Development: Setup

This document describes how to set up a local development copy of the project directory.

Starting Out

Development setup is a three step process:

  1. Repository check out.
  2. Build environment configuration.
  3. Initial build.

Repository Check Out

First, check out the sources from the SVN repository.

Anonymous Subversion Access:

svn checkout https://svn.forge.osor.eu/svn/openpermis/trunk/openpermis

Developer Subversion Access:

svn checkout --username ${USER} https://svn.forge.osor.eu/svn/openpermis/trunk/openpermis

Alternatively you may of course also use a graphical SVN client or use the SVN repository browser of your favourite IDE (the project repository already contains preconfigured settings for Eclipse).

Build Environment Configuration

The OpenPERMIS build environment is Ant based. However, instead of relying on your installation of Ant (which may or may not be the correct version) the OpenPERMIS project comes with a bundled version of Ant that includes all the extensions necessary for the build.

All that you need to install/provide in order to build OpenPERMIS is a JDK >= 5.0.

Always use the bundled build script to invoke build commands instead of your local version of ant in order to avoid conflicts!

Due to the fact that Ant always has to be configured and enriched by additional libraries a complete Ant runtime environment is included in the project directory. To start the bundled Ant version there is a script in the top level directory of the project (build.sh for Unix / Mac OS X and build.cmd for Windows). This script is not named ant to prevent naming conflicts with other versions of Ant that might already be installed on your system.

In the following all files mentioned are listed relative to the toplevel directory of the project directory. Also, all build commands should be executed from the toplevel directory of the master module.

Site and User Specific Configuration Files

To keep site and user specific information out of the build process the build tools use the following configuration files:

env
site.sh
Unix / Mac OS X only
site.xml
Windows only
user.xml

The build script first imports the site specific configuration file and then launches ANT which in turn imports the following files:

build.xml > env/user.xml > env/site.xml

Thus, the user configuration overrides the site configuration which in turn overrides the default values.

To create and/or configure the site and user specific configuration files refer to the sections Semi-automated Setup or Manual Setup below.

Semi-automated Setup

There is a small setup script which will help you conduct the steps outlined in the manual setup section below. In the toplevel directory execute:

On Unix / Mac OS X:

sh build.sh setup ${USER} ${SITE}

or on Windows:

build setup %USER% %SITE%

Where ${USER} or %USER% denotes your username and ${SITE} or %SITE% represents the name of the site or your computer.

If there is already an existing configuration for this user and sitename then the environment files are linked or copied, otherwise a new set of configuration files are created and placed in the env/configuration folder.

You should adjust the contents of newly created configuration files in the env/configuration folder and execute build setup again once you are done editing.

Once the configuration files are in place and the site specific path to the JDK >= 5.0 is set proceed to perform the Initial Build.

Manual Setup

If you want to prepare the setup manually perform the following steps:

  1. The Ant startup script build.sh (Unix / Mac OS X) or build.cmd (Windows) includes another script (env/site.sh on Unix / Mac OS X or env/site.cmd on Windows) that has to set the site specific path to a JDK >= 5.0 installation and to set an appropriate path that includes libraries and binaries used. Make a link (on Unix / Mac OS X) or a copy (on Windows) to one of the existing confiuration/site_*.sh or confiuration\site_*.cmd files.

  2. The build file for Ant includes also the configuration file env/site.xml. Since this file is sourced right after the user specific file env/user.xml (see above), it is possible to overwrite all properties here that have not been specified in the user specific file. Additional tasks can also be defined in this file. Make a link (on Unix / Mac OS X systems) or a copy (on Windows systems) to one of the existing configuration/site_*.xml files.

  3. The build file for Ant includes the configuration file env/user.xml. Since this file is sourced first, it is possible to overwriteall properties here for a certain user. Additional tasks can also be defined in this file. Make a link (on Unix / Mac OS X systems) or a copy (on Windows systems) to one of the existing configuration/user_*.xml files.

Commands to execute on Unix / Mac OS X:

cd env
ln -s configuration/site_${SITE}.sh site.sh
ln -s configuration/site_${SITE}.xml site.xml
ln -s configuration/user_${USER}.xml user.xml

or on Windows:

cd env
copy configuration\site_%SITE%.cmd site.cmd
copy configuration\site_%SITE%.xml site.xml
copy configuration\user_%USER%.xml user.xml

Windows Tip: Always modify the files in the configuration directory if you want to check-in the changes and the run the setup command again.

Initial Build

Some portions of the documentation (API documentation and some other HTML pages) are generated automatically. So your initial setup process should build this documentation in the next step. But also after a later update it is good practice to proceed with the next step to ensure that everything is correctly (re-)built.

To create all generated sources and documentations and to compile all parts of the project the build tool build.sh (Unix / Mac OS X) or build.cmd (Windows) has to be started with the target world.

On Unix / Mac OS X:

sh./build.sh world

or on Windows:

build world

Unix / Mac OS X Tip: Make the build script executable if it isn't already (e.g. using chmod a+x ./build.sh) and create an alias for it using alias build 'sh ./build.sh'. Now you can execute build targets simply by issuing commands like build world.

After all these steps all parts of the whole project is built and the documentation should be complete.

The targets of the master build file are listed on the Build Environment page (this page is only avaible once build world has been run).