Plugin Documentation

Goals available for this plugin:

Goal Report? Description
erlang:appup No

This Mojo will generate an application upgrade file template for an application. In order to do so all available non-SNAPSHOT versions of the project will be resolved (also from remote repositories). All versions smaller than the current version will be included in the generation. The resulting application upgrade file's location will be prompted on success as well as its content.

The generation algorithm is outlined in the following description:

  • Find added modules and add a {load_module, Module} statements for them.
  • Find updated modules and invoke the GetAppupDirectiveScript on them.
  • Find deleted modules and add a {delete_module, Module} statements for them.


The GetAppupDirectiveScript works as described below:

  • Add a {update, Module, supervisor} statement if Module is a supervisor.
  • Add a {update, Module} statement if Module exports code_change/3.
  • Add a {load_module, Module} statement if Module does not meet the previous conditions.
erlang:compile No This Mojo compiles the projects Erlang sources and MIB files.
erlang:coverage No Runs a test coverage analysis on the modules in of the project, optionally printing the result to console. The coverage data is saved as a simple text file (COVERAGE-${project.artifactId}.txt) with simple space separated list of results, with coverage levels for: modules, functions, clauses and lines. See also CoverageReport, i.e. the coverage-report goal.

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:coverage-report Yes Generates a test coverage HTML report from the results produced by the Coverage mojo i.e. the coverage-goal. The report contains a 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.
erlang:dialyzer No

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 will be done by default.
erlang:edoc Yes This Mojo will generate source code documentation for an application.
erlang:extract-dependencies No Unpack 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-resources No Copies 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 (string)
  • ${DESCRIPTION}: the projects description string (string)
  • ${ID}: the project id (string)
  • ${NAME}: the projects name (string)
  • ${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-resources No Copies 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-resources No Copies all test resource files into that target directory structure. Copied resources contain:
  • resources (*)
  • test resources (*)
erlang:help No Display help information on maven-erlang-plugin.
Call 
  mvn erlang:help -Ddetail=true -Dgoal=<goal-name>
to display parameter details.
erlang:initialize No Mojo 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:package No

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 project id (string)
  • ${NAME}: the projects name (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-release No This 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:profile No Performs function profiling using eprof, by executing any EUnit test modules, with the suffix [module]_prof.erl, found among the test sources. The profiling result are filtered and written out to the file (PROFILING-${project.artifactId}.txt), which may be used to generate a profiling-report.
erlang:profiling-report Yes Generates a profiling report from the output of an already executed profile goal. NOTE: this report does not invoke any other lifecycle, it is required that a profiling is already run before the report can be generated.
erlang:reload-dependencies No Mojo that first purges all dynamically loaded modules on the backend node and reloads the modules provided by (unpacked) dependencies.
erlang:reload-test-dependencies No Mojo that first purges all dynamically loaded modules on the test backend node and reloads the modules provided by (unpacked) dependencies.
erlang:relup No This Mojo will generate a release upgrade file template for a release project. In order to do so all available non-SNAPSHOT versions of the project will be resolved (also from remote repositories). All versions smaller than the current version will be included in the generation. The resulting release upgrade file's location will be prompted on success as well as its content. The actual generation will be made using systools:make_relup/4.
erlang:run No

A Mojo that runs erlang projects on a specific (remote) node. This will start the project along with all dependent applications and all modules pre-loaded. In case the project is run on the backend node the build will be paused to give the user the possibilty to interact with the running project.
erlang:setup No

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-info No

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-system No

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 can be started either directly or as a daemon using the bin/start script. This script has to be provided with the correct root directory of the target system. Custom arguments like node name or cookie can be set by giving them as additional command line arguments to bin/start.

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

  • FIXME not supported on Microsoft Windows
erlang:test No A Mojo that runs test modules using eunit.
erlang:test-compile No Compile 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-initialize No Mojo 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-release No This 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:upload No

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 and uploading the project's private resources making them available using code:priv_dir/1. To achieve this the temporary upload directory is added to the remote node's code path. 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-tests No

This Mojo uploads an application's modules compiled for test execution and the application's tests onto a remote node. This will also upload the application's resource files making them available to the remote node using code:priv_dir/1. The modules will be purged once as if c:c/1 would have been called on a shell.
erlang:validate No Mojo that checks the project configuration for legal values.

System Requirements

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

Maven 2.0
JDK 1.6
Memory No minimum requirement.
Disk Space No 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.2.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.2.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.2.0</version>
      </plugin>
      ...
    </plugins>
  </reporting>
  ...
</project>

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