# systools

### MODULE

systools

### MODULE SUMMARY

A Set of Release Handling Tools.

### DESCRIPTION

This module contains functions to generate boot scripts (`.boot`, `.script`), release upgrade scripts (`relup`), and release packages.

### EXPORTS

`make_relup(Name, UpFromNames, DownToNames) -> Result`
`make_relup(Name, UpFromNames, DownToNames, Opts) -> Result`

Types:

`Name = string()`
`UpFromNames = DownToNames = [Name | {Name,Description}]`
`Description = term()`
`Opts = [Opt]`
`Opt = {path,Path} | restart_emulator | silent | noexec`
`Path = [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.

The function compares the release resource file `Name.rel` with all release resource files `Name2.rel` specified in `UpFromNames` and `DownToNames`. For each such pair, it is deducted:

- Which applications should be deleted, that is applications which are listed in `Name.rel` but not in `Name2.rel`.
- Which applications should be added, that is applications which are listed in `Name2.rel` but not in `Name.rel`.
- Which applications should 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/downgrading, that is if the ERTS version differs between the two release versions.

Instructions for this are added to the `relup` script in the above order. Instructions for upgrading/downgrading between application versions are fetched from the relevant application upgrade files `Application.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` in the current working directory.

The optional `Description` 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,Path}` is provided, `Path` is appended to the code path. A directory in the path can be given with a wildcard `*`, this is expanded to all matching directories.

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, Opts) -> Result`

Types:

`Name = string()`
`Opts = [Opt]`
`Opt = no_module_tests | {path,Path} |`
`| local | {variables,[Var]}`
`| exref | {exref,[Application]}]`
`| silent`
`Path = [Dir]`
`Dir = string()`
`Var = {VarName,PrefixDir}`
`VarName = PrefixDir = string()`
`Application = atom()`
`Result = ok | error`
`| {ok,Module,Warnings} | {error,Module,Error}`
`Module = atom()`
`Warnings = Error = term()`

Generates a boot script `Name.script` and a binary version `Name.boot`, specifying which code should be loaded and which applications should be started when the Erlang runtime system is started.

The function checks the contents of the release resource file `Name.rel` to find out which applications are included in the release. It then checks the relevant application resource files `Application.app` for the values of the `modules` and `mod` keys, see `app(4)`, to find out which modules should be loaded and if and how the application should be started.

The correctness of each application is checked:

- The version of an application specified in the release resource file should be the same as the version specified in the application resource file.
- There should be no undefined applications, that is, dependencies to applications which are not included in the release.
- 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 object code for a module is older than the source code.
  If the `no_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 release resource file is kept. The result is printed to `Name.script` and `Name.boot` in the current working directory (or to the directory where `Name.rel` is located, if `Name` contains a path).

All the files are searched for in the code 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 ends with `ebin` in which case they are assumed to be in the corresponding `src` directory.

If the option `{path,Path}` is provided, `Path` is appended to the code path. A directory in the path can be given with a wildcard `*`, this is expanded to all matching directories.

In the generated boot script all applications are 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. This is easiest illustrated using an example:

If the option `{variables,[{"TEST","/test/lib"}]}` is supplied, all applications found underneath `/test/lib` will get the path `$TEST` in the generated boot script.

When starting the system with the generated boot script, the `TEST` variable is given a value using the `-boot_var Var Dir` command line flag (see `erl(1)`).

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,[Application]}`, 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, Opts) -> Result`

Types:

`Name = string()`
`Opts = [Opt]`
`Opt = {path,Path} | silent | {dirs,Dirs} | {erts,ErtsDir} | no_module_tests | {variables,Vars} | {var_tar,VarTar} | {machine,Machine} | exref | {exref,[AppName]}`
`Path = [Dir]`
`Dir = string()`
`Dirs = [atom()]`
`ErtsDir = string()`
`Vars = [Var]`
`Var = {VarName,PreFixDir}`
`VarName = atom() | string()`
`PreFixDir = string()`
`VarTar = include | ownfile | omit`
`Machine = atom()`
`AppName = atom()`
`Result = ok | error`
`| {ok,Module,Warnings} | {error,Module,Error}`
`Module = atom()`
`Warning = Error = term()`

A release package file is generated from the `Name.rel` file. The `Name.tar.gz` file is generated. This file must be uncompressed and unpacked on the target system before the new release can be activated, using the `release_handler`.

By default, the generated release package contains a directory under the `lib` directory for each included application. Each application directory is named `ApplicationName-ApplicationVsn`. For each application, the `ebin` and `priv` directories are included. These directories are copied from where the applications were found. If more directories are needed, it is possible to specify these with the `{dirs,Dirs}` option. For example, if the src and example directories should be included for each application in the release package, the `{dirs,[src,examples]}` option should be supplied.

The `variables` option can be used to specify an installation directory other than the Erlang installation directory for the user provided applications. If the option `{variables,[{"TEST","/home/xxx/applications"}]}` is supplied, all applications found underneath this directory will be packed into the `TEST.tar.gz` file. Accordingly, a separate package is created for each defined variable. By default, all these files are included at the top level in the `ReleaseName.tar.gz` file and should be unpacked to an appropriate installation directory. 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 main `ReleaseName.tar.gz` file. This is the default.
- `ownfile`. Each separate (variable) package is generated as separate files in the same directory as the `ReleaseName.tar.gz` file.
- `omit`. No separate (variable) packages are generated and applications which are found underneath a variable directory are ignored.

The normal code server path is searched for the release file `ReleaseName.rel` and the application files (`ApplicationName.app`). The code server path can be appended with a path specified with the `{path, Path}` option. `Path` can contain wildcards (*) as described for the `make_script` function.

The `machine` option can be used to generate a release package file for an Erlang machine other than the running machine. This ensures that object code files with the expected file extension are included in the package, for example `.beam` files.

A directory called `releases/RelVsn` is also included in the release package. The release version `RelVsn` is found in the release package. This directory contains the boot script (`ReleaseName.boot` copied to `start.boot`), the `relup` file (generated by `make_relup`), and the system configuration file (`sys.config`).

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

Finally, the `releases` directory contains the `ReleaseName.rel` file.

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 `TarRet` and the handling of errors and warnings are as described for the `make_script` function above.

`script2boot(File) -> ok | error`

Types:

`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)

### AUTHORS

Gunilla Hugosson - support@erlang.ericsson.se

sasl 1.9.3
Copyright © 1991-2002 Ericsson Utvecklings AB