From 0c20078ff0fbad9066c8dd4ebcd6faa0b4f31b42 Mon Sep 17 00:00:00 2001 From: Hans Bolinder Date: Thu, 12 Mar 2015 15:35:13 +0100 Subject: Update System Principles Language cleaned up by the technical writers xsipewe and tmanevik from Combitech. Proofreading and corrections by Hans Bolinder. --- system/doc/system_principles/create_target.xmlsrc | 367 ++++++++++----------- system/doc/system_principles/error_logging.xml | 38 ++- system/doc/system_principles/system_principles.xml | 186 ++++++----- system/doc/system_principles/upgrade.xml | 98 +++--- system/doc/system_principles/versions.xml | 288 ++++++++-------- 5 files changed, 482 insertions(+), 495 deletions(-) (limited to 'system/doc/system_principles') 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 @@ A create_target.xml + -
- Introduction -

When creating a system using Erlang/OTP, the most simple way is - to install Erlang/OTP somewhere, install the application specific +

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.

-

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.

+

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.

-

This chapter is about creating such a system, which we call a +

This chapter is about creating such a system, which is called a target system.

-

In the following sections we consider creating target systems with - different requirements of functionality:

+

The following sections deal with target systems + with different requirements of functionality:

- a basic target system that can be started by - calling the ordinary erl script, - a simple target system where also code - replacement in run-time can be performed, and - an embedded target system where there is also + A basic target system that can be started by + calling the ordinary erl script. + A simple target system where also code + replacement in runtime can be performed. + An embedded target system 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. + at boot time. -

We only consider the case when Erlang/OTP is running on a UNIX - system.

-

In the sasl application there is an example Erlang - module target_system.erl 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.

-
+

Here is only considered the case when Erlang/OTP is running on a + UNIX system.

+

The sasl application includes the example Erlang + module target_system.erl, 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 + Listing of target_system.erl

Creating a Target System

It is assumed that you have a working Erlang/OTP system structured - according to the OTP Design Principles.

-

Step 1. First create a .rel file (see rel(4)) that specifies the erts - version and lists all applications that should be included in the - new basic target system. An example is the following - mysystem.rel file:

+ according to the OTP design principles.

+

Step 1. Create a .rel file (see the + rel(4) 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 mysystem.rel file:

%% mysystem.rel {release, @@ -91,23 +90,23 @@ {pea, "1.0"}]}.

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 - pea).

-

Step 2. From the directory where the mysystem.rel - file reside, start the Erlang/OTP system:

+ written (here exemplified by the application Pea (pea)).

+

Step 2. Start Erlang/OTP from the directory where + the mysystem.rel file resides:

 os> erl -pa /home/user/target_system/myapps/pea-1.0/ebin
-

where also the path to the pea-1.0 ebin directory is - provided.

-

Step 3. Now create the target system:

+

Here also the path to the pea-1.0 ebin directory is + provided.

+

Step 3. Create the target system:

 1> target_system:create("mysystem").
-

The target_system:create/1 function does the following:

+

The function target_system:create/1 performs the + following:

- Reads the mysystem.rel file, and creates a new file - plain.rel which is identical to former, except that it - only lists the kernel and stdlib applications. - From the mysystem.rel and plain.rel files + Reads the file mysystem.rel and creates a new file + plain.rel that is identical to the former, except that it + only lists the Kernel and STDLIB applications. + From the files mysystem.rel and plain.rel creates the files mysystem.script, mysystem.boot, plain.script, and plain.boot 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/ +lib/pea-1.0/

The file releases/FIRST/start.boot is a copy of our mysystem.boot

