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