SMILA/Documentation/HowTo/Howto build a SMILA-Distribution

Build Requirements

Text file encoding has to set to UTF-8.
Steps to provide UTF-8 text file encoding: Window --> Preferences --> General --> Workspace --> choose UTF-8 under Other

Our build process needs ant-contrib to build SMILA application. It is not included in the trunk. You may download it from: ant-contrib.

Furthermore our build process may generate reports for checkstyle, emma and pmd. To generate these reports you need special files. These files are also not included in the svn trunk. To generate these reports you may download these files from: checkstyle emma pmd. The base location for these files and the ant-contrib is lib and has to be located in the trunk directory. This folder structure is recommanded. See below:

lib/
   ant-contrib/
       ant-contrib-1.0b1.jar
   checkstyle/
       checkstyle-all-4.3.jar
   emma/
       emma.jar
       emma_ant.jar
   pmd/
      asm-3.1.jar
      jaxen-1.1.1.jar
      pmd-4.1.jar

By default the configuration of the build process is developed to run the build with and without these dependencies (exception: ant-contrib is always required). If you don´t include these dependencies during build process, reports for checkstyle, emma and pmd won´t be generated.

After downloading files you have two possibilities to include these files into the build process:

1. Create a folder structure like above in the trunk directory
2. Create a folder structure like above anywhere on your hard disk (e.g. d:\lib) and pass the location via -Dlib.dir paramater to the build process (e.g. -Dlib.dir=d:\lib).

Configuring the Build

The folder SMILA.builder contains everything needed to build SMILA and/or run all tests locally. The default settings are set to build against eclipse 3.4.1 and build a product for Win 32bit and Linux 32bit. But it is also possible to build other platforms.

Whether you build from command line or from eclipse, in both cases the make.xml ant script is executed. Before execution certain properties need to be set to meet the local setup.

Setting the Target Build Platform

Independent of which way you are going to build, you must set the configs property in the build.properties file to your setup.

Windows 32bit	... configs=win32,win32,x86 # ...
Windows 64bit (only provided by eclipse 3.4 and higher)	... configs=win32,win32,x86_64 # ...
Linux 32bit	... configs=linux,gtk,x86 # ...
Linux 64bit	... configs=linux, gtk, x86_64 # ...
Solaris SPARC	... configs=solaris, gtk, sparc # ...

If you want to provide several distributions e.g one for windows 32bit and one for linux 32bit (default build plan), you have to string together the config values.

Example:	configs=win32, win32, x86 & \ linux, gtk, x86

Note:
The default is to build for both, windows and linux platforms. However, for this to work locally the eclipse must have the corresponding plugins installed which is usually not the case if you downloaded a 
platform specific distribution. If platform plugins are missing you will end up on Windows with:
 
 
[java] D:\Program Files\eclipse33\eclipse-SDK-3.3.2-win32-smila-build\eclipse\plugins\org.eclipse.pde.build_3.3.2.v20071019\scripts\genericTargets.xml:85: Unable to find plug-in: 
org.eclipse.core.filesystem.linux.x86_0.0.0. Please check the error log for more details.

Setting Build Properties

Property	Default	Comment
buildDirectory	<SMILA_HOME>/eclipse.build
eclipse.home	<ECLIPSE_HOME>	the location of the eclipse instance used to build smila
builder	<SMILA_HOME>/SMILA.builder
eclipse.running	true
pdeBuildPluginVersion	3.4.1.R34x_v20080805 (for 3.4.1)	3.3.2.v20071019 (for 3.3.2) to change the value go to build.properties file in folder SMILA.builder
equinoxLauncherPluginVersion	1.0.101.R34x_v20080819 (for 3.4.1)	1.0.1.R33x_v20080118 (for 3.3.2) to change the value go to build.properties file in folder SMILA.builder
os	win32	these merely control under which platform the test will run. It must be one of the target platforms you have build.
ws	win32
arch	x86
test.java.home	<JAVA_HOME>	a java 1.5 SDK instance

For the build from eclipse you pass in these values via the command line text box in the launch config on the command line these are set in a shell script.

Executing the make.xml

all dependency graph

The default target is all. This will by default build the application and run all unit tests. The dependency graph will explain what will happen and shows the relevant targets you may call instead.

Executing make.xml from within eclipse

Steps:

1. set up devolopment environment see: How to set up dev environment
2. select the SMILA.builder bundle
3. open External Tools Dialog
4. create a new ant build configuration or choose your configuration if exists
5. choose the build file of this bundle, e. g. ${workspace_loc:/SMILA.builder/make.xml}
6. insert all properties from above into the arguments input field (but adapt these to your setup) but prepend each with -D so each is passed into ant as a property, e.g.

   -DbuildDirectory=D:/eccenca/SMILA/eclipse.build

   -Declipse.home=D:/eclipse33

   -Dbuilder=D:/eccenca/SMILA/SMILA.builder

   -Declipse.running=true

   -DpdeBuildPluginVersion=3.4.1.R34x_v20080805

   -DequinoxLauncherPluginVersion=1.0.101.R34x_v20080819

   -Dos=win32 -Dws=win32 -Darch=x86

   -Dlib.dir=D:/eccenca/SMILA/lib

7. Apply, close and run SMILA.builder with this external tool configuration

Note:
To start another than the default target specify the desired target also in the argument input box.

Executing make.xml from command line

The make.bat (or .sh) is just a shell script to set the properties that are needed for the ant script. These files exist only as templates in SVN with .#~#~# appended to denote their template nature. Rename it as u see fit, but make.bat (.sh) is already in the svn:ignore to prevent it from beeing committed accidentally, so it is recommended to use that.

Steps:

1. adjust all paths in \SMILA.builder\make.bat according to own setup
2. execute make.bat

Note:
To execute another than the default target just pass it as an argument, like so:
make build