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 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
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  Es‐
33       cripts.
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 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
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 de‐
51           fault  the  window  processes traps exit, but this behavior can al‐
52           tered 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  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
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  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
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 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
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, 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
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 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
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  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
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  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
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 consists 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 consists 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                           | {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

EXPORTS

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