aboutsummaryrefslogtreecommitdiffstats
path: root/system/doc/system_principles/system_principles.xml
diff options
context:
space:
mode:
Diffstat (limited to 'system/doc/system_principles/system_principles.xml')
-rw-r--r--system/doc/system_principles/system_principles.xml188
1 files changed, 104 insertions, 84 deletions
diff --git a/system/doc/system_principles/system_principles.xml b/system/doc/system_principles/system_principles.xml
index 70c69b1dab..70bb3cd441 100644
--- a/system/doc/system_principles/system_principles.xml
+++ b/system/doc/system_principles/system_principles.xml
@@ -4,7 +4,7 @@
<chapter>
<header>
<copyright>
- <year>1996</year><year>2014</year>
+ <year>1996</year><year>2015</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
@@ -28,35 +28,41 @@
<rev></rev>
<file>system_principles.xml</file>
</header>
+ <marker id="system principles"></marker>
<section>
<title>Starting the System</title>
- <p>An Erlang runtime system is started with the command <c>erl</c>:</p>
+ <p>An Erlang runtime system is started with command <c>erl</c>:</p>
<pre>
% <input>erl</input>
Erlang/OTP 17 [erts-6.0] [hipe] [smp:8:8]
Eshell V6.0 (abort with ^G)
1> </pre>
- <p><c>erl</c> understands a number of command line arguments, see
- <c>erl(1)</c>. A number of them are also described in this chapter.</p>
- <p>Application programs can access the values of the command line
- arguments by calling one of the functions
- <c>init:get_argument(Key)</c>, or <c>init:get_arguments()</c>.
- See <c>init(3)</c>.</p>
+ <p><c>erl</c> understands a number of command-line arguments, see
+ the <seealso marker="erts:erl">erl(1)</seealso> manual page in
+ ERTS. Some of them are also described in this chapter.</p>
+ <p>Application programs can access the values of the command-line
+ arguments by calling the function <c>init:get_argument(Key)</c>
+ or <c>init:get_arguments()</c>. See the
+ <seealso marker="erts:init">init(3)</seealso> manual page in
+ ERTS.</p>
</section>
<section>
<title>Restarting and Stopping the System</title>
- <p>The runtime system can be halted by calling <c>halt/0,1</c>.
- See <c>erlang(3)</c>.</p>
- <p>The module <c>init</c> contains function for restarting,
- rebooting and stopping the runtime system. See <c>init(3)</c>.</p>
+ <p>The runtime system is halted by calling <c>halt/0,1</c>. For
+ details, see the <seealso marker="erts:erlang">erlang(3)</seealso>
+ manual page in ERTS.</p>
+ <p>The module <c>init</c> contains functions for restarting,
+ rebooting, and stopping the runtime system:</p>
<pre>
init:restart()
init:reboot()
init:stop()</pre>
- <p>Also, the runtime system will terminate if the Erlang shell is
+ <p>For details, see the <seealso marker="erts:init">init(3)</seealso>
+ manual page in ERTS.</p>
+ <p>The runtime system terminates if the Erlang shell is
terminated.</p>
</section>
@@ -69,14 +75,15 @@ init:stop()</pre>
<p>A boot script file has the extension <c>.script</c>.
The runtime system uses a binary version of the script. This
<em>binary boot script</em> file has the extension <c>.boot</c>.</p>
- <p>Which boot script to use is specified by the command line flag
- <c>-boot</c>. The extension <c>.boot</c> should be omitted.
- Example, using the boot script <c>start_all.boot</c>:</p>
+ <p>Which boot script to use is specified by the command-line flag
+ <c>-boot</c>. The extension <c>.boot</c> is to be omitted.
+ For example, using the boot script <c>start_all.boot</c>:</p>
<pre>
% <input>erl -boot start_all</input></pre>
<p>If no boot script is specified, it defaults to
- <c>ROOT/bin/start</c>, see Default Boot Scripts below.</p>
- <p>The command line flag <c>-init_debug</c> makes the <c>init</c>
+ <c>ROOT/bin/start</c>, see <seealso marker="#default_boot_scripts">
+ Default Boot Scripts</seealso>.</p>
+ <p>The command-line flag <c>-init_debug</c> makes the <c>init</c>
process write some debug information while interpreting the boot
script:</p>
<pre>
@@ -87,59 +94,55 @@ init:stop()</pre>
{start,heart}
{start,error_logger}
...</pre>
- <p>See <c>script(4)</c> for a detailed description of the syntax
- and contents of the boot script.</p>
+ <p>For a detailed description of the syntax and contents of the
+ boot script, see the <c>script(4)</c> manual page in SASL.</p>
<section>
+ <marker id="default_boot_scripts"></marker>
<title>Default Boot Scripts</title>
- <p>Erlang/OTP comes with two boot scripts:</p>
- <taglist>
- <tag><c>start_clean.boot</c></tag>
- <item>
- <p>Loads the code for and starts the applications Kernel and
- STDLIB.</p>
- </item>
- <tag><c>start_sasl.boot</c></tag>
- <item>
- <p>Loads the code for and starts the applications Kernel,
- STDLIB and SASL.</p>
- </item>
- <tag><c>no_dot_erlang.boot</c></tag>
- <item>
- <p>Loads the code for and starts the applications Kernel and
- STDLIB, skips loading the <c>.erlang</c> file.
- Useful for scripts and other tools that should be behave the
- same irregardless 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 +151,17 @@ init:stop()</pre>
<marker id="code_loading"></marker>
<title>Code Loading Strategy</title>
<p>The runtime system can be started in either <em>embedded</em> or
- <em>interactive</em> mode. Which one is decided by the command
- line flag <c>-mode</c>.</p>
+ <em>interactive</em> mode. Which one is decided by the
+ command-line flag <c>-mode</c>.</p>
<pre>
% <input>erl -mode embedded</input></pre>
<p>Default mode is <c>interactive</c>.</p>
+ <p>The mode properties are as follows:</p>
<list type="bulleted">
- <item>In embedded mode, all code is loaded during system start-up
+ <item>In embedded mode, all code is loaded during system startup
according to the boot script. (Code can also be loaded later
- by explicitly ordering the code server to do so).</item>
- <item>In interactive mode, code is dynamically loaded when first
+ by explicitly ordering the code server to do so.)</item>
+ <item>In interactive mode, the code is dynamically loaded when first
referenced. When a call to a function in a module is made, and
the module is not loaded, the code server searches the code path
and loads the module into the system.</item>
@@ -165,21 +169,21 @@ init:stop()</pre>
<p>Initially, the code path consists of the current
working directory and all object code directories under
<c>ROOT/lib</c>, where <c>ROOT</c> is the installation directory
- of Erlang/OTP. Directories can be named <c>Name[-Vsn]</c> and
- the code server, by default, chooses the directory with
+ of Erlang/OTP. Directories can be named <c>Name[-Vsn]</c>. The
+ code server, by default, chooses the directory with
the highest version number among those which have the same
<c>Name</c>. The <c>-Vsn</c> suffix is optional. If an
<c>ebin</c> directory exists under the <c>Name[-Vsn]</c>
- directory, it is this directory which is added to the code path.</p>
- <p>The code path can be extended by using the command line flags
- <c>-pa Directories</c> and <c>-pz Directories</c>. These will add
- <c>Directories</c> to the head or end of the code path,
- respectively. Example</p>
+ directory, this directory is added to the code path.</p>
+ <p>The code path can be extended by using the command-line flags
+ <c>-pa Directories</c> and <c>-pz Directories</c>. These add
+ <c>Directories</c> to the head or the end of the code path,
+ respectively. Example:</p>
<pre>
% <input>erl -pa /home/arne/mycode</input></pre>
<p>The code server module <c>code</c> contains a number of
- functions for modifying and checking the search path, see
- <c>code(3)</c>.</p>
+ functions for modifying and checking the search path, see the
+ <c>code(3)</c> manual page in Kernel.</p>
</section>
<section>
@@ -192,49 +196,65 @@ init:stop()</pre>
<cell align="left" valign="middle"><em>Documented in</em></cell>
</row>
<row>
- <cell align="left" valign="middle">module</cell>
+ <cell align="left" valign="middle">Module</cell>
<cell align="left" valign="middle"><c>.erl</c></cell>
- <cell align="left" valign="middle">Erlang Reference Manual</cell>
+ <cell align="left" valign="middle">
+ <seealso marker="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>