bionic (5) appup.5.gz

Provided by: erlang-manpages_20.2.2+dfsg-1ubuntu2_all bug

NAME

       appup - Application upgrade file

DESCRIPTION

       The application upgrade file defines how an application is upgraded or downgraded in a running system.

       This file is used by the functions in systools when generating a release upgrade file relup.

FILE SYNTAX

       The  application  upgrade  file  is  to be called Application.appup, where Application is the application
       name. The file is to be located in the ebin directory for the application.

       The .appup file contains one single Erlang term, which  defines  the  instructions  used  to  upgrade  or
       downgrade the application. The file has the following syntax:

       {Vsn,
         [{UpFromVsn, Instructions}, ...],
         [{DownToVsn, Instructions}, ...]}.

         Vsn = string():
           Current application version.

         UpFromVsn = string() | binary():
           An  earlier  application  version to upgrade from. If it is a string, it is interpreted as a specific
           version number. If it is a binary, it is interpreted as a regular expression that can match  multiple
           version numbers.

         DownToVsn = string() | binary():
           An  earlier  application  version to downgrade to. If it is a string, it is interpreted as a specific
           version number. If it is a binary, it is interpreted as a regular expression that can match  multiple
           version numbers.

         Instructions:
           A  list  of  release upgrade instructions, see Release Upgrade Instructions. It is recommended to use
           high-level instructions only.  These  are  automatically  translated  to  low-level  instructions  by
           systools when creating the relup file.

       To  avoid  duplication  of  upgrade  instructions,  it  is  allowed to use regular expressions to specify
       UpFromVsn and DownToVsn. To be considered a regular expression, the version identifier must be  specified
       as a binary. For example, the following match all versions 2.1.x, where x is any number:

       <<"2\\.1\\.[0-9]+">>

       Notice that the regular expression must match the complete version string, so this example works for, for
       example, 2.1.1, but not for 2.1.1.1.

