consulo.dev

Appearance

This page serves as a guide to the Maven-based plugin configuration for Consulo projects.

The Getting Started with Maven page provides a tutorial for creating Maven-based Consulo plugins.

WARNING

When adding additional repositories to your Maven build script, always use HTTPS protocol.

Overview of the Maven Plugin ​

The maven-consulo-plugin provides Maven goals that enable developing Consulo plugins.

When getting started, there are several items to note:

  • It is advised to upgrade to the latest available version of the maven-consulo-plugin regularly.
  • The plugin provides goals for code generation (icons and localization), packaging, and deployment.

Guide to Configuring Maven Plugin Functionality ​

This section presents a guided tour of maven-consulo-plugin configuration to achieve commonly desired functionality.

Configuring the Maven Plugin for Building Consulo Plugin Projects ​

The maven-consulo-plugin builds plugin projects against the Consulo API.

Consulo Configuration ​

The Consulo API version your plugin targets is controlled by the dependency versions declared in your pom.xml.

All available platform versions can be browsed in the Consulo Artifacts Repositories.

Plugin Dependencies ​

Consulo plugin projects may depend on either bundled or third-party plugins. In that case, a project should declare Maven dependencies on those plugins that match the Consulo version used to build the plugin project.

Note that this describes a build-time dependency so that Maven can resolve the required artifacts. The runtime dependency must be added in the Plugin Configuration (plugin.xml) file as described in Plugin Dependencies.

Code Generation Goals ​

The maven-consulo-plugin provides goals for generating source code:

  • generate-icon - Generates icon classes from icon definitions in ICON-LIB/.
  • generate-localize - Generates localization classes from localize files in LOCALIZE-LIB/.

These goals are typically configured to run during the generate-sources phase:

xml
<build>
    <plugins>
        <plugin>
            <groupId>consulo.maven</groupId>
            <artifactId>maven-consulo-plugin</artifactId>
            <extensions>true</extensions>
            <executions>
                <execution>
                    <phase>generate-sources</phase>
                    <goals>
                        <goal>generate-icon</goal>
                        <goal>generate-localize</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

Configuring the Plugin Configuration File ​

The platform version is specified in your plugin.xml file using the <platformVersion> element:

xml
<platformVersion>SNAPSHOT</platformVersion>

Always set this to SNAPSHOT in source code. The actual version number is substituted automatically during deployment.

Verifying Plugin ​

Before publishing, verify your plugin works correctly by building it and installing it into a local Consulo instance.

Publishing with Maven ​

Please review the Publishing Plugins with Maven page for information about deploying your plugin to the Consulo Plugin Repository.

Common Maven Plugin Configurations for Development ​

Different combinations of Maven plugin configuration are needed to create the desired build environment. This section reviews some of the more common configurations.

Plugins Targeting Consulo ​

Consulo plugins have the most straightforward Maven plugin configuration.

  • Determine the version of Consulo API to use for building the plugin project. See Platform Versioning for details.
  • Ensure <platformVersion>SNAPSHOT</platformVersion> is set in your plugin.xml file.

Plugins Targeting Alternate Consulo-Based IDEs ​

Maven also supports developing plugins to run in IDEs that are based on the Consulo. For more information, see the Developing for Multiple Products page of this guide.