Frequently Asked Questions

What project directory layouts does the plug-in support?

For application projects there are two possible directory layouts. The erlang-otp packaging type assumes the standard maven directory layout while the erlang-std packaging type assumes the Erlang/OTP standard directory layout. Release projects don't have a specific directory layout (flat top level directory) since they only consist of a pom.xml, a release file, a release upgrade file and a system configuration file.

For an exact listing of directories and the supported content types please refer to the PackagingType documentation.

Is there a project archetype for erlang projects?

The plug-in does not depend on any empty directories so users don't have to create them if they don't use them (e.g. an empty priv directory). We therefore recommend that users write their own pom.xml from the start using an editor with assistance (e.g. Eclipse in combination with the m2eclipse plug-in). After creation of the pom.xml file the setup goal may be used to setup the needed directory layout as well as default configuration files. For more information please refer to the setup mojo documentation.

For application and release upgrade files the plug-in provides separate goals that can generate sensible template files based on previously installed/deployed project artifacts. For more information please refer to the appup and relup mojo documentation.

How does the plug-in work?

The plug-in uses several erlang nodes as backends to execute scripts via remote procedure calls. The backend node will not be altered by the plug-in except for the extension of code paths. The plug-in does not need write access to the backend node's installation directory. A backend node is started and stoppend by the plug-in automatically as needed. The plug-in can re-use an already running backend node by reconnecting to it.

Can I use Maven 3 with the plug-in?

Yes, it is possible to run the plug-in with Maven 3 but there are some things to consider due to the site-plugin changes that came with the Maven 3 version. These changes are important when using the reporting features of the plug-in.

How do I manage non-erlang source code/artifacts?

It is recommended to organize your project's non-erlang dependencies in separate maven projects (or at least with a separate classifier). The plug-in will put all non-erlang dependency artifacts into the application project's target priv directory. The erlang application will be able to find this directory using code:priv_dir/1 at runtime as well as during test execution.

How does the plug-in's dependency management work (roughly)?

The plug-in manages the dependencies to other erlang projects packaged by this plugin. This supports modular architectures/releases featuring a whole bunch of custom applications dependening on each other. The plug-in also does not care whether your projects use different application packaging type. The available application types may be mixed up in a release or in an application's dependencies.

The plug-in is not intendended to manage standard Erlang/OTP application dependencies. When packaging a release it is assumed that this code is automatically available to the backend node. This is guaranteed by checking the Erlang/OTP release version running on the backend node against the required Erlang/OTP release version of a release as configured in its pom.xml.

Release projects can be seen as packaging projects that do not contain code but manage a versioned set of versioned application dependencies. Applications or releases must not have dependencies to other releases. Read more on this in the release packaging section.

The plug-in also respects the dependency scopes test and provided. These dependencies will not be packaged into the release and need not be contained in the application resource or release file.

Can the plug-in run my project (and its dependencies) for testing purposes?

Yes, the run mojo provides a convenient way to run either application projects or the applications contained in release projects (with all dependency applications) for basic testing purposes (optionally on a remote node). When running releases the project's sys.config will be loaded into the environment before starting the applications. All resource files (application priv directories) will be available to the runtime system and can be retrieved using code:priv_dir/1 for a specific application. The plug-in will give an advice about how to connect to the (remote) node running the application(s).

Does the plug-in suppport structured source directories?

Yes, the plug-in supports structured source directories. All recursively found modules will be compiled and the resulting .beam objects will be put flattened into the targets ebin directory.

