← Back to branch summary

~rdoering/ubuntu/karmic/erlang/fix-535090

« back to all changes in this revision

Viewing changes to lib/kernel/doc/src/app.xml

  • Committer: Bazaar Package Importer
  • Author(s): Sergei Golovan
  • Date: 2009-02-15 16:42:52 UTC
  • mfrom: (3.1.2 squeeze)
  • Revision ID: james.westby@ubuntu.com-20090215164252-q5x4rcf8a5pbesb1
Tags: 1:12.b.5-dfsg-2
Upload to unstable after lenny is released.

Show diffs side-by-side

added added

removed removed

Lines of Context:
lib/kernel/doc/src/app.xml
 
1
<?xml version="1.0" encoding="latin1" ?>
 
2
<!DOCTYPE fileref SYSTEM "fileref.dtd">
 
3
 
 
4
<fileref>
 
5
  <header>
 
6
    <copyright>
 
7
      <year>1997</year>
 
8
      <year>2007</year>
 
9
      <holder>Ericsson AB, All Rights Reserved</holder>
 
10
    </copyright>
 
11
    <legalnotice>
 
12
  The contents of this file are subject to the Erlang Public License,
 
13
  Version 1.1, (the "License"); you may not use this file except in
 
14
  compliance with the License. You should have received a copy of the
 
15
  Erlang Public License along with this software. If not, it can be
 
16
  retrieved online at http://www.erlang.org/.
 
17
 
 
18
  Software distributed under the License is distributed on an "AS IS"
 
19
  basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
 
20
  the License for the specific language governing rights and limitations
 
21
  under the License.
 
22
 
 
23
  The Initial Developer of the Original Code is Ericsson AB.
 
24
    </legalnotice>
 
25
 
 
26
    <title>app</title>
 
27
    <prepared></prepared>
 
28
    <docno></docno>
 
29
    <date></date>
 
30
    <rev></rev>
 
31
  </header>
 
32
  <file>app</file>
 
33
  <filesummary>Application resource file.</filesummary>
 
34
  <description>
 
35
    <p>The <em>application resource file</em> specifies the resources an
 
36
      application uses, and how the application is started. There must
 
37
      always be one application resource file called
 
38
      <c>Application.app</c> for each application <c>Application</c> in
 
39
      the system.</p>
 
40
    <p>The file is read by the application controller when an
 
41
      application is loaded/started. It is also used by the functions in
 
42
      <c>systools</c>, for example when generating start scripts.</p>
 
43
  </description>
 
44
 
 
45
  <section>
 
46
    <title>FILE SYNTAX</title>
 
47
    <p>The application resource file should be called
 
48
      <c>Application.app</c> where <c>Application</c> is the name of
 
49
      the application. The file should be located in the <c>ebin</c>
 
50
      directory for the application.</p>
 
51
    <p>It must contain one single Erlang term, which is called an
 
52
      <em>application specification</em>:</p>
 
53
    <code type="none">
 
54
{application, Application,
 
55
  [{description,  Description},
 
56
   {id,           Id},
 
57
   {vsn,          Vsn},
 
58
   {modules,      Modules},
 
59
   {maxP,         MaxP},
 
60
   {maxT,         MaxT},
 
61
   {registered,   Names},
 
62
   {included_applications, Apps},
 
63
   {applications, Apps},
 
64
   {env,          Env},
 
65
   {mod,          Start},
 
66
   {start_phases, Phases}]}.
 
67
 
 
68
             Value                Default
 
69
             -----                -------
 
70
Application  atom()               -
 
71
Description  string()             ""
 
72
Id           string()             ""
 
73
Vsn          string()             ""
 
74
Modules      [Module]             []
 
75
MaxP         int()                infinity
 
76
MaxT         int()                infinity
 
77
Names        [Name]               []
 
78
Apps         [App]                []
 
79
Env          [{Par,Val}]          []
 
80
Start        {Module,StartArgs}   undefined
 
81
Phases       [{Phase,PhaseArgs}]  undefined
 
82
  Module = Name = App = Par = Phase = atom()
 
83
  Val = StartArgs = PhaseArgs = term()</code>
 
84
    <p><c>Application</c> is the name of the application.</p>
 
85
    <p>For the application controller, all keys are optional.
 
86
      The respective default values are used for any omitted keys.</p>
 
87
    <p>The functions in <c>systools</c> require more information. If
 
88
      they are used, the following keys are mandatory:
 
89
      <c>description</c>, <c>vsn</c>, <c>modules</c>, <c>registered</c>
 
90
      and <c>applications</c>. The other keys are ignored by
 
91
      <c>systools</c>.</p>
 
92
    <taglist>
 
93
      <tag><c>description</c></tag>
 
94
      <item>
 
95
        <p>A one-line description of the application.</p>
 
