NAME¶

rebar3 - tool for working with Erlang projects

SYNOPSIS¶

rebar3 --version

rebar3 help

rebar3 command [options] ...

DESCRIPTION¶

Rebar3 is an Erlang tool that makes it easy to create, develop, and release Erlang libraries, applications, and systems in a repeatable manner.

Full documentation at http://www.rebar3.org/

ESSENTIAL COMMANDS¶

For the full command list, see the COMMANDS section.

With rebar3 help <task>, commands and plugins will display their own help information.

compile

Compile the current project

new (help [template])|template

Show information about templates or use one

update

Fetch the newest version of the Hex index

do command[,command,...]

Run one or more commands in a sequence

shell

Start the current project in a REPL. You can then use r3:do(task) to call it on the project without dropping the current state.

COMMANDS¶

as

Higher order provider for running multiple tasks in a sequence as a certain profiles.

clean [-a|--all] [-p|--profile]

Remove compiled beam files from apps.

--all: Clean all apps include deps

--profile: Clean under profile. Equivalent to `rebar3 as <profile> clean`

compile [-d|--deps_only]

Compile apps .app.src and .erl files.

--deps_only: Only compile dependencies, no project apps will be built.

cover [-r|--reset] [-v|--verbose] [-m|--min_coverage]

Perform coverage analysis.

--reset: Reset all coverdata.

--verbose: Print coverage analysis.

--min_coverage: Mandate a coverage percentage required to succeed (0..100)

ct [--dir] [--suite] [--group] [--case] [--label] [--config] [--spec] [--join_specs] [--allow_user_terms] [--logdir] [--logopts] [--verbosity] [-c|--cover] [--cover_export_name] [--repeat] [--duration] [--until] [--force_stop] [--basic_html] [--stylesheet] [--decrypt_key] [--decrypt_file] [--abort_if_missing_suites] [--multiply_timetraps] [--scale_timetraps] [--create_priv_dir] [--include] [--readable] [-v|--verbose] [--name] [--sname] [--setcookie] [--sys_config] [--compile_only] [--retry]

Run Common Tests.

--dir: List of additional directories containing test suites

--suite: List of test suites to run

--group: List of test groups to run

--case: List of test cases to run

--label: Test label

--config: List of config files

--spec: List of test specifications

--join_specs: Merge all test specifications and perform a single test run

--allow_user_terms: Allow user defined config values in config files

--logdir: Log folder

--logopts: Options for common test logging

--verbosity: Verbosity

--cover: Generate cover data

--cover_export_name: Base name of the coverdata file to write

--repeat: How often to repeat tests

--duration: Max runtime (format: HHMMSS)

--until: Run until (format: HHMMSS)

--force_stop: Force stop on test timeout (true | false | skip_rest)

--basic_html: Show basic HTML

--stylesheet: CSS stylesheet to apply to html output

--decrypt_key: Path to key for decrypting config

--decrypt_file: Path to file containing key for decrypting config

--abort_if_missing_suites: Abort if suites are missing

--multiply_timetraps:

--scale_timetraps: Scale timetraps

--create_priv_dir: Create priv dir (auto_per_run | auto_per_tc | manual_per_tc)

--include: Directories containing additional include files

--readable: Shows test case names and only displays logs to shell on failures (true | compact | false)

--verbose: Verbose output

--name: Gives a long name to the node

--sname: Gives a short name to the node

--setcookie: Sets the cookie if the node is distributed

--sys_config: List of application config files

--compile_only: Compile modules in the project with the test configuration but do not run the tests

--retry: Experimental feature. If any specification for previously failing test is found, runs them.

deps

List dependencies

dialyzer [-u|--update-plt] [-s|--succ-typings]

Run the Dialyzer analyzer on the project.

--update-plt: Enable updating the PLT. Default: true

--succ-typings: Enable success typing analysis. Default: true

do

Higher order provider for running multiple tasks in a sequence.

edoc

Generate documentation using edoc.

escriptize

Generate escript archive.

eunit [--app] [--application] [-c|--cover] [--cover_export_name] [-d|--dir] [-f|--file] [-m|--module] [-s|--suite] [-v|--verbose] [--name] [--sname] [--setcookie]

