123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452 |
- <refentry id="ajdee">
- <refnamediv>
- <refname>AJDEE</refname>
- <refpurpose>JDEE support for XEmacs and GNU Emacs </refpurpose>
- </refnamediv>
-
- <refsect1>
- <title>AJDE for Emacs User's Guide</title>
- <para>
- This guide describes AspectJ-mode extensions of JDEE for GNU Emacs and
- XEmacs, which
- provides enhanced editing and management of AspectJ code via a minor
- mode extension of JDE mode. AJDEE's AspectJ support builds on
- <link linkend="aspectj-mode">aspectj-mode's</link> extension of
- java-mode, also provided with the release.
- Included in this document are guidance for AJDEE's <link
- linkend="ajdee-featuresandusage">use</link>, including an <link
- linkend="exploringspacewar">exploration of spacewar</link>, and <link
- linkend="ajdee-installationetc">installation and compatibility</link>. See
- the README file in AJDEE's distribution directory for
- release-specific details.
- </para>
-
- <para>
- In addition to the java-mode extensions provided by
- <link linkend="aspectj-mode">aspectj-mode</link>, AJDEE provides
- (see graphic):
- <itemizedlist>
- <listitem>
- <para>
- Viewing and navigation of aspect structures via the
- the speedbar and Classes menu.
- </para>
- </listitem>
-
- <listitem>
- <para>
- Basic support for completion.
- </para>
- </listitem>
-
- <listitem>
- <para>
- Integrated Javadoc support.
- </para>
- </listitem>
-
- </itemizedlist>
- </para>
-
- <para>
- <inlinemediaobject id="ajdeemacsscreenshot">
- <imageobject>
- <imagedata fileref="ajdee.gif"/>
- </imageobject>
- </inlinemediaobject>
- </para>
- </refsect1>
-
- <refsect1 id="ajdee-featuresandusage"><!-- Features and Usage -->
- <title>AJDEE Features and Usage</title>
- <para>
- The AJDEE extensions of JDE require no special effort to use.
- The speedbar and Classes menus provide additional sublists showing
- crosscutting structure. Selecting items in those lists navigates to
- the referenced item.
- </para>
-
- <refsect2>
- <title>Aspect Structure and Navigation</title>
-
- <refsect3>
- <title>Enhancements to Speedbar in JDE Mode</title>
- <para>
- As a minor mode of JDE mode, AJDEE enhances the speedbar to
- show the location of aspect, advice, and inter-type declarations.
- The affects/affected-by relationships are shown in the speedbar
- rather than embedding tags in the text (available as an option),
- and selecting the items in the speedbar will perform the expected
- navigation. The speedbar symbols have been extended for AspectJ as
- follows (see right side of <link
- linkend="ajdeemacsscreenshot">figure)</link>:
- </para>
-
- <table id="speedbarenhancements">
- <title>Enhancements to Speedbar in JDE Mode</title>
- <tgroup cols="2" colsep="1" rowsep="1" align="left">
- <thead>
- <row>
- <entry>Indication</entry>
- <entry>Meaning</entry>
- </row>
- </thead>
-
- <tbody>
- <row>
- <entry>
- <literal>(+) </literal>
- <emphasis><literal>name</literal></emphasis>
- </entry>
- <entry>
- A class, interface, or aspect; double mouse-1 will
- display its declarations
- </entry>
- </row>
-
- <row>
- <entry><literal>+ </literal>
- <emphasis><literal>methodSignature</literal></emphasis>
- </entry>
- <entry>
- Method has an advice that applies to it; double mouse-1
- will display the relevant advice.
- </entry>
- </row>
-
- <row>
- <entry><literal>+ </literal>
- <emphasis><literal>adviceSignature</literal></emphasis>
- </entry>
- <entry>
- Advice declared by the containing aspect; double mouse-1
- will display affected methods.
- </entry>
- </row>
-
- <row>
- <entry><literal>+ </literal>
- <emphasis><literal>introductionSig</literal></emphasis>
- </entry>
- <entry>
- Inter-type declaration declared by the containing class; double
- mouse-1 will display affected methods or classes.
- </entry>
- </row>
-
- <row>
- <entry><literal>| | </literal>
- <emphasis><literal>methodOrFieldSig</literal></emphasis>
- </entry>
- <entry>
- Method or field has been declared by an aspect;
- double mouse-1 on text will navigate to the declaration; a +
- within the bars means that it has an advice that applies
- to it.
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <para>
- A minus (<literal>-</literal>) is displayed on the item when the
- crosscutting items are displayed. AspectJ structure information is
- derived from the last compile of your AspectJ program.
- </para>
- </refsect3>
- </refsect2>
-
- <refsect2>
- <title>Compilation and JavaDoc</title>
-
- <para>
- The option <option>AspectJ Compile File Specification</option>
- can be customized from the <guisubmenu>Customize options</guisubmenu>
- under the <guimenu>AspectJ</guimenu> menu, changing the default
- compile specification given to <command>ajc</command>.
- See <link linkend="ajdee-installationetc">installation instructions</link>
- for examples and other customizations.
- </para>
-
- <para>
- AspectJ JavaDoc support is
- enabled by setting <option>Jde Javadoc Command Path</option> to
- invoke <command>ajdoc</command>. These are the default settings
- provided in the installation instructions.
- </para>
- </refsect2>
-
- </refsect1>
-
- <refsect1 id="exploringspacewar"><!-- Exploring the Spacewar Source Code -->
- <title>Exploring the Spacewar Source Code</title>
- <para>
- To begin exploring Spacewar within emacs using JDE and AspectJ mode:
- </para>
- <itemizedlist>
- <listitem>
- <para>Compile spacewar.</para>
- </listitem>
-
- <listitem>
- <para>Change into the <filename>spacewar</filename>
- directory.</para>
- </listitem>
-
- <listitem>
- <para>Type <userinput>emacs Ship.java</userinput>.</para>
- </listitem>
-
- <listitem>
- <para>
- Pull down the <guimenu>JDE</guimenu> menu and select the
- <guimenuitem>Speedbar</guimenuitem> entry to show the AspectJ
- files in the directory. Note that <filename>Ship.java</filename>
- is shown in red to denote that it is currently shown in the main
- buffer.
- </para>
- </listitem>
-
- <listitem>
- <para>
- Double-click with the left mouse button on the
- <literal>+</literal> in front of the
- <filename>Ship.java</filename> entry. It should display an entry
- for the class <classname>Ship</classname>.
- </para>
- </listitem>
-
- <listitem>
- <para>
- Double-clicking on Ship will navigate to its declaration in
- the buffer. Note that declarations of advice are annotated to
- note the types of objects that they advise, declarations of
- methods that are advised are annotated with the aspects that
- advise them, and so forth.
- </para>
- </listitem>
-
- <listitem>
- <para>
- Double-clicking on the <literal>+</literal> in front of either
- will show the declared fields, methods, inter-type declarations, and
- advice. A <literal>+</literal> in front of any field or method
- means that it is introduced or advised; double-clicking will list
- entries for the introducers/advisers; double-clicking on them
- will navigate to their declarations. A <literal>+</literal> in
- front of any inter-type declarations or advice will will display its
- targets.
- </para>
- </listitem>
-
- </itemizedlist>
- </refsect1>
-
- <refsect1 id="ajdee-installationetc"><!-- Installation and Compatibility -->
- <title>Installation and Compatibility</title>
-
- <para> AJDEE requires the installation of
- <ulink url="http://sunsite.auc.dk/jde">JDE 2.2.9beta4</ulink> or
- higher and small edits to your <filename>.emacs</filename> file to
- configure AJDEE and enable autoloading AJDEE when a
- <filename>.java</filename> file is loaded.
- </para>
-
- <refsect2>
- <title>Installation for enhancement of JDE mode</title>
-
- <!-- <note> -->
- <para>
- The first and last steps, with enhancements, can be found in the
- example Emacs initialization file
- <filename>sample.emacs</filename> and the sample JDE project
- file <filename>sample.prj</filename> in the distribution. The
- latter also demonstrates a way to enable AspectJ mode on a
- per-project basis.
- </para>
- <!-- </note> -->
-
- <orderedlist>
- <listitem>
- <para>
- Make sure AJDEE, aspectj-mode, JDE, and supporting packages are on
- your <literal>load-path</literal> and are ``required''. This is an
- example for the 1.0 release:
- <programlisting>
- ;; I keep my emacs packages in C:/Emacs
- (setq load-path
- (append
- '(
- "C:/Emacs/aspectj-emacsMode-1.0" ; for AJDEE
- "C:/Emacs/aspectj-emacsAJDEE-1.0"
- "C:/Emacs/jde-2.2.9beta6/lisp"
- "C:/Emacs/elib-1.0" ; for JDEE
- "C:/Emacs/speedbar-0.14beta2" ; for JDEE
- "C:/Emacs/semantic-1.4beta12" ; for JDEE/speedbar
- "C:/Emacs/eieio-0.17beta3" ; for JDEE
- )
- load-path))
-
- (require 'jde)
- (require 'ajdee) ; can also appear in prj.el</programlisting>
- </para>
- </listitem>
-
- <listitem>
- <para>
- <emphasis>[Optional]</emphasis> add <literal>-emacssym</literal>
- switch to the <filename>ajc</filename> and <filename>ajc.bat</filename>
- files in your AspectJ tools installations (in the
- <filename>/bin</filename> directory). If you invoke the compiler
- outside Emacs, this will
- ensure that your compiles always generate information for annotations
- and the jump menu in the form of <literal>.ajesym</literal> files.
- </para>
- </listitem>
-
- <listitem>
- <para>
- Customize AJDEE's compile options by
- putting a version of the following in your
- <filename>.emacs</filename> file or in a JDE project file
- <filename>prj.el</filename> in your project's hierarchy (see the
- <option>JDE Project File Name</option> option for the latter).
- Here is a simple example:
-
- <programlisting>
- ;; A default version for simple projects, maybe good for
- ;;; .emacs file.
- (custom-set-variables
- '(jde-compiler '("ajc" "ajc"))
- '(jde-javadoc-command-path "ajdoc")
-
- ;; ajc requires all files to be named for a compile
- '(aspectj-compile-file-specification "*.java"))</programlisting>
-
- Here is an example for spacewar, in
- <filename>examples/spacewar</filename>.
- <programlisting>
- ;;; These options are for the spacewar, in examples/spacewar.
- (custom-set-variables
- '(jde-compiler '("ajc" "ajc"))
- '(jde-javadoc-command-path "ajdoc")
-
- ;; ajc provides an ``argfile'' mechanism for specifying all files.
- '(aspectj-compile-file-specification "-argfile demo.lst")
-
- ;; *if* compiling packages, name root dir for package hierarchy
- ;; to tell ajc where .class files should go.
- '(jde-compile-option-directory "..")
- '(jde-run-working-directory ".."))
- '(jde-run-application-class "spacewar.Game")</programlisting>
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis>[XEmacs only]</emphasis> If you're installing JDE
- yourself, be sure to closely follow the JDE installation
- directions for XEmacs, otherwise you may get out of date JDE
- <filename>.jar</filename> files.
- </para>
- </listitem>
- </orderedlist>
-
- </refsect2>
-
- <refsect2>
- <title>Customizing Options</title>
- <para>
- Selecting <guimenuitem>Customize options</guimenuitem> from the
- <guimenu>AspectJ</guimenu> menu displays a number of options that
- customize AspectJ mode. These control whether annotations are shown
- by default, and whether the bovinator set up by JDE runs.
- <option>AspectJ Compile File Specification</option>, specifies a
- compilation argument as
- an alternative to the current buffer's file or the run class's file.
- Example customizations are shown above and in the sample files
- discussed above.
- </para>
- </refsect2>
-
- </refsect1>
-
-
- <refsect1>
- <title>Usage and Upgrade Problems</title>
-
- Please see the documentation for
- <link linkend="aspectj-mode">aspectj-mode</link> for problems not
- specific to AJDEE's features.
-
- <itemizedlist>
-
- <listitem>
- <para><emphasis>Symptom</emphasis>: Get
- standard speedbar menus in JDE; no annotations display. Message:
-
- <screen>
- AspectJ Mode Warning: Can't find declarations file for...
- </screen>
-
- </para>
-
- <para>AspectJ file has not been compiled with ajc and the <literal>-emacssym</literal>
- flag,
- or was compiled with an obsolete version of ajc. After compilation,
- there should be a <file>.ajesym for every <file>.java in the
- build. If .ajsym files are present but error persists, recompile. Note
- that aspectj-mode for JDE has a fallback view for uncompiled files.
- </para>
- </listitem>
-
- <listitem>
- <para><emphasis>Symptom</emphasis>: Navigations via the speedbar and
- the jump menu are off, annotations are misplaced in the code. </para>
-
- <para>AspectJ mode operates by querying data
- derived from the most recent compile that includes the
- <literal>-emacssym</literal> flag. Recompile the entire program with
- ajc including the switch. Consider permanently installing the switch
- by editing the ajc and ajc.bat files in the /bin file in your
- distribution.</para>
- </listitem>
-
- <listitem>
- <para><emphasis>Symptom</emphasis>: Java files that are part of a Java project not written
- in AspectJ come up in aspectj-mode. </para>
-
- <para>Emacs uses the file suffix (.java) to
- determine which mode to invoke. You can either globally toggle the
- AspectJ features from the AspectJ menu, or you can prevent AJDEE
- from coming up by moving the (require 'ajdee) expression from
- your .emacs file to a prj.el file in each AspectJ project's directory
- (see sample.prj in the distribution).
- </para>
- </listitem>
-
- <listitem>
- <para><emphasis>Symptom</emphasis>: Reported bug fixes and new features
- to AJDEE are not seen, or ajdee.el cannot be found or loaded, with
- message:
-
- <screen>
- Error in init file: File error: "Cannot open load file", "ajdee"
- </screen>
-
- </para>
- <para>Your load-path variable (set in your .emacs)
- is referring to an old release. Change your load-path to
- point at the directory for the current release. See the sample.emacs
- files in the distribution, for example.</para>
- </listitem>
- </itemizedlist>
- </refsect1>
- </refentry>
-
- <!-- Local variables: -->
- <!-- fill-column: 79 -->
- <!-- compile-command: "ant -quiet dev-html" -->
- <!-- sgml-local-ecat-files: devguide.ced -->
- <!-- sgml-parent-document:("devguide.sgml" "book" "refentry") -->
- <!-- End: -->
|