Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Difference between revisions of "SMILA/Documentation/HowTo/Howto build a SMILA-Distribution"
m (New page: ==== Build Requirements ==== Text file encoding has to set to UTF-8. <br/> Steps to provide UTF-8 text file encoding: '''Window''' --> '''Preferences''' --> '''General''' --> '''Workspace...) |
|||
Line 1: | Line 1: | ||
==== Build Requirements ==== | ==== Build Requirements ==== | ||
− | + | The build process uses Eclipse's PDE Build tools to build all the bundles, run all unit tests and create an ZIP archive with a complete SMILA application that can be installed and run independently from any development environment. To run this build process, you should first install the following software. | |
− | + | ||
− | + | * Eclipse SDK 3.4.x for your operating system: We recommend installing a second Eclipse instance independently from the one you are using as your IDE so that additional installed Eclipse plugins you use in your work do not interfere with the build process (this shouldn't happen, usually - but just to be safe). You can find the download on [http://download.eclipse.org/eclipse/downloads/]. This How-to was tested with [http://download.eclipse.org/eclipse/downloads/drops/R-3.4.2-200902111700/index.php Eclipse Classic SDK 3.4.2]. | |
− | + | * DeltaPack matching your Eclipse version: The DeltaPack contains some additional bundles needed in the build, mainly for creating the SMILA executable for different platforms. You'll find the download on [http://download.eclipse.org/eclipse/downloads/ http://download.eclipse.org/eclipse/downloads/]. Install it by unpacking it into you Eclipse SDK installation. This How-to was tested with [http://download.eclipse.org/eclipse/downloads/drops/R-3.4.2-200902111700/download.php?dropFile=eclipse-3.4.2-delta-pack.zip DeltaPack 3.4.2]. | |
− | + | * Sun Java Development Kit: You need a full JDK to build SMILA, not just a JRE. Both versions 5 and 6 should work, but we tested the How-to with [http://java.sun.com/javase/downloads/index_jdk5.jsp JDK 5.0] | |
− | + | * Apache Ant: The build process is executed by Ant, which you can download here: [http://ant.apache.org/]. At least version 1.7 is needed (and tested). | |
− | + | * Additional Libraries for building which are not included in SMILA repository. The build scripts assume the following directory structure for these libraries. You can either create this structure in your working copy of the SMILA repository next to all the SMILA bundles, or somewhere else on your hard disk and configure the build process to find them there (see below). | |
<source lang="text"> | <source lang="text"> | ||
lib/ | lib/ | ||
ant-contrib/ | ant-contrib/ | ||
− | + | ant-contrib-1.0b1.jar | |
checkstyle/ | checkstyle/ | ||
− | + | checkstyle-all-4.3.jar | |
emma/ | emma/ | ||
− | + | emma.jar, emma_ant.jar | |
− | + | ||
pmd/ | pmd/ | ||
− | asm-3.1.jar | + | asm-3.1.jar, jaxen-1.1.1.jar, pmd-4.1.jar |
− | + | ||
− | + | ||
</source> | </source> | ||
− | + | ** ant-contrib: This is required to run the build. You may download it from: [http://sourceforge.net/projects/ant-contrib ant-contrib]. | |
+ | ** Furthermore our build process optionally generates reports for checkstyle, emma (code coverage) and pmd (static code analysis) if these libraries are present. To generate these reports you may download these files from: [http://checkstyle.sourceforge.net/ checkstyle] [http://emma.sourceforge.net/ emma] [http://pmd.sourceforge.net/ pmd]. The build is configured to run without these libraries and will just not create the respective reports, but everything else will be OK. | ||
+ | ==== Configuring the Build ==== | ||
− | |||
− | |||
− | |||
− | |||
− | |||
The folder <tt>SMILA.builder</tt> 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. | The folder <tt>SMILA.builder</tt> 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. | ||
Line 77: | Line 70: | ||
{| | {| | ||
− | ! Example: | + | ! Example: 0 |
| {{Codeblock|<pre> | | {{Codeblock|<pre> | ||
configs=win32, win32, x86 & \ | configs=win32, win32, x86 & \ | ||
Line 83: | Line 76: | ||
}} | }} | ||
|} | |} | ||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
</source> | </source> | ||
===== Setting Build Properties ===== | ===== Setting Build Properties ===== | ||
− | {| border="1 | + | These are the main properties that can be used to configure the build process executed by <tt>make.xml</tt>. If you run the build from Eclipse you must add them to the Ant launch configuration, |
+ | for running from command line we have included templates that you can adapt to your local setup. | ||
+ | |||
+ | {| border="1" cellspacing="0" cellpadding="5" valign=top | ||
! Property !! Default !! Comment | ! Property !! Default !! Comment | ||
|- | |- | ||
− | |buildDirectory || <SMILA_HOME>/eclipse.build || | + | |buildDirectory || <SMILA_HOME>/eclipse.build || directory where build output will be created. |
|- | |- | ||
− | | | + | |builder || <SMILA_HOME>/SMILA.builder || directory where <tt>make.xml</tt> is located |
|- | |- | ||
− | | | + | |eclipse.home || <ECLIPSE_HOME> || the location of the [[#Build Requirements |eclipse instance]] used to build SMILA |
|- | |- | ||
− | | | + | |lib.dir || <SMILA_HOME>/lib || location of the additional build libs (ant-contrib, etc.) |
|- | |- | ||
− | |pdeBuildPluginVersion || 3.4.1.R34x_v20080805 | + | |pdeBuildPluginVersion || 3.4.1.R34x_v20080805 || 3.4.1.R34x_v20081217 (for build with Eclipse 3.4.2) |
|- | |- | ||
− | |equinoxLauncherPluginVersion || 1.0.101.R34x_v20080819 | + | |equinoxLauncherPluginVersion || 1.0.101.R34x_v20080819 || 1.0.101.R34x_v20081125 (for build with Eclipse 3.4.2) |
|- | |- | ||
|os || win32 || rowspan=3 | these merely control under which platform the test will run. It must be one of the [[#Setting the Target Build Platform |target platforms]] you have build. | |os || win32 || rowspan=3 | these merely control under which platform the test will run. It must be one of the [[#Setting the Target Build Platform |target platforms]] you have build. | ||
Line 123: | Line 108: | ||
|} | |} | ||
− | |||
− | |||
==== Executing the make.xml ==== | ==== Executing the make.xml ==== | ||
Line 137: | Line 120: | ||
# set up devolopment environment see: [[SMILA/Development_Guidelines/Howto_set_up_dev_environment|How to set up dev environment]] | # set up devolopment environment see: [[SMILA/Development_Guidelines/Howto_set_up_dev_environment|How to set up dev environment]] | ||
# select the SMILA.builder bundle | # select the SMILA.builder bundle | ||
− | # open External Tools | + | # open External Tools Configuration dialog (in Toolbar or Run -> External Tools submenu) |
− | # create a new | + | # create a new "Ant build" configuration or choose your configuration if exists |
− | # | + | # set the "Buildfile" field to ${workspace_loc:/SMILA.builder/make.xml} |
− | # insert all properties from above into the arguments input field ( | + | # set the "Base directory" field to ${workspace_loc:/SMILA.builder} |
− | #: -DbuildDirectory=D:/ | + | # insert all properties from above into the arguments input field (and adapt these to your setup) but prepend each with <tt>-D</tt> so each is passed into <tt>ant</tt> as a property, e.g. |
− | #: -Declipse.home=D:/ | + | #: -DbuildDirectory=D:/workspace/SMILA/eclipse.build |
− | #: -Dbuilder=D:/ | + | #: -Declipse.home=D:/eclipse341 |
+ | #: -Dbuilder=D:/workspace/SMILA/SMILA.builder | ||
#: -Declipse.running=true | #: -Declipse.running=true | ||
#: -DpdeBuildPluginVersion=3.4.1.R34x_v20080805 | #: -DpdeBuildPluginVersion=3.4.1.R34x_v20080805 | ||
#: -DequinoxLauncherPluginVersion=1.0.101.R34x_v20080819 | #: -DequinoxLauncherPluginVersion=1.0.101.R34x_v20080819 | ||
#: -Dos=win32 -Dws=win32 -Darch=x86 | #: -Dos=win32 -Dws=win32 -Darch=x86 | ||
− | #: -Dlib.dir=D:/ | + | #: -Dlib.dir=D:/workspace/SMILA/lib |
− | # Apply, | + | # Apply, and run SMILA.builder with this external tool configuration |
+ | |||
+ | Note: To start another than the default target select the targets of your choice on the "Targets" tab. | ||
− | |||
− | |||
− | |||
− | |||
===== Executing make.xml from command line ===== | ===== 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 <tt>.#~#~#</tt> appended to denote their template nature. Copy one of them matching your system, but the names <tt>make.bat</tt> and <tt>make.sh</tt> is already in the svn:ignore to prevent it from beeing committed accidentally, so it is recommended to use them. | |
− | # | + | |
− | + | Both scripts are very similar, they start with setting some environment variables which are then used to create the build configuration properties and eventually feed them into an ANT call. There are the variables you usually need to check and adapt: | |
+ | |||
+ | {| border="1" cellspacing="0" cellpadding="5" valign=top | ||
+ | ! Variable !! Comment | ||
+ | |- | ||
+ | | SMILA_HOME || location of your SVN working copy. Can be derived automatically in <tt>.sh</tt> script, in the batch file, you must set it yourself. | ||
+ | |- | ||
+ | | ECLIPSE_HOME || the location of the [[#Build Requirements |eclipse instance]] used to build SMILA | ||
+ | |- | ||
+ | | ARCH || operating system and platform settings for running the tests. See description of <tt>os</tt>, <tt>ws</tt> and <tt>arch</tt> properties above. | ||
+ | |- | ||
+ | | JAVA_HOME || location of the JDK to build and run tests in. Must match the ARCH setting | ||
+ | |- | ||
+ | | ANT_HOME || location of your ANT installation | ||
+ | |- | ||
+ | | BUILDLIB_DIR || location of your build files. If you placed them in the SMILA_HOME you can leave this untouched and comment out the <tt>libDir</tt> setting in the next line. | ||
+ | |- | ||
+ | | buildOpts || choose the line matching your Eclipse installation or adapt them if you have another version installed. | ||
+ | |- | ||
+ | |} | ||
+ | |||
+ | Usually you don't need to change anything after the line setting <tt>buildOpts</tt>. | ||
+ | |||
+ | To run a build with the default target (<tt>all</tt>), open a command prompt or shell in the SMILA.builder directory and just enter. | ||
+ | |||
+ | <source lang="text"> | ||
+ | make | ||
+ | </source> | ||
+ | |||
+ | To execute another than the default target just pass it (or them) as an argument: | ||
<source lang="text"> | <source lang="text"> | ||
− | |||
− | |||
make build | make build | ||
</source> | </source> | ||
+ | |||
+ | In Windows you will not see much output in the command prompt window, because the batch file redirects it to a logfile (named <tt>log.make</tt>, if the batch file is <tt>make.bat</tt>) so that you can check for error details after the build. You can install the [http://gnuwin32.sourceforge.net/ GnuWin32] or [http://www.cygwin.com/ Cygwin] tools and use <tt>tee</tt> to have the output written to both console and logfile. The template contains the changed ANT call as a comment quite at the end of the script. | ||
+ | |||
+ | [[Category:SMILA]] |
Revision as of 06:47, 6 April 2009
Contents
Build Requirements
The build process uses Eclipse's PDE Build tools to build all the bundles, run all unit tests and create an ZIP archive with a complete SMILA application that can be installed and run independently from any development environment. To run this build process, you should first install the following software.
- Eclipse SDK 3.4.x for your operating system: We recommend installing a second Eclipse instance independently from the one you are using as your IDE so that additional installed Eclipse plugins you use in your work do not interfere with the build process (this shouldn't happen, usually - but just to be safe). You can find the download on [1]. This How-to was tested with Eclipse Classic SDK 3.4.2.
- DeltaPack matching your Eclipse version: The DeltaPack contains some additional bundles needed in the build, mainly for creating the SMILA executable for different platforms. You'll find the download on http://download.eclipse.org/eclipse/downloads/. Install it by unpacking it into you Eclipse SDK installation. This How-to was tested with DeltaPack 3.4.2.
- Sun Java Development Kit: You need a full JDK to build SMILA, not just a JRE. Both versions 5 and 6 should work, but we tested the How-to with JDK 5.0
- Apache Ant: The build process is executed by Ant, which you can download here: [2]. At least version 1.7 is needed (and tested).
- Additional Libraries for building which are not included in SMILA repository. The build scripts assume the following directory structure for these libraries. You can either create this structure in your working copy of the SMILA repository next to all the SMILA bundles, or somewhere else on your hard disk and configure the build process to find them there (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
- ant-contrib: This is required to run the build. You may download it from: ant-contrib.
- Furthermore our build process optionally generates reports for checkstyle, emma (code coverage) and pmd (static code analysis) if these libraries are present. To generate these reports you may download these files from: checkstyle emma pmd. The build is configured to run without these libraries and will just not create the respective reports, but everything else will be OK.
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 |
|
Windows 64bit
(only provided by eclipse 3.4 and higher) |
|
Linux 32bit |
|
Linux 64bit |
|
Solaris 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: 0 |
|
---|
</source>
Setting Build Properties
These are the main properties that can be used to configure the build process executed by make.xml. If you run the build from Eclipse you must add them to the Ant launch configuration, for running from command line we have included templates that you can adapt to your local setup.
Property | Default | Comment |
---|---|---|
buildDirectory | <SMILA_HOME>/eclipse.build | directory where build output will be created. |
builder | <SMILA_HOME>/SMILA.builder | directory where make.xml is located |
eclipse.home | <ECLIPSE_HOME> | the location of the eclipse instance used to build SMILA |
lib.dir | <SMILA_HOME>/lib | location of the additional build libs (ant-contrib, etc.) |
pdeBuildPluginVersion | 3.4.1.R34x_v20080805 | 3.4.1.R34x_v20081217 (for build with Eclipse 3.4.2) |
equinoxLauncherPluginVersion | 1.0.101.R34x_v20080819 | 1.0.101.R34x_v20081125 (for build with Eclipse 3.4.2) |
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 |
Executing the make.xml
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:
- set up devolopment environment see: How to set up dev environment
- select the SMILA.builder bundle
- open External Tools Configuration dialog (in Toolbar or Run -> External Tools submenu)
- create a new "Ant build" configuration or choose your configuration if exists
- set the "Buildfile" field to ${workspace_loc:/SMILA.builder/make.xml}
- set the "Base directory" field to ${workspace_loc:/SMILA.builder}
- insert all properties from above into the arguments input field (and adapt these to your setup) but prepend each with -D so each is passed into ant as a property, e.g.
- -DbuildDirectory=D:/workspace/SMILA/eclipse.build
- -Declipse.home=D:/eclipse341
- -Dbuilder=D:/workspace/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:/workspace/SMILA/lib
- Apply, and run SMILA.builder with this external tool configuration
Note: To start another than the default target select the targets of your choice on the "Targets" tab.
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. Copy one of them matching your system, but the names make.bat and make.sh is already in the svn:ignore to prevent it from beeing committed accidentally, so it is recommended to use them.
Both scripts are very similar, they start with setting some environment variables which are then used to create the build configuration properties and eventually feed them into an ANT call. There are the variables you usually need to check and adapt:
Variable | Comment |
---|---|
SMILA_HOME | location of your SVN working copy. Can be derived automatically in .sh script, in the batch file, you must set it yourself. |
ECLIPSE_HOME | the location of the eclipse instance used to build SMILA |
ARCH | operating system and platform settings for running the tests. See description of os, ws and arch properties above. |
JAVA_HOME | location of the JDK to build and run tests in. Must match the ARCH setting |
ANT_HOME | location of your ANT installation |
BUILDLIB_DIR | location of your build files. If you placed them in the SMILA_HOME you can leave this untouched and comment out the libDir setting in the next line. |
buildOpts | choose the line matching your Eclipse installation or adapt them if you have another version installed. |
Usually you don't need to change anything after the line setting buildOpts.
To run a build with the default target (all), open a command prompt or shell in the SMILA.builder directory and just enter.
make
To execute another than the default target just pass it (or them) as an argument:
make build
In Windows you will not see much output in the command prompt window, because the batch file redirects it to a logfile (named log.make, if the batch file is make.bat) so that you can check for error details after the build. You can install the GnuWin32 or Cygwin tools and use tee to have the output written to both console and logfile. The template contains the changed ANT call as a comment quite at the end of the script.