Configuring Assemblies

An "assembly" is a group of files and/or directories assembled into an archive and distributed. File system entries are included (or excluded) by setting up the appropriate entries in your configuration. For example, consider the following additions to a standard, top level rebar.config, which will put the entire rebar generated release into an archive:

rebar.config

{sub_dirs, ["rel"]}.
{dist, [
    {incl_dirs, ["rel/myapp"]}
]}.

Assembly Configuration Parameters

These parameters can be given at the top level, or to any assembly tuple, wherever it is sourced from.

Option	Description	Default
format	The output format, one of zip,tar,targz.	targz
outdir	The output directory into which generated archives should be placed.	./dist
workdir	The directory in which all temporary file system entries should be dealt with.	./dist/.work
incl_dirs	List of glob patterns, literal folder names or folder specs to include.	No Default
excl_dirs	List of glob patterns, literal folder names or folder specs to exclude.	No Default
incl_files	List of glob patterns, literal file names or file specs to include.	No Default
excl_files	List of glob patterns, literal file names or file specs to exclude.	No Default
vars_file	The (absolute or relative) path to a file containing variables for substitution.	See Notes below.
version	If given, specifies the version (or how to calculate it).	See Notes below.

Notes

An assembly tuple is defined as {assembly, Name, [Options]}, where Options are listed above. The Name of the assembly is used as the name of the generated archive, such that an assembly configuration {assembly, "myproject", Options} will produce a file named "myproject.zip" in the appropriate outdir. If provided, the result of evaluating version option is appended to the archive filename, such that {assembly, "myapp", [{version, "1.0.1"}|Rest]} will end up in a file named "myapp-1.0.1.zip".

The version option can also take a two tuple indicating that the current VCS should be used to calculate the version. For git, this takes {git, tag} which produces the most recent tag minus commit info. For all other VCS providers, this takes {vcs, ShellCommand}, evaluates ShellCommand in a sub-shell and captures stdout, strips any trailing whitespace from the output and uses the resulting string as the version. The vcs tuple equivalent to the {git, tag} option would be {vcs, "git describe --abbrev=0"}.

The incl and excl options for both files and folders take lists, containing one of three kinds of configuration entry. The first is a simple path, which can be relative or absolute and is represented as a string. The second form is a glob expression passed to (filelib:fold_files/5 and/or filelib:wildcard/1) in order to collect files (or directories), also represented as a string. When passed one of Path or Glob, an instance of the third configuration element is created. This spec tuple is defined as {spec, Path, Glob, Target, Mode, Template}. The Elements have the following semantics:

Element	Description	Default
Path	The (absolute or relative) path to the file or directory. Ignored if Glob is present.	undefined
Glob	A glob expression for the dile or directory.	undefined
Target	The target output directory (for files) or path (for directories).	See Further Notes below.
Mode	The file or directory permissions (set with file:change_mode/2).	See Further Notes below.
Template	If true, any matching file(s) are rendered by rebar_templater. Ignores directories	false.

Special Configuration Functions

When an assembly is located in an external dist.config, a few additional (convenience) functions can be utilised to simplify several common tasks. Some examples of these functions are listed below, and their descriptions provided in the following table.

{dist, [
    {assembly, "foo", [
        {format, tar},
        {vars_file, "myvars.vars"},
        {incl_files, [
            %% glob all .sh files, 
            %% apply templates (using myvars.vars)
            %% and place in "priv" in the resulting archive
            template({glob, "\\.sh$"}, "priv"),
            %% rename/relocate src/foo.app.src to ebin/foo.app
            spec("src/foo.app.src", name("ebin/foo.app"))]},
        {incl_dirs, ["ebin", "priv"]},
        %% exclude all content in dirs matching the glob expression
        {excl_dirs, [glob("**/build")]},
        {excl_files, [
            %% exclude all files matching the glob expression
            glob("rebar_.*_plugin\\.beam$"),
            glob("ebin/foo.app")]},
        {version, "1.2.3"}
    ]}
]}.

Further Notes

If the Target field is given, it is handled in the following manner prior to archiving:

• For files, the directory Target is used as the base directory in the archive, into which the files(s) will be placed

• For directories, the source directory is copied (recursively), into the Target location in the archive

If the Template field is set to true for a file, the contents of the assembly’s vars_file are loaded and passed to rebar_templater:render/2 along with the binary contents of the file. This field is ignored when processing directories.