Does the plug-in support private include files (that won't be shipped)?

Yes, the root source folder of a project is added to the include path during compilation. This may be used for private header files (e.g. testing purposes) that will not be packaged along.

How should the application's include files be used?

An application should include its include files as if they were placed in the same directory as the including source. The plug-in will pull in the needed include directives for compilation automatically. Alternatively, the -include_lib directive can be used for the applications includes as well as the dependency applications includes. This has the advantage that one can see directly which application provides the specific include. However, the -include_lib directive can not be applied to private header files as described in the section above.

How does the plug-in deal with resources and test resources?

The plug-in supports random resources that will be put into the target priv directory. Resources from the test priv directory will override the default resources in the test phase. The priv directory can be obtained at test runtime using code:priv_dir/1.

How does the plug-in support unit testing?

Unless specified otherwise the plugin executes all modules with the suffix _test or _tests as eunit tests. Tests may be skipped using the skipTests paramter. To execute only a specific test the parameter test can be used (in fact the plug-in even executes test modules placed in the application's main source directory).

When test execution was successful the plugin provides surefire compatible reports about test runs that will automatically be found by the maven surefire plugin on site generation.

The plug-in also provides the possibility to generate test coverage reports with annotated source code listing (as you may know them from tools like eclemma) and/or with console output. See the coverage example page for further information about that.

To run only a single test module the test parameter can be set to a specific test module.

How to debug a broken unit test?

Debugging broken unit tests can sometimes be a hard thing. Therefore debugging should be made directly from the erlang console where you can use all that shiny dbg stuff erlang has to offer. The plug-in can support that by uploading all needed modules (tests and project modules compiled with debug information) to a specified node. The upload-tests goal will upload everything you need to an (already started) node the user can run/debug tests on. A lightweight alternative to re-running the unit tests on a separate node could be to examine the output of the backend nodes which is written to the file target/backend.log.

How does application packaging of erlang-otp and erlang-std projects work?

The plug-in will package your application according to the OTP design principles (e.g. the package will make use of the OTP directory layout). This can be seen when inspecting the target directory after a run of mvn package. The dependency artifacts are .tar.gz packages of the created directory structure. The needed erlang application file can/should be written by the user but the plug-in may support the user by providing application packaging variables that will expand to sensible values when packaging the application.

The $MODULES variable for example expands to a list of modules the application delivers. This us useful for the modules tuple in the application resource file inspected by the erlang release handler.

Another example is the $REGISTERED variable. This will interact with the -registered([...]). attribute and expand to a list of names registered by an application at runtime.

The $APPLICATIONS variable will expand to a listing of (transitive) application dependencies an application has based on the specified maven dependencies.

For a list of available application packaging variables see the plugin configuration page.

How does the plug-in deal with library applications?

It simply doesn't do anything special with them. Library applications are packaged like any other application project since the only difference to other applications is that the mod tuple in its application resource file is omitted. The sasl application can handle that so calls to application:start/1 and application:stop/1 can be made without any problems.

We've heard of people recommending to put library dependencies into the included_application tuple and package the code along with the using application. The included_application tuple is intended only for applications that will be included in another applications supervision tree manually. We recommend to separate your applications properly and write correct, simple application resource files.

How does release packaging of erlang-rel projects work?

The plug-in will package your release according to the OTP design principles into a .tar.gz package that can be installed by the erlang release handler. The needed erlang release file can/should be written by the user but the plug-in may support the user by providing release packaging variables that will expand to sensible values when building the release.

Because dependencies to applications have to be resolved (to versions) at this point the release must be built on a backend node that can deliver the required versions of applications. The maven dependencies (applications packaged by the plug-in) will be put into the code paths automatically by the plug-in. Standard Erlang/OTP applications will be taken from the backend node's code path.

The $APPLICATIONS and $AUTODEPS variables expand to all transitive maven dependencies as required by the release files applications section and will also put in the required transitive dependencies to standard Erlang/OTP applications (e.g. mnesia, sasl, ...). The version of the standard applications are those available to the backend node. To achieve a correct dependency management a release project must configure what Erlang/OTP release should be used as release base (the standard application versions will then be taken from this release). The build will fail if either the OTP release base variable (otpRelease) is not configured or the backend node does not run the configured release.

To be able to make a test build with another OTP release version the user may specify the skipReleaseTest parameter to skip the OTP release verification. The release will then pull in the standard erlang applications from another OTP release (that is currently run by the backend node).

In summary, this means that if you decide to create your release based on the applications of R13B04 your backend node must actually run this version of erlang. This can be achieved by building your release on a central build server like jenkins/hudson or by having the suitable release installed locally. It is possible to specify the used erl command using the erlCommand parameter.

For a list of available release packaging variables see the plugin configuration page.

In case the plug-in support is disclaimed the user has to take care of the availability of the required versions of standard applications. This can be achieved by specifying the skipReleaseTest parameter and adding the needed applications to the code path of the backend node manually. Applications found in paths prepended to the code path will override later entries.

On top of that the plug-in will generate the necessary scripts to package with the release (e.g. .boot file, ...). Finally the plug-in preforms some checks on the project's resource files.

Does the plug-in support the edoc application overview file?

The EDoc application overview is supported by the edoc report mojo. While in erlang-otp projects the file overview.edoc has to be located in the src/site directory, in erlang-std project will expect the file in the doc directory. The packaging variables ${ARTIFACT}, ${DESCRIPTION}, ${ID} and ${VERSION} are available to the overview file and may be used accordingly.

How to deal with non-maven packaged erlang projects?

To make non-maven packaged 3rd party erlang applications available to other application or release projects Gregory Haskins wrote the nifty escript eapp2mvn to deploy these artifacts under configurable maven coordinates. The script's documentation is self-contained. The script can be found in the tools directory of the plug-in's source code repository.