réplica de
https://github.com/eclipse-aspectj/aspectj.git
synced 2024-08-26 05:57:44 +02:00
408 líneas
16 KiB
XML
408 líneas
16 KiB
XML
<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: -->
|