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
19 executing 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
33 Escripts.
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
38 application 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
51 default the window processes traps exit, but this behavior can
52 altered 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
76 included. This implies that both modules that exist in the ebin
77 directory 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
80 included. 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
103 details. Each release has a name, a version and a set of applica‐
104 tions with a few release specific parameters such as type and
105 included 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
112 before 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,
126 embedded and standalone. development is default. The parameters
127 that are affected by the profile are: incl_sys_filters,
128 excl_sys_filters, 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
194 expressions in order to be included. Further the files may not
195 match any filter in excl_sys_filters in order to be included. Which
196 application 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
227 application must match at least one of the listed regular expres‐
228 sions in order to be included. Further the files may not match any
229 filter in excl_app_filters in order to be included. This parameter
230 defaults 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
236 application 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 consits 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 consits 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 | {relocatable, relocatable()}
354 | {app_file, app_file()}
355 | {debug_info, debug_info()}
356 | {incl_sys_filters, incl_sys_filters()}
357 | {excl_sys_filters, excl_sys_filters()}
358 | {incl_app_filters, incl_app_filters()}
359 | {excl_app_filters, excl_app_filters()}
360 | {incl_archive_filters, incl_archive_filters()}
361 | {excl_archive_filters, excl_archive_filters()}
362 | {archive_opts, [archive_opt()]}
363 app() = {vsn, app_vsn()}
364 | {lib_dir, lib_dir()}
365 | {mod, mod_name(), [mod()]}
366 | {mod_cond, mod_cond()}
367 | {incl_cond, incl_cond()}
368 | {debug_info, debug_info()}
369 | {app_file, app_file()}
370 | {excl_lib, excl_lib()}
371 | {incl_sys_filters, incl_sys_filters()}
372 | {excl_sys_filters, excl_sys_filters()}
373 | {incl_app_filters, incl_app_filters()}
374 | {excl_app_filters, excl_app_filters()}
375 | {incl_archive_filters, incl_archive_filters()}
376 | {excl_archive_filters, excl_archive_filters()}
377 | {archive_opts, [archive_opt()]}
378 mod() = {incl_cond, incl_cond()}
379 | {debug_info, debug_info()}
380 rel_app() = app_name()
381 | {app_name(), app_type()}
382 | {app_name(), [incl_app()]}
383 | {app_name(), app_type(), [incl_app()]}
384 app_name() = atom()
385 app_type() = permanent | transient | temporary | load | none
386 app_vsn() = string()
387 archive_opt = zip_create_opt()
388 boot_rel() = rel_name()
389 app_file() = keep | strip | all
390 debug_info() = keep | strip
391 dir() = string()
392 escript() = {incl_cond, incl_cond()}
393 escript_file() = file()
394 excl_app_filters() = regexps()
395 excl_archive_filters() = regexps()
396 excl_lib() = otp_root
397 excl_sys_filters() = regexps()
398 file() = string()
399 incl_app() = app_name()
400 incl_app_filters() = regexps()
401 incl_archive_filters() = regexps()
402 incl_cond() = include | exclude | derived
403 incl_sys_filters() = regexps()
404 lib_dir() = dir()
405 mod_cond() = all | app | ebin | derived | none
406 mod_name() = atom()
407 profile() = development | embedded | standalone
408 re_regexp() = string()
409 reason() = string()
410 regexps() = [re_regexp()]
411 | {add, [re_regexp()]}
412 | {del, [re_regexp()]}
413 rel_file() = term()
414 rel_name() = string()
415 rel_vsn() = string()
416 relocatable = boolean()
417 root_dir() = dir()
418 script_file() = term()
419 server() = server_pid() | options()
420 server_pid() = pid()
421 target_dir() = file()
422 window_pid() = pid()
423 base_dir() = dir()
424 base_file() = file()
425 top_dir() = file()
426 top_file() = file()
427 target_spec() = [target_spec()]
428 | {create_dir, base_dir(), [target_spec()]}
429 | {create_dir, base_dir(), top_dir(), [target_spec()]}
430 | {archive, base_file(), [archive_opt()], [target_spec()]}
431 | {copy_file, base_file()}
432 | {copy_file, base_file(), top_file()}
433 | {write_file, base_file(), iolist()}
434 | {strip_beam_file, base_file()}
435
437 create_target(Server, TargetDir) -> ok | {error, Reason}
438 Types:
440 Server = server()
442 TargetDir = target_dir()
443 Reason = reason()
444 Create a target system. Gives the same result as {ok,Target‐
446 Spec}=reltool:get_target_spec(Server) and reltool:eval_tar‐
447 get_spec(TargetSpec,RootDir,TargetDir).
448 eval_target_spec(TargetSpec, RootDir, TargetDir) -> ok | {error, Rea‐
450 son}
451 Types:
453 TargetSpec = target_spec()
455 RootDir = root_dir()
456 TargetDir = target_dir()
457 Reason = reason()
458 Create the actual target system from a specification generated
460 by reltool:get_target_spec/1. The creation of the specification
461 for a target system is performed in two steps. In the first step
462 a complete specification will be generated. It will likely con‐
463 tain much more files than you are interested in in your target
464 system. In the second step the specification will be filtered
465 according to your filters. There you have the ability to specify
466 filters per application as well as system wide filters. You can
467 also select a profile for your system. Depending on the profile,
468 different default filters will be used.
469 The top directories bin, releases and lib are treated differ‐
471 ently from other files. All other files are by default copied to
472 the target system. The releases directory contains generated
473 rel, script, and boot files. The lib directory contains the
474 applications. Which applications are included and if they should
475 be customized (archived, stripped from debug info etc.) is spec‐
476 ified with various configuration parameters. The files in the
477 bin directory are copied from the erts-vsn/bin directory, but
478 only those files that were originally included in the bin direc‐
479 tory of the source system.
480 If the configuration parameter relocatable was set to true there
482 is no need to install the target system with reltool:install/2
483 before it can be started. In that case the file tree containing
484 the target system can be moved without re-installation.
485 In most cases, the RootDir parameter should be set to the same
487 as the root_dir configuration parameter used in the call to rel‐
488 tool:get_target_spec/1 (or code:root_dir() if the configuration
489 parameter is not set). In some cases it might be useful to eval‐
490 uate the same target specification towards different root direc‐
491 tories. This should, however, be used with great care as it
492 requires equivalent file structures under all roots.
493 get_config(Server) -> {ok, Config} | {error, Reason}
495 Types:
497 Server = server()
499 Config = config()
500 Reason = reason()
501 Get reltool configuration. Shorthand for reltool:get_con‐
503 fig(Server,false,false).
504 get_config(Server, InclDefaults, InclDerived) -> {ok, Config} | {error,
506 Reason}
507 Types:
509 Server = server()
511 InclDefaults = incl_defaults()
512 InclDerived = incl_derived()
513 Config = config()
514 Reason = reason()
515 Get reltool configuration. Normally, only the explicit configu‐
517 ration parameters with values that differ from their defaults
518 are interesting. But the builtin default values can be returned
519 by setting InclDefaults to true. The derived configuration can
520 be returned by setting InclDerived to true.
521 get_rel(Server, Relname) -> {ok, RelFile} | {error, Reason}
523 Types:
525 Server = server()
527 RelName = rel_name()
528 RelFile = rel_file()
529 Reason = reason()
530 Get contents of a release file. See rel(4) for more details.
532 get_script(Server, Relname) -> {ok, ScriptFile | {error, Reason}
534 Types:
536 Server = server()
538 RelName = rel_name()
539 ScriptFile = script_file()
540 Reason = reason()
541 Get contents of a boot script file. See script(4) for more
543 details.
544 get_status(Server) -> {ok, [Warning]} | {error, Reason}
546 Types:
548 Server = server()
550 Warning = string()
551 Reason = reason()
552 Get status about the configuration
554 get_server(WindowPid) -> {ok, ServerPid} | {error, Reason}
556 Types:
558 WindowPid = window_pid()
560 ServerPid = server_pid()
561 Reason = reason()
562 Return the process identifier of the server process.
564 get_target_spec(Server) -> {ok, TargetSpec} | {error, Reason}
566 Types:
568 Server = server()
570 TargetSpec = target_spec()
571 Reason = reason()
572 Return a specification of the target system. The actual target
574 system can be created with reltool:eval_target_spec/3.
575 install(RelName, TargetDir) -> ok | {error, Reason}
577 Types:
579 RelName = rel_name()
581 TargetDir = target_dir()
582 Reason = reason()
583 Install a created target system
585 start() -> {ok, WindowPid} | {error, Reason}
587 Types:
589 WindowPid = window_pid()
591 Reason = reason()
592 Start a main window process with default options
594 start(Options) -> {ok, WindowPid} | {error, Reason}
596 Types:
598 Options = options()
600 WindowPid = window_pid()
601 Reason = reason()
602 Start a main window process with options
604 start_link(Options) -> {ok, WindowPid} | {error, Reason}
606 Types:
608 Options = options()
610 WindowPid = window_pid()
611 Reason = reason()
612 Start a main window process with options. The process is linked.
614 start_server(Options) -> {ok, ServerPid} | {error, Reason}
616 Types:
618 Options = options()
620 ServerPid = server_pid()
621 Reason = reason()
622 Start a server process with options. The server process identity
624 can be given as an argument to several other functions in the
625 API.
626 stop(Pid) -> ok | {error, Reason}
628 Types:
630 Pid = server_pid() | window_pid()
632 Reason = reason()
633 Stop a server or window process
635Ericsson AB reltool 0.7.8 reltool(3)