The release resource file mysystem.rel is duplicated in the tar file. Originally, this file was only stored in - the releases directory in order to make it possible + the releases directory to make it possible for the release_handler to extract this file separately. After unpacking the tar file, release_handler would automatically copy the file to releases/FIRST. However, sometimes the tar file is unpacked without involving - the release_handler (e.g. when unpacking the first - target system) and therefore the file is now instead + the release_handler (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.

+ needed.

 - Creates the temporary directory tmp and extracts the tar file - mysystem.tar.gz into that directory. - Deletes the erl and start files from - tmp/erts-5.10.4/bin. These files will be created again from + Creates the temporary directory tmp and extracts + the tar file mysystem.tar.gz into that directory. + Deletes the files erl and start from + tmp/erts-5.10.4/bin. These files are created again from source when installing the release. Creates the directory tmp/bin. Copies the previously created file plain.boot to @@ -151,31 +150,31 @@ lib/pea-1.0/ Copies the files epmd, run_erl, and to_erl from the directory tmp/erts-5.10.4/bin to the directory tmp/bin. - Creates the directory tmp/log, which will be used + Creates the directory tmp/log, which is used if the system is started as embedded with the bin/start script. Creates the file tmp/releases/start_erl.data with the contents "5.10.4 FIRST". This file is to be passed as data - file to the start_erl script. - + file to the start_erl script. Recreates the file mysystem.tar.gz from the directories - in the directory tmp, and removes tmp. + in the directory tmp and removes tmp.
Installing a Target System

Step 4. Install the created target system in a - suitable directory.

+ suitable directory.

 2> target_system:install("mysystem", "/usr/local/erl-target").
-

The function target_system:install/2 does the following: +

The function target_system:install/2 performs the following:

Extracts the tar file mysystem.tar.gz into the target directory /usr/local/erl-target. - In the target directory reads the file releases/start_erl.data - in order to find the Erlang runtime system version ("5.10.4"). + In the target directory reads the file + releases/start_erl.data to find the Erlang runtime system + version ("5.10.4"). Substitutes %FINAL_ROOTDIR% and %EMU% for /usr/local/erl-target and beam, respectively, in the files erl.src, start.src, and @@ -184,97 +183,102 @@ lib/pea-1.0/ start, and run_erl in the target bin directory. Finally the target releases/RELEASES file is created - from data in the releases/mysystem.rel file. + from data in the file releases/mysystem.rel.
Starting a Target System -

Now we have a target system that can be started in various ways.

-

We start it as a basic target system by invoking

+

Now we have a target system that can be started in various ways. + We start it as a basic target system by invoking:

 os> /usr/local/erl-target/bin/erl
-

where only the kernel and stdlib 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: - bin/erl file (obtained from erts-5.10.4/bin/erl.src) - and the bin/start.boot file (a copy of plain.boot).

+

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:

+ + bin/erl (obtained from + erts-5.10.4/bin/erl.src) + bin/start.boot (a copy of + plain.boot) +

We can also start a distributed system (requires bin/epmd).

To start all applications specified in the original - mysystem.rel file, use the -boot flag as follows:

+ mysystem.rel file, use flag -boot as follows:

 os> /usr/local/erl-target/bin/erl -boot /usr/local/erl-target/releases/FIRST/start
-

We start a simple target system as above. The only difference - is that also the file releases/RELEASES is present for - code replacement in run-time to work.

-

To start an embedded target system the shell script - bin/start is used. That shell script calls +

We start a simple target system as above. The only + difference is that also the file releases/RELEASES is + present for code replacement in runtime to work.

+

To start an embedded target system, the shell script + bin/start is used. The script calls bin/run_erl, which in turn calls bin/start_erl (roughly, start_erl is an embedded variant of - erl).

+ erl).

The shell script start, 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.

run_erl 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 (to_erl).

-

start_erl requires the root directory - ("/usr/local/erl-target"), the releases directory - ("/usr/local/erl-target/releases"), and the location of - the start_erl.data file. It reads the run-time system - version ("5.10.4") and release version ("FIRST") from - the start_erl.data file, starts the run-time system of the - version found, and provides -boot flag specifying the boot - file of the release version found - ("releases/FIRST/start.boot").

-

start_erl also assumes that there is sys.config in - release version directory ("releases/FIRST/sys.config"). That - is the topic of the next section (see below).

-

The start_erl shell script should normally not be +

start_erl requires:

