Skip to end of metadata
Go to start of metadata

Introduction to the ignition-maven-plugin

  The ignition-maven-plugin was built to simplify the process of building Ignition Module source code into .modl files using the Apache Maven toolset. With the plugin, we leverage the convention-based nature of Maven to encourage a simple, stable build process. As a result, you'll need some basic familiarity with Maven. If you have no experience with Maven, we suggest you take a look at Maven in 5 Minutes as a start. You don't need to be a "Maven Master" to use the plugin, but familiarity with Maven's lifecycles, phases, goals and the all-important POM is helpful.     By configuring a Maven pom.xml in your module, you will be able to define information about your module such as the moduleName, requiredIgnitionVersion, scopes, as well as the locations of your license and documentation files. It's no coincidence that these configurations mirror those in the module.xml -- with the plugin configured, the module.xml will be automatically created and added to your module.      

Where to get the Plugin

  The plugin artifacts (jars) are hosted with the rest of the SDK at the Inductive Automation Nexus Repositories. To reference Maven dependencies from the repositories, you simply need to include our repository information in your Maven (or Gradle) dependency list. Here is an example of an entry as can be seen in our example projects' pom files:

The Inductive Automation Maven Artifact Repository
<distributionManagement>
	<repository>
    	<id>releases</id>
    	<name>IA Release</name>
    	<url>http://nexus.inductiveautomation.com/repository/inductiveautomation-releases/</url>
	</repository>
<distributionManagement>

 

 

With your Ignition SDK dependencies resolved, we can take a look at how the plugin works.  

Using the Ignition Maven Plugin

  The ignition plugin runs as part of the maven <build> cycle, and should be listed specified under <plugins> as a <plugin>. The plugin has two goals specified for building your Module:

  • modl
  • post

The modl goal

The modl goal allows for the execution of a customized package phase of the maven build. This goal will compile and test your project, resolve and download dependencies against the Ignition SDK repositories, search for specified doc and license files and zip them up into an modl file.

The post goal

As of ignition-maven-plugin v1.0.8, there is also the post goal. The post goal takes the modl goal one step further and acts as helper goal to "post" your packaged modl file to your running developer gateway. Note: You'll need to specify a <gatewayAddress> in the plugin configurations if you are not using the default (localhost:8088).:  

Configuring the Plugin

  The plugin has three requirements that need to be configured. The best way to understand the plugins with a variety of scope/dependy configurations is to review some of the examples, but here is a an overview of the different parts of the plugin configuration:

1. The descriptor

The descriptor is a typical Maven descriptor and consists of the <groupId>, <artifactId> and the <version>. The group and artifact ids are always going to be the same, and the version should be whichever version of the ignition-maven-plugin you are using. Here is an example descriptor:

<groupId>com.inductiveautomation.ignitionsdk</groupId>
<artifactId>ignition-maven-plugin</artifactId>
<version>1.0.8</version>

 

2. The executions

The <executions> section of the plugin is where we specify the goals of the plugin. <executions> can have one or more <execution> listed, and requires a <goal> to be specified. By default, the phases of the modl and post goals are bound to the package and install goals respectively. With multiple executions, you should also have an <id> for each execution. An example of the execution section looks like this:

Example <executions> for Ignition Maven Plugin
<executions>
    <execution>
        <id>modlexecution</id>
        <phase>package</phase>
        <goals>
            <goal>modl</goal>
        </goals>
    </execution>
    <execution>
        <id>postexecution</id>
        <phase>install</phase>
            <goals>
                <goal>post</goal>
            </goals>
    </execution>
</executions>

3. The configuration

The <configuration> section is the real heart of the plugin. Here is a list of required configuration tags:

  • projectScopes
    • Used to define the scope of each part of your project. Has name and scope tags, where name represents the artifact id of the project dependency, and the scope is any combination of one or more characters 'C', 'D' and or 'G' representing the scope (Client, Designer or Gateway) of the project.
  • moduleId
    • the full package module identifier, for example com.inductiveautomation.examples.examplemodule
  • moduleName
    • The readable text name of your Module, as it will be displayed in the gateway module page.
  • moduleDescription
    • A brief description if your module.
  • moduleVersion
    • the version of your module, most often set to ${project.version}.
  • requiredIgnitionVersion
    • the minimum required version of Ignition.
  • requiredFrameworkVersion
    • the minimum required version of Java
  • depends
    • specifies the dependencies for each scope.
  • hooks
    • tells the Gateway and/or Designer where to find the hooks for your module.

