← Back to branch summary

~ubuntu-branches/debian/squeeze/erlang/squeeze

« back to all changes in this revision

Viewing changes to system/doc/system_principles/system_principles.xml

  • Committer: Bazaar Package Importer
  • Author(s): Sergei Golovan
  • Date: 2010-03-09 17:34:57 UTC
  • mfrom: (10.1.2 sid)
  • Revision ID: james.westby@ubuntu.com-20100309173457-4yd6hlcb2osfhx31
Tags: 1:13.b.4-dfsg-3
Manpages in section 1 are needed even if only arch-dependent packages are
built. So, re-enabled them.

Show diffs side-by-side

added added

removed removed

Lines of Context:
system/doc/system_principles/system_principles.xml
 
1
<?xml version="1.0" encoding="latin1" ?>
 
2
<!DOCTYPE chapter SYSTEM "chapter.dtd">
 
3
 
 
4
<chapter>
 
5
  <header>
 
6
    <copyright>
 
7
      <year>1996</year><year>2009</year>
 
8
      <holder>Ericsson AB. All Rights Reserved.</holder>
 
9
    </copyright>
 
10
    <legalnotice>
 
11
      The contents of this file are subject to the Erlang Public License,
 
12
      Version 1.1, (the "License"); you may not use this file except in
 
13
      compliance with the License. You should have received a copy of the
 
14
      Erlang Public License along with this software. If not, it can be
 
15
      retrieved online at http://www.erlang.org/.
 
16
    
 
17
      Software distributed under the License is distributed on an "AS IS"
 
18
      basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
 
19
      the License for the specific language governing rights and limitations
 
20
      under the License.
 
21
    
 
22
    </legalnotice>
 
23
 
 
24
    <title>System Principles</title>
 
25
    <prepared></prepared>
 
26
    <docno></docno>
 
27
    <date></date>
 
28
    <rev></rev>
 
29
    <file>system_principles.xml</file>
 
30
  </header>
 
31
 
 
32
  <section>
 
33
    <title>Starting the System</title>
 
34
    <p>An Erlang runtime system is started with the command <c>erl</c>:</p>
 
35
    <pre>
 
36
% <input>erl</input>
 
37
Erlang (BEAM) emulator version 5.2.3.5 [hipe] [threads:0]
 
38
 
 
39
Eshell V5.2.3.5  (abort with ^G)
 
40
1> </pre>
 
41
    <p><c>erl</c> understands a number of command line arguments, see
 
42
      <c>erl(1)</c>. A number of them are also described in this
 
43
      chapter.</p>
 
44
    <p>Application programs can access the values of the command line
 
45
      arguments by calling one of the functions
 
46
      <c>init:get_argument(Key)</c>, or <c>init:get_arguments()</c>.
 
47
      See <c>init(3)</c>.</p>
 
48
  </section>
 
49
 
 
50
  <section>
 
51
    <title>Restarting and Stopping the System</title>
 
52
    <p>The runtime system can be halted by calling <c>halt/0,1</c>.
 
53
      See <c>erlang(3)</c>.</p>
 
54
    <p>The module <c>init</c> contains function for restarting,
 
55
      rebooting and stopping the runtime system. See <c>init(3)</c>.</p>
 
56
    <pre>
 
57
init:restart()
 
58
init:reboot()
 
59
init:stop()</pre>
 
60
    <p>Also, the runtime system will terminate if the Erlang shell is
 
61
      terminated.</p>
 
62
  </section>
 
63
 
 
64
  <section>
 
65
    <marker id="BOOTSCRIPT"></marker>
 
66
    <title>Boot Scripts</title>
 
67
    <p>The runtime system is started using a <em>boot script</em>.
 
68
      The boot script contains instructions on which code to load and
 
69
      which processes and applications to start.</p>
 
70
    <p>A boot script file has the extension <c>.script</c>.
 
71
      The runtime system uses a binary version of the script. This
 
72
      <em>binary boot script</em> file has the extension <c>.boot</c>.</p>
 
73
    <p>Which boot script to use is specified by the command line flag
 
74
      <c>-boot</c>. The extension <c>.boot</c> should be omitted.
 
75
      Example, using the boot script <c>start_all.boot</c>:</p>
 
