= 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
{link:Omry Yadan|mailto:omry#yadan.net} (replace # with @)

== Download
 You can get midp-build-1.0 from {link:here|http://midp-build.firefang.net/ccount/click.php?id=1} (15/05/2009)

== Initial configuration
The following steps are done once per workspace:
# Obtain build system from version control
# 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, for example:
  MIDlet-Permissions-Opt=\
  javax.microedition.io.Connector.rtsp,\
  javax.microedition.io.Connector.socket__

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 [http://antenna.sourceforge.net/wtkpreprocess.php 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[;exclude]__
where the [;exclude] is optional.

There can be multiple copy definition separated by a comma:
 __from_1;to_1;include_1[;exclude_1],from_2;to_2;include_2[;exclude_2],...,from_n;to_n;include_n[;exclude_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 [[BuildDevices]] 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 [http://www.wikicreole.org/wiki/Creole1.0TestCases this] 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__

