systools

MODULE

systools

MODULE SUMMARY

A Set of script Generators.

DESCRIPTION

This module contains functions to generate boot scripts, release upgrade scripts, and release packages. A release file (.rel), application definition files (.app), and application upgrade files (.appup) are required as input to these functions. The syntax definitions for these files can be found in rel(4), app(4) and appup(4) respectively, and also in the Design Principles chapter and in the SASL User's Guide.

If a boot script is written without using the generator, it can be transformed to a binary form with the script2boot/1 function, as required by the Erlang runtime system during start-up.

The behaviour functions described below can be used to obtain a list of the system defined behaviours, and information about which callback functions are required for each of them.

EXPORTS

behaviour_info() -> [Behaviour]

Types:
Behaviour = atom()

Returns a list of the behaviours defined in Erlang/OTP. gen_server and gen_event are examples of behaviours.

behaviour_info(Behaviour) -> [Function]

Types:
Behaviour = atom()
Function = {Name, Arity}
Name = atom()
Arity = int()

A behaviour calls a number of functions in the callback module. The functions that a callback module has to export are returned by this function. Behaviour is the same as returned from the behaviour_info/0 function.

make_script(ReleaseName) -> MakeRet
make_script(ReleaseName,Opts) -> MakeRet

Types:
ReleaseName = string()
Opts = [{path, Path} | silent | local | no_module_tests | {variables, Vars} | {machine, Machine} | exref | {exref, [AppName]}]
Path = [Dir]
Dir = string()
Vars = [Var]
Var = {VarName, PreFixDir}
VarName = atom() | string()
PreFixDir = string()
Machine = atom()
AppName = atom()
MakeRet = ok | error | {ok, Module, Warnings} | {error, Module, Error}
Warnings = void()
Module = atom()
Error = void()

A boot script file is generated from the ReleaseName.rel file. The ReleaseName.script and ReleaseName.boot files are generated. The release file contains a specification of the version of the release, and the name and version of the applications that are included.

The script generator searches the normal code server path for the ReleaseName.rel file and the application files ApplicationName.app. A path {path, Path} can be specified and appended to the code server path. Each directory in Path can be given with the wildcard * ( * is the only wildcard recognized). A directory given with wildcards is expanded to all matching directories. * is translated to "any character except /". If /*/ is specified - * is the only character given between two / characters - the corresponding regular expression is [^/]+ and it represents a directory.

The compiled Erlang modules should be located in the same directory as the .app file. The function searches for the source code in the corresponding src or src/e_src directory if the directory name of the .app file directory ends with /ebin. Otherwise, it searches for the source code in the .app file directory.

The correctness of each application is checked. The following checks are performed:

• The version of the application file found.
  


• Dependencies to applications not included in the release.
  


• Circular dependencies among applications.
  


• Duplicated module names.
  


• Version compliance between modules and versions specified in the application file.
  


• Currency of object code for each module.
  



The boot script is generated if all checks are satisfactory. The applications are loaded and started in the order specified in the release file. The exception to this order are dependencies between applications as specified in the application files. These dependencies specify that applications on which other applications depend must be started first.

If the no_module_tests option is specified, the module version and object code checks are excluded. This implies that a boot script can be generated without the requirement that each .app file must be located in the same directory as the modules which belong to the application.

The checks performed before the boot script is generated can be extended with some rudimentary cross reference checks by specifying the exref option. These checks are performed with the exref tool. All modules specified in the application resource files are loaded into the exref tool. A warning is generated for each call to an undefined function, but only explicit function calls are checked. No cross reference checks are performed if the exref option is specified in combination with the no_module_tests option.

As the cross reference checks can be heavy, the set of modules to be checked can be limited. The {exref, [AppName]} option specifies the applications in which modules should be cross referenced checked. One warning only is generated for each application whenever calls are found to functions in applications which are not cross reference checked.

The generated boot script contains a search path to all included applications. By default, all directories in the path are relative to the installation directory of the Erlang runtime system which uses the boot script.

The variables option can be used to specify an installation directory other than the Erlang installation directory for user provided applications. If the option {variables, [{"TEST","/home/xxx/applications"}]} is supplied, all applications found underneath this directory will have $TEST substituted in place of the directory. The variable substitution mechanism needs absolute paths. Therefore, the paths specified (either in the code server path, or with the path option) must be absolute. The following example illustrates this:

/home/xxx/applications/type1/app1/ebin
                            /app2/ebin
                       type2/app3/ebin
                       app4/ebin
        

The boot script is generated as:

systools:make_script(RelName,
                     [{path,["/home/xxx/applications/*/ebin"]},
                      {variables,[{"TEST","/home/xxx/applications"}]}])
        

