123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407 |
- <chapter id="ajbrowser" xreflabel="AspectJ Browser">
-
- <title>AspectJ Browser</title>
-
- <sect1 id="ajbrowser-intro">
- <para>
- AJBrowser presents a GUI for compiling programs with ajc
- and navigating crosscutting structure.
- </para>
- <para>
- The AspectJ Browser can edit program source files,
- compile using the AspectJ compiler <literal>ajc</literal>
- run a program,
- and graphically navigate the program's
- crosscutting structure.
- For more information on <literal>ajc</literal>,
- see <xref linkend="ajc-ref"/>.
-
-
- </para>
-
- <para>
- Launch the browser from the command line either
- by typing "ajbrowser" to invoke the script in
- <literal>{aspectj}/bin</literal>
- (if AspectJ is installed correctly)
- or by using the
- <literal>aspectjtools.jar</literal> directly,
- and specifying no arguments or some number of
- build configuration files
- (suffix <literal>.lst</literal>):
- <programlisting>
- java -jar aspectj1.1/lib/aspectjtools.jar aspectj1.1/doc/examples/spacewar/debug.lst
- </programlisting>
- </para>
-
- </sect1>
-
- <sect1>
- <title>Building Programs</title>
- <sect2>
- <title>Build Configurations</title>
-
- <para>A build configuration is a set of files to compile for a
- program (and optionally some additional compile arguments).
- Because <literal>ajc</literal> requires all sources to be specified
- (at least using the <literal>-sourceroots</literal> option),
- most users create <literal>.lst</literal> files that list
- the files to compile (one argument per line, globbing
- permitted - for more details, see <xref linkend="ajc-ref"/>).
- </para>
- <para>
- To work with a particular program, select the
- corresponding ".lst" build configuration file
- from the GUI using the File menu, "open" item,
- or by using the
- "Open Build Configuration" button
- (<inlinemediaobject>
- <imageobject>
- <imagedata fileref="openConfig.gif"/>
- </imageobject>
- </inlinemediaobject>).
-
- You can populate the build list from the command line
- by passing any number of ".lst" paths.
- (However, if you pass in any non-".lst" arguments,
- it will run the command-line compiler directly.)
- </para>
- <para>
- To switch between build configurations,
- select, add, or remove them
- using the corresponding toolbar buttons.
- </para>
- <para>Global build options are stored in an
- <literal>.ajbrowser</literal> file in your HOME directory.
- Edit these from the GUI by clicking the "Options" button
- or selecting the Tools menu item "Options...".
- This is how to set classpath, aspectpath, etc.
- </para>
- <para>The following sections walk through a build.
- </para>
- </sect2>
- <sect2>
- <title>Compiling a Program Build Configuration</title>
-
- <para>
- To compile click the "Build" button
- (<inlinemediaobject>
- <imageobject>
- <imagedata fileref="build.gif"/>
- </imageobject>
- </inlinemediaobject>), or
- or use the tools menu.
- </para>
- <para>To build using AspectJ 1.1's incremental mode,
- click the <literal>incremental compile</literal> checkbox in
- the <literal>AspectJ Build Options</literal> tab
- of the <literal>Options</literal> dialog.
- Once in incremental mode, you can force a full rebuild
- by holding the shift key down when selecting the
- build menu item or button.
- </para>
- <para>
- You may select
- from different build configurations in the GUI
- (see label 1 in the graphic below).
- (If you get classpath or other errors, set up the
- global build options as described above.)
- </para>
- <imageobject>
- <imagedata fileref="ajbrowser-building.gif"/>
- </imageobject>
- </sect2>
- </sect1>
-
- <sect1>
- <title>Navigating Program Structure</title>
-
- <para>
- Select nodes in the program structure by clicking them (see label 2).
- If one node is related to one or more other nodes by an association the
- name of the association will appear below that node and will be
- displayed in italics. Links to other structure nodes appear in blue
- below the association. If there is no corresponding source for the
- link it will appear light-blue.
- </para>
- <imageobject>
- <imagedata fileref="ajbrowser-building.gif"/>
- </imageobject>
-
- <sect2>
- <title>Example: Exploring the "Spacewar" sample code </title>
- <para>
- <itemizedlist>
-
- <listitem> <para>Launch <literal>ajbrowser</literal></para>
- </listitem>
-
- <listitem> Choose "File -> Open" or click the "Open Build
- Configuration" button
- (<inlinemediaobject>
- <imageobject>
- <imagedata fileref="openConfig.gif"/>
- </imageobject>
- </inlinemediaobject>) and select the configuration file for debugging
- the spacewar example, in
- <literal>examples/spacewar/debug.lst</literal>.
- </listitem>
-
- <listitem> <para>Click the "Build" button (<inlinemediaobject>
- <imageobject>
- <imagedata fileref="build.gif"/>
- </imageobject>
- </inlinemediaobject>) to
- compile. The left pane should fill with a spacewar declaration
- tree. If there is a compiler error, the clickable error message
- shows up as in label 4.
- </para>
-
- <para>Note: If you did not set up your classpath, the
- compile will fail with a message that you need to install
- aspectjrt.jar on your compile classpath. To do that, select "Tools
- -> Options" or click the "Options" button
- (<inlinemediaobject>
- <imageobject>
- <imagedata fileref="browseroptions.gif"/>
- </imageobject>
- </inlinemediaobject>). Click the <literal>Build Options</literal> tab
- to view the Build Paths pane. Edit the classpath entry to use your
- install location. For example, if you ran from the base Aspectj
- directory, the classpath need only include
- <literal>lib/aspectjrt.jar</literal> (though the browser may populate
- the classpath with the bootclasspath and classpath initially.)
- Be sure to use the
- <literal>lib/aspectjrt.jar</literal> that came with the browser.
- </para>
-
- <para>
- <imageobject>
- <imagedata fileref="ajbrowser-options.gif"/>
- </imageobject>
- </para>
-
- </listitem>
-
- <listitem> <para>Different structure views: The structure tree at the
- left can display different orderings and granularity for structure:
-
- <itemizedlist>
- <listitem> The package hierarchy view shows the traditional hierarchy
- of package, class, and members. </listitem>
-
- <listitem> The inheritance view shows the hierarchy from topmost
- parent classes through subclasses to members. </listitem>
-
- <listitem> The crosscutting view shows the aspect members
- and the code they affect. </listitem>
-
- <listitem> Additional buttons in the pane can be used to change the
- granularity and filter out items.
- </listitem>
-
- </itemizedlist>
-
- </para>
-
- <para>Whenever you select an item in the tree view, the
- source pane scrolls to that item. If you select a leaf item
- representing another program element, then the tree
- selection will go to the corresponding node. (See below for
- how to use two panes to maintain your place.)
- </para>
-
- </listitem>
- <listitem>
-
- <para>When working with aspects, it helps to be able to navigate
- between different program elements:
- </para>
-
- <itemizedlist>
-
- <listitem><para>When looking at a method, find the advice that
- affects it. </para></listitem>
-
- <listitem><para>When looking at a pointcut, find the advice that
- uses it. </para></listitem>
-
- <listitem><para>When looking at advice, find what it advises -
- e.g., method calls or executions, initializers, etc.
- </para></listitem>
-
- <listitem><para>When looking at a type, find any aspects that
- declare members or supertypes of the type, or
- vice-versa.
- </para></listitem>
-
- </itemizedlist>
-
- <para>You can view the advice on a particular method using the
- default, hierarchical view. Navigate to the tree item for
- <literal>spacewar.Registry.register(SpaceObject)</literal>
- in the <literal>debug.lst</literal> config file. Now, in
- the lower, file view, you can see and navigate to the advice
- using the subtree whose parent is the <literal>method
- affected by</literal> relation.
- </para>
-
- <para>You can also use crosscutting view to see the
- advice using a pointcut or the methods affected by advice.
- For example, to see what advice uses a particular pointcut,
- navigate to the tree item for the pointcut
- <literal>spacewar.Debug.allConstructorsCut()</literal> in
- the <literal>debug.lst</literal> config file. You can see
- and navigate to the advice that uses the pointcut using the
- <literal>pointcut used by</literal> relation.
- </para>
-
- <para>As an example of seeing the methods affected by advice,
- while still in the same view, select the first
- <literal>before</literal> advice in
- <literal>spacewar.Debug</literal>. It has relation
- sub-trees for both <literal>uses pointcut</literal> and
- <literal>affects constructions</literal>. The
- <literal>affects</literal> relations will list different
- kinds of join points - constructor or method calls, etc.
- </para>
- <para>Note that the AspectJ browser can only display
- static structure (whether hierarchical or crosscutting).
- That means that dynamicly-determined pointcuts (like
- <literal>cflow(pointcut)</literal>)
- will not be shown as picking out static points in
- source code. Displayable pointcuts roughly correspond
- to those that can be used in a
- <literal>declare error</literal> statement.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </sect2>
- </sect1>
- <sect1>
- <title>Running Programs</title>
- <para>
- The browser supports a limited form of running compiled programs.
- To run programs that have been built, click the run button
- or select one of the run menu items in the project menu.
- You can run in the same VM or spawn a new process;
- the latter is generally better for GUI programs.
- </para>
- <para>Both require that any classpath you set be specified
- using platform-specific paths and path separators (the
- compiler might be more tolerant).
- Output and error streams will be
- merged into the streams of the browser (using separate
- threads, so it may take a few seconds for the pipe
- threads to gain control.) Errors should
- be detected and displayed in a dialog.
- </para>
- <para>
- The GUI does not support killing a running program,
- so if your program might hang,
- be sure to save your files since you may need to
- kill the browser itself to kill its child processes.
- </para>
- </sect1>
-
- <sect1 id="ajbrowser-problems">
- <title>Isolating problems running the AspectJ browser</title>
-
- <para>
- If you have problems with the browser 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 browser.
- (It may be in the compiler; 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 the build options.
- </para></listitem>
- <listitem><para>
- If the build options look correct and the problem only occurs
- when building from the browser, then please submit a bug report.
- </para></listitem>
- </itemizedlist>
-
- <sect2 id="ajbrowser-knownProblems">
- <title>Known issues with the AspectJ browser</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=IDE&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED">
- IDE bugs
- </ulink>.
- </para>
- <para>
- <itemizedlist>
- <listitem><para>
- Memory and forking: Users email most about the browser task running
- out of memory.
- This is not a problem with the browser; some compiles take a lot of
- memory, often more than similar compiles using javac.
- The browser does not support forking, so the only solution is to
- edit the java command line or script that launches the browser
- to add memory.
- </para></listitem>
- <listitem><para>
- Editing build configuration files: this is not currently supported.
- </para></listitem>
- <listitem><para>
- The structure model is incomplete after incremental compiles.
- To get a complete structure model requires a full build.
- </para></listitem>
- <listitem><para>
- If you change the output directory, you must do a
- full build.
- </para></listitem>
- </itemizedlist>
- </para>
- </sect2>
- <sect2 id="ajbrowser-limitations">
- <title>Limitations</title>
- <para>
- <itemizedlist>
- <listitem><para>
- The AJBrowser expects the package and directory structure to match. If they do not
- it will be unable to browse to the corresponding file.
- </para></listitem>
- <listitem><para>
- The "Run" feature launches applications in the same VM. As a result, if a Swing application
- is disposed the AJBrowser will be disposed as well.
- </para></listitem>
- </itemizedlist>
- </para>
- </sect2>
- <sect2 id="ajbrowser-feedback">
- <title>AspectJ Browser questions and bugs</title>
- <para>
- 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 feature requests;
- 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 IDE component.
- </para>
- </sect2>
- </sect1>
- </chapter>
-
- <!-- Local variables: -->
- <!-- fill-column: 79 -->
- <!-- sgml-local-ecat-files: devguide.ced -->
- <!-- sgml-parent-document:("devguide.sgml" "book" "refentry") -->
- <!-- End: -->
|