File: release_handling.html

package info (click to toggle)
erlang-doc-html 1%3A11.b.2-1
links: PTS
area: main
in suites: etch, etch-m68k
size: 23,284 kB
ctags: 10,724
sloc: erlang: 505; ansic: 323; makefile: 62; perl: 61; sh: 45
file content (851 lines) | stat: -rw-r--r-- 29,356 bytes
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<!-- This document was generated using DocBuilder 3.3.3 -->
<HTML>
<HEAD>
  <TITLE>Release Handling</TITLE>
  <SCRIPT type="text/javascript" src="../../doc/erlresolvelinks.js">
</SCRIPT>
</HEAD>
<BODY BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" VLINK="#FF00FF"
      ALINK="#FF0000">
<CENTER>
<A HREF="http://www.erlang.se"><IMG BORDER=0 ALT="[Ericsson AB]" SRC="min_head.gif"></A>
</CENTER>
<A NAME="11"><!-- Empty --></A>
<H2>11 Release Handling</H2>
<A NAME="11.1"><!-- Empty --></A>
<H3>11.1 Release Handling Principles</H3>

<P>An important feature of the Erlang programming language is
the ability to change module code in run-time, <STRONG>code
        replacement</STRONG>, as described in <STRONG>Erlang Reference
        Manual</STRONG>.
<P>Based on this feature, the OTP application SASL provides a
framework for upgrading and downgrading between different
versions of an entire release in run-time. This is what we call
<STRONG>release handling</STRONG>.
<P>The framework consists of off-line support (<CODE>systools</CODE>) for
generating scripts and building release packages, and on-line
support (<CODE>release_handler</CODE>) for unpacking and installing
release packages.
<P>Note that the minimal system based on Erlang/OTP, enabling
release handling, thus consists of Kernel, STDLIB and SASL.
<P>
<OL>

<LI>
        A release is created as described in the previous chapter
         <A HREF="release_structure.html">Releases</A>.
         The release is transferred to and installed at target
         environment. Refer to <STRONG>System Principles</STRONG> for
         information of how to install the first target system.<BR>


</LI>


<LI>
        Modifications, for example error corrections, are made to
         the code in the development environment.<BR>


</LI>


<LI>
        At some point it is time to make a new version of release.
         The relevant <CODE>.app</CODE> files are updated and a new
         <CODE>.rel</CODE> file is written.<BR>


</LI>


<LI>
        For each modified application, an
         <A HREF="#appup">application upgrade file</A>,
         <CODE>.appup</CODE>, is created. In this file, it is described how
         to upgrade and/or downgrade between the old and new version of
         the application.<BR>


</LI>


<LI>
        Based on the <CODE>.appup</CODE> files, a
         <A HREF="#relup">release upgrade file</A> called
         <CODE>relup</CODE>, is created. This file describes how to upgrade
         and/or downgrade between the old and new version of
         the entire release.<BR>


</LI>


<LI>
         A new release package is made and transferred to
         the target system.<BR>


</LI>


<LI>
        The new release package is unpacked using the release
         handler.<BR>


</LI>


<LI>
        The new version of the release is installed, also using
         the release handler. This is done by evaluating
         the instructions in <CODE>relup</CODE>. Modules may be added,
         deleted or re-loaded, applications may be started, stopped or
         re-started etc. In some cases, it is even necessary to restart
         the entire emulator.<BR>

        If the installation fails, the system may be rebooted.
         The old release version is then automatically used.<BR>


</LI>


<LI>
        If the installation succeeds, the new version is made
         the default version, which should now be used in case of a
         system reboot.<BR>


</LI>


</OL>

<P>The next chapter, <A HREF="appup_cookbook.html">Appup
        Cookbook</A>, contains examples of <CODE>.appup</CODE> files
for typical cases of upgrades/downgrades that are normally easy
to handle in run-time. However, there are a many aspects that can
make release handling complicated. To name a few examples:
<P>
<UL>

<LI>
        Complicated or circular dependencies can make it difficult
         or even impossible to decide in which order things must be
         done without risking run-time errors during an upgrade or
         downgrade. Dependencies may be:<BR>

        
<UL>

<LI>
between nodes,
</LI>


<LI>
between processes, and
</LI>


<LI>
between modules.
</LI>


</UL>


</LI>


<LI>
        During release handling, non-affected processes continue
         normal execution. This may lead to timeouts or other problems.
         For example, new processes created in the time window between
         suspending processes using a certain module and loading a new
         version of this module, may execute old code.<BR>


