1REBAR3(1)                   General Commands Manual                  REBAR3(1)
2
3
4

NAME

6       rebar3 - tool for working with Erlang projects
7
8

SYNOPSIS

10       rebar3 --version
11
12       rebar3 help
13
14       rebar3 command [options] ...
15
16

DESCRIPTION

18       Rebar3  is  an  Erlang  tool that makes it easy to create, develop, and
19       release Erlang libraries, applications, and  systems  in  a  repeatable
20       manner.
21
22       Full documentation at http://www.rebar3.org/
23
24

ESSENTIAL COMMANDS

26       For the full command list, see the COMMANDS section.
27
28
29       With  rebar3  help  <task>, commands and plugins will display their own
30       help information.
31
32
33       compile
34              Compile the current project
35
36
37       new (help [template])|template
38              Show information about templates or use one
39
40
41       update Fetch the newest version of the Hex index
42
43
44       do command[,command,...]
45              Run one or more commands in a sequence
46
47
48       shell  Start  the  current  project  in  a  REPL.  You  can  then   use
49              r3:do(task)  to call it on the project without dropping the cur‐
50              rent state.
51
52

COMMANDS

54       as     Higher order provider for running multiple tasks in  a  sequence
55              as a certain profiles.
56
57       clean [-a|--all] [-p|--profile]
58              Remove compiled beam files from apps.
59
60              --all: Clean all apps include deps
61
62              --profile:  Clean  under profile. Equivalent to `rebar3 as <pro‐
63              file> clean`
64
65       compile [-d|--deps_only]
66              Compile apps .app.src and .erl files.
67
68              --deps_only: Only compile dependencies, no project apps will  be
69              built.
70
71       cover [-r|--reset] [-v|--verbose] [-m|--min_coverage]
72              Perform coverage analysis.
73
74              --reset: Reset all coverdata.
75
76              --verbose: Print coverage analysis.
77
78              --min_coverage:  Mandate  a coverage percentage required to suc‐
79              ceed (0..100)
80
81       ct [--dir] [--suite] [--group] [--case] [--label]  [--config]  [--spec]
82       [--join_specs]   [--allow_user_terms]  [--logdir]  [--logopts]  [--ver‐
83       bosity]  [-c|--cover]  [--cover_export_name]  [--repeat]   [--duration]
84       [--until]  [--force_stop] [--basic_html] [--stylesheet] [--decrypt_key]
85       [--decrypt_file]   [--abort_if_missing_suites]   [--multiply_timetraps]
86       [--scale_timetraps]    [--create_priv_dir]   [--include]   [--readable]
87       [-v|--verbose] [--name] [--sname] [--setcookie] [--sys_config]  [--com‐
88       pile_only] [--retry]
89              Run Common Tests.
90
91              --dir: List of additional directories containing test suites
92
93              --suite: List of test suites to run
94
95              --group: List of test groups to run
96
97              --case: List of test cases to run
98
99              --label: Test label
100
101              --config: List of config files
102
103              --spec: List of test specifications
104
105              --join_specs: Merge all test specifications and perform a single
106              test run
107
108              --allow_user_terms: Allow user defined config values  in  config
109              files
110
111              --logdir: Log folder
112
113              --logopts: Options for common test logging
114
115              --verbosity: Verbosity
116
117              --cover: Generate cover data
118
119              --cover_export_name: Base name of the coverdata file to write
120
121              --repeat: How often to repeat tests
122
123              --duration: Max runtime (format: HHMMSS)
124
125              --until: Run until (format: HHMMSS)
126
127              --force_stop:  Force  stop  on  test  timeout  (true  |  false |
128              skip_rest)
129
130              --basic_html: Show basic HTML
131
132              --stylesheet: CSS stylesheet to apply to html output
133
134              --decrypt_key: Path to key for decrypting config
135
136              --decrypt_file: Path to file containing key for decrypting  con‐
137              fig
138
139              --abort_if_missing_suites: Abort if suites are missing
140
141              --multiply_timetraps:
142
143              --scale_timetraps: Scale timetraps
144
145              --create_priv_dir: Create priv dir (auto_per_run | auto_per_tc |
146              manual_per_tc)
147
148              --include: Directories containing additional include files
149
150              --readable: Shows test case names  and  only  displays  logs  to
151              shell on failures (true | compact | false)
152
153              --verbose: Verbose output
154
155              --name: Gives a long name to the node
156
157              --sname: Gives a short name to the node
158
159              --setcookie: Sets the cookie if the node is distributed
160
161              --sys_config: List of application config files
162
163              --compile_only:  Compile  modules  in  the project with the test
164              configuration but do not run the tests
165
166              --retry: Experimental feature. If any specification  for  previ‐
167              ously failing test is found, runs them.
168
169       deps   List dependencies
170
171       dialyzer [-u|--update-plt] [-s|--succ-typings]
172              Run the Dialyzer analyzer on the project.
173
174              --update-plt: Enable updating the PLT. Default: true
175
176              --succ-typings: Enable success typing analysis. Default: true
177
178       do     Higher order provider for running multiple tasks in a sequence.
179
180       edoc   Generate documentation using edoc.
181
182       escriptize
183              Generate escript archive.
184
185       eunit   [--app]   [--application]   [-c|--cover]  [--cover_export_name]
186       [-d|--dir]  [-f|--file]   [-m|--module]   [-s|--suite]   [-v|--verbose]
187       [--name] [--sname] [--setcookie]
188              Run EUnit Tests.
189
190              --app:  Comma  separated list of application test suites to run.
191              Equivalent to `[{application, App}]`.
192
193              --application: Comma separated list of application  test  suites
194              to run. Equivalent to `[{application, App}]`.
195
196              --cover: Generate cover data. Defaults to false.
197
198              --cover_export_name: Base name of the coverdata file to write
199
200              --dir:  Comma separated list of dirs to load tests from. Equiva‐
201              lent to `[{dir, Dir}]`.
202
203              --file: Comma separated list of files to load tests from. Equiv‐
204              alent to `[{file, File}]`.
205
206              --module:  Comma  separated  list of modules to load tests from.
207              Equivalent to `[{module, Module}]`.
208
209              --suite: Comma separated list of modules  to  load  tests  from.
210              Equivalent to `[{module, Module}]`.
211
212              --verbose: Verbose output. Defaults to false.
213
214              --name: Gives a long name to the node
215
216              --sname: Gives a short name to the node
217
218              --setcookie: Sets the cookie if the node is distributed
219
220       get-deps
221              Fetch dependencies.
222
223       help   Display a list of tasks or help for a given task or subtask.
224
225       new [-f|--force]
226              Create new project from templates.
227
228              --force: overwrite existing files
229
230       path  [--app]  [--base] [--bin] [--ebin] [--lib] [--priv] [-s|--separa‐
231       tor] [--src] [--rel]
232              Print paths to build dirs in current profile.
233
234              --app: Comma separated list of applications to return paths for.
235
236              --base: Return the `base' path of the current profile.
237
238              --bin: Return the `bin' path of the current profile.
239
240              --ebin: Return all `ebin' paths of the current profile's  appli‐
241              cations.
242
243              --lib: Return the `lib' path of the current profile.
244
245              --priv: Return the `priv' path of the current profile's applica‐
246              tions.
247
248              --separator: In case of multiple  return  paths,  the  separator
249              character to use to join them.
250
251              --src:  Return  the `src' path of the current profile's applica‐
252              tions.
253
254              --rel: Return the `rel' path of the current profile.
255
256       pkgs   List information for a package.
257
258       release   [-n|--relname]   [-v|--relvsn]   [-g|--goal]    [-u|--upfrom]
259       [-o|--output-dir]  [-h|--help]  [-l|--lib-dir]  [-p|--path] [--default-
260       libs] [-V|--verbose]  [-d|--dev-mode]  [-i|--include-erts]  [-a|--over‐
261       ride] [-c|--config] [--overlay_vars] [--vm_args] [--sys_config] [--sys‐
262       tem_libs] [--version] [-r|--root]
263              Build release of project.
264
265              --relname: Specify the name for the release that will be  gener‐
266              ated
267
268              --relvsn: Specify the version for the release
269
270              --goal:  Specify  a  target  constraint on the system. These are
271              usually the OTP
272
273              --upfrom: Only valid with relup target, specify the  release  to
274              upgrade from
275
276              --output-dir: The output directory for the release. This is `./`
277              by default.
278
279              --help: Print usage
280
281              --lib-dir: Additional dir that should be searched for OTP Apps
282
283              --path: Additional dir to add to the code path
284
285              --default-libs: Whether to use the default system added lib dirs
286              (means you must add them all manually). Default is true
287
288              --verbose: Verbosity level, maybe between 0 and 3
289
290              --dev-mode:  Symlink the applications and configuration into the
291              release instead of copying
292
293              --include-erts: If true include a copy of  erts  used  to  build
294              with,  if  a  path  include  erts at that path. If false, do not
295              include erts
296
297              --override: Provide an app name and a directory to  override  in
298              the form <appname>:<app directory>
299
300              --config: The path to a config file
301
302              --overlay_vars: Path to a file of overlay variables
303
304              --vm_args: Path to a file to use for vm.args
305
306              --sys_config: Path to a file to use for sys.config
307
308              --system_libs: Path to dir of Erlang system libs
309
310              --version: Print relx version
311
312              --root: The project root directory
313
314       relup [-n|--relname] [-v|--relvsn] [-g|--goal] [-u|--upfrom] [-o|--out‐
315       put-dir]  [-h|--help]   [-l|--lib-dir]   [-p|--path]   [--default-libs]
316       [-V|--verbose]   [-d|--dev-mode]   [-i|--include-erts]  [-a|--override]
317       [-c|--config]  [--overlay_vars]  [--vm_args]   [--sys_config]   [--sys‐
318       tem_libs] [--version] [-r|--root]
319              Create relup of releases.
320
321              --relname:  Specify the name for the release that will be gener‐
322              ated
323
324              --relvsn: Specify the version for the release
325
326              --goal: Specify a target constraint on  the  system.  These  are
327              usually the OTP
328
329              --upfrom:  Only  valid with relup target, specify the release to
330              upgrade from
331
332              --output-dir: The output directory for the release. This is `./`
333              by default.
334
335              --help: Print usage
336
337              --lib-dir: Additional dir that should be searched for OTP Apps
338
339              --path: Additional dir to add to the code path
340
341              --default-libs: Whether to use the default system added lib dirs
342              (means you must add them all manually). Default is true
343
344              --verbose: Verbosity level, maybe between 0 and 3
345
346              --dev-mode: Symlink the applications and configuration into  the
347              release instead of copying
348
349              --include-erts:  If  true  include  a copy of erts used to build
350              with, if a path include erts at that  path.  If  false,  do  not
351              include erts
352
353              --override:  Provide  an app name and a directory to override in
354              the form <appname>:<app directory>
355
356              --config: The path to a config file
357
358              --overlay_vars: Path to a file of overlay variables
359
360              --vm_args: Path to a file to use for vm.args
361
362              --sys_config: Path to a file to use for sys.config
363
364              --system_libs: Path to dir of Erlang system libs
365
366              --version: Print relx version
367
368              --root: The project root directory
369
370       report Provide a crash report to be sent to the rebar3 issues page.
371
372       shell [--config] [--name] [--sname] [--setcookie]  [--script]  [--apps]
373       [--start-clean] [--user_drv_args]
374              Run shell with project apps and deps in path.
375
376              --config:  Path  to  the config file to use. Defaults to {shell,
377              [{config, File}]} and then the relx sys.config file if not spec‐
378              ified.
379
380              --name: Gives a long name to the node.
381
382              --sname: Gives a short name to the node.
383
384              --setcookie: Sets the cookie if the node is distributed.
385
386              --script:  Path  to  an  escript file to run before starting the
387              project apps. Defaults to  rebar.config  {shell,  [{script_file,
388              File}]} if not specified.
389
390              --apps:  A list of apps to boot before starting the shell. (E.g.
391              --apps app1,app2,app3) Defaults to rebar.config {shell,  [{apps,
392              Apps}]} or relx apps if not specified.
393
394              --start-clean:  Cancel  any  applications  in the 'apps' list or
395              release.
396
397              --user_drv_args: Arguments passed to user_drv start function for
398              creating custom shells.
399
400       tar  [-n|--relname]  [-v|--relvsn] [-g|--goal] [-u|--upfrom] [-o|--out‐
401       put-dir]  [-h|--help]   [-l|--lib-dir]   [-p|--path]   [--default-libs]
402       [-V|--verbose]   [-d|--dev-mode]   [-i|--include-erts]  [-a|--override]
403       [-c|--config]  [--overlay_vars]  [--vm_args]   [--sys_config]   [--sys‐
404       tem_libs] [--version] [-r|--root]
405              Tar archive of release built of project.
406
407              --relname:  Specify the name for the release that will be gener‐
408              ated
409
410              --relvsn: Specify the version for the release
411
412              --goal: Specify a target constraint on  the  system.  These  are
413              usually the OTP
414
415              --upfrom:  Only  valid with relup target, specify the release to
416              upgrade from
417
418              --output-dir: The output directory for the release. This is `./`
419              by default.
420
421              --help: Print usage
422
423              --lib-dir: Additional dir that should be searched for OTP Apps
424
425              --path: Additional dir to add to the code path
426
427              --default-libs: Whether to use the default system added lib dirs
428              (means you must add them all manually). Default is true
429
430              --verbose: Verbosity level, maybe between 0 and 3
431
432              --dev-mode: Symlink the applications and configuration into  the
433              release instead of copying
434
435              --include-erts:  If  true  include  a copy of erts used to build
436              with, if a path include erts at that  path.  If  false,  do  not
437              include erts
438
439              --override:  Provide  an app name and a directory to override in
440              the form <appname>:<app directory>
441
442              --config: The path to a config file
443
444              --overlay_vars: Path to a file of overlay variables
445
446              --vm_args: Path to a file to use for vm.args
447
448              --sys_config: Path to a file to use for sys.config
449
450              --system_libs: Path to dir of Erlang system libs
451
452              --version: Print relx version
453
454              --root: The project root directory
455
456       tree [-v|--verbose]
457              Print dependency tree.
458
459              --verbose: Print repo and branch/tag/ref for git and hg deps
460
461       unlock Unlock dependencies.
462
463       update Update package index.
464
465       upgrade
466              Upgrade dependencies.
467
468       version
469              Print version for rebar and current Erlang.
470
471       xref   Run cross reference analysis.
472
473

ENVIRONMENT

475       Environment variables  allow  overall  rebar3  control  across  command
476       boundaries.
477
478
479       REBAR_PROFILE
480              Choose a default profile. Defaults to default
481
482
483       HEX_CDN
484              Pick an alternative hex mirror.
485
486
487       REBAR_CACHE_DIR
488              Location of the directory for local cache. Defaults to hex.pm.
489
490
491       QUIET  Only display errors.
492
493
494       DEBUG  Display debug information.
495
496
497       REBAR_COLOR=high|low
498              How much color to show in the terminal. Defaults to high.
499
500
501       REBAR_CONFIG
502              Name of rebar configuration files. Defaults to rebar.config
503
504
505       REBAR_GIT_CLONE_OPTIONS
506              Arguments  to  add  after each git clone operation. For example,
507              the value --reference ~/.cache/repos.reference allows to  create
508              a cache of all fetched repositories across builds
509
510

Configuration File Options

512       See http://www.rebar3.org/v3.0/docs/configuration
513
514
515
516Erlang                           November 2018                       REBAR3(1)
Impressum