systools

A Set of Release Handling Tools

This module contains functions to generate boot scripts (.boot, .script), a release upgrade file (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} | warnings_as_errors
  •  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 instructions for upgrading from or downgrading to one or more previous releases. The instructions are used by release_handler when installing a new version of a release in runtime.

By default, relup file is located in the current working directory. If option {outdir,Dir} is specified, the relup file is located 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, the following is deducted:

Which applications to be deleted, that is, applications listed in Name.rel but not in Name2.rel

Which applications to be added, that is, applications listed in Name2.rel but not in Name.rel

Which applications to 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 file 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 the relup file.

The optional Descr parameter is included "as is" in the relup file, 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 files for an application are located in the same directory.

If option {path,[Dir]} is specified, this path is appended to the current path. Wildcard * is expanded to all matching directories, for example, lib/*/ebin.

If option restart_emulator is specified, a low-level instruction to restart the emulator is appended to the relup file. 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. For more information about this, see Design Principles in System Documentation.

By default, errors and warnings are printed to tty and the function returns ok or error. If option silent is specified, the function instead either returns {ok,Relup,Module,Warnings}, where Relup is the release upgrade file, or {error,Module,Error}. Warnings and errors can be converted to strings by calling Module:format_warning(Warnings) or Module:format_error(Error).

If option noexec is specified, the function returns the same values as for silent but no relup file is created.

If option warnings_as_errors is specified, warnings are treated as errors.

make_script(Name) -> Result make_script(Name, [Opt]) -> Result
  • 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 to be loaded and which applications to be started when the Erlang runtime system is started. See script(4).

The release resource file Name.rel is read to determine which applications are included in the release. Then the relevant application resource files App.app are read to determine which modules to be loaded, and if and how the applications are to be started. (Keys modules and mod, see app(4).

By default, the boot script and boot file are located in the same directory as Name.rel. That is, in the current working directory unless Name contains a path. If option {outdir,Dir} is specified, they are located in Dir instead.

The correctness of each application is checked as follows:

The version of an application specified in the .rel file is to be the same as the version specified in the .app file.

There are to be no undefined applications, that is, dependencies to applications that are not included in the release. (Key applications in the .app file).

There are to be no circular dependencies among the applications.

There are to be no duplicated modules, that is, modules with the same name but belonging to different applications.

If option src_tests is specified, a warning is issued if the source code for a module is missing or is 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 fails if the mandatory applications Kernel and STDLIB are not included in the .rel file and have start type permanent (which is default).

If SASL is not included as an application in the .rel file, a warning is issued because such a release cannot be used in an upgrade. To turn off this warning, add 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 are 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 can be located in the corresponding src directory.

If option {path,[Dir]} is specified, this path is appended to the current path. A directory in the path can be specified 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. They are assumed to be located in $ROOT/lib, where $ROOT is the root directory of the installed release. If option local is specified, the actual directories where the applications were found are used instead. This is a useful way to test a generated boot script locally.

Option variables 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 gets the path VarName/Rest/App-Vsn/ebin in the boot script. If an application is found in a directory Prefix/Rest, the path is VarName/Rest/App-Vsn/ebin. When starting Erlang, all variables VarName are given values using command-line flag boot_var.

Example: If option {variables,[{"TEST","lib"}]} is specified and myapp.app is found in lib/myapp/ebin, the path to this application in the boot script is "$TEST/myapp-1/ebin". If myapp.app is found in lib/test, the path is $TEST/test/myapp-1/ebin.

The checks performed before the boot script is generated can be extended with some cross reference checks by specifying option exref. These checks are performed with the Xref tool. All applications, or the applications specified with {exref,[App]}, are checked by Xref and warnings are issued for calls to undefined functions.

By default, errors and warnings are printed to tty and the function returns ok or error. If option silent is specified, 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 option warnings_as_errors is specified, warnings are treated as errors.

If option no_dot_erlang is specified, the instruction to load the .erlang file during boot is not included.

make_tar(Name) -> Result make_tar(Name, [Opt]) -> Result
  • Name = string()
  • Opt = {dirs,[IncDir]} | {path,[Dir]} | {variables,[Var]} | {var_tar,VarTar} | {erts,Dir} | src_tests | exref | {exref,[App]} | silent | {outdir,Dir} | | no_warn_sasl | warnings_as_errors
  •  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. This file must be uncompressed and unpacked on the target system using release_handler before the new release can be installed.

The release resource file Name.rel is read to determine which applications are included in the release. Then the relevant application resource files App.app are read to determine the version and modules of each application (keys vsn and modules, see app(4)).

By default, the release package file is located in the same directory as Name.rel. That is, in the current working directory unless Name contains a path. If option {outdir,Dir} is specified, it is located in Dir instead.

If SASL is not included as an application in the .rel file, a warning is issued because such a release cannot be used in an upgrade. To turn off this warning, add option no_warn_sasl.

By default, the release package contains the directories lib/App-Vsn/ebin and lib/App-Vsn/priv for each included application. If more directories are to be included, option dirs is specified, for example, {dirs,[src,examples]}.

All these files are searched for in the current path. If option {path,[Dir]} is specified, this path is appended to the current path. Wildcard * is expanded to all matching directories. Example: "lib/*/ebin".

Option variables can be used to specify an installation directory other than lib for some of the applications. If variable {VarName,Prefix} is specified and an application is found in directory Prefix/Rest/App[-Vsn]/ebin, this application is packed into a separate VarName.tar.gz file as Rest/App-Vsn/ebin.

Example: If option {variables,[{"TEST","lib"}]} is specified and myapp.app is located in lib/myapp-1/ebin, application myapp is included in TEST.tar.gz:

% tar tf TEST.tar
myapp-1/ebin/myapp.app
...

Option {var_tar,VarTar} can be used to specify if and where a separate package is to be stored. In this option VarTar is one of the following:

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 a separate file in the same directory as the ReleaseName.tar.gz file.
omit

No separate (variable) packages are generated. Applications that are found underneath a variable directory are ignored.

A directory releases is also included in the release package, containing Name.rel and a subdirectory 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 or sys.config.src. These files are searched for in the same directory as Name.rel, in the current working directory, and in any directories specified using option path. In the case of sys.config it is not included if sys.config.src is found.

If the release package is to contain a new Erlang runtime system, the bin directory of the specified runtime system {erts,Dir} is copied to erts-ErtsVsn/bin.

All checks with function make_script are performed before the release package is created. Options src_tests and exref are also valid here.

The return value and the handling of errors and warnings are the same as described for make_script.

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.boot file.

A boot script generated using make_script is already transformed to the binary form.

See Also

app(4), appup(4), erl(1), rel(4), release_handler(3), relup(4), script(4)