Go to main content

man pages section 5: File Formats

Exit Print View

Updated: Thursday, June 13, 2019
 
 

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. Note that, even if  the  applica-
       tion  has  been  started  before  the  release  upgrade  is  performed,
       restart_application may only load it rather than start it, depending on
       the  application's  start type: 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.

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