rebar3 release



  • as

後面接 profile name,就是以該 profile 運作

  • compile

在確認所有 dependencies 都存在時,可編譯所有 dependencies, 專案的 .app.src 及 .erl

Option Type Description
-d/--deps_only none Only compile dependencies
  • clean

移除 beam files

rebar3 clean 只會清除 default profile

rebar3 as test clean 會清除 test profile

Option Type Description
--all/-a none Clean all apps, including the dependencies
--apps Comma separated list of strings Clean a specific list of apps or dependencies
--profile/-p string Specify a profile (alternative to rebar3 as clean)
  • ct

執行 test/ 目錄下面的 common tests

options 裡面有全部 ct_run 的 options

Option Type Description
--dir Comma separated list of strings 編譯/執行某目錄的 all test suites
--suite Comma separated list of strings 編譯/執行特定 test suites,可用絕對/相對路徑
--group Comma separated list of strings Test groups to run. See the Common Test Documentation.
--case Comma separated list of strings List of test cases to run. See the Common Test Documentation.
--spec Comma separated list of strings List of Test Specifications
--join_specs Comma separated list of strings 類似 --spec 但把所有 spec 整合成一個
--repeat Integer 多久重複 tests 一次
--duration String (format: HHMMSS) 可容許 test 運作最長的時間
--until String (format: HHMMSS) 執行 test 到什麼時間
--force_stop `true false
--multiply_timetraps Integer 以特定乘數擴充test 的 timeout values
--scale_timetraps Boolean 在 code coverage/tracing 時,使用automatic timeout value scaling
--abort_if_missing_suites Boolean 如果 test suite 不存在,要不要放棄(Default: true)
--sys_config String 執行 test 時要使用的 config file list (like sys.config)
--config Comma separated list of strings 執行 test 使用的 config files,ref: Common Test Documentation
--allow_user_terms Boolean 可自訂 config values in config files ref: Common Test Documentation.
--decrypt_key String 設定解密的 key
--decrypt_file String 設定解密的 key file
--logdir String 寫入 test logs 的目錄 ref: Common Test Documentation. Default: _build/test/logs
--logopts Comma separated list of strings 設定 common test logging options. ref: Common Test Documentation. Default: _build/test/logs
--readable Boolean 在 report 增加 test names, Default: true
--verbose, -v Boolean 啟用 verbose output Default: false
--verbosity Integer 設定 log verbosity level
--cover, -c Boolean 產生 cover data
--cover_export_name String 修改 code coverage filename
--label String Set a test label
--basic_html Boolean show basic HTML
--stylesheet String CSS stylesheet to apply to HTML output
--create_priv_dir `auto_per_run auto_per_tc
--include String 設定 include files 的目錄
--name, --sname String 以某個名稱啟動 a distributed node
--setcookie String 設定 cookie
--compile_only Boolean 以特定 test config 編譯專案,但不執行 test
  • cover

由 Common Test/Enuit test suite 產生 coverage analysis

rebar3 do ct, cover

rebar3 do eunit, cover

rebar3 do eunit, ct, cover

其中 rebar.config 有設定 {cover_enabled, true},會產生 html report

Option Type Description
-m, --min_coverage Integer Mandate a coverage percentage required to succeed (0..100)
--reset, -r none Resets all cover data
--verbose, -v none Prints coverage analysis in the terminal.

可用 {cover_excl_mods, [Modules]}{cover_excl_apps, [AppNames]} 做 blacklist

  • deps

列出 dependencies,以及是否有 locked

  • do

依序執行 tasks

rebar3 do a,b,c
  • dialyzer

產生 suitable PLT (Persistent Lookup Table)

檔名 <prefix>_<otp_release>_plt

Option Type Description Default
--update-plt, -u boolean Enable updating the PLT. true
--succ-typings, -s boolean Enable success typing analysis. true
  • edoc

  • escriptize

產生 escript beam files

example from relx

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

在 test profile 運作

Config Option Type Description
--cover, -c Boolean Generate cover data
--verbose, -v Boolean Verbose output
--app Comma separated list of strings List of applications to run tests for. Equivalent to EUnit’s [{application, App}].
--suite Comma separated list of strings List of test suites to run. Equivalent to EUnit’s [{module, Suite}].
--file, -f Comma separated list of strings List of files to run (such as test/my_tests.beam), equivalent to Eunit’s [{file, File}].
  • get-deps

取 dependencies

  • help

  • new

new project from templates

  • path

列印目前 profile 的 dirs

Option Type Description
--app Comma separated list of strings Comma separated list of applications to return paths for.
--base none Return the base path of the current profile.
--bin none Return the bin path of the current profile.
--ebin none Return all ebin paths of the current profile’s applications.
--lib none Return the lib path of the current profile.
--priv none Return the priv path of the current profile.
--separator, -s string In case of multiple return paths, the separator character to use to join them.
--src none Return the src path of the current profile’s applications.
--rel none Return the rel path of the current profile.
  • release