RELEASE UPGRADE INSTRUCTIONS

       Release upgrade instructions are interpreted by the release handler when an upgrade or downgrade is made.
       For more information about release handling, see OTP Design Principles in System Documentation.

       A  process  is  said  to use a module Mod if Mod is listed in the Modules part of the child specification
       used to start the process, see supervisor(3erl). In the case of gen_event, an event  manager  process  is
       said to use Mod if Mod is an installed event handler.

   High-Level Instructions
       {update, Mod}
       {update, Mod, supervisor}
       {update, Mod, Change}
       {update, Mod, DepMods}
       {update, Mod, Change, DepMods}
       {update, Mod, Change, PrePurge, PostPurge, DepMods}
       {update, Mod, Timeout, Change, PrePurge, PostPurge, DepMods}
       {update, Mod, ModType, Timeout, Change, PrePurge, PostPurge, DepMods}
         Mod = atom()
         ModType = static | dynamic
         Timeout = int()>0 | default | infinity
         Change = soft | {advanced,Extra}
           Extra = term()
         PrePurge = PostPurge = soft_purge | brutal_purge
         DepMods = [Mod]

       Synchronized code replacement of processes using module Mod.

       All  those  processes  are  suspended  using  sys:suspend, the new module version is loaded, and then the
       processes are resumed using sys:resume.

         Change:
           Defaults to soft and defines the type of code change. If it is set to  {advanced,Extra},  implemented
           processes  using  gen_server,  gen_fsm,  gen_statem,  or  gen_event transform their internal state by
           calling  the  callback  function  code_change.  Special  processes   call   the   callback   function
           system_code_change/4.  In  both  cases,  the  term  Extra  is  passed  as an argument to the callback
           function.

         PrePurge:
           Defaults to brutal_purge. It controls what action to take with processes executing  old  code  before
           loading  the new module version. If the value is brutal_purge, the processes are killed. If the value
           is soft_purge, release_handler:install_release/1 returns {error,{old_processes,Mod}}.

         PostPurge:
           Defaults to brutal_purge. It controls what action to take with processes that are executing old  code
           when  the  new  module version has been loaded. If the value is brutal_purge, the code is purged when
           the release is made permanent and the processes are killed. If the value is soft_purge,  the  release
           handler purges the old code when no remaining processes execute the code.

         DepMods:
           Defaults  to  []  and defines other modules that Mod is dependent on. In the relup file, instructions
           for suspending processes using Mod come before instructions for suspending processes using modules in
           DepMods  when upgrading, and conversely when downgrading. In case of circular dependencies, the order
           of the instructions in the appup file is kept.

         Timeout:
           Defines the time-out when suspending processes. If no value or  default  is  specified,  the  default
           value for sys:suspend is used.

         ModType:
           Defaults  to  dynamic.  It specifies if the code is "dynamic", that is, if a process using the module
           spontaneously switches to new code, or if it is "static". When doing an advanced update and  upgrade,
           the  new  version  of  a  dynamic  module  is loaded before the process is asked to change code. When
           downgrading, the process is asked to change code before loading the new version. For static  modules,
           the  new  version is loaded before the process is asked to change code, both in the case of upgrading
           and downgrading. Callback modules are dynamic.

       update with argument supervisor is used when changing the start specification of a supervisor.

       {load_module, Mod}
       {load_module, Mod, DepMods}
       {load_module, Mod, PrePurge, PostPurge, DepMods}
         Mod = atom()
         PrePurge = PostPurge = soft_purge | brutal_purge
         DepMods = [Mod]

       Simple code replacement of the module Mod.

       For a description of PrePurge and PostPurge, see update above.

       DepMods defaults to [] and defines  which  other  modules  Mod  is  dependent  on.  In  the  relup  file,
       instructions  for  loading  these modules come before the instruction for loading Mod when upgrading, and
       conversely when downgrading.

       {add_module, Mod}
       {add_module, Mod, DepMods}
         Mod = atom()
         DepMods = [Mod]

       Loads a new module Mod.

       DepMods defaults to [] and defines  which  other  modules  Mod  is  dependent  on.  In  the  relup  file,
       instructions  related  to  these  modules come before the instruction for loading Mod when upgrading, and
       conversely when downgrading.

       {delete_module, Mod}
       {delete_module, Mod, DepMods}
         Mod = atom()

       Deletes a module Mod using the low-level instructions remove and purge.

       DepMods defaults to [] and defines  which  other  modules  Mod  is  dependent  on.  In  the  relup  file,
       instructions  related  to  these modules come before the instruction for removing Mod when upgrading, and
       conversely when downgrading.

       {add_application, Application}
       {add_application, Application, Type}
         Application = atom()
         Type = permanent | transient | temporary | load | none

       Adding an application means that the modules defined by the modules key in the .app file are loaded using
       add_module.

       Type  defaults  to  permanent  and  specifies  the  start  type of the application. If Type = permanent |
       transient  |  temporary,  the  application  is  loaded  and  started  in  the  corresponding   way,   see
       application(3erl). If Type = load, the application is only loaded. If Type = none, the application is not
       loaded and not started, although the code for its modules is loaded.

       {remove_application, Application}
         Application = atom()

       Removing an  application  means  that  the  application  is  stopped,  the  modules  are  unloaded  using
       delete_module, and then the application specification is unloaded from the application controller.

       {restart_application, Application}
         Application = atom()

       Restarting  an application means that the application is stopped and then started again, similar to using
       the instructions remove_application and add_application in sequence.

   Low-Level Instructions
       {load_object_code, {App, Vsn, [Mod]}}
         App = Mod = atom()
         Vsn = string()

       Reads each Mod from directory App-Vsn/ebin as a binary. It does not load the modules. The instruction  is
       to be placed first in the script to read all new code from the file to make the suspend-load-resume cycle
       less time-consuming.

       point_of_no_return

       If a crash occurs after this instruction, the system cannot recover and is restarted from the old release
       version.  The instruction must only occur once in a script. It is to be placed after all load_object_code
       instructions.

       {load, {Mod, PrePurge, PostPurge}}
         Mod = atom()
         PrePurge = PostPurge = soft_purge | brutal_purge

       Before this instruction occurs, Mod must have been loaded using load_object_code. This instruction  loads
       the  module.  PrePurge  is ignored. For a description of PostPurge, see the high-level instruction update
       earlier.

       {remove, {Mod, PrePurge, PostPurge}}
         Mod = atom()
         PrePurge = PostPurge = soft_purge | brutal_purge

       Makes the current version of Mod old. PrePurge is ignored. For a description of PostPurge, see the  high-
       level instruction update earlier.

       {purge, [Mod]}
         Mod = atom()

       Purges  each  module Mod, that is, removes the old code. Notice that any process executing purged code is
       killed.

       {suspend, [Mod | {Mod, Timeout}]}
         Mod = atom()
         Timeout = int()>0 | default | infinity

       Tries to suspend all processes using a module Mod. If a process does not respond, it is ignored. This can
       cause  the  process to die, either because it crashes when it spontaneously switches to new code, or as a
       result of a purge operation. If no Timeout is specified or default is specified, the  default  value  for
       sys:suspend is used.

       {resume, [Mod]}
         Mod = atom()

       Resumes all suspended processes using a module Mod.

       {code_change, [{Mod, Extra}]}
       {code_change, Mode, [{Mod, Extra}]}
         Mod = atom()
         Mode = up | down
         Extra = term()

       Mode  defaults to up and specifies if it is an upgrade or downgrade. This instruction sends a code_change
       system message to all processes using a module Mod by  calling  function  sys:change_code,  passing  term
       Extra as argument.

       {stop, [Mod]}
         Mod = atom()

       Stops  all  processes  using  a  module  Mod by calling supervisor:terminate_child/2. This instruction is
       useful when the simplest way to change code is to stop and restart the processes that run the code.

       {start, [Mod]}
         Mod = atom()

       Starts all stopped processes using a module Mod by calling supervisor:restart_child/2.

       {sync_nodes, Id, [Node]}
       {sync_nodes, Id, {M, F, A}}
         Id = term()
         Node = node()
         M = F = atom()
         A = [term()]

       apply(M, F, A) must return a list of nodes.

       This instruction synchronizes the release installation with other nodes. Each  Node  must  evaluate  this
       command  with  the  same  Id. The local node waits for all other nodes to evaluate the instruction before
       execution continues. If a node goes down, it is considered to be an unrecoverable error,  and  the  local
       node  is  restarted  from the old release. There is no time-out for this instruction, which means that it
       can hang forever.

       {apply, {M, F, A}}
         M = F = atom()
         A = [term()]

       Evaluates apply(M, F, A).

       If  the   instruction   appears   before   instruction   point_of_no_return,   a   failure   is   caught.
       release_handler:install_release/1 then returns {error,{'EXIT',Reason}}, unless {error,Error} is thrown or
       returned. Then it returns {error,Error}.

       If the instruction appears after instruction point_of_no_return and the function call fails,  the  system
       is restarted.

       restart_new_emulator

       This  instruction  is  used when the application ERTS, Kernel, STDLIB, or SASL is upgraded. It shuts down
       the current emulator and starts a new one. All processes are terminated gracefully, and the  new  version
       of  ERTS,  Kernel,  STDLIB,  and  SASL are used when the emulator restarts. Only one restart_new_emulator
       instruction is allowed in the relup file, and it must be placed  first.  systools:make_relup/3,4  ensures
       this  when  the relup file is generated. The rest of the instructions in the relup file is executed after
       the restart as a part of the boot script.

       An info report is written when the upgrade is completed. To programmatically determine if the upgrade  is
       complete, call release_handler:which_releases/0,1 and check if the expected release has status current.

       The  new  release must still be made permanent after the upgrade is completed, otherwise the old emulator
       is started if there is an emulator restart.

   Warning:
       As stated earlier, instruction restart_new_emulator causes the emulator to be restarted with new versions
       of  ERTS>, Kernel, STDLIB, and SASL. However, all other applications do at startup run their old versions
       in this new emulator. This is usually no problem, but every now and then incompatible  changes  occur  to
       the core applications, which can cause trouble in this setting. Such incompatible changes (when functions
       are removed) are normally preceded by a  deprecation  over  two  major  releases.  To  ensure  that  your
       application  is  not crashed by an incompatible change, always remove any call to deprecated functions as
       soon as possible.

       restart_emulator

       This instruction is similar to restart_new_emulator, except it must be placed at the  end  of  the  relup
       file.  It  is  not related to an upgrade of the emulator or the core applications, but can be used by any
       application when a complete reboot of the system is required.

       When generating the relup file, systools:make_relup/3,4 ensures that there is only  one  restart_emulator
       instruction and that it is the last instruction in the relup file.

SEE ALSO

       release_handler(3erl), relup(5), supervisor(3erl), systools(3erl)