Building Portico

The prospect of building Portico can be a little intimidating for those unfamiliar with the layout of the repository or the basics of Apache Ant. Every effort has been made to ensure that the process of building Portico is as simple and straightforward as possible. As a result, depending on what exactly you are attempting to do, it is possible to trigger a full build with just a single, small command. This article describes the basic structure of the repository and the process required to build Portico.

Requirements
The exact requirements depend on what you are trying to build. The full list of possible requirements is outlined below, along with some information on which task the requirement relates to.

With the exception of Java, nothing is mandatory. Generally speaking, if you want to build Portico fully, you will also need a C++ compiler (GCC or VC6 are used in testing).

Note that some tasks will have a dependency on others, and those other tasks may have requirements. For example to create a full release build the unit tests need to run (and they require CppUnit).

Building Portico
The Portico build process is powered by Apache Ant. To ensure that building Portico is simple, there is no need to actually have Ant pre-installed. The Portico repository contains its own, pre-configured copy, along with helper scripts to invoke it.

The build process contains a number of build targets that control it. To run the build, you just use the supplied ant execution scripts and provide that target name. For example (where "sandbox" is the target name):

[tim@zapp:codebase]$ ./ant sandbox

You can also chain targets together, so that multiple are executed. For example, to wipe the slate clean and create an entirely fresh sandbox (as is often useful after getting the latest code with an svn update), you would issue the following command:

[tim@zapp:codebase]$ ./ant clean sandbox

The primary targets are described below:

The Two Build Halves
The build process itself is made up of two separate halves: one for the Java code (the main RTI and the Java interfaces) and the other for the C++ interface. You can tell which build targets belong to which side by checking their prefix. Targets that begin with java. belong to the java build, while targets beginning with cpp. belong to the C++ interface build.

For example, consider the following two targets compile the java and c++ interface code respectively:

[tim@zapp:codebase]$ ./ant java.compile (would compile the java code) [tim@zapp:codebase]$ ./ant cpp.compile (would compile the c++ interface code)

There may be times when you are only interested in using part of the Portico build process. For example, you may have changed some of the main RTI code and want to run the unit tests, but seeing as you haven't changed any C++ code, you don't want to run those tests (alternatively, you might not have CppUnit installed, and thus can't run the C++ unit tests). In such circumstances, you would use one of the module-specific targets:

[tim@zapp:codebase]$ ./ant java.test

For each of the primary build targets (see list above), there are java/c++ specific versions. These versions are prefixed with either java. or cpp. as appropriate.

Generating Installers
As a convenience, Portico provides a number of installer packages for various platforms. Like everything else, the generation of these installers is also controlled by the build process. It is also important to note that the build process will only attempt to build an installer relevant to the platform it is currently running on. For example, you can only build a windows installer if you are running the build on windows.

So that Ant can find the various tools it requires to build the installers there is a little additional setup that must be completed before the build will be happy:


 * CppUnit (all): You need to have CppUnit installed so that the C++ unit tests can compile and execute. See Unit Tests for more information on installing CppUnit..


 * NSIS (windows): If you want to build windows installers, you need to have NSIS installed and the  environment variable set and pointing to that install.


 * RPM Tools (linux): Building RPMs naturally requires having the RPM building tools installed.

Creating an Installer
There is a dedicated build target for creating installers. This target will go through and generate a clean release (via the  target) and then build the appropriate installer for the system it is running on:

[tim@zapp:codebase]$ ./ant installers

When the Build Fails
Each part of the build process will have its own special requirements. If your system doesn't meet those requirements, you can't run that part of the build. For example, you can't compile the C++ interface without having a C++ compiler installed (MSVC for windows, gcc for the rest). You also can't run the C++ unit tests unless you have CppUnit installed.

Obviously there is little you can do about this situation. If you don't have the required software, you can't build that part of Portico. If you happen not to care about that particular part of Portico, you could skip it by invoking a separate sequence of targets.

I don't have a C++ Compiler
You can't build the C++ interface. However, you CAN build the rest of Portico. In this case, just use the java. prefixed targets (, ,  , ...)

I don't have CppUnit Installed but I still want to generate an Installer
Running the  targets WITHOUT running through a full suite of unit tests is not advised. However, if you really don't want to run the tests (or can't, say, because you haven't got CppUnit installed), you can set the  system property.

Setting this property when running a  build will cause the build to skip the unit tests and javadoc generation (as these are the most time-consuming tasks). You use this command as follows:

[tim@zapp:codebase]$ ./ant release -Dbuild.devel=true

Someone told me to "try the latest source"
Many people wish to benefit from the bug fixes and feature enhancements that go into the Portico codebase before a new official release is made. Obviously this is something the development team encourages, as it helps us get feedback and bug reports faster.

Alternatively, from time-to-time a developer may suggest that you "try the latest source" or the "latest trunk". To build a new version of Portico from the latest code requires only two commands:


 * 1) Get the code from Subversion (or "svn update")
 * 2) Run an

This will generate a fully usable, complete Portico installation in the form of a sandbox (located in the  directory). If you want, you can just point your  environment variable at this directory and run happily as if you were using a version of Portico you got from an installer. This way, whenever you update to the latest code, you just have to run the sandbox target again.