Skip to main content

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.

Jump to: navigation, search

Difference between revisions of "SMILA/Documentation/HowTo/Howto build a SMILA-Distribution"

(Build Requirements)
(Build Requirements)
(49 intermediate revisions by 5 users not shown)
Line 1: Line 1:
==== Build Requirements  ====
+
This HowTo describes how to build a SMILA distribution.
  
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.
+
==== Build Requirements  ====
  
*Eclipse SDK 3.7.1 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/ http://download.eclipse.org/eclipse/downloads/]. This How-to was tested with [http://download.eclipse.org/eclipse/downloads/drops/R-3.7.1-201109091335/index.php Eclipse Classic SDK 3.7.1].
+
The build process uses Eclipse's PDE Build tools to build all the bundles, run all unit tests, and create a 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:  
  
*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.7.1-201109091335/index.php#DeltaPack DeltaPack 3.7.1].
+
*'''Eclipse SDK 4.4(.1)''' for your operating system: We recommend installing a fresh Eclipse instance independently from the one you might already be using and use this solely for the purpose of building SMILA. This makes sure that any potential additional Eclipse plugins installed on your existing installation won't 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/ http://download.eclipse.org/eclipse/downloads/]. This HowTo was tested with [http://download.eclipse.org/eclipse/downloads/drops4/R-4.4.1-201409250400/ Eclipse Classic SDK 4.4.1].
  
