1systools(3) Erlang Module Definition systools(3)
2
6 systools - A Set of Release Handling Tools
7
9 This module contains functions to generate boot scripts (.boot,
10 .script), a release upgrade file (relup), and release packages.
11
13 make_relup(Name, UpFrom, DownTo) -> Result
14 make_relup(Name, UpFrom, DownTo, [Opt]) -> Result
15 Types:
17 Name = string()
19 UpFrom = DownTo = [Name | {Name,Descr}]
20 Descr = term()
21 Opt = {path,[Dir]} | restart_emulator | silent | noexec |
22 {outdir,Dir} | warnings_as_errors
23 Dir = string()
24 Result = ok | error | {ok,Relup,Module,Warnings} | {er‐
25 ror,Module,Error}
26 Relup, see relup(4)
27 Module = atom()
28 Warnings = Error = term()
29 Generates a release upgrade file relup containing instructions
31 for upgrading from or downgrading to one or more previous re‐
32 leases. The instructions are used by release_handler when in‐
33 stalling a new version of a release in runtime.
34 By default, relup file is located in the current working direc‐
36 tory. If option {outdir,Dir} is specified, the relup file is lo‐
37 cated in Dir instead.
38 The release resource file Name.rel is compared with all release
40 resource files Name2.rel, specified in UpFrom and DownTo. For
41 each such pair, the following is deducted:
42 * Which applications to be deleted, that is, applications
44 listed in Name.rel but not in Name2.rel
45 * Which applications to be added, that is, applications listed
47 in Name2.rel but not in Name.rel
48 * Which applications to be upgraded/downgraded, that is, ap‐
50 plications listed in both Name.rel and Name2.rel but with
51 different versions
52 * If the emulator needs to be restarted after upgrading or
54 downgrading, that is, if the ERTS version differs between
55 Name.rel and Name2.rel
56 Instructions for this are added to the relup file in the above
58 order. Instructions for upgrading or downgrading between appli‐
59 cation versions are fetched from the relevant application up‐
60 grade files App.appup, sorted in the same order as when generat‐
61 ing a boot script, see make_script/1,2. High-level instructions
62 are translated into low-level instructions and the result is
63 printed to the relup file.
64 The optional Descr parameter is included "as is" in the relup
66 file, see relup(4). Defaults to the empty list.
67 All the files are searched for in the code path. It is assumed
69 that the .app and .appup files for an application are located in
70 the same directory.
71 If option {path,[Dir]} is specified, this path is appended to
73 the current path. Wildcard * is expanded to all matching direc‐
74 tories, for example, lib/*/ebin.
75 If option restart_emulator is specified, a low-level instruction
77 to restart the emulator is appended to the relup file. This en‐
78 sures that a complete reboot of the system is done when the sys‐
79 tem is upgraded or downgraded.
80 If an upgrade includes a change from an emulator earlier than
82 OTP R15 to OTP R15 or later, the warning pre_R15_emulator_up‐
83 grade is issued. For more information about this, see Design
84 Principles in System Documentation.
85 By default, errors and warnings are printed to tty and the func‐
87 tion returns ok or error. If option silent is specified, the
88 function instead either returns {ok,Relup,Module,Warnings},
89 where Relup is the release upgrade file, or {error,Module,Er‐
90 ror}. Warnings and errors can be converted to strings by calling
91 Module:format_warning(Warnings) or Module:format_error(Error).
92 If option noexec is specified, the function returns the same
94 values as for silent but no relup file is created.
95 If option warnings_as_errors is specified, warnings are treated
97 as errors.
98 make_script(Name) -> Result
100 make_script(Name, [Opt]) -> Result
101 Types:
103 Name = string()
105 Opt = src_tests | {path,[Dir]} | local | {variables,[Var]} |
106 exref | {exref,[App]}] | silent | {outdir,Dir} | no_dot_er‐
107 lang | no_warn_sasl | warnings_as_errors | {script_name,
108 Name}
109 Dir = string()
110 Var = {VarName,Prefix}
111 VarName = Prefix = string()
112 App = atom()
113 Result = ok | error | {ok,Module,Warnings} | {error,Mod‐
114 ule,Error}
115 Module = atom()
116 Warnings = Error = term()
117 Generates a boot script Name.script and its binary version, the
119 boot file Name.boot, unless the {script_name, ScriptName} option
120 is given, in which case the names are ScriptName.script and
121 ScriptName.boot The boot file specifies which code to be loaded
122 and which applications to be started when the Erlang runtime
123 system is started. See script(4).
124 The release resource file Name.rel is read to determine which
126 applications are included in the release. Then the relevant ap‐
127 plication resource files App.app are read to determine which
128 modules to be loaded, and if and how the applications are to be
129 started. (Keys modules and mod, see app(4).
130 By default, the boot script and boot file are located in the
132 same directory as Name.rel. That is, in the current working di‐
133 rectory unless Name contains a path. If option {outdir,Dir} is
134 specified, they are located in Dir instead.
135 The correctness of each application is checked as follows:
137 * The version of an application specified in the .rel file is
139 to be the same as the version specified in the .app file.
140 * There are to be no undefined applications, that is, depen‐
142 dencies to applications that are not included in the re‐
143 lease. (Key applications in the .app file).
144 * There are to be no circular dependencies among the applica‐
146 tions.
147 * There are to be no duplicated modules, that is, modules with
149 the same name but belonging to different applications.
150 * If option src_tests is specified, a warning is issued if the
152 source code for a module is missing or is newer than the ob‐
153 ject code.
154 The applications are sorted according to the dependencies be‐
156 tween the applications. Where there are no dependencies, the or‐
157 der in the .rel file is kept.
158 The function fails if the mandatory applications Kernel and
160 STDLIB are not included in the .rel file and have start type
161 permanent (which is default).
162 If SASL is not included as an application in the .rel file, a
164 warning is issued because such a release cannot be used in an
165 upgrade. To turn off this warning, add option no_warn_sasl.
166 All files are searched for in the current path. It is assumed
168 that the .app and .beam files for an application are located in
169 the same directory. The .erl files are also assumed to be lo‐
170 cated in this directory, unless it is an ebin directory in which
171 case they can be located in the corresponding src directory.
172 If option {path,[Dir]} is specified, this path is appended to
174 the current path. A directory in the path can be specified with
175 a wildcard *, this is expanded to all matching directories. Ex‐
176 ample: "lib/*/ebin".
177 In the generated boot script all application directories are
179 structured as App-Vsn/ebin. They are assumed to be located in
180 $ROOT/lib, where $ROOT is the root directory of the installed
181 release. If option local is specified, the actual directories
182 where the applications were found are used instead. This is a
183 useful way to test a generated boot script locally.
184 Option variables can be used to specify an installation direc‐
186 tory other than $ROOT/lib for some of the applications. If a
187 variable {VarName,Prefix} is specified and an application is
188 found in a directory Prefix/Rest/App[-Vsn]/ebin, this applica‐
189 tion gets the path VarName/Rest/App-Vsn/ebin in the boot script.
190 If an application is found in a directory Prefix/Rest, the path
191 is VarName/Rest/App-Vsn/ebin. When starting Erlang, all vari‐
192 ables VarName are given values using command-line flag boot_var.
193 Example: If option {variables,[{"TEST","lib"}]} is specified and
195 myapp.app is found in lib/myapp/ebin, the path to this applica‐
196 tion in the boot script is "$TEST/myapp-1/ebin". If myapp.app is
197 found in lib/test, the path is $TEST/test/myapp-1/ebin.
198 The checks performed before the boot script is generated can be
200 extended with some cross reference checks by specifying option
201 exref. These checks are performed with the Xref tool. All appli‐
202 cations, or the applications specified with {exref,[App]}, are
203 checked by Xref and warnings are issued for calls to undefined
204 functions.
205 By default, errors and warnings are printed to tty and the func‐
207 tion returns ok or error. If option silent is specified, the
208 function instead returns {ok,Module,Warnings} or {error,Mod‐
209 ule,Error}. Warnings and errors can be converted to strings by
210 calling Module:format_warning(Warnings) or Module:format_er‐
211 ror(Error).
212 If option warnings_as_errors is specified, warnings are treated
214 as errors.
215 If option no_dot_erlang is specified, the instruction to load
217 the .erlang file during boot is not included.
218 make_tar(Name) -> Result
220 make_tar(Name, Opts) -> Result
222 Types:
224 Name = string()
226 Opts = [Opt]
227 Opt =
228 {dirs, [IncDir]} |
229 {path, [Dir]} |
230 {variables, [Var]} |
231 {var_tar, VarTar} |
232 {erts, Dir} |
233 erts_all | src_tests | exref |
234 {exref, [App]} |
235 silent |
236 {outdir, Dir} |
237 no_warn_sasl | warnings_as_errors |
238 {extra_files, ExtraFiles}
239 Dir = file:filename_all()
240 IncDir = src | include | atom()
241 Var = {VarName, PreFix}
242 VarName = PreFix = string()
243 VarTar = include | ownfile | omit
244 App = atom()
245 Result =
246 ok | error |
247 {ok, Module :: module(), Warnings :: term()} |
248 {error, Module :: module(), Error :: term()}
249 ExtraFiles = [{NameInArchive, file:filename_all()}]
250 NameInArchive = string()
251 Creates a release package file Name.tar.gz. This file must be
253 uncompressed and unpacked on the target system using re‐
254 lease_handler before the new release can be installed.
255 The release resource file Name.rel is read to determine which
257 applications are included in the release. Then the relevant ap‐
258 plication resource files App.app are read to determine the ver‐
259 sion and modules of each application (keys vsn and modules, see
260 app(4)).
261 By default, the release package file is located in the same di‐
263 rectory as Name.rel. That is, in the current working directory
264 unless Name contains a path. If option {outdir,Dir} is speci‐
265 fied, it is located in Dir instead.
266 If SASL is not included as an application in the .rel file, a
268 warning is issued because such a release cannot be used in an
269 upgrade. To turn off this warning, add option no_warn_sasl.
270 By default, the release package contains the directories
272 lib/App-Vsn/ebin and lib/App-Vsn/priv for each included applica‐
273 tion. If more directories are to be included, option dirs is
274 specified, for example, {dirs,[src,examples]}.
275 All these files are searched for in the current path. If option
277 {path,[Dir]} is specified, this path is appended to the current
278 path. Wildcard * is expanded to all matching directories. Exam‐
279 ple: "lib/*/ebin".
280 If the {extra_files, ExtraFiles} option is given then the Ex‐
282 traFiles are added to the tarball after everything else to be
283 included has been added. The ExtraFiles list is a list of files
284 or directories in the same format as the add_type() tuple for
285 erl_tar:add/3,4
286 Option variables can be used to specify an installation direc‐
288 tory other than lib for some of the applications. If variable
289 {VarName,Prefix} is specified and an application is found in di‐
290 rectory Prefix/Rest/App[-Vsn]/ebin, this application is packed
291 into a separate VarName.tar.gz file as Rest/App-Vsn/ebin.
292 Example: If option {variables,[{"TEST","lib"}]} is specified and
294 myapp.app is located in lib/myapp-1/ebin, application myapp is
295 included in TEST.tar.gz:
296 % tar tf TEST.tar
298 myapp-1/ebin/myapp.app
299 Option {var_tar,VarTar} can be used to specify if and where a
301 separate package is to be stored. In this option VarTar is one
302 of the following:
303 include:
305 Each separate (variable) package is included in the main Re‐
306 leaseName.tar.gz file. This is the default.
307 ownfile:
309 Each separate (variable) package is generated as a separate
310 file in the same directory as the ReleaseName.tar.gz file.
311 omit:
313 No separate (variable) packages are generated. Applications
314 that are found underneath a variable directory are ignored.
315 A directory releases is also included in the release package,
317 containing Name.rel and a subdirectory RelVsn. RelVsn is the re‐
318 lease version as specified in Name.rel.
319 releases/RelVsn contains the boot script Name.boot renamed to
321 start.boot and, if found, the files relup and sys.config or
322 sys.config.src. These files are searched for in the same direc‐
323 tory as Name.rel, in the current working directory, and in any
324 directories specified using option path. In the case of sys.con‐
325 fig it is not included if sys.config.src is found.
326 If the release package is to contain a new Erlang runtime sys‐
328 tem, the erts-ErtsVsn/bin directory of the specified runtime
329 system {erts,Dir} is copied to erts-ErtsVsn/bin. Some erts exe‐
330 cutables are not copied by default, if you want to include all
331 executables you can give the erts_all option.
332 All checks with function make_script are performed before the
334 release package is created. Options src_tests and exref are also
335 valid here.
336 The return value and the handling of errors and warnings are the
338 same as described for make_script.
339 script2boot(File) -> ok | error
341 Types:
343 File = string()
345 The Erlang runtime system requires that the contents of the
347 script used to boot the system is a binary Erlang term. This
348 function transforms the File.script boot script to a binary
349 term, which is stored in the File.boot file.
350 A boot script generated using make_script is already transformed
352 to the binary form.
353
355 app(4), appup(4), erl(1), rel(4), release_handler(3), relup(4),
356 script(4)
357Ericsson AB sasl 4.2.1 systools(3)