Merge branch 'siri/sasl/upgrade-erts/OTP-9438'

* siri/sasl/upgrade-erts/OTP-9438:
  Fix bug in erts upgrade on windows
  Add release vsn info to erts_vsn_changed warning
  Check for sasl application in systools:make_script and make_relup
  Add syntax check of relup to check_install_release and install_release
  Add documentation for upgrade from pre R15 to post R15 sasl
  Handle upgrade from pre R15 to post R15 sasl
  Step version of sasl to 2.2 for R15
  Document upgrade instructions restart_new_emulator and restart_emulator
  Wait for two restarts in upgrade_restart test
  Add restart_new_emulator instruction to kernel, stdlib and sasl appups
  Distinguish restart_new_emulator from restart_emulator in upgrade instructions
  Upgrade erts: merge sys.config for tmp release instead of using old
  Allow regexp for version in .appup
  Restart emulator before running upgrade script when erts is upgraded

Conflicts:
	lib/sasl/src/release_handler.erl
	lib/sasl/test/release_handler_SUITE.erl

2 files changed, 92 insertions, 21 deletions

diff --git a/system/doc/design_principles/appup_cookbook.xml b/system/doc/design_principles/appup_cookbook.xml
index bc61578953..798b23d847 100644
--- a/system/doc/design_principles/appup_cookbook.xml
+++ b/system/doc/design_principles/appup_cookbook.xml
@@ -4,7 +4,7 @@
 <chapter>
   <header>
     <copyright>
-      <year>2003</year><year>2009</year>
+      <year>2003</year><year>2011</year>
       <holder>Ericsson AB. All Rights Reserved.</holder>
     </copyright>
     <legalnotice>
@@ -603,25 +603,60 @@ code_change(_OldVsn, State, port) ->
   </section>
 
   <section>
-    <title>Emulator Restart</title>
-    <p>If the emulator can or should be restarted, the very simple
-      <c>.relup</c> file can be created manually:</p>
+    <title>Emulator Restart and Upgrade</title>
+    <p>There are two upgrade instructions that will restart the emulator:</p>
+    <taglist>
+      <tag><c>restart_new_emulator</c></tag>
+      <item>Intended for when erts, kernel, stdlib or sasl is
+        upgraded. It is automatically added when the relup file is
+        generated by <c>systools:make_relup/3,4</c>. It is executed
+        before all other upgrade instructions. See
+        <seealso marker="release_handling#restart_new_emulator_instr">Release
+        Handling</seealso> for more information about this
+        instruction.</item>
+      <tag><c>restart_emulator</c></tag>
+      <item>Used when a restart of the emulator is required after all
+        other upgrade instructions are executed. See
+        <seealso marker="release_handling#restart_emulator_instr">Release
+        Handling</seealso> for more information about this
+        instruction.</item>
+    </taglist>
+
+    <p>If an emulator restart is necessary and no upgrade instructions
+      are needed, i.e. if the restart itself is enough for the
+      upgraded applications to start running the new versions, a very
+      simple <c>.relup</c> file can be created manually:</p>
     <code type="none">
 {"B",
  [{"A",
    [],
-   [restart_new_emulator]}],
+   [restart_emulator]}],
  [{"A",
    [],
-   [restart_new_emulator]}]
+   [restart_emulator]}]
 }.</code>
-    <p>This way, the release handler framework with automatic packing
-      and unpacking of release packages, automatic path updates etc. can
-      be used without having to specify <c>.appup</c> files.</p>
-    <p>If some transformation of persistent data, for example database
-      contents, needs to be done before installing the new release
-      version, instructions for this can be added to the <c>.relup</c>
-      file as well.</p>
+    <p>In this case, the release handler framework with automatic
+      packing and unpacking of release packages, automatic path
+      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>
 
diff --git a/system/doc/design_principles/release_handling.xml b/system/doc/design_principles/release_handling.xml
index 1d62c242c0..8ed36f3c56 100644
--- a/system/doc/design_principles/release_handling.xml
+++ b/system/doc/design_principles/release_handling.xml
@@ -4,7 +4,7 @@
 <chapter>
   <header>
     <copyright>
-      <year>2003</year><year>2009</year>
+      <year>2003</year><year>2011</year>
       <holder>Ericsson AB. All Rights Reserved.</holder>
     </copyright>
     <legalnotice>
@@ -313,18 +313,35 @@
     </section>
 
     <section>
+      <marker id="restart_new_emulator_instr"></marker>
       <title>restart_new_emulator (low-level)</title>
       <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
+        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>When the release handler encounters the instruction, it shuts
-        down the current emulator by calling <c>init:reboot()</c>, see
+      <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
+        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. 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 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>
+        the temporary boot file. After the reboot, the rest of the
+        relup instructions are executed. This is done as a part of the
+        boot script.</p>
+      <p>An info report is written when the upgrade is completed. To
+        programatically find out if the upgrade is complete,
+        call <c>release_handler:which_releases/0</c> and check if the
+        expected release has status <c>current</c>.</p>
+      <p>The new 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
@@ -333,6 +350,25 @@
         by using the SASL configuration parameter <c>start_prg</c>, see
         <c>sasl(6)</c>.</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
+        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
+	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
+        executed after the restart.</p>
+    </section>
   </section>
 
   <section>