Provided by: erlang-manpages_16.b.3-dfsg-1ubuntu2_all bug

NAME

       systools - 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}  |
                 warnings_as_errors
                  Dir = string()
                 Result = ok | error | {ok,Relup,Module,Warnings} | {error,Module,Error}
                  Relup - see relup(5)
                  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(5).
              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.

              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. See  Design  Principles  for
              more information about this.

              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.

              If the option warnings_as_errors is provided, 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
                  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(5).

              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(5)).

              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 be no duplicated modules, that is, modules with the same name but
                  belonging to different applications.

                * If the src_tests option is specified, a warning is issued if  the  source  code
                  for a module is missing or 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 will fail if the mandatory applications  kernel  and  stdlib  are  not
              included in the .rel file and have start type permanent (default).

              If  sasl  is  not included as an application in the .rel file, a warning is emitted
              because such a release can not be used in an upgrade. To turn off this warning, add
              the 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 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).

              If the option warnings_as_errors is provided, warnings are treated as errors.

              If  the  option no_dot_erlang is provided, the instruction to load the .erlang file
              during boot is NOT included.

       make_tar(Name) -> Result
       make_tar(Name, [Opt]) -> Result

              Types:

                 Name = string()
                 Opt = {dirs,[IncDir]} | {path,[Dir]} | {variables,[Var]}  |  {var_tar,VarTar}  |
                 {erts,Dir} | src_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(5)).

              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 src_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(5), appup(5), erl(1), rel(5), release_handler(3erl), relup(5), script(5)