1reltool(3)                 Erlang Module Definition                 reltool(3)
2
3
4

NAME

6       reltool - Main API of the Reltool application
7

DESCRIPTION

9       This is an interface module for the Reltool application.
10
11       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
17       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
24       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
28       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
32       Finally single  modules  and  entire  applications  may  be  read  from
33       Escripts.
34
35       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
42       The following top level options are supported:
43
44         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
49         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
54         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
58       Besides  the already mentioned source parameters root_dir and lib_dirs,
59       the following system (sys) level options are supported:
60
61         erts:
62           Erts specific configuration. See application level options below.
63
64         escript:
65           Escript specific configuration. An escript  has  a  mandatory  file
66           name and escript level options that are described below.
67
68         app:
69           Application  specific configuration. An application has a mandatory
70           name and application level options that are described below.
71
72         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
86         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
96         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
100         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
107         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
116         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
130         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
142         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
147         excl_lib:
148
149
150     Warning:
151         This option is experimental.
152
153
154           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
163           When starting this release, three things must be specified:
164
165           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
172           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
178           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
185           Example:
186
187         erl -sasl releases_dir \"mytarget/releases\" -boot mytarget/releases/1.0/myrel\
188          -boot_var RELTOOL_EXT_LIB mytarget/lib
189
190         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
200         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
207         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
215         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
222         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
232         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
240         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
247       On application (escript) level, the following options are supported:
248
249         incl_cond:
250           The  value  of this parameter overrides the parameter with the same
251           name on system level.
252
253       On application (app) level, the following options are supported:
254
255         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
260           This parameter is mutual exclusive with lib_dir. If vsn and lib_dir
261           are both omitted, the latest version will be chosen.
262
263           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
268         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
274           This parameter is mutual exclusive with vsn. If vsn and lib_dir are
275           both omitted, the latest version will be chosen.
276
277           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
282         mod:
283           Module  specific  configuration.  A module has a mandatory name and
284           module level options that are described below.
285
286         mod_cond:
287           The value of this parameter overrides the parameter with  the  same
288           name on system level.
289
290         incl_cond:
291           The  value  of this parameter overrides the parameter with the same
292           name on system level.
293
294         app_file:
295           The value of this parameter overrides the parameter with  the  same
296           name on system level.
297
298         debug_info:
299           The  value  of this parameter overrides the parameter with the same
300           name on system level.
301
302         incl_app_filters:
303           The value of this parameter overrides the parameter with  the  same
304           name on system level.
305
306         excl_app_filters:
307           The  value  of this parameter overrides the parameter with the same
308           name on system level.
309
310         incl_archive_filters:
311           The value of this parameter overrides the parameter with  the  same
312           name on system level.
313
314         excl_archive_filters:
315           The  value  of this parameter overrides the parameter with the same
316           name on system level.
317
318         archive_opts:
319           The value of this parameter overrides the parameter with  the  same
320           name on system level.
321
322       On module (mod) level, the following options are supported:
323
324         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
333         debug_info:
334           The  value  of this parameter overrides the parameter with the same
335           name on application level.
336

DATA TYPES

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

EXPORTS

437       create_target(Server, TargetDir) -> ok | {error, Reason}
438
439              Types:
440
441                 Server = server()
442                 TargetDir = target_dir()
443                 Reason = reason()
444
445              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
449       eval_target_spec(TargetSpec, RootDir, TargetDir) -> ok |  {error,  Rea‐
450       son}
451
452              Types:
453
454                 TargetSpec = target_spec()
455                 RootDir = root_dir()
456                 TargetDir = target_dir()
457                 Reason = reason()
458
459              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
470              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
481              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
486              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
494       get_config(Server) -> {ok, Config} | {error, Reason}
495
496              Types:
497
498                 Server = server()
499                 Config = config()
500                 Reason = reason()
501
502              Get  reltool  configuration.  Shorthand   for   reltool:get_con‐
503              fig(Server,false,false).
504
505       get_config(Server, InclDefaults, InclDerived) -> {ok, Config} | {error,
506       Reason}
507
508              Types:
509
510                 Server = server()
511                 InclDefaults = incl_defaults()
512                 InclDerived = incl_derived()
513                 Config = config()
514                 Reason = reason()
515
516              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
522       get_rel(Server, Relname) -> {ok, RelFile} | {error, Reason}
523
524              Types:
525
526                 Server = server()
527                 RelName = rel_name()
528                 RelFile = rel_file()
529                 Reason = reason()
530
531              Get contents of a release file. See rel(4) for more details.
532
533       get_script(Server, Relname) -> {ok, ScriptFile | {error, Reason}
534
535              Types:
536
537                 Server = server()
538                 RelName = rel_name()
539                 ScriptFile = script_file()
540                 Reason = reason()
541
542              Get contents of a boot  script  file.  See  script(4)  for  more
543              details.
544
545       get_status(Server) -> {ok, [Warning]} | {error, Reason}
546
547              Types:
548
549                 Server = server()
550                 Warning = string()
551                 Reason = reason()
552
553              Get status about the configuration
554
555       get_server(WindowPid) -> {ok, ServerPid} | {error, Reason}
556
557              Types:
558
559                 WindowPid = window_pid()
560                 ServerPid = server_pid()
561                 Reason = reason()
562
563              Return the process identifier of the server process.
564
565       get_target_spec(Server) -> {ok, TargetSpec} | {error, Reason}
566
567              Types:
568
569                 Server = server()
570                 TargetSpec = target_spec()
571                 Reason = reason()
572
573              Return  a  specification of the target system. The actual target
574              system can be created with reltool:eval_target_spec/3.
575
576       install(RelName, TargetDir) -> ok | {error, Reason}
577
578              Types:
579
580                 RelName = rel_name()
581                 TargetDir = target_dir()
582                 Reason = reason()
583
584              Install a created target system
585
586       start() -> {ok, WindowPid} | {error, Reason}
587
588              Types:
589
590                 WindowPid = window_pid()
591                 Reason = reason()
592
593              Start a main window process with default options
594
595       start(Options) -> {ok, WindowPid} | {error, Reason}
596
597              Types:
598
599                 Options = options()
600                 WindowPid = window_pid()
601                 Reason = reason()
602
603              Start a main window process with options
604
605       start_link(Options) -> {ok, WindowPid} | {error, Reason}
606
607              Types:
608
609                 Options = options()
610                 WindowPid = window_pid()
611                 Reason = reason()
612
613              Start a main window process with options. The process is linked.
614
615       start_server(Options) -> {ok, ServerPid} | {error, Reason}
616
617              Types:
618
619                 Options = options()
620                 ServerPid = server_pid()
621                 Reason = reason()
622
623              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
627       stop(Pid) -> ok | {error, Reason}
628
629              Types:
630
631                 Pid = server_pid() | window_pid()
632                 Reason = reason()
633
634              Stop a server or window process
635
636
637
638Ericsson AB                      reltool 0.7.8                      reltool(3)
Impressum