+ + The root directory ("/usr/local/erl-target") + The releases directory + ("/usr/local/erl-target/releases" + The location of the file start_erl.data + +

It performs the following:

+ + Reads the runtime system version ("5.10.4") and + release version ("FIRST") from the file + start_erl.data. + Starts the runtime system of the version found. + Provides the flag -boot specifying the boot + file of the release version found + ("releases/FIRST/start.boot"). + +

start_erl also assumes that there is sys.config + in the release version directory ("releases/FIRST/sys.config"). + That is the topic of the next section.

+

The start_erl shell script is normally not to be altered by the user.

System Configuration Parameters -

As was pointed out above start_erl requires a - sys.config in the release version directory - ("releases/FIRST/sys.config"). If there is no such a - file, the system start will fail. Hence such a file has to - be added as well.

-

-

If you have system configuration data that are neither file - location dependent nor site dependent, it may be convenient to - create the sys.config early, so that it becomes a part of +

As was mentioned in the previous section, start_erl + requires a sys.config in the release version directory + ("releases/FIRST/sys.config"). If there is no such + file, the system start fails. Such a file must therefore + also be added.

+

If you have system configuration data that is neither + file-location-dependent nor site-dependent, it can be convenient + to create sys.config early, so it becomes part of the target system tar file created by - target_system:create/1. In fact, if you create, in the - current directory, not only the mysystem.rel file, but - also a sys.config file, that latter file will be tacitly + target_system:create/1. In fact, if you in the + current directory create not only the file mysystem.rel, + but also file sys.config, the latter file is tacitly put in the appropriate directory.

- Differences from the Install Script -

The above install/2 procedure differs somewhat from that + Differences From the Install Script +

The previous install/2 procedure differs somewhat from that of the ordinary Install shell script. In fact, create/1 makes the release package as complete as possible, and leave to the - install/2 procedure to finish by only considering location - dependent files.

+ install/2 procedure to finish by only considering + location-dependent files.

Creating the Next Version - -

- In this example the pea application has been changed, and - so are erts, kernel, stdlib and - sasl. -

- -

- Step 1. Create the .rel file: -

+

In this example the Pea application has been changed, and + so are the applications ERTS, Kernel, STDLIB + and SASL.

+

Step 1. Create the file .rel:

%% mysystem2.rel {release, @@ -284,65 +288,49 @@ os> /usr/local/erl-target/bin/erl -boot /usr/local/erl-target/releases/FI {stdlib, "2.0"}, {sasl, "2.4"}, {pea, "2.0"}]}. -

- Step 2. Create the application upgrade file (see - appup(4)) for pea, - for example: -

+

Step 2. Create the application upgrade file (see the + appup(4) manual page in + SASL) for Pea, for example:

%% pea.appup {"2.0", [{"1.0",[{load_module,pea_lib}]}], [{"1.0",[{load_module,pea_lib}]}]}. -

- Step 3. From the directory where the - mysystem2.rel file reside, start the Erlang/OTP system: -

+

Step 3. From the directory where the file + mysystem2.rel resides, start the Erlang/OTP system, + giving the path to the new version of Pea:

 os> erl -pa /home/user/target_system/myapps/pea-2.0/ebin
-

giving the path to the new version of pea.

- -

- Step 4. Create the release upgrade file (see relup(4)): -

+

Step 4. Create the release upgrade file (see the + relup(4) manual page in + SASL):

-1> systools:make_relup("mysystem2",["mysystem"],["mysystem"],[{path,["/home/user/target_system/myapps/pea-1.0/ebin","/my/old/erlang/lib/*/ebin"]}]).
-

- where "mysystem" is the base release and - "mysystem2" is the release to upgrade to. -

-

- Note that the path option is used for pointing out the +1> systools:make_relup("mysystem2",["mysystem"],["mysystem"], + [{path,["/home/user/target_system/myapps/pea-1.0/ebin", + "/my/old/erlang/lib/*/ebin"]}]). +

Here "mysystem" is the base release and + "mysystem2" is the release to upgrade to.

+

The path 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.) -

-

- Step 5. Create the new release: -

+ Erlang/OTP.)

+

Step 5. Create the new release:

 2> target_system:create("mysystem2").
-

- Given that the relup file generated in step 4 above is - now located in the current directory, it will automatically be - included in the release package. -

+

Given that the file relup generated in Step 4 is + now located in the current directory, it is automatically + included in the release package.

Upgrading the Target System -

- This part is done on the target node, and for this example we +

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 - -heart option, allowing automatic restart of the - node. See Starting a Target - System above for more information. -

-

- We add -heart to bin/start: -

+ -heart option, allowing automatic restart of the node. + For more information, see + Starting a Target System.

+

We add -heart to bin/start:

#!/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 -

- And we use the simplest possible sys.config, which we - store in releases/FIRST: -

