---
name: "systools"
section: "3erl"
platform: "linux"
package: "erlang-manpages"
version: "1:25.2.3+dfsg-1+deb12u4"
release: "Debian 12 (Bookworm)"
platforms: ["linux"]
url: "https://new.carta.tech/systools"
---

# systools(3erl)

A Set of Release Handling Tools

## NAME

systools - A Set of Release Handling Tools

## DESCRIPTION

This module contains functions to generate boot scripts (*.boot*, *.script*), a release upgrade file (*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} \| warnings\_as\_errors\
\
  Dir = string()\
 Result = ok \| error \| {ok,Relup,Module,Warnings} \| {error,Module,Error}\
\
  Relup, see [relup(5)](/relup/5.md)\
\
  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(5)](/relup/5.md)*. 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**\

Types:

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 \| {script\_name, Name}\
\
  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*, unless the *{script\_name, ScriptName}* option is given, in which case the names are *ScriptName.script* and *ScriptName.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(5)](/script/5.md)*.

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(5)](/app/5.md)*.

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

Types:

Name = string()\
 Opts = \[Opt\]\
 Opt = \
\
     {dirs, \[IncDir\]} \|\
\
     {path, \[Dir\]} \|\
\
     {variables, \[Var\]} \|\
\
     {var\_tar, VarTar} \|\
\
     {erts, Dir} \|\
\
     erts\_all \| src\_tests \| exref \|\
\
     {exref, \[App\]} \|\
\
     silent \|\
\
     {outdir, Dir} \|\
\
     no\_warn\_sasl \| warnings\_as\_errors \|\
\
     {extra\_files, ExtraFiles}\
 Dir = file:filename\_all()\
 IncDir = src \| include \| atom()\
 Var = {VarName, PreFix}\
 VarName = PreFix = string()\
 VarTar = include \| ownfile \| omit\
 App = atom()\
 Result = \
\
     ok \| error \|\
\
     {ok, Module :: module(), Warnings :: term()} \|\
\
     {error, Module :: module(), Error :: term()}\
 ExtraFiles = \[{NameInArchive, file:filename\_all()}\]\
 NameInArchive = string()\

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(5)](/app/5.md)*).

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"*.

If the *{extra\_files, ExtraFiles}* option is given then the *ExtraFiles* are added to the tarball after everything else to be included has been added. The *ExtraFiles* list is a list of files or directories in the same format as the *add\_type()* tuple for erl\_tar:add/3,4

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 *erts-ErtsVsn/bin* directory of the specified runtime system *{erts,Dir}* is copied to *erts-ErtsVsn/bin*. Some erts executables are not copied by default, if you want to include all executables you can give the *erts\_all* option.

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**\

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

A boot script generated using *make\_script* is already transformed to the binary form.

## SEE ALSO

*[app(5)](/app/5.md)*, *[appup(5)](/appup/5.md)*, *[erl(1)](/erl/1.md)*, *[rel(5)](/rel/5.md)*, *[release\_handler(3erl)](/release_handler/3erl.md)*, *[relup(5)](/relup/5.md)*, *[script(5)](/script/5.md)*