# 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, UpFrom, DownTo) -> Result`
`make_relup(Name, UpFrom, DownTo, [Opt]) -> Result`

Types:

`Name = string()`
`UpFrom = DownTo = [Name | {Name,Descr}]`
`Descr = term()`
`Opt = {path,[Dir]} | restart_emulator | silent | noexec | {outdir,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.

By default, `relup` is placed in the current working directory. If the option `{outdir,Dir}` is provided, `relup` is placed 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, 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 or downgrading, that is if the ERTS version differs between `Name.rel` and `Name2.rel`.

Instructions for this are added to the `relup` script 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 `relup`.

The optional `Descr` 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,[Dir]}` is provided, this path is appended to the current path. The wildcard `*` is expanded to all matching directories. Example: `lib/*/ebin`.

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, [Opt]) -> Result`

Types:

`Name = string()`
`Opt = no_module_tests | {path,[Dir]} | local | {variables,[Var]} | exref | {exref,[App]}] | silent | {outdir,Dir}`
`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 should be loaded and which applications should be started when the Erlang runtime system is started. See `script(4)`.

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

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

The correctness of each application is checked:

- The version of an application specified in the `.rel` file should be the same as the version specified in the `.app` file.
- There should be no undefined applications, that is, dependencies to applications which are not included in the release. (Key `applications` in `.app` file).
- 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 source code for a module is missing or newer than the object 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 `.rel` file is kept.

All files are searched for in the current 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 is an `ebin` directory in which case they may be located in the corresponding `src` directory.

If the option `{path,[Dir]}` is provided, this path is appended to the current path. A directory in the path can be given 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` and 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. If a variable `{VarName,Prefix}` is specified and an application is found in a directory `Prefix/Rest/App[-Vsn]/ebin`, this application will get the path `VarName/Rest/App-Vsn/ebin` in the boot script. If an application is found in a directory `Prefix/Rest`, the path will be `VarName/Rest/App-Vsn/ebin`. When starting Erlang, all variables `VarName` are given values using the `boot_var` command line flag.

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

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,[App]}`, 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, [Opt]) -> Result`

Types:

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

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

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

By default, the release package contains the directories `lib/App-Vsn/ebin` and `lib/App-Vsn/priv` for each included application. If more directories, the option `dirs` is supplied. Example: `{dirs,[src,examples]}`.

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

The `variables` option can be used to specify an installation directory other than `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 will be packed into a separate `VarName.tar.gz` file as `Rest/App-Vsn/ebin`.

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

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

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.

A directory called `releases` is also included in the release package, containing `Name.rel` and a subdirectory called `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`. These files are searched for in the same directory as `Name.rel`, in the current working directory, and in any directories specified using the `path` option.

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

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 and the handling of errors and warnings are the same as described for `make_script` 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 Arendt - support@erlang.ericsson.se

sasl 2.1.5.1
Copyright © 1991-2007 Ericsson AB