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 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. The boot file specifies which code to be
120 loaded and which applications to be started when the Erlang run‐
121 time system is started. See script(4).
122 The release resource file Name.rel is read to determine which
124 applications are included in the release. Then the relevant
125 application resource files App.app are read to determine which
126 modules to be loaded, and if and how the applications are to be
127 started. (Keys modules and mod, see app(4).
128 By default, the boot script and boot file are located in the
130 same directory as Name.rel. That is, in the current working
131 directory unless Name contains a path. If option {outdir,Dir} is
132 specified, they are located in Dir instead.
133 The correctness of each application is checked as follows:
135 * The version of an application specified in the .rel file is
137 to be the same as the version specified in the .app file.
138 * There are to be no undefined applications, that is, depen‐
140 dencies to applications that are not included in the
141 release. (Key applications in the .app file).
142 * There are to be no circular dependencies among the applica‐
144 tions.
145 * There are to be no duplicated modules, that is, modules with
147 the same name but belonging to different applications.
148 * If option src_tests is specified, a warning is issued if the
150 source code for a module is missing or is newer than the
151 object code.
152 The applications are sorted according to the dependencies
154 between the applications. Where there are no dependencies, the
155 order in the .rel file is kept.
156 The function fails if the mandatory applications Kernel and
158 STDLIB are not included in the .rel file and have start type
159 permanent (which is default).
160 If SASL is not included as an application in the .rel file, a
162 warning is issued because such a release cannot be used in an
163 upgrade. To turn off this warning, add option no_warn_sasl.
164 All files are searched for in the current path. It is assumed
166 that the .app and .beam files for an application are located in
167 the same directory. The .erl files are also assumed to be
168 located in this directory, unless it is an ebin directory in
169 which case they can be located in the corresponding src direc‐
170 tory.
171 If option {path,[Dir]} is specified, this path is appended to
173 the current path. A directory in the path can be specified with
174 a wildcard *, this is expanded to all matching directories.
175 Example: "lib/*/ebin".
176 In the generated boot script all application directories are
178 structured as App-Vsn/ebin. They are assumed to be located in
179 $ROOT/lib, where $ROOT is the root directory of the installed
180 release. If option local is specified, the actual directories
181 where the applications were found are used instead. This is a
182 useful way to test a generated boot script locally.
183 Option variables can be used to specify an installation direc‐
185 tory other than $ROOT/lib for some of the applications. If a
186 variable {VarName,Prefix} is specified and an application is
187 found in a directory Prefix/Rest/App[-Vsn]/ebin, this applica‐
188 tion gets the path VarName/Rest/App-Vsn/ebin in the boot script.
189 If an application is found in a directory Prefix/Rest, the path
190 is VarName/Rest/App-Vsn/ebin. When starting Erlang, all vari‐
191 ables VarName are given values using command-line flag boot_var.
192 Example: If option {variables,[{"TEST","lib"}]} is specified and
194 myapp.app is found in lib/myapp/ebin, the path to this applica‐
195 tion in the boot script is "$TEST/myapp-1/ebin". If myapp.app is
196 found in lib/test, the path is $TEST/test/myapp-1/ebin.
197 The checks performed before the boot script is generated can be
199 extended with some cross reference checks by specifying option
200 exref. These checks are performed with the Xref tool. All appli‐
201 cations, or the applications specified with {exref,[App]}, are
202 checked by Xref and warnings are issued for calls to undefined
203 functions.
204 By default, errors and warnings are printed to tty and the func‐
206 tion returns ok or error. If option silent is specified, the
207 function instead returns {ok,Module,Warnings} or {error,Mod‐
208 ule,Error}. Warnings and errors can be converted to strings by
209 calling Module:format_warning(Warnings) or Module:for‐
210 mat_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, [Opt]) -> Result
220 Types:
222 Name = string()
224 Opt = {dirs,[IncDir]} | {path,[Dir]} | {variables,[Var]} |
225 {var_tar,VarTar} | {erts,Dir} | src_tests | exref |
226 {exref,[App]} | silent | {outdir,Dir} | | no_warn_sasl |
227 warnings_as_errors
228 Dir = string()
229 IncDir = src | include | atom()
230 Var = {VarName,PreFix}
231 VarName = Prefix = string()
232 VarTar = include | ownfile | omit
233 Machine = atom()
234 App = atom()
235 Result = ok | error | {ok,Module,Warnings} | {error,Mod‐
236 ule,Error}
237 Module = atom()
238 Warning = Error = term()
239 Creates a release package file Name.tar.gz. This file must be
241 uncompressed and unpacked on the target system using
242 release_handler before the new release can be installed.
243 The release resource file Name.rel is read to determine which
245 applications are included in the release. Then the relevant
246 application resource files App.app are read to determine the
247 version and modules of each application (keys vsn and modules,
248 see app(4)).
249 By default, the release package file is located in the same
251 directory as Name.rel. That is, in the current working directory
252 unless Name contains a path. If option {outdir,Dir} is speci‐
253 fied, it is located in Dir instead.
254 If SASL is not included as an application in the .rel file, a
256 warning is issued because such a release cannot be used in an
257 upgrade. To turn off this warning, add option no_warn_sasl.
258 By default, the release package contains the directories
260 lib/App-Vsn/ebin and lib/App-Vsn/priv for each included applica‐
261 tion. If more directories are to be included, option dirs is
262 specified, for example, {dirs,[src,examples]}.
263 All these files are searched for in the current path. If option
265 {path,[Dir]} is specified, this path is appended to the current
266 path. Wildcard * is expanded to all matching directories. Exam‐
267 ple: "lib/*/ebin".
268 Option variables can be used to specify an installation direc‐
270 tory other than lib for some of the applications. If variable
271 {VarName,Prefix} is specified and an application is found in
272 directory Prefix/Rest/App[-Vsn]/ebin, this application is packed
273 into a separate VarName.tar.gz file as Rest/App-Vsn/ebin.
274 Example: If option {variables,[{"TEST","lib"}]} is specified and
276 myapp.app is located in lib/myapp-1/ebin, application myapp is
277 included in TEST.tar.gz:
278 % tar tf TEST.tar
280 myapp-1/ebin/myapp.app
281 Option {var_tar,VarTar} can be used to specify if and where a
283 separate package is to be stored. In this option VarTar is one
284 of the following:
285 include:
287 Each separate (variable) package is included in the main
288 ReleaseName.tar.gz file. This is the default.
289 ownfile:
291 Each separate (variable) package is generated as a separate
292 file in the same directory as the ReleaseName.tar.gz file.
293 omit:
295 No separate (variable) packages are generated. Applications
296 that are found underneath a variable directory are ignored.
297 A directory releases is also included in the release package,
299 containing Name.rel and a subdirectory RelVsn. RelVsn is the
300 release version as specified in Name.rel.
301 releases/RelVsn contains the boot script Name.boot renamed to
303 start.boot and, if found, the files relup and sys.config or
304 sys.config.src. These files are searched for in the same direc‐
305 tory as Name.rel, in the current working directory, and in any
306 directories specified using option path. In the case of sys.con‐
307 fig it is not included if sys.config.src is found.
308 If the release package is to contain a new Erlang runtime sys‐
310 tem, the bin directory of the specified runtime system
311 {erts,Dir} is copied to erts-ErtsVsn/bin.
312 All checks with function make_script are performed before the
314 release package is created. Options src_tests and exref are also
315 valid here.
316 The return value and the handling of errors and warnings are the
318 same as described for make_script.
319 script2boot(File) -> ok | error
321 Types:
323 File = string()
325 The Erlang runtime system requires that the contents of the
327 script used to boot the system is a binary Erlang term. This
328 function transforms the File.script boot script to a binary
329 term, which is stored in the File.boot file.
330 A boot script generated using make_script is already transformed
332 to the binary form.
333
335 app(4), appup(4), erl(1), rel(4), release_handler(3), relup(4),
336 script(4)
337Ericsson AB sasl 3.3 systools(3)