Run EUnit Tests.

--app: Comma separated list of application test suites to run. Equivalent to `[{application, App}]`.

--application: Comma separated list of application test suites to run. Equivalent to `[{application, App}]`.

--cover: Generate cover data. Defaults to false.

--cover_export_name: Base name of the coverdata file to write

--dir: Comma separated list of dirs to load tests from. Equivalent to `[{dir, Dir}]`.

--file: Comma separated list of files to load tests from. Equivalent to `[{file, File}]`.

--module: Comma separated list of modules to load tests from. Equivalent to `[{module, Module}]`.

--suite: Comma separated list of modules to load tests from. Equivalent to `[{module, Module}]`.

--verbose: Verbose output. Defaults to false.

--name: Gives a long name to the node

--sname: Gives a short name to the node

--setcookie: Sets the cookie if the node is distributed

get-deps

Fetch dependencies.

help

Display a list of tasks or help for a given task or subtask.

new [-f|--force]

Create new project from templates.

--force: overwrite existing files

path [--app] [--base] [--bin] [--ebin] [--lib] [--priv] [-s|--separator] [--src] [--rel]

Print paths to build dirs in current profile.

--app: Comma separated list of applications to return paths for.

--base: Return the `base' path of the current profile.

--bin: Return the `bin' path of the current profile.

--ebin: Return all `ebin' paths of the current profile's applications.

--lib: Return the `lib' path of the current profile.

--priv: Return the `priv' path of the current profile's applications.

--separator: In case of multiple return paths, the separator character to use to join them.

--src: Return the `src' path of the current profile's applications.

