6.1 Running JeeWiz

Ant is always used to run JeeWiz.

Ant is normally run from a JeeWiz project directory, and the command line to do a build is normally ant. This is by convention: it assumes the existence of an Ant 'build.xml' script. It is true in all the JeeWiz examples (in the 'examples' directory). If you wish to change the build.xml name, refer to the Ant documentation for specifying the local build file. The build.xml files for the examples typically support targets for 'clean' and 'build' tasks, 'build' being the default.

This section discusses how to set up Ant and run JeeWiz.

6.1.1  Setting up Ant

• As there were major changes to Ant after version 1.5*, JeeWiz is incompatible with these versions of Ant.
• JeeWiz has been tested with Ant 1.6.*, but this is no longer part of the production tests. If you want to use Ant 1.6, try it and report any problems.

There have been no equivalent changes to the ant file to start up Unix. If you want to run JeeWiz in a Unix installation, please let us know so we can cooperate to make it work.

6.1.2  Starting JeeWiz

For the JeeWiz examples, you can just invoke ant from the appropriate project and the build.xml file provided will take care of interfacing to the JeeWiz engine.

If you write your own build.xml files to start running JeeWiz, you need to decide between the two available ways to start JeeWiz. Both ways use an Ant build file in jeewiz/bin.

6.1.2.1  jwrun.xml

The original way is to use jwrun.xml. This starts a new JVM to run Ant. There are two good reasons for using the 'jwrun' approach:

1. It is a good idea in advanced applications where there are lots of variables, because this approach does not automatically propagate properties from the calling Ant project into the JeeWiz build.

   It may seem unlikely that an Ant property you use in programming a build script would collide with one in a JeeWiz build. However, this is not as unlikely as it seems - there can be hundreds of properties in a large run. Furthermore, these top-level properties will influence the build in unpredictable ways and cost a lot of time to diagnose.

   When you need to use more facilities of the jwrun.xml interface, you can pass parameters through the project build.xml into jwrun using "pass*" properties. There are 60 of these: pass, pass2, pass3, ... pass 59. They all get passed as arguments to 'jwrun'.
2. This approach is normally used in conjunction with build properties files. The build properties file gives an alternative, property-style, way of specifying changes in a build's configuration. As there are a range of build properties files used, it also allows customisations to be introduced for an installation, for a particular user or for a given build.

Note that, on Windows, you will need to use quotes around parameters with names and values - i.e. -Dpass=name=value - passed in this way, because the command-line processor does not correctly parse the two '=' signs. In other words:

ant "-Dpass20=projectDir=build" // good ant -Dpass20=projectDir=build // fails

jwrun is the preferred option if you are

• building a large-scale generation system
• supporting people with different installations, where the different build properties are useful
• setting up a workflow that supports downstream configuration (i.e. after all the Ant scripts have been written)

6.1.2.2  jwcall.xml

The disadvantage of using jwrun, if you are Ant-oriented, is that it is slightly inconvenient to pass extra properties in from the command line: Instead of '-Dproperty=value', a user has to pass the properties using a 'pass' variable: -Dpass=-D....

This problem can be avoided using the 'jwcall' way of running JeeWiz - which you do in your Ant build job by calling jeewiz/bin/jwcall.xml. When you call into jwcall.xml (from an <ant> call task in your script), it links directly to the master JeeWiz task, without starting a new JVM.

This passes all the properties you pass into it to JeeWiz - and so runs the risk of passing unintended variables into JeeWiz. However, for simple builds, this approach is easier to understand and change from build.xml.

jwcall is the preferred option if you are writing Ant scripts which will determine the final configuration of a build.

The examples in the manual use the 'jwrun' form for command-line calls. If you are using the 'jwcall' form, remove the '-Dpass=' prefixes on the calls.

6.1.3  Shared Properties

See jeewiz/bin/jwrun.xml for detailed documentation.

6.1.4  jwrun JVM properties

See jeewiz/bin/jwrun.xml for detailed documentation.  

Copyright (c) 2001-2008 New Technology/enterprise Ltd.