Building BASE from source code
1. Getting the source code
Download
The source code for most BASE releases can be downloaded from the DownloadPage. The code is packaged in a compressed TAR archive. Unpack this to a directory of your choice.
Subversion
The BASE source code lives in a Subversion server. It is a versioning system that enables us to keep track of all changes made to the code. You will need a client for subversion to be able to get the source code. If you are using Eclipse there is an excellent subversion plugin.
Check out the source code with the command:
svn checkout https://base.thep.lu.se/svn/trunk/ base-src
This will create a sub-directory base-src
with all source files. Anonymous checkouts are allowed, but write permission is only granted to developers. The trunk version is the head of the development and should be used for testing purposes only. The sub-urls to https://base.thep.lu.se/svn/branches/*
and https://base.thep.lu.se/svn/tags/*
can be used to get other version, including specific releases and bugfix branches. For more information see the DownloadPage or check the subversion source repository directly.
2. Create a local configuration
The configuration files included with a binary distribution are located in the <base-src>/config/dist
directory. You should never modify these files directly for your local setup. Instead, place a copy of files that you need to modify in the <base-src>/config/local
directory. When building BASE all targets exception the 'dist' target will first check the local configuration files.
Note that the build process usually copies the configuration files to the <base-src>/www/WEB-INF/classes
directory. The reason is that Tomcat can't read files outside the WEB-INF
directory and this makes the subversion working copy identical to a binary distribution.
- All utility programs, such as the installation program and the job agent, use the configuration files in
<base-src>/www/WEB-INF/classes
. - The only exception is the test programs. They will read the configuration from
<base-src>/config/local
and<base-src>/config/dist
directories. - Running
ant clean
will remove the copied configuration files.
3. Ant
We use Ant to build and compile BASE. We recommend Ant 1.10. All build instructions for Ant are in the build.xml file.
A build is started with the command:
ant <target>
where <target>
is one of the named targets defined in the build file. You may specify multiple targets:
ant web jobagent
All <property>:s defined in build.xml
can be overridden by creating a file build.properties
and adding white-space separated key-value pairs with new property values. It is, for example, needed to set tomcat.home
to the path to a Tomcat installation in order to check that JSP file compile. See below and #2151 for more information.
Main build targets
These targets works on the entire BASE source code. They may take some time to finish, but everything will be checked and recompiled if needed.
ant dev
Build everything for local use. This targets compiles the core, plugins, web application, job agent, etc. for local use. It doesn't generate javadoc documentation.
ant dist
Build everything for distribution. This target compiles everything, generates the javadoc documentation, etc. Everything is placed in the dist subdirectory.
ant package
Create compressed tar files of the distribution.
ant clean
Remove all generated files.
Other useful targets
These targets are quicker to use if you know that you have only made changes to a specific module.
ant core
Compile the core for local use.
ant coreplugins
Compile the core plugins for local use.
ant web
Compile the web client application for local use.
ant installprg
Compile the installation programs for local use.
ant jobagent
Compile the job agent for local use.
ant test
Compile the test programs for local use.
ant doc
Generate documentation for local use. This generates all documentation and may take a long time.
ant doc.javadoc
Generate Javadoc documentation only. The documentation is generated in the
<base-src>/doc/api
directory.
ant doc.docbook.html
Generate user- and administrator documentation from docbook in HTML format. Docbook will work with pure Java but performance is better if XSLTPROC is installed. The documentation is generated in the
<base-src>/doc/html
directory.
Pre-compiling JSP pages
This should be performed at regular intervals and at least before a new minor release. You need to have Tomcat installation that includes the build tools. If the ${tomcat.home}/bin/catalina-tasks.xml
file is present then you have the correct version. If not, we recommend that the ZIP distribution is downloaded and unpacked to some place. It can be anywhere, you will not have to run an actual Tomcat instance from there.
Create a build.properties
file in your root BASE development directory (=same directory where build.xml
is located). Add a tomcat.home
entry that points to the directory where the Tomcat installation is located. The JSP files can then compiled by:
ant jsp
The goal is that this should compile without errors or warnings. Warnings can be controlled by the Xlint
parameter. It is by default set to Xlint:all,-serial
. The -serial
option is needed since Jasper doesn't create serialVersionUID
fields in the generated code. The Xlint
parameter can be customized by setting the jsp.xlint
property in the build.properties
file (only the part after Xlint:
). For example:
jsp.xlint all,-serial,-unchecked,-rawtypes,-deprecation,-cast
Running BASE from the local installation
If you have followed the instructions so far the subversion working copy installation is compatible with a binary distribution. You can find the installation programs, web application and all other things in the same places as for a binary installation. Read the installation instructions for more information.