.TH systools 3erl "sasl 2.4.1" "Ericsson AB" "Erlang Module Definition"
.SH NAME
systools \- A Set of Release Handling Tools.
.SH DESCRIPTION
.LP
This module contains functions to generate boot scripts (\fI\&.boot\fR\&, \fI\&.script\fR\&), release upgrade scripts (\fIrelup\fR\&), and release packages\&.
.SH EXPORTS
.LP
.B
make_relup(Name, UpFrom, DownTo) -> Result
.br
.B
make_relup(Name, UpFrom, DownTo, [Opt]) -> Result
.br
.RS
.LP
Types:

.RS 3
Name = string()
.br
UpFrom = DownTo = [Name | {Name,Descr}]
.br
 Descr = term()
.br
Opt = {path,[Dir]} | restart_emulator | silent | noexec | {outdir,Dir} | warnings_as_errors
.br
 Dir = string()
.br
Result = ok | error | {ok,Relup,Module,Warnings} | {error,Module,Error}
.br
 Relup - see relup(5)
.br
 Module = atom()
.br
 Warnings = Error = term()
.br
.RE
.RE
.RS
.LP
Generates a release upgrade file \fIrelup\fR\& 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 \fIrelease_handler\fR\& when installing a new version of a release in run-time\&.
.LP
By default, \fIrelup\fR\& is placed in the current working directory\&. If the option \fI{outdir,Dir}\fR\& is provided, \fIrelup\fR\& is placed in \fIDir\fR\& instead\&.
.LP
The release resource file \fIName\&.rel\fR\& is compared with all release resource files \fIName2\&.rel\fR\& specified in \fIUpFrom\fR\& and \fIDownTo\fR\&\&. For each such pair, it is deducted:
.RS 2
.TP 2
*
Which applications should be deleted, that is applications which are listed in \fIName\&.rel\fR\& but not in \fIName2\&.rel\fR\&\&.
.LP
.TP 2
*
Which applications should be added, that is applications which are listed in \fIName2\&.rel\fR\& but not in \fIName\&.rel\fR\&\&.
.LP
.TP 2
*
Which applications should be upgraded/downgraded, that is applications listed in both \fIName\&.rel\fR\& and \fIName2\&.rel\fR\&, but with different versions\&.
.LP
.TP 2
*
If the emulator needs to be restarted after upgrading or downgrading, that is if the ERTS version differs between \fIName\&.rel\fR\& and \fIName2\&.rel\fR\&\&.
.LP
.RE