</LI>


</UL>

<P>It is therefore recommended that code is changed in as small
steps as possible, and always kept backwards compatible.<A NAME="req"><!-- Empty --></A><A NAME="11.2"><!-- Empty --></A>
<H3>11.2 Requirements</H3>

<P>For release handling to work properly, the runtime system needs
to have knowledge about which release it is currently running. It
must also be able to change (in run-time) which boot script and
system configuration file should be used if the system is
rebooted, for example by <CODE>heart</CODE> after a failure.
Therefore, Erlang must be started as an embedded system, see
<STRONG>Embedded System</STRONG> for information on how to do this.
<P>For system reboots to work properly, it is also required that
the system is started with heart beat monitoring, see
<CODE>erl(1)</CODE> and <CODE>heart(3)</CODE>.
<P>Other requirements:
<P>
<UL>

<LI>
        The boot script included in a release package must be
         generated from the same <CODE>.rel</CODE> file as the release
         package itself.<BR>

        Information about applications are fetched from the script
         when an upgrade or downgrade is performed.<BR>


</LI>


<LI>
        The system must be configured using one and only one system
         configuration file, called <CODE>sys.config</CODE>.<BR>

        If found, this file is automatically included when a release
         package is created.<BR>


</LI>


<LI>
        All versions of a release, except the first one, must
         contain a <CODE>relup</CODE> file.<BR>

        If found, this file is automatically included when a release
         package is created.<BR>


</LI>


</UL>
<A NAME="11.3"><!-- Empty --></A>
<H3>11.3 Distributed Systems</H3>

<P>If the system consists of several Erlang nodes, each node may use
its own version of the release. The release handler is a locally
registered process and must be called at each node where an
upgrade or downgrade is required. There is a release handling
instruction that can be used to synchronize the release handler
processes at a number of nodes: <CODE>sync_nodes</CODE>. See
<CODE>appup(4)</CODE>.<A NAME="instr"><!-- Empty --></A><A NAME="11.4"><!-- Empty --></A>
<H3>11.4 Release Handling Instructions</H3>

<P>OTP supports a set of <STRONG>release handling instructions</STRONG>
that is used when creating <CODE>.appup</CODE> files. The release
handler understands a subset of these, the <STRONG>low-level</STRONG>
instructions. To make it easier for the user, there are also a
number of <STRONG>high-level</STRONG> instructions, which are translated
to low-level instructions by <CODE>systools:make_relup</CODE>.
<P>Here, some of the most frequently used instructions are
described. The complete list of instructions is found in
<CODE>appup(4)</CODE>.
<P>First, some definitions:
<P>
<DL>

<DT>
<STRONG>Residence module</STRONG>
</DT>

<DD>
        The module where a process has its tail-recursive loop
        function(s). If the tail-recursive loop functions are
        implemented in several modules, all those modules are residence
        modules for the process.<BR>


</DD>

<DT>
<STRONG>Functional module</STRONG>
</DT>

<DD>
        A module which is not a residence module for any process.<BR>


</DD>

</DL>

<P>Note that for a process implemented using an OTP behaviour,
the behaviour module is the residence module for that process.
The callback module is a functional module.<A NAME="11.4.1"><!-- Empty --></A>
<H4>11.4.1 load_module</H4>

<P>If a simple extension has been made to a functional module, it
        is sufficient to simply load the new version of the module into
        the system, and remove the old version. This is called
        <STRONG>simple code replacement</STRONG> and for this the following
        instruction is used:
<PRE>
{load_module, Module}
      
</PRE>
<A NAME="11.4.2"><!-- Empty --></A>
<H4>11.4.2 update</H4>

<P>If a more complex change has been made, for example a change
        to the format of the internal state of a gen_server, simple code
        replacement is not sufficient. Instead it is necessary to
        suspend the processes using the module (to avoid that they try
        to handle any requests before the code replacement is
        completed), ask them to transform the internal state format and
        switch to the new version of the module, remove the old version
        and last, resume the processes. This is called <STRONG>synchronized
         code replacement</STRONG> and for this the following instructions
        are used:
<PRE>
{update, Module, {advanced, Extra}}
{update, Module, supervisor}
      
</PRE>

