rebar3
Commands
後面接 profile name，就是以該 profile 運作
在確認所有 dependencies 都存在時，可編譯所有 dependencies, 專案的 .app.src 及 .erl
| Option |
Type |
Description |
-d/--deps_only |
none |
Only compile dependencies |
移除 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) |
執行 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 |
由 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
列出 dependencies，以及是否有 locked
依序執行 tasks
rebar3 do a,b,c
產生 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 |
產生 escript beam files
example from relx
{escript_emu_args, "%%! +sbtu +A0 -noinput\n"}.
{escript_incl_apps, [getopt, erlware_commons, bbmustache, providers, relx]}.
在 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}]. |
取 dependencies
new project from templates
列印目前 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. |
build release of project
產生 relup
產生 bug report
啟動包含 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
產生 release 的 tar archive
tree of dependencies
| Option |
Type |
Description |
-v, --verbose |
none |
Print repo and branch/tag/ref for git and hg deps |
將 unbuilt dependencies 新增到 rebar.lock
更新 package index
更新 dependenies libraries
cross reference analysis
Releases
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 進去
在 rebar.config 增加 relx 段落
{relx, [{release, {<release name>, "0.0.1"},
[<app>]},
{release, {<other release name>, "0.1.0"},
[<app>]},
{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"},
[<app>],
[{dev_mode, false},
{include_erts, true}]},
{release, {<release name>, "0.1.0"},
[<app>],
[{dev_mode, true}]}
]}.
build release
rebar3 release -n <release_name>
包含 source code
{include_src, false}
排除 application
{exclude_apps, [app1, app2]}
排除 module
{exclude_modules, [
{app1, [app1_mod1, app1_mod2]},
{app2, [app2_mod1, app2_mod2]}
]}.
Modes
{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}}@127.0.0.1
## 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.src 與 config/vm.args.src
%% sys.config.src
[
{appname, [{port, ${PORT}}]}
].
# vm.args.src
-name ${NODE_NAME}
%% rebar.config
{relx, [{release, {<release name>, "0.0.1"},
[<app>]},
{mode, dev}]}.
OTP-21 and Rebar3 3.6 以前
要設定 RELX_REPLACE_OS_VARS=true
# vm.args
-name ${NODE_NAME}
%% sys.config
[
{appname, [{port, "${PORT}"}]}
].
可透過環境變數啟動不同的 node name
#!/bin/bash
export RELX_REPLACE_OS_VARS=true
for i in `seq 1 10`;
do
NODE_NAME=node_$i PORT=808$i _build/default/rel/<release>/bin/<release> foreground &
sleep 1
done
Overlays: Build-Time Configuration
example:
{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
"./base.config".
%% The build we have
{build, "dev"}.
%% prod.config
%% Include the base config
"./base.config".
%% The build we have
{build, "prod"}.
Deployable Tarball
With ERTS
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 |
Installing
bin/myrel install 0.0.1
Listing
bin/myrel versions
Upgrading
bin/myrel upgrade 0.0.2
Downgrading
bin/myrel downgrade 0.0.1
Hooks
可在 start, stop, install_upgrade 的 pre, post 擴充 hooks
功能
- pid 可將 BEAM pid 寫入某設定位置 預設為
/var/run/<rel_name>.pid
- wait_for_vm_start 等待 vm 啟動 (可被 ping)
- 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"}]}
]}.
Extensions
可管理 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
#!/bin/bash
case $1 in
help)
echo "bin/gameserver status"
;;
*)
;;
esac
# 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]),
halt()."
echo $(erl -boot no_dot_erlang -sasl errlog_type error -noshell -eval "$code")
References
rebar3 docs
eeeggghit rebar3
Erlang：Rebar3的简单使用
Automatic release upgrades in Erlang
relx
