diff options
Diffstat (limited to 'lib/reltool/doc/src/reltool.xml')
| -rw-r--r-- | lib/reltool/doc/src/reltool.xml | 245 |
1 files changed, 135 insertions, 110 deletions
diff --git a/lib/reltool/doc/src/reltool.xml b/lib/reltool/doc/src/reltool.xml index 9786928ae8..31e15e34e7 100644 --- a/lib/reltool/doc/src/reltool.xml +++ b/lib/reltool/doc/src/reltool.xml @@ -5,7 +5,7 @@ <header> <copyright> <year>2009</year> - <year>2009</year> + <year>2011</year> <holder>Ericsson AB, All Rights Reserved</holder> </copyright> <legalnotice> @@ -48,8 +48,8 @@ <c>root_dir</c> is the root directory of the analysed system and it defaults to the system executing <c>reltool</c>. Applications may also be located outside <c>root_dir</c>. <c>lib_dirs</c> - defines additional library directories where applications - additional may reside and it defaults to the the directories + defines library directories where additional applications + may reside and it defaults to the directories listed by the operating system environment variable <c>ERL_LIBS</c>. See the module <c>code</c> for more info. Finally single modules and entire applications may be read from @@ -58,23 +58,23 @@ <p>Some configuration parameters control the behavior of Reltool on system (<c>sys</c>) level. Others provide control on application (<c>app</c>) level and yet others are on module - (<c>mod</c>) level. Module level parameters overrides application - level parameters and application level parameters overrides system + (<c>mod</c>) level. Module level parameters override application + level parameters and application level parameters override system level parameters. Escript <c>escript</c> level parameters - overrides system level parameters.</p> + override system level parameters.</p> <p>The following top level <c>options</c> are supported:</p> <taglist> - <tag><c><![CDATA[config]]></c></tag> + <tag><c>config</c></tag> <item> <p>This is the main option and it controls the configuration of <c>reltool</c>. It can either be a <c>sys</c> tuple or a name of a <c>file</c> containing a sys tuple.</p> </item> - <tag><c><![CDATA[trap_exit]]></c></tag> + <tag><c>trap_exit</c></tag> <item> <p>This option controls the error handling behavior of <c>reltool</c>. By default the window processes traps @@ -82,7 +82,7 @@ <c>trap_exit</c> to <c>false</c>.</p> </item> - <tag><c><![CDATA[wx_debug]]></c></tag> + <tag><c>wx_debug</c></tag> <item> <p>This option controls the debug level of <c>wx</c>. As its name indicates it is only useful for debugging. See @@ -97,36 +97,36 @@ <taglist> - <tag><c><![CDATA[erts]]></c></tag> + <tag><c>erts</c></tag> <item> <p>Erts specific configuration. See application level options below.</p> </item> - <tag><c><![CDATA[escript]]></c></tag> + <tag><c>escript</c></tag> <item> <p>Escript specific configuration. An escript has a mandatory file name and escript level options that are described below.</p> </item> - <tag><c><![CDATA[app]]></c></tag> + <tag><c>app</c></tag> <item> <p>Application specific configuration. An application has a mandatory name and application level options that are described below.</p> </item> - <tag><c><![CDATA[mod_cond]]></c></tag> + <tag><c>mod_cond</c></tag> <item> <p>This parameter controls the module inclusion policy. It defaults to <c>all</c> which means that if an application is included (either explicitly or implicitly) all modules in that application will be included. This implies that both modules - that exists on the <c>ebin</c> directory of the application, + that exist in the <c>ebin</c> directory of the application, as well as modules that are named in the <c>app</c> file will be included. If the parameter is set to <c>ebin</c>, both - modules on the <c>ebin</c> directory and derived modules are + modules in the <c>ebin</c> directory and derived modules are included. If the parameter is set to <c>app</c>, both modules in the <c>app</c> file and derived modules are included. <c>derived</c> means that only modules that are used by other @@ -134,69 +134,69 @@ system level is used as default for all applications.</p> </item> - <tag><c><![CDATA[incl_cond]]></c></tag> + <tag><c>incl_cond</c></tag> <item> - <p>This parameter controls the application and escript - inclusion policy. It defaults to <c>derived</c> which means - that the applications that not have any explicit - <c>incl_cond</c> setting, will only be included if any other - (explicitly or implicitly included) application uses it. The - value <c>include</c> implies that all applications and - escripts that that not have any explicit <c>incl_cond</c> - setting will be included. <c>exclude</c> implies that all - applications and escripts) that that not have any explicit - <c>incl_cond</c> setting will be excluded.</p> + <p>This parameter controls the application and escript + inclusion policy. It defaults to <c>derived</c> which means + that the applications that do not have any explicit + <c>incl_cond</c> setting, will only be included if any other + (explicitly or implicitly included) application uses it. The + value <c>include</c> implies that all applications and + escripts that do not have any explicit <c>incl_cond</c> + setting will be included. <c>exclude</c> implies that all + applications and escripts) that do not have any explicit + <c>incl_cond</c> setting will be excluded.</p> </item> - <tag><c><![CDATA[boot_rel]]></c></tag> + <tag><c>boot_rel</c></tag> <item> <p>A target system may have several releases but the one given as <c>boot_rel</c> will be used as default when the system is booting up.</p> </item> - <tag><c><![CDATA[rel]]></c></tag> + <tag><c>rel</c></tag> <item> <p>Release specific configuration. Each release maps to a - <c>rel</c>, <c>script</c> and <c>boot </c> file. See the + <c>rel</c>, <c>script</c> and <c>boot</c> file. See the module <c>systools</c> for more info about the details. Each release has a name, a version and a set of applications with a few release specific parameters such as type and included applications.</p> </item> - <tag><c><![CDATA[relocatable]]></c></tag> + <tag><c>relocatable</c></tag> <item> - <p>This parameter controls whether the <c>erl</c> executable - in the target system automatically should determine where it - is installed or if it should use a hardcoded path to the - installation. In the latter case the target system must be - installed with <c>reltool:install/2</c> before it can be - used. If the system is relocatable, the file tree containing - the target system can be moved to another location without - re-installation. The default is <c>true</c>.</p> + <p>This parameter controls whether the <c>erl</c> executable + in the target system should automatically determine where it + is installed or if it should use a hardcoded path to the + installation. In the latter case the target system must be + installed with <c>reltool:install/2</c> before it can be + used. If the system is relocatable, the file tree containing + the target system can be moved to another location without + re-installation. The default is <c>true</c>.</p> </item> - <tag><c><![CDATA[profile]]></c></tag> + <tag><c>profile</c></tag> <item> - <p>The creation of the specification for a target system is - performed in two steps. In the first step a complete - specification is generated. It will likely contain much more - files than you are interested in your customized target - system. In the second step the specification will be filtered - according to your filters. There you have the ability to - specify filters per application as well as system wide - filters. You can also select a <c>profile</c> for your - system. Depending on the <c>profile</c>, different default - filters will be used. There are three different profiles to - choose from: <c>development</c>, <c>embedded</c> and - <c>standalone</c>. <c>development</c> is default. The - parameters that are affected by the <c>profile</c> are: - <c>incl_sys_filters</c>, <c>excl_sys_filters</c>, - <c>incl_app_filters</c> and <c>excl_app_filters</c>.</p> + <p>The creation of the specification for a target system is + performed in two steps. In the first step a complete + specification is generated. It will likely contain much more + files than you are interested in in your customized target + system. In the second step the specification will be filtered + according to your filters. There you have the ability to + specify filters per application as well as system wide + filters. You can also select a <c>profile</c> for your + system. Depending on the <c>profile</c>, different default + filters will be used. There are three different profiles to + choose from: <c>development</c>, <c>embedded</c> and + <c>standalone</c>. <c>development</c> is default. The + parameters that are affected by the <c>profile</c> are: + <c>incl_sys_filters</c>, <c>excl_sys_filters</c>, + <c>incl_app_filters</c> and <c>excl_app_filters</c>.</p> </item> - <tag><c><![CDATA[app_file]]></c></tag> + <tag><c>app_file</c></tag> <item> <p>This parameter controls the default handling of the <c>app</c> files when a target system is generated. It @@ -213,7 +213,7 @@ and <c>strip</c>.</p> </item> - <tag><c><![CDATA[debug_info]]></c></tag> + <tag><c>debug_info</c></tag> <item> <p>The <c>debug_info</c> parameter controls whether the debug information in the beam file should be kept (<c>keep</c>) or @@ -221,31 +221,31 @@ system.</p> </item> - <tag><c><![CDATA[incl_sys_filters]]></c></tag> + <tag><c>incl_sys_filters</c></tag> <item> <p>This parameter normally contains a list of regular - expressions that controls which files in the system that + expressions that controls which files in the system should be included. Each file in the target system must match at least one of the listed regular expressions in order to be included. Further the files may not match any filter in <c>excl_sys_filters</c> in order to be included. Which - application files that should be included are controlled with + application files should be included is controlled with the parameters <c>incl_app_filters</c> and <c>excl_app_filters</c>. This parameter defaults to <c>[".*"]</c>.</p> </item> - <tag><c><![CDATA[excl_sys_filters]]></c></tag> + <tag><c>excl_sys_filters</c></tag> <item> <p>This parameter normally contains a list of regular - expressions that controls which files in the system that not - should be included in the target system. In order to be + expressions that controls which files in the system should + not be included in the target system. In order to be included, a file must match some filter in <c>incl_sys_filters</c> but not any filter in <c>excl_sys_filters</c>. This parameter defaults to <c>[]</c>.</p> </item> - <tag><c><![CDATA[incl_app_filters]]></c></tag> + <tag><c>incl_app_filters</c></tag> <item> <p>This parameter normally contains a list of regular expressions that controls which application specific files @@ -256,23 +256,23 @@ parameter defaults to <c>[".*"]</c>.</p> </item> - <tag><c><![CDATA[excl_app_filters]]></c></tag> + <tag><c>excl_app_filters</c></tag> <item> <p>This parameter normally contains a list of regular expressions that controls which application specific files - that not should be included in the target system. In order to + should not be included in the target system. In order to be included, a file must match some filter in <c>incl_app_filters</c> but not any filter in <c>excl_app_filters</c>. This parameter defaults to <c>[]</c>.</p> </item> - <tag><c><![CDATA[incl_archive_filters]]></c></tag> + <tag><c>incl_archive_filters</c></tag> <item> <p>This parameter normally contains a list of regular expressions that controls which top level directories in an - application that should be included in an archive file (as - opposed of beeing included as a regular directory outside the + application should be included in an archive file (as + opposed to being included as a regular directory outside the archive). Each top directory in the application must match at least one of the listed regular expressions in order to be included. Further the files may not match any filter in @@ -280,122 +280,122 @@ parameter defaults to <c>[".*"]</c>.</p> </item> - <tag><c><![CDATA[excl_archive_filters]]></c></tag> + <tag><c>excl_archive_filters</c></tag> <item> <p>This parameter normally contains a list of regular expressions that controls which top level directories in an - application that not should be included in an archive file. In + application should not be included in an archive file. In order to be included in the application archive, a top directory must match some filter in <c>incl_archive_filters</c> but not any filter in <c>excl_archive_filters</c>. This parameter defaults to <c>["^include$","^priv$"]</c>.</p> </item> - <tag><c><![CDATA[archive_opts]]></c></tag> + <tag><c>archive_opts</c></tag> <item> <p>This parameter contains a list of options that are given to <c>zip:create/3</c> when application specific files are - packaged into an archive. All options are not supported. The - most useful options in this context, are the ones that - controls which types of files that should be compressed. This + packaged into an archive. Only a subset of the options are + supported. The most useful options in this context are the ones + that control which types of files should be compressed. This parameter defaults to <c>[]</c>.</p> </item> </taglist> - <p>On application (<c>escript</c>) level,the following options are + <p>On application (<c>escript</c>) level, the following options are supported:</p> <taglist> - <tag><c><![CDATA[incl_cond]]></c></tag> + <tag><c>incl_cond</c></tag> <item> <p>The value of this parameter overrides the parameter with the same name on system level.</p> </item> </taglist> - <p>On application (<c>app</c>) level,the following options are + <p>On application (<c>app</c>) level, the following options are supported:</p> <taglist> - <tag><c><![CDATA[vsn]]></c></tag> + <tag><c>vsn</c></tag> <item> <p>The version of the application. In an installed system there may exist several versions of an application. The <c>vsn</c> parameter - controls which version of the application that will be choosen. If it - is omitted, the latest version will be choosen.</p> + controls which version of the application will be chosen. If it + is omitted, the latest version will be chosen.</p> </item> - <tag><c><![CDATA[mod]]></c></tag> + <tag><c>mod</c></tag> <item> <p>Module specific configuration. A module has a mandatory name and module level options that are described below.</p> </item> - <tag><c><![CDATA[mod_cond]]></c></tag> + <tag><c>mod_cond</c></tag> <item> <p>The value of this parameter overrides the parameter with the same name on system level.</p> </item> - <tag><c><![CDATA[incl_cond]]></c></tag> + <tag><c>incl_cond</c></tag> <item> <p>The value of this parameter overrides the parameter with the same name on system level.</p> </item> - <tag><c><![CDATA[app_file]]></c></tag> + <tag><c>app_file</c></tag> <item> <p>The value of this parameter overrides the parameter with the same name on system level.</p> </item> - <tag><c><![CDATA[debug_info]]></c></tag> + <tag><c>debug_info</c></tag> <item> <p>The value of this parameter overrides the parameter with the same name on system level.</p> </item> - <tag><c><![CDATA[incl_app_filters]]></c></tag> + <tag><c>incl_app_filters</c></tag> <item> <p>The value of this parameter overrides the parameter with the same name on system level.</p> </item> - <tag><c><![CDATA[excl_app_filters]]></c></tag> + <tag><c>excl_app_filters</c></tag> <item> <p>The value of this parameter overrides the parameter with the same name on system level.</p> </item> - <tag><c><![CDATA[incl_archive_filters]]></c></tag> + <tag><c>incl_archive_filters</c></tag> <item> <p>The value of this parameter overrides the parameter with the same name on system level.</p> </item> - <tag><c><![CDATA[excl_archive_filters]]></c></tag> + <tag><c>excl_archive_filters</c></tag> <item> <p>The value of this parameter overrides the parameter with the same name on system level.</p> </item> - <tag><c><![CDATA[archive_opts]]></c></tag> + <tag><c>archive_opts</c></tag> <item> <p>The value of this parameter overrides the parameter with the same name on system level.</p> </item> </taglist> - <p>On module (<c>mod</c>) level,the following options are + <p>On module (<c>mod</c>) level, the following options are supported:</p> <taglist> - <tag><c><![CDATA[incl_cond]]></c></tag> + <tag><c>incl_cond</c></tag> <item> - <p>This parameter controls whether the module is included or not. By - default the <c>mod_incl</c> parameter on application and system level - will be used to control whether the module is included or not. The - value of <c>incl_cond</c> overrides the module inclusion policy. - <c>include</c> implies that the module is included, while - <c>exclude</c> implies that the module not is included. - <c>derived</c> implies that the is included if any included uses the - module.</p> + <p>This parameter controls whether the module is included or not. By + default the <c>mod_incl</c> parameter on application and system level + will be used to control whether the module is included or not. The + value of <c>incl_cond</c> overrides the module inclusion policy. + <c>include</c> implies that the module is included, while + <c>exclude</c> implies that the module is not included. + <c>derived</c> implies that the module is included if it is used + by any other included module.</p> </item> - <tag><c><![CDATA[debug_info]]></c></tag> + <tag><c>debug_info</c></tag> <item> <p>The value of this parameter overrides the parameter with the same name on application level.</p> @@ -477,7 +477,9 @@ mod_name() = atom() profile() = development | embedded | standalone re_regexp() = string() reason() = string() -regexps() = [re_regexp()] | {add, [re_regexp()]} | {del, [re_regexp()]} +regexps() = [re_regexp()] + | {add, [re_regexp()]} + | {del, [re_regexp()]} rel_file() = term() rel_name() = string() rel_vsn() = string() @@ -487,7 +489,19 @@ script_file() = term() server() = server_pid() | options() server_pid() = pid() target_dir() = file() -window_pid() = pid()]]></code> +window_pid() = pid() +base_dir() = dir() +base_file() = file() +top_dir() = file() +top_file() = file() +target_spec() = [target_spec()] + | {create_dir, base_dir(), [target_spec()]} + | {create_dir, base_dir(), top_dir(), [target_spec()]} + | {archive, base_file(), [archive_opt()], [target_spec()]} + | {copy_file, base_file()} + | {copy_file, base_file(), top_file()} + | {write_file, base_file(), iolist()} + | {strip_beam_file, base_file()}]]></code> <marker id="start"></marker> </section> @@ -497,9 +511,9 @@ window_pid() = pid()]]></code> <name>create_target(Server, TargetDir) -> ok | {error, Reason}</name> <fsummary>Create a target system</fsummary> <type> - <v>Server = server()</v> + <v>Server = server()</v> <v>TargetDir = target_dir()</v> - <v>Reason = reason()</v> + <v>Reason = reason()</v> </type> <desc><p>Create a target system. Gives the same result as <c>{ok,TargetSpec}=reltool:get_target_spec(Server)</c> and @@ -532,12 +546,12 @@ window_pid() = pid()]]></code> files are by default copied to the target system. The <c>releases</c> directory contains generated <c>rel</c>, <c>script</c>, and <c>boot</c> files. The <c>lib</c> directory - contains the applications. Which applications that are included + contains the applications. Which applications are included and if they should be customized (archived, stripped from debug info etc.) is specified with various configuration parameters. The files in the <c>bin</c> directory are copied from the <c>erts-vsn/bin</c> directory, but only those files - that was originally included in <c>bin</c> directory of the + that were originally included in the <c>bin</c> directory of the source system.</p> <p>If the configuration parameter <c>relocatable</c> was set to @@ -570,10 +584,10 @@ window_pid() = pid()]]></code> <v>Reason = reason()</v> </type> <desc><p>Get reltool configuration. Normally, only the explicit - configuration parameters with values that differs from their + configuration parameters with values that differ from their defaults are interesting. But the builtin default values can be returned by setting <c>InclDefaults</c> to <c>true</c>. The - derived configuration can be return by setting + derived configuration can be returned by setting <c>InclDerived</c> to <c>true</c>.</p></desc> </func> @@ -604,6 +618,17 @@ window_pid() = pid()]]></code> </func> <func> + <name>get_status(Server) -> {ok, [Warning]} | {error, Reason}</name> + <fsummary>Get contents of a release file</fsummary> + <type> + <v>Server = server()</v> + <v>Warning = string()</v> + <v>Reason = reason()</v> + </type> + <desc><p>Get status about the configuration</p></desc> + </func> + + <func> <name>get_server(WindowPid) -> {ok, ServerPid} | {error, Reason}</name> <fsummary>Start server process with options</fsummary> <type> @@ -680,7 +705,7 @@ window_pid() = pid()]]></code> <v>Reason = reason()</v> </type> <desc><p>Start a server process with options. The server process - identity can be given as argument to several other functions in the + identity can be given as an argument to several other functions in the API.</p></desc> </func> |