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} |
25 {error,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
32 releases. The instructions are used by release_handler when
33 installing 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
37 located 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,
50 applications 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
60 upgrade files App.appup, sorted in the same order as when gener‐
61 ating a boot script, see make_script/1,2. High-level instruc‐
62 tions are translated into low-level instructions and the result
63 is 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
78 ensures that a complete reboot of the system is done when the
79 system 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_emula‐
83 tor_upgrade is issued. For more information about this, see
84 Design 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,Mod‐
90 ule,Error}. Warnings and errors can be converted to strings by
91 calling Module:format_warning(Warnings) or Module:for‐
92 mat_error(Error).
93 If option noexec is specified, the function returns the same
95 values as for silent but no relup file is created.
96 If option warnings_as_errors is specified, warnings are treated
98 as errors.
99 make_script(Name) -> Result
101 make_script(Name, [Opt]) -> Result
102 Types:
104 Name = string()
106 Opt = src_tests | {path,[Dir]} | local | {variables,[Var]} |
107 exref | {exref,[App]}] | silent | {outdir,Dir} |
108 no_dot_erlang | no_warn_sasl | warnings_as_errors |
109 {script_name, Name}
110 Dir = string()
111 Var = {VarName,Prefix}
112 VarName = Prefix = string()
113 App = atom()
114 Result = ok | error | {ok,Module,Warnings} | {error,Mod‐
115 ule,Error}
116 Module = atom()
117 Warnings = Error = term()
118 Generates a boot script Name.script and its binary version, the
120 boot file Name.boot, unless the {script_name, ScriptName} option
121 is given, in which case the names are ScriptName.script and
122 ScriptName.boot The boot file specifies which code to be loaded
123 and which applications to be started when the Erlang runtime
124 system is started. See script(4).
125 The release resource file Name.rel is read to determine which
127 applications are included in the release. Then the relevant
128 application resource files App.app are read to determine which
129 modules to be loaded, and if and how the applications are to be
130 started. (Keys modules and mod, see app(4).
131 By default, the boot script and boot file are located in the
133 same directory as Name.rel. That is, in the current working
134 directory unless Name contains a path. If option {outdir,Dir} is
135 specified, they are located in Dir instead.
136 The correctness of each application is checked as follows:
138 * The version of an application specified in the .rel file is
140 to be the same as the version specified in the .app file.
141 * There are to be no undefined applications, that is, depen‐
143 dencies to applications that are not included in the
144 release. (Key applications in the .app file).
145 * There are to be no circular dependencies among the applica‐
147 tions.
148 * There are to be no duplicated modules, that is, modules with
150 the same name but belonging to different applications.
151 * If option src_tests is specified, a warning is issued if the
153 source code for a module is missing or is newer than the
154 object code.
155 The applications are sorted according to the dependencies
157 between the applications. Where there are no dependencies, the
158 order in the .rel file is kept.
159 The function fails if the mandatory applications Kernel and
161 STDLIB are not included in the .rel file and have start type
162 permanent (which is default).
163 If SASL is not included as an application in the .rel file, a
165 warning is issued because such a release cannot be used in an
166 upgrade. To turn off this warning, add option no_warn_sasl.
167 All files are searched for in the current path. It is assumed
169 that the .app and .beam files for an application are located in
170 the same directory. The .erl files are also assumed to be
171 located in this directory, unless it is an ebin directory in
172 which case they can be located in the corresponding src direc‐
173 tory.
174 If option {path,[Dir]} is specified, this path is appended to
176 the current path. A directory in the path can be specified with
177 a wildcard *, this is expanded to all matching directories.
178 Example: "lib/*/ebin".
179 In the generated boot script all application directories are
181 structured as App-Vsn/ebin. They are assumed to be located in
182 $ROOT/lib, where $ROOT is the root directory of the installed
183 release. If option local is specified, the actual directories
184 where the applications were found are used instead. This is a
185 useful way to test a generated boot script locally.
186 Option variables can be used to specify an installation direc‐
188 tory other than $ROOT/lib for some of the applications. If a
189 variable {VarName,Prefix} is specified and an application is
190 found in a directory Prefix/Rest/App[-Vsn]/ebin, this applica‐
191 tion gets the path VarName/Rest/App-Vsn/ebin in the boot script.
192 If an application is found in a directory Prefix/Rest, the path
193 is VarName/Rest/App-Vsn/ebin. When starting Erlang, all vari‐
194 ables VarName are given values using command-line flag boot_var.
195 Example: If option {variables,[{"TEST","lib"}]} is specified and
197 myapp.app is found in lib/myapp/ebin, the path to this applica‐
198 tion in the boot script is "$TEST/myapp-1/ebin". If myapp.app is
199 found in lib/test, the path is $TEST/test/myapp-1/ebin.
200 The checks performed before the boot script is generated can be
202 extended with some cross reference checks by specifying option
203 exref. These checks are performed with the Xref tool. All appli‐
204 cations, or the applications specified with {exref,[App]}, are
205 checked by Xref and warnings are issued for calls to undefined
206 functions.
207 By default, errors and warnings are printed to tty and the func‐
209 tion returns ok or error. If option {ok,Module,Warnings} or
210 {error,Module,Error}. silent is specified, the function instead
211 returns Warnings and errors can be converted to strings by call‐
212 ing Module:format_warning(Warnings) or Module:for‐
213 mat_error(Error).
214 If option warnings_as_errors is specified, warnings are treated
216 as errors.
217 If option no_dot_erlang is specified, the instruction to load
219 the .erlang file during boot is not included.
220 make_tar(Name) -> Result
222 make_tar(Name, Opts) -> Result
224 Types:
226 Name = string()
228 Opts = [Opt]
229 Opt =
230 {dirs, [IncDir]} |
231 {path, [Dir]} |
232 {variables, [Var]} |
233 {var_tar, VarTar} |
234 {erts, Dir} |
235 erts_all | src_tests | exref |
236 {exref, [App]} |
237 silent |
238 {outdir, Dir} |
239 no_warn_sasl | warnings_as_errors |
240 {extra_files, ExtraFiles}
241 Dir = file:filename_all()
242 IncDir = src | include | atom()
243 Var = {VarName, PreFix}
244 VarName = PreFix = string()
245 VarTar = include | ownfile | omit
246 App = atom()
247 Result =
248 ok | error |
249 {ok, Module :: module(), Warnings :: term()} |
250 {error, Module :: module(), Error :: term()}
251 ExtraFiles = [{NameInArchive, file:filename_all()}]
252 NameInArchive = string()
253 Creates a release package file Name.tar.gz. This file must be
255 uncompressed and unpacked on the target system using
256 release_handler before the new release can be installed.
257 The release resource file Name.rel is read to determine which
259 applications are included in the release. Then the relevant
260 application resource files App.app are read to determine the
261 version and modules of each application (keys vsn and modules,
262 see app(4)).
263 By default, the release package file is located in the same
265 directory as Name.rel. That is, in the current working directory
266 unless Name contains a path. If option {outdir,Dir} is speci‐
267 fied, it is located in Dir instead.
268 If SASL is not included as an application in the .rel file, a
270 warning is issued because such a release cannot be used in an
271 upgrade. To turn off this warning, add option no_warn_sasl.
272 By default, the release package contains the directories
274 lib/App-Vsn/ebin and lib/App-Vsn/priv for each included applica‐
275 tion. If more directories are to be included, option dirs is
276 specified, for example, {dirs,[src,examples]}.
277 All these files are searched for in the current path. If option
279 {path,[Dir]} is specified, this path is appended to the current
280 path. Wildcard * is expanded to all matching directories. Exam‐
281 ple: "lib/*/ebin".
282 If the {extra_files, ExtraFiles} option is given then the
284 ExtraFiles are added to the tarball after everything else to be
285 included has been added. The ExtraFiles list is a list of files
286 or directories in the same format as the add_type() tuple for
287 erl_tar:add/3,4
288 Option variables can be used to specify an installation direc‐
290 tory other than lib for some of the applications. If variable
291 {VarName,Prefix} is specified and an application is found in
292 directory Prefix/Rest/App[-Vsn]/ebin, this application is packed
293 into a separate VarName.tar.gz file as Rest/App-Vsn/ebin.
294 Example: If option {variables,[{"TEST","lib"}]} is specified and
296 myapp.app is located in lib/myapp-1/ebin, application myapp is
297 included in TEST.tar.gz:
298 % tar tf TEST.tar
300 myapp-1/ebin/myapp.app
301 Option {var_tar,VarTar} can be used to specify if and where a
303 separate package is to be stored. In this option VarTar is one
304 of the following:
305 include:
307 Each separate (variable) package is included in the main
308 ReleaseName.tar.gz file. This is the default.
309 ownfile:
311 Each separate (variable) package is generated as a separate
312 file in the same directory as the ReleaseName.tar.gz file.
313 omit:
315 No separate (variable) packages are generated. Applications
316 that are found underneath a variable directory are ignored.
317 A directory releases is also included in the release package,
319 containing Name.rel and a subdirectory RelVsn. RelVsn is the
320 release version as specified in Name.rel.
321 releases/RelVsn contains the boot script Name.boot renamed to
323 start.boot and, if found, the files relup and sys.config or
324 sys.config.src. These files are searched for in the same direc‐
325 tory as Name.rel, in the current working directory, and in any
326 directories specified using option path. In the case of sys.con‐
327 fig it is not included if sys.config.src is found.
328 If the release package is to contain a new Erlang runtime sys‐
330 tem, the erts-ErtsVsn/bin directory of the specified runtime
331 system {erts,Dir} is copied to erts-ErtsVsn/bin. Some erts exe‐
332 cutables are not copied by default, if you want to include all
333 executables you can give the erts_all option.
334 All checks with function make_script are performed before the
336 release package is created. Options src_tests and exref are also
337 valid here.
338 The return value and the handling of errors and warnings are the
340 same as described for make_script.
341 script2boot(File) -> ok | error
343 Types:
345 File = string()
347 The Erlang runtime system requires that the contents of the
349 script used to boot the system is a binary Erlang term. This
350 function transforms the File.script boot script to a binary
351 term, which is stored in the File.boot file.
352 A boot script generated using make_script is already transformed
354 to the binary form.
355
357 app(4), appup(4), erl(1), rel(4), release_handler(3), relup(4),
358 script(4)
359Ericsson AB sasl 4.0.2 systools(3)