Provided by: erlang-manpages_16.b.3-dfsg-1ubuntu2.2_all 
NAME
systools - A Set of Release Handling Tools.
DESCRIPTION
This module contains functions to generate boot scripts (.boot, .script), release upgrade
scripts (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 a script which describes how to
upgrade the system from a number of previous releases, and how to downgrade to a
number of previous releases. The script is used by release_handler when installing
a new version of a release in run-time.
By default, relup is placed in the current working directory. If the option
{outdir,Dir} is provided, relup is placed 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, it is deducted:
* Which applications should be deleted, that is applications which are listed in
Name.rel but not in Name2.rel.
* Which applications should be added, that is applications which are listed in
Name2.rel but not in Name.rel.
* Which applications should 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 script 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 relup.
The optional Descr parameter is included as-is in the relup script, 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 file for an application is located in the same directory.
If the option {path,[Dir]} is provided, this path is appended to the current path.
The wildcard * is expanded to all matching directories. Example: lib/*/ebin.
If the restart_emulator option is supplied, a low-level instruction to restart the
emulator is appended to the relup scripts. 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. See Design Principles for
more information about this.
By default, errors and warnings are printed to tty and the function returns ok or
error. If the option silent is provided, the function instead returns
{ok,Relup,Module,Warnings} where Relup is the release upgrade script, or it returns
{error,Module,Error}. Warnings and errors can be converted to strings by calling
Module:format_warning(Warnings) or Module:format_error(Error).
If the option noexec is provided, the function returns the same values as for
silent but no relup file is created.
If the option warnings_as_errors is provided, 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
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. The boot file specifies which code should be loaded and which
applications should be started when the Erlang runtime system is started. See
script(5).
The release resource file Name.rel is read to find out which applications are
included in the release. Then the relevant application resource files App.app are
read to find out which modules should be loaded and if and how the application
should be started. (Keys modules and mod, see app(5)).
By default, the boot script and boot file are placed in the same directory as
Name.rel. That is, in the current working directory unless Name contains a path. If
the option {outdir,Dir} is provided, they are placed in Dir instead.
The correctness of each application is checked:
* The version of an application specified in the .rel file should be the same as
the version specified in the .app file.
* There should be no undefined applications, that is, dependencies to
applications which are not included in the release. (Key applications in .app
file).
* There should be no circular dependencies among the applications.
* There should be no duplicated modules, that is, modules with the same name but
belonging to different applications.
* If the src_tests option is specified, a warning is issued if the source code
for a module is missing or 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 will fail if the mandatory applications kernel and stdlib are not
included in the .rel file and have start type permanent (default).
If sasl is not included as an application in the .rel file, a warning is emitted
because such a release can not be used in an upgrade. To turn off this warning, add
the 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 is 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 may be located in the corresponding src directory.
If the option {path,[Dir]} is provided, this path is appended to the current path.
A directory in the path can be given 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 and assumed to be located in $ROOT/lib, where $ROOT is the root directory
of the installed release. If the local option is supplied, the actual directories
where the applications were found are used instead. This is a useful way to test a
generated boot script locally.
The variables option 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 will get the path VarName/Rest/App-Vsn/ebin in the boot script. If an
application is found in a directory Prefix/Rest, the path will be VarName/Rest/App-
Vsn/ebin. When starting Erlang, all variables VarName are given values using the
boot_var command line flag.
Example: If the option {variables,[{"TEST","lib"}]} is supplied, and myapp.app is
found in lib/myapp/ebin, then the path to this application in the boot script will
be "$TEST/myapp-1/ebin". If myapp.app is found in lib/test, then the path will be
$TEST/test/myapp-1/ebin.
The checks performed before the boot script is generated can be extended with some
cross reference checks by specifying the exref option. These checks are performed
with the Xref tool. All applications, or the applications specified with
{exref,[App]}, are checked by Xref and warnings are generated for calls to
undefined functions.
By default, errors and warnings are printed to tty and the function returns ok or
error. If the option silent is provided, 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 the option warnings_as_errors is provided, warnings are treated as errors.
If the option no_dot_erlang is provided, the instruction to load the .erlang file
during boot is NOT included.
make_tar(Name) -> Result
make_tar(Name, [Opt]) -> Result
Types:
Name = string()
Opt = {dirs,[IncDir]} | {path,[Dir]} | {variables,[Var]} | {var_tar,VarTar} |
{erts,Dir} | src_tests | exref | {exref,[App]} | silent | {outdir,Dir}
Dir = string()
IncDir = src | include | atom()
Var = {VarName,PreFix}
VarName = Prefix = string()
VarTar = include | ownfile | omit
Machine = atom()
App = atom()
Result = ok | error | {ok,Module,Warnings} | {error,Module,Error}
Module = atom()
Warning = Error = term()
Creates a release package file Name.tar.gz. file. This file must be uncompressed
and unpacked on the target system using the release_handler, before the new release
can be installed.
The release resource file Name.rel is read to find out which applications are
included in the release. Then the relevant application resource files App.app are
read to find out the version and modules of each application. (Keys vsn and
modules, see app(5)).
By default, the release package file is placed in the same directory as Name.rel.
That is, in the current working directory unless Name contains a path. If the
option {outdir,Dir} is provided, it is placed in Dir instead.
By default, the release package contains the directories lib/App-Vsn/ebin and
lib/App-Vsn/priv for each included application. If more directories, the option
dirs is supplied. Example: {dirs,[src,examples]}.
All these files are searched for in the current path. If the option {path,[Dir]} is
provided, this path is appended to the current path. The wildcard * is expanded to
all matching directories. Example: "lib/*/ebin".
The variables option can be used to specify an installation directory other than
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
will be packed into a separate VarName.tar.gz file as Rest/App-Vsn/ebin.
Example: If the option {variables,[{"TEST","lib"}]} is supplied, and myapp.app is
found in lib/myapp-1/ebin, the the application myapp is included in TEST.tar.gz:
% tar tf TEST.tar
myapp-1/ebin/myapp.app
...
The {var_tar,VarTar} option can be used to specify if and where a separate package
should be stored. In this option, VarTar is:
* 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 separate files in the
same directory as the ReleaseName.tar.gz file.
* omit. No separate (variable) packages are generated and applications which are
found underneath a variable directory are ignored.
A directory called releases is also included in the release package, containing
Name.rel and a subdirectory called 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. These files are searched for in the same
directory as Name.rel, in the current working directory, and in any directories
specified using the path option.
If the release package should contain a new Erlang runtime system, the bin
directory of the specified runtime system {erts,Dir} is copied to erts-ErtsVsn/bin.
All checks performed with the make_script function are performed before the release
package is created. The src_tests and exref options are also valid here.
The return value and the handling of errors and warnings are the same as described
for make_script above.
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 File.boot.
A boot script generated using the make_script function is already transformed to
the binary form.
SEE ALSO
app(5), appup(5), erl(1), rel(5), release_handler(3erl), relup(5), script(5)