+$ROOTDIR/bin/run_erl -daemon /tmp/ $ROOTDIR/log "exec $ROOTDIR/bin/start_erl $ROOTDIR\ +$RELDIR $START_ERL_DATA -heart +

We use the simplest possible sys.config, which we + store in releases/FIRST:

%% sys.config []. -

- Finally, in order to prepare the upgrade, we need to put the new +

Finally, to prepare the upgrade, we must put the new release package in the releases directory of the first - target system: -

+ target system:

 os> cp mysystem2.tar.gz /usr/local/erl-target/releases
-

- And assuming that the node has been started like this: -

+

Assuming that the node has been started as follows:

 os> /usr/local/erl-target/bin/start
-

- it can be accessed like this: -

+

It can be accessed as follows:

 os> /usr/local/erl-target/bin/to_erl /tmp/erlang.pipe.1
-

- Also note that logs can be found in +

Logs can be found in /usr/local/erl-target/log. This directory is specified as - an argument to run_erlin the start script listed above. -

+ an argument to run_erlin the start script listed above.

Step 1. Unpack the release:

@@ -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 release_handler:install_release/1 means that the release_handler has restarted the node by using - heart. This will always be done when the upgrade involves - a change of erts, kernel, stdlib or - sasl. See Upgrade when - Erlang/OTP has Changed for more infomation about this. + heart. This is always done when the upgrade involves + a change of the applications ERTS, Kernel, + STDLIB, or SASL. For more information, see + + Upgrade when Erlang/OTP has Changed.

- The node will be accessible via a new pipe: + The node is accessible through a new pipe: 

 os> /usr/local/erl-target/bin/to_erl /tmp/erlang.pipe.2

- Let's see which releases we have in our system: + Check which releases there are in the system: 

 1> release_handler:which_releases().
@@ -426,7 +406,7 @@ os> /usr/local/erl-target/bin/to_erl /tmp/erlang.pipe.2

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.

@@ -434,11 +414,9 @@ os> /usr/local/erl-target/bin/to_erl /tmp/erlang.pipe.2 

 2> release_handler:make_permanent("SECOND").
-

- Now look at the releases again: + Check the releases again:

- 
 3> release_handler:which_releases().
 [{"MYSYSTEM","SECOND",
@@ -447,19 +425,16 @@ os> /usr/local/erl-target/bin/to_erl /tmp/erlang.pipe.2
{"MYSYSTEM","FIRST", ["kernel-2.16.4","stdlib-1.19.4","sasl-2.3.4","pea-1.0"], old}] -

- Here we see that the new release version is permanent, so - it would be safe to restart the node. -

- + We see that the new release version is permanent, so + it would be safe to restart the node.

+ Listing of target_system.erl

This module can also be found in the examples directory - of the sasl application.

+ of the SASL application.

-
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 @@ error_logging.xml +
Error Information From the Runtime System

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):

with exit value: {{badmatch,[1,2,3]},[{m,f,1},{shell,eval_loop,2}]}]]>

The error information is handled by the error logger, a system process registered as error_logger. 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.

-

The exit reasons (such as badarg above) used by +

The exit reasons (such as badarg) used by the runtime system are described in - Errors and Error Handling - in the Erlang Reference Manual.

-

The process error_logger and its user interface (with - the same name) are described in - error_logger(3). - 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 error_logger.

+ + Errors and Error Handling.

+

For information about the process error_logger and its user + interface (with the same name), see the + error_logger(3) + 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 + error_logger.

SASL Error Logging -

The standard behaviors (supervisor, gen_server, - etc.) sends progress and error information to error_logger. - If the SASL application is started, this information is written - to tty as well. See +

The standard behaviours (supervisor, gen_server, + and so on) send progress and error information to error_logger. + If the SASL application is started, this information is + written to tty as well. For more information, see SASL Error Logging - in the SASL User's Guide for further information.

+ in the SASL User's Guide.

 % erl -boot start_sasl
 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 @@
     
     system_principles.xml
   
+  
 
   

     Starting the System
-    
An Erlang runtime system is started with the command erl:

+    
An Erlang runtime system is started with command erl:

     
 % erl
 Erlang/OTP 17 [erts-6.0] [hipe] [smp:8:8]
 
 Eshell V6.0  (abort with ^G)
 1> 

