path: root/manpages/rebar3.1

.TH "REBAR3" "1" "January 2017" "Erlang"

.SH NAME

\fBrebar3\fR \- tool for working with Erlang projects

.SH "SYNOPSIS"

\fBrebar3\fR \fB\-\-version\fR

.br
\fBrebar3\fR \fBhelp\fR

.br
\fBrebar3\fR \fIcommand\fR [\fIoptions\fR] \.\.\.

.SH "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 \fIhttp://www.rebar3.org/\fR

.SH "ESSENTIAL COMMANDS"

For the full command list, see the \fICOMMANDS\fR section\.

.P
With \fBrebar3 help <task>\fR, commands and plugins will display their own help information\.

.TP
\fBcompile\fR
Compile the current project

.TP
\fBnew\fR (\fBhelp [\fItemplate\fR])|\fItemplate\fR
Show information about templates or use one

.TP
\fBupdate\fR
Fetch the newest version of the Hex index

.TP
\fBdo\fR \fIcommand\fR[,\fIcommand\fR,...]
Run one or more commands in a sequence

.TP
\fBshell\fR
Start the current project in a REPL\. You can then use \fBr3:do(\fItask\fR)\fR to call it on the project without dropping the current state.

.SH "COMMANDS"

. this section generated by running the contents of 'commands' in rebar3 shell

