This is a quick-start guide on how to use the Erlang plugin for Maven

Download and install

Grab the latest release of the plugin (or the SVN version), go to the erlang-plugin/ directory and type:

mvn install

This will install the plugin in your local repository and make it available to you. While you're at it, also grab the latest release of the erlang-archetype plugin and install it likewise.

Create an Erlang project

To create a new Erlang project ready to use with Maven, just type:

mvn archetype:generate -DarchetypeGroupId=net.sf.maven-erlang -DarchetypeArtifactId=erlang-archetype -DarchetypeVersion=1.0-SNAPSHOT

This will prompt you for the artifactId, groupId, package and version of the new project create a directory named after the artifactId with the following structure:

my-project
|-- pom.xml
`-- src
    |-- main
    |   |-- erlang
    |   |   |-- sample_application.app
    |   |   `-- sample_module.erl
    |   `-- include
    |       `-- sample_module.hrl
    `-- test
        `-- erlang
            `-- sample_test.erl

Configuring your project

All the configuration is done in the pom.xml file. A typical POM for an Erlang project looks like this:

<project>
  <modelVersion>4.0.0</modelVersion>
  <groupId>org.sanctuaire</groupId>
  <artifactId>test</artifactId>
  <packaging>erlang-otp</packaging>
  <version>1.0-SNAPSHOT</version>
  <name>A custom Erlang project</name>
  <url>http://www.myorganization.org</url>

  <build>
    <plugins>
      <plugin>
        <groupId>net.sf.maven-erlang</groupId>
        <artifactId>erlang-plugin</artifactId>
        <extensions>true</extensions> <!-- mandatory if you want to use the custom lifecycle phases -->
        <configuration>
          <!-- Optional parameter: path to the erlang installation directory, i.e. path in path/bin/erlc -->
          <!-- <erlPath>C:/Program Files/erl5.5</erlPath> -->
          <!-- Optional parameter : path to eunit i.e. path in path/ebin -->
          <!-- <eunitPath></eunitPath> -->
          <!-- Optional parameter: if we should generate surefire-compatible
          reports. Requires eunit. -->
          <surefireReports>true</surefireReports>
          <!-- Optional parameter: debug_info (defaults to false, required to run dialyzer) -->
          <debugInfo>true</debugInfo>
          <!-- Optional parameter: compiler additional options -->
          <!-- <erlcOptions><param>+export_all</param></erlcOptions> -->
          <!-- Optional parameter: run dialyzer (defaults to false) -->
          <useDialyzer>true</useDialyzer>
          <!-- Optional parameter: compiler additional options for tests (in addition to erlcOptions) -->
          <!-- <erlcTestOptions><param>+debug_info</param><param>-DTEST</param></erlcTestOptions> -->
          <!-- Optional parameter: run dialyzer for tests (defaults to false) -->
          <!-- <testUseDialyzer>true</testUseDialyzer> -->
          <!-- Optional parameter: dialyzer additional options -->
          <!-- <dialyzerOptions><param>-Werror_handling</param></dialyzerOptions> -->
          <!-- Optional parameter: fail on dialyzer warnings (defaults to false) -->
          <dialyzerWarningsAreErrors>true</dialyzerWarningsAreErrors>
          <!-- Optional parameter: run code coverage during tests -->
          <!-- <codeCoverage>true</codeCoverage> -->
          <!-- Optional parameter : generate edoc documentation with package. -->
          <useEdoc>true</useEdoc>
          <!-- Optional parameter : application resource file. If this file
          exists, it will be used with edoc and it will be copied to "ebin/"
          directory. Defaults to artifactId.app -->
          <!-- <applicationResourceFile>mymodule.app</applicationResourceFile> -->
          <!-- Optional parameter : edoc options -->
          <!-- <edocOptions><param>{def, {macro, "value"}}</param></edocOptions> -->
        </configuration>
      </plugin>
    </plugins>
  </build>

  <reporting>
    <plugins>
      <plugin>
        <groupId>net.sf.maven-erlang</groupId>
        <artifactId>erlang-plugin</artifactId>
      </plugin>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-surefire-report-plugin</artifactId>
        <version>2.4.2</version>
      </plugin>
    </plugins>
  </reporting> 
</project>

Of course, you will need to add various sections in your POM to configure the generated website, to generate reports, etc.

Managing your project

Source files are expected to be in the src/main/erlang directory, and header files in the src/main/include directory.

The following goals are available:

  • compile your sources (in the target/ directory): mvn compile
  • run the test cases: mvn test
  • package the project (OTP way, zipped in the target/ directory): mvn package
  • deploy the project (as configured in your POM): mvn deploy
  • create the site with reports including code coverage report (as configured in your POM): mvn site

Test cases

The Erlang plugin considers that tests are performed by modules which have the following properties:

  • the module name ends with "_test" (this suffix can be changed with a simple parameter)
  • the module .erl file is in src/test/erlang/
  • the module exports the test/0 function (which is expected to call all the tests in the module)

    During the test phase, the Erlang plugin re-compiles the main sources with the export_all option, along with the test sources. This means that all the functions in your main modules are available in your tests, while you still can separate your testing code from your main code.

    The simplest way to write test cases is to use EUnit . You just have to include the eunit.hrl header in your test modules (after the -module and -export declarations but before any other declarations such as other includes, etc.). EUnit will automatically export the test/0 function, along with many other powerful features.