In the generated boot script, the path looks as follows for the applications app1 - app4:

[...
 "$TEST/type1/app1-Vsn/ebin",
 "$TEST/type1/app2-Vsn/ebin",
 "$TEST/type2/app3-Vsn/ebin",
 "$TEST/app4-Vsn/ebin"]
        

When starting the system with the generated boot script, the TEST variable is given a value using the -boot_var Var Value command line flag. In the previous example, Var is TEST and Value is the name of the directory where these applications are installed. The -boot_var flag is described for the init module.

The local option can also be used to change the default path as well. If the local option is supplied, the path includes the actual directories where the applications were found. This is a useful way to test a generated boot script locally.

The machine option can be used to generate a boot script for an Erlang machine other than the running machine. This is important when checking the object code, as the file extension can differ between the machines (for example .beam).

By default, this function writes all errors and warnings to the tty and returns ok or error. Nothing is written to the tty if the silent option is supplied, but the function returns {ok, Module, Warnings} or {error, Module, Errors} instead. To convert the Warnings and Errors terms to strings, the Module:format_warning(Warnings) and Module:format_error(Errors) functions are called respectively.

make_relup(ReleaseName,UpNameList,DownNameList) -> RelRet
make_relup(ReleaseName,UpNameList,DownNameList,Opts) -> RelRet

Types:
ReleaseName = string() | atom()
UpNameList = NameList
DownNameList = NameList
NameList = [ReleaseName | {ReleaseName, Description}]
Description = term()
Opts = [{path, Path} | silent | noexec | restart_emulator]
Path = [Dir]
Dir = string()
RelRet = ok | error | {ok, Relup, Module, Warnings} | {error, Module, Error}
Relup = {Vsn, UpScript, DownScript}
UpScript = RelupScript
DownScript = RelupScript
RelupScript = [{Vsn, Description, Script}]
Script = [low_level_release_upgrade_instructions]
Warnings = void()
Module = atom()
Error = void()

A relup file is generated which describes how to upgrade the system from a number of previous releases, and also how to downgrade from a number of previous releases.

The relup file is built by gathering all the application release upgrade scripts and picking those applicable for each combination of release versions. The scripts are also translated from high level release instructions to low level instructions. The normal code server path is searched for release files (ReleaseName.rel) and application files (ApplicationName.app), as well as the application upgrade scripts files (ApplicationName.appup). The ApplicationName.app and ApplicationName.appup files must be in the same directory. 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.

A ReleaseName.rel file must be available for each UpName and DownName since the versions of the applications are compared. For each change in the application versions, there must be an entry in the Application.appup file.

The optional Description parameter which can be supplied to either of the input name lists is passed to the correct output script in the relup file. The parameter defaults to the empty list [].

Basically, make_relup combines a re-ordering of the ReleaseName.rel file and the Application.appup files, so that the new release version and a target release version is a list of release upgrade scripts for all applications that have changed between the two release versions.

By default, this function writes the relup script to a file named relup and all errors and warnings to the tty and returns ok or error. If the silent option is supplied, nothing is written to the tty and the function returns {ok, Relup, Module, Warnings} or {error, Module, Error} instead, where Relup is the structure written to the relup file. The Warnings and Errors can be converted to strings with the Module:format_warning(Warning) and Module:format_error(Error) functions. If the noexec option is supplied, then nothing is written to the relup file and the function returns one of the verbose return values.

If the restart_emulator option is supplied, the low-level instruction restart_new_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.

make_tar(ReleaseName) -> TarRet
make_tar(ReleaseName,Opts) -> TarRet

Types:
ReleaseName = string()
Opts = [{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()
TarRet = ok | error | {ok, Module, Warnings} | {error, Module, Error}
Warnings = void()
Module = atom()
Error = void()

A release package file is generated from the ReleaseName.rel file. The ReleaseName.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

release_handler(3), init(3), exref(3)

AUTHORS

Joe Armstrong - support@erlang.ericsson.se
Martin Björklund - support@erlang.ericsson.se
Magnus Fröberg - support@erlang.ericsson.se
Peter Lundell - support@erlang.ericsson.se