|
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205 |
- <html>
- <head>
- <title>AspectJ build module</title>
- </head>
- <body>
- <h1>AspectJ build</h1>
-
- This build module contains taskdefs and resources for doing builds
- and checking source licenses. This document describes our approach
- to builds and provides some notes for maintaining the build module
- and debugging builds.
- For information
- on running builds and doing testing for the AspectJ project, see
- <a href="readme-build-and-test-aspectj.html">
- readme-build-and-test-aspectj.html</a>.
-
- <h3>Approach</h3>
- The AspectJ project source files are broken into modules,
- the subdirectories of the modules directory.
- (To eclipse users, each module is a Java or AspectJ project.)
- The modules are compiled independently and may be assembled
- by the build script into the release jar files.
- All required libraries are checked into the <code>lib</code> module.
- We use Ant to drive the build, but the logic for building and
- assembling modules resides in the BuildModule taskdef,
- which reads module dependencies from the Eclipse .classpath files
- and assembles the product according to the templates in the
- product directory.
- This makes it easy to change dependencies and add modules,
- but could make it difficult to debug if something were to go wrong.
-
-
- <h3>Maintaining the build module</h3>
-
- Because the BuildModule taskdef extracts dependencies from the Eclipse
- <code>.classpath</code> file, there is no need to update build scripts when
- adding or removing modules or changing their dependencies, so long
- as they are all in the base modules directory (usually the base of
- the eclipse workspace).
- Likewise, updating a product assembly should be easy,
- since they are based on introspection of the product directories.
-
- Still, the taskdef workings are not obvious in the build script, so
- this section makes clear some of the implicit logic
- in case it's required when debugging build failures or
- to make changes.
-
- <h4>Build module code updates</h4>
- The build module produces taskdefs used to run the build.
- The scripts avoid bootstrapping by using a build library jar
- checked in to
- <code>lib/build/build.jar</code>.
- That means code updates in the build module are not reflected in
- the build process until the <code>build.jar</code> produced by
- building this <code>build</code> module replaces that found in
- <code>lib/build/build.jar</code>. Once the module update is
- confirmed, the new <code>lib/build/build.jar</code> must be checked in
- to propogate the changes to other users.
- The scripts support an Ant variable <code>check.build.jar</code>
- by warning when <code>lib/build/build.jar</code> is out of date.
-
- <h4>BuildModule task</h4>
- The
- <a href="src/org/aspectj/internal/tools/ant/taskdefs/BuildModule.java">
- BuildModule</a>
- taskdef implements an integrated module or product build.
- <p/><u>Module builds</u> are based on the Eclipse <code>.classpath</code>
- file, and can produce
- a jar with the module classes, with two variations:
- <ul>
- <li> include only the module classes,
- or assemble the jar complete with all antecedent modules and
- libraries;
- </li><li>compile the module(s) with or without any
- testing source or libraries
- </li>
- </ul>
- If there is a file {moduleName}.mf.txt
- in the module directory, it will be used as the manifest for the
- module jar file.
-
- <p/><u>Product builds</u> are defined by introspection of a
- <a href="products">products</a> subdirectory like
- <a href="products/tools">products/tools</a> for the AspectJ installer.
-
- These have an <code>install</code> directory for installer resources
- and a <code>dist</code> directory containing all files belonging in
- the distribution, including 0-length placeholders for the module build
- results (e.g., <a href="products/tools/dist/lib">products/tools/dist/lib</a>).
- These placeholder file names are mapped to the originating
- module by <code>Builder.moduleAliasFor(String)</code>
- using values in
- <a href="src/org/aspectj/internal/tools/build/Builder.properties">
- Builder.properties</a>.
- (The "-all" suffix in the source jars means that the module and all required
- modules are included.)
- <p/>
- <a name="version"></a>
- <h4>Version synchronization</h4>
- The version is expressed in the jar manifests, in the <code>Version</code> class,
- and in some documentation files. The build script
- ensures all version expressions
- are aligned. When not doing or testing release builds,
- developers use the default "DEVELOPMENT" version.
-
- <p/>The build version is set in
- <a href="build-properties.xml">build-properties.xml</a> and propogated
- using Ant copy filters out to
- the <a href="../aspectj5rt/aspectj5rt.mf.txt">aspectjrt.jar manifest</a>,
- the <a href="../ajbrowser/ajbrowser.mf.txt">aspectjtools.jar manifest</a>
- and to
- <a href="../bridge/src/org/aspectj/bridge/Version.java">
- ../bridge/src/org/aspectj/bridge/Version.java</a>
- which the <a href="build.xml">build.xml</a> <code>init-version</code> task
- generates from a template
- <a href="lib/BridgeVersion.java.txt">lib/BridgeVersion.java.txt</a>.
- To avoid updating <code>Version.java</code> whenever
- <code>build-properties.xml</code> changes, a task
- <a href="src/org/aspectj/internal/tools/ant/taskdefs/VersionUptodate.java">
- src/org/aspectj/internal/tools/ant/taskdefs/VersionUptodate.java</a>
- determines whether Version.java has the same version by scanning the source file.
- The scan is dim-witted; do not change the lines flagged in the template
- without also changing the scanning code in the task.
-
- <h4>Temporary aj-{name} and persistant aspectj-{name}</h4>
- <p/>
- Top-level temporary build directories are prefixed "aj-",
- so you can safely destroy any such directory or ignore it
- in CVS or the Eclipse package explorer. By default the build script
- puts them at the same level as other modules. In build scripts, property names
- follow a similar convention; those prefixed "aj-" may be deleted at will, while
- "aspectj-" names are source directories which should never be deleted.
-
- <h4>Building Java 5 sources</h4>
- <p/>
- Java 5 source is supported in <code>{module}/java5-src</code> directories.
- Under Ant, when building in a pre-Java-5 VM, this source will be ignored
- (hence, it must not be required to compile). Under Eclipse, developers
- not using Java 5 should close the corresponding modules.
-
- <h4>Builder.properties, resources, and tree audit tests</h4>
- <p/>
- In <a href="src/org/aspectj/internal/tools/build/Builder.properties">
- src/org/aspectj/internal/tools/build/Builder.properties</a>
- you can set up
- <ul>
- <li>product aliases for mapping module jars</li>
- <li>libraries to exclude for assembling module jars</li>
- <li>patterns for copying resources.</li>
- </ul>
- Regarding the patterns, if you add a resource with an unrecognized suffix to a
- source tree, the corresponding unit test in
- <a href="testsrc/BuildModuleTests.java">testsrc/BuildModuleTests.java</a>
- will fail. You'll need to update the <code>Builder.properties</code>
- file (and recreate the build.jar) to ensure that the new resource
- is copied to the assembled module jar.
-
- <h3>Debugging build problems</h3>
- <h4>Running under Eclipse</h4>
- When running Ant from eclipse,
- do not use the default Eclipse Ant classpath; remove those jars and
- add all the libraries in <a href="../lib/ant/lib">../lib/ant/lib</a>
- as well as in <a href="../lib/junit">../lib/junit</a>.
- If the build is failing under eclipse or Ant and the problem appears
- to be in the build module, you can run the build directly in eclipse
- (not using the Ant script) by running the skipped JUnit tests in
- <a href="testsrc/org/aspectj/internal/build/ModulesTests.java">
- testsrc/org/aspectj/internal/build/ModulesTests.java</a>.
- <p/>
-
- <h4>Why new or changed modules might not work</h4>
- The BuildModule taskdef makes some assumptions about the naming,
- position, and contents of module directories and files.
- Understand those (documented in
- <a href="src/org/aspectj/internal/tools/ant/taskdefs/BuildModule.java">
- BuildModule.java</a>) before using non-standard module directories.
-
- <h4>Silent classpath and build failures</h4>
- <u>warning</u>: When Ant runs compile processes, sometimes Jar files
- are not closed until the process quits. When running Ant under Eclipse,
- that means the jar files are not writable until eclipse quits.
- This affects build products (e.g., installers) which are run under eclipse
- (e.g., by opening with the "default system editor") and libraries used
- when compiling under Javac (if not zip products or input). This problem
- presents as files not being writable, i.e., deleted or modified.
- <p/>
- One workaround is to delete any existing build products
- before re-creating them. The problem with this is that Ant provides no
- notice of that deletes fail when deleting with quiet="on", but when not
- running in quiet mode, deletes will fail if the directory does not exist.
- The workaround-workaround would be to create any required directories
- before trying to deleting any files, with the result of creating unused
- empty directories.
-
- <p/>
- Currently BuildModule tasks forks the Javac command to try to work around
- this problem, but the Zip commands do not work around it.
-
- If under Eclipse, you get strange behavior with Ant builds, clear
- out everything and build from the command line. In some cases, you
- have to exit Eclipse before files can be deleted. (*sigh*)
-
- <p/>
- </body>
- </html>
|