diff options
Diffstat (limited to 'system/doc/design_principles/release_handling.xml')
| -rw-r--r-- | system/doc/design_principles/release_handling.xml | 649 |
1 files changed, 334 insertions, 315 deletions
diff --git a/system/doc/design_principles/release_handling.xml b/system/doc/design_principles/release_handling.xml index 9d1e2c8669..20ddc3dbf5 100644 --- a/system/doc/design_principles/release_handling.xml +++ b/system/doc/design_principles/release_handling.xml @@ -8,16 +8,17 @@ <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. + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. </legalnotice> @@ -28,128 +29,126 @@ <rev></rev> <file>release_handling.xml</file> </header> + <marker id="release handling"></marker> <section> <title>Release Handling Principles</title> <p>An important feature of the Erlang programming language is - the ability to change module code in run-time, <em>code replacement</em>, as described in <em>Erlang Reference Manual</em>.</p> + the ability to change module code in runtime, + <em>code replacement</em>, as described in the Erlang + Reference Manual.</p> <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 + versions of an entire release in runtime. This is called <em>release handling</em>.</p> - <p>The framework consists of off-line support (<c>systools</c>) for - generating scripts and building release packages, and on-line - support (<c>release_handler</c>) for unpacking and installing - release packages.</p> - <p>Note that the minimal system based on Erlang/OTP, enabling - release handling, thus consists of Kernel, STDLIB and SASL.</p> - <list type="ordered"> - <item> - <p>A release is created as described in the previous chapter - <seealso marker="release_structure">Releases</seealso>. - The release is transferred to and installed at target - environment. Refer to <em>System Principles</em> for - information of how to install the first target system.</p> - </item> - <item> - <p>Modifications, for example error corrections, are made to - the code in the development environment.</p> - </item> - <item> - <p>At some point it is time to make a new version of release. - The relevant <c>.app</c> files are updated and a new - <c>.rel</c> file is written.</p> - </item> - <item> - <p>For each modified application, an - <seealso marker="#appup">application upgrade file</seealso>, - <c>.appup</c>, is created. In this file, it is described how - to upgrade and/or downgrade between the old and new version of - the application.</p> - </item> - <item> - <p>Based on the <c>.appup</c> files, a - <seealso marker="#relup">release upgrade file</seealso> called - <c>relup</c>, is created. This file describes how to upgrade - and/or downgrade between the old and new version of - the entire release.</p> - </item> - <item> - <p>A new release package is made and transferred to - the target system.</p> - </item> - <item> - <p>The new release package is unpacked using the release - handler.</p> - </item> - <item> - <p>The new version of the release is installed, also using - the release handler. This is done by evaluating - the instructions in <c>relup</c>. 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.</p> - <p>If the installation fails, the system may be rebooted. - The old release version is then automatically used.</p> - </item> - <item> - <p>If the installation succeeds, the new version is made - the default version, which should now be used in case of a - system reboot.</p> - </item> - </list> - <p>The next chapter, <seealso marker="appup_cookbook">Appup Cookbook</seealso>, contains examples of <c>.appup</c> 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> + <p>The framework consists of:</p> <list type="bulleted"> - <item> - <p>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:</p> - <list type="bulleted"> - <item>between nodes,</item> - <item>between processes, and</item> - <item>between modules.</item> - </list> - </item> - <item> - <p>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.</p> - </item> + <item>Offline support - <c>systools</c> for generating scripts + and building release packages</item> + <item>Online support - <c>release_handler</c> for unpacking and + installing release packages</item> </list> - <p>It is therefore recommended that code is changed in as small + <p>The minimal system based on Erlang/OTP, enabling release handling, + thus consists of the Kernel, STDLIB, and SASL + applications.</p> + + <section> + <title>Release Handling Workflow</title> + <p><em>Step 1</em>) A release is created as described in + <seealso marker="release_structure">Releases</seealso>.</p> + <p><em>Step 2</em>) The release is transferred to and installed at + target environment. For information of how to install the first + target system, see System Principles.</p> + <p><em>Step 3</em>) Modifications, for example, error corrections, + are made to the code in the development environment.</p> + <p><em>Step 4</em>) At some point, it is time to make a new version + of release. The relevant <c>.app</c> files are updated and a new + <c>.rel</c> file is written.</p> + <p><em>Step 5</em>) For each modified application, an + <seealso marker="#appup">application upgrade file</seealso>, + <c>.appup</c>, is created. In this file, it is described how to + upgrade and/or downgrade between the old and new version of the + application.</p> + <p><em>Step 6</em>) Based on the <c>.appup</c> files, a + <seealso marker="#relup">release upgrade file</seealso> called + <c>relup</c>, is created. This file describes how to upgrade and/or + downgrade between the old and new version of the entire release.</p> + <p><em>Step 7</em>) A new release package is made and transferred to + the target system.</p> + <p><em>Step 8</em>) The new release package is unpacked using the + release handler.</p> + <p><em>Step 9</em>) The new version of the release is installed, + also using the release handler. This is done by evaluating the + instructions in <c>relup</c>. Modules can be added, deleted, or + reloaded, applications can be started, stopped, or restarted, and so + on. In some cases, it is even necessary to restart the entire + emulator.</p> + <list type="bulleted"> + <item>If the installation fails, the system can be rebooted. + The old release version is then automatically used.</item> + <item>If the installation succeeds, the new version is made + the default version, which is to now be used if there is a + system reboot.</item> + </list> + </section> + + <section> + <title>Release Handling Aspects</title> + <p><seealso marker="appup_cookbook">Appup Cookbook</seealso>, + contains examples of <c>.appup</c> files + for typical cases of upgrades/downgrades that are normally easy to + handle in runtime. However, many aspects can make release handling + complicated, for example:</p> + <list type="bulleted"> + <item> + <p>Complicated or circular dependencies can make it difficult + or even impossible to decide in which order things must be + done without risking runtime errors during an upgrade or + downgrade. Dependencies can be:</p> + <list type="bulleted"> + <item>Between nodes</item> + <item>Between processes</item> + <item>Between modules</item> + </list> + </item> + <item> + <p>During release handling, non-affected processes continue + normal execution. This can lead to time-outs 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, can execute old code.</p> + </item> + </list> + <p>It is thus recommended that code is changed in as small steps as possible, and always kept backwards compatible.</p> + </section> </section> <section> <marker id="req"></marker> <title>Requirements</title> - <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 <c>heart</c> after a failure. - Therefore, Erlang must be started as an embedded system, see - <em>Embedded System</em> for information on how to do this.</p> + <p>For release handling to work properly, the runtime system must + have knowledge about which release it is running. It + must also be able to change (in runtime) which boot script and + system configuration file to use if the system is + rebooted, for example, by <c>heart</c> after a failure. + Thus, Erlang must be started as an embedded system; for + information on how to do this, see Embedded System.</p> <p>For system reboots to work properly, it is also required that - the system is started with heart beat monitoring, see - <c>erl(1)</c> and <c>heart(3)</c>.</p> + the system is started with heartbeat monitoring, see the + <c>erl(1)</c> manual page in ERTS and the <c>heart(3)</c> + manual page in Kernel</p> <p>Other requirements:</p> <list type="bulleted"> <item> <p>The boot script included in a release package must be generated from the same <c>.rel</c> file as the release package itself.</p> - <p>Information about applications are fetched from the script + <p>Information about applications is fetched from the script when an upgrade or downgrade is performed.</p> </item> <item> - <p>The system must be configured using one and only one system + <p>The system must be configured using only one system configuration file, called <c>sys.config</c>.</p> <p>If found, this file is automatically included when a release package is created.</p> @@ -165,13 +164,13 @@ <section> <title>Distributed Systems</title> - <p>If the system consists of several Erlang nodes, each node may use + <p>If the system consists of several Erlang nodes, each node can 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: <c>sync_nodes</c>. See - <c>appup(4)</c>.</p> + upgrade or downgrade is required. A release handling + instruction, <c>sync_nodes</c>, can be used to synchronize the + release handler processes at a number of nodes, see the + <c>appup(4)</c> manual page in SASL.</p> </section> <section> @@ -183,31 +182,26 @@ instructions. To make it easier for the user, there are also a number of <em>high-level</em> instructions, which are translated to low-level instructions by <c>systools:make_relup</c>.</p> - <p>Here, some of the most frequently used instructions are - described. The complete list of instructions can be found in - <c>appup(4)</c>.</p> + <p>Some of the most frequently used instructions are described in + this section. The complete list of instructions is included in the + <c>appup(4)</c> manual page in SASL.</p> <p>First, some definitions:</p> - <taglist> - <tag><em>Residence module</em></tag> - <item> - <p>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.</p> - </item> - <tag><em>Functional module</em></tag> - <item> - <p>A module which is not a residence module for any process.</p> - </item> - </taglist> - <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.</p> + <list type="bulleted"> + <item><em>Residence module</em> - The module where a process has + its tail-recursive loop function(s). If these functions are + implemented in several modules, all those modules are residence + modules for the process.</item> + <item><em>Functional module</em> - A module that is not a + residence module for any process.</item> + </list> + <p>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.</p> <section> <title>load_module</title> <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 + is sufficient to load the new version of the module into the system, and remove the old version. This is called <em>simple code replacement</em> and for this the following instruction is used:</p> @@ -217,44 +211,50 @@ <section> <title>update</title> - <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 <em>synchronized code replacement</em> and for this the following instructions - are used:</p> + <p>If a more complex change has been made, for example, a change + to the format of the internal state of a <c>gen_server</c>, simple + code replacement is not sufficient. Instead, it is necessary to:</p> + <list type="bulleted"> + <item>Suspend the processes using the module (to avoid that + they try to handle any requests before the code replacement is + completed).</item> + <item>Ask them to transform the internal state format and + switch to the new version of the module.</item> + <item>Remove the old version.</item> + <item>Resume the processes.</item> + </list> + <p>This is called <em>synchronized code replacement</em> and for + this the following instructions are used:</p> <code type="none"> {update, Module, {advanced, Extra}} {update, Module, supervisor}</code> <p><c>update</c> with argument <c>{advanced,Extra}</c> is used when changing the internal state of a behaviour as described - above. It will cause behaviour processes to call the callback + above. It causes behaviour processes to call the callback function <c>code_change</c>, passing the term <c>Extra</c> and - some other information as arguments. See the man pages for + some other information as arguments. See the manual pages for the respective behaviours and - <seealso marker="appup_cookbook#int_state">Appup Cookbook</seealso>.</p> + <seealso marker="appup_cookbook#int_state">Appup Cookbook</seealso>.</p> <p><c>update</c> with argument <c>supervisor</c> is used when changing the start specification of a supervisor. See - <seealso marker="appup_cookbook#sup">Appup Cookbook</seealso>.</p> + <seealso marker="appup_cookbook#sup">Appup Cookbook</seealso>.</p> <p>When a module is to be updated, the release handler finds which processes that are <em>using</em> the module by traversing the supervision tree of each running application and checking all the child specifications:</p> <code type="none"> {Id, StartFunc, Restart, Shutdown, Type, Modules}</code> - <p>A process is using a module if the name is listed in + <p>A process uses a module if the name is listed in <c>Modules</c> in the child specification for the process.</p> <p>If <c>Modules=dynamic</c>, 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> + about the list of currently installed event handlers + (<c>gen_fsm</c>), and it is checked if the module name is in + this list instead.</p> <p>The release handler suspends, asks for code change, and resumes processes by calling the functions - <c>sys:suspend/1,2</c>, <c>sys:change_code/4,5</c> and - <c>sys:resume/1,2</c> respectively.</p> + <c>sys:suspend/1,2</c>, <c>sys:change_code/4,5</c>, and + <c>sys:resume/1,2</c>, respectively.</p> </section> <section> @@ -263,39 +263,39 @@ used:</p> <code type="none"> {add_module, Module}</code> - <p>The instruction loads the module and is absolutely necessary + <p>The instruction loads the module and is necessary when running Erlang in embedded mode. It is not strictly required when running Erlang in interactive (default) mode, since the code server then automatically searches for and loads unloaded modules.</p> - <p>The opposite of <c>add_module</c> is <c>delete_module</c> which + <p>The opposite of <c>add_module</c> is <c>delete_module</c>, which unloads a module:</p> <code type="none"> {delete_module, Module}</code> - <p>Note that any process, in any application, with <c>Module</c> + <p>Any process, in any application, with <c>Module</c> as residence module, is killed when the instruction is - evaluated. The user should therefore ensure that all such + evaluated. The user must therefore ensure that all such processes are terminated before deleting the module, to avoid - a possible situation with failing supervisor restarts.</p> + a situation with failing supervisor restarts.</p> </section> <section> <title>Application Instructions</title> - <p>Instruction for adding an application:</p> + <p>The following is the instruction for adding an application:</p> <code type="none"> {add_application, Application}</code> <p>Adding an application means that the modules defined by the <c>modules</c> key in the <c>.app</c> file are loaded using - a number of <c>add_module</c> instructions, then the application + a number of <c>add_module</c> instructions, and then the application is started.</p> - <p>Instruction for removing an application:</p> + <p>The following is the instruction for removing an application:</p> <code type="none"> {remove_application, Application}</code> <p>Removing an application means that the application is stopped, the modules are unloaded using a number of <c>delete_module</c> - instructions and then the application specification is unloaded + instructions, and then the application specification is unloaded from the application controller.</p> - <p>Instruction for restarting an application:</p> + <p>The following is the instruction for restarting an application:</p> <code type="none"> {restart_application, Application}</code> <p>Restarting an application means that the application is stopped @@ -305,46 +305,48 @@ </section> <section> - <title>apply (low-level)</title> + <title>apply (Low-Level)</title> <p>To call an arbitrary function from the release handler, the following instruction is used:</p> <code type="none"> {apply, {M, F, A}}</code> - <p>The release handler will evaluate <c>apply(M, F, A)</c>.</p> + <p>The release handler evalutes <c>apply(M, F, A)</c>.</p> </section> <section> <marker id="restart_new_emulator_instr"></marker> - <title>restart_new_emulator (low-level)</title> + <title>restart_new_emulator (Low-Level)</title> <p>This instruction is used when changing to a new emulator - version, or when any of the core applications kernel, stdlib - or sasl is upgraded. If a system reboot is needed for some - other reason, the <c>restart_emulator</c> instruction should - be used instead.</p> - <p>Requires that the system is started with heart beat - monitoring, see <c>erl(1)</c> and <c>heart(3)</c>.</p> - <p>The <c>restart_new_emulator</c> instruction shall always be - the very first instruction in a relup. If the relup is - generated by <c>systools:make_relup/3,4</c> this is + version, or when any of the core applications Kernel, + STDLIB, or SASL is upgraded. If a system reboot + is needed for another reason, the <c>restart_emulator</c> + instruction is to be used instead.</p> + <p>This instruction requires that the system is started with + heartbeat monitoring, see the <c>erl(1)</c> manual page in + ERTS and the <c>heart(3)</c> manual page in Kernel.</p> + <p>The <c>restart_new_emulator</c> instruction must always be + the first instruction in a relup. If the relup is + generated by <c>systools:make_relup/3,4</c>, this is automatically ensured.</p> <p>When the release handler encounters the instruction, it first generates a temporary boot file, which starts the new versions of the emulator and the core applications, and the old version of all other applications. Then it shuts down - the current emulator by calling <c>init:reboot()</c>, see - <c>init(3)</c>. All processes are terminated gracefully and - the system is rebooted by the heart program, using the + the current emulator by calling <c>init:reboot()</c>, see the + <c>init(3)</c> manual page in Kernel. + All processes are terminated gracefully and + the system is rebooted by the <c>heart</c> program, using the temporary boot file. After the reboot, the rest of the relup instructions are executed. This is done as a part of the temporary boot script.</p> <warning> - <p>Since this mechanism causes the new versions of the - emulator and core applications to run with the old version of - other applications during startup, extra care must be taken to + <p>This mechanism causes the new versions of the emulator and + core applications to run with the old version of other + applications during startup. Thus, take extra care to avoid incompatibility. Incompatible changes in the core - applications may in some situations be necessary. If possible, + applications can in some situations be necessary. If possible, such changes are preceded by deprecation over two major - releases before the actual change. To make sure your + releases before the actual change. To ensure the application is not crashed by an incompatible change, always remove any call to deprecated functions as soon as possible.</p> @@ -352,35 +354,36 @@ <p>An info report is written when the upgrade is completed. To programmatically find out if the upgrade is complete, call <c>release_handler:which_releases(current)</c> and check - if it returns the expected (i.e. the new) release.</p> + if it returns the expected (that is, the new) release.</p> <p>The new release version must be made permanent when the new - emulator is up and running. Otherwise, the old version will be - used in case of a new system reboot.</p> - <p>On UNIX, the release handler tells the heart program which - command to use to reboot the system. Note that the environment - variable <c>HEART_COMMAND</c>, normally used by the heart - program, in this case is ignored. The command instead defaults - to <c>$ROOT/bin/start</c>. Another command can be set - by using the SASL configuration parameter <c>start_prg</c>, see - <c>sasl(6)</c>.</p> + emulator is operational. Otherwise, the old version will be + used if there is a new system reboot.</p> + <p>On UNIX, the release handler tells the <c>heart</c> program + which command to use to reboot the system. The environment + variable <c>HEART_COMMAND</c>, normally used by the <c>heart</c> + program, is ignored in this case. The command instead defaults + to <c>$ROOT/bin/start</c>. Another command can be set by using + the SASL configuration parameter <c>start_prg</c>, see + the <c>sasl(6)</c> manual page.</p> </section> <section> <marker id="restart_emulator_instr"></marker> - <title>restart_emulator (low-level)</title> - <p>This instruction is not related to upgrades of erts or any of - the core applications. It can be used by any application to + <title>restart_emulator (Low-Level)</title> + <p>This instruction is not related to upgrades of ERTS or any + of the core applications. It can be used by any application to force a restart of the emulator after all upgrade instructions are executed.</p> - <p>There can only be one <c>restart_emulator</c> instruction in - a relup script, and it shall always be placed at the end. If - the relup is generated by <c>systools:make_relup/3,4</c> this + <p>A relup script can only have one <c>restart_emulator</c> + instruction and it must always be placed at the end. If + the relup is generated by <c>systools:make_relup/3,4</c>, this is automatically ensured.</p> <p>When the release handler encounters the instruction, it shuts - down the emulator by calling <c>init:reboot()</c>, see - <c>init(3)</c>. All processes are terminated gracefully and - the system can then be rebooted by the heart program using the - new release version. No more upgrade instruction will be + down the emulator by calling <c>init:reboot()</c>, see the + <c>init(3)</c> manual page in Kernel. + All processes are terminated gracefully and the system + can then be rebooted by the <c>heart</c> program using the + new release version. No more upgrade instruction is executed after the restart.</p> </section> </section> @@ -389,10 +392,11 @@ <marker id="appup"></marker> <title>Application Upgrade File</title> <p>To define how to upgrade/downgrade between the current version - and previous versions of an application, we create an - <em>application upgrade file</em>, or in short <c>.appup</c> file. - The file should be called <c>Application.appup</c>, where - <c>Application</c> is the name of the application:</p> + and previous versions of an application, an + <em>application upgrade file</em>, or in short an <c>.appup</c> + file is created. + The file is to be called <c>Application.appup</c>, where + <c>Application</c> is the application name:</p> <code type="none"> {Vsn, [{UpFromVsn1, InstructionsU1}, @@ -401,24 +405,27 @@ [{DownToVsn1, InstructionsD1}, ..., {DownToVsnK, InstructionsDK}]}.</code> - <p><c>Vsn</c>, a string, is the current version of the application, - as defined in the <c>.app</c> file. Each <c>UpFromVsn</c> - is a previous version of the application to upgrade from, and each - <c>DownToVsn</c> is a previous version of the application to - downgrade to. Each <c>Instructions</c> is a list of release - handling instructions.</p> - <p>The syntax and contents of the <c>appup</c> file are described - in detail in <c>appup(4)</c>.</p> - <p>In the chapter <seealso marker="appup_cookbook">Appup Cookbook</seealso>, examples of <c>.appup</c> files for typical - upgrade/downgrade cases are given.</p> - <p>Example: Consider the release <c>ch_rel-1</c> from - the <seealso marker="release_structure#ch_rel">Releases</seealso> - chapter. Assume we want to add a function <c>available/0</c> to - the server <c>ch3</c> which returns the number of available - channels:</p> - <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.)</p> + <list type="bulleted"> + <item><c>Vsn</c>, a string, is the current version of the application, + as defined in the <c>.app</c> file.</item> + <item>Each <c>UpFromVsn</c> is a previous version of the application + to upgrade from.</item> + <item>Each <c>DownToVsn</c> is a previous version of the application + to downgrade to.</item> + <item>Each <c>Instructions</c> is a list of release handling + instructions.</item> + </list> + <p>For information about the syntax and contents of the <c>.appup</c> + file, see the <c>appup(4)</c> manual page in SASL.</p> + <p><seealso marker="appup_cookbook">Appup Cookbook</seealso> + includes examples of <c>.appup</c> files for typical upgrade/downgrade + cases.</p> + <p><em>Example:</em> Consider the release <c>ch_rel-1</c> from + <seealso marker="release_structure#ch_rel">Releases</seealso>. + Assume you want to add a function <c>available/0</c> to server + <c>ch3</c>, which returns the number of available channels (when + trying out the example, change in a copy of the original + directory, so that the first versions are still available):</p> <code type="none"> -module(ch3). -behaviour(gen_server). @@ -465,9 +472,9 @@ handle_cast({free, Ch}, Chs) -> {mod, {ch_app,[]}} ]}.</code> <p>To upgrade <c>ch_app</c> from <c>"1"</c> to <c>"2"</c> (and - to downgrade from <c>"2"</c> to <c>"1"</c>), we simply need to + to downgrade from <c>"2"</c> to <c>"1"</c>), you only need to load the new (old) version of the <c>ch3</c> callback module. - We create the application upgrade file <c>ch_app.appup</c> in + Create the application upgrade file <c>ch_app.appup</c> in the <c>ebin</c> directory:</p> <code type="none"> {"2", @@ -480,25 +487,25 @@ handle_cast({free, Ch}, Chs) -> <marker id="relup"></marker> <title>Release Upgrade File</title> <p>To define how to upgrade/downgrade between the new version and - previous versions of a release, we create a <em>release upgrade file</em>, or in short <c>relup</c> file.</p> + previous versions of a release, a <em>release upgrade file</em>, + or in short <c>relup</c> file, is to be created.</p> <p>This file does not need to be created manually, it can be generated by <c>systools:make_relup/3,4</c>. The relevant versions - of the <c>.rel</c> file, <c>.app</c> files and <c>.appup</c> 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 + of the <c>.rel</c> file, <c>.app</c> files, and <c>.appup</c> files + are used as input. It is deducted which applications are to be + added and deleted, and which applications that must be upgraded + and/or downgraded. The instructions for this are fetched from the <c>.appup</c> files and transformed into a single list of low-level instructions in the right order.</p> <p>If the <c>relup</c> file is relatively simple, it can be created - manually. Remember that it should only contain low-level - instructions.</p> - <p>The syntax and contents of the release upgrade file are - described in detail in <c>relup(4)</c>.</p> - <p>Example, continued from the previous section. We have a new - version "2" of <c>ch_app</c> and an <c>.appup</c> file. We also - need a new version of the <c>.rel</c> file. This time the file is - called <c>ch_rel-2.rel</c> and the release version string is - changed changed from "A" to "B":</p> + manually. It it only to contain low-level instructions.</p> + <p>For details about the syntax and contents of the release upgrade + file, see the <c>relup(4)</c> manual page in SASL.</p> + <p><em>Example, continued from the previous section:</em> You have a + new version "2" of <c>ch_app</c> and an <c>.appup</c> file. A new + version of the <c>.rel</c> file is also needed. This time the file + is called <c>ch_rel-2.rel</c> and the release version string is + changed from "A" to "B":</p> <code type="none"> {release, {"ch_rel", "B"}, @@ -512,13 +519,13 @@ handle_cast({free, Ch}, Chs) -> <pre> 1> <input>systools:make_relup("ch_rel-2", ["ch_rel-1"], ["ch_rel-1"]).</input> ok</pre> - <p>This will generate a <c>relup</c> file with instructions for + <p>This generates a <c>relup</c> file with instructions for how to upgrade from version "A" ("ch_rel-1") to version "B" ("ch_rel-2") and how to downgrade from version "B" to version "A".</p> - <p>Note that both the old and new versions of the <c>.app</c> and - <c>.rel</c> files must be in the code path, as well as - the <c>.appup</c> and (new) <c>.beam</c> files. It is possible - to extend the code path by using the option <c>path</c>:</p> + <p>Both the old and new versions of the <c>.app</c> and + <c>.rel</c> files must be in the code path, as well as the + <c>.appup</c> and (new) <c>.beam</c> files. The code path can be + extended by using the option <c>path</c>:</p> <pre> 1> <input>systools:make_relup("ch_rel-2", ["ch_rel-1"], ["ch_rel-1"],</input> <input>[{path,["../ch_rel-1",</input> @@ -529,31 +536,34 @@ ok</pre> <section> <marker id="rel_handler"></marker> <title>Installing a Release</title> - <p>When we have made a new version of a release, a release package + <p>When you 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> - <p>To install the new version of the release in run-time, + <p>To install the new version of the release in runtime, the <em>release handler</em> 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 <c>release_handler</c>, which is described in detail in - <c>release_handler(3)</c>.</p> - <p>Assuming there is a target system up and running with + to the SASL application, which handles unpacking, installation, + and removal of release packages. It is communicated through + the <c>release_handler</c> module. For details, see the + <c>release_handler(3)</c> manual page in SASL.</p> + <p>Assuming there is an operational target system with installation root directory <c>$ROOT</c>, the release package with - the new version of the release should be copied to + the new version of the release is to be copied to <c>$ROOT/releases</c>.</p> - <p>The first action is to <em>unpack</em> the release package, - the files are then extracted from the package:</p> + <p>First, <em>unpack</em> the release package. + The files are then extracted from the package:</p> <code type="none"> release_handler:unpack_release(ReleaseName) => {ok, Vsn}</code> - <p><c>ReleaseName</c> is the name of the release package except - the <c>.tar.gz</c> extension. <c>Vsn</c> is the version of - the unpacked release, as defined in its <c>.rel</c> file.</p> - <p>A directory <c>$ROOT/lib/releases/Vsn</c> will be created, where + <list type="bulleted"> + <item><c>ReleaseName</c> is the name of the release package except + the <c>.tar.gz</c> extension.</item> + <item><c>Vsn</c> is the version of the unpacked release, as + defined in its <c>.rel</c> file.</item> + </list> + <p>A directory <c>$ROOT/lib/releases/Vsn</c> is created, where the <c>.rel</c> file, the boot script <c>start.boot</c>, - the system configuration file <c>sys.config</c> and <c>relup</c> + the system configuration file <c>sys.config</c>, and <c>relup</c> are placed. For applications with new version numbers, - the application directories will be placed under <c>$ROOT/lib</c>. + the application directories are placed under <c>$ROOT/lib</c>. Unchanged applications are not affected.</p> <p>An unpacked release can be <em>installed</em>. The release handler then evaluates the instructions in <c>relup</c>, step by @@ -563,11 +573,11 @@ release_handler:install_release(Vsn) => {ok, FromVsn, []}</code> <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 - <em>permanent</em>, which means the previous version becomes - <em>old</em>:</p> + the release, but if anything happens and the system is + rebooted, it starts using the previous version again.</p> + <p>To be made the default version, the newly installed release + must be made <em>permanent</em>, which means the previous + version becomes <em>old</em>:</p> <code type="none"> release_handler:make_permanent(Vsn) => ok</code> <p>The system keeps information about which versions are old and @@ -579,41 +589,44 @@ release_handler:make_permanent(Vsn) => ok</code> release_handler:install_release(FromVsn) => {ok, Vsn, []}</code> <p>An installed, but not permanent, release can be <em>removed</em>. Information about the release is then deleted from - <c>$ROOT/releases/RELEASES</c> and the release specific code, - that is the new application directories and + <c>$ROOT/releases/RELEASES</c> and the release-specific code, + that is, the new application directories and the <c>$ROOT/releases/Vsn</c> directory, are removed.</p> <code type="none"> release_handler:remove_release(Vsn) => ok</code> - <p>Example, continued from the previous sections:</p> - <p>1) Create a target system as described in <em>System Principles</em> of the first version <c>"A"</c> of <c>ch_rel</c> - from - the <seealso marker="release_structure#ch_rel">Releases</seealso> - chapter. This time <c>sys.config</c> must be included in - the release package. If no configuration is needed, the file - should contain the empty list:</p> - <code type="none"> + + <section> + <title>Example (continued from the previous sections)</title> + <p><em>Step 1)</em> Create a target system as described in + System Principles of the first version <c>"A"</c> + of <c>ch_rel</c> from + <seealso marker="release_structure#ch_rel">Releases</seealso>. + This time <c>sys.config</c> must be included in the release package. + If no configuration is needed, the file is to contain the empty + list:</p> + <code type="none"> [].</code> - <p>2) Start the system as a simple target system. Note that in - reality, it should be started as an embedded system. However, - using <c>erl</c> with the correct boot script and config file is - enough for illustration purposes:</p> - <pre> + <p><em>Step 2)</em> Start the system as a simple target system. In + reality, it is to be started as an embedded system. However, using + <c>erl</c> with the correct boot script and config file is enough for + illustration purposes:</p> + <pre> % <input>cd $ROOT</input> % <input>bin/erl -boot $ROOT/releases/A/start -config $ROOT/releases/A/sys</input> ...</pre> <p><c>$ROOT</c> is the installation directory of the target system.</p> - <p>3) In another Erlang shell, generate start scripts and create a - release package for the new version <c>"B"</c>. Remember to - include (a possible updated) <c>sys.config</c> and - the <c>relup</c> file, see <seealso marker="#relup">Release Upgrade File</seealso> above.</p> - <pre> + <p><em>Step 3)</em> In another Erlang shell, generate start scripts and + create a release package for the new version <c>"B"</c>. Remember to + include (a possible updated) <c>sys.config</c> and the <c>relup</c> file, + see <seealso marker="#relup">Release Upgrade File</seealso>.</p> + <pre> 1> <input>systools:make_script("ch_rel-2").</input> ok 2> <input>systools:make_tar("ch_rel-2").</input> ok</pre> - <p>The new release package now contains version "2" of <c>ch_app</c> - and the <c>relup</c> file as well:</p> - <code type="none"> + <p>The new release package now also contains version "2" of <c>ch_app</c> + and the <c>relup</c> file:</p> + <code type="none"> % tar tf ch_rel-2.tar lib/kernel-2.9/ebin/kernel.app lib/kernel-2.9/ebin/application.beam @@ -633,28 +646,30 @@ releases/B/relup releases/B/sys.config releases/B/ch_rel-2.rel releases/ch_rel-2.rel</code> - <p>4) Copy the release package <c>ch_rel-2.tar.gz</c> to - the <c>$ROOT/releases</c> directory.</p> - <p>5) In the running target system, unpack the release package:</p> - <pre> + <p><em>Step 4)</em> Copy the release package <c>ch_rel-2.tar.gz</c> + to the <c>$ROOT/releases</c> directory.</p> + <p><em>Step 5)</em> In the running target system, unpack the release + package:</p> + <pre> 1> <input>release_handler:unpack_release("ch_rel-2").</input> {ok,"B"}</pre> <p>The new application version <c>ch_app-2</c> is installed under <c>$ROOT/lib</c> next to <c>ch_app-1</c>. The <c>kernel</c>, - <c>stdlib</c> and <c>sasl</c> directories are not affected, as + <c>stdlib</c>, and <c>sasl</c> directories are not affected, as they have not changed.</p> <p>Under <c>$ROOT/releases</c>, a new directory <c>B</c> is created, containing <c>ch_rel-2.rel</c>, <c>start.boot</c>, - <c>sys.config</c> and <c>relup</c>.</p> - <p>6) Check if the function <c>ch3:available/0</c> is available:</p> - <pre> + <c>sys.config</c>, and <c>relup</c>.</p> + <p><em>Step 6)</em> Check if the function <c>ch3:available/0</c> is + available:</p> + <pre> 2> <input>ch3:available().</input> ** exception error: undefined function ch3:available/0</pre> - <p>7) Install the new release. The instructions in + <p><em>Step 7)</em> Install the new release. The instructions in <c>$ROOT/releases/B/relup</c> are executed one by one, resulting in the new version of <c>ch3</c> being loaded. The function <c>ch3:available/0</c> is now available:</p> - <pre> + <pre> 3> <input>release_handler:install_release("B").</input> {ok,"A",[]} 4> <input>ch3:available().</input> @@ -663,15 +678,16 @@ releases/ch_rel-2.rel</code> ".../lib/ch_app-2/ebin/ch3.beam" 6> <input>code:which(ch_sup).</input> ".../lib/ch_app-1/ebin/ch_sup.beam"</pre> - <p>Note that processes in <c>ch_app</c> for which code have not - been updated, for example the supervisor, are still evaluating + <p>Processes in <c>ch_app</c> for which code have not + been updated, for example, the supervisor, are still evaluating code from <c>ch_app-1</c>.</p> - <p>8) If the target system is now rebooted, it will use version "A" - again. The "B" version must be made permanent, in order to be + <p><em>Step 8)</em> If the target system is now rebooted, it uses + version "A" again. The "B" version must be made permanent, to be used when the system is rebooted.</p> - <pre> + <pre> 7> <input>release_handler:make_permanent("B").</input> ok</pre> + </section> </section> <section> @@ -681,37 +697,40 @@ ok</pre> specifications are automatically updated for all loaded applications.</p> <note> - <p>The information about the new application specifications are + <p>The information about the new application specifications is fetched from the boot script included in the release package. - It is therefore important that the boot script is generated from + Thus, it is important that the boot script is generated from the same <c>.rel</c> file as is used to build the release package itself.</p> </note> <p>Specifically, the application configuration parameters are automatically updated according to (in increasing priority order):</p> - <list type="ordered"> + <list type="bulleted"> <item>The data in the boot script, fetched from the new application resource file <c>App.app</c></item> <item>The new <c>sys.config</c></item> - <item>Command line arguments <c>-App Par Val</c></item> + <item>Command-line arguments <c>-App Par Val</c></item> </list> <p>This means that parameter values set in the other system - configuration files, as well as values set using - <c>application:set_env/3</c>, are disregarded.</p> + configuration files and values set using + <c>application:set_env/3</c> are disregarded.</p> <p>When an installed release is made permanent, the system process <c>init</c> is set to point out the new <c>sys.config</c>.</p> - <p>After the installation, the application controller will compare + <p>After the installation, the application controller compares the old and new configuration parameters for all running applications and call the callback function:</p> <code type="none"> Module:config_change(Changed, New, Removed)</code> - <p><c>Module</c> is the application callback module as defined by - the <c>mod</c> key in the <c>.app</c> file. <c>Changed</c> and - <c>New</c> are lists of <c>{Par,Val}</c> for all changed and - added configuration parameters, respectively. <c>Removed</c> is - a list of all parameters <c>Par</c> that have been removed.</p> - <p>The function is optional and may be omitted when implementing an + <list type="bulleted"> + <item><c>Module</c> is the application callback module as defined + by the <c>mod</c> key in the <c>.app</c> file.</item> + <item><c>Changed</c> and <c>New</c> are lists of <c>{Par,Val}</c> for + all changed and added configuration parameters, respectively.</item> + <item><c>Removed</c> is a list of all parameters <c>Par</c> that have + been removed.</item> + </list> + <p>The function is optional and can be omitted when implementing an application callback module.</p> </section> </chapter> |