appup - Application upgrade file
Please see following description for synopsis
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 4.1.1 appup(5)