1appup(5)                             Files                            appup(5)
2
3
4

NAME

6       appup - Application upgrade file
7

DESCRIPTION

9       The  application upgrade file defines how an application is upgraded or
10       downgraded in a running system.
11
12       This file is used by  the  functions  in  systools  when  generating  a
13       release upgrade file relup.
14

FILE SYNTAX

16       The  application  upgrade file is to be called Application.appup, where
17       Application is the application name. The file is to be located  in  the
18       ebin directory for the application.
19
20       The  .appup  file  contains  one  single Erlang term, which defines the
21       instructions used to upgrade or downgrade the application. The file has
22       the following syntax:
23
24       {Vsn,
25         [{UpFromVsn, Instructions}, ...],
26         [{DownToVsn, Instructions}, ...]}.
27
28         Vsn = string():
29           Current application version.
30
31         UpFromVsn = string() | binary():
32           An  earlier application version to upgrade from. If it is a string,
33           it is interpreted as a specific version number. If it is a  binary,
34           it  is  interpreted as a regular expression that can match multiple
35           version numbers.
36
37         DownToVsn = string() | binary():
38           An earlier application version to downgrade to. If it is a  string,
39           it  is interpreted as a specific version number. If it is a binary,
40           it is interpreted as a regular expression that can  match  multiple
41           version numbers.
42
43         Instructions:
44           A  list  of  release  upgrade  instructions,  see  Release  Upgrade
45           Instructions. It is  recommended  to  use  high-level  instructions
46           only.  These are automatically translated to low-level instructions
47           by systools when creating the relup file.
48
49       To avoid duplication of upgrade instructions, it is allowed to use reg‐
50       ular expressions to specify UpFromVsn and DownToVsn. To be considered a
51       regular expression, the version  identifier  must  be  specified  as  a
52       binary. For example, the following match all versions 2.1.x, where x is
53       any number:
54
55       <<"2\\.1\\.[0-9]+">>
56
57       Notice that the regular expression  must  match  the  complete  version
58       string,  so  this  example  works  for, for example, 2.1.1, but not for
59       2.1.1.1.
60

RELEASE UPGRADE INSTRUCTIONS

