Building Oscar

Release version: 1.0.5 - May 13, 2005

Requirements

Everything needed to build Oscar is included in the release package except the Java Development Kit (JDK) and Ant; the Oscar source code and the Ant build file are included in the src.jar file of the release package. It should be possible to build Oscar with versions 1.2.x, 1.3.x, and 1.4.x of the JDK; Oscar was developed under JDK 1.4. The JDK is freely available from Sun Microsystems.

Ant is used as the build tool for Oscar; Ant is similar to the traditional MAKE build tool, but is implemented completely in and designed specifically for Java. Ant is freely available as part of the Jakarta Ant project. Oscar was built using version 1.6.1 of Ant and requires the subant task introduced in Ant 1.6. To use Ant, install the latest version and add the Ant bin directory to your PATH variable and set your JAVA_HOME and ANT_HOME environment variables to point to the JDK and Ant install directories, respectively.

Perparing to Build

The Oscar release package is bundled with the source code necessary to build the framework itself and one example bundle. The source code is located in the src.jar file in the Oscar installation directory. If you want to build Oscar, you must unjar this file by typing the following command inside the Oscar installation directory: 

    jar xvf src.jar

Executing the above command will create the following files and directories in your Oscar installation directory (assuming that you extracted it into the installation directory as intended):

Building Oscar

Thanks to Ant, it is very easy to build Oscar using the build.xml file. As stated in the requirements section, you must have Ant installed and the necessary environment variables set for Ant to function properly. Assuming that this is the case, building Oscar and the example bundle is as simple as typing "ant". By default, the Ant build file performs the following tasks:

  1. Create a directory, called classes/, in the Oscar installation directory for containing all compiled class files.
  2. Compile all Java source files in the src/ with the class files being written to the above classes/ directory.
  3. Create a moduleloader.jar file that contains the appropriate Module Loader packages from the classes/ directory; the resulting JAR file is placed into the lib/ directory.
  4. Create an osgi.jar file that contains the appropriate OSGi packages from the classes/ directory; the resulting JAR file is placed into the lib/ directory.
  5. Create an oscar.jar file that contains the appropriate Oscar packages from the classes/ directory; the resulting JAR file is placed into the lib/ directory.
  6. Build the example bundle by invoking its build.xml.

The resulting JAR files, moduleloader.jar, osgi.jar, and oscar.jar are all placed in the lib/ directory inside the Oscar installation directory. This means building Oscar will overwrite the originally installed JAR files, so you may want to experiment on a second Oscar installation. In addition to the framework JAR files, the resulting example bundle JAR file, simple.jar, is placed in the bundle/ directory inside the Oscar installation directory.

If you want to ensure that you are rebuilding a completely fresh version of Oscar and the example bundle, you can type "ant clean" first. This will delete any artifacts from previous builds so that you know that you are starting from scratch. Cleaning will also delete the moduleloader.jar, osgi.jar, and oscar.jar files from the lib/ directory, as well as the simple.jar file from the bundle/ directory.

If you only want to build the Oscar framework and do not want to build the included example bundle or any of other bundles, then you can delete the src-bundle/ directory and only the framework will be built. On the other hand, for those interested in building other bundles or only building bundles, the next section describes how to do so.

Building Bundles

The Oscar project directory is structured such that the framework source files are completely separate from any bundle source files. All framework source code is in the src/ directory of the Oscar installation directory and all bundle source code is in the src-bundle/ directory. The goal is to make it simple to build bundles as part of the overall build process when building Oscar or to build them independently. To achieve integration in the overall Oscar build process, the main Ant build.xml file assumes that src-bundle/ contains one directory per bundle, where each bundle directory contains its own build.xml file. This allows the build process to automatically integrate any bundle projects that are placed into the src-bundle/ directory using the subant task that was introduced in Ant 1.6.

To achieve bundle independence, each bundle project contained in src-bundle/ should be completely self-contained, meaning that it should be possible to build it directly by typing "ant" in its directory, but so that it can be integrated with the main build process, each should use particular properties that can be passed in from the main build file to specify where created JAR files should be placed. The details of the bundle build.xml file is not discussed here, but can be found in the bundle repository documentation. Additionally, the bundle repository documentation also explains how to use OBR to download source code for bundles so that they can be placed into the src-bundle/ directory. Initially, only the simple/ directory for the example bundle is present in src-bundle/.

If you only want to build bundles and not the framework, then you can delete the src/ directory that was extracted from the src.jar file above. If the src/ directory is not present, then only the bundles will be built.

Feedback

For information on using Oscar, refer to usage.html. If you have comments or suggestions, feel free to contact me at heavy@ungoverned.org.

Richard S. Hall