Provided by: erlang-manpages_25.2.3+dfsg-1_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)