96
      </item>
 
97
      <tag><c>id</c></tag>
 
98
      <item>
 
99
        <p>Product identification, or similar.</p>
 
100
      </item>
 
101
      <tag><c>vsn</c></tag>
 
102
      <item>
 
103
        <p>The version of the application.</p>
 
104
      </item>
 
105
      <tag><c>modules</c></tag>
 
106
      <item>
 
107
        <p>All modules introduced by this application. <c>systools</c>
 
108
          uses this list when generating start scripts and tar files. A
 
109
          module can only be defined in one application.</p>
 
110
      </item>
 
111
      <tag><c>maxP</c></tag>
 
112
      <item>
 
113
        <p><em>Deprecated - will be ignored</em>          <br></br>
 
114
 
 
115
          The maximum number of processes allowed in the application.</p>
 
116
      </item>
 
117
      <tag><c>maxT</c></tag>
 
118
      <item>
 
119
        <p>The maximum time in milliseconds that the application is
 
120
          allowed to run. After the specified time the application will
 
121
          automatically terminate.</p>
 
122
      </item>
 
123
      <tag><c>registered</c></tag>
 
124
      <item>
 
125
        <p>All names of registered processes started in this
 
126
          application. <c>systools</c> uses this list to detect name
 
127
          clashes between different applications.</p>
 
128
      </item>
 
129
      <tag><c>included_applications</c></tag>
 
130
      <item>
 
131
        <p>All applications which are included by this application.
 
132
          When this application is started, all included application
 
133
          will automatically be loaded, but not started, by
 
134
          the application controller. It is assumed that the topmost
 
135
          supervisor of the included application is started by a
 
136
          supervisor of this application.</p>
 
137
      </item>
 
138
      <tag><c>applications</c></tag>
 
139
      <item>
 
140
        <p>All applications which must be started before this
 
141
          application is allowed to be started. <c>systools</c> uses
 
142
          this list to generate correct start scripts. Defaults to
 
143
          the empty list, but note that all applications have
 
144
          dependencies to (at least) <c>kernel</c> and <c>stdlib</c>.</p>
 
145
      </item>
 
146
      <tag><c>env</c></tag>
 
147
      <item>
 
148
        <p>Configuration parameters used by the application. The value
 
149
          of a configuration parameter is retrieved by calling
 
150
          <c>application:get_env/1,2</c>. The values in the application
 
151
          resource file can be overridden by values in a configuration
 
152
          file (see <c>config(4)</c>) or by command line flags (see
 
153
          <c>erl(1)</c>).</p>
 
154
      </item>
 
155
      <tag><c>mod</c></tag>
 
156
      <item>
 
157
        <p>Specifies the application callback module and a start
 
158
          argument, see <c>application(3)</c>.</p>
 
159
        <p>The <c>mod</c> key is necessary for an application
 
160
          implemented as a supervision tree, or the application
 
161
          controller will not know how to start it. The <c>mod</c> key
 
162
          can be omitted for applications without processes, typically
 
163
          code libraries such as the application STDLIB.</p>
 
164
      </item>
 
165
      <tag><c>start_phases</c></tag>
 
166
      <item>
 
167
        <p>A list of start phases and corresponding start arguments for
 
168
          the application. If this key is present, the application
 
169
          master will - in addition to the usual call to
 
170
          <c>Module:start/2</c> - also call
 
171
          <c>Module:start_phase(Phase,Type,PhaseArgs)</c> for each
 
172
          start phase defined by the <c>start_phases</c> key, and only
 
173
          after this extended start procedure will
 
174
          <c>application:start(Application)</c> return.</p>
 
175
        <p></p>
 
176
        <p>Start phases may be used to synchronize startup of an
 
177
          application and its included applications. In this case,
 
178
          the <c>mod</c> key must be specified as:</p>
 
179
        <code type="none">
 
180
{mod, {application_starter,[Module,StartArgs]}}</code>
 
181
        <p>The application master will then call <c>Module:start/2</c>
 
182
          for the primary application, followed by calls to
 
183
          <c>Module:start_phase/3</c> for each start phase (as defined
 
184
          for the primary application) both for the primary application
 
185
          and for each of its included application, for which the start
 
186
          phase is defined.</p>
 
187
        <p></p>
 
188
        <p>This implies that for an included application, the set of
 
189
          start phases must be a subset of the set of phases defined
 
190
          for the primary application. Refer to <em>OTP Design Principles</em> for more information.</p>
 
191
      </item>
 
192
    </taglist>
 
193
  </section>
 
194
 
 
195
  <section>
 
196
    <title>SEE ALSO</title>
 
197
    <p><seealso marker="application">application(3)</seealso>,
 
198
      systools(3)</p>
 
199
  </section>
 
200
</fileref>
 
201