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.
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.
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.
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.
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.
Yes, the run mojo provides a convenient way to run an application project (with all dependency applications) for basic testing purposes (optionally on a remote node). The only configuration available will be the configuration specified in the specific application resource file. The plug-in will give an advice about how to connect to the (remote) node running the application. Please note that application resources will be available when running the application on a remote node.
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.
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.
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(APPNAME).
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.
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 providing all modules (with debug information compiled) needed for test execution in a single directory making it unnecessary to add custom code paths to an erlang shell used for unit test debugging. To debug the test run mvn clean test which will basically compile all needed modules and try the test execution. After that simply start an erlang shell in the directory target/ARTIFACTID-VERSION-test/ebin.
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.
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.
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 library directory.
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.
On top of that the plug-in will generate the necessary scripts to package with the release (e.g. .boot file, ...). .relup files will not (yet) be generated but will be packaged. Finally the plug-in checks the resulting release file for plausability (e.g. whether all application dependencies are present, ...).
The EDoc application overview is supported by the edoc report mojo. The file overview.edoc has to be located in the src/site directory. The packaging variables ${ARTIFACT}, ${DESCRIPTION}, ${ID} and ${VERSION} are available to the overview file and may be used accordingly.
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.