Midp build

Introduction

The midp-build system is a generic build system for mobile java applications developed in Eclipse. it uses the Eclipse configuration files (.classpath files) to determine project dependency, build order and build classpath automatically.

it can build any MIDlet with very little configuration.

The system supports complex builds with multiple outputs, for example - it's possible to build for several products, configurations and devices in a single run.
The build fully support preprocessing of source code based on symbols that are defined per devices, products and configurations (or almost any combination of those).
The build allow fine customization of the properties contained in the JAD for each JAR+JAD pair generated.
The build supports signing of generated MIDlets automatically
The build supports including classpath resources in the generated JAR(s), and/or copying specific resources
The build supports local builds, based on files on the workspace (without changing them in any way).
The build fully supports CVS, this includes:

Building directly from CVS
Tagging code in CVS
Checking out code to a temp directory
Building the checked out code

The build supports multiple build configurations per Eclipse project (see conf.prefix)

About

I create midp-build while I was working at Vollee, which finally cloesd it's doors a few months ago. this code is released with their approval.

the build itself is released under the BSD license.
included libraries have their own licenses, all open source (some GPL or LGPL).

Contact

Omry Yadan (replace # with @)

Download

You can get midp-build-1.0 from here (15/05/2009)

Initial configuration

The following steps are done once per workspace:

Download and extract midp-build
inside midp-build, copy example-local.properties to local.properties and edit it to match your system configuration:

Enter your workspace directory (workspace)
Enter your WTK directory (wtk.home)
Enter CVS parameters (user, password, server and repository path)

Building a single midlet

Minimal setup

This section describe the minimum steps to configure the build to build a single MIDlet inside a project called TestProject

Create a directory named build_conf inside your TestProject.
Copy ''example-build.properties'' from midp-build into TestProject/build_conf/build.properties
Edit build.properties, specifically, the MIDlet name, and the MIDlet class and the JAR name.
Run using ant -Dproject=TestProject
Output will be generated into TestProject/build/dist

If you want to use multiple build configurations with the same project, you can put the configuration files in any directory you choose, but you will need to run the build with: ant -Dproject=TestProject -Dconf.prefix=your_directory/ the trailing slash is important.

Additional JAD attributes

To add additional JAD attributes to your MIDlet, create a jad.properties file inside TestProject/build_conf/. The jad.properties file is a list of key-value lines, separated by = or :. Multiple lines values are also supported (lines ending with )

This section contains description of additional build features.

Preprocessor symbols

The build system is fully integrated with the Antenna preprocessor. to configure symbols used to preprocess your midlet create a symbols.txt file inside TestProject/build_conf/. The file is a list of preprocessor symbols, one in each line, for example:

FOO="bar"
FAST_MODE=true
SPEED=666
USE_TCP

In addition, the device name specified in the build.properties (devices=.._) also adds a set of symbols to the build.

Those symbols will be defined when the code is being preprocessed. see the documentation of the preprocessor for more information.

Copying resources

For simple midlets, it is often enough to simply include the classpath resources in the jar. this is the default behavior, and it's controller by the build.properties parameter include.cp.resources=true set to false to prevent classpath resources from getting into the output JAR.

if you want more control over what gets into the JAR, you can use the resource copy lists. there are three types of resources list the that can be defined:

res.copy.list : this is the one you will typically use. if there is an error during copying the build will fail.
optional.res.copy.list : optional, normally used to replace some resources copied by the res.copy.list. the build will not fail if there is an error.
global.res.copy.list : copied only once for the entire build. (unlike other lists which are copied once per jar/jad generated). build will not fail on error.

The build supports a flexible method of specifying which resources to copy and where to put them. A single copy definition is defined as from;to;include where the is optional.

There can be multiple copy definition separated by a comma: from_1;to_1;include_1,from_2;to_2;include_2,...,from_n;to_n;include_n

The special variables ${from_base}, ${workspace} and ${to_base} will hold the source and destination of the copy operation.

${from_base} is the directory of the project you are building.
${workspace} is the workspace root, in case you want to reference other projects.
${to_base} is the root of the generated jar file.

Another thing to note is %ScreenSize%. this is a special variable extracted from the current device properties. see ] for more information.