.LP
Instructions for this are added to the \fIrelup\fR\& script in the above order\&. Instructions for upgrading or downgrading between application versions are fetched from the relevant application upgrade files \fIApp\&.appup\fR\&, sorted in the same order as when generating a boot script, see \fImake_script/1,2\fR\&\&. High-level instructions are translated into low-level instructions and the result is printed to \fIrelup\fR\&\&.
.LP
The optional \fIDescr\fR\& parameter is included as-is in the \fIrelup\fR\& script, see \fIrelup(5)\fR\&\&. Defaults to the empty list\&.
.LP
All the files are searched for in the code path\&. It is assumed that the \fI\&.app\fR\& and \fI\&.appup\fR\& file for an application is located in the same directory\&.
.LP
If the option \fI{path,[Dir]}\fR\& is provided, this path is appended to the current path\&. The wildcard \fI*\fR\& is expanded to all matching directories\&. Example: \fIlib/*/ebin\fR\&\&.
.LP
If the \fIrestart_emulator\fR\& 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\&.
.LP
If an upgrade includes a change from an emulator earlier than OTP R15 to OTP R15 or later, the warning \fIpre_R15_emulator_upgrade\fR\& is issued\&. See \fBDesign Principles\fR\& for more information about this\&.
.LP
By default, errors and warnings are printed to tty and the function returns \fIok\fR\& or \fIerror\fR\&\&. If the option \fIsilent\fR\& is provided, the function instead returns \fI{ok,Relup,Module,Warnings}\fR\& where \fIRelup\fR\& is the release upgrade script, or it returns \fI{error,Module,Error}\fR\&\&. Warnings and errors can be converted to strings by calling \fIModule:format_warning(Warnings)\fR\& or \fIModule:format_error(Error)\fR\&\&.
.LP
If the option \fInoexec\fR\& is provided, the function returns the same values as for \fIsilent\fR\& but no \fIrelup\fR\& file is created\&.
.LP
If the option \fIwarnings_as_errors\fR\& is provided, warnings are treated as errors\&.
.RE

.LP
.B
make_script(Name) -> Result
.br
.B
make_script(Name, [Opt]) -> Result
.br
.RS
.LP
Types:

.RS 3
Name = string()
.br
Opt = src_tests | {path,[Dir]} | local | {variables,[Var]} | exref | {exref,[App]}] | silent | {outdir,Dir} | no_dot_erlang | no_warn_sasl | warnings_as_errors
.br
 Dir = string()
.br
 Var = {VarName,Prefix}
.br
 VarName = Prefix = string()
.br
 App = atom()
.br
Result = ok | error | {ok,Module,Warnings} | {error,Module,Error}
.br
 Module = atom()
.br
 Warnings = Error = term()
.br
.RE
.RE
.RS
.LP
Generates a boot script \fIName\&.script\fR\& and its binary version, the boot file \fIName\&.boot\fR\&\&. The boot file specifies which code should be loaded and which applications should be started when the Erlang runtime system is started\&. See \fIscript(5)\fR\&\&.
.LP
The release resource file \fIName\&.rel\fR\& is read to find out which applications are included in the release\&. Then the relevant application resource files \fIApp\&.app\fR\& are read to find out which modules should be loaded and if and how the application should be started\&. (Keys \fImodules\fR\& and \fImod\fR\&, see \fIapp(5)\fR\&)\&.
.LP
By default, the boot script and boot file are placed in the same directory as \fIName\&.rel\fR\&\&. That is, in the current working directory unless \fIName\fR\& contains a path\&. If the option \fI{outdir,Dir}\fR\& is provided, they are placed in \fIDir\fR\& instead\&.
.LP
The correctness of each application is checked:
.RS 2
.TP 2
*
The version of an application specified in the \fI\&.rel\fR\& file should be the same as the version specified in the \fI\&.app\fR\& file\&.
.LP
.TP 2
*
There should be no undefined applications, that is, dependencies to applications which are not included in the release\&. (Key \fIapplications\fR\& in \fI\&.app\fR\& file)\&.
.LP
.TP 2
*
There should be no circular dependencies among the applications\&.
.LP
.TP 2
*
There should be no duplicated modules, that is, modules with the same name but belonging to different applications\&.
.LP
.TP 2
*
If the \fIsrc_tests\fR\& option is specified, a warning is issued if the source code for a module is missing or newer than the object code\&.
.LP
.RE

.LP
The applications are sorted according to the dependencies between the applications\&. Where there are no dependencies, the order in the \fI\&.rel\fR\& file is kept\&.
.LP
The function will fail if the mandatory applications \fIkernel\fR\& and \fIstdlib\fR\& are not included in the \fI\&.rel\fR\& file and have start type \fIpermanent\fR\& (default)\&.
.LP
If \fIsasl\fR\& is not included as an application in the \fI\&.rel\fR\& file, a warning is emitted because such a release can not be used in an upgrade\&. To turn off this warning, add the option \fIno_warn_sasl\fR\&\&.
.LP
All files are searched for in the current path\&. It is assumed that the \fI\&.app\fR\& and \fI\&.beam\fR\& files for an application is located in the same directory\&. The \fI\&.erl\fR\& files are also assumed to be located in this directory, unless it is an \fIebin\fR\& directory in which case they may be located in the corresponding \fIsrc\fR\& directory\&.
.LP
If the option \fI{path,[Dir]}\fR\& is provided, this path is appended to the current path\&. A directory in the path can be given with a wildcard \fI*\fR\&, this is expanded to all matching directories\&. Example: \fI"lib/*/ebin"\fR\&\&.
.LP
In the generated boot script all application directories are structured as \fIApp-Vsn/ebin\fR\& and assumed to be located in \fI$ROOT/lib\fR\&, where \fI$ROOT\fR\& is the root directory of the installed release\&. If the \fIlocal\fR\& 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\&.
.LP
The \fIvariables\fR\& option can be used to specify an installation directory other than \fI$ROOT/lib\fR\& for some of the applications\&. If a variable \fI{VarName,Prefix}\fR\& is specified and an application is found in a directory \fIPrefix/Rest/App[-Vsn]/ebin\fR\&, this application will get the path \fIVarName/Rest/App-Vsn/ebin\fR\& in the boot script\&. If an application is found in a directory \fIPrefix/Rest\fR\&, the path will be \fIVarName/Rest/App-Vsn/ebin\fR\&\&. When starting Erlang, all variables \fIVarName\fR\& are given values using the \fIboot_var\fR\& command line flag\&.
.LP
Example: If the option \fI{variables,[{"TEST","lib"}]}\fR\& is supplied, and \fImyapp\&.app\fR\& is found in \fIlib/myapp/ebin\fR\&, then the path to this application in the boot script will be \fI"$TEST/myapp-1/ebin"\fR\&\&. If \fImyapp\&.app\fR\& is found in \fIlib/test\fR\&, then the path will be \fI$TEST/test/myapp-1/ebin\fR\&\&.
.LP
The checks performed before the boot script is generated can be extended with some cross reference checks by specifying the \fIexref\fR\& option\&. These checks are performed with the Xref tool\&. All applications, or the applications specified with \fI{exref,[App]}\fR\&, are checked by Xref and warnings are generated for calls to undefined functions\&.
.LP
By default, errors and warnings are printed to tty and the function returns \fIok\fR\& or \fIerror\fR\&\&. If the option \fIsilent\fR\& is provided, the function instead returns \fI{ok,Module,Warnings}\fR\& or \fI{error,Module,Error}\fR\&\&. Warnings and errors can be converted to strings by calling \fIModule:format_warning(Warnings)\fR\& or \fIModule:format_error(Error)\fR\&\&.
.LP
If the option \fIwarnings_as_errors\fR\& is provided, warnings are treated as errors\&.
.LP
If the option \fIno_dot_erlang\fR\& is provided, the instruction to load the \fI\&.erlang\fR\& file during boot is \fINOT\fR\& included\&.
.RE

