Build

This document is structured into the following sections:

Overview
Directory Structure
build.xml
module-include.xml
module.palette
module.lexicon
Grouping Modules
devkit.properties
Using Build

Overview

The Niagara developers kit includes the build tool used by Tridium to build the framework itself. You may utilize this build tool to manage your own Niagara modules. The build tool includes the following:

The build.exe executable used to invoke the Tridium build software;
The IBM Jikes compiler is used to compile the java source files;
Every module declares a "build.xml" file to instruct the build tool how to build and package the module;
A standard directory structure is required for each module;

Directory Structure

Every module is managed in its own directory structure. Below is an example of a directory for the alarm module:

  [alarm]
    +- build.xml
    +- module-include.xml
    +- module.palette
    +- module.lexicon
    +- [src]
    |    +- [javax]
    |    |    +- [baja]
    |    |         +- [alarm]
    |    |              +- JavaClass1.java
    |    |              +- JavaClass2.java
    |    +- [com]
    |    |    +- [tridium]
    |    |         +- [alarm]
    |    |              + JavaClass3.java
    |    |              +- [ui]
    |    |                   + BAlarmConsole.java
    |    +- [doc]
    |         +- AlarmConsole-guide.html
    +- [libJar]

All of the source code which is used to build the module's jar file is located under the "src" directory. During the build process the "libJar" directory is used to build up the image which will be zipped up for the module's jar file.

build.xml

At the root of every module's directory must be a "build.xml" file. This file instructs the build tool how to build the module. An example of alarm's "build.xml" file:

<module 
 name = "alarm"
 bajaVersion = "0"
 preferredSymbol = "a"
 description = "Niagara Alarm Module"
 vendor = "Tridium"
>

  <dependency name="baja"  bajaVersion="1" />
  <dependency name="bajaui" />
  <dependency name="workbench" vendor="Tridium" vendorVersion="3.1" />
  <dependency name="history"  />

  <package name="javax.baja.alarm" doc="true" />
  <package name="com.tridium.alarm" />
  <package name="com.tridium.alarm.ui" doc="bajaonly" install="ui" />

  
  <resources name="com/tridium/alarm/ui/icons/*.png" install="ui" />
  <resources name="doc/*.*" />
</module>

The root module element must have the following attributes:

name [required]: Name of the module which should match the directory name.
bajaVersion [required]: Baja specification version number, or "0" if not a public specification.
preferredSymbol [required]: Pick a short symbol to use as a abbreviation for the module name. This symbol is used during XML serialization.
description [required]: A short description of the module's purpose in life.
vendor [required]: Vendor for the module.
install [optional]: Sets the default value of install for packages and resources. This attribute is used during provisioning to strip optional directories for headless devices. Valid values are "runtime", "ui", and "doc". The default is "runtime".
edition [optional]: Sets the default value of edition for packages. This attribute determines which Java library edition to compile against. Valid values are "j2me", "j2se", and "j2se-5.0". The default is "j2me".

Note that vendorVersion is not configured in "build.xml", rather it is defined in "devkit.properties"

Dependency Element

Use the dependency element to declare a module dependency. The dependency is required at both compile time and runtime. There are four possible attributes:

name [required]: Name of dependent module.
bajaVersion [optional]: Lowest Baja specification version required for the module.
vendor [optional]: Specifies a required vendor name for the dependent module.
vendorVersion [optional]: Specifies a required vendor version for the dependent module.

Package Element

The package element is used to declare a Java package. These elements are used for both compiling java source files as well as generating reference documentation. The following attributes are supported:

