aboutsummaryrefslogtreecommitdiffstats
path: root/system/doc/system_principles/system_principles.xml
diff options
context:
space:
mode:
authorErlang/OTP <[email protected]>2009-11-20 14:54:40 +0000
committerErlang/OTP <[email protected]>2009-11-20 14:54:40 +0000
commit84adefa331c4159d432d22840663c38f155cd4c1 (patch)
treebff9a9c66adda4df2106dfd0e5c053ab182a12bd /system/doc/system_principles/system_principles.xml
downloadotp-84adefa331c4159d432d22840663c38f155cd4c1.tar.gz
otp-84adefa331c4159d432d22840663c38f155cd4c1.tar.bz2
otp-84adefa331c4159d432d22840663c38f155cd4c1.zip
The R13B03 release.OTP_R13B03
Diffstat (limited to 'system/doc/system_principles/system_principles.xml')
-rw-r--r--system/doc/system_principles/system_principles.xml236
1 files changed, 236 insertions, 0 deletions
diff --git a/system/doc/system_principles/system_principles.xml b/system/doc/system_principles/system_principles.xml
new file mode 100644
index 0000000000..27512a1660
--- /dev/null
+++ b/system/doc/system_principles/system_principles.xml
@@ -0,0 +1,236 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE chapter SYSTEM "chapter.dtd">
+
+<chapter>
+ <header>
+ <copyright>
+ <year>1996</year><year>2009</year>
+ <holder>Ericsson AB. All Rights Reserved.</holder>
+ </copyright>
+ <legalnotice>
+ The contents of this file are subject to the Erlang Public License,
+ Version 1.1, (the "License"); you may not use this file except in
+ compliance with the License. You should have received a copy of the
+ Erlang Public License along with this software. If not, it can be
+ retrieved online at http://www.erlang.org/.
+
+ Software distributed under the License is distributed on an "AS IS"
+ basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+ the License for the specific language governing rights and limitations
+ under the License.
+
+ </legalnotice>
+
+ <title>System Principles</title>
+ <prepared></prepared>
+ <docno></docno>
+ <date></date>
+ <rev></rev>
+ <file>system_principles.xml</file>
+ </header>
+
+ <section>
+ <title>Starting the System</title>
+ <p>An Erlang runtime system is started with the command <c>erl</c>:</p>
+ <pre>
+% <input>erl</input>
+Erlang (BEAM) emulator version 5.2.3.5 [hipe] [threads:0]
+
+Eshell V5.2.3.5 (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>
+ </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>
+ <pre>
+init:restart()
+init:reboot()
+init:stop()</pre>
+ <p>Also, the runtime system will terminate if the Erlang shell is
+ terminated.</p>
+ </section>
+
+ <section>
+ <marker id="BOOTSCRIPT"></marker>
+ <title>Boot Scripts</title>
+ <p>The runtime system is started using a <em>boot script</em>.
+ The boot script contains instructions on which code to load and
+ which processes and applications to start.</p>
+ <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>
+ <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>
+ process write some debug information while interpreting the boot
+ script:</p>
+ <pre>
+% <input>erl -init_debug</input>
+{progress,preloaded}
+{progress,kernel_load_completed}
+{progress,modules_loaded}
+{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>
+
+ <section>
+ <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>
+ </taglist>
+ <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>
+ </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
+ <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>
+ <p>The binary boot script file <c>Name.boot</c> is generated from
+ the boot script file <c>Name.script</c> using the function
+ <c>systools:script2boot(File)</c>.</p>
+ </section>
+ </section>
+
+ <section>
+ <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>
+ <pre>
+% <input>erl -mode embedded</input></pre>
+ <p>Default mode is <c>interactive</c>.</p>
+ <list type="bulleted">
+ <item>In embedded mode, all code is loaded during system start-up
+ 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
+ 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>
+ </list>
+ <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
+ 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>
+ <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>
+ </section>
+
+ <section>
+ <title>File Types</title>
+ <p>The following file types are defined in Erlang/OTP:</p>
+ <table>
+ <row>
+ <cell align="left" valign="middle"><em>File Type</em></cell>
+ <cell align="left" valign="middle"><em>File Name/Extension</em></cell>
+ <cell align="left" valign="middle"><em>Documented in</em></cell>
+ </row>
+ <row>
+ <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>
+ </row>
+ <row>
+ <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>
+ </row>
+ <row>
+ <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>
+ </row>
+ <row>
+ <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>
+ </row>
+ <row>
+ <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>
+ </row>
+ <row>
+ <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"><c>.config</c></cell>
+ <cell align="left" valign="middle"><c>config(4)</c></cell>
+ </row>
+ <row>
+ <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>
+ </row>
+ <row>
+ <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>
+ </row>
+ <tcaption>File Types</tcaption>
+ </table>
+ </section>
+</chapter>
+