Plugin Documentation

Goals available for this plugin:

GoalReport?Description
erlang:compileNoThis Mojo compiles the projects erlang sources.
erlang:coverageYesGenerates a test coverage report with: project summary, showing the number of functions, clauses executable lines and their test coverage percentage. A module list with individual coverage reports and an extensive source code report, with lines annotated in red or green, showing the exact coverage.

ISSUE If a test purges or unloads a module to do coverage for, the coverage compilation information will be gone and the coverage report will fail.

erlang:dialyzerNo

This Mojo runs the erlang dialyzer tool on the project sources as well as the project includes. This means dialyzer will run over the complete project code (excluding test modules).

The dialyzer can be skipped using the skipDialyzer parameter. Additionally, the user can choose to run dialyzer also on the projects dependencies using the dialyzerWithDependencies parameter. This is disabled by default for the erlang-otp and erlang-std project packaging.

erlang:dialyzer-releaseNo

This Mojo runs the erlang dialyzer tool on the release dependencies. The dialyzer can be skipped using the skipDialyzer parameter.

erlang:edocYesThis Mojo will generate source code documentation for an application.
erlang:extract-dependenciesNoUnpack erlang-otp or erlang-std dependencies. This will unpack all dependencies of this MavenProject into the target/lib directory. This is done only in case the dependency has changed since the last unpack process.
erlang:generate-release-resourcesNoCopies all resource files into that target directory structure. Copied resources contain:
  • release file (*.rel)
  • release upgrade file (relup)
  • boot scripts, etc. as returned from systools:make_script
The build of script files can be customized by passing user options through the scriptOptions parameter. In order to manage the project over the project pom there is the possibility to let the Mojo automatically fill in values from the project pom into the .rel file. This can be done by using one of the supported variables into the release file. Below is a list of supported variables and their substitutions:

  • ${ARTIFACT}: the projects artifact id (atom)
  • ${VERSION}: the projects version (string)
  • ${ERTS}: expands to the tuple {erts, "ERTS_VERSION"} with the version of erts available on the backend node (tuple)
  • ${APPLICATIONS}: a comma separated listing with all transitive dependency applications of the project (tuple listing)
  • ${AUTODEPS}: an erlang list with all transitive dependency applications of the project (list)
  • ${APPLICATION_NAME}: will be replaced by the tuple {'APPLICATION_NAME', "APPLICATION_VERSION"} with the version available on the backend node (tuple)
erlang:generate-resourcesNoCopies all resource files into that target directory structure. Copied resources contain:
  • erlang source files (*.erl)
  • erlang include files (*.hrl)
  • edoc overviews (overview.edoc)
  • resources (*)
erlang:generate-test-resourcesNoCopies all test resource files into that target directory structure. Copied resources contain:
  • resources (*)
  • test resources (*)
erlang:helpNoDisplay help information on maven-erlang-plugin.
Call
  mvn erlang:help -Ddetail=true -Dgoal=<goal-name>
to display parameter details.
erlang:initializeNoMojo that starts the erlang node used as a backend for rpcs made by the plugin. The node will only be started if it is not already running. The node will be shutdown when the executing JVM exits. This is done by a Runtime.addShutdownHook() which will only be added once each JVM execution.
erlang:packageNo

This Mojo packages all application artifacts into a single .tar.gz package. This includes .beam files, the .hrl include files and private data from the priv directory.

Besides that this Mojo also copies the erlang application resource file. In order to manage the project over the project pom there is the possibility to let the Mojo automatically fill in values from the project pom into the .app and .appup files. This can be done by using one of the supported variables into the application resource files. Below is a list of supported variables and their substitutions:

  • ${ARTIFACT}: the projects artifact id (atom)
  • ${DESCRIPTION}: the projects description (string)
  • ${ID}: the projects id (string)
  • ${VERSION}: the projects version (string)
  • ${MODULES}: all compiled .beam files found in the target ebin folder (list)
  • ${REGISTERED}: all registered names, based on the -registered(Names). attribute retrieved from the compiled .beam files (list)
  • ${APPLICATIONS}: all dependency applications of the project as configured in the project's pom.xml (string)

The resulting application resource file as well as the application upgrade file will be checked for plausability.

erlang:package-releaseNoThis Mojo packages/creates a release .tar.gz using the erlang systools modules. The build can be customized by providing additional options through the tarOptions parameter.
erlang:reload-dependenciesNoMojo that first purges all dynamically loaded modules on the backend node and reloads the modules provided by (unpacked) dependencies.
erlang:reload-release-dependenciesNoMojo that first purges all dynamically loaded modules on the backend node and reloads the modules provided by (unpacked) dependencies.
erlang:reload-test-dependenciesNoMojo that first purges all dynamically loaded modules on the test backend node and reloads the modules provided by (unpacked) dependencies.
erlang:runNo

A Mojo that runs erlang applications packaged with packaging type PackagingType.ERLANG_OTP or PackagingType.ERLANG_STD on a specific (remote) node. This will start the application with all dependent applications and all modules pre-loaded. When finished the Mojo will stop and unload the started applications.

TODO: release projects cannot be run

erlang:setupNo

Utility goal that will setup a new Erlang/OTP Maven project, creating the basic resources and folders required, from a best practice point of view.

