<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE chapter SYSTEM "chapter.dtd">
<chapter>
<header>
<copyright>
<year>1996</year><year>2013</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>
<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>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>
