systools - A Set of Release Handling Tools
Please see following description for synopsis
systools(3) Erlang Module Definition systools(3)
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(4)
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 direc-
tory. 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 appli-
cation versions are fetched from the relevant application
upgrade files App.appup, sorted in the same order as when gener-
ating a boot script, see make_script/1,2. High-level instruc-
tions 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(4). 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 direc-
tories, 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_emula-
tor_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 func-
tion 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,Mod-
ule,Error}. Warnings and errors can be converted to strings by
calling Module:format_warning(Warnings) or Module:for-
mat_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,Mod-
ule,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(4).
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(4).
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, depen-
dencies to applications that are not included in the
release. (Key applications in the .app file).
* There are to be no circular dependencies among the applica-
tions.
* 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 direc-
tory.
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 direc-
tory 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 applica-
tion 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 vari-
ables 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 applica-
tion 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 appli-
cations, 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 func-
tion returns ok or error. If option {ok,Module,Warnings} or
{error,Module,Error}. silent is specified, the function instead
returns Warnings and errors can be converted to strings by call-
ing Module:format_warning(Warnings) or Module:for-
mat_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(4)).
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 speci-
fied, 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 applica-
tion. 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. Exam-
ple: "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 direc-
tory 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 direc-
tory as Name.rel, in the current working directory, and in any
directories specified using option path. In the case of sys.con-
fig it is not included if sys.config.src is found.
If the release package is to contain a new Erlang runtime sys-
tem, the erts-ErtsVsn/bin directory of the specified runtime
system {erts,Dir} is copied to erts-ErtsVsn/bin. Some erts exe-
cutables 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(4), appup(4), erl(1), rel(4), release_handler(3), relup(4),
script(4)
Ericsson AB sasl 4.1.1 systools(3)