-    
erl understands a number of command line arguments, see
-      erl(1). A number of them are also described in this chapter.

-    
Application programs can access the values of the command line
-      arguments by calling one of the functions
-      init:get_argument(Key), or init:get_arguments().
-      See init(3).

+    
erl understands a number of command-line arguments, see
+      the erl(1)  manual page in
+      ERTS. Some of them are also described in this chapter.

+    
Application programs can access the values of the command-line
+      arguments by calling the function init:get_argument(Key)
+      or init:get_arguments(). See the
+      init(3) manual page in
+      ERTS.

   

 
   

     Restarting and Stopping the System
-    
The runtime system can be halted by calling halt/0,1.
-      See erlang(3).

-    
The module init contains function for restarting,
-      rebooting and stopping the runtime system. See init(3).

+    
The runtime system is halted by calling halt/0,1. For
+      details, see the erlang(3)
+      manual page in ERTS.

+    
The module init contains functions for restarting,
+      rebooting, and stopping the runtime system:

     
 init:restart()
 init:reboot()
 init:stop()

-    
Also, the runtime system will terminate if the Erlang shell is
+    
For details, see the init(3)
+      manual page in ERTS.

+    
The runtime system terminates if the Erlang shell is
       terminated.

   

 
@@ -69,14 +75,15 @@ init:stop()

A boot script file has the extension .script. The runtime system uses a binary version of the script. This binary boot script file has the extension .boot.

-

Which boot script to use is specified by the command line flag - -boot. The extension .boot should be omitted. - Example, using the boot script start_all.boot:

+

Which boot script to use is specified by the command-line flag + -boot. The extension .boot is to be omitted. + For example, using the boot script start_all.boot:

 % erl -boot start_all

If no boot script is specified, it defaults to - ROOT/bin/start, see Default Boot Scripts below.

-

The command line flag -init_debug makes the init + ROOT/bin/start, see + Default Boot Scripts.

+

The command-line flag -init_debug makes the init process write some debug information while interpreting the boot script:

@@ -87,59 +94,55 @@ init:stop()
{start,heart} {start,error_logger} ... -

See script(4) for a detailed description of the syntax - and contents of the boot script.

+

For a detailed description of the syntax and contents of the + boot script, see the script(4) manual page in SASL.

+ Default Boot Scripts -

Erlang/OTP comes with two boot scripts:

- - start_clean.boot - -

Loads the code for and starts the applications Kernel and - STDLIB.

- - start_sasl.boot - -

Loads the code for and starts the applications Kernel, - STDLIB and SASL.

- - no_dot_erlang.boot - -

Loads the code for and starts the applications Kernel and - STDLIB, skips loading the .erlang file. - Useful for scripts and other tools that should be behave the - same regardless of user preferences. -

- - +

Erlang/OTP comes with these boot scripts:

+ + start_clean.boot - Loads the code for and starts + the applications Kernel and STDLIB. + start_sasl.boot - Loads the code for and starts + the applications Kernel, STDLIB, and + SASL). + no_dot_erlang.boot - Loads the code for and + starts the applications Kernel and STDLIB. + Skips loading the file .erlang. Useful for scripts and + other tools that are to behave the same irrespective of user + preferences. +

Which of start_clean and start_sasl to use as default is decided by the user when installing Erlang/OTP using Install. The user is asked "Do you want to use a minimal system startup instead of the SASL startup". If the answer is yes, then start_clean is used, otherwise - start_sasl is used. A copy of the selected boot script - is made, named start.boot and placed in - the ROOT/bin directory.

+ start_sasl is used. A copy of the selected boot script is + made, named start.boot and placed in directory + ROOT/bin.

User-Defined Boot Scripts

It is sometimes useful or necessary to create a user-defined boot script. This is true especially when running Erlang in - embedded mode, see Code Loading Strategy.

-

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 - Name.rel, using the function + embedded mode, see + Code Loading Strategy.

+

A boot script can be written manually. However, it is + recommended to create a boot script by generating it from a + release resource file Name.rel, using the function systools:make_script/1,2. 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).

-

Read more about .rel files in OTP Design Principles and - rel(4).

+ OTP applications, but can be plain Erlang).

+

