aboutsummaryrefslogtreecommitdiffstats
path: root/lib/sasl/doc/src
diff options
context:
space:
mode:
authorSiri Hansen <[email protected]>2011-11-18 14:55:40 +0100
committerSiri Hansen <[email protected]>2011-11-18 14:55:40 +0100
commit405322cc25ae4343ec824c2d611553534d1b1b92 (patch)
tree8e58b80de7fa8585261fa9315c141a49d21f2177 /lib/sasl/doc/src
parent6e024b633005fa53ff67d0222b42d983f8ea85f8 (diff)
parentcc7c2a74ee9074357f6ab0701be61e7bb57004ef (diff)
downloadotp-405322cc25ae4343ec824c2d611553534d1b1b92.tar.gz
otp-405322cc25ae4343ec824c2d611553534d1b1b92.tar.bz2
otp-405322cc25ae4343ec824c2d611553534d1b1b92.zip
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
Diffstat (limited to 'lib/sasl/doc/src')
-rw-r--r--lib/sasl/doc/src/appup.xml37
-rw-r--r--lib/sasl/doc/src/release_handler.xml28
-rw-r--r--lib/sasl/doc/src/systools.xml5
3 files changed, 61 insertions, 9 deletions
diff --git a/lib/sasl/doc/src/appup.xml b/lib/sasl/doc/src/appup.xml
index 89bcf23b5e..195f9fe1d3 100644
--- a/lib/sasl/doc/src/appup.xml
+++ b/lib/sasl/doc/src/appup.xml
@@ -319,12 +319,37 @@ point_of_no_return
<pre>
restart_new_emulator
</pre>
- <p>Shuts down the current emulator and starts a ne one. All
- processes are terminated gracefully. The new release must still
- be made permanent when the new emulator is up and running.
- Otherwise, the old emulator is started in case of a emulator
- restart. This instruction should be used when a new emulator is
- introduced, or if a complete reboot of the system should be done.</p>
+ <p>This instruction is used when erts, kernel, stdlib or sasl is
+ upgraded. It shuts down the current emulator and starts a new
+ one. All processes are terminated gracefully, and the new
+ version of erts, kernel, stdlib and sasl are used when the
+ emulator restarts. Only one <c>restart_new_emulator</c>
+ instruction is allowed in the relup, and it shall be placed
+ first. <seealso marker="systools#make_relup/3">systools:make_relup3,4</seealso>
+ will ensure this when the relup is generated. The rest of the
+ relup script is executed after the restart as a part of the boot
+ script.</p>
+ <p>An info report will be written when the upgrade is
+ completed. To programatically find out if the upgrade is
+ complete,
+ call <seealso marker="release_handler#which_release/0">
+ release_handler:which_releases</seealso> and check if the
+ expected release has status <c>current</c>.</p>
+ <p>The new release must still be made permanent after the upgrade
+ is completed. Otherwise, the old emulator is started in case of
+ an emulator restart.</p>
+ <pre>
+restart_emulator
+ </pre>
+ <p>This instruction is similar to <c>restart_new_emulator</c>,
+ except it shall be placed at the end of the relup script. It is
+ not related to an upgrade of the emulator or the core
+ applications, but can be used by any application when a complete
+ reboot of the system is reqiured. When generating the
+ relup, <seealso marker="systools#make_relup/3">systools:make_relup/3,4</seealso>
+ ensures that there is only one <c>restart_emulator</c>
+ instruction and that it is the last instruction of the
+ relup.</p>
</section>
<section>
diff --git a/lib/sasl/doc/src/release_handler.xml b/lib/sasl/doc/src/release_handler.xml
index cf05b1a67d..7f32100d4b 100644
--- a/lib/sasl/doc/src/release_handler.xml
+++ b/lib/sasl/doc/src/release_handler.xml
@@ -238,7 +238,7 @@ old reboot_old permanent
</func>
<func>
<name>install_release(Vsn) -> {ok, OtherVsn, Descr} | {error, Reason}</name>
- <name>install_release(Vsn, [Opt]) -> {ok, OtherVsn, Descr} | {error, Reason}</name>
+ <name>install_release(Vsn, [Opt]) -> {ok, OtherVsn, Descr} | {continue_after_restart, OtherVsn, Descr} | {error, Reason}</name>
<fsummary>Install a release in the system.</fsummary>
<type>
<v>Vsn = OtherVsn = string()</v>
@@ -248,7 +248,8 @@ old reboot_old permanent
<v>&nbsp;Timeout = default | infinity | int()>0</v>
<v>&nbsp;Bool = boolean()</v>
<v>Descr = term()</v>
- <v>Reason = {illegal_option, Opt} | {already_installed, Vsn} | {change_appl_data, term()} | term()</v>
+ <v>Reason = {illegal_option, Opt} | {already_installed, Vsn} | {change_appl_data, term()} | {missing_base_app, OtherVsn, App} | {could_not_create_hybrid_boot, term()} | term()</v>
+ <v>App = atom()</v>
</type>
<desc>
<p>Installs the specified version <c>Vsn</c> of the release.
@@ -268,6 +269,15 @@ old reboot_old permanent
<c>OtherVsn</c> and <c>Descr</c> are the version
(<c>UpFromVsn</c> or <c>Vsn</c>) and description
(<c>Descr1</c> or <c>Descr2</c>) as specified in the script.</p>
+ <p>If <c>{continue_after_restart,OtherVsn,Descr}</c> is
+ returned, it means that the emulator will be restarted
+ before the upgrade instructions are executed. This will
+ happen if the emulator or any of the applications kernel,
+ stdlib or sasl are updated. The new version of the emulator
+ and these core applications will execute after the restart,
+ but for all other applications the old versions will be
+ started and the upgrade will be performed as normal by
+ executing the upgrade instructions.</p>
<p>If a recoverable error occurs, the function returns
<c>{error,Reason}</c> and the original application
specifications are restored. If a non-recoverable error
@@ -325,6 +335,18 @@ release_handler:set_unpacked(RelFile, [{myapp,"1.0","/home/user"},...]).
upgrade, but it will allow checks and purge to be executed
in the background before the real upgrade is started.</p>
</note>
+ <note>
+ <p>When upgrading the emulator from a version older than OTP
+ R15, there will be an attempt to load new application beam
+ code into the old emulator. In some cases, the new beam
+ format can not be read by the old emulator, and so the code
+ loading will fail and terminate the complete upgrade. To
+ overcome this problem, the new application code should be
+ compiled with the old emulator. See <seealso
+ marker="doc/design_principles:appup_cookbook">Design
+ Principles</seealso> for more information about emulator
+ upgrade from pre OTP R15 versions.</p>
+ </note>
</desc>
</func>
<func>
@@ -454,7 +476,7 @@ release_handler:set_unpacked(RelFile, [{myapp,"1.0","/home/user"},...]).
and evaluated exactly in the same way as <c>release_handler</c>
does.</p>
<warning>
- <p>These function is primarily intended for simplified testing of
+ <p>These functions are primarily intended for simplified testing
of <c>.appup</c> files. They are not run within the context of
the <c>release_handler</c> process. They must therefore
<em>not</em> be used together with calls to
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