In addition, we have the following optional tags:

  • documentationFile
    • the path to the 'index.html' file of your documentation. By default, the plugin will look for a docs/ folder at at the root of your module.
  • licenseFile
    • the location of your license.html file. Can be 'license.html' if it's in the same directory as the build pom, or a full path to the file.
  • freeModule
    • specifies whether or not the module is free. Defaults to false.
    • Note: deprecated in 7.7.8+, 7.8.3+. override isFreeModule() in GatewayModuleHook instead.
  • gatewayAddress
    • is the URL and port of your testing gateway if not using the default location at http://localhost:8088. Should follow the format http://example.gateway.com:1234.  

Example Build pom.xml

  To help illustrate the configuration, lets take a look at an example plugin configuration.. In this case, the pom is located in a separate build directory to keep our structure clean and understandable. In the same project are two peer directories, one with Client specific code and the other with Designer source. If we ignore the ide-specific files (.idea and .iml), the directory structure looks like this:

 

Directory Structure for Example Build Pom

In the wme-build directory we have our docs folder, containing our module documentation, a license.html, and the build pom. In wme-client and wme-designer we can see their source code directories, as well as their own respective poms (in which their own dependencies are listed). The parent project has its own pom, where we declare the location of our dependency repos (such as Maven Central or the Ignition SDK Repo shown above). When using the ignition-sdk-plugin, we want to configure it from whichever pom contains the build instructions (designated by having the Maven <build> descriptor).

The wme-build Pom file
<project>
...
<build>
    <plugins>
        <plugin>   <!-- start the plugin configuration -->

			<!-- The descriptor block -->
            <groupId>com.inductiveautomation.ignitionsdk</groupId>
            <artifactId>ignition-maven-plugin</artifactId>
            <version>1.0.8-SNAPSHOT</version>

			<!-- The executions block -->
            <executions>
                <execution>				
                    <id>modlexecution</id>  <!-- id is needed when there are more than one execution in <executions> -->
                    <phase>package</phase>  <!-- phase of the lifecycle the goal should execute in, defaults to phase -->
                    <goals>
                        <goal>modl</goal>   <!-- the goals to execute in this phase -->
                    </goals>
                </execution>
                <execution>
                    <id>postexecution</id>
                    <phase>install</phase>
                        <goals>
                            <goal>post</goal>
                        </goals>
                </execution>
            </executions>

			<!-- The configuration block -->
            <configuration>
                <projectScopes>
                    <projectScope>
                        <name>wme-client</name>  <!-- we have a project called wme-client with the client source -->
                        <scope>CD</scope>		 <!-- the scopes required by the project files, here Client and Designer are needed -->
                    </projectScope>

                    <projectScope>
                        <name>wme-designer</name>  <! -- the project that has our designer source -->
                        <scope>D</scope>
                    </projectScope>
                </projectScopes>

                <moduleId>com.inductiveautomation.ignition.examples.wme</moduleId>
                <moduleName>WeatherModuleExample</moduleName>
                <moduleDescription>
					A module that provides current and forecasted weather conditions.
            	</moduleDescription>
                <moduleVersion>${project.version}</moduleVersion>
                <requiredIgnitionVersion>7.7.0</requiredIgnitionVersion>
                <requiredFrameworkVersion>6</requiredFrameworkVersion>
                <licenseFile>license.html</licenseFile>
                <documentationFile>doc/</documentationFile>
	
				<!-- specify our dependencies -->
                <depends>
                    <depend>
                        <scope>D</scope>
                        <moduleId>fpmi</moduleId>
                    </depend>
                </depends>
				
				<!-- specify one or more hook locations and their scope -->
                <hooks>
                    <hook>
                        <scope>D</scope>
                        <hookClass>com.inductiveautomation.ignition.examples.wme.designer.DesignerHook</hookClass>
                    </hook>
                </hooks>
            </configuration>
        </plugin>
    </plugins>
</build>
...
</project>
  • No labels