diff options
Diffstat (limited to 'lib/kernel/doc/src/app.xml')
| -rw-r--r-- | lib/kernel/doc/src/app.xml | 168 |
1 files changed, 90 insertions, 78 deletions
diff --git a/lib/kernel/doc/src/app.xml b/lib/kernel/doc/src/app.xml index 68c042b2ae..5e0da409a3 100644 --- a/lib/kernel/doc/src/app.xml +++ b/lib/kernel/doc/src/app.xml @@ -42,12 +42,12 @@ </description> <section> - <title>FILE SYNTAX</title> - <p>The application resource file should be called - <c>Application.app</c> where <c>Application</c> is the name of - the application. The file should be located in the <c>ebin</c> - directory for the application.</p> - <p>It must contain one single Erlang term, which is called an + <title>File Syntax</title> + <p>The application resource file is to be called + <c>Application.app</c>, where <c>Application</c> is the + application name. The file is to be located in directory <c>ebin</c> + for the application.</p> + <p>The file must contain a single Erlang term, which is called an <em>application specification</em>:</p> <code type="none"> {application, Application, @@ -80,19 +80,26 @@ Env [{Par,Val}] [] Start {Module,StartArgs} [] Phases [{Phase,PhaseArgs}] undefined RTDeps [ApplicationVersion] [] - Module = Name = App = Par = Phase = atom() - Val = StartArgs = PhaseArgs = term() - ApplicationVersion = string()</code> - <p><c>Application</c> is the name of the application.</p> + +Module = Name = App = Par = Phase = atom() +Val = StartArgs = PhaseArgs = term() +ApplicationVersion = string()</code> + <taglist> + <tag><c>Application</c></tag> + <item>Application name.</item> + </taglist> <p>For the application controller, all keys are optional. The respective default values are used for any omitted keys.</p> <p>The functions in <c>systools</c> require more information. If - they are used, the following keys are mandatory: - <c>description</c>, <c>vsn</c>, <c>modules</c>, <c>registered</c> - and <c>applications</c>. The other keys are ignored by - <c>systools</c>.</p> - <warning><p>The <c>RTDeps</c> type was introduced in OTP 17.0 and - might be subject to changes during the OTP 17 release.</p></warning> + they are used, the following keys are mandatory:</p> + <list type="bulleted"> + <item><c>description</c></item> + <item><c>vsn</c></item> + <item><c>modules</c></item> + <item><c>registered</c></item> + <item><c>applications</c></item> + </list> + <p>The other keys are ignored by <c>systools</c>.</p> <taglist> <tag><c>description</c></tag> <item> @@ -104,7 +111,7 @@ RTDeps [ApplicationVersion] [] </item> <tag><c>vsn</c></tag> <item> - <p>The version of the application.</p> + <p>Version of the application.</p> </item> <tag><c>modules</c></tag> <item> @@ -114,15 +121,14 @@ RTDeps [ApplicationVersion] [] </item> <tag><c>maxP</c></tag> <item> - <p><em>Deprecated - will be ignored</em> <br></br> - - The maximum number of processes allowed in the application.</p> + <p><em>Deprecated - is ignored</em></p> + <p>Maximum number of processes allowed in the application.</p> </item> <tag><c>maxT</c></tag> <item> - <p>The maximum time in milliseconds that the application is - allowed to run. After the specified time the application will - automatically terminate.</p> + <p>Maximum time, in milliseconds, that the application is + allowed to run. After the specified time, the application + terminates automatically.</p> </item> <tag><c>registered</c></tag> <item> @@ -132,20 +138,20 @@ RTDeps [ApplicationVersion] [] </item> <tag><c>included_applications</c></tag> <item> - <p>All applications which are included by this application. - When this application is started, all included application - will automatically be loaded, but not started, by - the application controller. It is assumed that the topmost + <p>All applications included by this application. + When this application is started, all included applications + are loaded automatically, but not started, by + the application controller. It is assumed that the top-most supervisor of the included application is started by a supervisor of this application.</p> </item> <tag><c>applications</c></tag> <item> - <p>All applications which must be started before this + <p>All applications that must be started before this application is allowed to be started. <c>systools</c> uses this list to generate correct start scripts. Defaults to - the empty list, but note that all applications have - dependencies to (at least) <c>kernel</c> and <c>stdlib</c>.</p> + the empty list, but notice that all applications have + dependencies to (at least) <c>Kernel</c> and <c>STDLIB</c>.</p> </item> <tag><c>env</c></tag> <item> @@ -153,78 +159,84 @@ RTDeps [ApplicationVersion] [] of a configuration parameter is retrieved by calling <c>application:get_env/1,2</c>. The values in the application resource file can be overridden by values in a configuration - file (see <c>config(4)</c>) or by command line flags (see - <c>erl(1)</c>).</p> + file (see <seealso marker="config"><c>config(4)</c></seealso>) + or by command-line flags (see + <seealso marker="erts:erl"><c>erts:erl(1)</c></seealso>).</p> </item> <tag><c>mod</c></tag> <item> - <p>Specifies the application callback module and a start - argument, see <c>application(3)</c>.</p> - <p>The <c>mod</c> key is necessary for an application - implemented as a supervision tree, or the application - controller will not know how to start it. The <c>mod</c> key + <p>Specifies the application callback module and a start argument, see + <seealso marker="application"><c>application(3)</c></seealso>.</p> + <p>Key <c>mod</c> is necessary for an application + implemented as a supervision tree, otherwise the application + controller does not know how to start it. <c>mod</c> can be omitted for applications without processes, typically - code libraries such as the application STDLIB.</p> + code libraries, for example, <c>STDLIB</c>.</p> </item> <tag><c>start_phases</c></tag> <item> <p>A list of start phases and corresponding start arguments for the application. If this key is present, the application - master will - in addition to the usual call to - <c>Module:start/2</c> - also call + master, in addition to the usual call to + <c>Module:start/2</c>, also calls <c>Module:start_phase(Phase,Type,PhaseArgs)</c> for each - start phase defined by the <c>start_phases</c> key, and only - after this extended start procedure will - <c>application:start(Application)</c> return.</p> - <p>Start phases may be used to synchronize startup of an + start phase defined by key <c>start_phases</c>. Only + after this extended start procedure, + <c>application:start(Application)</c> returns.</p> + <p>Start phases can be used to synchronize startup of an application and its included applications. In this case, - the <c>mod</c> key must be specified as:</p> + key <c>mod</c> must be specified as follows:</p> <code type="none"> {mod, {application_starter,[Module,StartArgs]}}</code> - <p>The application master will then call <c>Module:start/2</c> + <p>The application master then calls <c>Module:start/2</c> for the primary application, followed by calls to <c>Module:start_phase/3</c> for each start phase (as defined - for the primary application) both for the primary application - and for each of its included application, for which the start + for the primary application), both for the primary application + and for each of its included applications, for which the start phase is defined.</p> <p>This implies that for an included application, the set of start phases must be a subset of the set of phases defined - for the primary application. Refer to <em>OTP Design Principles</em> for more information.</p> + for the primary application. For more information, see + <seealso marker="doc/design_principles:applications">OTP Design Principles</seealso>. + </p> </item> - <tag><marker id="runtime_dependencies"></marker><c>runtime_dependencies</c></tag> - <item><p>A list of application versions that the application - depends on. An example of such an application version is - <c>"kernel-3.0"</c>. Application versions specified as runtime - dependencies are minimum requirements. That is, a larger - application version than the one specified in the - dependency satisfies the requirement. For information on - how to compare application versions see - <seealso marker="doc/system_principles:versions">the - documentation of versions in the system principles - guide</seealso>. Note that the application version - specifies a source code version. An additional indirect - requirement is that installed binary application of - the specified version has been built so that it is - compatible with the rest of the system.</p> - <p>Some dependencies might only be required in specific runtime - scenarios. In the case such optional dependencies exist, these are - specified and documented in the corresponding "App" documentation - of the specific application.</p> - <warning><p>The <c>runtime_dependencies</c> key was introduced in - OTP 17.0. The type of its value might be subject to changes during - the OTP 17 release.</p></warning> - <warning><p>All runtime dependencies specified in OTP applications - during the OTP 17 release may not be completely correct. This - is actively being worked on. Declared runtime dependencies in OTP - applications are expected to be correct in OTP 18.</p></warning> + <tag> + <marker id="runtime_dependencies"></marker> + <c>runtime_dependencies</c></tag> + <item> + <p>A list of application versions that the application + depends on. An example of such an application version is + <c>"kernel-3.0"</c>. Application versions specified as runtime + dependencies are minimum requirements. That is, a larger + application version than the one specified in the + dependency satisfies the requirement. For information about + how to compare application versions, see section + <seealso marker="doc/system_principles:versions">Versions</seealso> + in the System Principles User's Guide.</p> + <p>Notice that the application version + specifies a source code version. One more, indirect, + requirement is that the installed binary application of + the specified version is built so that it is + compatible with the rest of the system.</p> + <p>Some dependencies can only be required in specific runtime + scenarios. When such optional dependencies exist, these are + specified and documented in the corresponding "App" documentation + of the specific application.</p> + <warning><p>The <c>runtime_dependencies</c> key was introduced in + OTP 17.0. The type of its value might be subject to changes during + the OTP 17 release.</p></warning> + <warning><p>All runtime dependencies specified in OTP applications + during the OTP 17 release may not be completely correct. This + is actively being worked on. Declared runtime dependencies in OTP + applications are expected to be correct in OTP 18.</p></warning> </item> </taglist> </section> <section> - <title>SEE ALSO</title> - <p><seealso marker="application">application(3)</seealso>, - systools(3)</p> + <title>See Also</title> + <p><seealso marker="application"><c>application(3)</c></seealso>, + <seealso marker="sasl:systools"><c>sasl:systools(3)</c></seealso></p> </section> </fileref> |