<P><CODE>update</CODE> with argument <CODE>{advanced,Extra}</CODE> is used
        when changing the internal state of a behaviour as described
        above. It will cause behaviour processes to call the callback
        function <CODE>code_change</CODE>, passing the term <CODE>Extra</CODE> and
        some other information as arguments. See the man pages for
        the respective behaviours and
        <A HREF="appup_cookbook.html#int_state">Appup
         Cookbook</A>.
<P><CODE>update</CODE> with argument <CODE>supervisor</CODE> is used when
        changing the start specification of a supervisor. See
        <A HREF="appup_cookbook.html#sup">Appup Cookbook</A>.

<P>The release handler finds the processes <STRONG>using</STRONG> a module
        to update by traversing the supervision tree of each running
        application and checking all the child specifications:
<PRE>
{Id, StartFunc, Restart, Shutdown, Type, Modules}
        
</PRE>

<P>A process is using a module if the name is listed in
        <CODE>Modules</CODE> in the child specification for the process.
<P>If <CODE>Modules=dynamic</CODE>, which is the case for event
        managers, the event manager process informs the release handler
        about the list of currently installed event handlers (gen_fsm)
        and it is checked if the module name is in this list instead.

<P>The release handler suspends, asks for code change, and
        resumes processes by calling the functions
        <CODE>sys:suspend/1,2</CODE>, <CODE>sys:change_code/4,5</CODE> and
        <CODE>sys:resume/1,2</CODE> respectively.<A NAME="11.4.3"><!-- Empty --></A>
<H4>11.4.3 add_module and delete_module</H4>

<P>If a new module is introduced, the following instruction is
        used:
<PRE>
{add_module, Module}
      
</PRE>

<P>The instruction loads the module and is absolutely necessary
        when running Erlang in embedded mode. It is not strictly
        required when running Erlang in interactive (default) mode,
        since the code server automatically searches for and loads
        unloaded modules.
<P>The opposite of <CODE>add_module</CODE> is <CODE>delete_module</CODE> which
        unloads a module:
<PRE>
{delete_module, Module}
      
</PRE>

<P>Note that any process, in any application, with <CODE>Module</CODE>
        as residence module, is killed when the instruction is
        evaluated. The user should therefore ensure that all such
        processes are terminated before deleting the module, to avoid
        a possible situation with failing supervisor restarts.<A NAME="11.4.4"><!-- Empty --></A>
<H4>11.4.4 Application Instructions</H4>

<P>Instruction for adding an application:
<PRE>
{add_application, Application}
      
</PRE>

<P>Adding an application means that the modules defined by
        the <CODE>modules</CODE> key in the <CODE>.app</CODE> file are loaded using
        a number of <CODE>add_module</CODE> instructions, then the application
        is started.
<P>Instruction for removing an application:
<PRE>
{remove_application, Application}
    
</PRE>

<P>Removing an application means that the application is stopped,
        the modules are unloaded using a number of <CODE>delete_module</CODE>
        instructions and then the application specification is unloaded
        from the application controller.
<P>Instruction for removing an application:
<PRE>
{restart_application, Application}
      
</PRE>

<P>Restarting an application means that the application is stopped
        and then started again similar to using the instructions
        <CODE>remove_application</CODE> and <CODE>add_application</CODE> in
        sequence.<A NAME="11.4.5"><!-- Empty --></A>
<H4>11.4.5 apply (low-level)</H4>

<P>To call an arbitrary function from the release handler,
        the following instruction is used:
<PRE>
{apply, {M, F, A}}
      
</PRE>

<P>The release handler will evalute <CODE>apply(M, F, A)</CODE>.<A NAME="11.4.6"><!-- Empty --></A>
<H4>11.4.6 restart_new_emulator (low-level)</H4>

<P>This instruction is used when changing to a new emulator
        version, or if a system reboot is needed for some other reason.
        Requires that the system is started with heart beat
        monitoring, see <CODE>erl(1)</CODE> and <CODE>heart(3)</CODE>.
<P>When the release handler encounters the instruction, it shuts
        down the current emulator by calling <CODE>init:reboot()</CODE>, see
        <CODE>init(3)</CODE>. All processes are terminated gracefully and
        the system can then be rebooted by the heart program, using
        the new release version. This new version must still be made
        permanent when the new emulator is up and running. Otherwise,
        the old version is used in case of a new system reboot.
