.TH systools 3 "sasl  2.1.5.3" "Ericsson AB" "ERLANG MODULE DEFINITION"
.SH MODULE
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
.TP
Types
Name = string()
.br
UpFrom = DownTo = [Name | {Name, Descr}]
.br
Descr = term()
.br
Opt = {path, [Dir]} | restart_emulator | silent | noexec | {outdir, Dir}
.br
Dir = string()
.br
Result = ok | error | {ok, Relup, Module, Warnings} | {error, Module, Error}
.br
Relup - see relup(4)
.br
Module = atom()
.br
Warnings = Error = term()
.br
.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\&.
.TP 2
*
Which applications should be added, that is applications which are listed in \fIName2\&.rel\fR but not in \fIName\&.rel\fR\&.
.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\&.
.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\&.
.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(4)\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
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\&.
.RE
.LP
.B
make_script(Name) -> Result
.br
.B
make_script(Name, [Opt]) -> Result
.br
.RS
.TP
Types
Name = string()
.br
Opt = no_module_tests | {path, [Dir]} | local | {variables, [Var]} | exref | {exref, [App]}] | silent | {outdir, Dir}
.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
.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(4)\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(4)\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\&.
.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)\&.
.TP 2
*
There should be no circular dependencies among the applications\&.
.TP 2
*
There should no duplicated modules, that is, modules with the same name but belonging to different applications\&.
.TP 2
*
A warning is issued if the source code for a module is missing or newer than the object code\&. 
.br
 If the \fIno_module_tests\fR option is specified, this check is omitted\&.
.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
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\&.
.RE
.LP
.B
make_tar(Name) -> Result
.br
.B
make_tar(Name, [Opt]) -> Result
.br
.RS
.TP
Types
Name = string()
.br
Opt = {dirs, [IncDir]} | {path, [Dir]} | {variables, [Var]} | {var_tar, VarTar} | {erts, Dir} | no_module_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
.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(4)\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:

.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\&.
.TP 2
*
\fIownfile\fR\&. Each separate (variable) package is generated as separate files in the same directory as the \fIReleaseName\&.tar\&.gz\fR file\&.
.TP 2
*
\fIomit\fR\&. No separate (variable) packages are generated and applications which are found underneath a variable directory are ignored\&.
.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 \fIno_module_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
.TP
Types
File = string()
.br
.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(4), appup(4), erl(1), rel(4), release_handler(3), relup(4), script(4)