build release of project

  • relup

產生 relup

  • report

產生 bug report

  • shell

啟動包含 app, deps 的 shell

Option Type Description
--config string Allows to load a config file, if any. Defaults to the sys_config entry defined for relx if present.
--name, --sname atom Starts the node in network mode. Equivalent to erl’s -name and -sname options.
--setcookie string Sets the cookie for a distributed node. Equivalent to erl’s -setcookie option
--script string path to an escript to be evaluated before applications are started
--apps string Comma-separated list of application names to be booted. Defaults to the apps in the relx release if present.
--start-clean When specified, no apps are booted by the shell; useful to override release or shell tuple configurations in rebar.config
--relname, -r atom If multiple releases are present, specify which one to pick
--relvsn, -v string If multiple releases are present, specify which version to use
--env-file string Path to file of os environment variables to setup before expanding vars in config files
--user_drv_args string Arguments passed to user_drv start function for creating custom shells

可呼叫 r3:compile() r3:upgrade() 自動編譯, 更新 reload new modules

  • tar

產生 release 的 tar archive

  • tree

tree of dependencies

Option Type Description
-v, --verbose none Print repo and branch/tag/ref for git and hg deps
  • lock

將 unbuilt dependencies 新增到 rebar.lock

  • unlock

  • update

更新 package index

  • upgrade

更新 dependenies libraries

  • version

  • xref

cross reference analysis


release 就是 a set of applications for booting Erlang VM and start project

.erl 檔案描述,會產生 .script.boot

boot file 是 script 的 binary form,給 Erlang Run-Time System (ERTS) 使用

target system 是可在另一台機器啟動的 Erlang system,通常會包裝 ERTS 進去

  • relx

在 rebar.config 增加 relx 段落