<P>On UNIX, the release handler tells the heart program which
        command to use to reboot the system. Note that the environment
        variable <CODE>HEART_COMMAND</CODE>, normally used by the heart
        program, in this case is ignored. The command instead defaults
        to <CODE>$ROOT/bin/start</CODE>. Another command can be set
        by using the SASL configuration parameter <CODE>start_prg</CODE>, see
        <CODE>sasl(6)</CODE>.<A NAME="appup"><!-- Empty --></A><A NAME="11.5"><!-- Empty --></A>
<H3>11.5 Application Upgrade File</H3>

<P>To define how to upgrade/downgrade between the current version
and previous versions of an application, we create an
<STRONG>application upgrade file</STRONG>, or in short <CODE>.appup</CODE> file.
The file should be called <CODE>Application.appup</CODE>, where
<CODE>Application</CODE> is the name of the application:
<PRE>
{Vsn,
 [{UpFromVsn1, InstructionsU1},
  ...,
  {UpFromVsnK, InstructionsUK}],
 [{DownToVsn1, InstructionsD1},
  ...,
  {DownToVsnK, InstructionsDK}]}.
    
</PRE>

<P><CODE>Vsn</CODE>, a string, is the current version of the application,
as defined in the <CODE>.app</CODE> file. Each <CODE>UpFromVsn</CODE>
is a previous version of the application to upgrade from, and each
<CODE>DownToVsn</CODE> is a previous version of the application to
downgrade to. Each <CODE>Instructions</CODE> is a list of release
handling instructions.
<P>The syntax and contents of the <CODE>appup</CODE> file are described
in detail in <CODE>appup(4)</CODE>.
<P>In the chapter <A HREF="appup_cookbook.html">Appup
        Cookbook</A>, examples of <CODE>.appup</CODE> files for typical
upgrade/downgrade cases are given.
<P>Example: Consider the release <CODE>ch_rel-1</CODE> from
the <A HREF="release_structure.html#ch_rel">Releases</A>
chapter. Assume we want to add a function <CODE>available/0</CODE> to
the server <CODE>ch3</CODE> which returns the number of available
channels:
<P>(Hint: When trying out the example, make the changes in a copy of
the original directory, so that the first versions are still
available.)
<PRE>
-module(ch3).
-behaviour(gen_server).

-export([start_link/0]).
-export([alloc/0, free/1]).
-export([available/0]).
-export([init/1, handle_call/3, handle_cast/2]).

start_link() -&#62;
    gen_server:start_link({local, ch3}, ch3, [], []).

alloc() -&#62;
    gen_server:call(ch3, alloc).

free(Ch) -&#62;
    gen_server:cast(ch3, {free, Ch}).

available() -&#62;
    gen_server:call(ch3, available).

init(_Args) -&#62;
    {ok, channels()}.

handle_call(alloc, _From, Chs) -&#62;
    {Ch, Chs2} = alloc(Chs),
    {reply, Ch, Chs2};
handle_call(available, _From, Chs) -&#62;
    N = available(Chs),
    {reply, N, Chs}.

handle_cast({free, Ch}, Chs) -&#62;
    Chs2 = free(Ch, Chs),
    {noreply, Chs2}.
    
</PRE>

