EVOLUTION-MANAGER

Edit File: systools.3

.TH systools 3 "sasl 2.3.4" "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(4) .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(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 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(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\&. .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(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\&: .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(4), appup(4), erl(1), rel(4), release_handler(3), relup(4), script(4)