{relx, [{release, {<release name>, "0.0.1"},
        {release, {<other release name>, "0.1.0"},

        {dev_mode, true},
        {include_erts, false},

        {extended_start_script, true}]}.

執行 rebar3 release 就會產生 release package 到 _build/<profile>/rel/<release name>/bin/<release name>

可指定多個 release name

可對 release 設定不同 options

{relx, [{release, {<release name>, "0.0.1"},
         [{dev_mode, false},
          {include_erts, true}]},
        {release, {<release name>, "0.1.0"},
         [{dev_mode, true}]}

build release

rebar3 release -n <release_name>
  • Build Configuration

包含 source code

{include_src, false}

排除 application

{exclude_apps, [app1, app2]}

排除 module

{exclude_modules, [
    {app1, [app1_mod1, app1_mod2]},
    {app2, [app2_mod1, app2_mod2]}


{relx, [...
        {mode, <mode>},
Mode Expanded Options
dev [{dev_mode, true}, {include_src, true}, {debug_info, keep}, {include_erts, false}]
prod [{include_src, false}, {debug_info, strip}, {include_erts, true}, {dev_mode, false}]
minimal [{include_src, false}, {debug_info, strip}, {include_erts, false}, {dev_mode, false}]

minimal 沒有 erlang runtime,其他跟 prod 一樣

可覆寫 option

  {mode, prod},
  {debug_info, keep}

Verification Checks

relx 預設會檢查module 使用的 external functions,因此會出現 warning

這可協助避免沒有在 .app.src 宣告 applications


{check_for_undefined_functions, false}

如果 source code 遺失,會產生 warning

{src_tests, true}

Runtime Configuration

relx 會提供預設的 vm.args,裡面有 node name 及 cookie

## Name of the node
-name {{release_name}}@

## Cookie for distributed Erlang
-setcookie {{release_name}}

如要使用自訂的 vm.args 或 vm.args.src

{vm_args, "config/vm_prod.args"}

{vm_args_src, "config/vm_prod.args.src"}

Application Configuration

config/sys.config.src or config/sys.config

  {<app_name>, [{<key>, <val>}, ...]}


{sys_config, "config/sys_prod.config"}

{sys_config_src, "config/sys_prod.config.src"}

Environment Variable Replacement

OTP-21+ & rebar3 3.6+

可設定 sys_config_src vm_args_src 設定檔名

設定裡面可用 ${VARIABLE} 取得環境變數

rebar3 v3.14.0 以後,會自動 include config/sys.config.srcconfig/vm.args.src

%% sys.config.src
  {appname, [{port, ${PORT}}]}
# vm.args.src
-name ${NODE_NAME}
%% rebar.config
{relx, [{release, {<release name>, "0.0.1"},

        {mode, dev}]}.

OTP-21 and Rebar3 3.6 以前


# vm.args
-name ${NODE_NAME}
%% sys.config
 {appname, [{port, "${PORT}"}]}

可透過環境變數啟動不同的 node name



for i in `seq 1 10`;
    NODE_NAME=node_$i PORT=808$i _build/default/rel/<release>/bin/<release> foreground &
    sleep 1

Overlays: Build-Time Configuration


{relx, [
    {overlay_vars, "vars.config"},
    {overlay, [{mkdir, "log/sasl"},
               {template, "priv/app.config", "etc/app.config"},
               {copy, "Procfile", "Procfile"}]}

template 類似 copy,但有支援變數擴展


Name Description
log The current log level in the format of (<logname>:<loglevel>)
output_dir The current output directory for the built release
target_dir The same as output_dir; exists for backwards compatibility
overridden The current list of overridden apps (a list of app names)
goals The list of user-specified goals in the system
lib_dirs The list of library directories, both user-specified and derived
config_file The list of config file used in the system
providers The list of provider names used for this run of relx
sys_config The location of the sys.config file
root_dir The root dir of the current project
default_release_name The current default release name for the relx run
default_release_version The current default release version for the relx run
default_release The current default release for the relx run
release_erts_version The version of the Erlang Run-Time System in use
erts_vsn The same as release_erts_version (for backwards compatibility)
release_name The currently executing release
release_version The currently executing version
rel_vsn Same as release_version. Exists for backwards compatibility
release_applications A list of applications included in the release
%% base.config
{data_dir, "/data/yolo_app"}.
{version, "1.0.0"}.
{run_user, "root"}.

%% dev.config
%% Include the base config
%% The build we have
{build, "dev"}.

%% prod.config
%% Include the base config
%% The build we have
{build, "prod"}.

Deployable Tarball


rebar3 as prod tar

會產生 myrel-0.1.0.tar.gz


$ mkdir myrel
$ mv myrel-0.1.0.tar.gz myrel/
$ cd myrel
$ tar -zxvf myrel-0.1.0.tar.gz
$ bin/myrel console

Without ERTS

{profiles, [{prod, [{relx, [{mode, minimal},
                            {system_libs, false}]}]}]}.

%% 或自行設定 include_erts
{profiles, [{prod, [{relx, [{include_erts, false},
                            {system_libs, false}]}]}]}

tar.gz 裡面就不會包含 kernel 與 stdlib

With ERTS Built for Another System

{include_erts, "/path/to/erlang"},
{system_libs, "/path/to/erlang"},

Extended Start Script

Command Description
foreground Start release with output to stdout
remote Connect remote shell to running node
console Start the release with an interactive shell
console_clean Start an interactive shell without the release’s applications
rpc [Mod [Fun [Args]]]] Run apply(Mod, Fun, Args) on running node
eval [Exprs] Run expressions on running node
status Verify node is running and then run status hook scripts
restart Restart the applications but not the VM
reboot Reboot the entire VM
stop Stop the running node
pid Print the PID of the OS process
ping Print pong if the node is alive
daemon Start release in the background with run_erl (named pipes)
daemon_attach Connect to node started as daemon with to_erl (named pipes)

Release Handling: Install, Upgrade

Command Description
unpack [Version] Unpack a release tarball
install [Version] Install a release
uninstall [Version] Uninstall a release
upgrade [Version] Upgrade the running release to a new version
downgrade [Version] Downgrade the running release to a new version
versions Print versions of the release available
  1. Installing

    bin/myrel install 0.0.1
  2. Listing

    bin/myrel versions
  3. Upgrading

    bin/myrel upgrade 0.0.2
  4. Downgrading

    bin/myrel downgrade 0.0.1


可在 start, stop, install_upgrade 的 pre, post 擴充 hooks


  1. pid 可將 BEAM pid 寫入某設定位置 預設為 /var/run/<rel_name>.pid
  2. wait_for_vm_start 等待 vm 啟動 (可被 ping)
  3. wait_for_process 等待某個 configurable name 在 process registry 中出現
{extended_start_script_hooks, [
  {pre_start, [{custom, "hooks/pre_start"}]},
  {post_start, [
    {pid, "/tmp/foo.pid"},
    {wait_for_process, some_process},
    {custom, "hooks/post_start"}
  {pre_stop, [
    {custom, "hooks/pre_stop"}]},
    {post_stop, [{custom, "hooks/post_stop"}]},
  {post_stop, [{custom, "hooks/post_stop"}]}


可管理 releases: foreground, stop, restart

擴充指令,增加 status,實際上呼叫 extensions/status shell script

%% start script extensions
{extended_start_script_extensions, [
   {status, "extensions/status"}

%% 因為是相對路徑,可能需要複製
{copy, "scripts/extensions/status", "bin/extensions/status"},

example of status


case $1 in
        echo "bin/gameserver status"

# get the status tuple from gameserver
Status=$(relx_nodetool eval "pool_debug:status(json).")

# now print it out
code="Json = binary_to_list($Status),
      io:format(\"~p~n\", [Json]),
echo $(erl -boot no_dot_erlang -sasl errlog_type error -noshell -eval "$code")


rebar3 docs

eeeggghit rebar3


Automatic release upgrades in Erlang