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
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<!-- This document was generated using DocBuilder 3.3.2 -->
<HTML>
<HEAD>
<TITLE>systools</TITLE>
<SCRIPT type="text/javascript" src="../../../../doc/erlresolvelinks.js">
</SCRIPT>
<STYLE TYPE="text/css">
<!--
.REFBODY { margin-left: 13mm }
.REFTYPES { margin-left: 8mm }
-->
</STYLE>
</HEAD>
<BODY BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" VLINK="#FF00FF"
ALINK="#FF0000">
<!-- refpage -->
<CENTER>
<A HREF="http://www.erlang.se">
<IMG BORDER=0 ALT="[Ericsson AB]" SRC="min_head.gif">
</A>
<H1>systools</H1>
</CENTER>
<H3>MODULE</H3>
<DIV CLASS=REFBODY>
systools
</DIV>
<H3>MODULE SUMMARY</H3>
<DIV CLASS=REFBODY>
A Set of Release Handling Tools.
</DIV>
<H3>DESCRIPTION</H3>
<DIV CLASS=REFBODY>
<P>This module contains functions to generate boot scripts
(<CODE>.boot</CODE>, <CODE>.script</CODE>), release upgrade scripts
(<CODE>relup</CODE>), and release packages.
</DIV>
<H3>EXPORTS</H3>
<P><A NAME="make_relup/3"><STRONG><CODE>make_relup(Name, UpFrom, DownTo) -> Result</CODE></STRONG></A><BR>
<A NAME="make_relup/4"><STRONG><CODE>make_relup(Name, UpFrom, DownTo, [Opt]) -> Result</CODE></STRONG></A><BR>
<DIV CLASS=REFBODY><P>Types:
<DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Name = string()</CODE></STRONG><BR>
<STRONG><CODE>UpFrom = DownTo = [Name | {Name,Descr}]</CODE></STRONG><BR>
<STRONG><CODE>Descr = term()</CODE></STRONG><BR>
<STRONG><CODE>Opt = {path,[Dir]} | restart_emulator | silent | noexec</CODE></STRONG><BR>
<STRONG><CODE>Dir = string()</CODE></STRONG><BR>
<STRONG><CODE>Result = ok | error | {ok,Relup,Module,Warnings} |
{error,Module,Error}</CODE></STRONG><BR>
<STRONG><CODE>Relup - see relup(4)</CODE></STRONG><BR>
<STRONG><CODE>Module = atom()</CODE></STRONG><BR>
<STRONG><CODE>Warnings = Error = term()</CODE></STRONG><BR>
</DIV>
</DIV>
<DIV CLASS=REFBODY>
<P>Generates a release upgrade file <CODE>relup</CODE> containing a
script which describes how to upgrade the system from a number
of previous releases, and how to downgrade to a number of
previous releases. The script is used by
<CODE>release_handler</CODE> when installing a new version of a
release in run-time.
<P>The release resource file <CODE>Name.rel</CODE> is compared with
all release resource files <CODE>Name2.rel</CODE> specified in
<CODE>UpFrom</CODE> and <CODE>DownTo</CODE>. For each such pair, it is
deducted:
<P>
<UL>
<LI>
Which applications should be deleted, that is
applications which are listed in <CODE>Name.rel</CODE> but not
in <CODE>Name2.rel</CODE>.<BR>
</LI>
<LI>
Which applications should be added, that is applications
which are listed in <CODE>Name2.rel</CODE> but not in
<CODE>Name.rel</CODE>.<BR>
</LI>
<LI>
Which applications should be upgraded/downgraded, that
is applications listed in both <CODE>Name.rel</CODE> and
<CODE>Name2.rel</CODE>, but with different versions.<BR>
</LI>
<LI>
If the emulator needs to be restarted after upgrading or
downgrading, that is if the ERTS version differs between
<CODE>Name.rel</CODE> and <CODE>Name2.rel</CODE>.<BR>
</LI>
</UL>
<P>Instructions for this are added to the <CODE>relup</CODE> script in
the above order. Instructions for upgrading or downgrading
between application versions are fetched from the relevant
application upgrade files <CODE>App.appup</CODE>, sorted in
the same order as when generating a boot script, see
<CODE>make_script/1,2</CODE>. High-level instructions are translated
into low-level instructions and the result is printed to
<CODE>relup</CODE> in the current working directory.
<P>The optional <CODE>Descr</CODE> parameter is included as-is in
the <CODE>relup</CODE> script, see <CODE>relup(4)</CODE>. Defaults to
the empty list.
<P>All the files are searched for in the code path. It is
assumed that the <CODE>.app</CODE> and <CODE>.appup</CODE> file for an
application is located in the same directory.
<P>If the option <CODE>{path,[Dir]}</CODE> is provided, this path is
appended to the current path. The wildcard <CODE>*</CODE> is
expanded to all matching directories.
Example: <CODE>lib/*/ebin</CODE>.
<P>If the <CODE>restart_emulator</CODE> option is supplied, a
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>By default, errors and warnings are printed to tty and
the function returns <CODE>ok</CODE> or <CODE>error</CODE>. If the option
<CODE>silent</CODE> is provided, the function instead returns
<CODE>{ok,Relup,Module,Warnings}</CODE> where <CODE>Relup</CODE> is
the release upgrade script, or it returns
<CODE>{error,Module,Error}</CODE>. Warnings and errors can be
converted to strings by calling
<CODE>Module:format_warning(Warnings)</CODE> or
<CODE>Module:format_error(Error)</CODE>.
<P>If the option <CODE>noexec</CODE> is provided, the function returns
the same values as for <CODE>silent</CODE> but no <CODE>relup</CODE> file
is created.
</DIV>
<P><A NAME="make_script/1"><STRONG><CODE>make_script(Name) -> Result</CODE></STRONG></A><BR>
<A NAME="make_script/2"><STRONG><CODE>make_script(Name, [Opt]) -> Result</CODE></STRONG></A><BR>
<DIV CLASS=REFBODY><P>Types:
<DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Name = string()</CODE></STRONG><BR>
<STRONG><CODE>Opt = no_module_tests | {path,[Dir]} | local
| {variables,[Var]} | exref | {exref,[App]}] | silent</CODE></STRONG><BR>
<STRONG><CODE>Dir = string()</CODE></STRONG><BR>
<STRONG><CODE>Var = {VarName,Prefix}</CODE></STRONG><BR>
<STRONG><CODE>VarName = Prefix = string()</CODE></STRONG><BR>
<STRONG><CODE>App = atom()</CODE></STRONG><BR>
<STRONG><CODE>Result = ok | error | {ok,Module,Warnings}
| {error,Module,Error}</CODE></STRONG><BR>
<STRONG><CODE>Module = atom()</CODE></STRONG><BR>
<STRONG><CODE>Warnings = Error = term()</CODE></STRONG><BR>
</DIV>
</DIV>
<DIV CLASS=REFBODY>
<P>Generates a boot script in a readable version
<CODE>Name.script</CODE> and a binary version <CODE>Name.boot</CODE>,
specifying which code should be loaded and which applications
should be started when the Erlang runtime system is started.
See <CODE>script(4)</CODE>.
<P>The release resource file <CODE>Name.rel</CODE> is read to find
out which applications are included in the release. Then
the relevant application resource files <CODE>App.app</CODE> are
read to find out which modules should be loaded and if and
how the application should be started. (Keys <CODE>modules</CODE>
and <CODE>mod</CODE>, see <CODE>app(4)</CODE>).
<P>The correctness of each application is checked:
<P>
<UL>
<LI>
The version of an application specified in
the <CODE>.rel</CODE> file should be the same as the version
specified in the <CODE>.app</CODE> file.<BR>
</LI>
<LI>
There should be no undefined applications, that is,
dependencies to applications which are not included in
the release. (Key <CODE>applications</CODE> in <CODE>.app</CODE>
file).
<BR>
</LI>
<LI>
There should be no circular dependencies among
the applications.<BR>
</LI>
<LI>
There should no duplicated modules, that is, modules with
the same name but belonging to different applications.<BR>
</LI>
<LI>
A warning is issued if the source code for a module is
missing or newer than the object code.<BR>
If the <CODE>no_module_tests</CODE> option is specified, this
check is omitted.<BR>
</LI>
</UL>
<P>The applications are sorted according to the dependencies
between the applications. Where there are no dependencies,
the order in the <CODE>.rel</CODE> file is kept. The resulting
boot script files are created in the current working
directory, or in the directory where <CODE>Name.rel</CODE> is
located if <CODE>Name</CODE> contains a path.
<P>All files are searched for in the current path. It is
assumed that the <CODE>.app</CODE> and <CODE>.beam</CODE> files for an
application is located in the same directory. The <CODE>.erl</CODE>
files are also assumed to be located in this directory, unless
it is an <CODE>ebin</CODE> directory in which case they may be
located in the corresponding <CODE>src</CODE> directory.
<P>If the option <CODE>{path,[Dir]}</CODE> is provided, this path is
appended to the current path. A directory in the path can be
given with a wildcard <CODE>*</CODE>, this is expanded to all
matching directories. Example: <CODE>"lib/*/ebin"</CODE>.
<P>In the generated boot script all application directories are
structured as <CODE>App-Vsn/ebin</CODE> and assumed to be located
in <CODE>$ROOT/lib</CODE>, where <CODE>$ROOT</CODE> is the root directory
of the installed release. If the <CODE>local</CODE> option is
supplied, the actual directories where the applications were
found are used instead. This is a useful way to test a
generated boot script locally.
<P>The <CODE>variables</CODE> option can be used to specify an
installation directory other than <CODE>$ROOT/lib</CODE> for some of
the applications. If a variable <CODE>{VarName,Prefix}</CODE> is
specified and an application is found in a directory
<CODE>Prefix/Rest/App[-Vsn]/ebin</CODE>, this application will get
the path <CODE>VarName/Rest/App-Vsn/ebin</CODE> in the boot script.
If an application is found in a directory <CODE>Prefix/Rest</CODE>,
the path will be <CODE>VarName/Rest/App-Vsn/ebin</CODE>. When
starting Erlang, all variables <CODE>VarName</CODE> are given
values using the <CODE>boot_var</CODE> command line flag.
<P>Example: If the option <CODE>{variables,[{"TEST","lib"}]}</CODE> is
supplied, and <CODE>myapp.app</CODE> is found in
<CODE>lib/myapp/ebin</CODE>, then the path to this application in
the boot script will be <CODE>$TEST/myapp-1/ebin"</CODE>. If
<CODE>myapp.app</CODE> is found in <CODE>lib/test</CODE>, then the path
will be <CODE>$TEST/test/myapp-1/ebin</CODE>.
<P>The checks performed before the boot script is generated can
be extended with some cross reference checks by specifying
the <CODE>exref</CODE> option. These checks are performed with
the Xref tool. All applications, or the applications specified
with <CODE>{exref,[App]}</CODE>, are checked by Xref and
warnings are generated for calls to undefined functions.
<P>By default, errors and warnings are printed to tty and
the function returns <CODE>ok</CODE> or <CODE>error</CODE>. If the option
<CODE>silent</CODE> is provided, the function instead returns
<CODE>{ok,Module,Warnings}</CODE> or <CODE>{error,Module,Error}</CODE>.
Warnings and errors can be converted to strings by calling
<CODE>Module:format_warning(Warnings)</CODE> or
<CODE>Module:format_error(Error)</CODE>.
</DIV>
<P><A NAME="make_tar/1"><STRONG><CODE>make_tar(Name) -> Result</CODE></STRONG></A><BR>
<A NAME="make_tar/2"><STRONG><CODE>make_tar(Name, [Opt]) -> Result</CODE></STRONG></A><BR>
<DIV CLASS=REFBODY><P>Types:
<DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Name = string()</CODE></STRONG><BR>
<STRONG><CODE>Opt = {dirs,[IncDir]} | {path,[Dir]} | {variables,[Var]}
| {var_tar,VarTar} | {erts,Dir} | no_module_tests | exref
| {exref,[App]} | silent
</CODE></STRONG><BR>
<STRONG><CODE>Dir = string()</CODE></STRONG><BR>
<STRONG><CODE>IncDir = src | include | atom()</CODE></STRONG><BR>
<STRONG><CODE>Var = {VarName,PreFix}</CODE></STRONG><BR>
<STRONG><CODE>VarName = Prefix = string()</CODE></STRONG><BR>
<STRONG><CODE>VarTar = include | ownfile | omit</CODE></STRONG><BR>
<STRONG><CODE>Machine = atom()</CODE></STRONG><BR>
<STRONG><CODE>App = atom()</CODE></STRONG><BR>
<STRONG><CODE>Result = ok | error | {ok,Module,Warnings}
| {error,Module,Error}</CODE></STRONG><BR>
<STRONG><CODE>Module = atom()</CODE></STRONG><BR>
<STRONG><CODE>Warning = Error = term()</CODE></STRONG><BR>
</DIV>
</DIV>
<DIV CLASS=REFBODY>
<P>Creates a release package file <CODE>Name.tar.gz</CODE>. file.
This file must be uncompressed and unpacked on the target
system using the <CODE>release_handler</CODE>, before the new
release can be installed.
<P>The release resource file <CODE>Name.rel</CODE> is read to find out
which applications are included in the release. Then
the relevant application resource files <CODE>App.app</CODE> are
read to find out the version and modules of each application.
(Keys <CODE>vsn</CODE> and <CODE>modules</CODE>, see <CODE>app(4)</CODE>).
<P>By default, the release package contains the directories
<CODE>lib/App-Vsn/ebin</CODE> and <CODE>lib/App-Vsn/priv</CODE> for each
included application. If more directories, the option
<CODE>dirs</CODE> is supplied. Example:
<CODE>{dirs,[src,examples]}</CODE>.
<P>All files are searched for in the current path. If
the option <CODE>{path,[Dir]}</CODE> is provided, this path is
appended to the current path. The wildcard <CODE>*</CODE> is
expanded to all matching directories.
Example: <CODE>"lib/*/ebin"</CODE>.
<P>The <CODE>variables</CODE> option can be used to specify an
installation directory other than <CODE>lib</CODE> for some of
the applications. If a variable <CODE>{VarName,Prefix}</CODE> is
specified and an application is found in a directory
<CODE>Prefix/Rest/App[-Vsn]/ebin</CODE>, this application will be
packed into a separate <CODE>VarName.tar.gz</CODE> file as
<CODE>Rest/App-Vsn/ebin</CODE>.
<P>Example: If the option <CODE>{variables,[{"TEST","lib"}]}</CODE> is
supplied, and <CODE>myapp.app</CODE> is found in
<CODE>lib/myapp-1/ebin</CODE>, the the application <CODE>myapp</CODE> is
included in <CODE>TEST.tar.gz</CODE>:
<PRE>
% <STRONG>tar tf TEST.tar</STRONG>
myapp-1/ebin/myapp.app
...
</PRE>
<P>The <CODE>{var_tar,VarTar}</CODE> option can be used to specify if
and where a separate package should be stored. In this option,
<CODE>VarTar</CODE> is:
<P>
<UL>
<LI>
<CODE>include</CODE>. Each separate (variable) package is
included in the main <CODE>ReleaseName.tar.gz</CODE> file. This
is the default.<BR>
</LI>
<LI>
<CODE>ownfile</CODE>. Each separate (variable) package is
generated as separate files in the same directory as
the <CODE>ReleaseName.tar.gz</CODE> file.<BR>
</LI>
<LI>
<CODE>omit</CODE>. No separate (variable) packages are
generated and applications which are found underneath a
variable directory are ignored.<BR>
</LI>
</UL>
<P>A directory called <CODE>releases/RelVsn</CODE> is also included
in the release package. The release version <CODE>RelVsn</CODE> is
found in the release package. This directory contains
<CODE>Name.rel</CODE>, the boot script <CODE>Name.boot</CODE> renamed to
<CODE>start.boot</CODE> and, if found, the files <CODE>relup</CODE> and
<CODE>sys.config</CODE>.
<P>If the release package should contain a new Erlang runtime
system, the <CODE>bin</CODE> directory of the specified runtime
system <CODE>{erts,Dir}</CODE> is copied to <CODE>erts-ErtsVsn/bin</CODE>.
<P>All checks performed with the <CODE>make_script</CODE> function
are performed before the release package is created. The
<CODE>no_module_tests</CODE> and <CODE>exref</CODE> options are also
valid here.
<P>The return value and the handling of errorsd and warnings
are the same as described for <CODE>make_script</CODE> above.
</DIV>
<P><A NAME="script2boot/1"><STRONG><CODE>script2boot(File) -> ok | error</CODE></STRONG></A><BR>
<DIV CLASS=REFBODY><P>Types:
<DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>File = string()</CODE></STRONG><BR>
</DIV>
</DIV>
<DIV CLASS=REFBODY>
<P>The Erlang runtime system requires that the contents of
the script used to boot the system is a binary Erlang term.
This function transforms the <CODE>File.script</CODE> boot script
to a binary term which is stored in the file <CODE>File.boot</CODE>.
<P>A boot script generated using the <CODE>make_script</CODE>
function is already transformed to the binary form.
</DIV>
<H3>SEE ALSO</H3>
<DIV CLASS=REFBODY>
<P>app(4), appup(4), erl(1), rel(4), release_handler(3), relup(4),
script(4)
</DIV>
<H3>AUTHORS</H3>
<DIV CLASS=REFBODY>
Gunilla Arendt - support@erlang.ericsson.se<BR>
</DIV>
<CENTER>
<HR>
<SMALL>sasl 2.0<BR>
Copyright © 1991-2004
<A HREF="http://www.erlang.se">Ericsson AB</A><BR>
</SMALL>
</CENTER>
</BODY>
</HTML>
|