.TP
\fBas\fR 
Higher order provider for running multiple tasks in a sequence as a certain profiles.
.TP
\fBclean\fR [\fI-a\fR|\fI--all\fR] [\fI-p\fR|\fI--profile\fR] 
Remove compiled beam files from apps.
.IP
\fI--all\fR: Clean all apps include deps
.IP
\fI--profile\fR: Clean under profile. Equivalent to `rebar3 as <profile> clean`
.TP
\fBcompile\fR 
Compile apps .app.src and .erl files.
.TP
\fBcover\fR [\fI-r\fR|\fI--reset\fR] [\fI-v\fR|\fI--verbose\fR] [\fI-m\fR|\fI--min_coverage\fR] 
Perform coverage analysis.
.IP
\fI--reset\fR: Reset all coverdata.
.IP
\fI--verbose\fR: Print coverage analysis.
.IP
\fI--min_coverage\fR: Mandate a coverage percentage required to succeed (0..100)
.TP
\fBct\fR [\fI--dir\fR] [\fI--suite\fR] [\fI--group\fR] [\fI--case\fR] [\fI--label\fR] [\fI--config\fR] [\fI--spec\fR] [\fI--join_specs\fR] [\fI--allow_user_terms\fR] [\fI--logdir\fR] [\fI--logopts\fR] [\fI--verbosity\fR] [\fI-c\fR|\fI--cover\fR] [\fI--cover_export_name\fR] [\fI--repeat\fR] [\fI--duration\fR] [\fI--until\fR] [\fI--force_stop\fR] [\fI--basic_html\fR] [\fI--stylesheet\fR] [\fI--decrypt_key\fR] [\fI--decrypt_file\fR] [\fI--abort_if_missing_suites\fR] [\fI--multiply_timetraps\fR] [\fI--scale_timetraps\fR] [\fI--create_priv_dir\fR] [\fI--include\fR] [\fI--readable\fR] [\fI-v\fR|\fI--verbose\fR] [\fI--name\fR] [\fI--sname\fR] [\fI--setcookie\fR] [\fI--sys_config\fR] [\fI--compile_only\fR] [\fI--retry\fR] 
Run Common Tests.
.IP
\fI--dir\fR: List of additional directories containing test suites
.IP
\fI--suite\fR: List of test suites to run
.IP
\fI--group\fR: List of test groups to run
.IP
\fI--case\fR: List of test cases to run
.IP
\fI--label\fR: Test label
.IP
\fI--config\fR: List of config files
.IP
\fI--spec\fR: List of test specifications
.IP
\fI--join_specs\fR: Merge all test specifications and perform a single test run
.IP
\fI--allow_user_terms\fR: Allow user defined config values in config files
.IP
\fI--logdir\fR: Log folder
.IP
\fI--logopts\fR: Options for common test logging
.IP
\fI--verbosity\fR: Verbosity
.IP
\fI--cover\fR: Generate cover data
.IP
\fI--cover_export_name\fR: Base name of the coverdata file to write
.IP
\fI--repeat\fR: How often to repeat tests
.IP
\fI--duration\fR: Max runtime (format: HHMMSS)
.IP
\fI--until\fR: Run until (format: HHMMSS)
.IP
\fI--force_stop\fR: Force stop on test timeout (true | false | skip_rest)
.IP
\fI--basic_html\fR: Show basic HTML
.IP
\fI--stylesheet\fR: CSS stylesheet to apply to html output
.IP
\fI--decrypt_key\fR: Path to key for decrypting config
.IP
\fI--decrypt_file\fR: Path to file containing key for decrypting config
.IP
\fI--abort_if_missing_suites\fR: Abort if suites are missing
.IP
\fI--multiply_timetraps\fR: 
.IP
\fI--scale_timetraps\fR: Scale timetraps
.IP
\fI--create_priv_dir\fR: Create priv dir (auto_per_run | auto_per_tc | manual_per_tc)
.IP
\fI--include\fR: Directories containing additional include files
.IP
\fI--readable\fR: Shows test case names and only displays logs to shell on failures
.IP
\fI--verbose\fR: Verbose output
.IP
\fI--name\fR: Gives a long name to the node
.IP
\fI--sname\fR: Gives a short name to the node
.IP
\fI--setcookie\fR: Sets the cookie if the node is distributed
.IP
\fI--sys_config\fR: List of application config files
.IP
\fI--compile_only\fR: Compile modules in the project with the test configuration but do not run the tests
.IP
\fI--retry\fR: Experimental feature. If any specification for previously failing test is found, runs them.
.TP
\fBdeps\fR 
List dependencies
.TP
\fBdialyzer\fR [\fI-u\fR|\fI--update-plt\fR] [\fI-s\fR|\fI--succ-typings\fR] 
Run the Dialyzer analyzer on the project.
.IP
\fI--update-plt\fR: Enable updating the PLT. Default: true
.IP
\fI--succ-typings\fR: Enable success typing analysis. Default: true
.TP
\fBdo\fR 
Higher order provider for running multiple tasks in a sequence.
.TP
\fBedoc\fR 
Generate documentation using edoc.
.TP
\fBescriptize\fR 
Generate escript archive.
.TP
\fBeunit\fR [\fI--app\fR] [\fI--application\fR] [\fI-c\fR|\fI--cover\fR] [\fI--cover_export_name\fR] [\fI-d\fR|\fI--dir\fR] [\fI-f\fR|\fI--file\fR] [\fI-m\fR|\fI--module\fR] [\fI-s\fR|\fI--suite\fR] [\fI-v\fR|\fI--verbose\fR] [\fI--name\fR] [\fI--sname\fR] [\fI--setcookie\fR] 
Run EUnit Tests.
.IP
\fI--app\fR: Comma separated list of application test suites to run. Equivalent to `[{application, App}]`.
.IP
\fI--application\fR: Comma separated list of application test suites to run. Equivalent to `[{application, App}]`.
.IP
\fI--cover\fR: Generate cover data. Defaults to false.
.IP
\fI--cover_export_name\fR: Base name of the coverdata file to write
.IP
\fI--dir\fR: Comma separated list of dirs to load tests from. Equivalent to `[{dir, Dir}]`.
.IP
\fI--file\fR: Comma separated list of files to load tests from. Equivalent to `[{file, File}]`.
.IP
\fI--module\fR: Comma separated list of modules to load tests from. Equivalent to `[{module, Module}]`.
.IP
\fI--suite\fR: Comma separated list of modules to load tests from. Equivalent to `[{module, Module}]`.
.IP
\fI--verbose\fR: Verbose output. Defaults to false.
.IP
\fI--name\fR: Gives a long name to the node
.IP
\fI--sname\fR: Gives a short name to the node
.IP
\fI--setcookie\fR: Sets the cookie if the node is distributed
.TP
\fBget-deps\fR 
Fetch dependencies.
.TP
\fBhelp\fR 
Display a list of tasks or help for a given task or subtask.
.TP
\fBnew\fR [\fI-f\fR|\fI--force\fR] 
Create new project from templates.
.IP
\fI--force\fR: overwrite existing files
.TP
\fBpath\fR [\fI--app\fR] [\fI--base\fR] [\fI--bin\fR] [\fI--ebin\fR] [\fI--lib\fR] [\fI--priv\fR] [\fI-s\fR|\fI--separator\fR] [\fI--src\fR] [\fI--rel\fR] 
Print paths to build dirs in current profile.
.IP
\fI--app\fR: Comma separated list of applications to return paths for.
.IP
\fI--base\fR: Return the `base' path of the current profile.
.IP
\fI--bin\fR: Return the `bin' path of the current profile.
.IP
\fI--ebin\fR: Return all `ebin' paths of the current profile's applications.
.IP
\fI--lib\fR: Return the `lib' path of the current profile.
.IP
\fI--priv\fR: Return the `priv' path of the current profile's applications.
.IP
\fI--separator\fR: In case of multiple return paths, the separator character to use to join them.
.IP
\fI--src\fR: Return the `src' path of the current profile's applications.
.IP
\fI--rel\fR: Return the `rel' path of the current profile.
.TP
\fBpkgs\fR 
List available packages.
.TP
\fBrelease\fR [\fI-n\fR|\fI--relname\fR] [\fI-v\fR|\fI--relvsn\fR] [\fI-g\fR|\fI--goal\fR] [\fI-u\fR|\fI--upfrom\fR] [\fI-o\fR|\fI--output-dir\fR] [\fI-h\fR|\fI--help\fR] [\fI-l\fR|\fI--lib-dir\fR] [\fI-p\fR|\fI--path\fR] [\fI--default-libs\fR] [\fI-V\fR|\fI--verbose\fR] [\fI-d\fR|\fI--dev-mode\fR] [\fI-i\fR|\fI--include-erts\fR] [\fI-a\fR|\fI--override\fR] [\fI-c\fR|\fI--config\fR] [\fI--overlay_vars\fR] [\fI--vm_args\fR] [\fI--sys_config\fR] [\fI--system_libs\fR] [\fI--version\fR] [\fI-r\fR|\fI--root\fR] 
Build release of project.
.IP
\fI--relname\fR: Specify the name for the release that will be generated
.IP
\fI--relvsn\fR: Specify the version for the release
.IP
\fI--goal\fR: Specify a target constraint on the system. These are usually the OTP
.IP
\fI--upfrom\fR: Only valid with relup target, specify the release to upgrade from
.IP
\fI--output-dir\fR: The output directory for the release. This is `./` by default.
.IP
\fI--help\fR: Print usage
.IP
\fI--lib-dir\fR: Additional dir that should be searched for OTP Apps
.IP
\fI--path\fR: Additional dir to add to the code path
.IP
\fI--default-libs\fR: Whether to use the default system added lib dirs (means you must add them all manually). Default is true
.IP
\fI--verbose\fR: Verbosity level, maybe between 0 and 3
.IP
\fI--dev-mode\fR: Symlink the applications and configuration into the release instead of copying
.IP
\fI--include-erts\fR: 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
.IP
\fI--override\fR: Provide an app name and a directory to override in the form <appname>:<app directory>
.IP
\fI--config\fR: The path to a config file
.IP
\fI--overlay_vars\fR: Path to a file of overlay variables
.IP
\fI--vm_args\fR: Path to a file to use for vm.args
.IP
\fI--sys_config\fR: Path to a file to use for sys.config
.IP
\fI--system_libs\fR: Path to dir of Erlang system libs
.IP
\fI--version\fR: Print relx version
.IP
\fI--root\fR: The project root directory
.TP
\fBrelup\fR [\fI-n\fR|\fI--relname\fR] [\fI-v\fR|\fI--relvsn\fR] [\fI-g\fR|\fI--goal\fR] [\fI-u\fR|\fI--upfrom\fR] [\fI-o\fR|\fI--output-dir\fR] [\fI-h\fR|\fI--help\fR] [\fI-l\fR|\fI--lib-dir\fR] [\fI-p\fR|\fI--path\fR] [\fI--default-libs\fR] [\fI-V\fR|\fI--verbose\fR] [\fI-d\fR|\fI--dev-mode\fR] [\fI-i\fR|\fI--include-erts\fR] [\fI-a\fR|\fI--override\fR] [\fI-c\fR|\fI--config\fR] [\fI--overlay_vars\fR] [\fI--vm_args\fR] [\fI--sys_config\fR] [\fI--system_libs\fR] [\fI--version\fR] [\fI-r\fR|\fI--root\fR] 
Create relup of releases.
.IP
\fI--relname\fR: Specify the name for the release that will be generated
.IP
\fI--relvsn\fR: Specify the version for the release
.IP
\fI--goal\fR: Specify a target constraint on the system. These are usually the OTP
.IP
\fI--upfrom\fR: Only valid with relup target, specify the release to upgrade from
.IP
\fI--output-dir\fR: The output directory for the release. This is `./` by default.
.IP
\fI--help\fR: Print usage
.IP
\fI--lib-dir\fR: Additional dir that should be searched for OTP Apps
.IP
\fI--path\fR: Additional dir to add to the code path
.IP
\fI--default-libs\fR: Whether to use the default system added lib dirs (means you must add them all manually). Default is true
.IP
\fI--verbose\fR: Verbosity level, maybe between 0 and 3
.IP
\fI--dev-mode\fR: Symlink the applications and configuration into the release instead of copying
.IP
\fI--include-erts\fR: 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
.IP
\fI--override\fR: Provide an app name and a directory to override in the form <appname>:<app directory>
.IP
\fI--config\fR: The path to a config file
.IP
\fI--overlay_vars\fR: Path to a file of overlay variables
.IP
\fI--vm_args\fR: Path to a file to use for vm.args
.IP
\fI--sys_config\fR: Path to a file to use for sys.config
.IP
\fI--system_libs\fR: Path to dir of Erlang system libs
.IP
\fI--version\fR: Print relx version
.IP
\fI--root\fR: The project root directory
.TP
\fBreport\fR 
Provide a crash report to be sent to the rebar3 issues page.
.TP
\fBshell\fR [\fI--config\fR] [\fI--name\fR] [\fI--sname\fR] [\fI--setcookie\fR] [\fI--script\fR] [\fI--apps\fR] [\fI--user_drv_args\fR] 
Run shell with project apps and deps in path.
.IP
\fI--config\fR: Path to the config file to use. Defaults to {shell, [{config, File}]} and then the relx sys.config file if not specified.
.IP
\fI--name\fR: Gives a long name to the node.
.IP
\fI--sname\fR: Gives a short name to the node.
.IP
\fI--setcookie\fR: Sets the cookie if the node is distributed.
.IP
\fI--script\fR: Path to an escript file to run before starting the project apps. Defaults to rebar.config {shell, [{script_file, File}]} if not specified.
.IP
\fI--apps\fR: 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.
.IP
\fI--user_drv_args\fR: Arguments passed to user_drv start function for creating custom shells.
.TP
\fBtar\fR [\fI-n\fR|\fI--relname\fR] [\fI-v\fR|\fI--relvsn\fR] [\fI-g\fR|\fI--goal\fR] [\fI-u\fR|\fI--upfrom\fR] [\fI-o\fR|\fI--output-dir\fR] [\fI-h\fR|\fI--help\fR] [\fI-l\fR|\fI--lib-dir\fR] [\fI-p\fR|\fI--path\fR] [\fI--default-libs\fR] [\fI-V\fR|\fI--verbose\fR] [\fI-d\fR|\fI--dev-mode\fR] [\fI-i\fR|\fI--include-erts\fR] [\fI-a\fR|\fI--override\fR] [\fI-c\fR|\fI--config\fR] [\fI--overlay_vars\fR] [\fI--vm_args\fR] [\fI--sys_config\fR] [\fI--system_libs\fR] [\fI--version\fR] [\fI-r\fR|\fI--root\fR] 
Tar archive of release built of project.
.IP
\fI--relname\fR: Specify the name for the release that will be generated
.IP
\fI--relvsn\fR: Specify the version for the release
.IP
\fI--goal\fR: Specify a target constraint on the system. These are usually the OTP
.IP
\fI--upfrom\fR: Only valid with relup target, specify the release to upgrade from
.IP
\fI--output-dir\fR: The output directory for the release. This is `./` by default.
.IP
\fI--help\fR: Print usage
.IP
\fI--lib-dir\fR: Additional dir that should be searched for OTP Apps
.IP
\fI--path\fR: Additional dir to add to the code path
.IP
\fI--default-libs\fR: Whether to use the default system added lib dirs (means you must add them all manually). Default is true
.IP
\fI--verbose\fR: Verbosity level, maybe between 0 and 3
.IP
\fI--dev-mode\fR: Symlink the applications and configuration into the release instead of copying
.IP
\fI--include-erts\fR: 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
.IP
\fI--override\fR: Provide an app name and a directory to override in the form <appname>:<app directory>
.IP
\fI--config\fR: The path to a config file
.IP
\fI--overlay_vars\fR: Path to a file of overlay variables
.IP
\fI--vm_args\fR: Path to a file to use for vm.args
.IP
\fI--sys_config\fR: Path to a file to use for sys.config
.IP
\fI--system_libs\fR: Path to dir of Erlang system libs
.IP
\fI--version\fR: Print relx version
.IP
\fI--root\fR: The project root directory
.TP
\fBtree\fR [\fI-v\fR|\fI--verbose\fR] 
Print dependency tree.
.IP
\fI--verbose\fR: Print repo and branch/tag/ref for git and hg deps
.TP
\fBunlock\fR 
Unlock dependencies.
.TP
\fBupdate\fR 
Update package index.
.TP
\fBupgrade\fR 
Upgrade dependencies.
.TP
\fBversion\fR 
Print version for rebar and current Erlang.
.TP
\fBxref\fR 
Run cross reference analysis.

.SH ENVIRONMENT

Environment variables allow overall rebar3 control across command boundaries.

.TP
\fBREBAR_PROFILE\fR
Choose a default profile. Defaults to \fBdefault\fR

.TP
\fBHEX_CDN\fR
Pick an alternative hex mirror.

.TP
\fBREBAR_CACHE_DIR\fR
Location of the directory for local cache. Defaults to \fIhex.pm\fB.

.TP
\fBQUIET\fR
Only display errors.

.TP
\fBDEBUG\fR
Display debug information.

.TP
\fBREBAR_COLOR\fR=\fIhigh\fR|\fIlow\fR
How much color to show in the terminal. Defaults to \fIhigh\fR.

.TP
\fBREBAR_CONFIG\fR
Name of rebar configuration files. Defaults to \fIrebar.config\fR

.SH Configuration File Options
See \fIhttp://www.rebar3.org/v3.0/docs/configuration\fR