name [required]: Name of package as it would be declared in a package or import statement. There must be a corresponding directory "src/packagePath" in your modules directory structure.
doc [optional]: If declared this attribute must be either false, true, or bajaonly. The default is false. If false then no reference documentation is generated for the package. If bajaonly is specified then only BObject Types and slot bajadoc is generated. If true is specified then full Javadoc documentation is generated on all public Java classes and members. For more information see Deploying Help.
compile [optional]: If declared this attribute must be either true or false. The default is true. This allows you to declare a package for documentation, but not compile the java source code into class files during a build.
install [optional]: This attribute is used during provisioning to strip optional directories for headless devices. Valid values are "runtime", "ui", and "doc". The default is defined by module element.
edition [optional]: This attribute determines which Java library edition to compile against.Valid values are "j2me", "j2se", and "j2se-5.0". The default is "j2me".

Resources Element

The resources element is used to copy files from the "src" directories into the "libJar" directories. The following are the attributes supported:

name [required]: Name of files to copy from the "src" to "libJar" directory. The path is relative to the "src" directory and is copied to a matching directory under "libJar". You may specify an explicit filename or use wildcards such as "*.*" or "*.png".
install [optional]: This attribute is used during provisioning to strip optional directories for headless devices. Valid values are "runtime", "ui", and "doc". The default is defined by module element.

module-include.xml

The "module-include.xml" file is an optional file that is placed directly under the module's root directory with the "build.xml". If it is declared, then the build tool automatically includes it in the module's manifest file "meta-inf/module.xml" file. It's primary purpose is to allow developers to declare def, type, and lexicon elements. An example is provided:

<!-- module-include file -->
<defs>
  <def name="alarm.foo" value="something" />
</defs>

<types>
  <type name="AlarmRecord" class="javax.baja.alarm.BAlarmRecord" />
  <type name="AlarmRecipient" class="javax.baja.alarm.BAlarmRecipient" />
  <type name="AlarmClass" class="javax.baja.alarm.BAlarmClass"/>
</types>

<lexicons>
  <lexicon module="bajaui" resource="fr/bajaui.lexicon" language="fr"/>
</lexicons>

module.palette

The "module.palette" file is an optional file that is placed directly under the module's root directory. If included it is automatically put into the root of the "libJar" directory, and accessible in the module as "/module.palette". The "module.palette" file should contain the standard palette of public components provided by the module. The format of the file is the same as a standard .bog file.

module.lexicon

The "module.lexicon" file is an optional file that is placed directly under the module's root directory. If included it is automatically put into the root of the "libJar" directory. The lexicon file defines the name/value pairs accessed via the Lexicon API.

Grouping Modules

The Niagara build tool allows you to create hierarchies of modules which may be managed together. This is done through the use of grouping "build.xml" files. Let's look at an example:

<module 
 name = "drivers"
 specVersion = "1"
 preferredSymbol = "drivers"
 description = "Niagara Framework Build Driver"
 vendor = "Tridium"
>

  <submodule name="lonworks" />
  <submodule name="bacnet" />
  <submodule name="modbus" />
  
</module>

You will note that it appears very similar to a standard "build.xml" file, except that it only contains submodule elements. The submodule elements contain a single attribute name which maps to the sub-module's root directory. If the modules have inter-dependencies, then they should be listed in order of the dependencies. You may use grouping "build.xml" files to create groupings of groupings and built up projects of arbitary size and depth.

devkit.properties

The build tool uses the "home/lib/devkit.properties" file to store a couple key pieces of information:

# This property defines the master build number used for vendorVersion.
build=3.0.59

# This property defines the project's root directory where 
# the the top level "build.xml" is located.
project.home=d:/niagara/r3dev

Using Build

Once you have your directories and "build.xml" files all squared away you use "build.exe" to actually build your modules. The first argument to most build commands is the path of the module or group of modules to build. The second argument is typically the build command to execute, the default is jar.

The following command compiles and jars the module "foo" located under the project root (declared in devkit.properties):

build /foo

The following command cleans the "libJar" directory of the module contained in a directory "goop" relative to the current working directory:

build goop clean

The following command cleans all modules in the project, then rebuilds them:

build / cleanjar

Execute the following command to dump a full listing of commands and options supported by the build tool:

build -help