aboutsummaryrefslogtreecommitdiffstats
path: root/lib/kernel/doc/src/app.xml
blob: b24a2bd7bd2d045950c117c5b71a09db56b88c4f (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE fileref SYSTEM "fileref.dtd">

<fileref>
  <header>
    <copyright>
      <year>1997</year><year>2013</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},
   {runtime_dependencies, RTDeps}]}.

             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}   []
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>
    <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>
    <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>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>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>
      <tag><marker id="runtime_dependencies"><c>runtime_dependencies</c></marker></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 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 might not be completely correct. This
      is actively 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>
  </section>
</fileref>