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.

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>