76
    <pre>
 
77
% <input>erl -boot start_all</input></pre>
 
78
    <p>If no boot script is specified, it defaults to
 
79
      <c>ROOT/bin/start</c>, see Default Boot Scripts below.</p>
 
80
    <p>The command line flag <c>-init_debug</c> makes the <c>init</c>
 
81
      process write some debug information while interpreting the boot
 
82
      script:</p>
 
83
    <pre>
 
84
% <input>erl -init_debug</input>
 
85
{progress,preloaded}
 
86
{progress,kernel_load_completed}
 
87
{progress,modules_loaded}
 
88
{start,heart}
 
89
{start,error_logger}
 
90
...</pre>
 
91
    <p>See <c>script(4)</c> for a detailed description of the syntax
 
92
      and contents of the boot script.</p>
 
93
 
 
94
    <section>
 
95
      <title>Default Boot Scripts</title>
 
96
      <p>Erlang/OTP comes with two boot scripts:</p>
 
97
      <taglist>
 
98
        <tag><c>start_clean.boot</c></tag>
 
99
        <item>
 
100
          <p>Loads the code for and starts the applications Kernel and
 
101
            STDLIB.</p>
 
102
        </item>
 
103
        <tag><c>start_sasl.boot</c></tag>
 
104
        <item>
 
105
          <p>Loads the code for and starts the applications Kernel,
 
106
            STDLIB and SASL.</p>
 
107
        </item>
 
108
      </taglist>
 
109
      <p>Which of <c>start_clean</c> and <c>start_sasl</c> to use as
 
110
        default is decided by the user when installing Erlang/OTP using
 
111
        <c>Install</c>. The user is asked "Do you want to use a minimal
 
112
        system startup instead of the SASL startup". If the answer is
 
113
        yes, then <c>start_clean</c> is used, otherwise
 
114
        <c>start_sasl</c> is used. A copy of the selected boot script
 
115
        is made, named <c>start.boot</c> and placed in
 
116
        the <c>ROOT/bin</c> directory.</p>
 
117
    </section>
 
118
 
 
119
    <section>
 
120
      <title>User-Defined Boot Scripts</title>
 
121
      <p>It is sometimes useful or necessary to create a user-defined
 
122
        boot script. This is true especially when running Erlang in
 
123
        embedded mode, see <seealso marker="#code_loading">Code Loading Strategy</seealso>.</p>
 
124
      <p>It is possible to write a boot script manually.
 
125
        The recommended way to create a boot script, however, is to
 
126
        generate the boot script from a release resource file
 
127
        <c>Name.rel</c>, using the function
 
128
        <c>systools:make_script/1,2</c>. This requires that the source
 
129
        code is structured as applications according to the OTP design
 
130
        principles. (The program does not have to be started in terms of
 
131
        OTP applications but can be plain Erlang).</p>
 
132
      <p>Read more about <c>.rel</c> files in OTP Design Principles and
 
133
        <c>rel(4)</c>.</p>
 
134
      <p>The binary boot script file <c>Name.boot</c> is generated from
 
135
        the boot script file <c>Name.script</c> using the function
 
136
        <c>systools:script2boot(File)</c>.</p>
 
137
    </section>
 
138
  </section>
 
139
 
 
140
  <section>
 
141
    <marker id="code_loading"></marker>
 
142
    <title>Code Loading Strategy</title>
 
143
    <p>The runtime system can be started in either <em>embedded</em> or
 
144
      <em>interactive</em> mode. Which one is decided by the command
 
145
      line flag <c>-mode</c>.</p>
 
146
    <pre>
 
147
% <input>erl -mode embedded</input></pre>
 
148
    <p>Default mode is <c>interactive</c>.</p>
 
149
    <list type="bulleted">
 
150
      <item>In embedded mode, all code is loaded during system start-up
 
151
       according to the boot script. (Code can also be loaded later
 
152
       by explicitly ordering the code server to do so).</item>
 
153
      <item>In interactive mode, code is dynamically loaded when first
 
154
       referenced. When a call to a function in a module is made, and
 
155
       the module is not loaded, the code server searches the code path
 
156
       and loads the module into the system.</item>
 
