1reltool(3) Erlang Module Definition reltool(3)
2
6 reltool - Main API of the Reltool application
7
9 This is an interface module for the Reltool application.
10 Reltool is a release management tool. It analyses a given Erlang/OTP
12 installation and determines various dependencies between applications.
13 The graphical frontend depicts the dependencies and enables interactive
14 customization of a target system. The backend provides a batch inter‐
15 face for generation of customized target systems.
16 The tool uses an installed Erlang/OTP system as input. root_dir is the
18 root directory of the analysed system and it defaults to the system ex‐
19 ecuting Reltool. Applications may also be located outside root_dir.
20 lib_dirs defines library directories where additional applications may
21 reside and it defaults to the directories listed by the operating sys‐
22 tem environment variable ERL_LIBS. See the module code for more info.
23 An application directory AppDir under a library directory is recognized
25 by the existence of an AppDir/ebin directory. If this does not exist,
26 Reltool will not consider AppDir at all when looking for applications.
27 It is recommended that application directories are named as the appli‐
29 cation, possibly followed by a dash and the version number. For example
30 myapp or myapp-1.1.
31 Finally single modules and entire applications may be read from Es‐
33 cripts.
34 Some configuration parameters control the behavior of Reltool on system
36 (sys) level. Others provide control on application (app) level and yet
37 others are on module (mod) level. Module level parameters override ap‐
38 plication level parameters and application level parameters override
39 system level parameters. Escript escript level parameters override sys‐
40 tem level parameters.
41 The following top level options are supported:
43 config:
45 This is the main option and it controls the configuration of Rel‐
46 tool. It can either be a sys tuple or a name of a file containing a
47 sys tuple.
48 trap_exit:
50 This option controls the error handling behavior of Reltool. By de‐
51 fault the window processes traps exit, but this behavior can al‐
52 tered by setting trap_exit to false.
53 wx_debug:
55 This option controls the debug level of wx. As its name indicates
56 it is only useful for debugging. See wx:debug/1 for more info.
57 Besides the already mentioned source parameters root_dir and lib_dirs,
59 the following system (sys) level options are supported:
60 erts:
62 Erts specific configuration. See application level options below.
63 escript:
65 Escript specific configuration. An escript has a mandatory file
66 name and escript level options that are described below.
67 app:
69 Application specific configuration. An application has a mandatory
70 name and application level options that are described below.
71 mod_cond:
73 This parameter controls the module inclusion policy. It defaults to
74 all which means that if an application is included (either explic‐
75 itly or implicitly) all modules in that application will be in‐
76 cluded. This implies that both modules that exist in the ebin di‐
77 rectory of the application, as well as modules that are named in
78 the app file will be included. If the parameter is set to ebin,
79 both modules in the ebin directory and derived modules are in‐
80 cluded. If the parameter is set to app, both modules in the app
81 file and derived modules are included. derived means that only mod‐
82 ules that are used by other included modules are included. The
83 mod_cond setting on system level is used as default for all appli‐
84 cations.
85 incl_cond:
87 This parameter controls the application and escript inclusion pol‐
88 icy. It defaults to derived which means that the applications that
89 do not have any explicit incl_cond setting, will only be included
90 if any other (explicitly or implicitly included) application uses
91 it. The value include implies that all applications and escripts
92 that do not have any explicit incl_cond setting will be included.
93 exclude implies that all applications and escripts that do not have
94 any explicit incl_cond setting will be excluded.
95 boot_rel:
97 A target system may have several releases but the one given as
98 boot_rel will be used as default when the system is booting up.
99 rel:
101 Release specific configuration. Each release maps to a rel, script
102 and boot file. See the module systools for more info about the de‐
103 tails. Each release has a name, a version and a set of applications
104 with a few release specific parameters such as type and included
105 applications.
106 relocatable:
108 This parameter controls whether the erl executable in the target
109 system should automatically determine where it is installed or if
110 it should use a hardcoded path to the installation. In the latter
111 case the target system must be installed with reltool:install/2 be‐
112 fore it can be used. If the system is relocatable, the file tree
113 containing the target system can be moved to another location with‐
114 out re-installation. The default is true.
115 profile:
117 The creation of the specification for a target system is performed
118 in two steps. In the first step a complete specification is gener‐
119 ated. It will likely contain much more files than you are inter‐
120 ested in in your customized target system. In the second step the
121 specification will be filtered according to your filters. There you
122 have the ability to specify filters per application as well as sys‐
123 tem wide filters. You can also select a profile for your system.
124 Depending on the profile, different default filters will be used.
125 There are three different profiles to choose from: development, em‐
126 bedded and standalone. development is default. The parameters that
127 are affected by the profile are: incl_sys_filters, excl_sys_fil‐
128 ters, incl_app_filters and excl_app_filters.
129 app_file:
131 This parameter controls the default handling of the app files when
132 a target system is generated. It defaults to keep which means that
133 app files are copied to the target system and their contents are
134 kept as they are. strip means that a new app file is generated from
135 the contents of the original app file where the non included mod‐
136 ules are removed from the file. all does also imply that a new app
137 file is generated from the contents of the original app file, with
138 the difference that all included modules are added to the file. If
139 the application does not have any app file a file will be created
140 for all but not for keep and strip.
141 debug_info:
143 The debug_info parameter controls what debug information in the
144 beam file should be kept or stripped. keep keeps all debug info,
145 strip strips all debug info, and a list of chunkids keeps only
146 those chunks.
147 excl_lib:
149 Warning:
152 This option is experimental.
153 If the excl_lib option is set to otp_root then reltool will not
156 copy anything from the Erlang/OTP installation ($OTPROOT) into the
157 target structure. The goal is to create a "slim" release which can
158 be used together with an existing Erlang/OTP installation. The tar‐
159 get structure will therefore only contain a lib directory with the
160 applications that were found outside of $OTPROOT (typically your
161 own applications), and a releases directory with the generated
162 .rel, .script and .boot files.
163 When starting this release, three things must be specified:
165 Which releases directory to use:
167 Tell the release handler to use the releases directory in our
168 target structure instead of $OTPROOT/releases. This is done by
169 setting the SASL environment variable releases_dir, either from
170 the command line (-sasl releases_dir <target-dir>/releases) or in
171 sys.config.
172 Which boot file to use:
174 The default boot file is $OTPROOT/bin/start, but in this case we
175 need to specify a boot file from our target structure, typically
176 <target-dir>/releases/<vsn>/<RelName>. This is done with the
177 -boot command line option to erl
178 The location of our applications:
180 The generated .script (and .boot) file uses the environment vari‐
181 able $RELTOOL_EXT_LIB as prefix for the paths to all applica‐
182 tions. The -boot_var option to erl can be used for specifying the
183 value of this variable, typically -boot_var RELTOOL_EXT_LIB <tar‐
184 get-dir>/lib.
185 Example:
187 erl -sasl releases_dir \"mytarget/releases\" -boot mytarget/releases/1.0/myrel\
189 -boot_var RELTOOL_EXT_LIB mytarget/lib
190 incl_sys_filters:
192 This parameter normally contains a list of regular expressions that
193 controls which files in the system should be included. Each file in
194 the target system must match at least one of the listed regular ex‐
195 pressions in order to be included. Further the files may not match
196 any filter in excl_sys_filters in order to be included. Which ap‐
197 plication files should be included is controlled with the parame‐
198 ters incl_app_filters and excl_app_filters. This parameter defaults
199 to [".*"].
200 excl_sys_filters:
202 This parameter normally contains a list of regular expressions that
203 controls which files in the system should not be included in the
204 target system. In order to be included, a file must match some fil‐
205 ter in incl_sys_filters but not any filter in excl_sys_filters.
206 This parameter defaults to [].
207 incl_app_filters:
209 This parameter normally contains a list of regular expressions that
210 controls which application specific files that should be included.
211 Each file in the application must match at least one of the listed
212 regular expressions in order to be included. Further the files may
213 not match any filter in excl_app_filters in order to be included.
214 This parameter defaults to [".*"].
215 excl_app_filters:
217 This parameter normally contains a list of regular expressions that
218 controls which application specific files should not be included in
219 the target system. In order to be included, a file must match some
220 filter in incl_app_filters but not any filter in excl_app_filters.
221 This parameter defaults to [].
222 On application (escript) level, the following options are supported:
224 incl_cond:
226 The value of this parameter overrides the parameter with the same
227 name on system level.
228 On application (app) level, the following options are supported:
230 vsn:
232 The version of the application. In an installed system there may
233 exist several versions of an application. The vsn parameter con‐
234 trols which version of the application will be chosen.
235 This parameter is mutual exclusive with lib_dir. If vsn and lib_dir
237 are both omitted, the latest version will be chosen.
238 Note that in order for reltool to sort application versions and
240 thereby be able to select the latest, it is required that the ver‐
241 sion id for the application consists of integers and dots only, for
242 example 1, 2.0 or 3.17.1.
243 lib_dir:
245 The directory to read the application from. This parameter can be
246 used to point out a specific location to fetch the application
247 from. This is useful for instance if the parent directory for some
248 reason is no good as a library directory on system level.
249 This parameter is mutual exclusive with vsn. If vsn and lib_dir are
251 both omitted, the latest version will be chosen.
252 Note that in order for reltool to sort application versions and
254 thereby be able to select the latest, it is required that the ver‐
255 sion id for the application consists of integers and dots only, for
256 example 1, 2.0 or 3.17.1.
257 mod:
259 Module specific configuration. A module has a mandatory name and
260 module level options that are described below.
261 mod_cond:
263 The value of this parameter overrides the parameter with the same
264 name on system level.
265 incl_cond:
267 The value of this parameter overrides the parameter with the same
268 name on system level.
269 app_file:
271 The value of this parameter overrides the parameter with the same
272 name on system level.
273 debug_info:
275 The value of this parameter overrides the parameter with the same
276 name on system level.
277 incl_app_filters:
279 The value of this parameter overrides the parameter with the same
280 name on system level.
281 excl_app_filters:
283 The value of this parameter overrides the parameter with the same
284 name on system level.
285 On module (mod) level, the following options are supported:
287 incl_cond:
289 This parameter controls whether the module is included or not. By
290 default the mod_cond parameter on application and system level will
291 be used to control whether the module is included or not. The value
292 of incl_cond overrides the module inclusion policy. include implies
293 that the module is included, while exclude implies that the module
294 is not included. derived implies that the module is included if it
295 is used by any other included module.
296 debug_info:
298 The value of this parameter overrides the parameter with the same
299 name on application level.
300
302 options() = [option()]
303 option() = {config, config() | file()}
304 | {trap_exit, bool()}
305 | {wx_debug, term()}
306 config() = {sys, [sys()]}
307 sys() = {root_dir, root_dir()}
308 | {lib_dirs, [lib_dir()]}
309 | {profile, profile()}
310 | {erts, app()}
311 | {escript, escript_file(), [escript()]}
312 | {app, app_name(), [app()]}
313 | {mod_cond, mod_cond()}
314 | {incl_cond, incl_cond()}
315 | {boot_rel, boot_rel()}
316 | {rel, rel_name(), rel_vsn(), [rel_app()]}
317 | {rel, rel_name(), rel_vsn(), [rel_app()], [rel_opt()]}
318 | {relocatable, relocatable()}
319 | {app_file, app_file()}
320 | {debug_info, debug_info()}
321 | {incl_sys_filters, incl_sys_filters()}
322 | {excl_sys_filters, excl_sys_filters()}
323 | {incl_app_filters, incl_app_filters()}
324 | {excl_app_filters, excl_app_filters()}
325 app() = {vsn, app_vsn()}
326 | {lib_dir, lib_dir()}
327 | {mod, mod_name(), [mod()]}
328 | {mod_cond, mod_cond()}
329 | {incl_cond, incl_cond()}
330 | {debug_info, debug_info()}
331 | {app_file, app_file()}
332 | {excl_lib, excl_lib()}
333 | {incl_sys_filters, incl_sys_filters()}
334 | {excl_sys_filters, excl_sys_filters()}
335 | {incl_app_filters, incl_app_filters()}
336 | {excl_app_filters, excl_app_filters()}
337 mod() = {incl_cond, incl_cond()}
338 | {debug_info, debug_info()}
339 rel_app() = app_name()
340 | {app_name(), app_type()}
341 | {app_name(), [incl_app()]}
342 | {app_name(), app_type(), [incl_app()]}
343 rel_opt() = {load_dot_erlang, boolean()}
344 app_name() = atom()
345 app_type() = permanent | transient | temporary | load | none
346 app_vsn() = string()
347 boot_rel() = rel_name()
348 app_file() = keep | strip | all
349 debug_info() = keep | strip | [beam_lib:chunkid()]
350 dir() = string()
351 escript() = {incl_cond, incl_cond()}
352 escript_file() = file()
353 excl_app_filters() = regexps()
354 excl_lib() = otp_root
355 excl_sys_filters() = regexps()
356 file() = string()
357 incl_app() = app_name()
358 incl_app_filters() = regexps()
359 incl_cond() = include | exclude | derived
360 incl_sys_filters() = regexps()
361 lib_dir() = dir()
362 mod_cond() = all | app | ebin | derived | none
363 mod_name() = atom()
364 profile() = development | embedded | standalone
365 re_regexp() = string()
366 reason() = string()
367 regexps() = [re_regexp()]
368 | {add, [re_regexp()]}
369 | {del, [re_regexp()]}
370 rel_file() = term()
371 rel_name() = string()
372 rel_vsn() = string()
373 relocatable = boolean()
374 root_dir() = dir()
375 script_file() = term()
376 server() = server_pid() | options()
377 server_pid() = pid()
378 target_dir() = file()
379 window_pid() = pid()
380 base_dir() = dir()
381 base_file() = file()
382 top_dir() = file()
383 top_file() = file()
384 target_spec() = [target_spec()]
385 | {create_dir, base_dir(), [target_spec()]}
386 | {create_dir, base_dir(), top_dir(), [target_spec()]}
387 | {copy_file, base_file()}
388 | {copy_file, base_file(), top_file()}
389 | {write_file, base_file(), iolist()}
390 | {strip_beam_file, base_file()}
391
393 create_target(Server, TargetDir) -> ok | {error, Reason}
394 Types:
396 Server = server()
398 TargetDir = target_dir()
399 Reason = reason()
400 Create a target system. Gives the same result as {ok,Target‐
402 Spec}=reltool:get_target_spec(Server) and reltool:eval_tar‐
403 get_spec(TargetSpec,RootDir,TargetDir).
404 eval_target_spec(TargetSpec, RootDir, TargetDir) -> ok | {error, Rea‐
406 son}
407 Types:
409 TargetSpec = target_spec()
411 RootDir = root_dir()
412 TargetDir = target_dir()
413 Reason = reason()
414 Create the actual target system from a specification generated
416 by reltool:get_target_spec/1. The creation of the specification
417 for a target system is performed in two steps. In the first step
418 a complete specification will be generated. It will likely con‐
419 tain much more files than you are interested in in your target
420 system. In the second step the specification will be filtered
421 according to your filters. There you have the ability to specify
422 filters per application as well as system wide filters. You can
423 also select a profile for your system. Depending on the profile,
424 different default filters will be used.
425 The top directories bin, releases and lib are treated differ‐
427 ently from other files. All other files are by default copied to
428 the target system. The releases directory contains generated
429 rel, script, and boot files. The lib directory contains the ap‐
430 plications. Which applications are included and if they should
431 be customized (stripped from debug info etc.) is specified with
432 various configuration parameters. The files in the bin directory
433 are copied from the erts-vsn/bin directory, but only those files
434 that were originally included in the bin directory of the source
435 system.
436 If the configuration parameter relocatable was set to true there
438 is no need to install the target system with reltool:install/2
439 before it can be started. In that case the file tree containing
440 the target system can be moved without re-installation.
441 In most cases, the RootDir parameter should be set to the same
443 as the root_dir configuration parameter used in the call to rel‐
444 tool:get_target_spec/1 (or code:root_dir() if the configuration
445 parameter is not set). In some cases it might be useful to eval‐
446 uate the same target specification towards different root direc‐
447 tories. This should, however, be used with great care as it re‐
448 quires equivalent file structures under all roots.
449 get_config(Server) -> {ok, Config} | {error, Reason}
451 Types:
453 Server = server()
455 Config = config()
456 Reason = reason()
457 Get reltool configuration. Shorthand for reltool:get_con‐
459 fig(Server,false,false).
460 get_config(Server, InclDefaults, InclDerived) -> {ok, Config} | {error,
462 Reason}
463 Types:
465 Server = server()
467 InclDefaults = incl_defaults()
468 InclDerived = incl_derived()
469 Config = config()
470 Reason = reason()
471 Get reltool configuration. Normally, only the explicit configu‐
473 ration parameters with values that differ from their defaults
474 are interesting. But the builtin default values can be returned
475 by setting InclDefaults to true. The derived configuration can
476 be returned by setting InclDerived to true.
477 get_rel(Server, Relname) -> {ok, RelFile} | {error, Reason}
479 Types:
481 Server = server()
483 RelName = rel_name()
484 RelFile = rel_file()
485 Reason = reason()
486 Get contents of a release file. See rel(4) for more details.
488 get_script(Server, Relname) -> {ok, ScriptFile | {error, Reason}
490 Types:
492 Server = server()
494 RelName = rel_name()
495 ScriptFile = script_file()
496 Reason = reason()
497 Get contents of a boot script file. See script(4) for more de‐
499 tails.
500 get_status(Server) -> {ok, [Warning]} | {error, Reason}
502 Types:
504 Server = server()
506 Warning = string()
507 Reason = reason()
508 Get status about the configuration
510 get_server(WindowPid) -> {ok, ServerPid} | {error, Reason}
512 Types:
514 WindowPid = window_pid()
516 ServerPid = server_pid()
517 Reason = reason()
518 Return the process identifier of the server process.
520 get_target_spec(Server) -> {ok, TargetSpec} | {error, Reason}
522 Types:
524 Server = server()
526 TargetSpec = target_spec()
527 Reason = reason()
528 Return a specification of the target system. The actual target
530 system can be created with reltool:eval_target_spec/3.
531 install(RelName, TargetDir) -> ok | {error, Reason}
533 Types:
535 RelName = rel_name()
537 TargetDir = target_dir()
538 Reason = reason()
539 Install a created target system
541 start() -> {ok, WindowPid} | {error, Reason}
543 Types:
545 WindowPid = window_pid()
547 Reason = reason()
548 Start a main window process with default options
550 start(Options) -> {ok, WindowPid} | {error, Reason}
552 Types:
554 Options = options()
556 WindowPid = window_pid()
557 Reason = reason()
558 Start a main window process with options
560 start_link(Options) -> {ok, WindowPid} | {error, Reason}
562 Types:
564 Options = options()
566 WindowPid = window_pid()
567 Reason = reason()
568 Start a main window process with options. The process is linked.
570 start_server(Options) -> {ok, ServerPid} | {error, Reason}
572 Types:
574 Options = options()
576 ServerPid = server_pid()
577 Reason = reason()
578 Start a server process with options. The server process identity
580 can be given as an argument to several other functions in the
581 API.
582 stop(Pid) -> ok | {error, Reason}
584 Types:
586 Pid = server_pid() | window_pid()
588 Reason = reason()
589 Stop a server or window process
591Ericsson AB reltool 1.0 reltool(3)