- Notifications
You must be signed in to change notification settings - Fork 1
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:
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. |
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. |
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"} ]} ]}.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.