wiki:UseCases

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

Selecting a main class without running ant main

ant run -Drun.main.class="package.MainClass"

Using runtime parameters

ant run -Drun.argline="runtimeparams"

with runtimeparams a space seperated list of runtime parameters that are to be passed to your Java program.

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

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 repositories in  http://asap-project.org/repo/ and  http://hmirepo.ewi.utwente.nl/

`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 hmibuild/ivy/ivysettings.xml

Advanced

Finding project dependencies

Using

ant ivyreport

in your project gives you a html file in the build directory that lists the project's dependencies.

Running and compiling against source code

It is possible (but not recommended) to run and compile your project against the source of other projects. To this end, define the projects source dependencies using rebuild.list:

e.g.

rebuild.list=Hmi/HmiUtil, Hmi/HmiMath, Hmi/HmiAnimation, Hmi/HmiNeurophysics, Hmi/HmiRenderEnvironment, Hmi/HmiAnimationEmbodiments
  • 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

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 ~/.antrc. 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 e.g. be Java 1.7, target is 1.6 class code)

Releasing external jar files

hmibuild/publishexternal/publish.py is a python script to release external jar files into e.g. hmirepo. This script will create the ivy xml file, setup up the correct directory structure in the repository and copy over a specified jar. The script assumes that a private key for the server is available in ~/.ssh/id_rsa. Windows users will need to install the winrandom and Crypto packages for Python, in linux (at least on the new techfak netboot machines in Bielefeld) it just works. Run the script as follows:

python ./publish.py -v 1.1 -o myorganization -m mymodule --host casoa@itchy mymodule-1.1.jar

Releasing your project on a repository

To create a release of your project on the soa, asap or hmi repository:

ant release

This requires that you specify the repository in the build.properties file, e.g.:

publish.resolver=soa.core.repository

Of course you'll also need to have write access to the repository. The following repositories are available by default:

asap.sftp.publish: the asap code ssh repository (web version located at http://asap-project.org/repo/repository)
asap.resource.sftp.publish: the asap resource ssh repository (web version located at http://asap-project.org/repo/resource)
soa.core.repository: the soashared repository, a git repository assumed to be located in your <gitroot>/soashared directory. Send a pull request to Herwin add your local changes into the shared git repository.
hmicore.sftp.publish: the hmi code ssh repository (web version located at http://hmirepo.ewi.utwente.nl/repository)
resource.sftp.publish: the resource hmi repository (web version located at http://hmirepo.ewi.utwente.nl/resource)

ant release increments the minor version number, then produces a version with "release" status. When the current version happens to be a developer version, then "incrementing the minor" actually means "stripping off" the -devi suffix.

To increment the major release number use

ant majorrelease

Releasing data as a zip file

To release a project containing only data as a zip file, set the following in ivy.xml:

<publications>
     <artifact type="zip" ext="zip"/>
</publications>

in build.properties

language=zipresource

This will zip up everything in your resource dir and release it when you use one of the release targets (e.g. release, majorrelease). When resolving such a released dataset, it will be unpacked in the lib directory. Such resource project should contain a single top-level directory and no other files in resource to keep the lib dir somewhat clean and readable (this is somewhat enforced by the resolver).

Releasing under a different user name

If you need to release under a different name than your username (e.g. at home), use

publish.user.name=yourpublishusername

in your ~/hmi.build.properties file.

Speeding up resolving

By default, resolve cleans ivy cache before resolving, so that all libraries are downloaded from the repository when resolving, including the ones that were already there. This can be suppressed by setting

ivycleanbeforeresolve=false

in your ~/hmi.build.properties file.

This might however lead to libraries not being resolved correctly sometimes; manually run ant ivyclean to fix this when problems occur.