Early Access Program Features

IntelliJ API to Build Scala Macros Support

Today we’ve released a new Scala plugin EAP build. With this build, we’re happy to introduce an API that extends the IDE coding assistance to custom Scala macros.

A macro is executed at compile-time and modifies the AST of your code: e.g. it can extend the class or its companion object with new methods or other code represented by the AST returned by the macro. Since IntelliJ IDEA’s coding assistance is based on static code analysis, the IDE is not aware of AST changes, and can’t provide appropriate code completion and inspections for the generated code.

Since macros are heavily used in some projects and libraries, we’ve added a special API to the platform that lets build IntelliJ plugins supporting particular macros. Using this API, we earlier added support for Monocle, and now Simulacrum:


Now, everyone can use this API to make their macros more friendly to their favorite IDE. To do that, you have to implement SyntheticMembersInjector, and register it in the plugin.xml file:

<extensions defaultExtensionNs="org.intellij.scala">
    <syntheticMemberInjector implementation="org.jetbrains.example.injector.Injector"/>

The Monocle and Simulacrum implementations will help you understand how to use the API. To help you with setting up a project, we’ve prepared a skeleton. You’re welcome to fork it, and add your implementation.

Once you’ve built a working plugin, it can be installed to the IDE via SettingsPluginsInstall plugin from disk…. If you want to share your plugin with other IntelliJ IDEA users, feel free to upload it to our plugin repository.

We’re eager to hear your feedback on the API. Feel free to share it either here in comments, on our discussion forum, or in the issue tracker.

In case you’d like to have particular macros supported by the Scala plugin, send us pull requests.

Develop with Pleasure!

Comments below can no longer be edited.

8 Responses to IntelliJ API to Build Scala Macros Support

  1. Avatar

    Turing says:

    October 15, 2015

    Why is macro support so hard? It seems like you don’t even look at the compiled class files which would contain all of the expanded AST that is generated from macros. If you looked at those, it would at least take care of a lot of the cases, such as not be able to code complete fields that are generated by macros. And it wouldn’t be 100%, but it would be a good deal closer than what you have.

    This system of having to implement a plugin seems like quite a hack and a pain to maintain. Adding a new macro would require additional work to add support into the plugin, which then needs to be built and subsequently installed on every dev’s machine.

    • Avatar

      Alberto Paro says:

      October 15, 2015

      Turing it’s very difficult to recover macros from class files.
      During AST rewrite in macro, you can inject a code that can be compiled to several classes.
      The syntax highlight will screw.
      The macro annotation in simulacrum generate other classes with a name convention: you are unable to connect the generated classes to the macro.
      Also in compiling you original macro code “dissapears” during AST transformation => you lack original code.
      There are a lot of other issues in managing macro.

    • Avatar

      Alexander Podkhalyuzin says:

      October 16, 2015

      We can’t rely on compiled classes as our highlighter works without it. However, macro expansion feature was implemented using compilation phase. So you can expand macroses after compilation with special compiler flag.

      As for pain to maintain. First of all, it’s better than nothing. So you have bigger choice about macros in your code:
      1. Not to use IntelliJ IDEA
      2. Not to use Macros
      3. Use both with pain to maintain.

      Problem with popular libraries macorses is bigger actually. And it’s really hard task to maintain all possible macroses. That’s the main reason of this API and this post. It’s not a big deal for library author to add few lines of code for IntelliJ IDEA, as they know exactly what their macros do and our API is quite simple to use. Then we can accept pull request. This is win-win for both, as lack of IntelliJ IDEA support can lessen library popularity. On our side supporting every macros from community is very painful task.

      Best regards,
      Alexander Podkhalyuzin.

  2. Avatar

    TD says:

    October 21, 2015

    I just downloaded latest IDEA EAP and latest plugin version, and it says that they are incompatible. Please, state what version of the plugin are you referring to and which version of IDEA it needs in your blogpost. It would also be great if you could provide release dates for the plugin versions at the plugin downloads page (https://confluence.jetbrains.com/display/SCA/Scala+Plugin+EAP+15), currently I don’t know, when I download an earlier plugin version, if it is one day or one month old.

    Tomáš Dvořák

    • Avatar

      Alexander Podkhalyuzin says:

      October 28, 2015

      You are right, we will try to be more consistent in future.

      Best regards,
      Alexander Podkhalyuzin.

  3. Avatar

    Pablo Guerrero says:

    December 7, 2015


    Is it possible with the new API to write a plugin for whitebox def macros?

    For example, a macro function that returns a new object using structural typing, or that defines a new class inside the macro and returns an instance of this new type.


  4. Avatar

    Raul Raja Martinez says:

    January 11, 2017

    The simulacrum and monocle link examples seem broken

Discover more