Provided by: erlang-manpages_22.0.7+dfsg-1_all bug

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)
                  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).
              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
                  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 to be loaded and which applications
              to be started when the Erlang runtime system is started. See script(5).

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

              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, [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} | |
                 no_warn_sasl | warnings_as_errors
                  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. 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)).

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

              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 bin directory
              of the specified runtime system {erts,Dir} is copied to erts-ErtsVsn/bin.

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