12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485868788899091929394959697989910010110210310410510610710810911011111211311411511611711811912012112212312412512612712812913013113213313413513613713813914014114214314414514614714814915015115215315415515615715815916016116216316416516616716816917017117217317417517617717817918018118218318418518618718818919019119219319419519619719819920020120220320420520620720820921021121221321421521621721821922022122222322422522622722822923023123223323423523623723823924024124224324424524624724824925025125225325425525625725825926026126226326426526626726826927027127227327427527627727827928028128228328428528628728828929029129229329429529629729829930030130230330430530630730830931031131231331431531631731831932032132232332432532632732832933033133233333433533633733833934034134234334434534634734834935035135235335435535635735835936036136236336436536636736836937037137237337437537637737837938038138238338438538638738838939039139239339439539639739839940040140240340440540640740840941041141241341441541641741841942042142242342442542642742842943043143243343443543643743843944044144244344444544644744844945045145245345445545645745845946046146246346446546646746846947047147247347447547647747847948048148248348448548648748848949049149249349449549649749849950050150250350450550650750850951051151251351451551651751851952052152252352452552652752852953053153253353453553653753853954054154254354454554654754854955055155255355455555655755855956056156256356456556656756856957057157257357457557657757857958058158258358458558658758858959059159259359459559659759859960060160260360460560660760860961061161261361461561661761861962062162262362462562662762862963063163263363463563663763863964064164264364464564664764864965065165265365465565665765865966066166266366466566666766866967067167267367467567667767867968068168268368468568668768868969069169269369469569669769869970070170270370470570670770870971071171271371471571671771871972072172272372472572672772872973073173273373473573673773873974074174274374474574674774874975075175275375475575675775875976076176276376476576676776876977077177277377477577677777877978078178278378478578678778878979079179279379479579679779879980080180280380480580680780880981081181281381481581681781881982082182282382482582682782882983083183283383483583683783883984084184284384484584684784884985085185285385485585685785885986086186286386486586686786886987087187287387487587687787887988088188288388488588688788888989089189289389489589689789889990090190290390490590690790890991091191291391491591691791891992092192292392492592692792892993093193293393493593693793893994094194294394494594694794894995095195295395495595695795895996096196296396496596696796896997097197297397497597697797897998098198298398498598698798898999099199299399499599699799899910001001100210031004100510061007100810091010101110121013101410151016101710181019102010211022102310241025102610271028102910301031103210331034103510361037103810391040104110421043104410451046104710481049105010511052105310541055105610571058105910601061106210631064106510661067106810691070107110721073107410751076107710781079108010811082108310841085108610871088108910901091109210931094109510961097109810991100110111021103110411051106110711081109111011111112111311141115111611171118111911201121112211231124112511261127112811291130113111321133113411351136113711381139114011411142114311441145114611471148114911501151115211531154115511561157115811591160116111621163116411651166116711681169117011711172117311741175117611771178117911801181118211831184118511861187118811891190119111921193119411951196119711981199120012011202120312041205120612071208120912101211121212131214121512161217121812191220122112221223122412251226122712281229123012311232123312341235123612371238123912401241124212431244124512461247124812491250125112521253125412551256125712581259126012611262126312641265126612671268126912701271127212731274127512761277127812791280128112821283128412851286128712881289129012911292129312941295129612971298129913001301130213031304130513061307130813091310131113121313131413151316131713181319132013211322132313241325132613271328132913301331133213331334133513361337133813391340134113421343134413451346134713481349135013511352135313541355135613571358135913601361136213631364136513661367136813691370137113721373137413751376137713781379138013811382138313841385138613871388138913901391139213931394139513961397139813991400140114021403140414051406140714081409141014111412141314141415141614171418141914201421142214231424142514261427142814291430143114321433143414351436143714381439144014411442144314441445144614471448144914501451145214531454145514561457145814591460146114621463146414651466146714681469147014711472147314741475147614771478147914801481148214831484148514861487148814891490149114921493149414951496149714981499150015011502150315041505150615071508150915101511151215131514151515161517151815191520152115221523152415251526152715281529153015311532153315341535153615371538153915401541154215431544154515461547154815491550155115521553155415551556155715581559156015611562156315641565156615671568156915701571157215731574157515761577157815791580158115821583158415851586158715881589159015911592159315941595159615971598159916001601160216031604160516061607160816091610161116121613161416151616 |
- <chapter id="antTasks" xreflabel="AspectJ Ant Tasks">
-
- <title>AspectJ Ant Tasks</title>
-
- <sect1 id="antTasks-intro">
- <title>Introduction</title>
-
- <para>
- AspectJ contains a compiler, <literal>ajc</literal>,
- that can be run from Ant.
- Included in the <literal>aspectjtools.jar</literal>
- are Ant binaries to support three
- ways of running the compiler:
- <orderedlist>
- <listitem>
- <para>
- <xref linkend="antTasks-iajc"/>,
- a task to run the AspectJ post-1.1 compiler,
- which supports all the eclipse and ajc options, including incremental mode.
- </para>
- </listitem>
- <listitem>
- <para>
- <xref linkend="antTasks-adapter"/>,
- an adapter class to run the new compiler using Javac tasks
- by setting the build.compiler property
- </para>
- </listitem>
- <listitem>
- <para>
- <xref linkend="antTasks-ajc"/>,
- a task to run build scripts compatible with the AspectJ 1.0 tasks
- </para>
- </listitem>
- </orderedlist>
- </para>
-
- <para>
- This describes how to install and use the tasks and the adapter.
- For an example Ant script, see
- <ulink url="../examples/build.xml">examples/build.xml</ulink>.
- </para>
- </sect1>
-
- <!-- . . . . . . . . . . . . . . . . . . . . . . . . . . . install -->
- <sect1 id="antTasks-install" xreflabel="Installing Ant Tasks">
- <title>Installing Ant Tasks</title>
- <para>
- Install Jakarta Ant 1.5.1:
- Please see the official Jakarta Ant website for more information
- and the 1.5.1 distribution. This release is source-compatible
- with Ant 1.3 and Ant 1.4, but the task sources must be
- compiled with those versions of the Ant libraries to be used
- under those versions of Ant.
- Sources are available under the Eclipse Public License v 2.0
- at <ulink url="http://eclipse.org/aspectj">http://eclipse.org/aspectj</ulink>.
- </para>
- <para>
- In Ant 1.5, third-party tasks can be declared using a taskdef entry in
- the build script, to identify the name and classes.
- When declaring a task, include the
- <literal>aspectjtools.jar</literal> either in the
- taskdef classpath or in <literal>${ANT_HOME}/lib</literal> where it will be added
- to the system class path by the ant script.
- You may specify the task script names directly,
- or use the "resource" attribute to specify the default names:
- </para>
- <programlisting><![CDATA[
- <taskdef resource="org/aspectj/tools/ant/taskdefs/aspectjTaskdefs.properties"/>
- ]]></programlisting>
-
- <para>
- The current resource file retains the name "ajc" for the Ajc10 task,
- and uses "iajc" for the AspectJ post-1.1 task.
- </para>
- <para>
- In Ant 1.6, third-party tasks are declared in their own namespace
- using <literal>antlib.xml</literal>. For example, the following
- script would build and run the spacewar example, if you put the
- script in the examples directory and <literal>aspectjtools.jar</literal>
- in the <literal>${ANT_HOME}/lib</literal> directory.
- </para>
- <programlisting><![CDATA[
- <project name="aspectj-ant1.6" default="spacewar"
- xmlns:aspectj="antlib:org.aspectj" basedir=".">
- <target name="spacewar">
- <aspectj:iajc
- argfiles="spacewar/debug.lst"
- outjar="spacewar.jar"
- classpath="../../lib/aspectjrt.jar"
- />
- <java classname="spacewar.Game"
- classpath="spacewar.jar:../../lib/aspectjrt.jar"/>
- </target>
- </project>
- ]]></programlisting>
- <para>
- For more information on using Ant, please refer to Jakarta's
- documentation on integrating user-defined Ant tasks into builds.
- </para>
-
- </sect1>
- <!-- . . . . . . . . . . . . . . . . . . . . . . . . . . . iajc -->
- <sect1 id="antTasks-iajc" xreflabel="AjcTask (iajc)">
- <title>AjcTask (iajc)</title>
- <para>
- This task uses the AspectJ post-1.1 compiler ajc.
- The AspectJ compiler can be used like Javac to compile Java sources,
- but it can also compile AspectJ sources or weave binary aspects
- with Java bytecode.
- It can run in normal "batch" mode or in an "incremental" mode,
- where it only recompiles files it has to revisit.
- For more information on ajc, see <xref linkend="ajc-ref"/>.
- Unlike Javac or the Javac Ant task, this task always compiles the
- specified files since aspects can apply to other (updated) files.
- For a workaround, see <xref linkend="antTasks-iajc-uptodate"/>.
- </para>
- <para>
- Beyond the normal ajc compiler options, this task also supports
- an experimental option for an incremental "tag" file, and it
- can copy resources from source directories or
- input jars to the output jar or directory.
- </para>
-
- <para>
- This task is named iajc to avoid conflict with the 1.0 task ajc.
- </para>
-
- <sect2 id="antTasks-iajc-options" xreflabel="AjcTask (iajc) Options">
- <title>AjcTask (iajc) Options</title>
- <para>
- The following tables list the supported parameters.
- For any parameter specified as a Path, a single path can be
- specified directly as an attribute,
- multiple paths can be specified using a nested element of
- the same name, and a common path can be reused by defining it as a
- global and passing the id to the corresponding {name}ref attribute.
- See <xref linkend="antTasks-iajc-paths"/>
- below for more details.
- </para>
- <para>
- Most attributes and nested elements are optional.
- The compiler requires that the same version of
- <literal>aspectjrt.jar</literal>
- be specified on the classpath, and that some sources be
- be specified
- (using one or more of
- <literal>sourceroots</literal>,
- <literal>injars</literal>,
- <literal>inpath</literal>,
- <literal>argfiles</literal>, and/or
- <literal>srcdir</literal> (with patterns)).
- When in incremental mode, only
- <literal>sourceroots</literal> may be specified.
- </para>
- <para>Boolean parameters default to <literal>false</literal>
- unless otherwise stated.
- </para>
-
- <!-- . . . . . . . . . . . . . . . . iajc options table -->
- <!-- table (and caption/title) not supported by fop -->
- <para>
- <emphasis role="strong">
- AjcTask (iajc) options for specifying sources
- </emphasis>
- </para>
- <informaltable>
-
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Attribute</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry><para>argfiles, argfilesRef
- (<xref linkend="antTasks-iajc-paths"/>)
- </para></entry>
- <entry><para>
- An argument file contains a list of arguments read by the compiler.
- Each line is read into one element of the argument array
- and may include another argfile by reference.
- </para></entry>
- </row>
- <row>
- <entry><para>sourceRoots, sourceRootsRef
- (<xref linkend="antTasks-iajc-paths"/>)
- </para></entry>
- <entry><para>
- Directories containing source files (ending with .java or .aj) to compile.
- </para></entry>
- </row>
- <row>
- <entry><para>srcdir
- (<xref linkend="antTasks-iajc-paths"/>)
- </para></entry>
- <entry><para>
- Base directory of sources to compile, assuming there are
- <xref linkend="antTasks-nested-includes"/>.
- This approach uses the Ant process
- for matching .java files and is not compatible with incremental
- mode. Unless using filters to limit the sources included,
- use sourceroots instead.
- </para></entry>
- </row>
- <row>
- <entry><para>injars, injarsRef
- (<xref linkend="antTasks-iajc-paths"/>)
- </para></entry>
- <entry><para>
- Deprecated - use inpath instead.
- Read .class files for bytecode weaving
- from zip files (only).
- </para></entry>
- </row>
- <row>
- <entry><para>inpath, inpathRef
- (<xref linkend="antTasks-iajc-paths"/>)
- </para></entry>
- <entry><para>
- Read .class files for bytecode weaving
- from directories or zip files (like classpath).
- </para></entry>
- </row>
- <row>
- <entry><para>classpath, classpathRef
- (<xref linkend="antTasks-iajc-paths"/>)
- </para></entry>
- <entry><para>
- The classpath used by the sources being compiled.
- When compiling aspects, include the same version of the
- <literal>aspectjrt.jar</literal>.
- </para></entry>
- </row>
- <row>
- <entry><para>bootclasspath, bootclasspathRef
- (<xref linkend="antTasks-iajc-paths"/>)
- </para></entry>
- <entry><para>
- The bootclasspath specifies types to use instead of the
- invoking VM's when seeking types during compilation.
- </para></entry>
- </row>
- <row>
- <entry><para>extDirs, extDirsRef
- (<xref linkend="antTasks-iajc-paths"/>)
- </para></entry>
- <entry><para>
- The extension directories to use instead of those in the
- invoking VM when seeking types during compilation.
- </para></entry>
- </row>
- <row>
- <entry><para>aspectPath, aspectPathRef
- (<xref linkend="antTasks-iajc-paths"/>)
- </para></entry>
- <entry><para>
- Similar to classpath, aspectpath contains read-only,
- binary aspect libraries that are woven into sources
- but not included in the output.
- <literal>aspectpath</literal> accepts jar/zip files
- (but, unlike classpath, not directories).
- </para></entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
-
- <para>
- <emphasis role="strong">
- AjcTask (iajc) options for specifying output
- </emphasis>
- </para>
- <informaltable>
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Attribute</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry><para>destDir
- </para></entry>
- <entry><para>
- The directory in which to place the generated class files.
- Only one of <literal>destDir</literal> and
- <literal>outJar</literal> may be set.
- </para></entry>
- </row>
- <row>
- <entry><para>outJar
- </para></entry>
- <entry><para>
- The zip file in which to place the generated output class files.
- Only one of <literal>destDir</literal> and
- <literal>outJar</literal> may be set.
- </para></entry>
- </row>
- <row>
- <entry><para>copyInjars
- </para></entry>
- <entry><para>
- (Deprecated/ignored; ajc does this.)
- If true, copy all non-.class files from input jar(s)
- to the output jar or destination directory after the
- compile (or incremental compile) completes.
- In forked mode, this copies only after the process
- completes, not after incremental compiles.
- </para></entry>
- </row>
- <row>
- <entry><para>sourceRootCopyFilter
- </para></entry>
- <entry><para>
- When set, copy all files from the sourceroot directories to the output jar
- or destination directory except those specified in the filter pattern.
- The pattern should be compatible with an Ant fileset excludes filter;
- when using this, most developers pass
- <literal>**/CVS/*,**/*.java</literal> to exclude any CVS directories
- or source files.
- See <literal>inpathDirCopyFilter</literal>.
- Requires <literal>destDir</literal> or <literal>outJar</literal>.
- </para></entry>
- </row>
- <row>
- <entry><para>inpathDirCopyFilter
- </para></entry>
- <entry>
- <para> When set, copy all files from the inpath directories
- to the output jar or destination directory except those
- specified in the filter pattern. The pattern should be
- compatible with an Ant fileset excludes filter; when
- using this, most developers pass
- <literal>**/CVS/*,**/*.java,**/*.class</literal> to
- exclude any CVS directories, source files, or unwoven
- .class files. (If <literal>**/*.class</literal> is not
- specified, it will be prepended to the filter.) See
- <literal>sourceRootCopyFilter</literal>. (Note that ajc
- itself copies all resources from input jar/zip files on
- the inpath.) Requires <literal>destDir</literal> or
- <literal>outJar</literal>.</para>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
-
- <para>
- <emphasis role="strong">
- AjcTask (iajc) options for specifying compiler behavior
- </emphasis>
- </para>
- <informaltable>
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Attribute</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry><para>fork
- </para></entry>
- <entry><para>
- Run process in another VM.
- This gets the forking classpath either explicitly
- from a <literal>forkclasspath</literal> entry
- or by searching the task or system/Ant classpath for the
- first readable file with a name of the form
- <literal>aspectj{-}tools{.*}.jar</literal>.
- When forking you can specify the amount of memory used
- with <literal>maxmem</literal>.
- Fork cannot be used in incremental mode,
- unless using a tag file.
- </para></entry>
- </row>
- <row>
- <entry><para>forkclasspath, forkclasspathRef
- (<xref linkend="antTasks-iajc-paths"/>)
- </para></entry>
- <entry><para>
- Specify the classpath to use for the compiler when forking.
- </para></entry>
- </row>
- <row>
- <entry><para>maxmem
- </para></entry>
- <entry><para>
- The maximum memory to use for the new VM when fork is true.
- Values should have the same form as accepted by the VM, e.g., "128m".
- </para></entry>
- </row>
- <row>
- <entry><para>incremental
- </para></entry>
- <entry><para>
- incremental mode: Build once, then recompile only required source
- files when user provides input.
- Requires that source files be specified only using
- <literal>sourceroots</literal>.
- Incompatible with forking.
- </para></entry>
- </row>
- <row>
- <entry><para>tagfile
- </para></entry>
- <entry><para>
- incremental mode: Build once, then recompile only required source
- files when the tag file is updated, finally exiting when tag file
- is deleted.
- Requires that source files be specified only using
- <literal>sourceroots</literal>.
- </para></entry>
- </row>
- <row>
- <entry><para>X
- </para></entry>
- <entry><para>
- Set experimental option(s), using comma-separated list of accepted options
- Options should not contain the leading X.
- Some commonly-used experimental options have their
- own entries. The other permitted ones (currently) are
- serializableAspects, incrementalFile, lazyTjp,
- reweavable, notReweavable, noInline,
- terminateAfterCompilation,
- ajruntimelevel:1.2, and ajruntimelevel:1.5.
- Of these, some were deprecated in AspectJ 5
- (reweavable, terminateAfterCompilation, etc.).
- </para></entry>
- </row>
- <row>
- <entry><para>XterminateAfterCompilation
- </para></entry>
- <entry><para>
- Terminates before the weaving process, dumping out unfinished class files.
- </para></entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
-
- <para>
- <emphasis role="strong">
- AjcTask (iajc) options for specifying compiler side-effects and messages
- </emphasis>
- </para>
- <informaltable>
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Attribute</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry><para>emacssym
- </para></entry>
- <entry><para>
- If true, emit <literal>.ajesym</literal> symbol files for Emacs support.
- </para></entry>
- </row>
- <row>
- <entry><para>crossref
- </para></entry>
- <entry><para>
- If true, emit <literal>.ajsym</literal> file into the output directory.
- </para></entry>
- </row>
- <row>
- <entry><para>verbose
- </para></entry>
- <entry><para>
- If true, log compiler verbose messages as Project.INFO during the compile.
- </para></entry>
- </row>
- <row>
- <entry><para>logCommand
- </para></entry>
- <entry><para>
- If true, log compiler command elements as Project.INFO
- (rather than the usual Project.VERBOSE level).
- </para></entry>
- </row>
- <row>
- <entry><para>Xlistfileargs
- </para></entry>
- <entry><para>
- If true, emit list of file arguments during
- the compile (but behaves now like verbose).
- </para></entry>
- </row>
- <row>
- <entry><para>version
- </para></entry>
- <entry><para>
- If true, do not compile - just print AspectJ version.
- </para></entry>
- </row>
- <row>
- <entry><para>help
- </para></entry>
- <entry><para>
- If true, just print help for the command-line compiler.
- </para></entry>
- </row>
- <row>
- <entry><para>Xlintwarnings
- </para></entry>
- <entry><para>
- Same as <literal>xlint:warning</literal>:
- if true, set default level of all language
- usage messages to warning.
- </para></entry>
- </row>
- <row>
- <entry><para>Xlint
- </para></entry>
- <entry><para>
- Specify default level of all language usage messages to one of
- [<literal>error warning ignore</literal>].
- </para></entry>
- </row>
- <row>
- <entry><para>XlintFile
- </para></entry>
- <entry><para>
- Specify property file containing <literal>name:level</literal> associations
- setting level for language messages emitted during compilation.
- Any levels set override the default associations in
- <literal>org/aspectj/weaver/XLintDefault.properties</literal>.
- </para></entry>
- </row>
- <row>
- <entry><para>failonerror
- </para></entry>
- <entry><para>
- If true, throw BuildException to halt build if there
- are any compiler errors.
- If false, continue notwithstanding compile errors.
- Defaults to <literal>true</literal>.
- </para></entry>
- </row>
- <row>
- <entry><para>messageHolderClass
- </para></entry>
- <entry><para>
- Specify a class to use as the message holder for the compile process.
- The entry must be a fully-qualified name of a class resolveable from
- the task classpath complying with the
- <literal>org.aspectj.bridge.IMessageHolder</literal> interface
- and having a public no-argument constructor.
- </para></entry>
- </row>
- <row>
- <entry><para>showWeaveInfo
- </para></entry>
- <entry><para>
- If true, emit weaver messages.
- Defaults to <literal>false</literal>.
- </para></entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
-
-
- <para>
- <emphasis role="strong">
- AjcTask (iajc) options for specifying Eclipse compiler options
- </emphasis>
- </para>
- <informaltable>
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Attribute</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry><para>nowarn
- </para></entry>
- <entry><para>
- If true, same as <literal>warn:none</literal>.
- </para></entry>
- </row>
- <row>
- <entry><para>deprecation
- </para></entry>
- <entry><para>
- If true, same as <literal>warn:deprecation</literal>
- </para></entry>
- </row>
- <row>
- <entry><para>warn
- </para></entry>
- <entry><para>
- One or more comma-separated warning specifications from
- [<literal>constructorName packageDefaultMethod deprecation,
- maskedCatchBlocks unusedLocals unusedArguments,
- unusedImports syntheticAccess assertIdentifier</literal>].
- </para></entry>
- </row>
- <row>
- <entry><para>debug
- </para></entry>
- <entry><para>
- If true, same as <literal>debug:lines,vars,source</literal>
- </para></entry>
- </row>
- <row>
- <entry><para>debugLevel
- </para></entry>
- <entry><para>
- One or more comma-separated debug specifications from
- [<literal>lines vars source</literal>].
- </para></entry>
- </row>
- <row>
- <entry><para>PreserveAllLocals
- </para></entry>
- <entry><para>
- If true, code gen preserves all local variables (for debug purposes).
- </para></entry>
- </row>
- <row>
- <entry><para>noimporterror
- </para></entry>
- <entry><para>
- If true, emit no errors for unresolved imports.
- </para></entry>
- </row>
- <row>
- <entry><para>referenceinfo
- </para></entry>
- <entry><para>
- If true, compute reference info.
- </para></entry>
- </row>
- <row>
- <entry><para>log
- </para></entry>
- <entry><para>
- File to log compiler messages to.
- </para></entry>
- </row>
- <row>
- <entry><para>encoding
- </para></entry>
- <entry><para>Default source encoding format
- (per-file encoding not supported in Ant tasks).
- </para></entry>
- </row>
- <row>
- <entry><para>proceedOnError
- </para></entry>
- <entry><para>
- If true, keep compiling after errors encountered,
- dumping class files with problem methods.
- </para></entry>
- </row>
- <row>
- <entry><para>progress
- </para></entry>
- <entry><para>
- If true, emit progress (requires log).
- </para></entry>
- </row>
- <row>
- <entry><para>time
- </para></entry>
- <entry><para>
- If true, display speed information.
- </para></entry>
- </row>
- <row>
- <entry><para>target
- </para></entry>
- <entry><para>
- Specify target class file format as one of
- [<literal>1.1 1.2</literal>].
- Defaults to 1.1 class file.
- </para></entry>
- </row>
- <row>
- <entry><para>source
- </para></entry>
- <entry><para>
- Set source compliance level to one of
- [<literal>1.3 1.4 1.5</literal>]
- (default is 1.4).
- 1.3 implies -source 1.3 and -target 1.1.
- 1.4 implies -source 1.4 and -target 1.2.
- 1.5 implies -source 1.5 and -target 1.5.
- </para></entry>
- </row>
- <row>
- <entry><para>source
- </para></entry>
- <entry><para>
- Set source assertion mode to one of
- [<literal>1.3 1.4</literal>].
- Default depends on compliance mode.
- </para></entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
-
- <!-- . . . . . . . . . . . . . . . . iajc options table -->
- </sect2>
-
- <sect2 id="antTasks-nested-includes" xreflabel="nested matches">
- <title>AjcTask matching parameters specified as nested elements</title>
- <para>
- This task forms an implicit FileSet and supports all attributes of
- <literal><fileset></literal> (dir becomes srcdir) as well as
- the nested
- <literal><include></literal>,
- <literal><exclude></literal>, and
- <literal><patternset></literal> elements.
- These can be used to specify source files.
- However, it is better to use <literal>sourceroots</literal>
- to specify source directories unless using filters to exclude
- some files from compilation.
- </para>
- </sect2>
-
- <sect2 id="antTasks-iajc-paths" xreflabel="Path">
- <title>AjcTask Path-like Structures</title>
- <para>
- Some parameters are path-like structures containing one or more
- elements; these are
- <literal>sourceroots</literal>,
- <literal>argfiles</literal>,
- <literal>injars</literal>,
- <literal>inpath</literal>,
- <literal>classpath</literal>,
- <literal>bootclasspath</literal>,
- <literal>forkclasspath</literal>, and
- <literal>aspectpath</literal>.
- In all cases, these may be specified as nested elements, something
- like this:
- </para>
- <programlisting><![CDATA[
- <iajc {attributes..} />
- <{name}>
- <pathelement path="{first-location}"/>
- <pathelement path="{second-location}"/>
- ...
- <{name}>
- ...
- </iajc>
- ]]></programlisting>
- <para>
- As with other Path-like structures, they may be defined elsewhere
- and specified using the refid attribute:
- </para>
- <programlisting><![CDATA[
- <path id="aspect.path">
- <pathelement path="${home}/lib/persist.jar"/>
- <pathelement path="${home}/lib/trace.jar"/>
- </path>
- ...
- <iajc {attributes..} />
- <aspectpath refid="aspect.path"/>
- ...
- </iajc>
- ]]></programlisting>
- <para>
- The task also supports an attribute <literal>{name}ref</literal>
- for each such parameter. E.g., for <literal>aspectpath</literal>:
- </para>
- <programlisting><![CDATA[
- <iajc {attributes..} aspectpathref="aspect.path"/>
- ]]></programlisting>
- </sect2>
-
- <sect2 id="antTasks-iajc-sample" xreflabel="Sample of iajc task">
- <title>Sample of iajc task</title>
- <para>
- A minimal build script defines the task and runs it, specifying the sources:
- </para>
- <programlisting><![CDATA[
- <project name="simple-example" default="compile" >
- <taskdef
- resource="org/aspectj/tools/ant/taskdefs/aspectjTaskdefs.properties">
- <classpath>
- <pathelement location="${home.dir}/tools/aspectj/lib/aspectjtools.jar"/>
- </classpath>
- </taskdef>
-
- <target name="compile" >
- <iajc sourceroots="${home.dir}/ec/project/src"
- classpath="${home.dir}/tools/aspectj/lib/aspectjrt.jar"/>
- </target>
- </project>
- ]]></programlisting>
- <para>
- Below is script with most everything in it. The compile process...
- </para>
- <orderedlist>
- <listitem>
- <para>Runs in incremental mode, recompiling when the user hits return;
- </para>
- </listitem>
- <listitem>
- <para>Reads all the source files from two directories;
- </para>
- </listitem>
- <listitem>
- <para>Reads binary .class files from input jar and directory;
- </para>
- </listitem>
- <listitem>
- <para>Uses a binary aspect library for persistence;
- </para>
- </listitem>
- <listitem>
- <para>Outputs to an application jar; and
- </para>
- </listitem>
- <listitem>
- <para>Copies resources from the source directories and binary input
- jar and directories to the application jar. </para>
- </listitem>
- </orderedlist>
- <para>
- When this target is built, the compiler will build once and then
- wait for input from the user.
- Messages are printed as usual.
- When the user has quit, then this runs the application.
- </para>
- <!-- if program changed, test in docs/test/antScriptTest -->
-
- <programlisting><![CDATA[
- <target name="build-test" >
- <iajc outjar="${home.dir}/output/application.jar"
- sourceRootCopyFilter="**/CVS/*,**/*.java"
- inpathDirCopyFilter="**/CVS/*,**/*.java,**/*.class"
- incremental="true" >
- <sourceroots>
- <pathelement location="${home.dir}/ec/project/src"/>
- <pathelement location="${home.dir}/ec/project/testsrc"/>
- </sourceroots>
- <inpath>
- <pathelement location="${home.dir}/build/module.jar"/>
- <pathelement location="${home.dir}/build/binary-input"/>
- </inpath>
- <aspectpath>
- <pathelement location="${home.dir}/ec/int/persist.jar"/>
- </aspectpath>
- <classpath>
- <pathelement location="${home.dir}/tools/aspectj/lib/aspectjrt.jar"/>
- </classpath>
- </iajc>
-
- <java classname="org.smart.app.Main">
- <classpath>
- <pathelement location="${home.dir}/tools/aspectj/lib/aspectjrt.jar"/>
- <pathelement location="${home.dir}/ec/int/persist.jar"/>
- <pathelement location="${home.dir}/output/application.jar"/>
- </classpath>
- </java>
- </target>
- ]]></programlisting>
- <para>
- For an example of a build script,
- see <ulink url="../examples/build.xml">
- ../examples/build.xml</ulink>.
- </para>
- </sect2>
-
- <sect2 id="antTasks-iajc-uptodate" xreflabel="Avoiding clean compiles">
- <title>Avoiding clean compiles</title>
- <para>
- Unlike javac, the ajc compiler always processes all input because
- new aspects can apply to updated classes and vice-versa.
- However, in the case where no files have been updated, there
- is no reason to recompile sources. One way to implement that
- is with an explicit dependency check using the uptodate task:
- </para>
- <programlisting><![CDATA[
- <target name="check.aspects.jar">
- <uptodate property="build.unnecessary"
- targetfile="${aspects.module-jar}" >
- <srcfiles dir="${src1}" includes="**/*.aj"/>
- <srcfiles dir="${src2}/" includes="**/*.aj"/>
- </uptodate>
- </target>
-
- <target name="compile.aspects" depends="prepare,check.aspects.jar"
- unless="build.unnecessary">
- <iajc ...
- ]]></programlisting>
- <para>
- When using this technique, be careful to verify that binary
- input jars are themselves up-to-date after they would have been
- modified by any build commands.
- </para>
- </sect2>
-
- <sect2 id="programmatically-handling-compiler-messages" xreflabel="programmatically-handling-compiler-messages">
- <title>Programmatically handling compiler messages</title>
- <para>
- Users may specify a message holder to which the compiler will pass
- all messages as they are generated. This will override all of the
- normal message printing, but does not prevent the task from failing
- if exceptions were thrown or if failonerror is true and the compiler
- detected errors in the sources.
- </para>
- <para>
- Handling messages programmatically could be useful when using the
- compiler to verify code. If aspects consist of declare [error|warning],
- then the compiler can act to detect invariants in the code being
- processed. For code to compare expected and actual messages, see the
- AspectJ testing module (which is not included in the binary
- distribution).
- </para>
- </sect2>
- </sect1>
-
- <!-- . . . . . . . . . . . . . . . . . . . . . . . . . . . adapter -->
- <sect1 id="antTasks-adapter" xreflabel="Ajc11CompilerAdapter (javac)">
- <title>Ajc11CompilerAdapter (javac)</title>
- <para>
- This CompilerAdapter can be used in javac task calls by setting the
- <literal>build.compiler</literal> property.
- This enables users to to easily switch between the Javac and AspectJ
- compilers. However, because there are differences in source file
- handling between the Javac task and the ajc compiler, not all
- Javac task invocations can be turned over to iajc. However, ajc can
- compile anything that Javac can, so it should be possible for any
- given compile job to restate the Javac task in a way that can be
- handled by iajc/ajc.
- </para>
- <sect2 id="antTasks-adapter-sample" xreflabel="Sample of compiler adapter">
- <title>Sample of compiler adapter</title>
- <para>
- To build using the adapter, put the
- <literal>aspectjtools.jar</literal>
- on the system/ant classpath (e.g., in
- <literal>${ANT_HOME}/lib</literal>)
- and define the
- <literal>build.compiler</literal>
- property as the fully-qualified name of the class,
- <literal>org.aspectj.tools.ant.taskdefs.Ajc11CompilerAdapter</literal>.
- </para>
- <para>
- The AspectJ compiler should run for any compile using the Javac task
- (for options, see the Ant documentation for the Javac task).
- For example, the call below passes all out-of-date source files in the
- <literal>src/org/aspectj</literal> subdirectories to the
- <literal>ajc</literal> command along with the destination directory:
- </para>
- <programlisting><![CDATA[
- -- command:
-
- cp aspectj1.1/lib/aspectjtools.jar ant/lib
- ant/bin/ant -Dbuild.compiler=org.aspectj.tools.ant.taskdefs.Ajc11CompilerAdapter ...
-
- -- task invocation in the build script:
-
- <javac srcdir="src" includes="org/aspectj/**/*.java" destdir="dest" />
- ]]></programlisting>
-
- <para>
- To pass ajc-specific arguments, use a compilerarg entry.
- </para>
- <programlisting><![CDATA[
- -- command
-
- Ant -Dbuild.compiler=org.aspectj.tools.ant.taskdefs.Ajc11CompilerAdapter
-
- -- build script
-
- <property name="ajc"
- value="org.aspectj.tools.ant.taskdefs.Ajc11CompilerAdapter"/>
-
- <javac srcdir="src" includes="org/aspectj/**/*.java" destdir="dest" >
- <compilerarg compiler="${ajc}" line="-argfile src/args.lst"/>
- <javac/>
- ]]></programlisting>
- <para>The Javac task does special handling of source files that
- can interfere with ajc. It removes any files that are not out-of-date
- with respect to the corresponding .class files. But ajc requires all
- source files, since an aspect may affect a source file that is not out
- of date. (For a solution to this, see the <literal>build.compiler.clean</literal>
- property described below.) Conversely, developers sometimes specify a source directory
- to javac, and let it search for files for types it cannot find.
- AspectJ will not do this kind of searching under the source directory
- (since the programmer needs to control which sources are affected).
- (Don't confuse the source directory used by Javac with the source root
- used by ajc; if you specify a source root to ajc, it will compile
- any source file under that source root (without exception or filtering).)
- To replace source dir searching in Javac, use an Ant filter to specify
- the source files.
- </para>
- </sect2>
-
- <sect2 id="antTasks-adapter-options" xreflabel="Compiler adapter compilerarg options">
- <title>Compiler adapter compilerarg options</title>
- <para>
- The adapter supports any ajc command-line option passed using compilerarg,
- as well as the following options available only in AjcTask.
- Find more details on the following options in <xref linkend="antTasks-iajc"/>.
- </para>
- <itemizedlist>
- <listitem><para>
- <literal>-Xmaxmem</literal>:
- set maximum memory for forking (also settable in javac).
- </para></listitem>
- <listitem><para>
- <literal>-Xlistfileargs</literal>:
- list file arguments (also settable in javac).
- </para></listitem>
- <listitem><para>
- <literal>-Xfailonerror</literal>:
- throw BuildException on compiler error (also settable in javac).
- </para></listitem>
- <listitem><para>
- <literal>-Xmessageholderclass</literal>:
- specify fully-qualified name of class to use as the message holder.
- </para></listitem>
- <listitem><para>
- <literal>-Xcopyinjars</literal>:
- copy resources from any input jars to output
- (default behavior since 1.1.1)
- </para></listitem>
- <listitem><para>
- <literal>-Xsourcerootcopyfilter {filter}</literal>:
- copy resources from source directories to output (minus files specified in filter)
- </para></listitem>
- <listitem><para>
- <literal>-Xtagfile {file}</literal>:
- use file to control incremental compilation
- </para></listitem>
- <listitem><para>
- <literal>-Xsrcdir {dir}</literal>:
- add to list of ajc source roots (all source files will be included).
- </para></listitem>
- </itemizedlist>
- <para>
- Special considerations when using Javac and compilerarg:
- </para>
- <itemizedlist>
- <listitem><para>
- The names above may differ slightly from what you might expect
- from AjcTask; use these forms when specifying compilerarg.
- </para></listitem>
- </itemizedlist>
- <itemizedlist>
- <listitem><para>
- By default the adapter will mimic the Javac task's copying of resource
- files by specifying
- <literal>"**/CVS/*,**/*.java,**/*.aj"</literal>
- for the sourceroot copy filter.
- To change this behavior, supply your own value
- (e.g., <literal>"**/*"</literal> to copy nothing).
- </para></listitem>
- </itemizedlist>
- <itemizedlist>
- <listitem><para>
- Warning - define the system property
- <literal>build.compiler.clean</literal> to compile all files,
- when available.
- Javac prunes the source file list of "up-to-date" source files
- based on the timestamps of corresponding .class files,
- and will not compile if no sources are out of date.
- This is wrong for ajc which requires all the files for each compile
- and which may refer indirectly to sources using argument files.
- </para>
- <para>
- To work around this, set the global property
- <literal>build.compiler.clean</literal>.
- This tells the compiler adapter to delete all .class files
- in the destination directory and re-execute the javac
- task so javac can recalculate the list of source files. e.g.,
- </para>
- <programlisting><![CDATA[
- Ant -Dbuild.compiler=org.aspectj.tools.ant.taskdefs.Ajc11CompilerAdapter
- -Dbuild.compiler.clean=anything ...
- ]]></programlisting>
- <para>
- Caveats to consider when using this global
- <literal>build.compiler.clean</literal> property:
- </para>
- <orderedlist>
- <listitem><para>
- If javac believes there are no out-of-date source files,
- then the adapter is never called and cannot clean up,
- and the "compile" will appear to complete successfully
- though it did nothing.
- </para></listitem>
- <listitem><para>
- Cleaning will makes stepwise build processes fail if
- they depend on the results of the prior compilation being
- in the same directory, since cleaning deletes all .class files.
- </para></listitem>
- <listitem><para>
- This clean process only permits one compile process at a
- time for each destination directory because it tracks
- recursion by writing a tag file to the destination directory.
- </para></listitem>
- <listitem><para>
- When running incrementally, the clean happens only before
- the initial compile.
- </para></listitem>
- </orderedlist>
- </listitem>
- </itemizedlist>
- </sect2>
- </sect1>
-
- <!-- . . . . . . . . . . . . . . . . . . . . . . . . . . . Ajc10 -->
- <sect1 id="antTasks-ajc" xreflabel="Ajc10 (ajc)">
- <title>Ajc10 (ajc)</title>
- <para>
- This task handles the same arguments as those used by the AspectJ 1.0 task.
- This should permit those with existing build scripts using the Ajc Ant
- task to continue using the same scripts when compiling with 1.1.
- This will list any use of options no longer supported in 1.1
- (e.g., <literal>lenient, strict, workingdir, preprocess, usejavac</literal>,...),
- and does not provide access to the new features of AspectJ 1.1.
- (Developers using AspectJ 1.1 only should upgrade their scripts
- to use AjcTask instead. This will not work for AspectJ 1.2 or later.)
- </para>
-
- <sect2 id="antTasks-ajc-options" xreflabel="Ajc10 (ajc) Options">
- <title>Ajc10 (ajc) Options</title>
- <para>
- </para>
- <para>
- Most attributes and nested elements are optional.
- The compiler requires that the same version of
- <literal>aspectjrt.jar</literal>
- be specified on the classpath, and that some sources be
- be specified
- (using one or more of
- <literal>argfiles</literal> and
- <literal>srcdir</literal> (with patterns)).
- </para>
- <para>Boolean parameters default to <literal>false</literal>
- unless otherwise stated.
- </para>
-
- <!-- . . . . . . . . . . . . . . . . ajc options table -->
- <table>
- <title>AjcTask (ajc) options for specifying sources</title>
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Attribute</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry><para>srcdir
- </para></entry>
- <entry><para>
- The base directory of the java files.
- See
- </para></entry>
- </row>
- <row>
- <entry><para>destdir
- </para></entry>
- <entry><para>
- The target directory for the output .class files
- </para></entry>
- </row>
- <row>
- <entry><para>includes
- </para></entry>
- <entry><para>
- Comma-separated list of patterns of files that must be included.
- No files are included when omitted.
- </para></entry>
- </row>
- <row>
- <entry><para>includesfile
- </para></entry>
- <entry><para>
- The path to a file containing include patterns.
- </para></entry>
- </row>
- <row>
- <entry><para>excludes
- </para></entry>
- <entry><para>
- Comma-separated list of patterns of files that must be excluded.
- No files (except default excludes) are excluded when omitted.
- </para></entry>
- </row>
- <row>
- <entry><para>excludesfile
- </para></entry>
- <entry><para>
- The path to a file containing exclude patterns.
- </para></entry>
- </row>
- <row>
- <entry><para>defaultexcludes
- </para></entry>
- <entry><para>
- If true, then default excludes are used.
- Default excludes are used when omitted
- (i.e., defaults to <literal>true</literal>).
- </para></entry>
- </row>
- <row>
- <entry><para>classpath, classpathref
- </para></entry>
- <entry><para>
- The classpath to use,
- optionally given as a reference to a classpath Path
- element defined elsewhere.
- </para></entry>
- </row>
- <row>
- <entry><para>bootclasspath, bootclasspathref
- </para></entry>
- <entry><para>
- The bootclasspath to use,
- optionally given as a reference to a bootclasspath Path
- element defined elsewhere.
- </para></entry>
- </row>
- <row>
- <entry><para>extdirs
- </para></entry>
- <entry><para>
- Paths to directories containting installed extensions.
- </para></entry>
- </row>
- <row>
- <entry><para>debug
- </para></entry>
- <entry><para>
- If true, emit debug info in the .class files.
- </para></entry>
- </row>
- <row>
- <entry><para>deprecation
- </para></entry>
- <entry><para>
- If true, emit messages about use of deprecated API.
- </para></entry>
- </row>
- <row>
- <entry><para>verbose
- </para></entry>
- <entry><para>
- Emit compiler status messages during the compile.
- </para></entry>
- </row>
- <row>
- <entry><para>version
- </para></entry>
- <entry><para>
- Emit version information and quit.
- </para></entry>
- </row>
- <row>
- <entry><para>failonerror
- </para></entry>
- <entry><para>
- If true, throw BuildException to halt build if there
- are any compiler errors.
- If false, continue notwithstanding compile errors.
- Defaults to <literal>true</literal>.
- </para></entry>
- </row>
- <row>
- <entry><para>source
- </para></entry>
- <entry><para>
- Value of -source option - ignored unless <literal>1.4</literal>.
- </para></entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table>
- <title>Parameters ignored by the old ajc taskdef,
- but now supported or buggy</title>
- <tgroup cols="3">
- <thead>
- <row>
- <entry>Attribute</entry>
- <entry>Description</entry>
- <entry>Supported?</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry><para>encoding
- </para></entry>
- <entry><para>Default encoding of source files.
- </para></entry>
- <entry><para>yes
- </para></entry>
- </row>
- <row>
- <entry><para>optimize
- </para></entry>
- <entry><para>
- Whether source should be compiled with optimization.
- </para></entry>
- <entry><para>yes?
- </para></entry>
- </row>
- <row>
- <entry><para>target
- </para></entry>
- <entry><para>
- Generate class files for specific VM version, one of
- [<literal>1.1 1.2</literal>].
- </para></entry>
- <entry><para>yes
- </para></entry>
- </row>
- <row>
- <entry><para>depend
- </para></entry>
- <entry><para>
- Enables dependency-tracking.
- </para></entry>
- <entry><para>no
- </para></entry>
- </row>
- <row>
- <entry><para>includeAntRuntime
- </para></entry>
- <entry><para>
- Whether to include the Ant run-time libraries.
- </para></entry>
- <entry><para>no
- </para></entry>
- </row>
- <row>
- <entry><para>includeJavaRuntime
- </para></entry>
- <entry><para>
- Whether to include the run-time libraries from the executing VM.
- </para></entry>
- <entry><para>no
- </para></entry>
- </row>
- <row>
- <entry><para>threads
- </para></entry>
- <entry><para>Multi-threaded compilation
- </para></entry>
- <entry><para>no
- </para></entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <para>
- The following table shows that many of the unique parameters in
- AspectJ 1.0 are no longer supported.
- </para>
- <table>
- <title>Parameters unique to ajc</title>
- <tgroup cols="3">
- <thead>
- <row>
- <entry>Attribute</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry><para>X
- </para></entry>
- <entry><para>
- deprecated X options include
- reweavable (on by default)
- reweavable:compress (compressed by default)
- </para></entry>
- </row>
- <row>
- <entry><para>emacssym
- </para></entry>
- <entry><para>
- Generate symbols for Emacs IDE support.
- </para></entry>
- </row>
- <row>
- <entry><para>argfiles
- </para></entry>
- <entry><para>
- A comma-delimited list of argfiles that contain a line-delimited
- list of source file paths (absolute or relative to the argfile).
- </para></entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
-
- <sect3>
- <title>argfiles - argument list files</title>
- <para>
- An argument file is a file (usually <literal>{file}.lst</literal>)
- containing a list of source file paths
- (absolute or relative to the argfile).
- You can use it to specify all source files to be compiled,
- which ajc requires to avoid searching every possible source file
- in the source path when building aspects.
- If you specify an argfile to the ajc task, it will not include all
- files in any specified source directory (which is the default
- behavior for the Javac task when no includes are specified).
- Conversely, if you specify excludes, they will be removed from
- the list of files compiled even if they were specified
- in an argument file.
- </para>
- <para>
- The compiler also accepts arguments that are not source files,
- but the IDE support for such files varies, and Javac does not
- support them. Be sure to include exactly one argument on each line.
- </para>
- </sect3>
- </sect2>
-
- <sect2 id="antTasks-ajc-nested">
- <title>Ajc10 parameters specified as nested elements</title>
- <para>
- This task forms an implicit FileSet and supports all attributes of
- <literal><fileset></literal> (dir becomes srcdir) as well as
- the nested
- <literal><include></literal>,
- <literal><exclude></literal>, and
- <literal><patternset></literal> elements.
- These can be used to specify source files.
- </para>
- <para>
- <literal>ajc</literal>'s
- <literal>srcdir</literal>,
- <literal>classpath</literal>,
- <literal>bootclasspath</literal>,
- <literal>extdirs</literal>, and
- <literal>jvmarg</literal>
- attributes are path-like structures and can also be set via nested
- <literal><src></literal>,
- <literal><classpath></literal>,
- <literal><bootclasspath></literal>,
- <literal><extdirs></literal>, and
- <literal><jvmargs></literal> elements, respectively.
- </para>
-
- </sect2>
-
- <sect2 id="antTasks-ajc-sample" xreflabel="Sample of ajc task">
- <title>Sample of ajc task</title>
- <para>
- Following is a declaration for the ajc task and a sample invocation
- that uses the ajc compiler to compile the files listed in
- <literal>default.lst</literal> into the dest dir:
- </para>
- <programlisting><![CDATA[
- <project name="example" default="compile" >
- <taskdef name="ajc"
- classname="org.aspectj.tools.ant.taskdefs.Ajc10" >
- <!-- declare classes needed to run the tasks and tools -->
- <classpath>
- <pathelement location="${home.dir}/tools/aspectj/lib/aspectjtools.jar"/>
- </classpath>
- </taskdef>
-
- <target name="compile" >
- <mkdir dir="dest" />
- <ajc destdir="dest" argfiles="default.lst" >
- <!-- declare classes needed to compile the target files -->
- <classpath>
- <pathelement location="${home.dir}/tools/aspectj/lib/aspectjrt.jar"/>
- </classpath>
- </ajc>
- </target>
- </project>
- ]]></programlisting>
- <para>
- This build script snippet
- </para>
- <programlisting><![CDATA[
- <ajc srcdir="${src}"
- destdir="${build}"
- argfiles="demo.lst"
- />
- ]]></programlisting>
- <para>
- compiles all .java files specified in the demo.lst and stores the .class files in the ${build} directory. Unlike the Javac task, the includes attribute is empty by default, so only those files specified in demo.lst are included.
- </para>
- <para>
- This next example
- </para>
- <programlisting><![CDATA[
- <ajc srcdir="${src}"
- destdir="${build}"
- includes="spacewar/*,coordination/*"
- excludes="spacewar/Debug.java"
- />
- ]]></programlisting>
- <para>
- compiles .java files under the <literal>${src}</literal> directory in the
- spacewar and coordination packages, and stores the .class files in the
- <literal>${build}</literal> directory.
- All source files under spacewar/ and coordination/ are used, except Debug.java.
- </para>
- <para>
- See <ulink url="../examples/build.xml">../examples/build.xml</ulink>
- for an example build script.
- </para>
- </sect2>
-
- </sect1>
-
- <!-- . . . . . . . . . . . . . . . . . . . . . . . . . . . problems -->
- <sect1 id="antTasks-problems">
- <title>Isolating problems running the Ant tasks</title>
-
- <para>
- If you have problems with the tasks not solved by the documentation,
- please try to see if you have the same problems when running ajc
- directly on the command line.
- </para>
- <itemizedlist>
- <listitem><para>
- If the problem occurs on the command line also, then the problem
- is not in the task.
- (It may be in the tools; please send bug reports.)
- </para></listitem>
- <listitem><para>
- If the problem does not occur on the command line, then it may
- lie in the parameters you are supplying in Ant or in the task's
- handling of them.
- </para></listitem>
- <listitem><para>
- If the build script looks correct and the problem only occurs when
- building from Ant, then please send a report
- (including your build file, if possible).
- </para></listitem>
- </itemizedlist>
-
- <sect2 id="antTasks-knownProblems">
- <title>Known issues with the Ant tasks</title>
- <para>
- For the most up-to-date information on known problems,
- see the
- <ulink url="http://bugs.eclipse.org/bugs">bug database</ulink>
- for unresolved
- <ulink url="http://bugs.eclipse.org/bugs/buglist.cgi?&product=AspectJ&component=Compiler&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED">
- compiler bugs
- </ulink> or
- <ulink url="http://bugs.eclipse.org/bugs/buglist.cgi?&product=AspectJ&component=Ant&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED">
- taskdef bugs
- </ulink>.
- </para>
- <para>
- When running Ant build scripts under Eclipse 2.x variants, you will get a
- VerifyError because the Eclipse Ant support fails to isolate the Ant runtime
- properly. To run in this context, set up iajc to fork (and use forkclasspath).
- Eclipse 3.0 will fork Ant processes to avoid problems like this.
- </para>
- <para>
- Memory and forking: Users email most often about the ajc task running
- out of memory.
- This is not a problem with the task; some compiles take a lot of
- memory, often more than similar compiles using javac.
- </para>
- <para>
- Forking is now supported in both the
- <xref linkend="antTasks-adapter"/> and
- <xref linkend="antTasks-iajc"/>,
- and you can set the maximum memory available.
- You can also not fork and increase the memory available to Ant
- (see the Ant documentation, searching for ANT_OPTS,
- the variable they use in their scripts to pass VM options,
- e.g., ANT_OPTS=-Xmx128m).
- </para>
- </sect2>
- <sect2 id="antTasks-feedback">
- <title>Ant task questions and bugs</title>
- <para>
- For questions, you can send email to
- <ulink url="mailto:aspectj-users@dev.eclipse.org">
- aspectj-users@dev.eclipse.org</ulink>.
- (Do join the list to participate!)
- We also welcome any bug reports, patches, and features;
- you can submit them to the bug database at
- <ulink url="http://bugs.eclipse.org/bugs">
- http://bugs.eclipse.org/bugs</ulink>
- using the AspectJ product and Ant component.
- </para>
- </sect2>
- </sect1>
- </chapter>
-
- <!-- Local variables: -->
- <!-- fill-column: 79 -->
- <!-- sgml-local-ecat-files: devguide.ced -->
- <!-- sgml-parent-document:("devguide.sgml" "book" "refentry") -->
- <!-- End: -->
|