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
|
<?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>
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
</legalnotice>
<title>config</title>
<prepared></prepared>
<docno></docno>
<date></date>
<rev></rev>
</header>
<file>config</file>
<filesummary>Configuration file.</filesummary>
<description>
<p>A <em>configuration file</em> contains values for configuration
parameters for the applications in the system. The <c>erl</c>
command line argument <c>-config Name</c> tells the system to use
data in the system configuration file <c>Name.config</c>.</p>
<p>Configuration parameter values in the configuration file will
override the values in the application resource files (see
<c>app(4)</c>). The values in the configuration file can be
overridden by command line flags (see <c>erl(1)</c>).</p>
<p>The value of a configuration parameter is retrieved by calling
<c>application:get_env/1,2</c>.</p>
</description>
<section>
<title>FILE SYNTAX</title>
<p>The configuration file should be called <c>Name.config</c> where
<c>Name</c> is an arbitrary name.</p>
<p>The <c>.config</c> file contains one single Erlang term.
The file has the following syntax:</p>
<code type="none">
[{Application1, [{Par11, Val11}, ..]},
..
{ApplicationN, [{ParN1, ValN1}, ..]}].</code>
<list type="bulleted">
<item>
<p><c>Application = atom()</c> is the name of the application.</p>
</item>
<item>
<p><c>Par = atom()</c> is the name of a configuration parameter.</p>
</item>
<item>
<p><c>Val = term()</c> is the value of a configuration
parameter.</p>
</item>
</list>
</section>
<section>
<title>sys.config</title>
<p>When starting Erlang in embedded mode, it is assumed that
exactly one system configuration file is used, named
<c>sys.config</c>. This file should be located in
<c>$ROOT/releases/Vsn</c>, where <c>$ROOT</c> is the Erlang/OTP
root installation directory and <c>Vsn</c> is the release version.</p>
<p>Release handling relies on this assumption. When installing a
new release version, the new <c>sys.config</c> is read and used
to update the application configurations.</p>
<p>This means that specifying another, or additional, <c>.config</c>
files would lead to inconsistent update of application
configurations. Therefore, in Erlang 5.4/OTP R10B, the syntax of
<c>sys.config</c> was extended to allow pointing out other
<c>.config</c> files:</p>
<code type="none">
[{Application, [{Par, Val}]} | File].</code>
<list type="bulleted">
<item>
<p><c>File = string()</c> is the name of another <c>.config</c>
file. The extension <c>.config</c> may be omitted. It is
recommended to use absolute paths. A relative path is
relative the current working directory of the emulator.</p>
</item>
</list>
<p>When traversing the contents of <c>sys.config</c> and a filename
is encountered, its contents are read and merged with the result
so far. When an application configuration tuple
<c>{Application, Env}</c> is found, it is merged with the result
so far. Merging means that new parameters are added and existing
parameter values overwritten. Example:</p>
<code type="none">
sys.config:
[{myapp,[{par1,val1},{par2,val2}]},
"/home/user/myconfig"].
myconfig.config:
[{myapp,[{par2,val3},{par3,val4}]}].</code>
<p>This will yield the following environment for <c>myapp</c>:</p>
<code type="none">
[{par1,val1},{par2,val3},{par3,val4}]</code>
<p>The behaviour if a file specified in <c>sys.config</c> does not
exist or is erroneous in some other way, is backwards compatible.
Starting the runtime system will fail. Installing a new release
version will not fail, but an error message is given and
the erroneous file is ignored.</p>
</section>
<section>
<title>SEE ALSO</title>
<p><c>app(4)</c>, <c>erl(1)</c>, <em>OTP Design Principles</em></p>
</section>
</fileref>
|
