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 whether the debug information in
144 the beam file should be kept (keep) or stripped strip when the file
145 is copied to the target system.
146 excl_lib:
148 Warning:
151 This option is experimental.
152 If the excl_lib option is set to otp_root then reltool will not
155 copy anything from the Erlang/OTP installation ($OTP_ROOT) into the
156 target structure. The goal is to create a "slim" release which can
157 be used together with an existing Erlang/OTP installation. The tar‐
158 get structure will therefore only contain a lib directory with the
159 applications that were found outside of $OTP_ROOT (typically your
160 own applications), and a releases directory with the generated
161 .rel, .script and .boot files.
162 When starting this release, three things must be specified:
164 Which releases directory to use:
166 Tell the release handler to use the releases directory in our
167 target structure instead of $OTP_ROOT/releases. This is done by
168 setting the SASL environment variable releases_dir, either from
169 the command line (-sasl releases_dir <target-dir>/releases) or in
170 sys.config.
171 Which boot file to use:
173 The default boot file is $OTP_ROOT/bin/start, but in this case we
174 need to specify a boot file from our target structure, typically
175 <target-dir>/releases/<vsn>/<RelName>. This is done with the
176 -boot command line option to erl
177 The location of our applications:
179 The generated .script (and .boot) file uses the environment vari‐
180 able $RELTOOL_EXT_LIB as prefix for the paths to all applica‐
181 tions. The -boot_var option to erl can be used for specifying the
182 value of this variable, typically -boot_var RELTOOL_EXT_LIB <tar‐
183 get-dir>/lib.
184 Example:
186 erl -sasl releases_dir \"mytarget/releases\" -boot mytarget/releases/1.0/myrel\
188 -boot_var RELTOOL_EXT_LIB mytarget/lib
189 incl_sys_filters:
191 This parameter normally contains a list of regular expressions that
192 controls which files in the system should be included. Each file in
193 the target system must match at least one of the listed regular ex‐
194 pressions in order to be included. Further the files may not match
195 any filter in excl_sys_filters in order to be included. Which ap‐
196 plication files should be included is controlled with the parame‐
197 ters incl_app_filters and excl_app_filters. This parameter defaults
198 to [".*"].
199 excl_sys_filters:
201 This parameter normally contains a list of regular expressions that
202 controls which files in the system should not be included in the
203 target system. In order to be included, a file must match some fil‐
204 ter in incl_sys_filters but not any filter in excl_sys_filters.
205 This parameter defaults to [].
206 incl_app_filters:
208 This parameter normally contains a list of regular expressions that
209 controls which application specific files that should be included.
210 Each file in the application must match at least one of the listed
211 regular expressions in order to be included. Further the files may
212 not match any filter in excl_app_filters in order to be included.
213 This parameter defaults to [".*"].
214 excl_app_filters:
216 This parameter normally contains a list of regular expressions that
217 controls which application specific files should not be included in
218 the target system. In order to be included, a file must match some
219 filter in incl_app_filters but not any filter in excl_app_filters.
220 This parameter defaults to [].
221 incl_archive_filters:
223 This parameter normally contains a list of regular expressions that
224 controls which top level directories in an application should be
225 included in an archive file (as opposed to being included as a reg‐
226 ular directory outside the archive). Each top directory in the ap‐
227 plication must match at least one of the listed regular expressions
228 in order to be included. Further the files may not match any filter
229 in excl_app_filters in order to be included. This parameter de‐
230 faults to [".*"].
231 excl_archive_filters:
233 This parameter normally contains a list of regular expressions that
234 controls which top level directories in an application should not
235 be included in an archive file. In order to be included in the ap‐
236 plication archive, a top directory must match some filter in
237 incl_archive_filters but not any filter in excl_archive_filters.
238 This parameter defaults to ["^include$","^priv$"].
239 archive_opts:
241 This parameter contains a list of options that are given to
242 zip:create/3 when application specific files are packaged into an
243 archive. Only a subset of the options are supported. The most use‐
244 ful options in this context are the ones that control which types
245 of files should be compressed. This parameter defaults to [].
246 On application (escript) level, the following options are supported:
248 incl_cond:
250 The value of this parameter overrides the parameter with the same
251 name on system level.
252 On application (app) level, the following options are supported:
254 vsn:
256 The version of the application. In an installed system there may
257 exist several versions of an application. The vsn parameter con‐
258 trols which version of the application will be chosen.
259 This parameter is mutual exclusive with lib_dir. If vsn and lib_dir
261 are both omitted, the latest version will be chosen.
262 Note that in order for reltool to sort application versions and
264 thereby be able to select the latest, it is required that the ver‐
265 sion id for the application consists of integers and dots only, for
266 example 1, 2.0 or 3.17.1.
267 lib_dir:
269 The directory to read the application from. This parameter can be
270 used to point out a specific location to fetch the application
271 from. This is useful for instance if the parent directory for some
272 reason is no good as a library directory on system level.
273 This parameter is mutual exclusive with vsn. If vsn and lib_dir are
275 both omitted, the latest version will be chosen.
276 Note that in order for reltool to sort application versions and
278 thereby be able to select the latest, it is required that the ver‐
279 sion id for the application consists of integers and dots only, for
280 example 1, 2.0 or 3.17.1.
281 mod:
283 Module specific configuration. A module has a mandatory name and
284 module level options that are described below.
285 mod_cond:
287 The value of this parameter overrides the parameter with the same
288 name on system level.
289 incl_cond:
291 The value of this parameter overrides the parameter with the same
292 name on system level.
293 app_file:
295 The value of this parameter overrides the parameter with the same
296 name on system level.
297 debug_info:
299 The value of this parameter overrides the parameter with the same
300 name on system level.
301 incl_app_filters:
303 The value of this parameter overrides the parameter with the same
304 name on system level.
305 excl_app_filters:
307 The value of this parameter overrides the parameter with the same
308 name on system level.
309 incl_archive_filters:
311 The value of this parameter overrides the parameter with the same
312 name on system level.
313 excl_archive_filters:
315 The value of this parameter overrides the parameter with the same
316 name on system level.
317 archive_opts:
319 The value of this parameter overrides the parameter with the same
320 name on system level.
321 On module (mod) level, the following options are supported:
323 incl_cond:
325 This parameter controls whether the module is included or not. By
326 default the mod_cond parameter on application and system level will
327 be used to control whether the module is included or not. The value
328 of incl_cond overrides the module inclusion policy. include implies
329 that the module is included, while exclude implies that the module
330 is not included. derived implies that the module is included if it
331 is used by any other included module.
332 debug_info:
334 The value of this parameter overrides the parameter with the same
335 name on application level.
336
338 options() = [option()]
339 option() = {config, config() | file()}
340 | {trap_exit, bool()}
341 | {wx_debug, term()}
342 config() = {sys, [sys()]}
343 sys() = {root_dir, root_dir()}
344 | {lib_dirs, [lib_dir()]}
345 | {profile, profile()}
346 | {erts, app()}
347 | {escript, escript_file(), [escript()]}
348 | {app, app_name(), [app()]}
349 | {mod_cond, mod_cond()}
350 | {incl_cond, incl_cond()}
351 | {boot_rel, boot_rel()}
352 | {rel, rel_name(), rel_vsn(), [rel_app()]}
353 | {rel, rel_name(), rel_vsn(), [rel_app()], [rel_opt()]}
354 | {relocatable, relocatable()}
355 | {app_file, app_file()}
356 | {debug_info, debug_info()}
357 | {incl_sys_filters, incl_sys_filters()}
358 | {excl_sys_filters, excl_sys_filters()}
359 | {incl_app_filters, incl_app_filters()}
360 | {excl_app_filters, excl_app_filters()}
361 | {incl_archive_filters, incl_archive_filters()}
362 | {excl_archive_filters, excl_archive_filters()}
363 | {archive_opts, [archive_opt()]}
364 app() = {vsn, app_vsn()}
365 | {lib_dir, lib_dir()}
366 | {mod, mod_name(), [mod()]}
367 | {mod_cond, mod_cond()}
368 | {incl_cond, incl_cond()}
369 | {debug_info, debug_info()}
370 | {app_file, app_file()}
371 | {excl_lib, excl_lib()}
372 | {incl_sys_filters, incl_sys_filters()}
373 | {excl_sys_filters, excl_sys_filters()}
374 | {incl_app_filters, incl_app_filters()}
375 | {excl_app_filters, excl_app_filters()}
376 | {incl_archive_filters, incl_archive_filters()}
377 | {excl_archive_filters, excl_archive_filters()}
378 | {archive_opts, [archive_opt()]}
379 mod() = {incl_cond, incl_cond()}
380 | {debug_info, debug_info()}
381 rel_app() = app_name()
382 | {app_name(), app_type()}
383 | {app_name(), [incl_app()]}
384 | {app_name(), app_type(), [incl_app()]}
385 rel_opt() = {load_dot_erlang, boolean()}
386 app_name() = atom()
387 app_type() = permanent | transient | temporary | load | none
388 app_vsn() = string()
389 archive_opt = zip_create_opt()
390 boot_rel() = rel_name()
391 app_file() = keep | strip | all
392 debug_info() = keep | strip
393 dir() = string()
394 escript() = {incl_cond, incl_cond()}
395 escript_file() = file()
396 excl_app_filters() = regexps()
397 excl_archive_filters() = regexps()
398 excl_lib() = otp_root
399 excl_sys_filters() = regexps()
400 file() = string()
401 incl_app() = app_name()
402 incl_app_filters() = regexps()
403 incl_archive_filters() = regexps()
404 incl_cond() = include | exclude | derived
405 incl_sys_filters() = regexps()
406 lib_dir() = dir()
407 mod_cond() = all | app | ebin | derived | none
408 mod_name() = atom()
409 profile() = development | embedded | standalone
410 re_regexp() = string()
411 reason() = string()
412 regexps() = [re_regexp()]
413 | {add, [re_regexp()]}
414 | {del, [re_regexp()]}
415 rel_file() = term()
416 rel_name() = string()
417 rel_vsn() = string()
418 relocatable = boolean()
419 root_dir() = dir()
420 script_file() = term()
421 server() = server_pid() | options()
422 server_pid() = pid()
423 target_dir() = file()
424 window_pid() = pid()
425 base_dir() = dir()
426 base_file() = file()
427 top_dir() = file()
428 top_file() = file()
429 target_spec() = [target_spec()]
430 | {create_dir, base_dir(), [target_spec()]}
431 | {create_dir, base_dir(), top_dir(), [target_spec()]}
432 | {archive, base_file(), [archive_opt()], [target_spec()]}
433 | {copy_file, base_file()}
434 | {copy_file, base_file(), top_file()}
435 | {write_file, base_file(), iolist()}
436 | {strip_beam_file, base_file()}
437
439 create_target(Server, TargetDir) -> ok | {error, Reason}
440 Types:
442 Server = server()
444 TargetDir = target_dir()
445 Reason = reason()
446 Create a target system. Gives the same result as {ok,Target‐
448 Spec}=reltool:get_target_spec(Server) and reltool:eval_tar‐
449 get_spec(TargetSpec,RootDir,TargetDir).
450 eval_target_spec(TargetSpec, RootDir, TargetDir) -> ok | {error, Rea‐
452 son}
453 Types:
455 TargetSpec = target_spec()
457 RootDir = root_dir()
458 TargetDir = target_dir()
459 Reason = reason()
460 Create the actual target system from a specification generated
462 by reltool:get_target_spec/1. The creation of the specification
463 for a target system is performed in two steps. In the first step
464 a complete specification will be generated. It will likely con‐
465 tain much more files than you are interested in in your target
466 system. In the second step the specification will be filtered
467 according to your filters. There you have the ability to specify
468 filters per application as well as system wide filters. You can
469 also select a profile for your system. Depending on the profile,
470 different default filters will be used.
471 The top directories bin, releases and lib are treated differ‐
473 ently from other files. All other files are by default copied to
474 the target system. The releases directory contains generated
475 rel, script, and boot files. The lib directory contains the ap‐
476 plications. Which applications are included and if they should
477 be customized (archived, stripped from debug info etc.) is spec‐
478 ified with various configuration parameters. The files in the
479 bin directory are copied from the erts-vsn/bin directory, but
480 only those files that were originally included in the bin direc‐
481 tory of the source system.
482 If the configuration parameter relocatable was set to true there
484 is no need to install the target system with reltool:install/2
485 before it can be started. In that case the file tree containing
486 the target system can be moved without re-installation.
487 In most cases, the RootDir parameter should be set to the same
489 as the root_dir configuration parameter used in the call to rel‐
490 tool:get_target_spec/1 (or code:root_dir() if the configuration
491 parameter is not set). In some cases it might be useful to eval‐
492 uate the same target specification towards different root direc‐
493 tories. This should, however, be used with great care as it re‐
494 quires equivalent file structures under all roots.
495 get_config(Server) -> {ok, Config} | {error, Reason}
497 Types:
499 Server = server()
501 Config = config()
502 Reason = reason()
503 Get reltool configuration. Shorthand for reltool:get_con‐
505 fig(Server,false,false).
506 get_config(Server, InclDefaults, InclDerived) -> {ok, Config} | {error,
508 Reason}
509 Types:
511 Server = server()
513 InclDefaults = incl_defaults()
514 InclDerived = incl_derived()
515 Config = config()
516 Reason = reason()
517 Get reltool configuration. Normally, only the explicit configu‐
519 ration parameters with values that differ from their defaults
520 are interesting. But the builtin default values can be returned
521 by setting InclDefaults to true. The derived configuration can
522 be returned by setting InclDerived to true.
523 get_rel(Server, Relname) -> {ok, RelFile} | {error, Reason}
525 Types:
527 Server = server()
529 RelName = rel_name()
530 RelFile = rel_file()
531 Reason = reason()
532 Get contents of a release file. See rel(4) for more details.
534 get_script(Server, Relname) -> {ok, ScriptFile | {error, Reason}
536 Types:
538 Server = server()
540 RelName = rel_name()
541 ScriptFile = script_file()
542 Reason = reason()
543 Get contents of a boot script file. See script(4) for more de‐
545 tails.
546 get_status(Server) -> {ok, [Warning]} | {error, Reason}
548 Types:
550 Server = server()
552 Warning = string()
553 Reason = reason()
554 Get status about the configuration
556 get_server(WindowPid) -> {ok, ServerPid} | {error, Reason}
558 Types:
560 WindowPid = window_pid()
562 ServerPid = server_pid()
563 Reason = reason()
564 Return the process identifier of the server process.
566 get_target_spec(Server) -> {ok, TargetSpec} | {error, Reason}
568 Types:
570 Server = server()
572 TargetSpec = target_spec()
573 Reason = reason()
574 Return a specification of the target system. The actual target
576 system can be created with reltool:eval_target_spec/3.
577 install(RelName, TargetDir) -> ok | {error, Reason}
579 Types:
581 RelName = rel_name()
583 TargetDir = target_dir()
584 Reason = reason()
585 Install a created target system
587 start() -> {ok, WindowPid} | {error, Reason}
589 Types:
591 WindowPid = window_pid()
593 Reason = reason()
594 Start a main window process with default options
596 start(Options) -> {ok, WindowPid} | {error, Reason}
598 Types:
600 Options = options()
602 WindowPid = window_pid()
603 Reason = reason()
604 Start a main window process with options
606 start_link(Options) -> {ok, WindowPid} | {error, Reason}
608 Types:
610 Options = options()
612 WindowPid = window_pid()
613 Reason = reason()
614 Start a main window process with options. The process is linked.
616 start_server(Options) -> {ok, ServerPid} | {error, Reason}
618 Types:
620 Options = options()
622 ServerPid = server_pid()
623 Reason = reason()
624 Start a server process with options. The server process identity
626 can be given as an argument to several other functions in the
627 API.
628 stop(Pid) -> ok | {error, Reason}
630 Types:
632 Pid = server_pid() | window_pid()
634 Reason = reason()
635 Stop a server or window process
637Ericsson AB reltool 0.9 reltool(3)