.LP
.B
make_tar(Name) -> Result
.br
.B
make_tar(Name, [Opt]) -> Result
.br
.RS
.LP
Types:

.RS 3
Name = string()
.br
Opt = {dirs,[IncDir]} | {path,[Dir]} | {variables,[Var]} | {var_tar,VarTar} | {erts,Dir} | src_tests | exref | {exref,[App]} | silent | {outdir,Dir}
.br
 Dir = string()
.br
 IncDir = src | include | atom()
.br
 Var = {VarName,PreFix}
.br
 VarName = Prefix = string()
.br
 VarTar = include | ownfile | omit
.br
 Machine = atom()
.br
 App = atom()
.br
Result = ok | error | {ok,Module,Warnings} | {error,Module,Error}
.br
 Module = atom()
.br
 Warning = Error = term()
.br
.RE
.RE
.RS
.LP
Creates a release package file \fIName\&.tar\&.gz\fR\&\&. file\&. This file must be uncompressed and unpacked on the target system using the \fIrelease_handler\fR\&, before the new release can be installed\&.
.LP
The release resource file \fIName\&.rel\fR\& is read to find out which applications are included in the release\&. Then the relevant application resource files \fIApp\&.app\fR\& are read to find out the version and modules of each application\&. (Keys \fIvsn\fR\& and \fImodules\fR\&, see \fIapp(5)\fR\&)\&.
.LP
By default, the release package file is placed in the same directory as \fIName\&.rel\fR\&\&. That is, in the current working directory unless \fIName\fR\& contains a path\&. If the option \fI{outdir,Dir}\fR\& is provided, it is placed in \fIDir\fR\& instead\&.
.LP
By default, the release package contains the directories \fIlib/App-Vsn/ebin\fR\& and \fIlib/App-Vsn/priv\fR\& for each included application\&. If more directories, the option \fIdirs\fR\& is supplied\&. Example: \fI{dirs,[src,examples]}\fR\&\&.
.LP
All these files are searched for in the current path\&. If the option \fI{path,[Dir]}\fR\& is provided, this path is appended to the current path\&. The wildcard \fI*\fR\& is expanded to all matching directories\&. Example: \fI"lib/*/ebin"\fR\&\&.
.LP
The \fIvariables\fR\& option can be used to specify an installation directory other than \fIlib\fR\& for some of the applications\&. If a variable \fI{VarName,Prefix}\fR\& is specified and an application is found in a directory \fIPrefix/Rest/App[-Vsn]/ebin\fR\&, this application will be packed into a separate \fIVarName\&.tar\&.gz\fR\& file as \fIRest/App-Vsn/ebin\fR\&\&.
.LP
Example: If the option \fI{variables,[{"TEST","lib"}]}\fR\& is supplied, and \fImyapp\&.app\fR\& is found in \fIlib/myapp-1/ebin\fR\&, the the application \fImyapp\fR\& is included in \fITEST\&.tar\&.gz\fR\&:
.LP
.nf

