Configuring the Plugin

The plugin can be configured directly in your project’s rebar.config file. You may also specify an external config file, from which to load assembly definitions. Only assembly definitions can be imported from an external file in this manner, and you must specify either a relative, or an absolute path to the file. This allows you to share common assembly definitions between projects if you wish. The external configuration is included by adding the following lines to your rebar config:

rebar.config

{dist, [{config, "dist.config"}]}.

Including Assemblies

Assemblies can be defined and/or included in a couple of ways.

Anonymous Assemblies

Any assembly which is defined at the top level in your rebar.config will be executed in response to the rebar dist command. These definitions form what is known as an anonymous assembly; Because these configuration elements are defined outside of the usual assembly tuple, they’re useless outside of their configuration scope. The only thing the plugin can do is execute them, unless it is to throw away the configuration values. When taken alongside the fact that it is an error to define an Assembly more than once, this means that top level configuration should only be declared in one place. Trying to declare an anonymous assembly in an external (e.g., in a file you reference via {config, Path}) is an error (and the external options will be ignored).

Named Assemblies

Named assemblies, declared as {assembly, Name, [Option]}, are treated quite differently. If they’re defined at the top level in your rebar.config, then they’re executed in the same manner as anonymous assemblies. Because they have a different scope, this allows you define multiple output targets in a single configuration file. For example:

rebar.config

{dist, [
    {assembly, "assembly1", %% 
        [{incl_dirs, ["dir1", "dir2"]},
         {excl_dirs, ["dir3"}]},
    {assembly, "assembly2", %% 
        [{incl_dirs, ["dir3/*"]},
         {excl_dirs, ["dir1", "dir2"]}]}
]}.

As both of these (assemblies) have been defined in the top level dist element, they will both be executed when the rebar dist command is run. The reverse situation is true when you include an external configuration file containing Named assemblies into your rebar.config. In this case, you must explicitly import the named assemblies into your top level config in order to execute them. Consider the following two configurations which demonstrate this:

rebar.config

%% here we *include* the dist.config elements, but do nothing with them
{dist, [{config, "dist.config"},
        {assembly, "assembly1", %% we also define and execute a named assembly at this level
            [{incl_dirs, ["dir1", "dir2"]},
             {excl_dirs, ["dir3"}]}]}.

%% here we include *all* the definitions in dist.config, but use only `mydist'
{dist, [
    {config, "dist.config"},
    {assembly, "mydist"}   %% this effectively marks the "mydist" assembly for processing
]}.

Built-In Assemblies

The plugin comes with some pre-defined assemblies, which you can reuse by simply referencing them in your rebar.config like so:

%% Using the built in assembly configuration(s)
{dist, [
    {assembly, release},  %% archives a release
    {assembly, project},  %% archives the current project (ebin, include, priv)
    {assembly, sources},  %% archives the whole project directory *as is*
    {assembly, doc}       %% archives the project's doc folder
]}.

There is (currently) no way to override the default configuration values in these assemblies. You can however, provide additional configuration which will be appended to an existing element. If for example, you pull in the built-in release assembly and want to exclude some additional directories, you can do so like this:

{dist, [
    {excl_dirs, ["dir1", "dir2"]},
    {assembly, release}
]}.