157
    </list>
 
158
    <p>Initially, the code path consists of the current
 
159
      working directory and all object code directories under
 
160
      <c>ROOT/lib</c>, where <c>ROOT</c> is the installation directory
 
161
      of Erlang/OTP. Directories can be named <c>Name[-Vsn]</c> and
 
162
      the code server, by default, chooses the directory with
 
163
      the highest version number among those which have the same
 
164
      <c>Name</c>. The <c>-Vsn</c> suffix is optional. If an
 
165
      <c>ebin</c> directory exists under the <c>Name[-Vsn]</c>
 
166
      directory, it is this directory which is added to the code path.</p>
 
167
    <p>The code path can be extended by using the command line flags
 
168
      <c>-pa Directories</c> and <c>-pz Directories</c>. These will add
 
169
      <c>Directories</c> to the head or end of the code path,
 
170
      respectively. Example</p>
 
171
    <pre>
 
172
% <input>erl -pa /home/arne/mycode</input></pre>
 
173
    <p>The code server module <c>code</c> contains a number of
 
174
      functions for modifying and checking the search path, see
 
175
      <c>code(3)</c>.</p>
 
176
  </section>
 
177
 
 
178
  <section>
 
179
    <title>File Types</title>
 
180
    <p>The following file types are defined in Erlang/OTP:</p>
 
181
    <table>
 
182
      <row>
 
183
        <cell align="left" valign="middle"><em>File Type</em></cell>
 
184
        <cell align="left" valign="middle"><em>File Name/Extension</em></cell>
 
185
        <cell align="left" valign="middle"><em>Documented in</em></cell>
 
186
      </row>
 
187
      <row>
 
188
        <cell align="left" valign="middle">module</cell>
 
189
        <cell align="left" valign="middle"><c>.erl</c></cell>
 
190
        <cell align="left" valign="middle">Erlang Reference Manual</cell>
 
191
      </row>
 
192
      <row>
 
193
        <cell align="left" valign="middle">include file</cell>
 
194
        <cell align="left" valign="middle"><c>.hrl</c></cell>
 
195
        <cell align="left" valign="middle">Erlang Reference Manual</cell>
 
196
      </row>
 
197
      <row>
 
198
        <cell align="left" valign="middle">release resource file</cell>
 
199
        <cell align="left" valign="middle"><c>.rel</c></cell>
 
200
        <cell align="left" valign="middle"><c>rel(4)</c></cell>
 
201
      </row>
 
202
      <row>
 
203
        <cell align="left" valign="middle">application resource file</cell>
 
204
        <cell align="left" valign="middle"><c>.app</c></cell>
 
205
        <cell align="left" valign="middle"><c>app(4)</c></cell>
 
206
      </row>
 
207
      <row>
 
208
        <cell align="left" valign="middle">boot script</cell>
 
209
        <cell align="left" valign="middle"><c>.script</c></cell>
 
210
        <cell align="left" valign="middle"><c>script(4)</c></cell>
 
211
      </row>
 
212
      <row>
 
213
        <cell align="left" valign="middle">binary boot script</cell>
 
214
        <cell align="left" valign="middle"><c>.boot</c></cell>
 
215
        <cell align="left" valign="middle">-</cell>
 
216
      </row>
 
217
      <row>
 
218
        <cell align="left" valign="middle">configuration file</cell>
 
219
        <cell align="left" valign="middle"><c>.config</c></cell>
 
220
        <cell align="left" valign="middle"><c>config(4)</c></cell>
 
221
      </row>
 
222
      <row>
 
223
        <cell align="left" valign="middle">application upgrade file</cell>
 
224
        <cell align="left" valign="middle"><c>.appup</c></cell>
 
225
        <cell align="left" valign="middle"><c>appup(4)</c></cell>
 
226
      </row>
 
227
      <row>
 
228
        <cell align="left" valign="middle">release upgrade file</cell>
 
229
        <cell align="left" valign="middle"><c>relup</c></cell>
 
230
        <cell align="left" valign="middle"><c>relup(4)</c></cell>
 
231
      </row>
 
232
      <tcaption>File Types</tcaption>
 
233
    </table>
 
234
  </section>
 
235
</chapter>
 
236