% tar tf TEST\&.tar
myapp-1/ebin/myapp.app
\&...
        
.fi
.LP
The \fI{var_tar,VarTar}\fR\& option can be used to specify if and where a separate package should be stored\&. In this option, \fIVarTar\fR\& is:
.RS 2
.TP 2
*
\fIinclude\fR\&\&. Each separate (variable) package is included in the main \fIReleaseName\&.tar\&.gz\fR\& file\&. This is the default\&.
.LP
.TP 2
*
\fIownfile\fR\&\&. Each separate (variable) package is generated as separate files in the same directory as the \fIReleaseName\&.tar\&.gz\fR\& file\&.
.LP
.TP 2
*
\fIomit\fR\&\&. No separate (variable) packages are generated and applications which are found underneath a variable directory are ignored\&.
.LP
.RE

.LP
A directory called \fIreleases\fR\& is also included in the release package, containing \fIName\&.rel\fR\& and a subdirectory called \fIRelVsn\fR\&\&. \fIRelVsn\fR\& is the release version as specified in \fIName\&.rel\fR\&\&.
.LP
\fIreleases/RelVsn\fR\& contains the boot script \fIName\&.boot\fR\& renamed to \fIstart\&.boot\fR\& and, if found, the files \fIrelup\fR\& and \fIsys\&.config\fR\&\&. These files are searched for in the same directory as \fIName\&.rel\fR\&, in the current working directory, and in any directories specified using the \fIpath\fR\& option\&.
.LP
If the release package should contain a new Erlang runtime system, the \fIbin\fR\& directory of the specified runtime system \fI{erts,Dir}\fR\& is copied to \fIerts-ErtsVsn/bin\fR\&\&.
.LP
All checks performed with the \fImake_script\fR\& function are performed before the release package is created\&. The \fIsrc_tests\fR\& and \fIexref\fR\& options are also valid here\&.
.LP
The return value and the handling of errors and warnings are the same as described for \fImake_script\fR\& above\&.
.RE

.LP
.B
script2boot(File) -> ok | error
.br
.RS
.LP
Types:

.RS 3
File = string()
.br
.RE
.RE
.RS
.LP
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 \fIFile\&.script\fR\& boot script to a binary term which is stored in the file \fIFile\&.boot\fR\&\&.
.LP
A boot script generated using the \fImake_script\fR\& function is already transformed to the binary form\&.
.RE

.SH "SEE ALSO"

.LP
app(5), appup(5), erl(1), rel(5), release_handler(3erl), relup(5), script(5)