View Source reltool (reltool v1.0.1)
Main API of the Reltool application
This is an interface module for the Reltool application.
Reltool is a release management tool. It analyses a given Erlang/OTP
installation and determines various dependencies between applications. The
graphical
frontend depicts the dependencies and enables interactive
customization of a target system. The backend provides a batch
interface for
generation of customized target systems.
The tool uses an installed Erlang/OTP system as input. root_dir
is the root
directory of the analysed system and it defaults to the system executing
Reltool. Applications may also be located outside root_dir
. lib_dirs
defines
library directories where additional applications may reside and it defaults to
the directories listed by the operating system environment variable ERL_LIBS
.
See the module code
for more info.
An application directory AppDir
under a library directory is recognized by the
existence of an AppDir/ebin
directory. If this does not exist, Reltool will
not consider AppDir
at all when looking for applications.
It is recommended that application directories are named as the application,
possibly followed by a dash and the version number. For example myapp
or
myapp-1.1
.
Finally single modules and entire applications may be read from Escripts.
Some configuration parameters control the behavior of Reltool on system (sys
)
level. Others provide control on application (app
) level and yet others are on
module (mod
) level. Module level parameters override application level
parameters and application level parameters override system level parameters.
Escript escript
level parameters override system level parameters.
The following top level options
are supported:
config
- This is the main option and it controls the configuration of Reltool. It can either be asys
tuple or a name of afile
containing a sys tuple.trap_exit
- This option controls the error handling behavior of Reltool. By default the window processes traps exit, but this behavior can altered by settingtrap_exit
tofalse
.wx_debug
- This option controls the debug level ofwx
. As its name indicates it is only useful for debugging. Seewx:debug/1
for more info.
Besides the already mentioned source parameters root_dir
and lib_dirs
, the
following system (sys
) level options are supported:
erts
- Erts specific configuration. See application level options below.escript
- Escript specific configuration. An escript has a mandatory file name and escript level options that are described below.app
- Application specific configuration. An application has a mandatory name and application level options that are described below.mod_cond
- This parameter controls the module inclusion policy. It defaults toall
which means that if an application is included (either explicitly or implicitly) all modules in that application will be included. This implies that both modules that exist in theebin
directory of the application, as well as modules that are named in theapp
file will be included. If the parameter is set toebin
, both modules in theebin
directory and derived modules are included. If the parameter is set toapp
, both modules in theapp
file and derived modules are included.derived
means that only modules that are used by other included modules are included. Themod_cond
setting on system level is used as default for all applications.incl_cond
- This parameter controls the application and escript inclusion policy. It defaults toderived
which means that the applications that do not have any explicitincl_cond
setting, will only be included if any other (explicitly or implicitly included) application uses it. The valueinclude
implies that all applications and escripts that do not have any explicitincl_cond
setting will be included.exclude
implies that all applications and escripts that do not have any explicitincl_cond
setting will be excluded.boot_rel
- A target system may have several releases but the one given asboot_rel
will be used as default when the system is booting up.rel
- Release specific configuration. Each release maps to arel
,script
andboot
file. See the modulesystools
for more info about the details. Each release has a name, a version and a set of applications with a few release specific parameters such as type and included applications.relocatable
- This parameter controls whether theerl
executable in the target system should automatically determine where it is installed or if it should use a hardcoded path to the installation. In the latter case the target system must be installed withreltool:install/2
before it can be used. If the system is relocatable, the file tree containing the target system can be moved to another location without re-installation. The default istrue
.profile
- The creation of the specification for a target system is performed in two steps. In the first step a complete specification is generated. It will likely contain much more files than you are interested in in your customized target system. In the second step the specification will be filtered according to your filters. There you have the ability to specify filters per application as well as system wide filters. You can also select aprofile
for your system. Depending on theprofile
, different default filters will be used. There are three different profiles to choose from:development
,embedded
andstandalone
.development
is default. The parameters that are affected by theprofile
are:incl_sys_filters
,excl_sys_filters
,incl_app_filters
andexcl_app_filters
.app_file
- This parameter controls the default handling of theapp
files when a target system is generated. It defaults tokeep
which means thatapp
files are copied to the target system and their contents are kept as they are.strip
means that a newapp
file is generated from the contents of the originalapp
file where the non included modules are removed from the file.all
does also imply that a newapp
file is generated from the contents of the originalapp
file, with the difference that all included modules are added to the file. If the application does not have anyapp
file a file will be created forall
but not forkeep
andstrip
.debug_info
- Thedebug_info
parameter controls what debug information in the beam file should be kept or stripped.keep
keeps all debug info,strip
strips all debug info, and a list of chunkids keeps only those chunks.excl_lib
Warning
This option is experimental.
If the
excl_lib
option is set tootp_root
then reltool will not copy anything from the Erlang/OTP installation ($OTPROOT) into the target structure. The goal is to create a "slim" release which can be used together with an existing Erlang/OTP installation. The target structure will therefore only contain alib
directory with the applications that were found outside of $OTPROOT (typically your own applications), and areleases
directory with the generated.rel,
.script
and.boot
files.When starting this release, three things must be specified:
Which
releases
directory to use - Tell the release handler to use thereleases
directory in our target structure instead of$OTPROOT/releases
. This is done by setting the SASL environment variablereleases_dir
, either from the command line (-sasl releases_dir <target-dir>/releases
) or insys.config
.Which boot file to use - The default boot file is
$OTPROOT/bin/start
, but in this case we need to specify a boot file from our target structure, typically<target-dir>/releases/<vsn>/<RelName>
. This is done with the-boot
command line option toerl
The location of our applications - The generated .script (and .boot) file uses the environment variable
$RELTOOL_EXT_LIB
as prefix for the paths to all applications. The-boot_var
option toerl
can be used for specifying the value of this variable, typically-boot_var RELTOOL_EXT_LIB <target-dir>/lib
.
Example:
erl -sasl releases_dir \"mytarget/releases\" -boot mytarget/releases/1.0/myrel\ -boot_var RELTOOL_EXT_LIB mytarget/lib
incl_sys_filters
- This parameter normally contains a list of regular expressions that controls which files in the system should be included. Each file in the target system must match at least one of the listed regular expressions in order to be included. Further the files may not match any filter inexcl_sys_filters
in order to be included. Which application files should be included is controlled with the parametersincl_app_filters
andexcl_app_filters
. This parameter defaults to[".*"]
.excl_sys_filters
- This parameter normally contains a list of regular expressions that controls which files in the system should not be included in the target system. In order to be included, a file must match some filter inincl_sys_filters
but not any filter inexcl_sys_filters
. This parameter defaults to[]
.incl_app_filters
- This parameter normally contains a list of regular expressions that controls which application specific files that should be included. Each file in the application must match at least one of the listed regular expressions in order to be included. Further the files may not match any filter inexcl_app_filters
in order to be included. This parameter defaults to[".*"]
.excl_app_filters
- This parameter normally contains a list of regular expressions that controls which application specific files should not be included in the target system. In order to be included, a file must match some filter inincl_app_filters
but not any filter inexcl_app_filters
. This parameter defaults to[]
.
On application (escript
) level, the following options are supported:
incl_cond
- The value of this parameter overrides the parameter with the same name on system level.
On application (app
) level, the following options are supported:
vsn
- The version of the application. In an installed system there may exist several versions of an application. Thevsn
parameter controls which version of the application will be chosen.This parameter is mutual exclusive with
lib_dir
. Ifvsn
andlib_dir
are both omitted, the latest version will be chosen.Note that in order for reltool to sort application versions and thereby be able to select the latest, it is required that the version id for the application consists of integers and dots only, for example
1
,2.0
or3.17.1
.lib_dir
- The directory to read the application from. This parameter can be used to point out a specific location to fetch the application from. This is useful for instance if the parent directory for some reason is no good as a library directory on system level.This parameter is mutual exclusive with
vsn
. Ifvsn
andlib_dir
are both omitted, the latest version will be chosen.Note that in order for reltool to sort application versions and thereby be able to select the latest, it is required that the version id for the application consists of integers and dots only, for example
1
,2.0
or3.17.1
.mod
- Module specific configuration. A module has a mandatory name and module level options that are described below.mod_cond
- The value of this parameter overrides the parameter with the same name on system level.incl_cond
- The value of this parameter overrides the parameter with the same name on system level.app_file
- The value of this parameter overrides the parameter with the same name on system level.debug_info
- The value of this parameter overrides the parameter with the same name on system level.incl_app_filters
- The value of this parameter overrides the parameter with the same name on system level.excl_app_filters
- The value of this parameter overrides the parameter with the same name on system level.
On module (mod
) level, the following options are supported:
incl_cond
- This parameter controls whether the module is included or not. By default themod_cond
parameter on application and system level will be used to control whether the module is included or not. The value ofincl_cond
overrides the module inclusion policy.include
implies that the module is included, whileexclude
implies that the module is not included.derived
implies that the module is included if it is used by any other included module.debug_info
- The value of this parameter overrides the parameter with the same name on application level.
DATA TYPES
options() = [option()]
option() = {config, config() | file()}
| {trap_exit, bool()}
| {wx_debug, term()}
config() = {sys, [sys()]}
sys() = {root_dir, root_dir()}
| {lib_dirs, [lib_dir()]}
| {profile, profile()}
| {erts, app()}
| {escript, escript_file(), [escript()]}
| {app, app_name(), [app()]}
| {mod_cond, mod_cond()}
| {incl_cond, incl_cond()}
| {boot_rel, boot_rel()}
| {rel, rel_name(), rel_vsn(), [rel_app()]}
| {rel, rel_name(), rel_vsn(), [rel_app()], [rel_opt()]}
| {relocatable, relocatable()}
| {app_file, app_file()}
| {debug_info, debug_info()}
| {incl_sys_filters, incl_sys_filters()}
| {excl_sys_filters, excl_sys_filters()}
| {incl_app_filters, incl_app_filters()}
| {excl_app_filters, excl_app_filters()}
app() = {vsn, app_vsn()}
| {lib_dir, lib_dir()}
| {mod, mod_name(), [mod()]}
| {mod_cond, mod_cond()}
| {incl_cond, incl_cond()}
| {debug_info, debug_info()}
| {app_file, app_file()}
| {excl_lib, excl_lib()}
| {incl_sys_filters, incl_sys_filters()}
| {excl_sys_filters, excl_sys_filters()}
| {incl_app_filters, incl_app_filters()}
| {excl_app_filters, excl_app_filters()}
mod() = {incl_cond, incl_cond()}
| {debug_info, debug_info()}
rel_app() = app_name()
| {app_name(), app_type()}
| {app_name(), [incl_app()]}
| {app_name(), app_type(), [incl_app()]}
rel_opt() = {load_dot_erlang, boolean()}
app_name() = atom()
app_type() = permanent | transient | temporary | load | none
app_vsn() = string()
boot_rel() = rel_name()
app_file() = keep | strip | all
debug_info() = keep | strip | [beam_lib:chunkid()]
dir() = string()
escript() = {incl_cond, incl_cond()}
escript_file() = file()
excl_app_filters() = regexps()
excl_lib() = otp_root
excl_sys_filters() = regexps()
file() = string()
incl_app() = app_name()
incl_app_filters() = regexps()
incl_cond() = include | exclude | derived
incl_sys_filters() = regexps()
lib_dir() = dir()
mod_cond() = all | app | ebin | derived | none
mod_name() = atom()
profile() = development | embedded | standalone
re_regexp() = string()
reason() = string()
regexps() = [re_regexp()]
| {add, [re_regexp()]}
| {del, [re_regexp()]}
rel_file() = term()
rel_name() = string()
rel_vsn() = string()
relocatable = boolean()
root_dir() = dir()
script_file() = term()
server() = server_pid() | options()
server_pid() = pid()
target_dir() = file()
window_pid() = pid()
base_dir() = dir()
base_file() = file()
top_dir() = file()
top_file() = file()
target_spec() = [target_spec()]
| {create_dir, base_dir(), [target_spec()]}
| {create_dir, base_dir(), top_dir(), [target_spec()]}
| {copy_file, base_file()}
| {copy_file, base_file(), top_file()}
| {write_file, base_file(), iolist()}
| {strip_beam_file, base_file()}
Summary
Functions
create_target(Server, TargetDir) -> ok | {error, Reason}
eval_target_spec(TargetSpec, RootDir, TargetDir) -> ok | {error, Reason}
get_config(Server) -> {ok, Config} | {error, Reason}
get_config(Server, InclDefaults, InclDerived) -> {ok, Config} | {error, Reason}
get_rel(Server, Relname) -> {ok, RelFile} | {error, Reason}
get_script(Server, Relname) -> {ok, ScriptFile | {error, Reason}
get_server(WindowPid) -> {ok, ServerPid} | {error, Reason}
get_status(Server) -> {ok, [Warning]} | {error, Reason}
get_target_spec(Server) -> {ok, TargetSpec} | {error, Reason}
install(RelName, TargetDir) -> ok | {error, Reason}
start() -> {ok, WindowPid} | {error, Reason}
start(Options) -> {ok, WindowPid} | {error, Reason}
start_link(Options) -> {ok, WindowPid} | {error, Reason}
start_server(Options) -> {ok, ServerPid} | {error, Reason}
stop(Pid) -> ok | {error, Reason}
Types
-type app() :: {vsn, app_vsn()} | {lib_dir, lib_dir()} | {mod, mod_name(), [mod()]} | {mod_cond, mod_cond()} | {incl_cond, incl_cond()} | {app_file, app_file()} | {debug_info, debug_info()} | {incl_app_filters, incl_app_filters()} | {excl_app_filters, excl_app_filters()}.
-type app_file() :: keep | strip | all.
-type app_name() :: atom().
-type app_type() :: permanent | transient | temporary | load | none.
-type app_vsn() :: string().
-type base_dir() :: dir().
-type base_file() :: file().
-type boot_rel() :: rel_name().
-type config() :: {sys, [sys()]}.
-type debug_info() :: keep | strip | [beam_lib:chunkid()].
-type dir() :: file:filename().
-type escript() :: {incl_cond, incl_cond()}.
-type escript_file() :: file().
-type excl_app_filters() :: regexps().
-type excl_lib() :: otp_root.
-type excl_sys_filters() :: regexps().
-type file() :: file:filename().
-type incl_app() :: app_name().
-type incl_app_filters() :: regexps().
-type incl_cond() :: include | exclude | derived.
-type incl_defaults() :: boolean().
-type incl_derived() :: boolean().
-type incl_sys_filters() :: regexps().
-type lib_dir() :: dir().
-type mod() :: {incl_cond, incl_cond()} | {debug_info, debug_info()}.
-type mod_cond() :: all | app | ebin | derived | none.
-type mod_name() :: atom().
-type options() :: [option()].
-type profile() :: development | embedded | standalone.
-type re_regexp() :: string().
-type reason() :: string().
-type rel_file() :: term().
-type rel_name() :: string().
-type rel_opt() :: {load_dot_erlang, boolean()}.
-type rel_vsn() :: string().
-type relocatable() :: boolean().
-type root_dir() :: dir().
-type script_file() :: term().
-type server() :: server_pid() | options().
-type server_pid() :: pid().
-type sys() :: {mod_cond, mod_cond()} | {incl_cond, incl_cond()} | {debug_info, debug_info()} | {app_file, app_file()} | {profile, profile()} | {excl_lib, excl_lib()} | {incl_sys_filters, incl_sys_filters()} | {excl_sys_filters, excl_sys_filters()} | {incl_app_filters, incl_app_filters()} | {excl_app_filters, excl_app_filters()} | {root_dir, root_dir()} | {lib_dirs, [lib_dir()]} | {boot_rel, boot_rel()} | {rel, rel_name(), rel_vsn(), [rel_app()]} | {rel, rel_name(), rel_vsn(), [rel_app()], [rel_opt()]} | {relocatable, relocatable()} | {erts, app()} | {escript, escript_file(), [escript()]} | {app, app_name(), [app()]}.
-type target_dir() :: dir().
-type target_spec() :: [target_spec()] | {create_dir, base_dir(), [target_spec()]} | {create_dir, base_dir(), top_dir(), [target_spec()]} | {copy_file, base_file()} | {copy_file, base_file(), top_file()} | {write_file, base_file(), binary()} | {strip_beam_file, base_file()}.
-type top_dir() :: file().
-type top_file() :: file().
-type warning() :: string().
-type window_pid() :: pid().
Functions
-spec create_target(server(), target_dir()) -> ok | {error, reason()}.
create_target(Server, TargetDir) -> ok | {error, Reason}
Create a target system. Gives the same result as
{ok,TargetSpec}=reltool:get_target_spec(Server)
and
reltool:eval_target_spec(TargetSpec,RootDir,TargetDir)
.
-spec eval_target_spec(target_spec(), root_dir(), target_dir()) -> ok | {error, reason()}.
eval_target_spec(TargetSpec, RootDir, TargetDir) -> ok | {error, Reason}
Create the actual target system from a specification generated by
reltool:get_target_spec/1
. The creation of the specification for a target
system is performed in two steps. In the first step a complete specification
will be generated. It will likely contain much more files than you are
interested in in your target system. In the second step the specification will
be filtered according to your filters. There you have the ability to specify
filters per application as well as system wide filters. You can also select a
profile
for your system. Depending on the profile
, different default filters
will be used.
The top directories bin
, releases
and lib
are treated differently from
other files. All other files are by default copied to the target system. The
releases
directory contains generated rel
, script
, and boot
files. The
lib
directory contains the applications. Which applications are included and
if they should be customized (stripped from debug info etc.) is specified with
various configuration parameters. The files in the bin
directory are copied
from the erts-vsn/bin
directory, but only those files that were originally
included in the bin
directory of the source system.
If the configuration parameter relocatable
was set to true
there is no need
to install the target system with reltool:install/2
before it can be started.
In that case the file tree containing the target system can be moved without
re-installation.
In most cases, the RootDir
parameter should be set to the same as the
root_dir
configuration parameter used in the call to
reltool:get_target_spec/1
(or code:root_dir()
if the configuration parameter
is not set). In some cases it might be useful to evaluate the same target
specification towards different root directories. This should, however, be used
with great care as it requires equivalent file structures under all roots.
get_config(Server) -> {ok, Config} | {error, Reason}
Get reltool configuration. Shorthand for
reltool:get_config(Server,false,false)
.
-spec get_config(server(), incl_defaults(), incl_derived()) -> {ok, config()} | {error, reason()}.
get_config(Server, InclDefaults, InclDerived) -> {ok, Config} | {error, Reason}
Get reltool configuration. Normally, only the explicit configuration parameters
with values that differ from their defaults are interesting. But the builtin
default values can be returned by setting InclDefaults
to true
. The derived
configuration can be returned by setting InclDerived
to true
.
get_rel(Server, Relname) -> {ok, RelFile} | {error, Reason}
Get contents of a release file. See rel(4)
for more details.
-spec get_script(server(), rel_name()) -> {ok, script_file()} | {error, reason()}.
get_script(Server, Relname) -> {ok, ScriptFile | {error, Reason}
Get contents of a boot script file. See script(4)
for more details.
-spec get_server(window_pid()) -> {ok, server_pid()} | {error, reason()}.
get_server(WindowPid) -> {ok, ServerPid} | {error, Reason}
Return the process identifier of the server process.
get_status(Server) -> {ok, [Warning]} | {error, Reason}
Get status about the configuration
-spec get_target_spec(server()) -> {ok, target_spec()} | {error, reason()}.
get_target_spec(Server) -> {ok, TargetSpec} | {error, Reason}
Return a specification of the target system. The actual target system can be
created with reltool:eval_target_spec/3
.
install(RelName, TargetDir) -> ok | {error, Reason}
Install a created target system
-spec start() -> {ok, window_pid()} | {error, reason()}.
start() -> {ok, WindowPid} | {error, Reason}
Start a main window process with default options
-spec start(options()) -> {ok, window_pid()} | {error, reason()}.
start(Options) -> {ok, WindowPid} | {error, Reason}
Start a main window process with options
-spec start_link(options()) -> {ok, window_pid()} | {error, reason()}.
start_link(Options) -> {ok, WindowPid} | {error, Reason}
Start a main window process with options. The process is linked.
-spec start_server(options()) -> {ok, server_pid()} | {error, reason()}.
start_server(Options) -> {ok, ServerPid} | {error, Reason}
Start a server process with options. The server process identity can be given as an argument to several other functions in the API.
-spec stop(server_pid() | window_pid()) -> ok | {error, reason()}.
stop(Pid) -> ok | {error, Reason}
Stop a server or window process