For more information about .rel files, see + + OTP Design Principles and the + rel(4) manual page in + SASL.

The binary boot script file Name.boot is generated from - the boot script file Name.script using the function + the boot script file Name.script, using the function systools:script2boot(File).

@@ -148,16 +151,17 @@ init:stop() Code Loading Strategy

The runtime system can be started in either embedded or - interactive mode. Which one is decided by the command - line flag -mode.

+ interactive mode. Which one is decided by the + command-line flag -mode.

 % erl -mode embedded

Default mode is interactive.

+

The mode properties are as follows:

- In embedded mode, all code is loaded during system start-up + 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). - In interactive mode, code is dynamically loaded when first + by explicitly ordering the code server to do so.) + 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. @@ -165,21 +169,21 @@ init:stop()

Initially, the code path consists of the current working directory and all object code directories under ROOT/lib, where ROOT is the installation directory - of Erlang/OTP. Directories can be named Name[-Vsn] and - the code server, by default, chooses the directory with + of Erlang/OTP. Directories can be named Name[-Vsn]. The + code server, by default, chooses the directory with the highest version number among those which have the same Name. The -Vsn suffix is optional. If an ebin directory exists under the Name[-Vsn] - directory, it is this directory which is added to the code path.

-

The code path can be extended by using the command line flags - -pa Directories and -pz Directories. These will add - Directories to the head or end of the code path, - respectively. Example

+ directory, this directory is added to the code path.

+

The code path can be extended by using the command-line flags + -pa Directories and -pz Directories. These add + Directories to the head or the end of the code path, + respectively. Example:

 % erl -pa /home/arne/mycode

The code server module code contains a number of - functions for modifying and checking the search path, see - code(3).

+ functions for modifying and checking the search path, see the + code(3) manual page in Kernel.

@@ -192,49 +196,65 @@ init:stop() Documented in - module + Module .erl - Erlang Reference Manual + + + Erlang Reference Manual - include file + Include file .hrl - Erlang Reference Manual + + + Erlang Reference Manual - release resource file + Release resource file .rel - rel(4) + + rel(4) + manual page in SASL - application resource file + Application resource file .app - app(4) + + app(4) + manual page in Kernel - boot script + Boot script .script - script(4) + + script(4) + manual page in SASL - binary boot script + Binary boot script .boot - - configuration file + Configuration file .config - config(4) + + config(4) + manual page in Kernel - application upgrade file + Application upgrade file .appup - appup(4) + + appup(4) + manual page in SASL - release upgrade file + Release upgrade file relup - relup(4) + + relup(4) + manual page in SASL File Types 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 @@ upgrade.xml +
Introduction -

- As of Erlang/OTP 17, most applications deliver a valid - application upgrade (appup) file. In earlier releases, a + +

As of Erlang/OTP 17, most applications deliver a valid + application upgrade file (appup). 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 restart_application 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 restart_application instruction ensures that all modules in the application are reloaded and - thereby running the new code. -

+ thereby running the new code.

- Upgrade of core applications -

- The core applications ERTS, Kernel, STDLIB + Upgrade of Core Applications +

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 release_handler by the upgrade instruction - restart_new_emulator. This instruction will always be the - very first instruction executed, and it will restart the + restart_new_emulator. 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. -

- -

- It might seem strange to do a two-step upgrade instead of + new version.

+

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 - code_change 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. -

- -

- If, however, the more brutal variant is preferred, it is - possible to handwrite the release upgrade file using only the + code_change 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.

+

If, however, the more brutal variant is preferred, the + the release upgrade file can be handwritten using only the single upgrade instruction restart_emulator. This - instruction, in contrast to restart_new_emulator, will - cause the emulator to restart with the new versions of - all applications. -

- -

- Note that if other instructions are included before + instruction, in contrast to restart_new_emulator, + causes the emulator to restart with the new versions of + all applications.

+

Note: If other instructions are included before restart_emulator in the handwritten relup 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 restart_emulator has no effect as the - release_handler will not do any attempt at executing - them. -

- -

- See relup(4) for - information about the release upgrade file, and appup(4) for further information - about upgrade instructions. -

+ release_handler will not execute them.

+

For information about the release upgrade file, see the + relup(4) manual page + in SASL. + For more information about upgrade instructions, see the + appup(4) manual page + in SASL.

