diff options
Diffstat (limited to 'system/doc/system_principles')
| -rw-r--r-- | system/doc/system_principles/Makefile | 21 | ||||
| -rw-r--r-- | system/doc/system_principles/book.xml | 21 | ||||
| -rw-r--r-- | system/doc/system_principles/create_target.xmlsrc | 386 | ||||
| -rw-r--r-- | system/doc/system_principles/error_logging.xml | 59 | ||||
| -rw-r--r-- | system/doc/system_principles/part.xml | 21 | ||||
| -rw-r--r-- | system/doc/system_principles/system_principles.xml | 209 | ||||
| -rw-r--r-- | system/doc/system_principles/upgrade.xml | 117 | ||||
| -rw-r--r-- | system/doc/system_principles/versions.xml | 311 | ||||
| -rw-r--r-- | system/doc/system_principles/xmlfiles.mk | 21 |
9 files changed, 581 insertions, 585 deletions
diff --git a/system/doc/system_principles/Makefile b/system/doc/system_principles/Makefile index b1c0fc3ddd..2bb84474df 100644 --- a/system/doc/system_principles/Makefile +++ b/system/doc/system_principles/Makefile @@ -3,16 +3,17 @@ # # Copyright Ericsson AB 1996-2012. All Rights Reserved. # -# 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. +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. # # %CopyrightEnd% # diff --git a/system/doc/system_principles/book.xml b/system/doc/system_principles/book.xml index 3692752bbe..11eacba578 100644 --- a/system/doc/system_principles/book.xml +++ b/system/doc/system_principles/book.xml @@ -8,16 +8,17 @@ <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. + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. </legalnotice> diff --git a/system/doc/system_principles/create_target.xmlsrc b/system/doc/system_principles/create_target.xmlsrc index a8ee2d1245..ccc26081c3 100644 --- a/system/doc/system_principles/create_target.xmlsrc +++ b/system/doc/system_principles/create_target.xmlsrc @@ -8,16 +8,17 @@ <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/. + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 - 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. + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. </legalnotice> @@ -31,55 +32,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 +91,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 +124,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 +151,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 +184,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 +289,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 +343,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 +382,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 +407,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 +415,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 +426,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..024137a430 100644 --- a/system/doc/system_principles/error_logging.xml +++ b/system/doc/system_principles/error_logging.xml @@ -8,16 +8,17 @@ <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. + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. </legalnotice> @@ -28,41 +29,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/part.xml b/system/doc/system_principles/part.xml index d05c89fde8..1557b5ff62 100644 --- a/system/doc/system_principles/part.xml +++ b/system/doc/system_principles/part.xml @@ -8,16 +8,17 @@ <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. + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. </legalnotice> diff --git a/system/doc/system_principles/system_principles.xml b/system/doc/system_principles/system_principles.xml index 79ed86cd9f..3605df3ade 100644 --- a/system/doc/system_principles/system_principles.xml +++ b/system/doc/system_principles/system_principles.xml @@ -4,20 +4,21 @@ <chapter> <header> <copyright> - <year>1996</year><year>2014</year> + <year>1996</year><year>2015</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. + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. </legalnotice> @@ -28,35 +29,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 +76,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 +95,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="doc/design_principles:release_handling"> + 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 +152,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 +170,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 +197,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="doc/reference_manual:modules"> + 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="doc/reference_manual:modules"> + 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..173e46185c 100644 --- a/system/doc/system_principles/upgrade.xml +++ b/system/doc/system_principles/upgrade.xml @@ -8,16 +8,17 @@ <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/. + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 - 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. + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. </legalnotice> @@ -31,88 +32,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 ed6fd1f7fe..ee104a8302 100644 --- a/system/doc/system_principles/versions.xml +++ b/system/doc/system_principles/versions.xml @@ -8,16 +8,17 @@ <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. + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. </legalnotice> @@ -31,94 +32,100 @@ <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 - <seealso marker="../installation_guide/OTP-PATCH-APPLY"><c>otp_patch_apply</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>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 + <seealso marker="../installation_guide/OTP-PATCH-APPLY"><c>otp_patch_apply</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. 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. @@ -126,88 +133,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> @@ -263,6 +270,6 @@ <item><c>wx-1.2</c></item> <item><c>xmerl-1.3.7</c></item> </list> - </section> + </section> </chapter> diff --git a/system/doc/system_principles/xmlfiles.mk b/system/doc/system_principles/xmlfiles.mk index c60ffbad28..fcc1fc886f 100644 --- a/system/doc/system_principles/xmlfiles.mk +++ b/system/doc/system_principles/xmlfiles.mk @@ -3,16 +3,17 @@ # # Copyright Ericsson AB 2009-2014. All Rights Reserved. # -# 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. +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. # # %CopyrightEnd% # |