Provided by: erlang-manpages_14.b.4-dfsg-1ubuntu1_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 should be called Application.appup where Application is the
       name of the application. The file  should  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() is the current version of the application.

         * UpFromVsn = string() is an earlier version of the application to upgrade from.

         * DownToVsn = string() is an earlier version of the application to downgrade to.

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

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, refer to OTP Design
       Principles.

       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 the module Mod. All those  processes  are
       suspended  using  sys:suspend,  the  new  version  of  the  module  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},  processes  implemented  using  gen_server,  gen_fsm  or  gen_event will
       transform their internal state by  calling  the  callback  function  code_change.  Special
       processes  will  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 and controls what action to take with processes that are
       executing  old  code  before  loading  the  new  version  of  the  module. 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 and controls what action to take with processes that
       are executing old code when the new version of the module 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 will purge the old  code  when  no
       remaining processes execute the code.

       DepMods  defaults  to  []  and  defines which other modules Mod is dependent on. In relup,
       instructions for  suspending  processes  using  Mod  will  come  before  instructions  for
       suspending  processes  using  modules  in  DepMods  when  upgrading,  and  vice versa when
       downgrading. In case of circular dependencies, the order of the instructions in the  appup
       script is kept.

       Timeout  defines  the  timeout when suspending processes. If no value or default is given,
       the default value for sys:suspend is used.

       ModType defaults to dynamic and specifies if the code is "dynamic", that is if  a  process
       using  the  module does spontaneously switch to new code, or if it is "static". When doing
       an advanced update and upgrading, 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.

       See update above for a description of PrePurge and PostPurge.

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

       {add_module, Mod}
         Mod = atom()

       Loads a new module Mod.

       {delete_module, Mod}
         Mod = atom()

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

       {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 will be loaded and started in the
       corresponding way, see application(3erl). If Type = load, the  application  will  only  be
       loaded.  If  Type = none, the application will be neither loaded nor started, although the
       code for its modules will be 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 the directory App-Vsn/ebin as a binary. It does not load the modules.
       The instruction should be placed first in the script in order to read all  new  code  from
       file to make the suspend-load-resume cycle less time consuming. After this instruction has
       been executed, the code server with the new version of App.

       point_of_no_return

       If a crash occurs after this instruction, the system cannot recover and is restarted  from
       the  old  version  of  the  release.  The instruction must only occur once in a script. It
       should 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. See the high-level instruction update
       for a description of PostPurge.

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

       Makes the current version of Mod old. PrePurge is ignored. See the high-level  instruction
       update for a description of PostPurge.

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

       Purges  each  module  Mod,  that  is removes the old code. Note 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  may  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 given, 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 the function sys:change_code, passing the term Extra as argument.

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

       Stops all processes using  a  module  Mod  by  calling  supervisor:terminate_child/2.  The
       instruction  is  useful  when  the  simplest way to change code is to stop and restart the
       processes which 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.

       The 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. In case  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 timeout for this instruction, which means that it may hang forever.

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

       Evaluates apply(M, F,  A).  If  the  instruction  appears  before  the  point_of_no_return
       instruction,   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 the point_of_no_return instruction, and the function call
       fails, the system is restarted.

       restart_new_emulator

       Shuts down the current emulator  and  starts  a  ne  one.  All  processes  are  terminated
       gracefully.  The  new release must still be made permanent when the new emulator is up and
       running. Otherwise, the old emulator is started  in  case  of  a  emulator  restart.  This
       instruction  should  be used when a new emulator is introduced, or if a complete reboot of
       the system should be done.

SEE ALSO

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