*Sun Java Development Kit: You need a full JDK, version 6, to build SMILA, not just a JRE. You can get it at [http://java.sun.com/javase/downloads/index.jsp]
+
*'''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 HowTo was tested with [http://download.eclipse.org/eclipse/downloads/drops4/R-4.4.1-201409250400/#DeltaPack DeltaPack 4.4.1].
  
*Apache Ant: The build process is executed by Ant, which you can download here: [http://ant.apache.org/ http://ant.apache.org/]. At least version 1.7 is needed (and tested).
+
*'''Sun Java Development Kit''': You need a full JDK, version 7, to build SMILA, not just a JRE. You can get it at [http://www.oracle.com/technetwork/java/javase/downloads/index.html]
  
*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).
+
*'''Apache Ant''': The build process is executed by Ant, which you can download here: [http://ant.apache.org/ 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). For your convenience, we have put together a package with current versions of these libraries for download: [https://www.dropbox.com/s/5zqumk5n45l5r70/smila-build-libraries-1.2.0.zip smila-build-libraries-1.2.0.zip]. The structure of this package is:
 +
<div style="margin-left: 1.5em">
 
<source lang="text">
 
<source lang="text">
 
lib/
 
lib/
 
   ant-contrib/
 
   ant-contrib/
       ant-contrib-1.0b3.jar
+
       ant-contrib-1.x.jar
 
   checkstyle/
 
   checkstyle/
       checkstyle-all-4.4.jar
+
       checkstyle-all-5.x.jar
   emma/
+
   jacoco/
       emma.jar, emma_ant.jar
+
       jacocoagent.jar, jacocoant.jar
 
   pmd/
 
   pmd/
 
       asm-3.2.jar, jaxen-1.1.1.jar, pmd-4.3.jar
 
       asm-3.2.jar, jaxen-1.1.1.jar, pmd-4.3.jar
</source>
+
  xjc/
+
      InterfacesXJCPlugin.jar, jaxb-api.jar, jaxb-impl.jar, jaxb-xjc.jar
 
+
</source>  
**ant-contrib: This is required to run the build. You may download it from: [http://sourceforge.net/projects/ant-contrib ant-contrib]. (Tested with ant-contrib 1.0b3)
+
</div>
+
**ant-contrib: This is required to run the build. You may download it from: [http://sourceforge.net/projects/ant-contrib/files/ant-contrib/1.0b3/ ant-contrib]. You can use the binary versions available there. (Tested with ant-contrib 1.0b3)  
**Furthermore our build process optionally generates reports for checkstyle, emma (code coverage) and pmd (static code analysis) if these libraries are present. The build is configured to run without these libraries and will just not create the respective reports, but everything else will be OK. To generate these reports you may download these files from:  
+
**Furthermore our build process optionally generates reports for checkstyle, jacoco (code coverage) and pmd (static code analysis) if these libraries are present. The build is configured to run without these libraries and will just not create the respective reports, but everything else will be OK. To generate these reports you may download these files from:  
+
***[http://checkstyle.sourceforge.net/ checkstyle] (use Checkstyle 5.5 or higher, older versions will not handle Java-7 source code correctly).  
***[http://checkstyle.sourceforge.net/ checkstyle] (use Checkstyle 4.x. The current rules do not work with 5.0) (Tested with Checkstyle 4.4)
+
***[http://eclemma.org/jacoco/ jacoco]. (Tested with jacoco 0.5.7 and higher)  
+
***[http://pmd.sourceforge.net/ pmd]. (Tested with pmd 4.3)
***[http://emma.sourceforge.net/ emma] (Tested with emma 2.0.5312)
+
**xjc: is only needed if you need to generate JAXB classes from an XML schema, see [[SMILA/Development Guidelines/Setup for JAXB code generation]] for details.
+
***[http://pmd.sourceforge.net/ pmd]. (Tested with pmd 4.3, 4.1 should also work)
+
  
 
==== Configuring the Build  ====
 
==== 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.7.1 and build a product for Win 32bit and 64bit, Linux 32bit and 64bit as well as MacOS x86 64bit. 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 4.2 and build a product for Win 32bit and 64bit, Linux 32bit and 64bit as well as MacOS x86 64bit. But it is also possible to build other platforms. &nbsp;  
&nbsp;
+
  
Whether you build from command line or from eclipse, in both cases the <tt>make.xml</tt> ant script is executed. Before execution certain properties need to be set to meet the local setup.
+
Whether you build from command line or from Eclipse, in both cases the <tt>make.xml</tt> ant script is executed. Before execution certain properties need to be set to meet the local setup.  
  
 
===== Setting the Target Build Platform  =====
 
===== Setting the Target Build Platform  =====
  
Independent of which way you are going to build, you must copy the file <tt>build.properties.template</tt> to <tt>build.properties</tt> and set the <tt>configs</tt> property in <tt>build.properties</tt> for your setup.
+
''First, [[SMILA/Development Guidelines/Howto set up dev environment|setup a development environment]].'' When finished copy the file <tt>SMILA.builder/build.properties.template</tt> to <tt>SMILA.builder/build.properties</tt> and adapt the copied file: Add the platforms that you want to build as value triplets to the <tt>configs</tt> property and comment out or remove those that you don't need. The available platform triplets are:<br>  
  
You should exclude the target platforms that you don't need to build from your ''configs'' setting.
+
{| border="1"
 
+
|+ <br>
{|
+
|+  
+
 
|-
 
|-
! Windows 32bit
+
! Windows 32bit  
+
| {{Codeblock|<pre>...
| {{Codeblock|<PRE>...
+
 
configs=win32,win32,x86  
 
configs=win32,win32,x86  
# ... </PRE>
+
# ... </pre>
 
}}
 
}}
 
|-
 
|-
! Windows 64bit
+
! Windows 64bit  
+
| {{Codeblock|<pre>...
| {{Codeblock|<PRE>...
+
 
configs=win32,win32,x86_64  
 
configs=win32,win32,x86_64  
# ... </PRE>
+
# ... </pre>
 
}}
 
}}
 
|-
 
|-
! Linux 32bit
+
! Linux 32bit  
+
| {{Codeblock|<pre>...
| {{Codeblock|<PRE>...
+
 
configs=linux,gtk,x86
 
configs=linux,gtk,x86
# ... </PRE>
+
# ... </pre>
 
}}
 
}}
 
|-
 
|-
! Linux 64bit
+
! Linux 64bit  
+
| {{Codeblock|<pre>...
| {{Codeblock|<PRE>...
+
 
configs=linux, gtk, x86_64
 
configs=linux, gtk, x86_64
# ... </PRE>
+
# ... </pre>
 
}}
 
}}
 
|-
 
|-
! Solaris SPARC
+
! Solaris SPARC  
+
| {{Codeblock|<pre>...
| {{Codeblock|<PRE>...
+
 
configs=solaris, gtk, sparc
 
configs=solaris, gtk, sparc
# ... </PRE>
+
# ... </pre>
 
}}
 
}}
 
|}
 
|}
  
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.
+
If you want to provide several distributions at once e.g one for Windows 32bit and one for Linux 32bit (default build plan), concatenate the platform triplets with the '&amp;' character:<br>
+
  
{|
+
{| border="1"
 
|-
 
|-
! Example:
+
! Example:  
+
| {{Codeblock|<pre>configs=win32, win32, x86 & \
| {{Codeblock|<PRE>configs=win32, win32, x86 & \
+
  linux, gtk, x86 </pre>
  linux, gtk, x86 </PRE>
+
 
}}
 
}}
 
|}
 
|}
  
The application distribution archive files will be created in subdirectory <tt>Application</tt> of the specified build directory (see below). For each <tt>configs</tt> entry <tt>$os, $ws, $arch</tt> a ZIP file named <tt>SMILA-incubation-$os.$ws.$arch.zip</tt> will be created.
+
The archive files of the application distribution are created in the <tt>Application</tt> directory below the specified build directory (see below). For each platform triplet in the <tt>configs</tt> property (<tt>$os, $ws, $arch</tt>) a ZIP file named <tt>SMILA-incubation-$os.$ws.$arch.zip</tt> is built.  
  
 
===== Setting Build Properties  =====
 
===== Setting Build Properties  =====
  
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 within Eclipse you must add them to the Ant launch configuration (see [[#Executing_make.xml_from_within_eclipse|Executing make.xml from within Eclipse]] below), for running from command line we have included templates that you can adapt to your local setup (see [[#Executing_make.xml_from_command_line|Executing make.xml from command line]] below).
+
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 within Eclipse you must add them to the Ant launch configuration (see [[#Executing_make.xml_from_within_Eclipse|Executing make.xml from within Eclipse]] below), for running from command line we have included templates that you can adapt to your local setup (see [[#Executing_make.xml_from_command_line|Executing make.xml from command line]] below).  
  
{| border="1" cellspacing="0" cellpadding="5"
+
<br> Note: When using linux, make sure not to use paths containing softlinks, because they may not be correctly resolved during the build process. Use the full qualified path instead.&nbsp;
 +
 
 +
{| cellspacing="0" cellpadding="5" border="1"
 
|-
 
|-
! Property
+
! Property  
! Default
+
! Default  
 
! Comment
 
! Comment
 
|-
 
|-
| buildDirectory
+
| <tt>buildDirectory</tt>
| &lt;SMILA_HOME&gt;/eclipse.build
+
| <tt>&lt;SMILA_HOME&gt;/eclipse.build</tt>
| directory where build output will be created. This should be always a subdirectory of SMILA_HOME. The application distribution ZIP files will be created in subdirectory <tt>Application</tt> of this directory.
+
| Directory where built output will be created. This should be always a subdirectory of &lt;SMILA_HOME&gt;. The application distribution's ZIP files will be created in the subdirectory <tt>Application</tt> of this directory.
 
|-
 
|-
| builder
+
| <tt>builder</tt>
| &lt;SMILA_HOME&gt;/SMILA.builder
+
| <tt>&lt;SMILA_HOME&gt;/SMILA.builder</tt>
| directory where <tt>make.xml</tt> is located
+
| Directory where <tt>make.xml</tt> is locate.
 
|-
 
|-
| eclipse.home
+
| <tt>eclipse.home</tt>
| &lt;ECLIPSE_HOME&gt;
+
| <tt>&lt;ECLIPSE_HOME&gt;</tt>
| the location of the [[#Build_Requirements|eclipse instance]] used to build SMILA
+
| Location of the [[#Build_Requirements|Eclipse instance]] used to build SMILA.
 
|-
 
|-
| lib.dir
+
| <tt>lib.dir</tt>
| &lt;SMILA_HOME&gt;/lib
+
| <tt>&lt;SMILA_HOME&gt;/lib</tt>
| location of the additional build libs (ant-contrib, etc.)
+
| Location of the additional build libs (ant-contrib, etc.).
 
|-
 
|-
| pdeBuildPluginVersion
+
| <tt>os</tt>
| 3.7.0.v20110512-1320
+
| win32
| for build with Eclipse 3.7.1
+
| rowspan="3" | These properties merely control under which platform the test will run. It must be one of the [[#Setting_the_Target_Build_Platform|target platforms]] you have built.
 
|-
 
|-
| equinoxLauncherPluginVersion
+
| <tt>ws</tt>
| 1.2.0.v20110502
+
| for build with Eclipse 3.7.1
+
|-
+
| 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.
+
|-
+
| ws
+
 
| win32
 
| win32
 
|-
 
|-
| arch
+
| <tt>arch</tt>
 
| x86
 
| x86
 
|-
 
|-
| test.java.home
+
| <tt>test.java.home</tt>
| &lt;JAVA_HOME&gt;
+
| <tt>&lt;JAVA_HOME&gt;</tt>
| &nbsp;a java 1.6 SDK instance
+
| A Java 1.7 SDK instance.
 
|}
 
|}
  
==== Executing the make.xml ====
+
==== Executing the make.xml ====
[[Image:Smila.build.all.png|thumb|right| <tt>all</tt> dependency graph]]
+
  
The default target is <tt>all</tt>. This will by default build the application and run all unit tests. Note that this can take quite a while. To build the distribution archives only, use targets <tt>clean</tt> and <tt>final-application</tt>. The [[:image:Smila.build.all.png|dependency graph]] will explain what will happen and shows the relevant targets you may call instead.
+
The default target is <tt>all</tt>, building the application and running all unit tests. Note that this can take quite a while. To build the distribution archives only, use the targets <tt>clean</tt> and <tt>final-application</tt>. See [[SMILA/Development Guidelines/Introduction to make.xml|Introduction to make.xml]] for more details.  
  
 +
===== Executing make.xml from within Eclipse  =====
  
===== Executing make.xml from within eclipse  =====
+
Steps:
  
Steps:
+
#Select the <tt>SMILA.builder</tt> bundle.
 
+
#Open the ''External Tools Configuration'' dialog (select ''Run -&gt; External Tools -&gt; External Tools Configuration'').
#set up devolopment environment see: [[SMILA/Development Guidelines/Howto set up dev environment|How to set up dev environment]]
+
#Create a new ''Ant Build'' configuration.
#select the SMILA.builder bundle
+
#In the ''Buildfile'' field, enter: <tt>${workspace_loc:/SMILA.builder/make.xml}</tt>.
#open External Tools Configuration dialog (in Toolbar or Run -&gt; External Tools submenu)
+
#In the ''Base Directory'' field, enter: <tt>${workspace_loc:/SMILA.builder}</tt>.
#create a new "Ant build" configuration or choose your configuration if exists
+
#Add all properties from [[#Setting_Build_Properties|above]] into the ''Arguments'' field (and adapt them to meet your setup) but prepend each with <tt>-D</tt> so each is passed into <tt>ant</tt> as a property (note that <tt>buildDirectory</tt> should be a subdirectory of your SMILA workspace directory), e.g. when using Eclipse 3.7.2 to build:  
#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 <tt>-D</tt> so each is passed into <tt>ant</tt> as a property (note that buildDirectory should be a subdirectory of your SMILA workspace directory), e.g. when using Eclipse 3.7.1 to build:
+
 
#:-DbuildDirectory=D:/workspace/SMILA/eclipse.build  
 
#:-DbuildDirectory=D:/workspace/SMILA/eclipse.build  
#:&nbsp;-Declipse.home=D:/eclipse371
+
#:&nbsp;-Declipse.home=D:/eclipse42
 
#:-Dbuilder=D:/workspace/SMILA/SMILA.builder  
 
#:-Dbuilder=D:/workspace/SMILA/SMILA.builder  
 
#:-Declipse.running=true  
 
#:-Declipse.running=true  
#:-Dos=win32 -Dws=win32 -Darch=x86
+
#:-Dos=win32 -Dws=win32 -Darch=x86  
#:-Dlib.dir=D:/workspace/SMILA/lib
+
#:-Dlib.dir=D:/workspace/SMILA/lib  
 +
#Apply, and run the Ant build.<br>'''Note:''' To start another than the default target select the targets of your choice on the ''Targets'' tab.
  
#Apply, and run SMILA.builder with this external tool configuration
+
===== Executing make.xml from command line  =====
  
Note: To start another than the default target select the targets of your choice on the "Targets" tab.
+
The <tt>make.bat</tt> and <tt>make.sh</tt> files are just shell scripts setting 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 and rename them as you like, but note that the names <tt>make.bat</tt> and <tt>make.sh</tt> are already in the svn:ignore list to prevent them from beeing committed accidentally, so it is recommended to use them.  
  
===== Executing make.xml from command line =====
+
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:
  
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.
+
{| cellspacing="0" cellpadding="5" border="1"
 
+
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.
+
! Variable
 +
! Comment
 
|-
 
|-
| ECLIPSE_HOME || the location of the [[#Build Requirements |eclipse instance]] used to build SMILA
+
| <tt>SMILA_HOME </tt>
 +
| Location of your SVN working copy. May be derived automatically in the <tt>.sh</tt> script, in the batch file, however, you must set it yourself.
 
|-
 
|-
| 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.  
+
| <tt>ECLIPSE_HOME </tt>  
 +
| Location of the [[#Build_Requirements|Eclipse instance]] used to build SMILA.
 
|-
 
|-
| JAVA_HOME || location of the JDK to build and run tests in. Must match the ARCH setting.  
+
| <tt>ARCH </tt>
'''Tip:''' In case your compile log complaints about a non-1.6 compatible JVM despite the correct setting, you must also add the {{path|JAVA_HOME}} location to the {{Path|ECLIPSE_HOME/eclipse.ini}} like so:<br/>
+
| Operating system and platform settings for running the tests. See description of <tt>os</tt>, <tt>ws</tt> and <tt>arch</tt> properties above.
{{Code|
+
|-
 +
| <tt>JAVA_HOME </tt>
 +
| Location of the JDK to build and run tests in. Must match the <tt>ARCH</tt> setting.  
 +
'''Tip:''' If your compile log complaints about a non-1.6 compatible JVM despite the correct settings, you must also add the {{path|JAVA_HOME}} location to the {{Path|ECLIPSE_HOME/eclipse.ini}} like so:<br> {{Code|
 
-vm<br/>
 
-vm<br/>
<JAVA_HOME>\bin}}
+
<JAVA_HOME>\bin}}  
|-
+
 
| 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.
+
| <tt>ANT_HOME </tt>  
 +
| Location of your ANT installation.
 
|-
 
|-
| buildOpts ||  choose the line matching your Eclipse installation or adapt them if you have another version installed.
+
| <tt>BUILDLIB_DIR </tt>
 +
| 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.
 
|-
 
|-
 +
| <tt>buildOpts </tt>
 +
| Use the default <tt>buildOpts</tt> for Eclipse pdebuild or adapt them if you have another version installed.
 
|}
 
|}
  
Usually you don't need to change anything after the line setting <tt>buildOpts</tt>.
+
Usually you don't need to change anything below 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.
+
To run a build with the default target (<tt>all</tt>), open a command prompt or shell in the <tt>SMILA.builder</tt> directory and just enter.  
  
 
<source lang="text">
 
<source lang="text">
 
make
 
make
</source>
+
</source>  
  
To execute another than the default target just pass it (or them) as an argument:
+
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>  
  
For example, to build the application distribution ZIPs without running the tests (which can take quite long), you can use:
+
For example, to build the application distribution ZIPs without running the tests (which can take quite long), you can use:  
  
 
<source lang="text">
 
<source lang="text">
 
make clean final-application
 
make clean final-application
</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.
+
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]]
 
[[Category:SMILA]]

Revision as of 09:29, 13 November 2014

This HowTo describes how to build a SMILA distribution.

Build Requirements

The build process uses Eclipse's PDE Build tools to build all the bundles, run all unit tests, and create a 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 4.4(.1) for your operating system: We recommend installing a fresh Eclipse instance independently from the one you might already be using and use this solely for the purpose of building SMILA. This makes sure that any potential additional Eclipse plugins installed on your existing installation won't 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 HowTo was tested with Eclipse Classic SDK 4.4.1.
  • 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 HowTo was tested with DeltaPack 4.4.1.
  • Sun Java Development Kit: You need a full JDK, version 7, to build SMILA, not just a JRE. You can get it at [1]
  • 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). For your convenience, we have put together a package with current versions of these libraries for download: smila-build-libraries-1.2.0.zip. The structure of this package is:
lib/
   ant-contrib/
      ant-contrib-1.x.jar
   checkstyle/
      checkstyle-all-5.x.jar
   jacoco/
      jacocoagent.jar, jacocoant.jar
   pmd/
      asm-3.2.jar, jaxen-1.1.1.jar, pmd-4.3.jar
   xjc/
      InterfacesXJCPlugin.jar, jaxb-api.jar, jaxb-impl.jar, jaxb-xjc.jar
    • ant-contrib: This is required to run the build. You may download it from: ant-contrib. You can use the binary versions available there. (Tested with ant-contrib 1.0b3)
    • Furthermore our build process optionally generates reports for checkstyle, jacoco (code coverage) and pmd (static code analysis) if these libraries are present. The build is configured to run without these libraries and will just not create the respective reports, but everything else will be OK. To generate these reports you may download these files from:
      • checkstyle (use Checkstyle 5.5 or higher, older versions will not handle Java-7 source code correctly).
      • jacoco. (Tested with jacoco 0.5.7 and higher)
      • pmd. (Tested with pmd 4.3)
    • xjc: is only needed if you need to generate JAXB classes from an XML schema, see SMILA/Development Guidelines/Setup for JAXB code generation for details.

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 4.2 and build a product for Win 32bit and 64bit, Linux 32bit and 64bit as well as MacOS x86 64bit. 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

First, setup a development environment. When finished copy the file SMILA.builder/build.properties.template to SMILA.builder/build.properties and adapt the copied file: Add the platforms that you want to build as value triplets to the configs property and comment out or remove those that you don't need. The available platform triplets are:


Windows 32bit
...
configs=win32,win32,x86 
# ... 
Windows 64bit
...
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 at once e.g one for Windows 32bit and one for Linux 32bit (default build plan), concatenate the platform triplets with the '&' character:

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

The archive files of the application distribution are created in the Application directory below the specified build directory (see below). For each platform triplet in the configs property ($os, $ws, $arch) a ZIP file named SMILA-incubation-$os.$ws.$arch.zip is built.

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 within Eclipse you must add them to the Ant launch configuration (see Executing make.xml from within Eclipse below), for running from command line we have included templates that you can adapt to your local setup (see Executing make.xml from command line below).


Note: When using linux, make sure not to use paths containing softlinks, because they may not be correctly resolved during the build process. Use the full qualified path instead. 

Property Default Comment
buildDirectory <SMILA_HOME>/eclipse.build Directory where built output will be created. This should be always a subdirectory of <SMILA_HOME>. The application distribution's ZIP files will be created in the subdirectory Application of this directory.
builder <SMILA_HOME>/SMILA.builder Directory where make.xml is locate.
eclipse.home <ECLIPSE_HOME> Location of the Eclipse instance used to build SMILA.
lib.dir <SMILA_HOME>/lib Location of the additional build libs (ant-contrib, etc.).
os win32 These properties merely control under which platform the test will run. It must be one of the target platforms you have built.
ws win32
arch x86
test.java.home <JAVA_HOME> A Java 1.7 SDK instance.

Executing the make.xml

The default target is all, building the application and running all unit tests. Note that this can take quite a while. To build the distribution archives only, use the targets clean and final-application. See Introduction to make.xml for more details.

Executing make.xml from within Eclipse

Steps:

  1. Select the SMILA.builder bundle.
  2. Open the External Tools Configuration dialog (select Run -> External Tools -> External Tools Configuration).
  3. Create a new Ant Build configuration.
  4. In the Buildfile field, enter: ${workspace_loc:/SMILA.builder/make.xml}.
  5. In the Base Directory field, enter: ${workspace_loc:/SMILA.builder}.
  6. Add all properties from above into the Arguments field (and adapt them to meet your setup) but prepend each with -D so each is passed into ant as a property (note that buildDirectory should be a subdirectory of your SMILA workspace directory), e.g. when using Eclipse 3.7.2 to build:
    -DbuildDirectory=D:/workspace/SMILA/eclipse.build
     -Declipse.home=D:/eclipse42
    -Dbuilder=D:/workspace/SMILA/SMILA.builder
    -Declipse.running=true
    -Dos=win32 -Dws=win32 -Darch=x86
    -Dlib.dir=D:/workspace/SMILA/lib
  7. Apply, and run the Ant build.
    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 and make.sh files are just shell scripts setting 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 and rename them as you like, but note that the names make.bat and make.sh are already in the svn:ignore list to prevent them 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. May be derived automatically in the .sh script, in the batch file, however, you must set it yourself.
ECLIPSE_HOME 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.

Tip: If your compile log complaints about a non-1.6 compatible JVM despite the correct settings, you must also add the JAVA_HOME location to the ECLIPSE_HOME/eclipse.ini like so:
-vm
<JAVA_HOME>\bin

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 Use the default buildOpts for Eclipse pdebuild or adapt them if you have another version installed.

Usually you don't need to change anything below 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

For example, to build the application distribution ZIPs without running the tests (which can take quite long), you can use:

make clean final-application

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.

Back to the top