- Applications that still do not allow code upgrade -

- A few applications, for instance HiPE do not support - upgrade at all. This is indicated by an application upgrade file - containing only {Vsn,[],[]}. 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 relup file, preferably as described above - with only the restart_emulator instruction. -

- + Applications that Still do Not Allow Code Upgrade +

A few applications, such as HiPE, do not support upgrade. + This is indicated by an application upgrade file containing only + {Vsn,[],[]}. 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 relup, preferably as described above + with only the restart_emulator instruction.

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 @@ versions.xml -
OTP Version + + +
+ OTP Version

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 version - scheme used is described in more detail below.

- + introduced in OTP 17. The version scheme used is described in detail in + Version Scheme.

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 always preferred to use OTP applications from one single OTP version.

-

Release candidates have an -rc<N> - suffix. The suffix -rc0 will be used during development up to + suffix. The suffix -rc0 is used during development up to the first release candidate.

-
Retrieving Current OTP Version -

In an OTP source code tree, the OTP version can be read from - the text file <OTP source root>/OTP_VERSION. The - absolute path to the file can be constructed by calling - filename:join([code:root_dir(), "OTP_VERSION"]).

-

In an installed OTP development system, the OTP version can be read - from the text file <OTP installation root>/releases/<OTP release number>/OTP_VERSION. - The absolute path to the file can by constructed by calling - filename:join([code:root_dir(), "releases", erlang:system_info(otp_release), "OTP_VERSION"]).

-

If the version read from the OTP_VERSION file in a - development system has a ** suffix, the system has been - patched using the otp_patch_apply tool available to - licensed customers. In this case, the system consists of application - versions from multiple OTP versions. The version preceding the ** - 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 otp_patch_apply, the OTP_VERSION file - may identify an incorrect OTP version.

- -

No OTP_VERSION file will be placed in a - target system 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.

+
+ Retrieving Current OTP Version +

In an OTP source code tree, the OTP version can be read from + the text file <OTP source root>/OTP_VERSION. The + absolute path to the file can be constructed by calling + filename:join([code:root_dir(), "OTP_VERSION"]).

+

In an installed OTP development system, the OTP version can be read + from the text file <OTP installation root>/releases/<OTP release number>/OTP_VERSION. + The absolute path to the file can by constructed by calling + filename:join([code:root_dir(), "releases", erlang:system_info(otp_release), "OTP_VERSION"]).

+

If the version read from the OTP_VERSION file in a + development system has a ** suffix, the system has been + patched using the otp_patch_apply tool available to + licensed customers. In this case, the system consists of application + versions from multiple OTP versions. The version preceding the ** + 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 otp_patch_apply, the file OTP_VERSION + can identify an incorrect OTP version.

+

No OTP_VERSION file is placed in a + target system 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.

-
OTP Versions Table -

The text file <OTP source root>/otp_versions.table 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:

-
-<OtpVersion> : <ChangedAppVersions> # <UnchangedAppVersions> :
-
-

<OtpVersion> is on the format OTP-<VSN>, i.e., - the same as the git tag used to identify the source. - <ChangedAppVersions> and <UnchangedAppVersions> - are space separated lists of application versions on the - format <application>-<vsn>. - <ChangedAppVersions> corresponds to changed applications - with new version numbers in this OTP version, and - <UnchangedAppVersions> 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).

-

Using ordinary UNIX tools like sed and grep one - can easily find answers to various questions like:

- - Which OTP versions are kernel-3.0 part of? -

$ grep ' kernel-3\.0 ' otp_versions.table

 - In which OTP version was kernel-3.0 introduced? -

$ sed 's/#.*//;/ kernel-3\.0 /!d' otp_versions.table

 - -

The above commands give a bit more information than the exact answers, - but adequate information when manually searching for answers to these - questions.

-

The format of the otp_versions.table might be subject - to changes during the OTP 17 release.

 -
+
+ OTP Versions Table +

The text file <OTP source root>/otp_versions.table, + 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:

+ 
+<OtpVersion> : <ChangedAppVersions> # <UnchangedAppVersions> :
+

<OtpVersion> has the format OTP-<VSN>, + that is, the same as the git tag used to identify the source.

+

<ChangedAppVersions> and + <UnchangedAppVersions> are space-separated lists of + application versions and has the format + <application>-<vsn>.

