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 {ok,Module,Warnings} or {er‐
208 ror,Module,Error}. silent is specified, the function instead re‐
209 turns Warnings and errors can be converted to strings by calling
210 Module:format_warning(Warnings) or Module:format_error(Error).
211 If option warnings_as_errors is specified, warnings are treated
213 as errors.
214 If option no_dot_erlang is specified, the instruction to load
216 the .erlang file during boot is not included.
217 make_tar(Name) -> Result
219 make_tar(Name, Opts) -> Result
221 Types:
223 Name = string()
225 Opts = [Opt]
226 Opt =
227 {dirs, [IncDir]} |
228 {path, [Dir]} |
229 {variables, [Var]} |
230 {var_tar, VarTar} |
231 {erts, Dir} |
232 erts_all | src_tests | exref |
233 {exref, [App]} |
234 silent |
235 {outdir, Dir} |
236 no_warn_sasl | warnings_as_errors |
237 {extra_files, ExtraFiles}
238 Dir = file:filename_all()
239 IncDir = src | include | atom()
240 Var = {VarName, PreFix}
241 VarName = PreFix = string()
242 VarTar = include | ownfile | omit
243 App = atom()
244 Result =
245 ok | error |
246 {ok, Module :: module(), Warnings :: term()} |
247 {error, Module :: module(), Error :: term()}
248 ExtraFiles = [{NameInArchive, file:filename_all()}]
249 NameInArchive = string()
250 Creates a release package file Name.tar.gz. This file must be
252 uncompressed and unpacked on the target system using re‐
253 lease_handler before the new release can be installed.
254 The release resource file Name.rel is read to determine which
256 applications are included in the release. Then the relevant ap‐
257 plication resource files App.app are read to determine the ver‐
258 sion and modules of each application (keys vsn and modules, see
259 app(4)).
260 By default, the release package file is located in the same di‐
262 rectory as Name.rel. That is, in the current working directory
263 unless Name contains a path. If option {outdir,Dir} is speci‐
264 fied, it is located in Dir instead.
265 If SASL is not included as an application in the .rel file, a
267 warning is issued because such a release cannot be used in an
268 upgrade. To turn off this warning, add option no_warn_sasl.
269 By default, the release package contains the directories
271 lib/App-Vsn/ebin and lib/App-Vsn/priv for each included applica‐
272 tion. If more directories are to be included, option dirs is
273 specified, for example, {dirs,[src,examples]}.
274 All these files are searched for in the current path. If option
276 {path,[Dir]} is specified, this path is appended to the current
277 path. Wildcard * is expanded to all matching directories. Exam‐
278 ple: "lib/*/ebin".
279 If the {extra_files, ExtraFiles} option is given then the Ex‐
281 traFiles are added to the tarball after everything else to be
282 included has been added. The ExtraFiles list is a list of files
283 or directories in the same format as the add_type() tuple for
284 erl_tar:add/3,4
285 Option variables can be used to specify an installation direc‐
287 tory other than lib for some of the applications. If variable
288 {VarName,Prefix} is specified and an application is found in di‐
289 rectory Prefix/Rest/App[-Vsn]/ebin, this application is packed
290 into a separate VarName.tar.gz file as Rest/App-Vsn/ebin.
291 Example: If option {variables,[{"TEST","lib"}]} is specified and
293 myapp.app is located in lib/myapp-1/ebin, application myapp is
294 included in TEST.tar.gz:
295 % tar tf TEST.tar
297 myapp-1/ebin/myapp.app
298 Option {var_tar,VarTar} can be used to specify if and where a
300 separate package is to be stored. In this option VarTar is one
301 of the following:
302 include:
304 Each separate (variable) package is included in the main Re‐
305 leaseName.tar.gz file. This is the default.
306 ownfile:
308 Each separate (variable) package is generated as a separate
309 file in the same directory as the ReleaseName.tar.gz file.
310 omit:
312 No separate (variable) packages are generated. Applications
313 that are found underneath a variable directory are ignored.
314 A directory releases is also included in the release package,
316 containing Name.rel and a subdirectory RelVsn. RelVsn is the re‐
317 lease version as specified in Name.rel.
318 releases/RelVsn contains the boot script Name.boot renamed to
320 start.boot and, if found, the files relup and sys.config or
321 sys.config.src. These files are searched for in the same direc‐
322 tory as Name.rel, in the current working directory, and in any
323 directories specified using option path. In the case of sys.con‐
324 fig it is not included if sys.config.src is found.
325 If the release package is to contain a new Erlang runtime sys‐
327 tem, the erts-ErtsVsn/bin directory of the specified runtime
328 system {erts,Dir} is copied to erts-ErtsVsn/bin. Some erts exe‐
329 cutables are not copied by default, if you want to include all
330 executables you can give the erts_all option.
331 All checks with function make_script are performed before the
333 release package is created. Options src_tests and exref are also
334 valid here.
335 The return value and the handling of errors and warnings are the
337 same as described for make_script.
338 script2boot(File) -> ok | error
340 Types:
342 File = string()
344 The Erlang runtime system requires that the contents of the
346 script used to boot the system is a binary Erlang term. This
347 function transforms the File.script boot script to a binary
348 term, which is stored in the File.boot file.
349 A boot script generated using make_script is already transformed
351 to the binary form.
352
354 app(4), appup(4), erl(1), rel(4), release_handler(3), relup(4),
355 script(4)
356Ericsson AB sasl 4.1 systools(3)