--rel: Return the `rel' path of the current profile.

pkgs

List information for a package.

release [-n|--relname] [-v|--relvsn] [-g|--goal] [-u|--upfrom] [-o|--output-dir] [-h|--help] [-l|--lib-dir] [-p|--path] [--default-libs] [-V|--verbose] [-d|--dev-mode] [-i|--include-erts] [-a|--override] [-c|--config] [--overlay_vars] [--vm_args] [--sys_config] [--system_libs] [--version] [-r|--root]

Build release of project.

--relname: Specify the name for the release that will be generated

--relvsn: Specify the version for the release

--goal: Specify a target constraint on the system. These are usually the OTP

--upfrom: Only valid with relup target, specify the release to upgrade from

--output-dir: The output directory for the release. This is `./` by default.

--help: Print usage

--lib-dir: Additional dir that should be searched for OTP Apps

--path: Additional dir to add to the code path

--default-libs: Whether to use the default system added lib dirs (means you must add them all manually). Default is true

--verbose: Verbosity level, maybe between 0 and 3

--dev-mode: Symlink the applications and configuration into the release instead of copying

--include-erts: If true include a copy of erts used to build with, if a path include erts at that path. If false, do not include erts

--override: Provide an app name and a directory to override in the form <appname>:<app directory>

--config: The path to a config file

--overlay_vars: Path to a file of overlay variables

--vm_args: Path to a file to use for vm.args

--sys_config: Path to a file to use for sys.config

--system_libs: Path to dir of Erlang system libs

--version: Print relx version

--root: The project root directory

relup [-n|--relname] [-v|--relvsn] [-g|--goal] [-u|--upfrom] [-o|--output-dir] [-h|--help] [-l|--lib-dir] [-p|--path] [--default-libs] [-V|--verbose] [-d|--dev-mode] [-i|--include-erts] [-a|--override] [-c|--config] [--overlay_vars] [--vm_args] [--sys_config] [--system_libs] [--version] [-r|--root]

Create relup of releases.

--relname: Specify the name for the release that will be generated

--relvsn: Specify the version for the release

--goal: Specify a target constraint on the system. These are usually the OTP

--upfrom: Only valid with relup target, specify the release to upgrade from

--output-dir: The output directory for the release. This is `./` by default.

--help: Print usage

--lib-dir: Additional dir that should be searched for OTP Apps

--path: Additional dir to add to the code path

--default-libs: Whether to use the default system added lib dirs (means you must add them all manually). Default is true

--verbose: Verbosity level, maybe between 0 and 3

--dev-mode: Symlink the applications and configuration into the release instead of copying

--include-erts: If true include a copy of erts used to build with, if a path include erts at that path. If false, do not include erts

--override: Provide an app name and a directory to override in the form <appname>:<app directory>

--config: The path to a config file

--overlay_vars: Path to a file of overlay variables

--vm_args: Path to a file to use for vm.args

--sys_config: Path to a file to use for sys.config

--system_libs: Path to dir of Erlang system libs

--version: Print relx version

--root: The project root directory

report

Provide a crash report to be sent to the rebar3 issues page.

shell [--config] [--name] [--sname] [--setcookie] [--script] [--apps] [--start-clean] [--user_drv_args]

Run shell with project apps and deps in path.

--config: Path to the config file to use. Defaults to {shell, [{config, File}]} and then the relx sys.config file if not specified.

--name: Gives a long name to the node.

--sname: Gives a short name to the node.

--setcookie: Sets the cookie if the node is distributed.

--script: Path to an escript file to run before starting the project apps. Defaults to rebar.config {shell, [{script_file, File}]} if not specified.

--apps: A list of apps to boot before starting the shell. (E.g. --apps app1,app2,app3) Defaults to rebar.config {shell, [{apps, Apps}]} or relx apps if not specified.

--start-clean: Cancel any applications in the 'apps' list or release.

--user_drv_args: Arguments passed to user_drv start function for creating custom shells.

tar [-n|--relname] [-v|--relvsn] [-g|--goal] [-u|--upfrom] [-o|--output-dir] [-h|--help] [-l|--lib-dir] [-p|--path] [--default-libs] [-V|--verbose] [-d|--dev-mode] [-i|--include-erts] [-a|--override] [-c|--config] [--overlay_vars] [--vm_args] [--sys_config] [--system_libs] [--version] [-r|--root]

Tar archive of release built of project.

--relname: Specify the name for the release that will be generated

--relvsn: Specify the version for the release

--goal: Specify a target constraint on the system. These are usually the OTP

--upfrom: Only valid with relup target, specify the release to upgrade from

--output-dir: The output directory for the release. This is `./` by default.

--help: Print usage

--lib-dir: Additional dir that should be searched for OTP Apps

--path: Additional dir to add to the code path

--default-libs: Whether to use the default system added lib dirs (means you must add them all manually). Default is true

--verbose: Verbosity level, maybe between 0 and 3

--dev-mode: Symlink the applications and configuration into the release instead of copying

--include-erts: If true include a copy of erts used to build with, if a path include erts at that path. If false, do not include erts

--override: Provide an app name and a directory to override in the form <appname>:<app directory>

--config: The path to a config file

--overlay_vars: Path to a file of overlay variables

--vm_args: Path to a file to use for vm.args

--sys_config: Path to a file to use for sys.config

--system_libs: Path to dir of Erlang system libs

--version: Print relx version

--root: The project root directory

tree [-v|--verbose]

Print dependency tree.

--verbose: Print repo and branch/tag/ref for git and hg deps

unlock

Unlock dependencies.

update

Update package index.

upgrade

Upgrade dependencies.

version

Print version for rebar and current Erlang.

xref

Run cross reference analysis.

ENVIRONMENT¶

Environment variables allow overall rebar3 control across command boundaries.

REBAR_PROFILE

Choose a default profile. Defaults to default

HEX_CDN

Pick an alternative hex mirror.

REBAR_CACHE_DIR

Location of the directory for local cache. Defaults to hex.pm.

QUIET

Only display errors.

DEBUG

Display debug information.

REBAR_COLOR=high|low

How much color to show in the terminal. Defaults to high.

REBAR_CONFIG

Name of rebar configuration files. Defaults to rebar.config

REBAR_GIT_CLONE_OPTIONS

Arguments to add after each git clone operation. For example, the value --reference ~/.cache/repos.reference allows to create a cache of all fetched repositories across builds

Configuration File Options¶

See http://www.rebar3.org/v3.0/docs/configuration