From ae1c361f797a104a35aef967cc694b457217f488 Mon Sep 17 00:00:00 2001
From: Siri Hansen <siri@erlang.org>
Date: Thu, 3 Nov 2011 15:01:11 +0100
Subject: Add documentation for upgrade from pre R15 to post R15 sasl

---
 lib/sasl/doc/src/systools.xml                   |  5 +++++
 system/doc/design_principles/appup_cookbook.xml | 18 ++++++++++++++++++
 2 files changed, 23 insertions(+)

diff --git a/lib/sasl/doc/src/systools.xml b/lib/sasl/doc/src/systools.xml
index 8c1c327d74..fa2fcbf534 100644
--- a/lib/sasl/doc/src/systools.xml
+++ b/lib/sasl/doc/src/systools.xml
@@ -111,6 +111,11 @@
           low-level instruction to restart the emulator is appended to
           the relup scripts. This ensures that a complete reboot of
           the system is done when the system is upgraded or downgraded.</p>
+	<p>If an upgrade includes a change from an emulator earlier
+	  than OTP R15 to OTP R15 or later, the warning
+	  <c>pre_R15_emulator_upgrade</c> is issued. See <seealso
+	  marker="doc/design_principles:appup_cookbook">Design
+	  Principles</seealso> for more information about this.</p>
         <p>By default, errors and warnings are printed to tty and
           the function returns <c>ok</c> or <c>error</c>. If the option
           <c>silent</c> is provided, the function instead returns
diff --git a/system/doc/design_principles/appup_cookbook.xml b/system/doc/design_principles/appup_cookbook.xml
index eebe6ba7b4..798b23d847 100644
--- a/system/doc/design_principles/appup_cookbook.xml
+++ b/system/doc/design_principles/appup_cookbook.xml
@@ -640,5 +640,23 @@ code_change(_OldVsn, State, port) ->
       updates etc. can be used without having to specify <c>.appup</c>
       files.</p>
   </section>
+
+  <section>
+    <title>Emulator Upgrade from pre OTP R15</title>
+    <p>From OTP R15, an emulator upgrade is performed by restarting
+    the emulator with new versions of the core applications
+    (<c>kernel</c>, <c>stdlib</c> and <c>sasl</c>) before loading code
+    and running upgrade instruction for other applications. For this
+    to work, the release to upgrade from must includes OTP R15 or
+    later. For the case where the release to upgrade from includes an
+    earlier emulator version, <c>systools:make_relup</c> will create a
+    backwards compatible relup file. This means that all upgrade
+    instructions will be executed before the emulator is
+    restarted. The new application code will therefore be loaded into
+    the old emulator. If the new code is compiled with the new
+    emulator, there might be cases where the beam format has changed
+    and beam files can not be loaded. To overcome this problem, the
+    new code should be compiled with the old emulator.</p>
+  </section>
 </chapter>
 
-- 
cgit v1.2.3