org.aspectj/docs/developer/IDE.md

# Setting up an AspectJ development environment

_by Alexander Kriegisch, originally published on 2021-08-05_

AspectJ, being an Eclipse project, can of course be used in the Eclipse IDE for Java developers, if you also install the
AspectJ Development Tools (AJDT). IntelliJ IDEA also offers AspectJ and Spring AOP support. Regarding build tools, there
are AspectJ plugins for Maven, Gradle, Mill and Ant.

Of course, you can use and other IDE and build tool or simply use your trusted text editor of choice and compile using
the AspectJ Compiler _ajc_ from the command line.

Please refer to the [AspectJ Development Environment Guide](../devguide/index.adoc)
for more details about on-board AspectJ tools, such as _ajc_ (compiler), _ajdoc_ (aspect-enriched Javadoc), _aj_
(load-time weaving helper) as well as basic information about load-time weaving configuration and the built-in Ant task
for AspectJ.

## IDE support

We are going to focus on the two IDEs the author of this document is acquainted with, Eclipse and IntelliJ IDEA. That
does not mean that others such as NetBeans or the increasingly popular editor-on-steroids Visual Studio Code might not
also be excellent choices, but I simply do not know them, sorry.

### Eclipse

If you install [AspectJ Development Tools (AJDT)](https://www.eclipse.org/ajdt/), you can use AspectJ in the Eclipse
Java IDE. For the last few years, AJDT has rather been kept alive than actively developed, but still it works nicely for
the usual tasks, such as writing aspects in both native and annotation-style syntax, viewing cross-references between
aspects and Java code, applying all sorts of weaving strategies (compile-time weaving, post-compile binary weaving,
load-time weaving) and with an additional m2e (Maven to Eclipse) connector also for importing and refreshing from
projects using AspectJ Maven Plugin.

#### AspectJ Development Tools (AJDT)

Use an update site corresponding to your Eclipse version (minimal version listed):
// AspectJ_JDK_Update: add new release to table
* Eclipse 2024-03 (4.31), AspectJ 1.9.22, Java 22: https://download.eclipse.org/tools/aspectj/ajdt/431/dev/update
* Eclipse 2023-12 (4.30), AspectJ 1.9.21, Java 21: https://download.eclipse.org/tools/aspectj/ajdt/430/dev/update<br>
  **Please note:** In Eclipse 2023-12, you should also add
  https://download.eclipse.org/eclipse/updates/4.31-I-builds/I20231201-1800/ in addition to the regular release update
  sites https://download.eclipse.org/eclipse/updates/4.30/ or https://download.eclipse.org/releases/latest. This is,
  because AspectJ 1.9.21 contains support for JDK 21 string templates, which was added to the compiler after the 2023-12
  release, but also includes a few Eclipse API changes requiring the additional update site. After adding it, please
  make sure to call _Help_ → _Check for Updates_ and accept the updates.
* Eclipse 2022-12 (4.26), AspectJ 1.9.19, Java 19: https://download.eclipse.org/tools/aspectj/ajdt/426/dev/update
* Eclipse 2022-03 (4.23), AspectJ 1.9.19, Java 19: https://download.eclipse.org/tools/aspectj/ajdt/423/dev/update
* Eclipse 2021-09 (4.21), AspectJ 1.9.8, Java 17: https://download.eclipse.org/tools/aspectj/ajdt/421/dev/update
* Eclipse 2021-03 (4.19), AspectJ 1.9.7, Java 16: https://download.eclipse.org/tools/aspectj/ajdt/419/dev/update
* Eclipse 2018-12 (4.10), AspectJ 1.9.6, Java 14: https://download.eclipse.org/tools/aspectj/ajdt/410/dev/update
* For older versions, please refer to https://www.eclipse.org/ajdt/downloads (page was not updated in a long time,
  and I have no write access).

#### Maven to Eclipse (m2e) connector

