Provided by: erlang-manpages_25.3.2.8+dfsg-1ubuntu4_all 
NAME
systools - A Set of Release Handling Tools
DESCRIPTION
This module contains functions to generate boot scripts (.boot, .script), a release upgrade file (relup),
and release packages.
EXPORTS
make_relup(Name, UpFrom, DownTo) -> Result
make_relup(Name, UpFrom, DownTo, [Opt]) -> Result
Types:
Name = string()
UpFrom = DownTo = [Name | {Name,Descr}]
Descr = term()
Opt = {path,[Dir]} | restart_emulator | silent | noexec | {outdir,Dir} | warnings_as_errors
Dir = string()
Result = ok | error | {ok,Relup,Module,Warnings} | {error,Module,Error}
Relup, see relup(5)
Module = atom()
Warnings = Error = term()
Generates a release upgrade file relup containing instructions for upgrading from or downgrading
to one or more previous releases. The instructions are used by release_handler when installing a
new version of a release in runtime.
By default, relup file is located in the current working directory. If option {outdir,Dir} is
specified, the relup file is located in Dir instead.
The release resource file Name.rel is compared with all release resource files Name2.rel,
specified in UpFrom and DownTo. For each such pair, the following is deducted:
* Which applications to be deleted, that is, applications listed in Name.rel but not in
Name2.rel
* Which applications to be added, that is, applications listed in Name2.rel but not in Name.rel
* Which applications to be upgraded/downgraded, that is, applications listed in both Name.rel
and Name2.rel but with different versions
* If the emulator needs to be restarted after upgrading or downgrading, that is, if the ERTS
version differs between Name.rel and Name2.rel
Instructions for this are added to the relup file in the above order. Instructions for upgrading
or downgrading between application versions are fetched from the relevant application upgrade
files App.appup, sorted in the same order as when generating a boot script, see make_script/1,2.
High-level instructions are translated into low-level instructions and the result is printed to
the relup file.
The optional Descr parameter is included "as is" in the relup file, see relup(5). Defaults to the
empty list.
All the files are searched for in the code path. It is assumed that the .app and .appup files for
an application are located in the same directory.
If option {path,[Dir]} is specified, this path is appended to the current path. Wildcard * is
expanded to all matching directories, for example, lib/*/ebin.
If option restart_emulator is specified, a low-level instruction to restart the emulator is
appended to the relup file. This ensures that a complete reboot of the system is done when the
system is upgraded or downgraded.
If an upgrade includes a change from an emulator earlier than OTP R15 to OTP R15 or later, the
warning pre_R15_emulator_upgrade is issued. For more information about this, see Design Principles
in System Documentation.
By default, errors and warnings are printed to tty and the function returns ok or error. If option
silent is specified, the function instead either returns {ok,Relup,Module,Warnings}, where Relup
is the release upgrade file, or {error,Module,Error}. Warnings and errors can be converted to
strings by calling Module:format_warning(Warnings) or Module:format_error(Error).
If option noexec is specified, the function returns the same values as for silent but no relup
file is created.
If option warnings_as_errors is specified, warnings are treated as errors.
make_script(Name) -> Result
make_script(Name, [Opt]) -> Result
Types:
Name = string()
Opt = src_tests | {path,[Dir]} | local | {variables,[Var]} | exref | {exref,[App]}] | silent |
{outdir,Dir} | no_dot_erlang | no_warn_sasl | warnings_as_errors | {script_name, Name}
Dir = string()
Var = {VarName,Prefix}
VarName = Prefix = string()
App = atom()
Result = ok | error | {ok,Module,Warnings} | {error,Module,Error}
Module = atom()
Warnings = Error = term()
Generates a boot script Name.script and its binary version, the boot file Name.boot, unless the
{script_name, ScriptName} option is given, in which case the names are ScriptName.script and
ScriptName.boot The boot file specifies which code to be loaded and which applications to be
started when the Erlang runtime system is started. See script(5).
The release resource file Name.rel is read to determine which applications are included in the
release. Then the relevant application resource files App.app are read to determine which modules
to be loaded, and if and how the applications are to be started. (Keys modules and mod, see
app(5).
By default, the boot script and boot file are located in the same directory as Name.rel. That is,
in the current working directory unless Name contains a path. If option {outdir,Dir} is specified,
they are located in Dir instead.
The correctness of each application is checked as follows:
* The version of an application specified in the .rel file is to be the same as the version
specified in the .app file.
* There are to be no undefined applications, that is, dependencies to applications that are not
included in the release. (Key applications in the .app file).
* There are to be no circular dependencies among the applications.
* There are to be no duplicated modules, that is, modules with the same name but belonging to
different applications.
* If option src_tests is specified, a warning is issued if the source code for a module is
missing or is newer than the object code.
The applications are sorted according to the dependencies between the applications. Where there
are no dependencies, the order in the .rel file is kept.
The function fails if the mandatory applications Kernel and STDLIB are not included in the .rel
file and have start type permanent (which is default).
If SASL is not included as an application in the .rel file, a warning is issued because such a
release cannot be used in an upgrade. To turn off this warning, add option no_warn_sasl.
All files are searched for in the current path. It is assumed that the .app and .beam files for an
application are located in the same directory. The .erl files are also assumed to be located in
this directory, unless it is an ebin directory in which case they can be located in the
corresponding src directory.
If option {path,[Dir]} is specified, this path is appended to the current path. A directory in the
path can be specified with a wildcard *, this is expanded to all matching directories. Example:
"lib/*/ebin".
In the generated boot script all application directories are structured as App-Vsn/ebin. They are
assumed to be located in $ROOT/lib, where $ROOT is the root directory of the installed release. If
option local is specified, the actual directories where the applications were found are used
instead. This is a useful way to test a generated boot script locally.
Option variables can be used to specify an installation directory other than $ROOT/lib for some of
the applications. If a variable {VarName,Prefix} is specified and an application is found in a
directory Prefix/Rest/App[-Vsn]/ebin, this application gets the path VarName/Rest/App-Vsn/ebin in
the boot script. If an application is found in a directory Prefix/Rest, the path is
VarName/Rest/App-Vsn/ebin. When starting Erlang, all variables VarName are given values using
command-line flag boot_var.
Example: If option {variables,[{"TEST","lib"}]} is specified and myapp.app is found in
lib/myapp/ebin, the path to this application in the boot script is "$TEST/myapp-1/ebin". If
myapp.app is found in lib/test, the path is $TEST/test/myapp-1/ebin.
The checks performed before the boot script is generated can be extended with some cross reference
checks by specifying option exref. These checks are performed with the Xref tool. All
applications, or the applications specified with {exref,[App]}, are checked by Xref and warnings
are issued for calls to undefined functions.
By default, errors and warnings are printed to tty and the function returns ok or error. If option
silent is specified, the function instead returns {ok,Module,Warnings} or {error,Module,Error}.
Warnings and errors can be converted to strings by calling Module:format_warning(Warnings) or
Module:format_error(Error).
If option warnings_as_errors is specified, warnings are treated as errors.
If option no_dot_erlang is specified, the instruction to load the .erlang file during boot is not
included.
make_tar(Name) -> Result
make_tar(Name, Opts) -> Result
Types:
Name = string()
Opts = [Opt]
Opt =
{dirs, [IncDir]} |
{path, [Dir]} |
{variables, [Var]} |
{var_tar, VarTar} |
{erts, Dir} |
erts_all | src_tests | exref |
{exref, [App]} |
silent |
{outdir, Dir} |
no_warn_sasl | warnings_as_errors |
{extra_files, ExtraFiles}
Dir = file:filename_all()
IncDir = src | include | atom()
Var = {VarName, PreFix}
VarName = PreFix = string()
VarTar = include | ownfile | omit
App = atom()
Result =
ok | error |
{ok, Module :: module(), Warnings :: term()} |
{error, Module :: module(), Error :: term()}
ExtraFiles = [{NameInArchive, file:filename_all()}]
NameInArchive = string()
Creates a release package file Name.tar.gz. This file must be uncompressed and unpacked on the
target system using release_handler before the new release can be installed.
The release resource file Name.rel is read to determine which applications are included in the
release. Then the relevant application resource files App.app are read to determine the version
and modules of each application (keys vsn and modules, see app(5)).
By default, the release package file is located in the same directory as Name.rel. That is, in the
current working directory unless Name contains a path. If option {outdir,Dir} is specified, it is
located in Dir instead.
If SASL is not included as an application in the .rel file, a warning is issued because such a
release cannot be used in an upgrade. To turn off this warning, add option no_warn_sasl.
By default, the release package contains the directories lib/App-Vsn/ebin and lib/App-Vsn/priv for
each included application. If more directories are to be included, option dirs is specified, for
example, {dirs,[src,examples]}.
All these files are searched for in the current path. If option {path,[Dir]} is specified, this
path is appended to the current path. Wildcard * is expanded to all matching directories. Example:
"lib/*/ebin".
If the {extra_files, ExtraFiles} option is given then the ExtraFiles are added to the tarball
after everything else to be included has been added. The ExtraFiles list is a list of files or
directories in the same format as the add_type() tuple for erl_tar:add/3,4
Option variables can be used to specify an installation directory other than lib for some of the
applications. If variable {VarName,Prefix} is specified and an application is found in directory
Prefix/Rest/App[-Vsn]/ebin, this application is packed into a separate VarName.tar.gz file as
Rest/App-Vsn/ebin.
Example: If option {variables,[{"TEST","lib"}]} is specified and myapp.app is located in
lib/myapp-1/ebin, application myapp is included in TEST.tar.gz:
% tar tf TEST.tar
myapp-1/ebin/myapp.app
...
Option {var_tar,VarTar} can be used to specify if and where a separate package is to be stored. In
this option VarTar is one of the following:
include:
Each separate (variable) package is included in the main ReleaseName.tar.gz file. This is the
default.
ownfile:
Each separate (variable) package is generated as a separate file in the same directory as the
ReleaseName.tar.gz file.
omit:
No separate (variable) packages are generated. Applications that are found underneath a
variable directory are ignored.
A directory releases is also included in the release package, containing Name.rel and a
subdirectory RelVsn. RelVsn is the release version as specified in Name.rel.
releases/RelVsn contains the boot script Name.boot renamed to start.boot and, if found, the files
relup and sys.config or sys.config.src. These files are searched for in the same directory as
Name.rel, in the current working directory, and in any directories specified using option path. In
the case of sys.config it is not included if sys.config.src is found.
If the release package is to contain a new Erlang runtime system, the erts-ErtsVsn/bin directory
of the specified runtime system {erts,Dir} is copied to erts-ErtsVsn/bin. Some erts executables
are not copied by default, if you want to include all executables you can give the erts_all
option.
All checks with function make_script are performed before the release package is created. Options
src_tests and exref are also valid here.
The return value and the handling of errors and warnings are the same as described for
make_script.
script2boot(File) -> ok | error
Types:
File = string()
The Erlang runtime system requires that the contents of the script used to boot the system is a
binary Erlang term. This function transforms the File.script boot script to a binary term, which
is stored in the File.boot file.
A boot script generated using make_script is already transformed to the binary form.
SEE ALSO
app(5), appup(5), erl(1), rel(5), release_handler(3erl), relup(5), script(5)