wiki:BuildSystem

Version 17 (modified by welberge, 7 years ago) (diff)

--

The ANT based build system

TODO: explain new non-git based repository!

Starting point

We assume that you already have the sources and the release libaries, in the following directory structure:

<svnroot>/HmiShared/ant
<svnroot>/HmiShared/docs
<svnroot>/HmiShared/repository
...etc
<svnroot>/HmiDemo/MyFirstProject
<svnroot>/HmiDemo/HmiAnimationDemo
...etc

And, if you checked out the source release:

<svnroot>/Hmi/HmiBml
<svnroot>/Hmi/HmiAnimation
....etc

Goal of the build system

The modules in Asap are dependent on many external and internal libraries, sometimes in different versions. Furthermore, each machine (32bit, 64bit, mac, windows, linux) may require its own version of a specific library. The build system was created to:

  • collect all dependent external libraries, and all internal releases, in a structured repository that allows to keep track of versions and dependencies
  • allow one to resolve, from this structured repository, exactly those versions of dependent libraries that are required for your project, on your machine and your operating system
  • make it easy to release new versions of our own modules
  • make it easy to use, in module A, the current latest compile of module B, instead of the released version of module B

Quickstart

In command prompt the module directory:

  • ant resolve to collect all dependent released and external libraries in the lib directory
  • ant compilelist to compile dependent modules
  • ant ca to collect the newest compiled versions in the lib directory
  • ant run to compile and run the project

Specify dependent libraries in ivy.xml; specify compile-dependent modules in build.properties using the rebuild.list property

Use cases

Running and compiling against released versions

  • ant resolve to collect all dependent released and external libraries in the lib directory
  • ant main to set the class that is to be run
  • ant run to compile and run the project

Running and compiling against source code

  • ant resolve to collect all dependent released and external libraries in the lib directory
  • ant compilelist to compile dependent modules
  • ant main to set the class that is to be run
  • ant run to compile and run the project

Testing

  • ant junit to compile and run the test cases
  • ant junitreport to compile and run the test cases and generate an html report in the test/report directory

Setting up project dependencies

The dependencies of a project are managed in the ivy.xml file in its root directory. A typical ivy.xml file looks like this:

<ivy-module version="2.0">
   <info organisation="HMI" module="HmiTTS"/>
   <dependencies> 
      <dependency org="jcip"       name="jcip-annotations"   rev="latest.release"  />   
      <dependency org="slf4j"      name="slf4j-api"          rev="latest.release"  />   
      <dependency org="HMI"        name="HmiUtil"            rev="latest.${resolve.status}"  />
      <dependency org="HMI"        name="HmiXml"             rev="latest.${resolve.status}"  />            
   </dependencies>
</ivy-module>   

rev="latest.release" means: resolve the latest version of this external library rev="latest.${resolve.status}" means: resolve the latest version of this HMI library of ${resolve.status} resolve.status is set in the build properties, valid values are beta and release.

Resolving dependencies

Dependencies are resolved from

  1. the local.lib directory of a project
  2. the local repository directory of a project (can be set up in its repository directory)
  3. the repository in HmiShared

`ant resolve' and similar resolve commands empty the lib directory, so use local.lib to store local libraries instead. Local resources are, by convention, stored in a projects resource directory.

Advanced: new/alternative default repositories can be added in HmiShared/ivy/ivysettings.xml

Advanced

Fixing java.lang.OutOfMemoryError: PermGen space

For large (re)builds, especially of HmiDemo projects with lots of dependencies, the default ant settings do not suffice, and ant might crash because of memory problems; typically

java.lang.OutOfMemoryError: PermGen space

This error can be fixed by explicitly setting the permgensize in the ANT_OPTS environment variable. In linux this is done using:

export ANT_OPTS="-XX:MaxPermSize=1024M"

in e.g. ~/.bashrc. In windows,ant calls the antrc_pre.bat file (if it exists) before running ant, so the environment variable can be set there using:

set ANT_OPTS=-XX:MaxPermSize=1024M

ant_rc.bat should be placed in your HOME directory.

Using a local repository

By default, the Hmi, Asap and external libraries are checked out from the https server and it is strongly advised that you resolve them from there. However, if you (temporarily, e.g. at a conference) don't have an internet connection, you can set up the build system to check out from a local directory (here: d:/hmirepo). This is done as follows:

Create a hmi.build.properties file in your home directory and add:

hmi.repository.filesystem.root=d:/hmirepo
repository.mode=filesystem

Copy the hmirepository to your directory of choice. Rsync can be used to create incremental copies:

rsync -v -a --delete loginname@hmirepo.ewi.utwente.nl:/local2/hmirepo .

Compiling to/as a different Java version

In build.properties:

javac.version=1.6 (both source and target are 1.6)

or

javac.target=1.6  (source may be theorie Java 7, target is 1.6 class code)

More

Detailed explanation of the build system is still being written. For specific questions, ask below.

Discussion

BuildSystem
 unsolved

Reply here to give additional information or ask questions.