aboutsummaryrefslogtreecommitdiffstats
path: root/lib/kernel/doc/src/app.xml
diff options
context:
space:
mode:
Diffstat (limited to 'lib/kernel/doc/src/app.xml')
-rw-r--r--lib/kernel/doc/src/app.xml168
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>