From 84adefa331c4159d432d22840663c38f155cd4c1 Mon Sep 17 00:00:00 2001
From: Erlang/OTP <otp@erlang.org>
Date: Fri, 20 Nov 2009 14:54:40 +0000
Subject: The R13B03 release.

---
 lib/kernel/doc/src/config.xml | 125 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 125 insertions(+)
 create mode 100644 lib/kernel/doc/src/config.xml

(limited to 'lib/kernel/doc/src/config.xml')

diff --git a/lib/kernel/doc/src/config.xml b/lib/kernel/doc/src/config.xml
new file mode 100644
index 0000000000..34398e90ac
--- /dev/null
+++ b/lib/kernel/doc/src/config.xml
@@ -0,0 +1,125 @@
+<?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>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>
+
-- 
cgit v1.2.3