From 741181e71756adc5cad84a09b6f55ca945171feb Mon Sep 17 00:00:00 2001 From: wisberg Date: Fri, 3 Mar 2006 10:17:58 +0000 Subject: warn about duplicate sources, convert exampled to -inpath, corrected -inpath aspects and argument file descriptions, linked out to affected types and load-time weaving, deprecated -emacsym as untested/unsupported. Leaving -messageHolder undocumented (Adrian's choice, if I recall correctly - not sure why) --- docs/devGuideDB/ajc.xml | 100 +++++++++++++++++++++++++++--------------------- 1 file changed, 56 insertions(+), 44 deletions(-) (limited to 'docs') diff --git a/docs/devGuideDB/ajc.xml b/docs/devGuideDB/ajc.xml index a9d21962c..1f1623577 100644 --- a/docs/devGuideDB/ajc.xml +++ b/docs/devGuideDB/ajc.xml @@ -19,38 +19,40 @@ Description - The ajc command compiles AspectJ and Java - language files, weaving aspects as necessary to produce .class files - compliant with any Java VM (1.1 or later). - To do bytecode weaving, it also accepts input classes or aspects - in binary form. + The ajc command compiles and weaves AspectJ and + Java source and .class files, producing .class files compliant with any + Java VM (1.1 or later). It combines compilation and bytecode weaving + and supports incremental builds; you can also weave bytecode + at run-time using . The arguments after the options specify the source file(s) to compile. - (Specify source classes using the -injars or - -inpath options, below.) - Files may be listed directly on the command line, or listed in a file. + To specify source classes, use -inpath (below). + Files may be listed directly on the command line or in a file. The -argfile file and @file forms - are equivalent, and are interpreted as meaning all the files listed in - the specified file. Each line in these files should contain one option - or filename. Comments, as in Java, start with // and - extend to the end of the line. + are equivalent, and are interpreted as meaning all the arguments + listed in the specified file. - NB: - You must explicitly pass ajc all sources necessary - for the compilation. When compiling source files containing aspects - or pointcuts, be sure - to include the source files for any types affected by the aspects or - picked out by the pointcuts. - (To exclude types from the scope affected by the aspect, - change the corresponding pointcut or declaration.) - This is necessary because, unlike javac, ajc does not search the - sourcepath for classes. - You may use the -sourceroots option to specify - as source all the .aj and .java files in a set of directory trees. + Note: + You must explicitly pass ajc all necessary sources. + Be sure to include the source not only for the + aspects or pointcuts but also for any affected types. + Specifying all sources is necessary because, unlike javac, ajc does not + search the sourcepath for classes. + (For a discussion of what affected types might be required, + see The AspectJ + Programming Guide, Implementation Appendix.) + + + To specify sources, you can list source files as arguments or use the + options -sourceroots or -inpath. + If there are multiple sources for any type, the result is undefined + since ajc has no way to determine which source is correct. (This + happens most often when users include the destination directory + on the inpath and rebuild.) @@ -82,11 +84,11 @@ -aspectpath Path - Weave binary aspects from Jars and directories on path into all sources. + Weave binary aspects from jar files and directories on path into all sources. The aspects should have been output by the same version of the compiler. - To run the output classes requires putting all the - aspectpath entries on the run classpath. + When running the output classes, the run classpath should contain + all aspectpath entries. Path, like classpath, is a single argument containing a list of paths to jar files, delimited by the platform- specific classpath delimiter. @@ -96,9 +98,20 @@ -argfile File - The file is a line-delimited list of arguments. - These arguments are inserted into the argument list. - + The file contains a line-delimited list of arguments. + Each line in the file should contain one option, filename, or + argument string (e.g., a classpath or inpath). + Arguments read from the file are inserted into the argument list + for the command. Relative paths in the file are calculated from + the directory containing the file (not the current working directory). + Comments, as in Java, start with // and + extend to the end of the line. Options specified in argument + files may override rather than extending existing option values, + so avoid specifying options like -classpath + in argument files unlike the argument file is the only build + specification. The form @file is the same + as specifying -argfile file. + @@ -155,7 +168,7 @@ -emacssym - Generate .ajesym symbol files for emacs support + Generate .ajesym symbol files for emacs support (deprecated). @@ -244,8 +257,8 @@ - -target [1.1 to 1.4] - Specify classfile target setting (1.1 to 1.4, default is 1.2) + -target [1.1 to 1.5] + Specify classfile target setting (1.1 to 1.5, default is 1.2) @@ -415,7 +428,8 @@ -Xnoweave (Experimental) produce unwoven class files - for input using -injars. + for input using -injars. (deprecated - .class files are by + default reweavable and can be input using -inpath.) @@ -580,18 +594,16 @@ ajc @sources.lst - An example using -injars and -aspectpath - Bytecode weaving using -injars: - AspectJ 1.1 supports weaving from input zip or jar files containing - class files. Using input jars is like compiling the corresponding + An example using -inpath and -aspectpath + Bytecode weaving using -inpath: + AspectJ 1.2 supports weaving .class files in input zip/jar files + and directories. + Using input jars is like compiling the corresponding source files, and all binaries are emitted to output. Although Java-compliant compilers may differ in their output, ajc should take as input any class files produced by javac, jikes, eclipse, - and, of course, ajc. Aspects included in -injars will be woven into - like other .class files, but they will specify any crosscutting - code (i.e., they will not be woven into other types). To use - aspects in their binary form to specify crosscutting, - see -aspectpath below. + and, of course, ajc. Aspects included in -inpath will be woven into + like other .class files, and they will affect other types as usual. Aspect libraries using -aspectpath: AspectJ 1.1 supports weaving from read-only libraries containing @@ -674,7 +686,7 @@ commands to your environment as needed. (b) Build the application with tracing: - ajc -injars app.jar -aspectpath tracelib.jar -outjar tracedapp.jar + ajc -inpath app.jar -aspectpath tracelib.jar -outjar tracedapp.jar -- cgit v1.2.3