aboutsummaryrefslogtreecommitdiffstats
path: root/system/doc/system_principles/upgrade.xml
diff options
context:
space:
mode:
authorSiri Hansen <[email protected]>2014-02-19 17:24:27 +0100
committerSiri Hansen <[email protected]>2014-04-03 12:17:52 +0200
commitc65821b677b4ebbc05192da9b8a48d32e53b3cfe (patch)
tree863ccc36f0f3d93be0f6e5210a2088b7b8091726 /system/doc/system_principles/upgrade.xml
parent8eb20d1fb0eb3a3b96d5e80e2e2617f893ef6986 (diff)
downloadotp-c65821b677b4ebbc05192da9b8a48d32e53b3cfe.tar.gz
otp-c65821b677b4ebbc05192da9b8a48d32e53b3cfe.tar.bz2
otp-c65821b677b4ebbc05192da9b8a48d32e53b3cfe.zip
Add documentation about upgrade
The example of how to create a first target system, which is located in the System Principles document, is now extended to also include an example of code upgrade. A new chapter is added to System Principles explaining different issues when upgrade includes new versions applications within Erlang/OTP.
Diffstat (limited to 'system/doc/system_principles/upgrade.xml')
-rw-r--r--system/doc/system_principles/upgrade.xml118
1 files changed, 118 insertions, 0 deletions
diff --git a/system/doc/system_principles/upgrade.xml b/system/doc/system_principles/upgrade.xml
new file mode 100644
index 0000000000..68e48da0b8
--- /dev/null
+++ b/system/doc/system_principles/upgrade.xml
@@ -0,0 +1,118 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE chapter SYSTEM "chapter.dtd">
+
+<chapter>
+ <header>
+ <copyright>
+ <year>2014</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>Upgrade when Erlang/OTP has Changed</title>
+ <prepared></prepared>
+ <responsible></responsible>
+ <docno></docno>
+ <approved></approved>
+ <checked></checked>
+ <date>2014-02-19</date>
+ <rev></rev>
+ <file>upgrade.xml</file>
+ </header>
+
+ <section>
+ <title>Introduction</title>
+ <p>
+ As of Erlang/OTP 17, most applications deliver a valid
+ application upgrade (<c>appup</c>) file. In earlier releases, a
+ majority of the applications in Erlang/OTP did not support
+ upgrade at all. Many of the applications use the
+ <c>restart_application</c> instruction. These are applications
+ for which it is not crucial to support real soft upgrade, for
+ instance tools and library applications. The
+ <c>restart_application</c> instruction
+ ensures that all modules in the application are reloaded and
+ thereby running the new code.
+ </p>
+ </section>
+
+ <section>
+ <title>Upgrade of core applications</title>
+ <p>
+ The core applications ERTS, Kernel, STDLIB
+ and SASL never allow real soft upgrade, but require the
+ Erlang emulator to be restarted. This is indicated to the
+ <c>release_handler</c> by the upgrade instruction
+ <c>restart_new_emulator</c>. This instruction will always be the
+ very first instruction executed, and it will restart the
+ emulator with the new versions of the above mentioned core
+ applications and the old versions of all other
+ applications. When the node is back up all other upgrade instructions are
+ executed, making sure each application is finally running its
+ new version.
+ </p>
+
+ <p>
+ It might seem strange to do a two-step upgrade instead of
+ just restarting the emulator with the new version of all
+ applications. The reason for this design decision is to allow
+ <c>code_change</c> functions to have side effects, for example changing
+ data on disk. It also makes sure that the upgrade mechanism for
+ non-core applications does not differ depending on whether or not
+ core applications are changed at the same time.
+ </p>
+
+ <p>
+ If, however, the more brutal variant is preferred, it is
+ possible to handwrite the release upgrade file using only the
+ single upgrade instruction <c>restart_emulator</c>. This
+ instruction, in contrast to <c>restart_new_emulator</c>, will
+ cause the emulator to restart with the new versions of
+ <em>all</em> applications.
+ </p>
+
+ <p>
+ <em>Note</em> that if other instructions are included before
+ <c>restart_emulator</c> in the handwritten <c>relup</c> file,
+ they will be executed in the old emulator. This is a big risk
+ since there is no guarantee that new beam code can be loaded
+ into the old emulator. Adding instructions after
+ <c>restart_emulator</c> has no effect as the
+ <c>release_handler</c> will not do any attempt at executing
+ them.
+ </p>
+
+ <p>
+ See <seealso marker="sasl:relup">relup(4)</seealso> for
+ information about the release upgrade file, and <seealso
+ marker="sasl:appup">appup(4)</seealso> for further information
+ about upgrade instructions.
+ </p>
+ </section>
+
+ <section>
+ <title>Applications that still do not allow code upgrade</title>
+ <p>
+ A few applications, for instance HiPE do not support
+ upgrade at all. This is indicated by an application upgrade file
+ containing only <c>{Vsn,[],[]}</c>. Any attempt at creating a release
+ upgrade file with such input will fail.
+ The only way to force an upgrade involving applications like this is to
+ handwrite the <c>relup</c> file, preferably as described above
+ with only the <c>restart_emulator</c> instruction.
+ </p>
+
+ </section>
+</chapter>