<P>A new version of the <CODE>ch_app.app</CODE> file must now be created,
where the version is updated:
<PRE>
{application, ch_app,
 [{description, &#34;Channel allocator&#34;},
  {vsn, &#34;2&#34;},
  {modules, [ch_app, ch_sup, ch3]},
  {registered, [ch3]},
  {applications, [kernel, stdlib, sasl]},
  {mod, {ch_app,[]}}
 ]}.
    
</PRE>

<P>To upgrade <CODE>ch_app</CODE> from <CODE>&#34;1&#34;</CODE> to <CODE>&#34;2&#34;</CODE> (and
to downgrade from <CODE>&#34;2&#34;</CODE> to <CODE>&#34;1&#34;</CODE>), we simply need to
load the new (old) version of the <CODE>ch3</CODE> callback module.
We create the application upgrade file <CODE>ch_app.appup</CODE> in
the <CODE>ebin</CODE> directory:
<PRE>
{&#34;2&#34;,
 [{&#34;1&#34;, [{load_module, ch3}]}],
 [{&#34;1&#34;, [{load_module, ch3}]}]
}.
    
</PRE>
<A NAME="relup"><!-- Empty --></A><A NAME="11.6"><!-- Empty --></A>
<H3>11.6 Release Upgrade File</H3>

<P>To define how to upgrade/downgrade between the new version and
previous versions of a release, we create a <STRONG>release upgrade
        file</STRONG>, or in short <CODE>relup</CODE> file.
<P>This file does not need to be created manually, it can be
generated by <CODE>systools:make_relup/3,4</CODE>. The relevant versions
of the <CODE>.rel</CODE> file, <CODE>.app</CODE> files and <CODE>.appup</CODE> files
are used as input. It is deducted which applications should be
added and deleted, and which applications that need to be upgraded
and/or downgraded. The instructions for this is fetched from
the <CODE>.appup</CODE> files and transformed into a single list of
low-level instructions in the right order.
<P>If the <CODE>relup</CODE> file is relatively simple, it can be created
manually. Remember that it should only contain low-level
instructions.
<P>The syntax and contents of the release upgrade file are
described in detail in <CODE>relup(4)</CODE>.
<P>Example, continued from the previous section. We have a new
version &#34;2&#34; of <CODE>ch_app</CODE> and an <CODE>.appup</CODE> file. We also
need a new version of the <CODE>.rel</CODE> file. This time the file is
called <CODE>ch_rel-2.rel</CODE> and the release version string is
changed changed from &#34;A&#34; to &#34;B&#34;:
<PRE>
{release,
 {&#34;ch_rel&#34;, &#34;B&#34;},
 {erts, &#34;5.3&#34;},
 [{kernel, &#34;2.9&#34;},
  {stdlib, &#34;1.12&#34;},
  {sasl, &#34;1.10&#34;},
  {ch_app, &#34;2&#34;}]
}.
    
</PRE>

<P>Now the <CODE>relup</CODE> file can be generated:
<PRE>
1&#62; <STRONG>systools:make_relup(&#34;ch_rel-2&#34;, [&#34;ch_rel-1&#34;], [&#34;ch_rel-1&#34;]).</STRONG>
ok
    
</PRE>

<P>This will generate a <CODE>relup</CODE> file with instructions for
how to upgrade from version &#34;A&#34; (&#34;ch_rel-1&#34;) to version &#34;B&#34;
(&#34;ch_rel-2&#34;) and how to downgrade from version &#34;B&#34; to version &#34;A&#34;.

<P>Note that both the old and new versions of the <CODE>.app</CODE> and
<CODE>.rel</CODE> files must be in the code path, as well as
the <CODE>.appup</CODE> and (new) <CODE>.beam</CODE> files. It is possible
to extend the code path by using the option <CODE>path</CODE>:
<PRE>
1&#62; <STRONG>systools:make_relup(&#34;ch_rel-2&#34;, [&#34;ch_rel-1&#34;], [&#34;ch_rel-1&#34;],</STRONG>
   <STRONG>[{path,[&#34;../ch_rel-1&#34;,</STRONG>
   <STRONG> &#34;../ch_rel-1/lib/ch_app-1/ebin&#34;]}]).</STRONG>
ok
    
</PRE>
<A NAME="rel_handler"><!-- Empty --></A><A NAME="11.7"><!-- Empty --></A>
<H3>11.7 Installing a Release</H3>

<P>When we have made a new version of a release, a release package
can be created with this new version and transferred to the target
environment.
<P>To install the new version of the release in run-time,
the <STRONG>release handler</STRONG> is used. This is a process belonging
to the SASL application, that handles unpacking, installation,
and removal of release packages. It is interfaced through
the module <CODE>release_handler</CODE>, which is described in detail in
<CODE>release_handler(3)</CODE>.
<P>Assuming there is a target system up and running with
installation root directory <CODE>$ROOT</CODE>, the release package with
the new version of the release should be copied to
<CODE>$ROOT/releases</CODE>.
<P>The first action is to <STRONG>unpack</STRONG> the release package,
the files are then extracted from the package:
<PRE>
release_handler:unpack_release(ReleaseName) =&#62; {ok, Vsn}
    
</PRE>

<P><CODE>ReleaseName</CODE> is the name of the release package except
the <CODE>.tar.gz</CODE> extension. <CODE>Vsn</CODE> is the version of
the unpacked release, as defined in its <CODE>.rel</CODE> file.
<P>A directory <CODE>$ROOT/lib/releases/Vsn</CODE> will be created, where
the <CODE>.rel</CODE> file, the boot script <CODE>start.boot</CODE>,
the system configuration file <CODE>sys.config</CODE> and <CODE>relup</CODE>
are placed. For applications with new version numbers,
the application directories will be placed under <CODE>$ROOT/lib</CODE>.
Unchanged applications are not affected.
<P>An unpacked release can be <STRONG>installed</STRONG>. The release
handler then evaluates the instructions in <CODE>relup</CODE>, step by
step:
<PRE>
release_handler:install_release(Vsn) =&#62; {ok, FromVsn, []}
    
</PRE>

<P>If an error occurs during the installation, the system is
rebooted using the old version of the release. If installation
succeeds, the system is afterwards using the new version of
the release, but should anything happen and the system is
rebooted, it would start using the previous version again. To be
made the default version, the newly installed release must be made
<STRONG>permanent</STRONG>, which means the previous version becomes
<STRONG>old</STRONG>:
<PRE>
release_handler:make_permanent(Vsn) =&#62; ok
    
</PRE>

<P>The system keeps information about which versions are old and
permanent in the files <CODE>$ROOT/releases/RELEASES</CODE> and
<CODE>$ROOT/releases/start_erl.data</CODE>.
<P>To downgrade from <CODE>Vsn</CODE> to <CODE>FromVsn</CODE>,
<CODE>install_release</CODE> must be called again:
<PRE>
release_handler:install_release(FromVsn) =&#62; {ok, Vsn, []}
    
</PRE>

<P>An installed, but not permanent, release can be <STRONG>removed</STRONG>.
Information about the release is then deleted from
<CODE>$ROOT/releases/RELEASES</CODE> and the release specific code,
that is the new application directories and
the <CODE>$ROOT/releases/Vsn</CODE> directory, are removed.
<PRE>
release_handler:remove_release(Vsn) =&#62; ok
    
</PRE>

<P>Example, continued from the previous sections:
<P>1) Create a target system as described in <STRONG>System
        Principles</STRONG> of the first version <CODE>&#34;A&#34;</CODE> of <CODE>ch_rel</CODE>
from
the <A HREF="release_structure.html#ch_rel">Releases</A>
chapter. This time <CODE>sys.config</CODE> must be included in
the release package. If no configuration is needed, the file
should contain the empty list:
<PRE>
[].
    
</PRE>

<P>2) Start the system as a simple target system. Note that in
reality, it should be started as an embedded system. However,
using <CODE>erl</CODE> with the correct boot script and <CODE>.config</CODE>
file is enough for illustration purposes:
<PRE>
% <STRONG>cd $ROOT</STRONG>
% <STRONG>bin/erl -boot $ROOT/releases/A/start -config $ROOT/releases/A/sys</STRONG>
...
    
</PRE>

<P><CODE>$ROOT</CODE> is the installation directory of the target system.

<P>3) In another Erlang shell, generate start scripts and create a
release package for the new version <CODE>&#34;B&#34;</CODE>. Remember to
include (a possible updated) <CODE>sys.config</CODE> and
the <CODE>relup</CODE> file, see <A HREF="#relup">Release
        Upgrade File</A> above.
<PRE>
1&#62; <STRONG>systools:make_script(&#34;ch_rel-2&#34;).</STRONG>
ok
2&#62; <STRONG>systools:make_tar(&#34;ch_rel-2&#34;).</STRONG>
ok
    
</PRE>

<P>The new release package now contains version &#34;2&#34; of <CODE>ch_app</CODE>
and the <CODE>relup</CODE> file as well:
<PRE>
% tar tf ch_rel-2.tar 
lib/kernel-2.9/ebin/kernel.app
lib/kernel-2.9/ebin/application.beam
...
lib/stdlib-1.12/ebin/stdlib.app
lib/stdlib-1.12/ebin/beam_lib.beam
...      
lib/sasl-1.10/ebin/sasl.app
lib/sasl-1.10/ebin/sasl.beam
...
lib/ch_app-2/ebin/ch_app.app
lib/ch_app-2/ebin/ch_app.beam
lib/ch_app-2/ebin/ch_sup.beam
lib/ch_app-2/ebin/ch3.beam
releases/B/start.boot
releases/B/relup
releases/B/sys.config
releases/ch_rel-2.rel
    
</PRE>

<P>4) Copy the release package <CODE>ch_rel-2.tar.gz</CODE> to
the <CODE>$ROOT/releases</CODE> directory.
<P>5) In the running target system, unpack the release package:
<PRE>
1&#62; <STRONG>release_handler:unpack_release(&#34;ch_rel-2&#34;).</STRONG>
{ok,&#34;B&#34;}
    
</PRE>

<P>The new application version <CODE>ch_app-2</CODE> is installed under
<CODE>$ROOT/lib</CODE> next to <CODE>ch_app-1</CODE>. The <CODE>kernel</CODE>,
<CODE>stdlib</CODE> and <CODE>sasl</CODE> directories are not affected, as
they have not changed.
<P>Under <CODE>$ROOT/releases</CODE>, a new directory <CODE>B</CODE> is created,
containing <CODE>ch_rel-2.rel</CODE>, <CODE>start.boot</CODE>,
<CODE>sys.config</CODE> and <CODE>relup</CODE>.
<P>6) Check if the function <CODE>ch3:available/0</CODE> is available:
<PRE>
2&#62; <STRONG>ch3:available().</STRONG>
** exited: {undef,[{ch3,available,[]},
                   {erl_eval,do_apply,5},
                   {shell,eval_loop,2}]} **
    
</PRE>

<P>7) Install the new release. The instructions in
<CODE>$ROOT/releases/B/relup</CODE> are executed one by one, resulting
in the new version of <CODE>ch3</CODE> being loaded. The function
<CODE>ch3:available/0</CODE> is now available:
<PRE>
3&#62; <STRONG>release_handler:install_release(&#34;B&#34;).</STRONG>
{ok,&#34;A&#34;,[]}
4&#62; <STRONG>ch3:available().</STRONG>
3
5&#62; <STRONG>code:which(ch3).</STRONG>
&#34;.../lib/ch_app-2/ebin/ch3.beam&#34;
6&#62; <STRONG>code:which(ch_sup).</STRONG>
&#34;.../lib/ch_app-1/ebin/ch_sup.beam&#34;
    
</PRE>

<P>Note that processes in <CODE>ch_app</CODE> for which code have not
been updated, for example the supervisor, are still evaluating
code from <CODE>ch_app-1</CODE>.
<P>8) If the target system is now rebooted, it will use version &#34;A&#34;
again. The &#34;B&#34; version must be made permanent, in order to be
used when the system is rebooted.
<PRE>
7&#62; <STRONG>release_handler:make_permanent(&#34;B&#34;).</STRONG>
ok
    
</PRE>
<A NAME="sys"><!-- Empty --></A><A NAME="11.8"><!-- Empty --></A>
<H3>11.8 Updating Application Specifications</H3>

<P>When a new version of a release is installed, the application
specifications are automatically updated for all loaded
applications.
<P>
<TABLE CELLPADDING=4>
  <TR>
    <TD VALIGN=TOP><IMG ALT="Note!" SRC="note.gif"></TD>
    <TD>

<P>The information about the new application specifications are
        fetched from the boot script included in the release package.
        It is therefore important that the boot script is generated from
        the same <CODE>.rel</CODE> file as is used to build the release
        package itself.    </TD>
  </TR>
</TABLE>

<P>Specifically, the application configuration parameters are
automatically updated according to (in increasing priority
order):
<P>
<OL>

<LI>
The data in the boot script, fetched from the new
        application resource file <CODE>App.app</CODE>
</LI>


<LI>
The new <CODE>sys.config</CODE>
</LI>


<LI>
Command line arguments <CODE>-App Par Val</CODE>
</LI>


</OL>

<P>This means that parameter values set in the other system
configuration files, as well as values set using
<CODE>application:set_env/3</CODE>, are disregarded.
<P>When an installed release is made permanent, the system process
<CODE>init</CODE> is set to point out the new <CODE>sys.config</CODE>.
<P>After the installation, the application controller will compare
the old and new configuration parameters for all running
applications and call the callback function:
<PRE>
Module:config_change(Changed, New, Removed)
    
</PRE>

<P><CODE>Module</CODE> is the application callback module as defined by
the <CODE>mod</CODE> key in the <CODE>.app</CODE> file. <CODE>Changed</CODE> and
<CODE>New</CODE> are lists of <CODE>{Par,Val}</CODE> for all changed and
added configuration parameters, respectively. <CODE>Removed</CODE> is
a list of all parameters <CODE>Par</CODE> that have been removed.
<P>The function is optional and may be omitted when implementing an
application callback module.<CENTER>
<HR>
<SMALL>
Copyright &copy; 1991-2006
<A HREF="http://www.erlang.se">Ericsson AB</A><BR>
</SMALL>
</CENTER>
</BODY>
</HTML>