systools
A Set of Release Handling Tools.
This module contains functions to generate boot scripts
(.boot
, .script
), release upgrade scripts
(relup
), and release packages.
Functions
make_relup(Name, UpFrom, DownTo) -> Result
make_relup(Name, UpFrom, DownTo, [Opt]) -> Result
Name = string()
UpFrom = DownTo = [Name | {Name,Descr}]
Descr = term()
Opt = {path,[Dir]} | restart_emulator | silent | noexec | {outdir,Dir}
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 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 inName2.rel
. -
Which applications should be added, that is applications which are listed in
Name2.rel
but not inName.rel
. -
Which applications should be upgraded/downgraded, that is applications listed in both
Name.rel
andName2.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
andName2.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(4)
. 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.
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.
make_script(Name) -> Result
make_script(Name, [Opt]) -> Result
Name = string()
Opt = no_module_tests | {path,[Dir]} | local | {variables,[Var]} | exref | {exref,[App]}] | silent | {outdir,Dir}
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(4)
.
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(4)
).
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 no duplicated modules, that is, modules with the same name but belonging to different applications.
-
A warning is issued if the source code for a module is missing or newer than the object code.
If theno_module_tests
option is specified, this check is omitted.
The applications are sorted according to the dependencies
between the applications. Where there are no dependencies,
the order in the .rel
file is kept.
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)
.
make_tar(Name) -> Result
make_tar(Name, [Opt]) -> Result
Name = string()
Opt = {dirs,[IncDir]} | {path,[Dir]} | {variables,[Var]} | {var_tar,VarTar} | {erts,Dir} | no_module_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(4)
).
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 mainReleaseName.tar.gz
file. This is the default. -
ownfile
. Each separate (variable) package is generated as separate files in the same directory as theReleaseName.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
no_module_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
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(4), appup(4), erl(1), rel(4), release_handler(3), relup(4), script(4)