+ + <ChangedAppVersions> corresponds to changed + applications with new version numbers in this OTP version. + <UnchangedAppVersions> corresponds to unchanged + application versions in this OTP version. + +

Both of them can be empty, but not at the same time. + If <ChangedAppVersions> 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).

+

By using ordinary UNIX tools like sed and grep one + can easily find answers to various questions like:

+ +

Which OTP versions are kernel-3.0 part of?

+

$ grep ' kernel-3\.0 ' otp_versions.table

+

In which OTP version was kernel-3.0 introduced?

+

$ sed 's/#.*//;/ kernel-3\.0 /!d' otp_versions.table +

+ +

The above commands give a bit more information than the exact + answers, but adequate information when manually searching for answers + to these questions.

+

The format of the otp_versions.table might be + subject to changes during the OTP 17 release.
+
-
Application Version -

As of OTP 17.0 application versions will use the same +

+ Application Version +

As of OTP 17.0 application versions use the same version scheme as the OTP version. Application versions part of a release candidate will however not have an -rc<N> 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.

-
+
+
+ Version Scheme -
Version Scheme - Note that the version scheme was changed as of OTP 17.0. This implies +

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. A list of - application versions used in OTP 17.0 can be found - at the end of this document. - -

In the normal case, a version will be constructed as - <Major>.<Minor>.<Patch> where <Major> - 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 <Minor> equals 0, - they are omitted. The three normal parts - <Major>.<Minor>.<Patch> will be changed as + application versions used in OTP 17.0 is included at the + end of this section

 +

In the normal case, a version is constructed as + <Major>.<Minor>.<Patch>, + where <Major> is the most significant part.

+

However, more dot-separated parts than this can exist. + The dot-separated parts consist of non-negative integers. If + all parts less significant than <Minor> equals + 0, they are omitted. The three normal parts + <Major>.<Minor>.<Patch> are changed as follows:

- - <Major>Increased when major changes, - including incompatibilities, have been made. - <Minor>Increased when new functionality - has been added. - <Patch>Increased when pure bug fixes - have been made. - -

When a part in the version number is increased, all less significant + + <Major> - Increases when major changes, + including incompatibilities, are made. + <Minor> - Increases when new + functionality is added. + <Patch> - Increases when pure bug fixes + are made. + +

When a part in the version number increases, all less significant parts are set to 0.

-

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.

-
Order of Versions -

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.

- -

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.

- -

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, 0 parts are added between the base - version and the least significant 1 part until a unique - version is found. Versions that have an order can be compared - as described in the paragraph above.

- -

An example of branched versions: The version 6.0.2.1 - is a branched version from the base version 6.0.2. - Versions on the form 6.0.2.<X> can be compared - with normal versions smaller than or equal to 6.0.2, - and other versions on the form 6.0.2.<X>. The - version 6.0.2.1 will include all changes in - 6.0.2. However, 6.0.3 will most likely - not include all changes in 6.0.2.1 (note that - these versions have no order). A second branched version from the base - version 6.0.2 will be version 6.0.2.0.1, and a - third branched version will be 6.0.2.0.0.1.

-
+
+ Order of Versions +

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.

+

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.

+

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, 0 parts are added between the base + version and the least significant 1 part until a unique + version is found. Versions that have an order can be compared + as described in the previous paragraph.

+

An example of branched versions: The version 6.0.2.1 + is a branched version from the base version 6.0.2. + Versions on the form 6.0.2.<X> can be compared + with normal versions smaller than or equal to 6.0.2, + and other versions on the form 6.0.2.<X>. The + version 6.0.2.1 will include all changes in + 6.0.2. However, 6.0.3 will most likely + not include all changes in 6.0.2.1 (note that + these versions have no order). A second branched version from the base + version 6.0.2 will be version 6.0.2.0.1, and a + third branched version will be 6.0.2.0.0.1.

+
+
+ OTP 17.0 Application Versions -
OTP 17.0 Application Versions -

The following application versions were part of OTP 17.0. If - the normal part of an applications version number compares - as smaller than the corresponding application version in this list, +

The 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.

asn1-3.0 @@ -262,6 +268,6 @@ wx-1.2 xmerl-1.3.7 -
+
-- cgit v1.2.3