1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
|
<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE chapter SYSTEM "chapter.dtd">
<chapter>
<header>
<copyright>
<year>2014</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
The contents of this file are subject to the Erlang Public License,
Version 1.1, (the "License"); you may not use this file except in
compliance with the License. You should have received a copy of the
Erlang Public License along with this software. If not, it can be
retrieved online at http://www.erlang.org/.
Software distributed under the License is distributed on an "AS IS"
basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
the License for the specific language governing rights and limitations
under the License.
</legalnotice>
<title>Upgrade when Erlang/OTP has Changed</title>
<prepared></prepared>
<responsible></responsible>
<docno></docno>
<approved></approved>
<checked></checked>
<date>2014-02-19</date>
<rev></rev>
<file>upgrade.xml</file>
</header>
<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
majority of the applications in Erlang/OTP did not support
upgrade at all. 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
<c>restart_application</c> instruction
ensures that all modules in the application are reloaded and
thereby running the new code.
</p>
</section>
<section>
<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
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
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
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
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
<c>restart_emulator</c> in the handwritten <c>relup</c> file,
they will be 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>
</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>
</section>
</chapter>
|
