Go to main content

man pages section 5: File Formats

Exit Print View

Updated: Wednesday, February 10, 2021
 
 

appup (5erl)

Name

appup - Application upgrade file

Synopsis

Please see following description for synopsis

Description

appup(5)                             Files                            appup(5)



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 reg-
       ular 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 supervi-
       sor(3). 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 pro-
           cesses 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 pro-
           cesses 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. Call-
           back modules are dynamic.

       update with argument supervisor is used when changing the start  speci-
       fication 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 applica-
       tion. If Type = permanent | transient | temporary, the  application  is
       loaded  and  started  in  the corresponding way, see application(3). If
       Type = load, the application is only loaded. If Type = none, the appli-
       cation 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 mod-
       ules  are unloaded using delete_module, and then the application speci-
       fication 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_applica-
       tion 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  ear-
       lier.

       {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:termi-
       nate_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 supervi-
       sor: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  exe-
       cution  continues. If a node goes down, it is considered to be an unre-
       coverable 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 programmat-
       ically  determine  if  the  upgrade  is  complete,  call   release_han-
       dler: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  com-
       pleted,  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 incom-
       patible 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 applica-
       tion 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(3), relup(4), supervisor(3), systools(3)



Ericsson AB                       sasl 3.0.3                          appup(5)