systools(3)



systools(3erl)             Erlang Module Definition             systools(3erl)

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} | {er-
                 ror,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 re-
              leases. The instructions are used by  release_handler  when  in-
              stalling a new version of a release in runtime.

              By  default, relup file is located in the current working direc-
              tory. If option {outdir,Dir} is specified, the relup file is lo-
              cated 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, ap-
                  plications 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  appli-
              cation  versions  are  fetched from the relevant application up-
              grade files App.appup, sorted in the same order as when generat-
              ing  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 direc-
              tories, 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 en-
              sures that a complete reboot of the system is done when the sys-
              tem 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_up-
              grade  is  issued.  For  more information about this, see Design
              Principles in System Documentation.

              By default, errors and warnings are printed to tty and the func-
              tion  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,Er-
              ror}. 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_er-
                 lang  |  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,Mod-
                 ule,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).

              The release resource file Name.rel is read  to  determine  which
              applications  are included in the release. Then the relevant ap-
              plication 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 di-
              rectory 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,  depen-
                  dencies  to  applications  that  are not included in the re-
                  lease. (Key applications in the .app file).

                * There are to be no circular dependencies among the  applica-
                  tions.

                * 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 ob-
                  ject code.

              The applications are sorted according to  the  dependencies  be-
              tween the applications. Where there are no dependencies, the or-
              der 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  lo-
              cated 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.  Ex-
              ample: "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  direc-
              tory  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 applica-
              tion 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  vari-
              ables 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  applica-
              tion 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 appli-
              cations,  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 func-
              tion returns ok or error. If option {ok,Module,Warnings} or {er-
              ror,Module,Error}. silent is specified, the function instead re-
              turns 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  re-
              lease_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  ap-
              plication  resource files App.app are read to determine the ver-
              sion and modules of each application (keys vsn and modules,  see
              app(5)).

              By  default, the release package file is located in the same di-
              rectory as Name.rel. That is, in the current  working  directory
              unless  Name  contains  a path. If option {outdir,Dir} is speci-
              fied, 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 applica-
              tion. 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. Exam-
              ple: "lib/*/ebin".

              If the {extra_files, ExtraFiles} option is given  then  the  Ex-
              traFiles  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  direc-
              tory  other  than  lib for some of the applications. If variable
              {VarName,Prefix} is specified and an application is found in di-
              rectory  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 Re-
                  leaseName.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 re-
              lease 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 direc-
              tory as Name.rel, in the current working directory, and  in  any
              directories specified using option path. In the case of sys.con-
              fig it is not included if sys.config.src is found.

              If the release package is to contain a new Erlang  runtime  sys-
              tem,  the  erts-ErtsVsn/bin  directory  of the specified runtime
              system {erts,Dir} is copied to erts-ErtsVsn/bin. Some erts  exe-
              cutables  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),  appup(5),  erl(1),  rel(5),  release_handler(3erl),  relup(5),
       script(5)

Ericsson AB                        sasl 4.0                     systools(3erl)

Man(1) output converted with man2html
list of all man pages