aboutsummaryrefslogtreecommitdiffstats
path: root/system/doc/system_principles/upgrade.xml
diff options
context:
space:
mode:
authorHans Bolinder <[email protected]>2015-03-12 15:35:13 +0100
committerBjörn Gustavsson <[email protected]>2015-03-12 17:42:20 +0100
commit0c20078ff0fbad9066c8dd4ebcd6faa0b4f31b42 (patch)
tree379988f5ea4bf36e144c59fa122175badb0df7f1 /system/doc/system_principles/upgrade.xml
parent9fe8adf35c16ab5d4566b03f3b36863c90b5b6dd (diff)
downloadotp-0c20078ff0fbad9066c8dd4ebcd6faa0b4f31b42.tar.gz
otp-0c20078ff0fbad9066c8dd4ebcd6faa0b4f31b42.tar.bz2
otp-0c20078ff0fbad9066c8dd4ebcd6faa0b4f31b42.zip
Update System Principles
Language cleaned up by the technical writers xsipewe and tmanevik from Combitech. Proofreading and corrections by Hans Bolinder.
Diffstat (limited to 'system/doc/system_principles/upgrade.xml')
-rw-r--r--system/doc/system_principles/upgrade.xml98
1 files changed, 41 insertions, 57 deletions
diff --git a/system/doc/system_principles/upgrade.xml b/system/doc/system_principles/upgrade.xml
index 68e48da0b8..83e8128f94 100644
--- a/system/doc/system_principles/upgrade.xml
+++ b/system/doc/system_principles/upgrade.xml
@@ -31,88 +31,72 @@
<rev></rev>
<file>upgrade.xml</file>
</header>
+ <marker id="upgrade section"></marker>
<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
+ <marker id="upgrade"></marker>
+ <p>As of Erlang/OTP 17, most applications deliver a valid
+ application upgrade file (<c>appup</c>). In earlier releases, a
majority of the applications in Erlang/OTP did not support
- upgrade at all. Many of the applications use the
+ upgrade. 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
+ example, 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>
+ thereby running the new code.</p>
</section>
<section>
- <title>Upgrade of core applications</title>
- <p>
- The core applications ERTS, Kernel, STDLIB
+ <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
+ <c>restart_new_emulator</c>. This instruction is always the
+ very first instruction executed, and it restarts 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
+ 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
+ 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
+ <c>code_change</c> functions to have side effects, for example,
+ changing data on disk. It also guarantees 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, the
+ the release upgrade file can be handwritten 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
+ instruction, in contrast to <c>restart_new_emulator</c>,
+ causes the emulator to restart with the new versions of
+ <em>all</em> applications.</p>
+ <p><em>Note:</em> 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
+ they are 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>
+ <c>release_handler</c> will not execute them.</p>
+ <p>For information about the release upgrade file, see the
+ <seealso marker="sasl:relup">relup(4)</seealso> manual page
+ in SASL.
+ For more information about upgrade instructions, see the
+ <seealso marker="sasl:appup">appup(4)</seealso> manual page
+ in SASL.</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>
-
+ <title>Applications that Still do Not Allow Code Upgrade</title>
+ <p>A few applications, such as HiPE, do not support upgrade.
+ This is indicated by an application upgrade file containing only
+ <c>{Vsn,[],[]}</c>. Any attempt at creating a release upgrade file
+ with such input fails. The only way to force an upgrade involving
+ applications like this is to
+ handwrite the file <c>relup</c>, preferably as described above
+ with only the <c>restart_emulator</c> instruction.</p>
</section>
</chapter>