Commands

Usage of each Rebar3 command.

Each command represents a task which runs one or more providers to fulfill the task.

alias

List aliases' definitions (from rebar.config).

Example output:

test=eunit,ct --suite=rebar_alias_SUITE,cover
check=xref,dialyzer

as

Higher order task which takes a profile name and list of tasks to run under that profile.

compile

After ensuring all dependencies are available, and fetching them if they are not, compile will compile the needed dependencies and the project's apps' .app.src and .erl files.

completion

Generates a completion file for one of the supported shells: bash, zsh.

Completion files can be generated based on the project setup, so autocompletion also works for all plugins used in the project, not just for default providers.

To use generated completion files run source path/to/generated/file.

For better user experience, set default autocompletion and override it when needed. Default autocompletion can be set by generating a global completion file and loading it in .bashrc or .zshrc.

To generate a global (project-independent) completion file run rebar3 completion --file path/to/global/completion/file outside a rebar3 project.

clean

Removes compiled BEAM files from apps.

The clean command by default removes the BEAM files for top-level applications. It does so while respecting profiles, which means that 'rebar3 clean' will only clean the default profile, and 'rebar3 as test clean' will only clean the test profile.

ct

Runs common tests for the project located under the test/ directory.

Most Common Test options as described in the Erlang documentation for ct_run are available. Some common ones are described below:

Runs in the test profile.

cover

Performs coverage analysis on modules called by Common Test or Eunit test suites. Call as rebar3 do ct, cover, rebar3 do eunit, cover or the combination of both with rebar3 do eunit, ct, cover while the {cover_enabled, true} option is in your rebar config file, or if the cover flags were used with these commands individually.

An HTML report is generated.

Specific modules can be blacklisted from code coverage by adding {cover_excl_mods, [Modules]} to the config file. Specific applications can be blacklisted by adding {cover_excl_apps, [AppNames]} to the config file.

deps

Lists dependencies, whether they're source or package dependencies, and whether they're locked or not. Those that are locked but not matching the lock file are followed by an asterisk (*).

do

Higher order provider for running multiple tasks in a sequence, separated by commas. Example: rebar3 do a, b, c.

dialyzer

Builds and keeps up-to-date a suitable PLT (Persistent Lookup Table), and uses it to carry out success typing analysis on the current project.

For instructions on suppressing warnings read the Requesting or Suppressing Warnings in Source Files section of the Dialyzer documentation.

PLT files are named <prefix>_<otp_release>_plt; The base PLT is a PLT containing the core applications often required for a project's PLT. One base PLT is created per OTP version and stored in base_plt_location. A base PLT is then used to build project PLTs.

The following (optional) configurations can be added to a proplist of options dialyzer in rebar.config:

edoc

Generates documentation using doc.

Runs in the docs profile.

escriptize

Generates an escript executable containing the project's and its dependencies' BEAM files.

To override the default module name for the escript (which is expected to be the same as the escript_name), add -escript main Module to escript_emu_args.

Example escript configuration from relx:

{escript_emu_args, "%%! +sbtu +A0 -noinput\n"}.
{escript_incl_apps, [getopt, erlware_commons, bbmustache, providers, relx]}.

eunit

Runs EUnit tests on project apps.

For more details, see EUnit.

Runs in the test profile.

get-deps

Fetch project dependencies.

help

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

new

Creates a new project from templates. See a list of available templates by providing no arguments.

path

Print paths to build dirs in current profile.

release

Builds release of project. Call rebar3 help release for arguments.

relup

Creates a relup from two releases that were already built by calling rebar3 release without clearing the _build directory. Call rebar3 help relup for arguments.

report

Generates contextual data to include in bug reports.

shell

Runs a shell with project apps and deps in path. Intended for development use only; use Releases for production.

The shell booted with this command has a running agent that allows running Rebar3 commands dynamically, such as r3:compile() or r3:upgrade(), and have new modules automatically reloaded. Specific namespaces can be reached by calling r3:do(Namespace, Command). No arguments can be passed to these commands.

tar

Builds a compressed tar archive of release built of project. Call rebar3 help tar for arguments.

tree

Prints a tree of dependencies and transitive dependencies of the project.

lock

Get unbuilt dependencies to be added to the rebar.lock file. They will just have been downloaded, but none of their build script should have run. Though this is not necessarily true with pre/post hooks and dep plugins.

unlock

Unlocks dependencies. Specify a comma separated list of dependencies to unlock and regenerate the rebar.lock file, or -a,--all to unlock them all and remove the rebar.lock file.

This command should be used when one or more dependencies have been taken out of rebar.config, but remain in the lock file.

update

Updates the package index.

upgrade

Takes the current dependency specifications in rebar.config and fetches the most up-to-date versions satisfying them, while updating the lock file accordingly.

version

Prints version for rebar3 and current Erlang.

xref

Runs cross reference analysis.