REBAR3(1)

📦
version 3.27.3 · 2 versions
, in alpine 3.24, arch rolling, fedora 43, fedora 44, opensuse-leap 16.0

💖 REBAR3(1) — the girlies' guide to the rebar3 manual page 💖

General Commands Manual · REBAR3(1)

okay bestie, sit DOWN, because we're about to go through the entire rebar3 manual together and I promise it's gonna be more fun than it has any right to be. this is part 1 so don't you dare think we're done. 💅

✨ NAME ✨

rebar3 — the tool for working with Erlang projects. that's it. that's the whole vibe. 🎀

✨ SYNOPSIS ✨

rebar3 --version

rebar3 help

rebar3 command [options] ...

literally three shapes, that's all she wrote: ask for the version, ask for help, or run a command with some options tacked on the end. slay. ✨

✨ DESCRIPTION ✨

Rebar3 is an Erlang tool that makes it easy to create, develop, and release Erlang libraries, applications, and systems in a repeatable manner. no chaos, no "it worked on my machine", just repeatable. iconic behaviour honestly. 💖

Full documentation at http://www.rebar3.org/ — go look, it's giving knowledge. 📚

✨ ESSENTIAL COMMANDS ✨

okay so for the full command list you gotta scroll down to the COMMANDS section, but here's the starter pack, the main-character commands, the ones you'll actually be typing every single day.

Also real quick: with rebar3 help <task>, commands and plugins will display their own help information. so if you're lost, just ask. they'll tell you. 🫶

  • compile — Compile the current project. yes queen, build it. 🔥
  • new (help [template])|template — Show information about templates or use one. templates are your little project blueprints. 🎀
  • update — Fetch the newest version of the Hex index. gotta stay fresh, gotta stay updated, no cap. ✨
  • do command[,command,...] — Run one or more commands in a sequence. multiple commands, one girlboss move. 👑
  • 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. this is the good stuff, keep your session alive while you poke at tasks. 🦋

✨ COMMANDS ✨

here we go, the full menu. every single one. no skipping, no summarising, we're eating the whole plate. 🍓

as

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

(that's the original wording and I'm keeping it exactly, plural profiles and all, because facts are facts. 😌)

clean

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

Remove compiled beam files from apps.

  • -a, --all — Clean all apps include deps. everything. the whole closet. 💀
  • -p, --profile — Clean under profile. Equivalent to rebar3 as <profile> clean.

compile

compile [-d|--deps_only]

Compile apps .app.src and .erl files.

  • -d, --deps_only — Only compile dependencies, no project apps will be built. deps only, your own apps get to nap. 😴

cover

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

Perform coverage analysis.

  • -r, --reset — Reset all coverdata.
  • -v, --verbose — Print coverage analysis.
  • -m, --min_coverage — Mandate a coverage percentage required to succeed (0..100). yes, a number from 0 to 100, and yes, you have to hit it. no hiding from the numbers bestie. 📊

ct

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. this is the big one, the marathon, the ct girlies know. 🏃♀️💨

  • --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
  • -c, --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 — (yep, the original gives this one no description at all, so I'm not inventing one. it exists, it's there, that's the tea. 🫖)
  • --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)
  • -v, --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.
⚠️ heads up bestie: --retry is marked Experimental feature in the original. experimental means experimental. don't be shocked if it does experimental things. 🙈

deps

List dependencies. just... lists them. simple. clean. a little snack. 🍓

dialyzer

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

Run the Dialyzer analyzer on the project.

  • -u, --update-plt — Enable updating the PLT. Default: true
  • -s, --succ-typings — Enable success typing analysis. Default: true

both default to true btw, so dialyzer is doing the most right out of the box. 🔥

do

Higher order provider for running multiple tasks in a sequence.

edoc

Generate documentation using edoc. docs are self care. 📚✨

escriptize

Generate escript archive.

eunit

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}].
  • -c, --cover — Generate cover data. Defaults to false.
  • --cover_export_name — Base name of the coverdata file to write
  • -d, --dir — Comma separated list of dirs to load tests from. Equivalent to [{dir, Dir}].
  • -f, --file — Comma separated list of files to load tests from. Equivalent to [{file, File}].
  • -m, --module — Comma separated list of modules to load tests from. Equivalent to [{module, Module}].
  • -s, --suite — Comma separated list of modules to load tests from. Equivalent to [{module, Module}].
  • -v, --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
💀 not me noticing --module and --suite have the exact same description and the exact same [{module, Module}] equivalent. that's how the original rolls, so that's how we roll. copy it verbatim, don't "fix" it.

get-deps

Fetch dependencies. go get 'em. 🏃♀️

help

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

new

new [-f|--force]

Create new project from templates. baby's first project, so cute. 🎀

  • -f, --force — overwrite existing files
⚠️ --force means overwrite existing files. like, actually overwrite them. be sure before you commit to that energy.

path

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. (keeping that stray backtick exactly as the original has it, iykyk 💅)
  • --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.
  • -s, --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

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. this is the big girlboss finale energy. 👑

  • -n, --relname — Specify the name for the release that will be generated
  • -v, --relvsn — Specify the version for the release
  • -g, --goal — Specify a target constraint on the system. These are usually the OTP
  • -u, --upfrom — Only valid with relup target, specify the release to upgrade from
  • -o, --output-dir — The output directory for the release. This is ./ by default.
  • -h, --help — Print usage
  • -l, --lib-dir — Additional dir that should be searched for OTP Apps
  • -p, --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
  • -V, --verbose — Verbosity level, maybe between 0 and 3
  • -d, --dev-mode — Symlink the applications and configuration into the release instead of copying
  • -i, --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
  • -a, --override — Provide an app name and a directory to override in the form <appname>:<app directory>
  • -c, --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
  • -r, --root — The project root directory

relup

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. upgrade paths, we love a glow-up. 🌈

  • -n, --relname — Specify the name for the release that will be generated
  • -v, --relvsn — Specify the version for the release
  • -g, --goal — Specify a target constraint on the system. These are usually the OTP
  • -u, --upfrom — Only valid with relup target, specify the release to upgrade from
  • -o, --output-dir — The output directory for the release. This is ./ by default.
  • -h, --help — Print usage
  • -l, --lib-dir — Additional dir that should be searched for OTP Apps
  • -p, --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
  • -V, --verbose — Verbosity level, maybe between 0 and 3
  • -d, --dev-mode — Symlink the applications and configuration into the release instead of copying
  • -i, --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
  • -a, --override — Provide an app name and a directory to override in the form <appname>:<app directory>
  • -c, --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

okay wait. that's where part 1 of this manual page ends — the relup options list runs out right at --system_libs and then the original just... continues in the next chunk. so we are NOT done bestie, hold on, there's more page coming. don't go anywhere. 💜

  • --version — Print relx version 💅
  • --root — The project root directory 🏠

📋 report

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

🐚 shell

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

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

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. 🔗

Source: Erlang, dated November 2018, for REBAR3(1) — slay bestie, bye 💖✨

📦 where this page comes from