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.xml199
1 files changed, 199 insertions, 0 deletions
diff --git a/lib/kernel/doc/src/app.xml b/lib/kernel/doc/src/app.xml
new file mode 100644
index 0000000000..ef1f5985f4
--- /dev/null
+++ b/lib/kernel/doc/src/app.xml
@@ -0,0 +1,199 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE fileref SYSTEM "fileref.dtd">
+
+<fileref>
+ <header>
+ <copyright>
+ <year>1997</year><year>2009</year>
+ <holder>Ericsson AB. All Rights Reserved.</holder>
+ </copyright>
+ <legalnotice>
+ The contents of this file are subject to the Erlang Public License,
+ Version 1.1, (the "License"); you may not use this file except in
+ compliance with the License. You should have received a copy of the
+ Erlang Public License along with this software. If not, it can be
+ retrieved online at http://www.erlang.org/.
+
+ Software distributed under the License is distributed on an "AS IS"
+ basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+ the License for the specific language governing rights and limitations
+ under the License.
+
+ </legalnotice>
+
+ <title>app</title>
+ <prepared></prepared>
+ <docno></docno>
+ <date></date>
+ <rev></rev>
+ </header>
+ <file>app</file>
+ <filesummary>Application resource file.</filesummary>
+ <description>
+ <p>The <em>application resource file</em> specifies the resources an
+ application uses, and how the application is started. There must
+ always be one application resource file called
+ <c>Application.app</c> for each application <c>Application</c> in
+ the system.</p>
+ <p>The file is read by the application controller when an
+ application is loaded/started. It is also used by the functions in
+ <c>systools</c>, for example when generating start scripts.</p>
+ </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
+ <em>application specification</em>:</p>
+ <code type="none">
+{application, Application,
+ [{description, Description},
+ {id, Id},
+ {vsn, Vsn},
+ {modules, Modules},
+ {maxP, MaxP},
+ {maxT, MaxT},
+ {registered, Names},
+ {included_applications, Apps},
+ {applications, Apps},
+ {env, Env},
+ {mod, Start},
+ {start_phases, Phases}]}.
+
+ Value Default
+ ----- -------
+Application atom() -
+Description string() ""
+Id string() ""
+Vsn string() ""
+Modules [Module] []
+MaxP int() infinity
+MaxT int() infinity
+Names [Name] []
+Apps [App] []
+Env [{Par,Val}] []
+Start {Module,StartArgs} undefined
+Phases [{Phase,PhaseArgs}] undefined
+ Module = Name = App = Par = Phase = atom()
+ Val = StartArgs = PhaseArgs = term()</code>
+ <p><c>Application</c> is the name of the application.</p>
+ <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>
+ <taglist>
+ <tag><c>description</c></tag>
+ <item>
+ <p>A one-line description of the application.</p>
+ </item>
+ <tag><c>id</c></tag>
+ <item>
+ <p>Product identification, or similar.</p>
+ </item>
+ <tag><c>vsn</c></tag>
+ <item>
+ <p>The version of the application.</p>
+ </item>
+ <tag><c>modules</c></tag>
+ <item>
+ <p>All modules introduced by this application. <c>systools</c>
+ uses this list when generating start scripts and tar files. A
+ module can only be defined in one application.</p>
+ </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>
+ </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>
+ </item>
+ <tag><c>registered</c></tag>
+ <item>
+ <p>All names of registered processes started in this
+ application. <c>systools</c> uses this list to detect name
+ clashes between different applications.</p>
+ </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
+ 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
+ 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>
+ </item>
+ <tag><c>env</c></tag>
+ <item>
+ <p>Configuration parameters used by the application. The value
+ 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>
+ </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
+ can be omitted for applications without processes, typically
+ code libraries such as the application STDLIB.</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
+ <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></p>
+ <p>Start phases may 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>
+ <code type="none">
+{mod, {application_starter,[Module,StartArgs]}}</code>
+ <p>The application master will then call <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
+ phase is defined.</p>
+ <p></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>
+ </item>
+ </taglist>
+ </section>
+
+ <section>
+ <title>SEE ALSO</title>
+ <p><seealso marker="application">application(3)</seealso>,
+ systools(3)</p>
+ </section>
+</fileref>
+