The connector between AspectJ Maven Plugin and AJDT has not been maintained by the AspectJ team for some years, but
there is a fairly up-to-date [fork by Miika Vesti (joker1)](https://github.com/joker1/m2eclipse-ajdt) with the following
update sites:
  * Eclipse 2022-12 (4.26): https://repo.t5.fi/public/eclipse/m2eclipse-ajdt/eclipse-2022-12/
  * Eclipse 2020-12 (4.18): https://repo.t5.fi/public/eclipse/m2eclipse-ajdt/eclipse-2020-12/
  * Eclipse 2019-06 (4.12): https://repo.t5.fi/public/eclipse/m2eclipse-ajdt/eclipse-2019-06/

Your AspectJ-related list of Eclipse update sites could look like this for Eclipse 2023-12:

![Eclipse IDE filtered list of update sites](images/EclipseSoftwareSitesAJDT.png)

### IntelliJ IDEA

IDEA is a commercial IDE by JetBrains, which also has a free Community Edition. The author of this guide uses a
complementary Ultimate Edition provided by JetBrains (thank you!), because he is an active open source developer (ask
them if you are eligible, too). If you want to use the Ultimate Edition for commercial purposes, however, of course you
need to buy it. According to [this resource](https://www.jetbrains.com/help/idea/aspectj.html), the AspectJ plugin is
for the Ultimate Edition only, so probably the plugin is not going to work in the Community Edition. But if you are
using AspectJ in your daytime job, probably you use the Ultimate Edition anyway.

Make sure that the following plugins are active:
  * AOP Pointcut Language (bundled): basic AspectJ and Spring AOP pointcut syntax support (annotation style)
  * AspectJ (marketplace, author JetBrains): native AspectJ support

If the Maven support bundled into IntelliJ IDEA is active as well, Maven projects using the AspectJ Maven Plugin will
also be imported correctly. I never tested with any of the Gradle plugins or the AspectJ Ant task because I am a Maven
user, so please try for yourself if those combinations are supported.

## Build tools

### Maven

If you want to build your AspectJ projects with Maven, use [AspectJ Maven Plugin](https://github.com/dev-aspectj/aspectj-maven-plugin)
by AspectJ.dev, artifact ID `dev.aspectj:aspectj-maven-plugin`. It is a fork of the original plugin by MojoHaus, which
was inactive for several years and even now shows no activity other than AspectJ version bumps. Because the AspectJ.dev
version has more features and is actively maintained by Alexander Kriegisch from the AspectJ core team, we recommend
using it instead of the Mojohaus version.

### Gradle

In contrast to Maven, there is no de-facto standard build plugin for Gradle, but a bunch of more or less well-maintained
plugins with a more or less complete feature set. I am not a Gradle user, but when answering related questions on
Stack Overflow, I got the impression that [Freefair by Lars Grefer](https://docs.freefair.io/gradle-plugins/current/reference/#_aspectj_plugins)
is the one I want to recommend because of its good documentation, active development and feature set. It could well be
or become for the Gradle ecosystem what AspectJ Maven is for the Maven one. A few examples can be found
[here](https://github.com/freefair/gradle-plugins/tree/main/examples/aspectj).

### Mill

If you want to build your AspectJ projects with the [Mill Build Tool](https://github.com/com-lihaoyi/mill), you can use
the [mill-aspectj](https://github.com/lefou/mill-aspectj) plugin. It is actively maintained, and its author Tobias
Roeser is also the maintainer of Mill. It supports all important settings of AspectJ and is even providing convenience
options for polyglot projects, e.g. it features an option for out-of-the-box chained compilation with Zinc (for
Java/Scala) and AspectJ (for weaving aspects) in the same module.

### Ant

As mentioned in the introduction, AspectJ features its own Ant task, which is described in
[this chapter](../devguide/antsupport.adoc) of the Development Environment
Guide.

### Command line

If you wish to install AspectJ in a separate directory and use it from the command line without any extra build tools,
feel free to download the **AspectJ installer**. It is an executable JAR installer, requires Java and possibly admin
rights, if e.g. under Windows you want to install AspectJ to _C:/Program Files/AspectJ_. You execute it from a command
prompt via `java -jar installer-<version>.jar` and select your installation options. Then you add `<ASPECTJ_HOME>/bin`
to your path and are good to go. You can now call tools like the Aspectj compiler `ajc` or the AspectJ documentation
generator `ajdoc` (similar to Javadoc) from the command line.

You can find older installer versions until 1.9.6 on the [AspectJ website](https://www.eclipse.org/aspectj/downloads.php),
more recent ones are attached to AspectJ [GitHub releases](https://github.com/eclipse-aspectj/aspectj/releases) as
_aspectj-*jar_.

## Biased recommendation

Feel free to be skeptical, because the author has both IDE and build tool biases, but I am recommending Maven as a build
tool, AspectJ Maven as a build plugin and then either of Eclipse or IDEA as integrated development environments (IDEs).
Why? Because Maven + (Eclipse or IDEA) probably has the most complete tooling and best end-to-end user experience for
AspectJ developers. Because I am also by far the most active AspectJ and Spring AOP supporter on Stack Overflow, you also
have better chances to receive spot-on answers than if e.g. you ask why your Ant or Gradle build does not work so nicely
in NetBeans or VS Code. But by all means, please do choose whichever combination of tools is the prescribed standard in
your work environment or simply your personal pereference. I believe, that diversity is good. 🙂