This will typically replace the functionality given by a Maven archetype, checking and creating any missing resource. Regarding erlang/OTP applications this could be:

  • source folder
  • application resource file [artifactId].app
  • application upgrade file [artifactId].appup
  • include folder
  • priv folder
  • test source folder
  • test include folder
  • test priv folder

Regarding erlang/OTP releases this could be:

  • release file [artifactId].rel
  • system configuration sys.config

By default some extras for project management are also generated:

  • site folder with site.xml
  • apt source folder with index.apt[.vm]
  • changelog folder with changes.xml

The default application resource file will look like (this would be sufficient for library applications):

{application, ${ARTIFACT},
 [{description, ${DESCRIPTION}},
  {id, ${ID}},
   {vsn, ${VERSION}},
   {modules, ${MODULES}},
   {maxT, infinity},
   {registered, ${REGISTERED}},
   {included_applications, []},
   {applications, [kernel, stdlib]},
   {env, []}, 
   {start_phases, []}]}.


The default application upgrade file will look like:

{${VERSION}, [EDIT HERE], [EDIT HERE]}.


The default release file will look like:

{release,
 {${ARTIFACT}, ${VERSION}},
 ${ERTS},
 ${AUTODEPS}}.


The default release upgrade file will look like:

{${VERSION}, [EDIT HERE], [EDIT HERE]}.


The default system configuration file will look like:

[].


erlang:show-build-infoNo

This Mojo outputs the build information ascertained by maven to compile Erlang sources. The output is supposed to enable other tools (like emacs) to reconstruct compilation commands.

The output is logged at info level and contains:

  • source folder for main erlang sources
  • source folder for unit-test erlang sources
  • include directories that may contain erlang header files
  • code path directories including those of dependend projects in the target directory of the maven build
The output consists of one line per item. Each item consists of two elements: InfoType ": " InfoValue where InfoType is one of:
  • src_dir
  • test_src_dir
  • include_dir
  • code_path
InfoValue is a file path. Both elements a seperated by the string ": " (colon, space).

erlang:target-systemNo

This Mojo creates a target system release package .tar.gz according to the official documentation. If there's no sys.config file found a default empty one will be included. The resulting target system depends on a correct root directory configuration. The plug-in will change the scripts to check for the ${ ARTIFACTID_TOP} (upper case) environment variable. This variable must be set by the user to guarantee a proper system behaviour. Example: If artifact id is release the environment variable ${RELEASE_TOP} must be set.

Note: The resulting target system is highly system dependent since it contains the erlang emulator (C code) from the backend nodes erlang installation.

Note: This mojo is currently working but still in experimental stage.

  • FIXME not supported on Microsoft Windows
erlang:testNoA Mojo that runs test modules using eunit.
erlang:test-compileNoCompile erlang test sources and recompile erlang sources with the options debug_info, export_all and {d, 'TEST'}. This will also compile the supporting erlang sources provided along with the plugin.
erlang:test-initializeNoMojo that starts the test erlang node used as a backend for rpcs made by the plugin. The node will only be started if it is not already running. The node will be shutdown when the executing JVM exits. This is done by a Runtime.addShutdownHook() which will only be added once each JVM execution.
erlang:test-releaseNoThis Mojo checks the release file for plausability. This is done by checking the release version, the release name as well as checking all dependencies for correct versioning and existence.
erlang:uploadNo

This Mojo uploads a project onto a remote node. In case of application projects this includes remote loading of the compiled application modules loading of the application resource file using application:load/1. The modules will be purged once as if c:c/1 would have been called on a shell. In case of a release project the release package (.tar.gz) will be uploaded in the remote nodes releases directory ready to be unpacked and installed using the release_handler.

Note: Uploading of releases will require that the remote erlang process has write access to its releases directory.

erlang:upload-testsNo

This Mojo uploads an application's modules compiled for test execution and the application's tests onto a remote node. This will not upload the application's resource files. The modules will be purged once as if c:c/1 would have been called on a shell.

System Requirements

The following specifies the minimum requirements to run this Maven plugin:

Maven2.0
JDK1.6
MemoryNo minimum requirement.
Disk SpaceNo minimum requirement.

Usage

You should specify the version in your project's plugin configuration:

<project>
  ...
  <build>
    <!-- To define the plugin version in your parent POM -->
    <pluginManagement>
      <plugins>
        <plugin>
          <groupId>eu.lindenbaum</groupId>
          <artifactId>maven-erlang-plugin</artifactId>
          <version>2.0.0</version>
        </plugin>
        ...
      </plugins>
    </pluginManagement>
    <!-- To use the plugin goals in your POM or parent POM -->
    <plugins>
      <plugin>
        <groupId>eu.lindenbaum</groupId>
        <artifactId>maven-erlang-plugin</artifactId>
        <version>2.0.0</version>
      </plugin>
      ...
    </plugins>
  </build>
  ...
  <!-- To use the report goals in your POM or parent POM -->
  <reporting>
    <plugins>
      <plugin>
        <groupId>eu.lindenbaum</groupId>
        <artifactId>maven-erlang-plugin</artifactId>
        <version>2.0.0</version>
      </plugin>
      ...
    </plugins>
  </reporting>
  ...
</project>

For more information, see "Guide to Configuring Plug-ins"