The project directory must be named $(PROJECT) or $(PROJECT)-<vsn>. OTP finds the application by that directory name. make rel fails before Relx runs when the name does not match.

First, relx must be added in the dependencies of your project. Relx is in the built-in index, so you can add it to REL_DEPS with the name alone:

REL_DEPS = relx

Then, you need to create a relx.config file in the $(RELX_CONFIG) location. This defaults to $(CURDIR)/relx.config. You can override it by defining the variable before including Erlang.mk:

RELX_CONFIG = $(CURDIR)/webchat.config

It is also possible to have multiple relx.config files. For example you might have one for development and one for production. You can use conditionals to decide which one should be used:

ifdef PROD
RELX_CONFIG = $(CURDIR)/relx.prod.config
else
RELX_CONFIG = $(CURDIR)/relx.dev.config
endif

relx.config.script is also recognized. It defaults to $(CURDIR)/relx.config.script and can be overridden with RELX_CONFIG_SCRIPT, set before including Erlang.mk. Erlang.mk evaluates the script with CONFIG bound to the terms from relx.config, or to [] when that file is absent. The script returns the configuration Relx receives. Either file is enough for make to build the release.

Erlang.mk provides RELX_OUTPUT_DIR for the output directory. It defaults to the _rel directory and overrides output_dir in the config:

RELX_OUTPUT_DIR = /path/to/staging/directory

All other configuration is done through relx.config. To enable development mode:

{dev_mode, true}.

Now that you’re all set, all you need to do is generate the release. As mentioned before, Erlang.mk will automatically generate it when it detects the $(RELX_CONFIG) file or $(RELX_CONFIG_SCRIPT). This means the following command will also build the release:

$ make

If you need to generate the release, and only the release, the rel target can be used:

$ make rel

Erlang.mk generates a tarball alongside the release, which can be directly uploaded to a server. The tarball is located at $(RELX_OUTPUT_DIR)/<name>/<name>-<vsn>.tar.gz. Set RELX_TAR=0 to skip it. make run skips it.

relx-post-rel runs after the release directory is assembled and before the tarball is written. You can define it to add files to the release tarball:

relx-post-rel::
    cp extra.txt $(RELX_OUTPUT_DIR)/example_release/

Erlang.mk provides a convenience function for running the release with one simple command:

$ make run

This command will also build the project and generate the release if they weren’t already. It starts the release in console mode, meaning you will also have a shell ready to use to check things as needed.

make run is currently not available on Windows.

If the release is already running, you can rebuild it and reload the changed modules into that node:

$ make RELOAD=1

This pings the release and then runs c:lm(). The release must have been built with {extended_start_script, true} in relx.config, which is what the relx.config template does. The build fails if the node cannot be reached.

RELOAD=1 is currently not available on Windows.

Erlang.mk provides a relup target for generating release upgrades. Release upgrades allow updating the code and the state of a running release without restarting it.

Once your changes are done, you need to update the version of the application(s) that will be updated. You also need to update the version of the release.

For each application that needs to be updated, an appup file must be written. Refer to the Erlang/OTP documentation for more details.

For the purpose of this section, assume the initial release version was 1, and the new version is 2. The name of the release will be example_release.

Once all this is done, you can build the tarball for the release upgrade:

$ make relup

This will create an archive at the root directory of the release, $RELX_OUTPUT_DIR/example_release/example_release-2.tar.gz.

Move the archive to the correct location on the running node. From the release’s root directory, the file inside releases/2/ is named after the release:

$ mkdir releases/2/
$ mv path/to/example_release-2.tar.gz releases/2/example_release.tar.gz

Finally, upgrade the release:

$ bin/example_release upgrade "2"

Or on Windows:

$ bin/example_release.cmd upgrade "2"

Your release was upgraded!