aboutsummaryrefslogtreecommitdiffstats
path: root/lib/kernel/doc/src/config.xml
diff options
context:
space:
mode:
Diffstat (limited to 'lib/kernel/doc/src/config.xml')
-rw-r--r--lib/kernel/doc/src/config.xml100
1 files changed, 52 insertions, 48 deletions
diff --git a/lib/kernel/doc/src/config.xml b/lib/kernel/doc/src/config.xml
index 0e34549482..714af93f4d 100644
--- a/lib/kernel/doc/src/config.xml
+++ b/lib/kernel/doc/src/config.xml
@@ -4,14 +4,14 @@
<fileref>
<header>
<copyright>
- <year>1997</year><year>2013</year>
+ <year>1997</year><year>2018</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
@@ -19,7 +19,7 @@
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>
@@ -33,94 +33,98 @@
<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
+ 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
+ <p>Configuration parameter values in the configuration file
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>
+ <seealso marker="app"><c>app(4)</c></seealso>).
+ The values in the configuration file can be
+ overridden by command-line flags (see
+ <seealso marker="erts:erl"><c>erts:erl(1)</c></seealso>).</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>
+ <title>File Syntax</title>
+ <p>The configuration file is to be called <c>Name.config</c>, where
+ <c>Name</c> is any name.</p>
+ <p>File <c>.config</c> contains a single Erlang term and
+ 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>
+[{Application1, [{Par11, Val11}, ...]},
+ ...
+ {ApplicationN, [{ParN1, ValN1}, ...]}].</code>
+ <taglist>
+ <tag><c>Application = atom()</c></tag>
+ <item><p>Application name.</p></item>
+ <tag><c>Par = atom()</c></tag>
+ <item><p>Name of a configuration parameter.</p></item>
+ <tag><c>Val = term()</c></tag>
+ <item><p>Value of a configuration parameter.</p></item>
+ </taglist>
</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>sys.config</c>. This file is to 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
+ <p>This means that specifying another <c>.config</c> file, or more
+ <c>.config</c> files, leads to inconsistent update of application
+ configurations. There is, however, a syntax for
+ <c>sys.config</c> that allows 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>
+ <taglist>
+ <tag><c>File = string()</c></tag>
+ <item>Name of another <c>.config</c> file.
+ Extension <c>.config</c> can be omitted. It is
+ recommended to use absolute paths. If a relative path is used,
+ <c>File</c> is searched, first, relative from <c>sys.config</c> directory, then relative
+ to the current working directory of the emulator, for backward compatibility.
+ This allow to use a <c>sys.config</c> pointing out other <c>.config</c> files in a release
+ or in a node started manually using <c>-config ...</c> with same result whatever
+ the current working directory.
+ </item>
+ </taglist>
<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>
+ parameter values overwritten.</p>
+ <p><em>Example:</em></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>
+ <p>This yields 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.
+ <p>The behavior if a file specified in <c>sys.config</c> does not
+ exist, or is erroneous, is backwards compatible.
Starting the runtime system will fail. Installing a new release
- version will not fail, but an error message is given and
+ version will not fail, but an error message is returned 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>
+ <title>See Also</title>
+ <p><seealso marker="app"><c>app(4)</c></seealso>,
+ <seealso marker="erts:erl"><c>erts:erl(1)</c></seealso>,
+ <seealso marker="doc/design_principles:des_princ">OTP Design Principles</seealso></p>
</section>
</fileref>