aboutsummaryrefslogtreecommitdiffstats
path: root/system/doc
diff options
context:
space:
mode:
Diffstat (limited to 'system/doc')
-rw-r--r--system/doc/design_principles/spec_proc.xml49
-rw-r--r--system/doc/installation_guide/otp_version.xml96
-rw-r--r--system/doc/installation_guide/part.xml1
-rw-r--r--system/doc/installation_guide/xmlfiles.mk1
-rw-r--r--system/doc/reference_manual/character_set.xml132
-rw-r--r--system/doc/reference_manual/introduction.xml85
-rw-r--r--system/doc/reference_manual/part.xml3
-rw-r--r--system/doc/system_principles/part.xml1
-rw-r--r--system/doc/system_principles/versions.xml268
-rw-r--r--system/doc/system_principles/xmlfiles.mk3
10 files changed, 442 insertions, 197 deletions
diff --git a/system/doc/design_principles/spec_proc.xml b/system/doc/design_principles/spec_proc.xml
index 8de7a5fe03..69bf2e0448 100644
--- a/system/doc/design_principles/spec_proc.xml
+++ b/system/doc/design_principles/spec_proc.xml
@@ -130,7 +130,8 @@ ok
-export([alloc/0, free/1]).
-export([init/1]).
-export([system_continue/3, system_terminate/4,
- write_debug/3]).
+ write_debug/3,
+ system_get_state/1, system_replace_state/2]).
start_link() ->
proc_lib:start_link(ch4, init, [self()]).
@@ -156,15 +157,15 @@ init(Parent) ->
loop(Chs, Parent, Deb) ->
receive
{From, alloc} ->
- Deb2 = sys:handle_debug(Deb, {ch4, write_debug},
+ Deb2 = sys:handle_debug(Deb, fun ch4:write_debug/3,
ch4, {in, alloc, From}),
{Ch, Chs2} = alloc(Chs),
From ! {ch4, Ch},
- Deb3 = sys:handle_debug(Deb2, {ch4, write_debug},
+ Deb3 = sys:handle_debug(Deb2, fun ch4:write_debug/3,
ch4, {out, {ch4, Ch}, From}),
loop(Chs2, Parent, Deb3);
{free, Ch} ->
- Deb2 = sys:handle_debug(Deb, {ch4, write_debug},
+ Deb2 = sys:handle_debug(Deb, fun ch4:write_debug/3,
ch4, {in, {free, Ch}}),
Chs2 = free(Ch, Chs),
loop(Chs2, Parent, Deb2);
@@ -177,9 +178,16 @@ loop(Chs, Parent, Deb) ->
system_continue(Parent, Deb, Chs) ->
loop(Chs, Parent, Deb).
-system_terminate(Reason, Parent, Deb, Chs) ->
+system_terminate(Reason, _Parent, _Deb, _Chs) ->
exit(Reason).
+system_get_state(Chs) ->
+ {ok, Chs}.
+
+system_replace_state(StateFun, Chs) ->
+ NChs = StateFun(Chs),
+ {ok, NChs, NChs}.
+
write_debug(Dev, Event, Name) ->
io:format(Dev, "~p event = ~p~n", [Name, Event]).</pre>
<p>Example on how the simple debugging functions in <c>sys</c> can
@@ -281,10 +289,10 @@ sys:handle_debug(Deb, Func, Info, Event) => Deb1</code>
<p><c>Deb</c> is the debug structure.</p>
</item>
<item>
- <p><c>Func</c> is a tuple <c>{Module, Name}</c> (or a fun) and
- should specify a (user defined) function used to format
+ <p><c>Func</c> is a fun specifying
+ a (user defined) function used to format
trace output. For each system event, the format function is
- called as <c>Module:Name(Dev, Event, Info)</c>, where:</p>
+ called as <c>Func(Dev, Event, Info)</c>, where:</p>
<list type="bulleted">
<item>
<p><c>Dev</c> is the IO device to which the output should
@@ -319,15 +327,15 @@ sys:handle_debug(Deb, Func, Info, Event) => Deb1</code>
loop(Chs, Parent, Deb) ->
receive
{From, alloc} ->
- Deb2 = sys:handle_debug(Deb, {ch4, write_debug},
+ Deb2 = sys:handle_debug(Deb, fun ch4:write_debug/3,
ch4, {in, alloc, From}),
{Ch, Chs2} = alloc(Chs),
From ! {ch4, Ch},
- Deb3 = sys:handle_debug(Deb2, {ch4, write_debug},
+ Deb3 = sys:handle_debug(Deb2, fun ch4:write_debug/3,
ch4, {out, {ch4, Ch}, From}),
loop(Chs2, Parent, Deb3);
{free, Ch} ->
- Deb2 = sys:handle_debug(Deb, {ch4, write_debug},
+ Deb2 = sys:handle_debug(Deb, fun ch4:write_debug/3,
ch4, {in, {free, Ch}}),
Chs2 = free(Ch, Chs),
loop(Chs2, Parent, Deb2);
@@ -366,8 +374,15 @@ Module:system_terminate(Reason, Parent, Deb, State)</code>
<item><c>Module</c> is the name of the module.</item>
<item><c>Deb</c> is the debug structure.</item>
<item><c>State</c> is a term describing the internal state and
- is passed to <c>system_continue</c>/<c>system_terminate</c>.</item>
+ is passed to <c>system_continue</c>/<c>system_terminate</c>/
+ <c>system_get_state</c>/<c>system_replace_state</c>.</item>
</list>
+ <p>If the process should return its state <c>handle_system_msg</c> will call:</p>
+ <code type="none">
+Module:system_get_state(State)</code>
+ <p>or if the process should replace its state using the fun <c>StateFun</c>:</p>
+ <code type="none">
+Module:system_replace_state(StateFun, State)</code>
<p>In the example:</p>
<code type="none">
loop(Chs, Parent, Deb) ->
@@ -383,7 +398,15 @@ system_continue(Parent, Deb, Chs) ->
loop(Chs, Parent, Deb).
system_terminate(Reason, Parent, Deb, Chs) ->
- exit(Reason).</code>
+ exit(Reason).
+
+system_get_state(Chs) ->
+ {ok, Chs, Chs}.
+
+system_replace_state(StateFun, Chs) ->
+ NChs = StateFun(Chs),
+ {ok, NChs, NChs}.
+</code>
<p>If the special process is set to trap exits, note that if
the parent process terminates, the expected behavior is to
terminate with the same reason:</p>
diff --git a/system/doc/installation_guide/otp_version.xml b/system/doc/installation_guide/otp_version.xml
deleted file mode 100644
index 0ce5144160..0000000000
--- a/system/doc/installation_guide/otp_version.xml
+++ /dev/null
@@ -1,96 +0,0 @@
-<?xml version="1.0" encoding="utf-8" ?>
-<!DOCTYPE chapter SYSTEM "chapter.dtd">
-
-<chapter>
- <header>
- <copyright>
- <year>2014</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>OTP version</title>
- <prepared></prepared>
- <responsible></responsible>
- <docno></docno>
- <approved></approved>
- <checked></checked>
- <date>2014-02-19</date>
- <rev></rev>
- <file>otp_version.xml</file>
- </header>
- <p>As of OTP release 17, the OTP release number corresponds to
- the major part of the OTP version. The OTP version as a concept was
- introduced in OTP 17. In the normal case, the OTP version will be
- constructed as
- <c>&lt;Major&gt;.&lt;Minor&gt;.&lt;Patch&gt;</c> where <c>&lt;Major&gt;</c>
- is the most significant part. However, more dot separated parts than
- this may exist. The dot separated parts consists of integers. If all
- parts less significant than <c>&lt;Minor&gt;</c> equals <c>0</c>, they
- are omitted. The three normal parts
- <c>&lt;Major&gt;.&lt;Minor&gt;.&lt;Patch&gt;</c> will be changed as
- follows:</p>
- <taglist>
- <tag><c>&lt;Major&gt;</c></tag><item>Increased when major changes,
- including incompatibilities, have been made.</item>
- <tag><c>&lt;Minor&gt;</c></tag><item>Increased when new functionality
- has been added.</item>
- <tag><c>&lt;Patch&gt;</c></tag><item>Increased when pure bug fixes
- have been made.</item>
- </taglist>
- <p>When a part in the version number is increased, all less significant
- parts are set to <c>0</c>. Release candidates have an <c>-rc&lt;N&gt;</c>
- suffix. The suffix <c>-rc0</c> will be used during development up to
- the first release candidate.</p>
-
- <p>OTP of a specific version is a set of applications of
- specific versions. The application versions identified by
- an OTP version corresponds to application versions that
- have been tested together by the Erlang/OTP team at Ericsson AB.
- An OTP system can however be put together with applications from
- different OTP versions. Such a combination of application versions
- has not been tested by the Erlang/OTP team. It is therefore
- <em>always preferred to use OTP applications from one single OTP
- version</em>.</p>
-
- <p>Application versions will be managed the same way as the OTP version.
- Application versions part of a release candidate will however not have an
- <c>-rc&lt;N&gt;</c> suffix as the OTP version. Also note that a major
- increment in an application version does not necessarily imply a major
- increment of the OTP version. This depends on whether the
- major change in the application is considered as a major change for
- OTP as a whole or not.</p>
-
- <p>In an OTP source code tree as well as in an installed OTP
- development system, the OTP version can be read from the text
- file <c>OTP_VERSION</c> in the OTP installation root directory
- (<seealso marker="kernel:code#root_dir/0"><c>code:root_dir()</c></seealso>).</p>
- <p>If the version read from the <c>OTP_VERSION</c> file in a
- development system has a <c>**</c> suffix, the system has been
- patched using the <c>$ERL_TOP/otp_build patch_app</c> tool. In
- this case, the system consists of application versions from
- multiple OTP versions. The version preceding the <c>**</c>
- suffix corresponds to the OTP version of the base system that
- has been patched. Note that if a development system is updated by
- other means than <c>$ERL_TOP/otp_build patch_app</c>, the
- <c>OTP_VERSION</c> file may identify wrong OTP version.</p>
-
- <p>On a target system (see the
- <seealso marker="doc/system_principles:create_target">system principles</seealso>
- documentation) no <c>OTP_VERSION</c> file will exist. This since
- one easily can create a target system where it is hard to even
- determine the base OTP version.</p>
-</chapter>
-
diff --git a/system/doc/installation_guide/part.xml b/system/doc/installation_guide/part.xml
index 150df39512..19808fd165 100644
--- a/system/doc/installation_guide/part.xml
+++ b/system/doc/installation_guide/part.xml
@@ -31,7 +31,6 @@
<description>
<p>How to install Erlang/OTP on UNIX or Windows.</p>
</description>
- <xi:include href="otp_version.xml"/>
<xi:include href="install-binary.xml"/>
<xi:include href="verification.xml"/>
<xi:include href="INSTALL.xml"/>
diff --git a/system/doc/installation_guide/xmlfiles.mk b/system/doc/installation_guide/xmlfiles.mk
index 245491ab94..3995c607af 100644
--- a/system/doc/installation_guide/xmlfiles.mk
+++ b/system/doc/installation_guide/xmlfiles.mk
@@ -17,7 +17,6 @@
# %CopyrightEnd%
#
INST_GUIDE_CHAPTER_FILES = \
- otp_version.xml \
install-binary.xml \
verification.xml \
INSTALL.xml \
diff --git a/system/doc/reference_manual/character_set.xml b/system/doc/reference_manual/character_set.xml
new file mode 100644
index 0000000000..884898eb34
--- /dev/null
+++ b/system/doc/reference_manual/character_set.xml
@@ -0,0 +1,132 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE chapter SYSTEM "chapter.dtd">
+
+<chapter>
+ <header>
+ <copyright>
+ <year>2014</year><year>2014</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>Character Set and Source File Encoding</title>
+ <prepared></prepared>
+ <docno></docno>
+ <date></date>
+ <rev></rev>
+ <file>character_set.xml</file>
+ </header>
+
+ <section>
+ <title>Character Set</title>
+ <p>In Erlang 4.8/OTP R5A the syntax of Erlang tokens was extended to
+ allow the use of the full ISO-8859-1 (Latin-1) character set. This
+ is noticeable in the following ways:</p>
+ <list type="bulleted">
+ <item>
+ <p>All the Latin-1 printable characters can be used and are
+ shown without the escape backslash convention.</p>
+ </item>
+ <item>
+ <p>Atoms and variables can use all Latin-1 letters.</p>
+ </item>
+ </list>
+ <table>
+ <row>
+ <cell align="left" valign="middle"><em>Octal</em></cell>
+ <cell align="left" valign="middle"><em>Decimal</em></cell>
+ <cell align="left" valign="middle">&nbsp;</cell>
+ <cell align="left" valign="middle"><em>Class</em></cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle">200 - 237</cell>
+ <cell align="left" valign="middle">128 - 159</cell>
+ <cell align="left" valign="middle">&nbsp;</cell>
+ <cell align="left" valign="middle">Control characters</cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle">240 - 277</cell>
+ <cell align="left" valign="middle">160 - 191</cell>
+ <cell align="right" valign="middle">- &iquest;</cell>
+ <cell align="left" valign="middle">Punctuation characters</cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle">300 - 326</cell>
+ <cell align="left" valign="middle">192 - 214</cell>
+ <cell align="center" valign="middle">&Agrave; - &Ouml;</cell>
+ <cell align="left" valign="middle">Uppercase letters</cell>
+ </row>
+ <row>
+ <cell align="center" valign="middle">327</cell>
+ <cell align="center" valign="middle">215</cell>
+ <cell align="center" valign="middle">&times;</cell>
+ <cell align="left" valign="middle">Punctuation character</cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle">330 - 336</cell>
+ <cell align="left" valign="middle">216 - 222</cell>
+ <cell align="center" valign="middle">&Oslash; - &THORN;</cell>
+ <cell align="left" valign="middle">Uppercase letters</cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle">337 - 366</cell>
+ <cell align="left" valign="middle">223 - 246</cell>
+ <cell align="center" valign="middle">&szlig; - &ouml;</cell>
+ <cell align="left" valign="middle">Lowercase letters</cell>
+ </row>
+ <row>
+ <cell align="center" valign="middle">367</cell>
+ <cell align="center" valign="middle">247</cell>
+ <cell align="center" valign="middle">&divide;</cell>
+ <cell align="left" valign="middle">Punctuation character</cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle">370 - 377</cell>
+ <cell align="left" valign="middle">248 - 255</cell>
+ <cell align="center" valign="middle">&oslash; - &yuml;</cell>
+ <cell align="left" valign="middle">Lowercase letters</cell>
+ </row>
+ <tcaption>Character Classes.</tcaption>
+ </table>
+ <p>In Erlang/OTP R16B the syntax of Erlang tokens was extended to
+ handle Unicode. To begin with the support is limited to
+ strings, but Erlang/OTP 18 is expected to handle Unicode atoms
+ as well. More about the usage of Unicode in Erlang source files
+ can be found in <seealso
+ marker="stdlib:unicode_usage#unicode_in_erlang">STDLIB's User's
+ Guide</seealso>.</p>
+ </section>
+ <section>
+ <title>Source File Encoding</title>
+ <p>The Erlang source file <marker
+ id="encoding">encoding</marker> is selected by a
+ comment in one of the first two lines of the source file. The
+ first string that matches the regular expression
+ <c>coding\s*[:=]\s*([-a-zA-Z0-9])+</c> selects the encoding. If
+ the matching string is not a valid encoding it is ignored. The
+ valid encodings are <c>Latin-1</c> and <c>UTF-8</c> where the
+ case of the characters can be chosen freely.</p>
+ <p>The following example selects UTF-8 as default encoding:</p>
+ <pre>
+%% coding: utf-8</pre>
+ <p>Two more examples, both selecting Latin-1 as default encoding:</p>
+ <pre>
+%% For this file we have chosen encoding = Latin-1</pre>
+ <pre>
+%% -*- coding: latin-1 -*-</pre>
+ <p>The default encoding for Erlang source files was changed from
+ Latin-1 to UTF-8 in Erlang OTP 17.0.</p>
+ </section>
+</chapter>
diff --git a/system/doc/reference_manual/introduction.xml b/system/doc/reference_manual/introduction.xml
index aa42967625..36bec17825 100644
--- a/system/doc/reference_manual/introduction.xml
+++ b/system/doc/reference_manual/introduction.xml
@@ -4,7 +4,7 @@
<chapter>
<header>
<copyright>
- <year>2003</year><year>2013</year>
+ <year>2003</year><year>2014</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
@@ -79,88 +79,5 @@
when xor</p>
</section>
- <section>
- <title>Character Set</title>
- <p>In Erlang 4.8/OTP R5A the syntax of Erlang tokens was extended to
- allow the use of the full ISO-8859-1 (Latin-1) character set. This
- is noticeable in the following ways:</p>
- <list type="bulleted">
- <item>
- <p>All the Latin-1 printable characters can be used and are
- shown without the escape backslash convention.</p>
- </item>
- <item>
- <p>Atoms and variables can use all Latin-1 letters.</p>
- </item>
- </list>
- <table>
- <row>
- <cell align="left" valign="middle"><em>Octal</em></cell>
- <cell align="left" valign="middle"><em>Decimal</em></cell>
- <cell align="left" valign="middle">&nbsp;</cell>
- <cell align="left" valign="middle"><em>Class</em></cell>
- </row>
- <row>
- <cell align="left" valign="middle">200 - 237</cell>
- <cell align="left" valign="middle">128 - 159</cell>
- <cell align="left" valign="middle">&nbsp;</cell>
- <cell align="left" valign="middle">Control characters</cell>
- </row>
- <row>
- <cell align="left" valign="middle">240 - 277</cell>
- <cell align="left" valign="middle">160 - 191</cell>
- <cell align="right" valign="middle">- &iquest;</cell>
- <cell align="left" valign="middle">Punctuation characters</cell>
- </row>
- <row>
- <cell align="left" valign="middle">300 - 326</cell>
- <cell align="left" valign="middle">192 - 214</cell>
- <cell align="center" valign="middle">&Agrave; - &Ouml;</cell>
- <cell align="left" valign="middle">Uppercase letters</cell>
- </row>
- <row>
- <cell align="center" valign="middle">327</cell>
- <cell align="center" valign="middle">215</cell>
- <cell align="center" valign="middle">&times;</cell>
- <cell align="left" valign="middle">Punctuation character</cell>
- </row>
- <row>
- <cell align="left" valign="middle">330 - 336</cell>
- <cell align="left" valign="middle">216 - 222</cell>
- <cell align="center" valign="middle">&Oslash; - &THORN;</cell>
- <cell align="left" valign="middle">Uppercase letters</cell>
- </row>
- <row>
- <cell align="left" valign="middle">337 - 366</cell>
- <cell align="left" valign="middle">223 - 246</cell>
- <cell align="center" valign="middle">&szlig; - &ouml;</cell>
- <cell align="left" valign="middle">Lowercase letters</cell>
- </row>
- <row>
- <cell align="center" valign="middle">367</cell>
- <cell align="center" valign="middle">247</cell>
- <cell align="center" valign="middle">&divide;</cell>
- <cell align="left" valign="middle">Punctuation character</cell>
- </row>
- <row>
- <cell align="left" valign="middle">370 - 377</cell>
- <cell align="left" valign="middle">248 - 255</cell>
- <cell align="center" valign="middle">&oslash; - &yuml;</cell>
- <cell align="left" valign="middle">Lowercase letters</cell>
- </row>
- <tcaption>Character Classes.</tcaption>
- </table>
- <p>In Erlang/OTP R16 the syntax of Erlang tokens was extended to
- handle Unicode. To begin with the support is limited to strings,
- but Erlang/OTP R18 is expected to handle Unicode atoms as well.
- More about the usage of Unicode in Erlang source files can be
- found in <seealso
- marker="stdlib:unicode_usage#unicode_in_erlang">STDLIB's User'S
- Guide</seealso>. The default encoding for Erlang source files
- is still Latin-1, but in Erlang/OTP R17 the default encoding
- will be UTF-8. The details on how to state the encoding of an
- Erlang source file can be found in <seealso
- marker="stdlib:epp#encoding">epp(3)</seealso>.</p>
- </section>
</chapter>
diff --git a/system/doc/reference_manual/part.xml b/system/doc/reference_manual/part.xml
index b4f114c268..ee8f3dd7eb 100644
--- a/system/doc/reference_manual/part.xml
+++ b/system/doc/reference_manual/part.xml
@@ -4,7 +4,7 @@
<part xmlns:xi="http://www.w3.org/2001/XInclude">
<header>
<copyright>
- <year>2003</year><year>2013</year>
+ <year>2003</year><year>2014</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
@@ -28,6 +28,7 @@
<rev></rev>
</header>
<xi:include href="introduction.xml"/>
+ <xi:include href="character_set.xml"/>
<xi:include href="data_types.xml"/>
<xi:include href="patterns.xml"/>
<xi:include href="modules.xml"/>
diff --git a/system/doc/system_principles/part.xml b/system/doc/system_principles/part.xml
index 915d5aca9b..811428baae 100644
--- a/system/doc/system_principles/part.xml
+++ b/system/doc/system_principles/part.xml
@@ -31,5 +31,6 @@
<xi:include href="system_principles.xml"/>
<xi:include href="error_logging.xml"/>
<xi:include href="create_target.xml"/>
+ <xi:include href="versions.xml"/>
</part>
diff --git a/system/doc/system_principles/versions.xml b/system/doc/system_principles/versions.xml
new file mode 100644
index 0000000000..2bf0d18010
--- /dev/null
+++ b/system/doc/system_principles/versions.xml
@@ -0,0 +1,268 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE chapter SYSTEM "chapter.dtd">
+
+<chapter>
+ <header>
+ <copyright>
+ <year>2014</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>Versions</title>
+ <prepared></prepared>
+ <responsible></responsible>
+ <docno></docno>
+ <approved></approved>
+ <checked></checked>
+ <date>2014-02-19</date>
+ <rev></rev>
+ <file>versions.xml</file>
+ </header>
+ <section><title>OTP Version</title>
+ <p>As of OTP release 17, the OTP release number corresponds to
+ the major part of the OTP version. The OTP version as a concept was
+ introduced in OTP 17. The <seealso marker="#version_scheme">version
+ scheme</seealso> used is described in more detail below.</p>
+
+ <p>OTP of a specific version is a set of applications of specific
+ versions. The application versions identified by an OTP version
+ corresponds to application versions that have been tested together
+ by the Erlang/OTP team at Ericsson AB. An OTP system can however be
+ put together with applications from different OTP versions. Such a
+ combination of application versions has not been tested by the
+ Erlang/OTP team. It is therefore <em>always preferred to use OTP
+ applications from one single OTP version</em>.</p>
+
+ <p>Release candidates have an <c>-rc&lt;N&gt;</c>
+ suffix. The suffix <c>-rc0</c> will be used during development up to
+ the first release candidate.</p>
+
+ <section><title>Retrieving Current OTP Version</title>
+ <p>In an OTP source code tree, the OTP version can be read from
+ the text file <c>&lt;OTP source root&gt;/OTP_VERSION</c>. The
+ absolute path to the file can be constructed by calling
+ <c>filename:join([<seealso marker="kernel:code#root_dir/0">code:root_dir()</seealso>, "OTP_VERSION"])</c>.</p>
+ <p>In an installed OTP development system, the OTP version can be read
+ from the text file <c>&lt;OTP installation root&gt;/releases/&lt;OTP release number&gt;/OTP_VERSION</c>.
+ The absolute path to the file can by constructed by calling
+ <c>filename:join([<seealso marker="kernel:code#root_dir/0">code:root_dir()</seealso>, "releases", <seealso marker="erts:erlang#system_info_otp_release">erlang:system_info(otp_release)</seealso>, "OTP_VERSION"]).</c></p>
+ <p>If the version read from the <c>OTP_VERSION</c> file in a
+ development system has a <c>**</c> suffix, the system has been
+ patched using the
+ <seealso marker="doc/installation_guide:PATCH-APP"><c>$ERL_TOP/otp_build patch_app</c></seealso>
+ tool. In this case, the system consists of application versions from
+ multiple OTP versions. The version preceding the <c>**</c>
+ suffix corresponds to the OTP version of the base system that
+ has been patched. Note that if a development system is updated by
+ other means than <c>$ERL_TOP/otp_build patch_app</c>, the
+ <c>OTP_VERSION</c> file may identify wrong OTP version.</p>
+
+ <p>No <c>OTP_VERSION</c> file will be placed in a
+ <seealso marker="create_target">target system</seealso> created
+ by OTP tools. This since one easily can create a target system
+ where it is hard to even determine the base OTP version. You may,
+ however, place such a file there yourself if you know the OTP
+ version.</p>
+ </section>
+
+ <section><title>OTP Versions Table</title>
+ <p>The text file <c>&lt;OTP source root&gt;/otp_versions.table</c> that
+ is part of the source code contains information about all OTP versions
+ from OTP 17.0 up to current OTP version. Each line contains information
+ about application versions that are part of a specific OTP version, and
+ is on the format:</p>
+<pre>
+&lt;OtpVersion&gt; : &lt;ChangedAppVersions&gt; # &lt;UnchangedAppVersions&gt; :
+</pre>
+ <p><c>&lt;OtpVersion&gt;</c> is on the format <c>OTP-&lt;VSN&gt;</c>, i.e.,
+ the same as the git tag used to identify the source.
+ <c>&lt;ChangedAppVersions&gt;</c> and <c>&lt;UnchangedAppVersions&gt;</c>
+ are space separated lists of application versions on the
+ format <c>&lt;application&gt;-&lt;vsn&gt;</c>.
+ <c>&lt;ChangedAppVersions&gt;</c> corresponds to changed applications
+ with new version numbers in this OTP version, and
+ <c>&lt;UnchangedAppVersions&gt;</c> corresponds to unchanged application
+ versions in this OTP version. Both of them might be empty, although
+ not at the same time. If &lt;ChangedAppVersions&gt; is empty, no changes
+ has been made that change the build result of any application. This could
+ for example be a pure bug fix of the build system. The order of lines
+ is undefined. All white space characters in this file are either space
+ (character 32) or line-break (character 10).</p>
+ <p>Using ordinary UNIX tools like <c>sed</c> and <c>grep</c> one
+ can easily find answers to various questions like:</p>
+ <taglist>
+ <tag>Which OTP versions are <c>kernel-3.0</c> part of?</tag>
+ <item><p><c> $ grep ' kernel-3\.0 ' otp_versions.table</c></p></item>
+ <tag>In which OTP version was <c>kernel-3.0</c> introduced?</tag>
+ <item><p><c> $ sed 's/#.*//;/ kernel-3\.0 /!d' otp_versions.table</c></p></item>
+ </taglist>
+ <p>The above commands give a bit more information than the exact answers,
+ but adequate information when manually searching for answers to these
+ questions.</p>
+ <warning><p>The format of the <c>otp_versions.table</c> might be subject
+ to changes during the OTP 17 release.</p></warning>
+ </section>
+ </section>
+
+ <section><title>Application Version</title>
+ <p>As of OTP 17.0 application versions will use the same
+ <seealso marker="#version_scheme">version scheme</seealso> as the
+ OTP version. Application versions part of a release candidate will
+ however not have an <c>-rc&lt;N&gt;</c> suffix as the OTP version.
+ Also note that a major increment in an application version does not
+ necessarily imply a major increment of the OTP version. This depends
+ on whether the major change in the application is considered as a
+ major change for OTP as a whole or not.</p>
+ </section>
+
+ <marker id="version_scheme"/>
+ <section><title>Version Scheme</title>
+ <note>Note that the version scheme was changed as of OTP 17.0. This implies
+ that application versions used prior to OTP 17.0 do not adhere to this
+ version scheme. <seealso marker="#otp_17_0_app_versions">A list of
+ application versions used in OTP 17.0</seealso> can be found
+ at the end of this document.</note>
+
+ <p>In the normal case, a version will be constructed as
+ <c>&lt;Major&gt;.&lt;Minor&gt;.&lt;Patch&gt;</c> where <c>&lt;Major&gt;</c>
+ is the most significant part. However, more dot separated parts than
+ this may exist. The dot separated parts consists of non-negative integers.
+ If all parts less significant than <c>&lt;Minor&gt;</c> equals <c>0</c>,
+ they are omitted. The three normal parts
+ <c>&lt;Major&gt;.&lt;Minor&gt;.&lt;Patch&gt;</c> will be changed as
+ follows:</p>
+ <taglist>
+ <tag><c>&lt;Major&gt;</c></tag><item>Increased when major changes,
+ including incompatibilities, have been made.</item>
+ <tag><c>&lt;Minor&gt;</c></tag><item>Increased when new functionality
+ has been added.</item>
+ <tag><c>&lt;Patch&gt;</c></tag><item>Increased when pure bug fixes
+ have been made.</item>
+ </taglist>
+ <p>When a part in the version number is increased, all less significant
+ parts are set to <c>0</c>.</p>
+
+ <p>An application version or an OTP version identifies source code
+ versions. That is, it does not imply anything about how the application
+ or OTP has been built.</p>
+
+ <section><title>Order of Versions</title>
+ <p>Version numbers in general are only partially ordered. However,
+ normal version numbers (with three parts) as of OTP 17.0 have a total
+ or linear order. This applies both to normal OTP versions and
+ normal application versions.</p>
+
+ <p>When comparing two version numbers that have an order, one
+ compare each part as ordinary integers from the most
+ significant part towards less significant parts. The order is
+ defined by the first parts of the same significance that
+ differ. An OTP version with a larger version include all
+ changes that that are part of a smaller OTP version. The same
+ goes for application versions.</p>
+
+ <p>In the general case, versions may have more than three parts. In
+ this case the versions are only partially ordered. Note that such
+ versions are only used in exceptional cases. When an extra
+ part (out of the normal three parts) is added to a version number,
+ a new branch of versions is made. The new branch has a linear
+ order against the base version. However, versions on different
+ branches have no order. Since they have no order, we
+ only know that they all include what is included in their
+ closest common ancestor. When branching multiple times from the
+ same base version, <c>0</c> parts are added between the base
+ version and the least significant <c>1</c> part until a unique
+ version is found. Versions that have an order can be compared
+ as described in the paragraph above.</p>
+
+ <p>An example of branched versions: The version <c>6.0.2.1</c>
+ is a branched version from the base version <c>6.0.2</c>.
+ Versions on the form <c>6.0.2.&lt;X&gt;</c> can be compared
+ with normal versions smaller than or equal to <c>6.0.2</c>,
+ and other versions on the form <c>6.0.2.&lt;X&gt;</c>. The
+ version <c>6.0.2.1</c> will include all changes in
+ <c>6.0.2</c>. However, <c>6.0.3</c> will most likely
+ <em>not</em> include all changes in <c>6.0.2.1</c> (note that
+ these versions have no order). A second branched version from the base
+ version <c>6.0.2</c> will be version <c>6.0.2.0.1</c>, and a
+ third branched version will be <c>6.0.2.0.0.1</c>.</p>
+ </section>
+ </section>
+
+ <marker id="otp_17_0_app_versions"/>
+ <section><title>OTP 17.0 Application Versions</title>
+ <p>The following application versions were part of OTP 17.0. If
+ the normal part of an applications version number compares
+ as smaller than the corresponding application version in this list,
+ the version number does not adhere to the version scheme introduced
+ in OTP 17.0 and should be considered as not having an order against
+ versions used as of OTP 17.0.</p>
+ <list>
+ <item><c>asn1-3.0</c></item>
+ <item><c>common_test-1.8</c></item>
+ <item><c>compiler-5.0</c></item>
+ <item><c>cosEvent-2.1.15</c></item>
+ <item><c>cosEventDomain-1.1.14</c></item>
+ <item><c>cosFileTransfer-1.1.16</c></item>
+ <item><c>cosNotification-1.1.21</c></item>
+ <item><c>cosProperty-1.1.17</c></item>
+ <item><c>cosTime-1.1.14</c></item>
+ <item><c>cosTransactions-1.2.14</c></item>
+ <item><c>crypto-3.3</c></item>
+ <item><c>debugger-4.0</c></item>
+ <item><c>dialyzer-2.7</c></item>
+ <item><c>diameter-1.6</c></item>
+ <item><c>edoc-0.7.13</c></item>
+ <item><c>eldap-1.0.3</c></item>
+ <item><c>erl_docgen-0.3.5</c></item>
+ <item><c>erl_interface-3.7.16</c></item>
+ <item><c>erts-6.0</c></item>
+ <item><c>et-1.5</c></item>
+ <item><c>eunit-2.2.7</c></item>
+ <item><c>gs-1.5.16</c></item>
+ <item><c>hipe-3.10.3</c></item>
+ <item><c>ic-4.3.5</c></item>
+ <item><c>inets-5.10</c></item>
+ <item><c>jinterface-1.5.9</c></item>
+ <item><c>kernel-3.0</c></item>
+ <item><c>megaco-3.17.1</c></item>
+ <item><c>mnesia-4.12</c></item>
+ <item><c>observer-2.0</c></item>
+ <item><c>odbc-2.10.20</c></item>
+ <item><c>orber-3.6.27</c></item>
+ <item><c>os_mon-2.2.15</c></item>
+ <item><c>ose-1.0</c></item>
+ <item><c>otp_mibs-1.0.9</c></item>
+ <item><c>parsetools-2.0.11</c></item>
+ <item><c>percept-0.8.9</c></item>
+ <item><c>public_key-0.22</c></item>
+ <item><c>reltool-0.6.5</c></item>
+ <item><c>runtime_tools-1.8.14</c></item>
+ <item><c>sasl-2.4</c></item>
+ <item><c>snmp-4.25.1</c></item>
+ <item><c>ssh-3.0.1</c></item>
+ <item><c>ssl-5.3.4</c></item>
+ <item><c>stdlib-2.0</c></item>
+ <item><c>syntax_tools-1.6.14</c></item>
+ <item><c>test_server-3.7</c></item>
+ <item><c>tools-2.6.14</c></item>
+ <item><c>typer-0.9.6</c></item>
+ <item><c>webtool-0.8.10</c></item>
+ <item><c>wx-1.2</c></item>
+ <item><c>xmerl-1.3.7</c></item>
+ </list>
+ </section>
+</chapter>
+
diff --git a/system/doc/system_principles/xmlfiles.mk b/system/doc/system_principles/xmlfiles.mk
index 4cbc00ed52..9743949798 100644
--- a/system/doc/system_principles/xmlfiles.mk
+++ b/system/doc/system_principles/xmlfiles.mk
@@ -19,4 +19,5 @@
SYSTEM_PRINCIPLES_CHAPTER_FILES = \
system_principles.xml \
error_logging.xml \
- create_target.xml
+ create_target.xml \
+ versions.xml