Building and Running the plugin

Use this to get started with developing the plugin.

Local Build

This plugin is built using Gradle. As this project includes the Gradle wrapper, developers don’t need to install Gradle. They need to install Java and make it available in the path or set environment variable JAVA_HOME the folder where they installed it. When building or running for the first time, the build-script downloads the community edition of IntelliJ automatically.

To build this plugin, run:

./gradlew -Dfile.encoding=UTF-8 buildPlugin

The ZIP file with plugin to distribute will be located in build/distributions.

The plugin.xml inside the archive will state version 0.0.1 unless the developer specifies an environment variable VERSION that holds a release number. This ensures that a locally built plugin will be overwritten by the JetBrains plugin update site.

Running the development version locally

To run the plugin for development, run

./gradlew -Dfile.encoding=UTF-8 runIde

To run all tests and the CheckStyle validations, run

./gradlew -Dfile.encoding=UTF-8 check

Running the plugin from with the IDE

About

Developers most likely want to do this for fast turnaround times when running single tests, and debugging both tests and the plugin itself. Use IntelliJ IDEA as an IDE for developing on this plugin.

Developers can use the most recent version of the IDE. The build.gradle file specifies the minimum version for all users of the plugin, but when developing they are free to use a more recent version.

Setup Tasks

  1. Checkout the GitHub project and import it as a gradle project.

  2. Ensure to install the following plugins (the IDE should recommend installing them once it opens the project):

    GrammarKit

    Helps with highlighting and code completion in Grammar files (*.flex).

    PsiViewer

    Helps to analyze the PSI (abstract syntax tree) created from the plugin in the IDE.

    CheckStyle

    This project contains a ready-to-go CheckStyle configuration that will work both in the IDE and in gradle.

  3. Go to Project Structure…​  Project Setting  Project.

  4. Choose “Amazon Corretto 11” as Project JDK
    (use Add JDK and Download JDK…​ if not already present).

Running Tests from the IDE

Running tests from the IDE might produce the error message “jarFiles is not set for PluginDescriptor”. To avoid this error message, set the following system properties when running tests from the IDE. When running tests from Gradle, this is added automatically:

-Didea.force.use.core.classloader=true
-Didea.use.core.classloader.for.plugin.path=true

Still, when running via the IDE, the tests in AsciiDocGrammarInspectionTest fail with an ExceptionInInitializerError when loading language tool classes. Run these tests using the CLI command gradlew check as described above.

Validation Tasks

Perform these tasks to ensure that the setup is ready for development:

  1. Run the test cases from AsciiDocLexerTest.java to see that running tests works in the setup.

  2. There are two ready-to-go run configurations checked in to git that run from the IDE:

    buildPlugin

    building the plugin as a ZIP-file that can then be installed locally into any JetBrains IDE

    runIde

    runs an IntelliJ community edition with the AsciiDoc plugin enabled. This allows for debugging IntelliJ and the plugin.