<?xml version="1.0" encoding="latin1" ?>
<!DOCTYPE fileref SYSTEM "fileref.dtd">
<fileref>
<header>
<copyright>
<year>1997</year><year>2012</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
The contents of this file are subject to the Erlang Public License,
Version 1.1, (the "License"); you may not use this file except in
compliance with the License. You should have received a copy of the
Erlang Public License along with this software. If not, it can be
retrieved online at http://www.erlang.org/.
Software distributed under the License is distributed on an "AS IS"
basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
the License for the specific language governing rights and limitations
under the License.
</legalnotice>
<title>appup</title>
<prepared></prepared>
<docno></docno>
<date></date>
<rev></rev>
</header>
<file>appup</file>
<filesummary>Application upgrade file.</filesummary>
<description>
<p>The <em>application upgrade file</em> defines how an application
is upgraded or downgraded in a running system.</p>
<p>This file is used by the functions in <c>systools</c> when
generating a release upgrade file <c>relup</c>.</p>
</description>
<section>
<title>FILE SYNTAX</title>
<p>The application upgrade file should be called
<c>Application.appup</c> where <c>Application</c> is the name of
the application. The file should be located in the <c>ebin</c>
directory for the application.</p>
<p>The <c>.appup</c> file contains one single Erlang term, which
defines the instructions used to upgrade or downgrade
the application. The file has the following syntax:</p>
<code type="none">
{Vsn,
[{UpFromVsn, Instructions}, ...],
[{DownToVsn, Instructions}, ...]}.
</code>
<list type="bulleted">
<item>
<p><c>Vsn = string()</c> is the current version of
the application.</p>
</item>
<item>
<p><c>UpFromVsn = string() | binary()</c> is an earlier
version of the application to upgrade from. If it is a
string, it will be interpreted as a specific version
number. If it is a binary, it will be interpreted as a
regular expression which can match multiple version
numbers.</p>
</item>
<item>
<p><c>DownToVsn = string() | binary()</c> is an earlier
version of the application to downgrade to. If it is a
string, it will be interpreted as a specific version
number. If it is a binary, it will be interpreted as a
regular expression which can match multiple version
numbers.</p>
</item>
<item>
<p><c>Instructions</c> is a list of <em>release upgrade instructions</em>, see below. It is recommended to use
high-level instructions only. These are automatically
translated to low-level instructions by <c>systools</c> when
creating the <c>relup</c> file.</p>
</item>
</list>
<p>In order to avoid duplication of upgrade instructions it is
allowed to use regular expressions to specify the <c>UpFromVsn</c>
and <c>DownToVsn</c>. To be considered a regular expression, the
version identifier must be specified as a binary, e.g.</p>
<code type="none"><<"2\\.1\\.[0-9]+">></code>
<p>will match all versions <c>2.1.x</c>, where x is any number.</p>
</section>
<section>
<title>RELEASE UPGRADE INSTRUCTIONS</title>
<p>Release upgrade instructions are interpreted by the release
handler when an upgrade or downgrade is made. For more
information about release handling, refer to <em>OTP Design Principles</em>.</p>
<p>A process is said to <em>use</em> a module <c>Mod</c>, if
<c>Mod</c> is listed in the <c>Modules</c> part of the child
specification used to start the process, see <c>supervisor(3)</c>.
In the case of gen_event, an event manager process is said to use
<c>Mod</c> if <c>Mod</c> is an installed event handler.</p>
<p><em>High-level instructions</em></p>
<pre>
{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]
</pre>
<p>Synchronized code replacement of processes using the module
<c>Mod</c>. All those processes are suspended using
<c>sys:suspend</c>, the new version of the module is loaded and
then the processes are resumed using <c>sys:resume</c>.</p>
<p><c>Change</c> defaults to <c>soft</c> and defines the type of
code change. If it is set to <c>{advanced,Extra}</c>, processes
implemented using gen_server, gen_fsm or gen_event will transform
their internal state by calling the callback function
<c>code_change</c>. Special processes will call the callback
function <c>system_code_change/4</c>. In both cases, the term
<c>Extra</c> is passed as an argument to the callback function.</p>
<p><c>PrePurge</c> defaults to <c>brutal_purge</c> 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 <c>brutal_purge</c>, the processes are killed. If the value is
<c>soft_purge</c>, <c>release_handler:install_release/1</c>
returns <c>{error,{old_processes,Mod}}</c>.</p>
<p><c>PostPurge</c> defaults to <c>brutal_purge</c> 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 <c>brutal_purge</c>, the code is purged when the release is
made permanent and the processes are killed. If the value is
<c>soft_purge</c>, the release handler will purge the old code
when no remaining processes execute the code.</p>
<p><c>DepMods</c> defaults to [] and defines which other modules
<c>Mod</c> is dependent on. In <c>relup</c>, instructions for
suspending processes using <c>Mod</c> will come before
instructions for suspending processes using modules in
<c>DepMods</c> when upgrading, and vice versa when downgrading.
In case of circular dependencies, the order of the instructions in
the <c>appup</c> script is kept.</p>
<p><c>Timeout</c> defines the timeout when suspending processes.
If no value or <c>default</c> is given, the default value for
<c>sys:suspend</c> is used.</p>
<p><c>ModType</c> defaults to <c>dynamic</c> 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.</p>
<p><c>update</c> with argument <c>supervisor</c> is used when
changing the start specification of a supervisor.</p>
<pre>
{load_module, Mod}
{load_module, Mod, DepMods}
{load_module, Mod, PrePurge, PostPurge, DepMods}
Mod = atom()
PrePurge = PostPurge = soft_purge | brutal_purge
DepMods = [Mod]
</pre>
<p>Simple code replacement of the module <c>Mod</c>.</p>
<p>See <c>update</c> above for a description of <c>PrePurge</c> and
<c>PostPurge</c>.</p>
<p><c>DepMods</c> defaults to [] and defines which other modules
<c>Mod</c> is dependent on. In <c>relup</c>, instructions for
loading these modules will come before the instruction for loading
<c>Mod</c> when upgrading, and vice versa when downgrading.</p>
<pre>
{add_module, Mod}
Mod = atom()
</pre>
<p>Loads a new module <c>Mod</c>.</p>
<pre>
{delete_module, Mod}
Mod = atom()
</pre>
<p>Deletes a module <c>Mod</c> using the low-level instructions
<c>remove</c> and <c>purge</c>.</p>
<pre>
{add_application, Application}
{add_application, Application, Type}
Application = atom()
Type = permanent | transient | temporary | load | none
</pre>
<p>Adding an application means that the modules defined by
the <c>modules</c> key in the <c>.app</c> file are loaded using
<c>add_module</c>.</p>
<p><c>Type</c> defaults to <c>permanent</c> and specifies the start type
of the application. If <c>Type = permanent | transient | temporary</c>,
the application will be loaded and started in the corresponding way,
see <c>application(3)</c>. If <c>Type = load</c>, the application will
only be loaded. If <c>Type = none</c>, the application will be neither
loaded nor started, although the code for its modules will be loaded.</p>
<pre>
{remove_application, Application}
Application = atom()
</pre>
<p>Removing an application means that the application is stopped,
the modules are unloaded using <c>delete_module</c> and then
the application specification is unloaded from the application
controller.</p>
<pre>
{restart_application, Application}
Application = atom()
</pre>
<p>Restarting an application means that the application is
stopped and then started again similar to using the instructions
<c>remove_application</c> and <c>add_application</c> in sequence.</p>
<p><em>Low-level instructions</em></p>
<pre>
{load_object_code, {App, Vsn, [Mod]}}
App = Mod = atom()
Vsn = string()
</pre>
<p>Reads each <c>Mod</c> from the directory <c>App-Vsn/ebin</c> 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 <c>App</c>.</p>
<pre>
point_of_no_return
</pre>
<p>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 <c>load_object_code</c> instructions.</p>
<pre>
{load, {Mod, PrePurge, PostPurge}}
Mod = atom()
PrePurge = PostPurge = soft_purge | brutal_purge
</pre>
<p>Before this instruction occurs, <c>Mod</c> must have been loaded
using <c>load_object_code</c>. This instruction loads the module.
<c>PrePurge</c> is ignored. See the high-level instruction
<c>update</c> for a description of <c>PostPurge</c>.</p>
<pre>
{remove, {Mod, PrePurge, PostPurge}}
Mod = atom()
PrePurge = PostPurge = soft_purge | brutal_purge
</pre>
<p>Makes the current version of <c>Mod</c> old.
<c>PrePurge</c> is ignored. See the high-level instruction
<c>update</c> for a description of <c>PostPurge</c>.</p>
<pre>
{purge, [Mod]}
Mod = atom()
</pre>
<p>Purges each module <c>Mod</c>, that is removes the old code.
Note that any process executing purged code is killed.</p>
<pre>
{suspend, [Mod | {Mod, Timeout}]}
Mod = atom()
Timeout = int()>0 | default | infinity
</pre>
<p>Tries to suspend all processes using a module <c>Mod</c>. 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 <c>Timeout</c> is specified or <c>default</c> is
given, the default value for <c>sys:suspend</c> is used.</p>
<pre>
{resume, [Mod]}
Mod = atom()
</pre>
<p>Resumes all suspended processes using a module <c>Mod</c>.</p>
<pre>
{code_change, [{Mod, Extra}]}
{code_change, Mode, [{Mod, Extra}]}
Mod = atom()
Mode = up | down
Extra = term()
</pre>
<p><c>Mode</c> defaults to <c>up</c> and specifies if it is an
upgrade or downgrade.</p>
<p>This instruction sends a <c>code_change</c> system message to
all processes using a module <c>Mod</c> by calling the function
<c>sys:change_code</c>, passing the term <c>Extra</c> as argument.</p>
<pre>
{stop, [Mod]}
Mod = atom()
</pre>
<p>Stops all processes using a module <c>Mod</c> by calling
<c>supervisor:terminate_child/2</c>. The instruction is useful
when the simplest way to change code is to stop and restart the
processes which run the code.</p>
<pre>
{start, [Mod]}
Mod = atom()
</pre>
<p>Starts all stopped processes using a module <c>Mod</c> by calling
<c>supervisor:restart_child/2</c>.</p>
<pre>
{sync_nodes, Id, [Node]}
{sync_nodes, Id, {M, F, A}}
Id = term()
Node = node()
M = F = atom()
A = [term()]
</pre>
<p><c>apply(M, F, A)</c> must return a list of nodes.</p>
<p>The instruction synchronizes the release installation with other
nodes. Each <c>Node</c> must evaluate this command, with the same
<c>Id</c>. 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.</p>
<pre>
{apply, {M, F, A}}
M = F = atom()
A = [term()]
</pre>
<p>Evaluates <c>apply(M, F, A)</c>. If the instruction appears
before the <c>point_of_no_return</c> instruction, a failure is
caught. <c>release_handler:install_release/1</c> then returns
<c>{error,{'EXIT',Reason}}</c>, unless <c>{error,Error}</c> is
thrown or returned. Then it returns <c>{error,Error}</c>.</p>
<p>If the instruction appears after the <c>point_of_no_return</c>
instruction, and the function call fails, the system is
restarted.</p>
<pre>
restart_new_emulator
</pre>
<p>This instruction is used when 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 <c>restart_new_emulator</c>
instruction is allowed in the relup, and it shall be placed
first. <seealso marker="systools#make_relup/3">systools:make_relup3,4</seealso>
will ensure this when the relup is generated. The rest of the
relup script is executed after the restart as a part of the boot
script.</p>
<p>An info report will be written when the upgrade is
completed. To programatically find out if the upgrade is
complete,
call <seealso marker="release_handler#which_releases/0">
release_handler:which_releases</seealso> and check if the
expected release has status <c>current</c>.</p>
<p>The new release must still be made permanent after the upgrade
is completed. Otherwise, the old emulator is started in case of
an emulator restart.</p>
<pre>
restart_emulator
</pre>
<p>This instruction is similar to <c>restart_new_emulator</c>,
except it shall be placed at the end of the relup script. 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 reqiured. When generating the
relup, <seealso marker="systools#make_relup/3">systools:make_relup/3,4</seealso>
ensures that there is only one <c>restart_emulator</c>
instruction and that it is the last instruction of the
relup.</p>
</section>
<section>
<title>SEE ALSO</title>
<p><seealso marker="relup">relup(4)</seealso>,
<seealso marker="release_handler">release_handler(3)</seealso>,
supervisor(3),
<seealso marker="systools">systools(3)</seealso></p>
</section>
</fileref>
