From 281fb9929e2cdcfdaf95e0b90b3b690b78535ddb Mon Sep 17 00:00:00 2001
From: Siri Hansen
Date: Mon, 24 Oct 2011 14:25:15 +0200
Subject: Document upgrade instructions restart_new_emulator and
restart_emulator
---
lib/sasl/doc/src/appup.xml | 37 ++++++++++++++++++++++++++++++------
lib/sasl/doc/src/release_handler.xml | 16 +++++++++++++---
2 files changed, 44 insertions(+), 9 deletions(-)
(limited to 'lib/sasl/doc/src')
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
restart_new_emulator
- 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.
+ 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 restart_new_emulator
+ instruction is allowed in the relup, and it shall be placed
+ first. systools:make_relup3,4
+ 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.
+ An info report will be written when the upgrade is
+ completed. To programatically find out if the upgrade is
+ complete,
+ call
+ release_handler:which_releases and check if the
+ expected release has status current.
+ 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.
+
+restart_emulator
+
+ This instruction is similar to restart_new_emulator,
+ 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, systools:make_relup/3,4
+ ensures that there is only one restart_emulator
+ instruction and that it is the last instruction of the
+ relup.
diff --git a/lib/sasl/doc/src/release_handler.xml b/lib/sasl/doc/src/release_handler.xml
index 5ac0dc1acc..c625b40c9d 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
install_release(Vsn) -> {ok, OtherVsn, Descr} | {error, Reason}
- install_release(Vsn, [Opt]) -> {ok, OtherVsn, Descr} | {error, Reason}
+ install_release(Vsn, [Opt]) -> {ok, OtherVsn, Descr} | {continue_after_restart, OtherVsn, Descr} | {error, Reason}
Install a release in the system.
Vsn = OtherVsn = string()
@@ -248,7 +248,8 @@ old reboot_old permanent
Timeout = default | infinity | int()>0
Bool = boolean()
Descr = term()
- Reason = {illegal_option, Opt} | {already_installed, Vsn} | {change_appl_data, term()} | term()
+ Reason = {illegal_option, Opt} | {already_installed, Vsn} | {change_appl_data, term()} | {missing_base_app, OtherVsn, App} | {could_not_create_hybrid_boot, term()} | term()
+ App = atom()
Installs the specified version Vsn of the release.
@@ -268,6 +269,15 @@ old reboot_old permanent
OtherVsn and Descr are the version
(UpFromVsn or Vsn) and description
(Descr1 or Descr2) as specified in the script.
+ If {continue_after_restart,OtherVsn,Descr} 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.
If a recoverable error occurs, the function returns
{error,Reason} and the original application
specifications are restored. If a non-recoverable error
@@ -442,7 +452,7 @@ release_handler:set_unpacked(RelFile, [{myapp,"1.0","/home/user"},...]).
and evaluated exactly in the same way as release_handler
does.
- These function is primarily intended for simplified testing of
+
These functions are primarily intended for simplified testing
of .appup files. They are not run within the context of
the release_handler process. They must therefore
not be used together with calls to
--
cgit v1.2.3
From aef75ca63752f65299e95c12b67870f1debea7ff Mon Sep 17 00:00:00 2001
From: Siri Hansen
Date: Tue, 1 Nov 2011 12:32:38 +0100
Subject: Handle upgrade from pre R15 to post R15 sasl
New emulator upgrade mechanism introduced in R15 can only work if the
sasl version to upgrade from is 2.2 or later. I.e. if we are already
running at least R15.
This commit adds backwards compatiblity for upgrades from earlier
versions, meaning that the new code is loaded into the old emulator
and code_change is executed - then after all application code is
updated, the emulator is restarted with the new erts version.
Note that this might cause problems if the new code is compiled with
the new emulator and there have been updates to the beam format. If
this happens, the workaround is to compile the new code with the old
emulator.
---
lib/sasl/doc/src/release_handler.xml | 12 ++++++++++++
1 file changed, 12 insertions(+)
(limited to 'lib/sasl/doc/src')
diff --git a/lib/sasl/doc/src/release_handler.xml b/lib/sasl/doc/src/release_handler.xml
index c625b40c9d..bd24b2d963 100644
--- a/lib/sasl/doc/src/release_handler.xml
+++ b/lib/sasl/doc/src/release_handler.xml
@@ -335,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.
+
+ 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 Design
+ Principles for more information about emulator
+ upgrade from pre OTP R15 versions.
+
--
cgit v1.2.3
From ae1c361f797a104a35aef967cc694b457217f488 Mon Sep 17 00:00:00 2001
From: Siri Hansen
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 +++++
1 file changed, 5 insertions(+)
(limited to 'lib/sasl/doc/src')
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.
+ If an upgrade includes a change from an emulator earlier
+ than OTP R15 to OTP R15 or later, the warning
+ pre_R15_emulator_upgrade is issued. See Design
+ Principles for more information about this.
By default, errors and warnings are printed to tty and
the function returns ok or error. If the option
silent is provided, the function instead returns
--
cgit v1.2.3