The following example copies all png files from YourProject/resources/graphics/RESOLUTION to the root of the jar file.

res.copy.list=
${from_base}/resources/graphics/%ScreenSize%/;
${to_base};
**/*.png

MIDlet sigining

Put your key store file inside midp-build, and edit common.properties with the relevant parameters. By default, the build signs the MIDlet it creates. to override this behavior add sign.jad=false to the build.properties file.

Release notes

The build supports a release notes file. to use it, create a release_notes.txt file inside TestProject/build_conf/. The release notes file is converted to HTML using the radeox wiki engine. See for supported syntax of the release notes.

Building multiple MIDlets in the same run

The build system multi dimentional, meaning it can build several targets in a single run. there are several "dimensions" to the build:

Devices

You can specify a comma separated list of devices in the build.properties file. For example: devices=Nokia/6280,Motrola/V6 This will create two JAR+JAD, one for each device. each device has it's own set of properties, defined in devices.xml. and that can be extended using custom_devices.xml. During the build, the symbol device is defined and contains the device currently built. this is useful to specify target directory based on the device in the build.properties file, for example: jar.path=${device}/ it can also used in the resource copy lists, to copy resources specified to a device.

in addition, all the device symbols are available in the resource lists using %SYMBOL%. (see the %ScreenSize% example).

Products and Configurations

There are two additional dimensions you can use: products=prod_1,prod_2..,prod_n configurations=config_1,config_2,...config_n each product is defined at build time in ${product} and each configuration is defined in ${configuration}.

This allows setting the generated JAR path to: jar.path=${product}/${configuration}/${device}/

Combining dimensions

It's possible to combine multiple dimensions: The following configuration: products=prod_1,prod_2 devices=Nokia/6280,Motorola/V6 configurations=qa,dev

will create JAR and JAD for the Cartesian multiplication of products, devices and configurations. since we have two of each, we will get 2*2*2=8 builds:

prod1,Nokia/6280,qa
prod1,Nokia/6280,dev
prod1,Motorola/V6,qa
prod1,Motorola/V6,dev
prod2,Nokia/6280,qa
prod2,Nokia/6280,dev
prod2,Motorola/V6,qa
prod3,Motorola/V6,dev

Overriding build options per build target ==

The build system supports a flexible method for overriding build options per build target. This is an advanced feature which is only needed for very complex builds.

Overriding order

Files are loaded in a specific order. files loaded later override file loaded before.

build.properties load order:

build_conf/build.properties
build_conf/products/${product}/build.properties
build_conf/configurations/${configuration}/build.properties
build_conf/configurations/${configuration}/${device}/build.properties

jad.properties and symbols properties are overridden in the same order:

Symbols load order:

build_conf/symbols.txt
build_conf/products/${product}/symbols.txt
build_conf/${configuration}/symbols.txt
build_conf/devices/${device}/symbols.txt
build_conf/${configuration}/${device}/symbols.txt

JAD properties load order:

build_conf/jad.properties
build_conf/products/${product}/jad.properties
build_conf/${configuration}/jad.properties
build_conf/devices/${device}/jad.properties
build_conf/${configuration}/${device}/jad.properties

Overriding per device

To override symbols or JAD attibutes per device, create a devices directory under your build_conf directory. in it, create a directory per device you want to override, for example: build_conf/devices/Nokia/6280 __build_conf/devices/Motorola/V6__ and put symbols.txt and/or jad.properties in the directory (in this case, in 6280 and V6). the symbols and jad properties will override those of the entire build when the specific device is built.

Overriding per product/configuration

to override symbols.txt, jad.attributes and even build.properties per product, create a directory directory under your build_conf directory. in it, create a directory per product you want to override, for example: build_conf/products/prod1 __build_conf/products/prod2__'

similarly, you can override per configuration: build_conf/configurations/dev __build_conf/configurations/qa__'

Note that it's possible to override the devices variable per products or configurations! this allow you to define a different set of devices to build per product (useful to build for specific devices per carrier).

Overriding per configuration AND device

it's possible to override specific build options per specific devices only in specific configurations. only jad.properties and symbols can be overridden in this manner. for example:

build_conf/configurations/dev/Nokia/6280
build_conf/configurations/dev/Motorola/V6