diff options
| author | Björn Gustavsson <bjorn@erlang.org> | 2015-03-16 11:48:38 +0100 |
|---|---|---|
| committer | Björn Gustavsson <bjorn@erlang.org> | 2015-03-16 11:48:38 +0100 |
| commit | b90108ba566ff3754ebef667d2375be4d41d044e (patch) | |
| tree | 4f6f4221371035ed700dcf4ef76b3d4018733eac /system/doc/system_principles | |
| parent | a2481e05c8009962d5a3ec56eaeffc053718ec7f (diff) | |
| parent | 0a1d39481440eb033f48fbbc8889bc99eda85d41 (diff) | |
| download | otp-b90108ba566ff3754ebef667d2375be4d41d044e.tar.gz otp-b90108ba566ff3754ebef667d2375be4d41d044e.tar.bz2 otp-b90108ba566ff3754ebef667d2375be4d41d044e.zip | |
Merge branch 'bjorn/system-documentation'
* bjorn/system-documentation:
Replace "lambda head" with "fun" in compiler warning
Remove an historical note about fun representation before R6B
Replace mention of a tuple fun with an external fun
Update Interoperability Tutorial
Update System Principles
Update Erlang Reference Manual
Update Getting Started
Update Programming Examples
Update OAM Principles
Update Installation Guide
Update Embedded Systems User's Guide
Update Efficiency Guide
Update Design Principles
Diffstat (limited to 'system/doc/system_principles')
| -rw-r--r-- | system/doc/system_principles/create_target.xmlsrc | 367 | ||||
| -rw-r--r-- | system/doc/system_principles/error_logging.xml | 38 | ||||
| -rw-r--r-- | system/doc/system_principles/system_principles.xml | 186 | ||||
| -rw-r--r-- | system/doc/system_principles/upgrade.xml | 98 | ||||
| -rw-r--r-- | system/doc/system_principles/versions.xml | 288 |
5 files changed, 482 insertions, 495 deletions
diff --git a/system/doc/system_principles/create_target.xmlsrc b/system/doc/system_principles/create_target.xmlsrc index a8ee2d1245..7c566229ac 100644 --- a/system/doc/system_principles/create_target.xmlsrc +++ b/system/doc/system_principles/create_target.xmlsrc @@ -31,55 +31,54 @@ <rev>A</rev> <file>create_target.xml</file> </header> + <marker id="creating upgrading target system"></marker> - <section> - <title>Introduction</title> - <p>When creating a system using Erlang/OTP, the most simple way is - to install Erlang/OTP somewhere, install the application specific + <p>When creating a system using Erlang/OTP, the simplest way is + to install Erlang/OTP somewhere, install the application-specific code somewhere else, and then start the Erlang runtime system, - making sure the code path includes the application specific code.</p> - <p>Often it is not desirable to use an Erlang/OTP system as is. A - developer may create new Erlang/OTP compliant applications for a + making sure the code path includes the application-specific code.</p> + <p>It is often not desirable to use an Erlang/OTP system as is. A + developer can create new Erlang/OTP-compliant applications for a particular purpose, and several original Erlang/OTP applications - may be irrelevant for the purpose in question. Thus, there is a + can be irrelevant for the purpose in question. Thus, there is a need to be able to create a new system based on a given - Erlang/OTP system, where dispensable applications are removed, - and a set of new applications are included. Documentation and + Erlang/OTP system, where dispensable applications are removed + and new applications are included. Documentation and source code is irrelevant and is therefore not included in the new system.</p> - <p>This chapter is about creating such a system, which we call a + <p>This chapter is about creating such a system, which is called a <em>target system</em>.</p> - <p>In the following sections we consider creating target systems with - different requirements of functionality:</p> + <p>The following sections deal with target systems + with different requirements of functionality:</p> <list type="bulleted"> - <item>a <em>basic target system</em> that can be started by - calling the ordinary <c>erl</c> script, </item> - <item>a <em>simple target system</em> where also code - replacement in run-time can be performed, and</item> - <item>an <em>embedded target system</em> where there is also + <item>A <em>basic target system</em> that can be started by + calling the ordinary <c>erl</c> script.</item> + <item>A <em>simple target system</em> where also code + replacement in runtime can be performed.</item> + <item>An <em>embedded target system</em> where there is also support for logging output from the system to file for later inspection, and where the system can be started automatically - at boot time. </item> + at boot time.</item> </list> - <p>We only consider the case when Erlang/OTP is running on a UNIX - system.</p> - <p>In the <c>sasl</c> application there is an example Erlang - module <c>target_system.erl</c> that contains functions for - creating and installing a target system. This module is used in - the examples below, and the source code of the module is listed - at the end of this chapter.</p> - </section> + <p>Here is only considered the case when Erlang/OTP is running on a + UNIX system.</p> + <p>The <c>sasl</c> application includes the example Erlang + module <c>target_system.erl</c>, which contains functions for + creating and installing a target system. This module is used in + the following examples. The source code of the module is listed + in <seealso marker="#listing of target system"> + Listing of target_system.erl</seealso></p> <section> <marker id="create"/> <title>Creating a Target System</title> <p>It is assumed that you have a working Erlang/OTP system structured - according to the OTP Design Principles.</p> - <p><em>Step 1.</em> First create a <c>.rel</c> file (see <seealso - marker="sasl:rel">rel(4)</seealso>) that specifies the <c>erts</c> - version and lists all applications that should be included in the - new basic target system. An example is the following - <c>mysystem.rel</c> file:</p> + according to the OTP design principles.</p> + <p><em>Step 1.</em> Create a <c>.rel</c> file (see the + <seealso marker="sasl:rel">rel(4)</seealso> manual page in + SASL), which specifies the ERTS version and lists + all applications that are to be included in the new basic target + system. An example is the following <c>mysystem.rel</c> file:</p> <code type="none"> %% mysystem.rel {release, @@ -91,23 +90,23 @@ {pea, "1.0"}]}.</code> <p>The listed applications are not only original Erlang/OTP applications but possibly also new applications that you have - written yourself (here exemplified by the application - <c>pea</c>). </p> - <p><em>Step 2.</em> From the directory where the <c>mysystem.rel</c> - file reside, start the Erlang/OTP system:</p> + written (here exemplified by the application Pea (<c>pea</c>)).</p> + <p><em>Step 2.</em> Start Erlang/OTP from the directory where + the <c>mysystem.rel</c> file resides:</p> <pre> os> <input>erl -pa /home/user/target_system/myapps/pea-1.0/ebin</input></pre> - <p>where also the path to the <c>pea-1.0</c> ebin directory is - provided. </p> - <p><em>Step 3.</em> Now create the target system: </p> + <p>Here also the path to the <c>pea-1.0</c> ebin directory is + provided.</p> + <p><em>Step 3.</em> Create the target system:</p> <pre> 1> <input>target_system:create("mysystem").</input></pre> - <p>The <c>target_system:create/1</c> function does the following:</p> + <p>The function <c>target_system:create/1</c> performs the + following:</p> <list type="ordered"> - <item>Reads the <c>mysystem.rel</c> file, and creates a new file - <c>plain.rel</c> which is identical to former, except that it - only lists the <c>kernel</c> and <c>stdlib</c> applications. </item> - <item>From the <c>mysystem.rel</c> and <c>plain.rel</c> files + <item>Reads the file <c>mysystem.rel</c> and creates a new file + <c>plain.rel</c> that is identical to the former, except that it + only lists the Kernel and STDLIB applications.</item> + <item>From the files <c>mysystem.rel</c> and <c>plain.rel</c> creates the files <c>mysystem.script</c>, <c>mysystem.boot</c>, <c>plain.script</c>, and <c>plain.boot</c> through a call to @@ -124,26 +123,26 @@ releases/mysystem.rel lib/kernel-2.16.4/ lib/stdlib-1.19.4/ lib/sasl-2.3.4/ -lib/pea-1.0/ </code> +lib/pea-1.0/</code> <p>The file <c>releases/FIRST/start.boot</c> is a copy of our <c>mysystem.boot</c></p> <p>The release resource file <c>mysystem.rel</c> is duplicated in the tar file. Originally, this file was only stored in - the <c>releases</c> directory in order to make it possible + the <c>releases</c> directory to make it possible for the <c>release_handler</c> to extract this file separately. After unpacking the tar file, <c>release_handler</c> would automatically copy the file to <c>releases/FIRST</c>. However, sometimes the tar file is unpacked without involving - the <c>release_handler</c> (e.g. when unpacking the first - target system) and therefore the file is now instead + the <c>release_handler</c> (for example, when unpacking the + first target system). The file is therefore now instead duplicated in the tar file so no manual copying is - necessary.</p> + needed.</p> </item> - <item>Creates the temporary directory <c>tmp</c> and extracts the tar file - <c>mysystem.tar.gz</c> into that directory. </item> - <item>Deletes the <c>erl</c> and <c>start</c> files from - <c>tmp/erts-5.10.4/bin</c>. These files will be created again from + <item>Creates the temporary directory <c>tmp</c> and extracts + the tar file <c>mysystem.tar.gz</c> into that directory.</item> + <item>Deletes the files <c>erl</c> and <c>start</c> from + <c>tmp/erts-5.10.4/bin</c>. These files are created again from source when installing the release.</item> <item>Creates the directory <c>tmp/bin</c>.</item> <item>Copies the previously created file <c>plain.boot</c> to @@ -151,31 +150,31 @@ lib/pea-1.0/ </code> <item>Copies the files <c>epmd</c>, <c>run_erl</c>, and <c>to_erl</c> from the directory <c>tmp/erts-5.10.4/bin</c> to the directory <c>tmp/bin</c>.</item> - <item>Creates the directory <c>tmp/log</c>, which will be used + <item>Creates the directory <c>tmp/log</c>, which is used if the system is started as embedded with the <c>bin/start</c> script.</item> <item>Creates the file <c>tmp/releases/start_erl.data</c> with the contents "5.10.4 FIRST". This file is to be passed as data - file to the <c>start_erl</c> script. - </item> + file to the <c>start_erl</c> script.</item> <item>Recreates the file <c>mysystem.tar.gz</c> from the directories - in the directory <c>tmp</c>, and removes <c>tmp</c>.</item> + in the directory <c>tmp</c> and removes <c>tmp</c>.</item> </list> </section> <section> <title>Installing a Target System</title> <p><em>Step 4.</em> Install the created target system in a - suitable directory. </p> + suitable directory.</p> <pre> 2> <input>target_system:install("mysystem", "/usr/local/erl-target").</input></pre> - <p>The function <c>target_system:install/2</c> does the following: + <p>The function <c>target_system:install/2</c> performs the following: </p> <list type="ordered"> <item>Extracts the tar file <c>mysystem.tar.gz</c> into the target directory <c>/usr/local/erl-target</c>.</item> - <item>In the target directory reads the file <c>releases/start_erl.data</c> - in order to find the Erlang runtime system version ("5.10.4").</item> + <item>In the target directory reads the file + <c>releases/start_erl.data</c> to find the Erlang runtime system + version ("5.10.4").</item> <item>Substitutes <c>%FINAL_ROOTDIR%</c> and <c>%EMU%</c> for <c>/usr/local/erl-target</c> and <c>beam</c>, respectively, in the files <c>erl.src</c>, <c>start.src</c>, and @@ -184,97 +183,102 @@ lib/pea-1.0/ </code> <c>start</c>, and <c>run_erl</c> in the target <c>bin</c> directory.</item> <item>Finally the target <c>releases/RELEASES</c> file is created - from data in the <c>releases/mysystem.rel</c> file.</item> + from data in the file <c>releases/mysystem.rel</c>.</item> </list> </section> <section> <marker id="start"/> <title>Starting a Target System</title> - <p>Now we have a target system that can be started in various ways.</p> - <p>We start it as a <em>basic target system</em> by invoking</p> + <p>Now we have a target system that can be started in various ways. + We start it as a <em>basic target system</em> by invoking:</p> <pre> os> <input>/usr/local/erl-target/bin/erl</input></pre> - <p>where only the <c>kernel</c> and <c>stdlib</c> applications are - started, i.e. the system is started as an ordinary development - system. There are only two files needed for all this to work: - <c>bin/erl</c> file (obtained from <c>erts-5.10.4/bin/erl.src</c>) - and the <c>bin/start.boot</c> file (a copy of <c>plain.boot</c>).</p> + <p>Here only the Kernel and STDLIB applications are + started, that is, the system is started as an ordinary development + system. Only two files are needed for all this to work:</p> + <list type="ordered"> + <item><c>bin/erl</c> (obtained from + <c>erts-5.10.4/bin/erl.src</c>)</item> + <item><c>bin/start.boot</c> (a copy of + <c>plain.boot</c>)</item> + </list> <p>We can also start a distributed system (requires <c>bin/epmd</c>).</p> <p>To start all applications specified in the original - <c>mysystem.rel</c> file, use the <c>-boot</c> flag as follows:</p> + <c>mysystem.rel</c> file, use flag <c>-boot</c> as follows:</p> <pre> os> <input>/usr/local/erl-target/bin/erl -boot /usr/local/erl-target/releases/FIRST/start</input></pre> - <p>We start a <em>simple target system</em> as above. The only difference - is that also the file <c>releases/RELEASES</c> is present for - code replacement in run-time to work.</p> - <p>To start an <em>embedded target system</em> the shell script - <c>bin/start</c> is used. That shell script calls + <p>We start a <em>simple target system</em> as above. The only + difference is that also the file <c>releases/RELEASES</c> is + present for code replacement in runtime to work.</p> + <p>To start an <em>embedded target system</em>, the shell script + <c>bin/start</c> is used. The script calls <c>bin/run_erl</c>, which in turn calls <c>bin/start_erl</c> (roughly, <c>start_erl</c> is an embedded variant of - <c>erl</c>). </p> + <c>erl</c>).</p> <p>The shell script <c>start</c>, which is generated from erts-5.10.4/bin/start.src during installation, is only an - example. You should edit it to suite your needs. Typically it is + example. Edit it to suite your needs. Typically it is executed when the UNIX system boots.</p> <p><c>run_erl</c> is a wrapper that provides logging of output from - the run-time system to file. It also provides a simple mechanism + the runtime system to file. It also provides a simple mechanism for attaching to the Erlang shell (<c>to_erl</c>).</p> - <p><c>start_erl</c> requires the root directory - (<c>"/usr/local/erl-target"</c>), the releases directory - (<c>"/usr/local/erl-target/releases"</c>), and the location of - the <c>start_erl.data</c> file. It reads the run-time system - version (<c>"5.10.4"</c>) and release version (<c>"FIRST"</c>) from - the <c>start_erl.data</c> file, starts the run-time system of the - version found, and provides <c>-boot</c> flag specifying the boot - file of the release version found - (<c>"releases/FIRST/start.boot"</c>).</p> - <p><c>start_erl</c> also assumes that there is <c>sys.config</c> in - release version directory (<c>"releases/FIRST/sys.config"</c>). That - is the topic of the next section (see below).</p> - <p>The <c>start_erl</c> shell script should normally not be + <p><c>start_erl</c> requires:</p> + <list type="ordered"> + <item>The root directory (<c>"/usr/local/erl-target"</c>)</item> + <item>The releases directory + (<c>"/usr/local/erl-target/releases"</c></item> + <item>The location of the file <c>start_erl.data</c></item> + </list> + <p>It performs the following:</p> + <list type="ordered"> + <item>Reads the runtime system version (<c>"5.10.4"</c>) and + release version (<c>"FIRST"</c>) from the file + <c>start_erl.data</c>.</item> + <item>Starts the runtime system of the version found.</item> + <item>Provides the flag <c>-boot</c> specifying the boot + file of the release version found + (<c>"releases/FIRST/start.boot"</c>).</item> + </list> + <p><c>start_erl</c> also assumes that there is <c>sys.config</c> + in the release version directory (<c>"releases/FIRST/sys.config"</c>). + That is the topic of the next section.</p> + <p>The <c>start_erl</c> shell script is normally not to be altered by the user.</p> </section> <section> <title>System Configuration Parameters</title> - <p>As was pointed out above <c>start_erl</c> requires a - <c>sys.config</c> in the release version directory - (<c>"releases/FIRST/sys.config"</c>). If there is no such a - file, the system start will fail. Hence such a file has to - be added as well.</p> - <p></p> - <p>If you have system configuration data that are neither file - location dependent nor site dependent, it may be convenient to - create the <c>sys.config</c> early, so that it becomes a part of + <p>As was mentioned in the previous section, <c>start_erl</c> + requires a <c>sys.config</c> in the release version directory + (<c>"releases/FIRST/sys.config"</c>). If there is no such + file, the system start fails. Such a file must therefore + also be added.</p> + <p>If you have system configuration data that is neither + file-location-dependent nor site-dependent, it can be convenient + to create <c>sys.config</c> early, so it becomes part of the target system tar file created by - <c>target_system:create/1</c>. In fact, if you create, in the - current directory, not only the <c>mysystem.rel</c> file, but - also a <c>sys.config</c> file, that latter file will be tacitly + <c>target_system:create/1</c>. In fact, if you in the + current directory create not only the file <c>mysystem.rel</c>, + but also file <c>sys.config</c>, the latter file is tacitly put in the appropriate directory.</p> </section> <section> - <title>Differences from the Install Script</title> - <p>The above <c>install/2</c> procedure differs somewhat from that + <title>Differences From the Install Script</title> + <p>The previous <c>install/2</c> procedure differs somewhat from that of the ordinary <c>Install</c> shell script. In fact, <c>create/1</c> makes the release package as complete as possible, and leave to the - <c>install/2</c> procedure to finish by only considering location - dependent files.</p> + <c>install/2</c> procedure to finish by only considering + location-dependent files.</p> </section> <section> <title>Creating the Next Version</title> - - <p> - In this example the <c>pea</c> application has been changed, and - so are <c>erts</c>, <c>kernel</c>, <c>stdlib</c> and - <c>sasl</c>. - </p> - - <p> - <em>Step 1.</em> Create the <c>.rel</c> file: - </p> + <p>In this example the Pea application has been changed, and + so are the applications ERTS, Kernel, STDLIB + and SASL.</p> + <p><em>Step 1.</em> Create the file <c>.rel</c>:</p> <code type="none"> %% mysystem2.rel {release, @@ -284,65 +288,49 @@ os> <input>/usr/local/erl-target/bin/erl -boot /usr/local/erl-target/releases/FI {stdlib, "2.0"}, {sasl, "2.4"}, {pea, "2.0"}]}.</code> - <p> - <em>Step 2.</em> Create the application upgrade file (see - <seealso marker="sasl:appup">appup(4)</seealso>) for <c>pea</c>, - for example: - </p> + <p><em>Step 2.</em> Create the application upgrade file (see the + <seealso marker="sasl:appup">appup(4)</seealso> manual page in + SASL) for Pea, for example:</p> <code type="none"> %% pea.appup {"2.0", [{"1.0",[{load_module,pea_lib}]}], [{"1.0",[{load_module,pea_lib}]}]}.</code> - <p> - <em>Step 3.</em> From the directory where the - <c>mysystem2.rel</c> file reside, start the Erlang/OTP system: - </p> + <p><em>Step 3.</em> From the directory where the file + <c>mysystem2.rel</c> resides, start the Erlang/OTP system, + giving the path to the new version of Pea:</p> <pre> os> <input>erl -pa /home/user/target_system/myapps/pea-2.0/ebin</input></pre> - <p>giving the path to the new version of <c>pea</c>. </p> - - <p> - <em>Step 4.</em> Create the release upgrade file (see <seealso - marker="sasl:relup">relup(4)</seealso>): - </p> + <p><em>Step 4.</em> Create the release upgrade file (see the + <seealso marker="sasl:relup">relup(4)</seealso> manual page in + SASL):</p> <pre> -1> <input>systools:make_relup("mysystem2",["mysystem"],["mysystem"],[{path,["/home/user/target_system/myapps/pea-1.0/ebin","/my/old/erlang/lib/*/ebin"]}]).</input></pre> - <p> - where <c>"mysystem"</c> is the base release and - <c>"mysystem2"</c> is the release to upgrade to. - </p> - <p> - Note that the <c>path</c> option is used for pointing out the +1> <input>systools:make_relup("mysystem2",["mysystem"],["mysystem"], + [{path,["/home/user/target_system/myapps/pea-1.0/ebin", + "/my/old/erlang/lib/*/ebin"]}]).</input></pre> + <p>Here <c>"mysystem"</c> is the base release and + <c>"mysystem2"</c> is the release to upgrade to.</p> + <p>The <c>path</c> option is used for pointing out the old version of all applications. (The new versions are already - in the code path - assuming of course that the erlang node on + in the code path - assuming of course that the Erlang node on which this is executed is running the correct version of - Erlang/OTP.) - </p> - <p> - <em>Step 5.</em> Create the new release: - </p> + Erlang/OTP.)</p> + <p><em>Step 5.</em> Create the new release:</p> <pre> 2> <input>target_system:create("mysystem2").</input></pre> - <p> - Given that the <c>relup</c> file generated in step 4 above is - now located in the current directory, it will automatically be - included in the release package. - </p> + <p>Given that the file <c>relup</c> generated in Step 4 is + now located in the current directory, it is automatically + included in the release package.</p> </section> <section> <title>Upgrading the Target System</title> - <p> - This part is done on the target node, and for this example we + <p>This part is done on the target node, and for this example we want the node to be running as an embedded system with the - <c>-heart</c> option, allowing automatic restart of the - node. See <seealso marker="#start">Starting a Target - System</seealso> above for more information. - </p> - <p> - We add <c>-heart</c> to <c>bin/start</c>: - </p> + <c>-heart</c> option, allowing automatic restart of the node. + For more information, see <seealso marker="#start"> + Starting a Target System</seealso>.</p> + <p>We add <c>-heart</c> to <c>bin/start</c>:</p> <code type="none"> #!/bin/sh ROOTDIR=/usr/local/erl-target/ @@ -354,36 +342,27 @@ fi START_ERL_DATA=${1:-$RELDIR/start_erl.data} -$ROOTDIR/bin/run_erl -daemon /tmp/ $ROOTDIR/log "exec $ROOTDIR/bin/start_erl $ROOTDIR $RELDIR $START_ERL_DATA -heart</code> - <p> - And we use the simplest possible <c>sys.config</c>, which we - store in <c>releases/FIRST</c>: - </p> +$ROOTDIR/bin/run_erl -daemon /tmp/ $ROOTDIR/log "exec $ROOTDIR/bin/start_erl $ROOTDIR\ +$RELDIR $START_ERL_DATA -heart</code> + <p>We use the simplest possible <c>sys.config</c>, which we + store in <c>releases/FIRST</c>:</p> <code type="none"> %% sys.config [].</code> - <p> - Finally, in order to prepare the upgrade, we need to put the new + <p>Finally, to prepare the upgrade, we must put the new release package in the <c>releases</c> directory of the first - target system: - </p> + target system:</p> <pre> os> <input>cp mysystem2.tar.gz /usr/local/erl-target/releases</input></pre> - <p> - And assuming that the node has been started like this: - </p> + <p>Assuming that the node has been started as follows:</p> <pre> os> <input>/usr/local/erl-target/bin/start</input></pre> - <p> - it can be accessed like this: - </p> + <p>It can be accessed as follows:</p> <pre> os> <input>/usr/local/erl-target/bin/to_erl /tmp/erlang.pipe.1</input></pre> - <p> - Also note that logs can be found in + <p>Logs can be found in <c>/usr/local/erl-target/log</c>. This directory is specified as - an argument to <c>run_erl</c>in the start script listed above. - </p> + an argument to <c>run_erl</c>in the start script listed above.</p> <p> <em>Step 1.</em> Unpack the release: </p> @@ -402,18 +381,19 @@ heart: Tue Apr 1 12:15:11 2014: Executed "/usr/local/erl-target/bin/start /usr/ The above return value and output after the call to <c>release_handler:install_release/1</c> means that the <c>release_handler</c> has restarted the node by using - <c>heart</c>. This will always be done when the upgrade involves - a change of <c>erts</c>, <c>kernel</c>, <c>stdlib</c> or - <c>sasl</c>. See <seealso marker="upgrade">Upgrade when - Erlang/OTP has Changed</seealso> for more infomation about this. + <c>heart</c>. This is always done when the upgrade involves + a change of the applications ERTS, Kernel, + STDLIB, or SASL. For more information, see + <seealso marker="upgrade"> + Upgrade when Erlang/OTP has Changed</seealso>. </p> <p> - The node will be accessible via a new pipe: + The node is accessible through a new pipe: </p> <pre> os> <input>/usr/local/erl-target/bin/to_erl /tmp/erlang.pipe.2</input></pre> <p> - Let's see which releases we have in our system: + Check which releases there are in the system: </p> <pre> 1> <input>release_handler:which_releases().</input> @@ -426,7 +406,7 @@ os> <input>/usr/local/erl-target/bin/to_erl /tmp/erlang.pipe.2</input></pre> <p> Our new release, "SECOND", is now the current release, but we can also see that our "FIRST" release is still permanent. This - means that if the node would be restarted at this point, it + means that if the node would be restarted now, it would come up running the "FIRST" release again. </p> <p> @@ -434,11 +414,9 @@ os> <input>/usr/local/erl-target/bin/to_erl /tmp/erlang.pipe.2</input></pre> </p> <pre> 2> <input>release_handler:make_permanent("SECOND").</input></pre> - <p> - Now look at the releases again: + Check the releases again: </p> - <pre> 3> <input>release_handler:which_releases().</input> <output>[{"MYSYSTEM","SECOND", @@ -447,19 +425,16 @@ os> <input>/usr/local/erl-target/bin/to_erl /tmp/erlang.pipe.2</input></pre> {"MYSYSTEM","FIRST", ["kernel-2.16.4","stdlib-1.19.4","sasl-2.3.4","pea-1.0"], old}]</output></pre> - <p> - Here we see that the new release version is <c>permanent</c>, so - it would be safe to restart the node. - </p> - + We see that the new release version is <c>permanent</c>, so + it would be safe to restart the node.</p> </section> <section> + <marker id="listing of target system"/> <title>Listing of target_system.erl</title> <p>This module can also be found in the <c>examples</c> directory - of the <c>sasl</c> application.</p> + of the SASL application.</p> <codeinclude file="../../../lib/sasl/examples/src/target_system.erl" tag="%module" type="erl"></codeinclude> - </section> </chapter> diff --git a/system/doc/system_principles/error_logging.xml b/system/doc/system_principles/error_logging.xml index 80d5211323..3a82f4e0e0 100644 --- a/system/doc/system_principles/error_logging.xml +++ b/system/doc/system_principles/error_logging.xml @@ -28,41 +28,43 @@ <rev></rev> <file>error_logging.xml</file> </header> + <marker id="error logging"></marker> <section> <title>Error Information From the Runtime System</title> <p>Error information from the runtime system, that is, information - about a process terminating due to an uncaught error exception, + about a process terminating because of an uncaught error exception, is by default written to terminal (tty):</p> <code type="none"><![CDATA[ =ERROR REPORT==== 9-Dec-2003::13:25:02 === Error in process <0.27.0> with exit value: {{badmatch,[1,2,3]},[{m,f,1},{shell,eval_loop,2}]}]]></code> <p>The error information is handled by the <em>error logger</em>, a system process registered as <c>error_logger</c>. This process - receives all error messages from the Erlang runtime system and - also from the standard behaviours and different Erlang/OTP + receives all error messages from the Erlang runtime system as + well as from the standard behaviours and different Erlang/OTP applications.</p> - <p>The exit reasons (such as <c>badarg</c> above) used by + <p>The exit reasons (such as <c>badarg</c>) used by the runtime system are described in - <seealso marker="doc/reference_manual:errors#exit_reasons">Errors and Error Handling</seealso> - in the Erlang Reference Manual.</p> - <p>The process <c>error_logger</c> and its user interface (with - the same name) are described in - <seealso marker="kernel:error_logger">error_logger(3)</seealso>. - It is possible to configure the system so that error information - is written to file instead/as well as tty. Also, it is possible - for user defined applications to send and format error - information using <c>error_logger</c>.</p> + <seealso marker="doc/reference_manual:errors#exit_reasons"> + Errors and Error Handling</seealso>.</p> + <p>For information about the process <c>error_logger</c> and its user + interface (with the same name), see the + <seealso marker="kernel:error_logger">error_logger(3)</seealso> + manual page in Kernel. The system can be configured so that + error information + is written to file or to tty, or both. In addition, user-defined + applications can send and format error information using + <c>error_logger</c>.</p> </section> <section> <title>SASL Error Logging</title> - <p>The standard behaviors (<c>supervisor</c>, <c>gen_server</c>, - etc.) sends progress and error information to <c>error_logger</c>. - If the SASL application is started, this information is written - to tty as well. See + <p>The standard behaviours (<c>supervisor</c>, <c>gen_server</c>, + and so on) send progress and error information to <c>error_logger</c>. + If the SASL application is started, this information is + written to tty as well. For more information, see <seealso marker="sasl:error_logging">SASL Error Logging</seealso> - in the SASL User's Guide for further information.</p> + in the SASL User's Guide.</p> <pre> % <input>erl -boot start_sasl</input> Erlang (BEAM) emulator version 5.4.13 [hipe] [threads:0] [kernel-poll] diff --git a/system/doc/system_principles/system_principles.xml b/system/doc/system_principles/system_principles.xml index 79ed86cd9f..5718e8a3f6 100644 --- a/system/doc/system_principles/system_principles.xml +++ b/system/doc/system_principles/system_principles.xml @@ -28,35 +28,41 @@ <rev></rev> <file>system_principles.xml</file> </header> + <marker id="system principles"></marker> <section> <title>Starting the System</title> - <p>An Erlang runtime system is started with the command <c>erl</c>:</p> + <p>An Erlang runtime system is started with command <c>erl</c>:</p> <pre> % <input>erl</input> Erlang/OTP 17 [erts-6.0] [hipe] [smp:8:8] Eshell V6.0 (abort with ^G) 1> </pre> - <p><c>erl</c> understands a number of command line arguments, see - <c>erl(1)</c>. A number of them are also described in this chapter.</p> - <p>Application programs can access the values of the command line - arguments by calling one of the functions - <c>init:get_argument(Key)</c>, or <c>init:get_arguments()</c>. - See <c>init(3)</c>.</p> + <p><c>erl</c> understands a number of command-line arguments, see + the <seealso marker="erts:erl">erl(1)</seealso> manual page in + ERTS. Some of them are also described in this chapter.</p> + <p>Application programs can access the values of the command-line + arguments by calling the function <c>init:get_argument(Key)</c> + or <c>init:get_arguments()</c>. See the + <seealso marker="erts:init">init(3)</seealso> manual page in + ERTS.</p> </section> <section> <title>Restarting and Stopping the System</title> - <p>The runtime system can be halted by calling <c>halt/0,1</c>. - See <c>erlang(3)</c>.</p> - <p>The module <c>init</c> contains function for restarting, - rebooting and stopping the runtime system. See <c>init(3)</c>.</p> + <p>The runtime system is halted by calling <c>halt/0,1</c>. For + details, see the <seealso marker="erts:erlang">erlang(3)</seealso> + manual page in ERTS.</p> + <p>The module <c>init</c> contains functions for restarting, + rebooting, and stopping the runtime system:</p> <pre> init:restart() init:reboot() init:stop()</pre> - <p>Also, the runtime system will terminate if the Erlang shell is + <p>For details, see the <seealso marker="erts:init">init(3)</seealso> + manual page in ERTS.</p> + <p>The runtime system terminates if the Erlang shell is terminated.</p> </section> @@ -69,14 +75,15 @@ init:stop()</pre> <p>A boot script file has the extension <c>.script</c>. The runtime system uses a binary version of the script. This <em>binary boot script</em> file has the extension <c>.boot</c>.</p> - <p>Which boot script to use is specified by the command line flag - <c>-boot</c>. The extension <c>.boot</c> should be omitted. - Example, using the boot script <c>start_all.boot</c>:</p> + <p>Which boot script to use is specified by the command-line flag + <c>-boot</c>. The extension <c>.boot</c> is to be omitted. + For example, using the boot script <c>start_all.boot</c>:</p> <pre> % <input>erl -boot start_all</input></pre> <p>If no boot script is specified, it defaults to - <c>ROOT/bin/start</c>, see Default Boot Scripts below.</p> - <p>The command line flag <c>-init_debug</c> makes the <c>init</c> + <c>ROOT/bin/start</c>, see <seealso marker="#default_boot_scripts"> + Default Boot Scripts</seealso>.</p> + <p>The command-line flag <c>-init_debug</c> makes the <c>init</c> process write some debug information while interpreting the boot script:</p> <pre> @@ -87,59 +94,55 @@ init:stop()</pre> {start,heart} {start,error_logger} ...</pre> - <p>See <c>script(4)</c> for a detailed description of the syntax - and contents of the boot script.</p> + <p>For a detailed description of the syntax and contents of the + boot script, see the <c>script(4)</c> manual page in SASL.</p> <section> + <marker id="default_boot_scripts"></marker> <title>Default Boot Scripts</title> - <p>Erlang/OTP comes with two boot scripts:</p> - <taglist> - <tag><c>start_clean.boot</c></tag> - <item> - <p>Loads the code for and starts the applications Kernel and - STDLIB.</p> - </item> - <tag><c>start_sasl.boot</c></tag> - <item> - <p>Loads the code for and starts the applications Kernel, - STDLIB and SASL.</p> - </item> - <tag><c>no_dot_erlang.boot</c></tag> - <item> - <p>Loads the code for and starts the applications Kernel and - STDLIB, skips loading the <c>.erlang</c> file. - Useful for scripts and other tools that should be behave the - same regardless of user preferences. - </p> - </item> - </taglist> + <p>Erlang/OTP comes with these boot scripts:</p> + <list type="bulleted"> + <item><c>start_clean.boot</c> - Loads the code for and starts + the applications Kernel and STDLIB.</item> + <item><c>start_sasl.boot</c> - Loads the code for and starts + the applications Kernel, STDLIB, and + SASL).</item> + <item><c>no_dot_erlang.boot</c> - Loads the code for and + starts the applications Kernel and STDLIB. + Skips loading the file <c>.erlang</c>. Useful for scripts and + other tools that are to behave the same irrespective of user + preferences.</item> + </list> <p>Which of <c>start_clean</c> and <c>start_sasl</c> to use as default is decided by the user when installing Erlang/OTP using <c>Install</c>. The user is asked "Do you want to use a minimal system startup instead of the SASL startup". If the answer is yes, then <c>start_clean</c> is used, otherwise - <c>start_sasl</c> is used. A copy of the selected boot script - is made, named <c>start.boot</c> and placed in - the <c>ROOT/bin</c> directory.</p> + <c>start_sasl</c> is used. A copy of the selected boot script is + made, named <c>start.boot</c> and placed in directory + <c>ROOT/bin</c>.</p> </section> <section> <title>User-Defined Boot Scripts</title> <p>It is sometimes useful or necessary to create a user-defined boot script. This is true especially when running Erlang in - embedded mode, see <seealso marker="#code_loading">Code Loading Strategy</seealso>.</p> - <p>It is possible to write a boot script manually. - The recommended way to create a boot script, however, is to - generate the boot script from a release resource file - <c>Name.rel</c>, using the function + embedded mode, see <seealso marker="#code_loading"> + Code Loading Strategy</seealso>.</p> + <p>A boot script can be written manually. However, it is + recommended to create a boot script by generating it from a + release resource file <c>Name.rel</c>, using the function <c>systools:make_script/1,2</c>. This requires that the source code is structured as applications according to the OTP design principles. (The program does not have to be started in terms of - OTP applications but can be plain Erlang).</p> - <p>Read more about <c>.rel</c> files in OTP Design Principles and - <c>rel(4)</c>.</p> + OTP applications, but can be plain Erlang).</p> + <p>For more information about <c>.rel</c> files, see + <seealso marker="otp design principles"> + OTP Design Principles</seealso> and the + <seealso marker="sasl:rel">rel(4)</seealso> manual page in + SASL.</p> <p>The binary boot script file <c>Name.boot</c> is generated from - the boot script file <c>Name.script</c> using the function + the boot script file <c>Name.script</c>, using the function <c>systools:script2boot(File)</c>.</p> </section> </section> @@ -148,16 +151,17 @@ init:stop()</pre> <marker id="code_loading"></marker> <title>Code Loading Strategy</title> <p>The runtime system can be started in either <em>embedded</em> or - <em>interactive</em> mode. Which one is decided by the command - line flag <c>-mode</c>.</p> + <em>interactive</em> mode. Which one is decided by the + command-line flag <c>-mode</c>.</p> <pre> % <input>erl -mode embedded</input></pre> <p>Default mode is <c>interactive</c>.</p> + <p>The mode properties are as follows:</p> <list type="bulleted"> - <item>In embedded mode, all code is loaded during system start-up + <item>In embedded mode, all code is loaded during system startup according to the boot script. (Code can also be loaded later - by explicitly ordering the code server to do so).</item> - <item>In interactive mode, code is dynamically loaded when first + by explicitly ordering the code server to do so.)</item> + <item>In interactive mode, the code is dynamically loaded when first referenced. When a call to a function in a module is made, and the module is not loaded, the code server searches the code path and loads the module into the system.</item> @@ -165,21 +169,21 @@ init:stop()</pre> <p>Initially, the code path consists of the current working directory and all object code directories under <c>ROOT/lib</c>, where <c>ROOT</c> is the installation directory - of Erlang/OTP. Directories can be named <c>Name[-Vsn]</c> and - the code server, by default, chooses the directory with + of Erlang/OTP. Directories can be named <c>Name[-Vsn]</c>. The + code server, by default, chooses the directory with the highest version number among those which have the same <c>Name</c>. The <c>-Vsn</c> suffix is optional. If an <c>ebin</c> directory exists under the <c>Name[-Vsn]</c> - directory, it is this directory which is added to the code path.</p> - <p>The code path can be extended by using the command line flags - <c>-pa Directories</c> and <c>-pz Directories</c>. These will add - <c>Directories</c> to the head or end of the code path, - respectively. Example</p> + directory, this directory is added to the code path.</p> + <p>The code path can be extended by using the command-line flags + <c>-pa Directories</c> and <c>-pz Directories</c>. These add + <c>Directories</c> to the head or the end of the code path, + respectively. Example:</p> <pre> % <input>erl -pa /home/arne/mycode</input></pre> <p>The code server module <c>code</c> contains a number of - functions for modifying and checking the search path, see - <c>code(3)</c>.</p> + functions for modifying and checking the search path, see the + <c>code(3)</c> manual page in Kernel.</p> </section> <section> @@ -192,49 +196,65 @@ init:stop()</pre> <cell align="left" valign="middle"><em>Documented in</em></cell> </row> <row> - <cell align="left" valign="middle">module</cell> + <cell align="left" valign="middle">Module</cell> <cell align="left" valign="middle"><c>.erl</c></cell> - <cell align="left" valign="middle">Erlang Reference Manual</cell> + <cell align="left" valign="middle"> + <seealso marker="erlang ref manual"> + Erlang Reference Manual</seealso></cell> </row> <row> - <cell align="left" valign="middle">include file</cell> + <cell align="left" valign="middle">Include file</cell> <cell align="left" valign="middle"><c>.hrl</c></cell> - <cell align="left" valign="middle">Erlang Reference Manual</cell> + <cell align="left" valign="middle"> + <seealso marker="erlang ref manual"> + Erlang Reference Manual</seealso></cell> </row> <row> - <cell align="left" valign="middle">release resource file</cell> + <cell align="left" valign="middle">Release resource file</cell> <cell align="left" valign="middle"><c>.rel</c></cell> - <cell align="left" valign="middle"><c>rel(4)</c></cell> + <cell align="left" valign="middle"> + <seealso marker="sasl:rel">rel(4)</seealso> + manual page in SASL</cell> </row> <row> - <cell align="left" valign="middle">application resource file</cell> + <cell align="left" valign="middle">Application resource file</cell> <cell align="left" valign="middle"><c>.app</c></cell> - <cell align="left" valign="middle"><c>app(4)</c></cell> + <cell align="left" valign="middle"> + <seealso marker="kernel:app">app(4)</seealso> + manual page in Kernel</cell> </row> <row> - <cell align="left" valign="middle">boot script</cell> + <cell align="left" valign="middle">Boot script</cell> <cell align="left" valign="middle"><c>.script</c></cell> - <cell align="left" valign="middle"><c>script(4)</c></cell> + <cell align="left" valign="middle"> + <seealso marker="sasl:script">script(4)</seealso> + manual page in SASL</cell> </row> <row> - <cell align="left" valign="middle">binary boot script</cell> + <cell align="left" valign="middle">Binary boot script</cell> <cell align="left" valign="middle"><c>.boot</c></cell> <cell align="left" valign="middle">-</cell> </row> <row> - <cell align="left" valign="middle">configuration file</cell> + <cell align="left" valign="middle">Configuration file</cell> <cell align="left" valign="middle"><c>.config</c></cell> - <cell align="left" valign="middle"><c>config(4)</c></cell> + <cell align="left" valign="middle"> + <seealso marker="kernel:config">config(4)</seealso> + manual page in Kernel</cell> </row> <row> - <cell align="left" valign="middle">application upgrade file</cell> + <cell align="left" valign="middle">Application upgrade file</cell> <cell align="left" valign="middle"><c>.appup</c></cell> - <cell align="left" valign="middle"><c>appup(4)</c></cell> + <cell align="left" valign="middle"> + <seealso marker="sasl:appup">appup(4)</seealso> + manual page in SASL</cell> </row> <row> - <cell align="left" valign="middle">release upgrade file</cell> + <cell align="left" valign="middle">Release upgrade file</cell> <cell align="left" valign="middle"><c>relup</c></cell> - <cell align="left" valign="middle"><c>relup(4)</c></cell> + <cell align="left" valign="middle"> + <seealso marker="sasl:relup">relup(4)</seealso> + manual page in SASL</cell> </row> <tcaption>File Types</tcaption> </table> diff --git a/system/doc/system_principles/upgrade.xml b/system/doc/system_principles/upgrade.xml index 68e48da0b8..83e8128f94 100644 --- a/system/doc/system_principles/upgrade.xml +++ b/system/doc/system_principles/upgrade.xml @@ -31,88 +31,72 @@ <rev></rev> <file>upgrade.xml</file> </header> + <marker id="upgrade section"></marker> <section> <title>Introduction</title> - <p> - As of Erlang/OTP 17, most applications deliver a valid - application upgrade (<c>appup</c>) file. In earlier releases, a + <marker id="upgrade"></marker> + <p>As of Erlang/OTP 17, most applications deliver a valid + application upgrade file (<c>appup</c>). In earlier releases, a majority of the applications in Erlang/OTP did not support - upgrade at all. Many of the applications use the + upgrade. Many of the applications use the <c>restart_application</c> instruction. These are applications for which it is not crucial to support real soft upgrade, for - instance tools and library applications. The + example, tools and library applications. The <c>restart_application</c> instruction ensures that all modules in the application are reloaded and - thereby running the new code. - </p> + thereby running the new code.</p> </section> <section> - <title>Upgrade of core applications</title> - <p> - The core applications ERTS, Kernel, STDLIB + <title>Upgrade of Core Applications</title> + <p>The core applications ERTS, Kernel, STDLIB, and SASL never allow real soft upgrade, but require the Erlang emulator to be restarted. This is indicated to the <c>release_handler</c> by the upgrade instruction - <c>restart_new_emulator</c>. This instruction will always be the - very first instruction executed, and it will restart the + <c>restart_new_emulator</c>. This instruction is always the + very first instruction executed, and it restarts the emulator with the new versions of the above mentioned core - applications and the old versions of all other - applications. When the node is back up all other upgrade instructions are + applications and the old versions of all other applications. + When the node is back up, all other upgrade instructions are executed, making sure each application is finally running its - new version. - </p> - - <p> - It might seem strange to do a two-step upgrade instead of + new version.</p> + <p>It might seem strange to do a two-step upgrade instead of just restarting the emulator with the new version of all applications. The reason for this design decision is to allow - <c>code_change</c> functions to have side effects, for example changing - data on disk. It also makes sure that the upgrade mechanism for - non-core applications does not differ depending on whether or not - core applications are changed at the same time. - </p> - - <p> - If, however, the more brutal variant is preferred, it is - possible to handwrite the release upgrade file using only the + <c>code_change</c> functions to have side effects, for example, + changing data on disk. It also guarantees that the upgrade + mechanism for non-core applications does not differ depending + on whether or not core applications are changed at the same time.</p> + <p>If, however, the more brutal variant is preferred, the + the release upgrade file can be handwritten using only the single upgrade instruction <c>restart_emulator</c>. This - instruction, in contrast to <c>restart_new_emulator</c>, will - cause the emulator to restart with the new versions of - <em>all</em> applications. - </p> - - <p> - <em>Note</em> that if other instructions are included before + instruction, in contrast to <c>restart_new_emulator</c>, + causes the emulator to restart with the new versions of + <em>all</em> applications.</p> + <p><em>Note:</em> If other instructions are included before <c>restart_emulator</c> in the handwritten <c>relup</c> file, - they will be executed in the old emulator. This is a big risk + they are executed in the old emulator. This is a big risk since there is no guarantee that new beam code can be loaded into the old emulator. Adding instructions after <c>restart_emulator</c> has no effect as the - <c>release_handler</c> will not do any attempt at executing - them. - </p> - - <p> - See <seealso marker="sasl:relup">relup(4)</seealso> for - information about the release upgrade file, and <seealso - marker="sasl:appup">appup(4)</seealso> for further information - about upgrade instructions. - </p> + <c>release_handler</c> will not execute them.</p> + <p>For information about the release upgrade file, see the + <seealso marker="sasl:relup">relup(4)</seealso> manual page + in SASL. + For more information about upgrade instructions, see the + <seealso marker="sasl:appup">appup(4)</seealso> manual page + in SASL.</p> </section> <section> - <title>Applications that still do not allow code upgrade</title> - <p> - A few applications, for instance HiPE do not support - upgrade at all. This is indicated by an application upgrade file - containing only <c>{Vsn,[],[]}</c>. Any attempt at creating a release - upgrade file with such input will fail. - The only way to force an upgrade involving applications like this is to - handwrite the <c>relup</c> file, preferably as described above - with only the <c>restart_emulator</c> instruction. - </p> - + <title>Applications that Still do Not Allow Code Upgrade</title> + <p>A few applications, such as HiPE, do not support upgrade. + This is indicated by an application upgrade file containing only + <c>{Vsn,[],[]}</c>. Any attempt at creating a release upgrade file + with such input fails. The only way to force an upgrade involving + applications like this is to + handwrite the file <c>relup</c>, preferably as described above + with only the <c>restart_emulator</c> instruction.</p> </section> </chapter> diff --git a/system/doc/system_principles/versions.xml b/system/doc/system_principles/versions.xml index ff042f4a3b..25eb90f626 100644 --- a/system/doc/system_principles/versions.xml +++ b/system/doc/system_principles/versions.xml @@ -31,93 +31,99 @@ <rev></rev> <file>versions.xml</file> </header> - <section><title>OTP Version</title> + <marker id="versions section"></marker> + + <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> - + introduced in OTP 17. The version scheme used is described in detail in + <seealso marker="#version_scheme">Version Scheme</seealso>.</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 + 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<N></c> - suffix. The suffix <c>-rc0</c> will be used during development up to + suffix. The suffix <c>-rc0</c> is 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><OTP source root>/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><OTP installation root>/releases/<OTP release number>/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 <c>otp_patch_apply</c> tool available to - licensed customers. 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>otp_patch_apply</c>, the <c>OTP_VERSION</c> file - may identify an incorrect 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> + <title>Retrieving Current OTP Version</title> + <p>In an OTP source code tree, the OTP version can be read from + the text file <c><OTP source root>/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><OTP installation root>/releases/<OTP release number>/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 <c>otp_patch_apply</c> tool available to + licensed customers. 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. Notice that if a development system is updated by + other means than <c>otp_patch_apply</c>, the file <c>OTP_VERSION</c> + can identify an incorrect OTP version.</p> + <p>No <c>OTP_VERSION</c> file is 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 can, + however, place such a file there if you know the OTP version.</p> </section> - <section><title>OTP Versions Table</title> - <p>The text file <c><OTP source root>/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> -<OtpVersion> : <ChangedAppVersions> # <UnchangedAppVersions> : -</pre> - <p><c><OtpVersion></c> is on the format <c>OTP-<VSN></c>, i.e., - the same as the git tag used to identify the source. - <c><ChangedAppVersions></c> and <c><UnchangedAppVersions></c> - are space separated lists of application versions on the - format <c><application>-<vsn></c>. - <c><ChangedAppVersions></c> corresponds to changed applications - with new version numbers in this OTP version, and - <c><UnchangedAppVersions></c> corresponds to unchanged application - versions in this OTP version. Both of them might be empty, although - not at the same time. If <ChangedAppVersions> 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> + <title>OTP Versions Table</title> + <p>The text file <c><OTP source root>/otp_versions.table</c>, + which is part of the source code, contains information about all + OTP versions from OTP 17.0 up to the current OTP version. Each line + contains information about application versions that are part of a + specific OTP version, and has the following format:</p> + <pre> +<OtpVersion> : <ChangedAppVersions> # <UnchangedAppVersions> :</pre> + <p><c><OtpVersion></c> has the format <c>OTP-<VSN></c>, + that is, the same as the git tag used to identify the source.</p> + <p><c><ChangedAppVersions></c> and + <c><UnchangedAppVersions></c> are space-separated lists of + application versions and has the format + <c><application>-<vsn></c>.</p> + <list type="bulleted"> + <item><c><ChangedAppVersions></c> corresponds to changed + applications with new version numbers in this OTP version.</item> + <item><c><UnchangedAppVersions></c> corresponds to unchanged + application versions in this OTP version.</item> + </list> + <p>Both of them can be empty, but not at the same time. + If <c><ChangedAppVersions></c> is empty, no changes have + 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>By using ordinary UNIX tools like <c>sed</c> and <c>grep</c> one + can easily find answers to various questions like:</p> + <list type="bulleted"> + <item><p>Which OTP versions are <c>kernel-3.0</c> part of?</p> + <p><c>$ grep ' kernel-3\.0 ' otp_versions.table</c> </p></item> + <item><p>In which OTP version was <c>kernel-3.0</c> introduced?</p> + <p><c>$ sed 's/#.*//;/ kernel-3\.0 /!d' otp_versions.table</c> + </p></item> + </list> + <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 + <section> + <title>Application Version</title> + <p>As of OTP 17.0 application versions 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<N></c> suffix as the OTP version. @@ -125,88 +131,88 @@ 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> + </section> + <section> + <title>Version Scheme</title> <marker id="version_scheme"/> - <section><title>Version Scheme</title> - <note>Note that the version scheme was changed as of OTP 17.0. This implies + <note><p>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><Major>.<Minor>.<Patch></c> where <c><Major></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><Minor></c> equals <c>0</c>, - they are omitted. The three normal parts - <c><Major>.<Minor>.<Patch></c> will be changed as + application versions used in OTP 17.0</seealso> is included at the + end of this section</p></note> + <p>In the normal case, a version is constructed as + <c><Major>.<Minor>.<Patch></c>, + where <c><Major></c> is the most significant part.</p> + <p>However, more dot-separated parts than this can exist. + The dot-separated parts consist of non-negative integers. If + all parts less significant than <c><Minor></c> equals + <c>0</c>, they are omitted. The three normal parts + <c><Major>.<Minor>.<Patch></c> are changed as follows:</p> - <taglist> - <tag><c><Major></c></tag><item>Increased when major changes, - including incompatibilities, have been made.</item> - <tag><c><Minor></c></tag><item>Increased when new functionality - has been added.</item> - <tag><c><Patch></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 + <list type="bulleted"> + <item><c><Major></c> - Increases when major changes, + including incompatibilities, are made.</item> + <item><c><Minor></c> - Increases when new + functionality is added.</item> + <item><c><Patch></c> - Increases when pure bug fixes + are made.</item> + </list> + <p>When a part in the version number increases, 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 + versions. That is, it implies nothing 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.<X></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.<X></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> + <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 to less significant parts. The order is + defined by the first parts of the same significance that + differ. An OTP version with a larger version includes all + changes that are part of a smaller OTP version. The same + goes for application versions.</p> + <p>In general, versions can have more than three parts. + The versions are then only partially ordered. 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, and therefore one can only conclude + 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 previous paragraph.</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.<X></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.<X></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> + <section> + <title>OTP 17.0 Application Versions</title> <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, + <p>The following list details the application versions that + were part of OTP 17.0. If + the normal part of an application version number compares + as smaller than the corresponding application version in the 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 + in OTP 17.0 and is to be considered as not having an order against versions used as of OTP 17.0.</p> <list> <item><c>asn1-3.0</c></item> @@ -262,6 +268,6 @@ <item><c>wx-1.2</c></item> <item><c>xmerl-1.3.7</c></item> </list> - </section> + </section> </chapter> |