62       Release upgrade instructions are interpreted  by  the  release  handler
63       when  an  upgrade  or  downgrade  is  made.  For more information about
64       release handling, see OTP Design Principles in System Documentation.
65
66       A process is said to use a module Mod if Mod is listed in  the  Modules
67       part of the child specification used to start the process, see supervi‐
68       sor(3). In the case of gen_event, an event manager process is  said  to
69       use Mod if Mod is an installed event handler.
70
71   High-Level Instructions
72       {update, Mod}
73       {update, Mod, supervisor}
74       {update, Mod, Change}
75       {update, Mod, DepMods}
76       {update, Mod, Change, DepMods}
77       {update, Mod, Change, PrePurge, PostPurge, DepMods}
78       {update, Mod, Timeout, Change, PrePurge, PostPurge, DepMods}
79       {update, Mod, ModType, Timeout, Change, PrePurge, PostPurge, DepMods}
80         Mod = atom()
81         ModType = static | dynamic
82         Timeout = int()>0 | default | infinity
83         Change = soft | {advanced,Extra}
84           Extra = term()
85         PrePurge = PostPurge = soft_purge | brutal_purge
86         DepMods = [Mod]
87
88       Synchronized code replacement of processes using module Mod.
89
90       All  those  processes  are  suspended using sys:suspend, the new module
91       version is loaded, and then the processes are resumed using sys:resume.
92
93         Change:
94           Defaults to soft and defines the type of code change. If it is  set
95           to   {advanced,Extra},   implemented  processes  using  gen_server,
96           gen_fsm, gen_statem, or gen_event transform their internal state by
97           calling  the  callback function code_change. Special processes call
98           the callback function system_code_change/4. In both cases, the term
99           Extra is passed as an argument to the callback function.
100
101         PrePurge:
102           Defaults to brutal_purge. It controls what action to take with pro‐
103           cesses executing old code before loading the new module version. If
104           the  value  is brutal_purge, the processes are killed. If the value
105           is    soft_purge,     release_handler:install_release/1     returns
106           {error,{old_processes,Mod}}.
107
108         PostPurge:
109           Defaults to brutal_purge. It controls what action to take with pro‐
110           cesses that are executing old code when the new module version  has
111           been  loaded. If the value is brutal_purge, the code is purged when
112           the release is made permanent and the processes are killed. If  the
113           value  is  soft_purge, the release handler purges the old code when
114           no remaining processes execute the code.
115
116         DepMods:
117           Defaults to [] and defines other modules that Mod is dependent  on.
118           In  the relup file, instructions for suspending processes using Mod
119           come before instructions for suspending processes using modules  in
120           DepMods when upgrading, and conversely when downgrading. In case of
121           circular dependencies, the order of the instructions in  the  appup
122           file is kept.
123
124         Timeout:
125           Defines  the  time-out  when  suspending  processes. If no value or
126           default is specified, the default value for sys:suspend is used.
127
128         ModType:
129           Defaults to dynamic. It specifies if the code  is  "dynamic",  that
130           is,  if  a  process  using the module spontaneously switches to new
131           code, or if it is "static".  When  doing  an  advanced  update  and
132           upgrade,  the  new version of a dynamic module is loaded before the
133           process is asked to change code. When downgrading, the  process  is
134           asked  to  change  code  before loading the new version. For static
135           modules, the new version is loaded before the process is  asked  to
136           change  code,  both in the case of upgrading and downgrading. Call‐
137           back modules are dynamic.
138
139       update with argument supervisor is used when changing the start  speci‐
140       fication of a supervisor.
141
142       {load_module, Mod}
143       {load_module, Mod, DepMods}
144       {load_module, Mod, PrePurge, PostPurge, DepMods}
145         Mod = atom()
146         PrePurge = PostPurge = soft_purge | brutal_purge
147         DepMods = [Mod]
148
149       Simple code replacement of the module Mod.
150
151       For a description of PrePurge and PostPurge, see update above.
152
153       DepMods defaults to [] and defines which other modules Mod is dependent
154       on. In the relup file, instructions  for  loading  these  modules  come
155       before  the  instruction for loading Mod when upgrading, and conversely
156       when downgrading.
157
158       {add_module, Mod}
159       {add_module, Mod, DepMods}
160         Mod = atom()
161         DepMods = [Mod]
162
163       Loads a new module Mod.
164
165       DepMods defaults to [] and defines which other modules Mod is dependent
166       on.  In  the  relup  file,  instructions  related to these modules come
167       before the instruction for loading Mod when upgrading,  and  conversely
168       when downgrading.
169
170       {delete_module, Mod}
171       {delete_module, Mod, DepMods}
172         Mod = atom()
173
174       Deletes a module Mod using the low-level instructions remove and purge.
175
176       DepMods defaults to [] and defines which other modules Mod is dependent
177       on. In the relup file,  instructions  related  to  these  modules  come
178       before  the instruction for removing Mod when upgrading, and conversely
179       when downgrading.
180
181       {add_application, Application}
182       {add_application, Application, Type}
183         Application = atom()
184         Type = permanent | transient | temporary | load | none
185
186       Adding an application means that the modules defined by the modules key
187       in the .app file are loaded using add_module.
188
189       Type defaults to permanent and specifies the start type of the applica‐
190       tion. If Type = permanent | transient | temporary, the  application  is
191       loaded  and  started  in  the corresponding way, see application(3). If
192       Type = load, the application is only loaded. If Type = none, the appli‐
193       cation is not loaded and not started, although the code for its modules
194       is loaded.
195
196       {remove_application, Application}
197         Application = atom()
198
199       Removing an application means that the application is stopped, the mod‐
200       ules  are unloaded using delete_module, and then the application speci‐
201       fication is unloaded from the application controller.
202
203       {restart_application, Application}
204         Application = atom()
205
206       Restarting an application means that the  application  is  stopped  and
207       then  started  again, similar to using the instructions remove_applica‐
208       tion and add_application in sequence. Note that, even if  the  applica‐
209       tion  has  been  started  before  the  release  upgrade  is  performed,
210       restart_application may only load it rather than start it, depending on
211       the  application's  start type: If Type = load, the application is only
212       loaded. If Type = none, the application is not loaded and not  started,
213       although the code for its modules is loaded.
214
215   Low-Level Instructions
216       {load_object_code, {App, Vsn, [Mod]}}
217         App = Mod = atom()
218         Vsn = string()
219
220       Reads  each  Mod  from  directory App-Vsn/ebin as a binary. It does not
221       load the modules. The instruction is to be placed first in  the  script
222       to  read  all  new  code  from the file to make the suspend-load-resume
223       cycle less time-consuming.
224
225       point_of_no_return
226
227       If a crash occurs after this instruction, the system cannot recover and
228       is  restarted  from  the old release version. The instruction must only
229       occur once in a script. It is to be placed after  all  load_object_code
230       instructions.
231
232       {load, {Mod, PrePurge, PostPurge}}
233         Mod = atom()
234         PrePurge = PostPurge = soft_purge | brutal_purge
235
236       Before  this  instruction  occurs,  Mod  must  have  been  loaded using
237       load_object_code.  This  instruction  loads  the  module.  PrePurge  is
238       ignored. For a description of PostPurge, see the high-level instruction
239       update earlier.
240
241       {remove, {Mod, PrePurge, PostPurge}}
242         Mod = atom()
243         PrePurge = PostPurge = soft_purge | brutal_purge
244
245       Makes the current version of  Mod  old.  PrePurge  is  ignored.  For  a
246       description  of  PostPurge,  see the high-level instruction update ear‐
247       lier.
248
249       {purge, [Mod]}
250         Mod = atom()
251
252       Purges each module Mod, that is, removes the old code. Notice that  any
253       process executing purged code is killed.
254
255       {suspend, [Mod | {Mod, Timeout}]}
256         Mod = atom()
257         Timeout = int()>0 | default | infinity
258
259       Tries  to  suspend  all processes using a module Mod. If a process does
260       not respond, it is ignored. This can cause the process to  die,  either
261       because  it crashes when it spontaneously switches to new code, or as a
262       result of a purge operation. If no Timeout is specified or  default  is
263       specified, the default value for sys:suspend is used.
264
265       {resume, [Mod]}
266         Mod = atom()
267
268       Resumes all suspended processes using a module Mod.
269
270       {code_change, [{Mod, Extra}]}
271       {code_change, Mode, [{Mod, Extra}]}
272         Mod = atom()
273         Mode = up | down
274         Extra = term()
275
276       Mode  defaults  to  up  and specifies if it is an upgrade or downgrade.
277       This instruction sends a code_change system message  to  all  processes
278       using  a  module  Mod by calling function sys:change_code, passing term
279       Extra as argument.
280
281       {stop, [Mod]}
282         Mod = atom()
283
284       Stops all processes using a module  Mod  by  calling  supervisor:termi‐
285       nate_child/2.  This  instruction  is  useful  when  the simplest way to
286       change code is to stop and restart the processes that run the code.
287
288       {start, [Mod]}
289         Mod = atom()
290
291       Starts all stopped processes using a module  Mod  by  calling  supervi‐
292       sor:restart_child/2.
293
294       {sync_nodes, Id, [Node]}
295       {sync_nodes, Id, {M, F, A}}
296         Id = term()
297         Node = node()
298         M = F = atom()
299         A = [term()]
300
301       apply(M, F, A) must return a list of nodes.
302
303       This  instruction  synchronizes  the  release  installation  with other
304       nodes. Each Node must evaluate this command with the same Id. The local
305       node  waits for all other nodes to evaluate the instruction before exe‐
306       cution continues. If a node goes down, it is considered to be an  unre‐
307       coverable  error, and the local node is restarted from the old release.
308       There is no time-out for this instruction, which means that it can hang
309       forever.
310
311       {apply, {M, F, A}}
312         M = F = atom()
313         A = [term()]
314
315       Evaluates apply(M, F, A).
316
317       If  the  instruction  appears  before instruction point_of_no_return, a
318       failure  is  caught.  release_handler:install_release/1  then   returns
319       {error,{'EXIT',Reason}},  unless  {error,Error}  is thrown or returned.
320       Then it returns {error,Error}.
321
322       If the instruction appears after instruction point_of_no_return and the
323       function call fails, the system is restarted.
324
325       restart_new_emulator
326
327       This  instruction is used when the application ERTS, Kernel, STDLIB, or
328       SASL is upgraded. It shuts down the current emulator and starts  a  new
329       one.  All  processes  are terminated gracefully, and the new version of
330       ERTS, Kernel, STDLIB, and SASL are used  when  the  emulator  restarts.
331       Only one restart_new_emulator instruction is allowed in the relup file,
332       and it must be placed first. systools:make_relup/3,4 ensures this  when
333       the  relup file is generated. The rest of the instructions in the relup
334       file is executed after the restart as a part of the boot script.
335
336       An info report is written when the upgrade is completed. To programmat‐
337       ically   determine  if  the  upgrade  is  complete,  call  release_han‐
338       dler:which_releases/0,1 and check if the expected  release  has  status
339       current.
340
341       The  new release must still be made permanent after the upgrade is com‐
342       pleted, otherwise the old emulator is started if there is  an  emulator
343       restart.
344
345   Warning:
346       As stated earlier, instruction restart_new_emulator causes the emulator
347       to be restarted with new versions of ERTS>, Kernel, STDLIB,  and  SASL.
348       However, all other applications do at startup run their old versions in
349       this new emulator. This is usually no problem, but every now  and  then
350       incompatible  changes  occur  to the core applications, which can cause
351       trouble in this setting. Such incompatible changes (when functions  are
352       removed)  are  normally  preceded  by  a  deprecation  over  two  major
353       releases. To ensure that your application is not crashed by  an  incom‐
354       patible  change, always remove any call to deprecated functions as soon
355       as possible.
356
357
358       restart_emulator
359
360       This instruction is similar to restart_new_emulator, except it must  be
361       placed at the end of the relup file. It is not related to an upgrade of
362       the emulator or the core applications, but can be used by any  applica‐
363       tion when a complete reboot of the system is required.
364
365       When  generating  the  relup file, systools:make_relup/3,4 ensures that
366       there is only one restart_emulator instruction and that it is the  last
367       instruction in the relup file.
368

SEE ALSO

370       release_handler(3), relup(4), supervisor(3), systools(3)
371
372
373
374Ericsson AB                       sasl 4.0.2                          appup(5)
Impressum