← Back to branch summary

~rdoering/ubuntu/karmic/erlang/fix-535090

« back to all changes in this revision

Viewing changes to lib/sasl/doc/src/script.xml

  • Committer: Bazaar Package Importer
  • Author(s): Sergei Golovan
  • Date: 2009-02-15 16:42:52 UTC
  • mfrom: (3.1.2 squeeze)
  • Revision ID: james.westby@ubuntu.com-20090215164252-q5x4rcf8a5pbesb1
Tags: 1:12.b.5-dfsg-2
Upload to unstable after lenny is released.

Show diffs side-by-side

added added

removed removed

Lines of Context:
lib/sasl/doc/src/script.xml
 
1
<?xml version="1.0" encoding="latin1" ?>
 
2
<!DOCTYPE fileref SYSTEM "fileref.dtd">
 
3
 
 
4
<fileref>
 
5
  <header>
 
6
    <copyright>
 
7
      <year>1997</year>
 
8
      <year>2007</year>
 
9
      <holder>Ericsson AB, All Rights Reserved</holder>
 
10
    </copyright>
 
11
    <legalnotice>
 
12
  The contents of this file are subject to the Erlang Public License,
 
13
  Version 1.1, (the "License"); you may not use this file except in
 
14
  compliance with the License. You should have received a copy of the
 
15
  Erlang Public License along with this software. If not, it can be
 
16
  retrieved online at http://www.erlang.org/.
 
17
 
 
18
  Software distributed under the License is distributed on an "AS IS"
 
19
  basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
 
20
  the License for the specific language governing rights and limitations
 
21
  under the License.
 
22
 
 
23
  The Initial Developer of the Original Code is Ericsson AB.
 
24
    </legalnotice>
 
25
 
 
26
    <title>script</title>
 
27
    <prepared>Martin Bj&ouml;rklund</prepared>
 
28
    <responsible>Bjarne D&auml;cker</responsible>
 
29
    <docno></docno>
 
30
    <approved>Bjarne D&auml;cker</approved>
 
31
    <checked></checked>
 
32
    <date>97-06-03</date>
 
33
    <rev>A</rev>
 
34
    <file>script.sgml</file>
 
35
  </header>
 
36
  <file>script</file>
 
37
  <filesummary>Boot script</filesummary>
 
38
  <description>
 
39
    <p>The <em>boot script</em> describes how the Erlang runtime system is
 
40
      started.  It contains instructions on which code to load and
 
41
      which processes and applications to start.
 
42
      </p>
 
43
    <p>The command <c>erl -boot Name</c> starts the system with a boot
 
44
      file called <c>Name.boot</c>, which is generated from the
 
45
      <c>Name.script</c> file, using <c>systools:script2boot/1</c>.
 
46
      </p>
 
47
    <p>The <c>.script</c> file is generated by <c>systools</c> from a
 
48
      <c>.rel</c> file and <c>.app</c> files.
 
49
      </p>
 
50
  </description>
 
51
 
 
52
  <section>
 
53
    <title>FILE SYNTAX</title>
 
54
    <p>The boot script is stored in a file with the extension
 
55
      <c>.script</c></p>
 
56
    <p>The file has the following syntax:
 
57
      </p>
 
58
    <code type="none">
 
59
{script, {Name, Vsn},
 
60
 [
 
61
  {progress, loading},
 
62
  {preLoaded, [Mod1, Mod2, ...]},
 
63
  {path, [Dir1,"$ROOT/Dir",...]}.
 
64
  {primLoad, [Mod1, Mod2, ...]},
 
65
  ...
 
66
  {kernel_load_completed},
 
67
  {progress, loaded},
 
68
  {kernelProcess, Name, {Mod, Func, Args}},
 
69
  ...
 
70
  {apply, {Mod, Func, Args}},
 
71
  ...
 
72
  {progress, started}]}.    </code>
 
73
    <list type="bulleted">
 
74
      <item><c>Name = string()</c> defines the name of the system.
 
75
      </item>
 
76
      <item><c>Vsn = string()</c> defines the version of the system.
 
77
      </item>
 
78
      <item><c>{progress, Term}</c> sets the "progress" of the
 
79
       initialization program.  The function <c>init:get_status()</c>
 
80
       returns the current value of the progress, which is
 
81
      <c>{InternalStatus,Term}</c>.
 
82
      </item>
 
83
      <item>
 
84
        <p><c>{path, [Dir]}</c> where <c>Dir</c> is a string.  This
 
85
          argument sets the load path of the system to <c>[Dir]</c>. The
 
86
          load path used to load modules is obtained from the initial
 
87
          load path, which is given in the script file, together with
 
88
          any path flags which were supplied in the command line
 
89
          arguments. The command line arguments modify the path as
 
90
          follows:</p>
 
91
        <list type="bulleted">
 
92
          <item><c>-pa Dir1 Dir2 ... DirN</c> adds the directories
 
93
          <c>Dir1, Dir2, ..., DirN</c> to the front of the initial
 
94
           load path.
 
95
          </item>
 
96
          <item><c>-pz Dir1 Dir2 ... DirN</c> adds the directories
 
97
          <c>Dir1, Dir2, ..., DirN</c> to the end of the initial
 
98
           load path.
 
99
          </item>
 
100
          <item>
 
101
            <p><c>-path Dir1 Dir2 ... DirN</c> defines a set of
 
102
              directories <c>Dir1, Dir2, ..., DirN</c> which replaces
 
103
              the search path given in the script file. Directory names
 
104
              in the path are interpreted as follows:</p>
 
105
            <list type="bulleted">
 
106
              <item>Directory names starting with <c>/</c> are assumed
 
107
               to be absolute path names.
 
108
              </item>
 
109
              <item>Directory names not starting with <c>/</c> are
 
110
               assumed to be relative the current working directory.
 
111
              </item>
 
112
              <item>The special <c>$ROOT</c> variable can only be used
 
113
               in the script, not as a command line argument. The
 
114
               given directory is relative the Erlang installation
 
115
               directory.
 
116
              </item>
 
117
            </list>
 
118
          </item>
 
119
        </list>
 
120
      </item>
 
121
      <item><c>{primLoad, [Mod]}</c> loads the modules <c>[Mod]</c>
 
122
       from the directories specified in <c>Path</c>.  The script
 
123
       interpreter fetches the appropriate module by calling the
 
124
       function <c>erl_prim_loader:get_file(Mod)</c>.  A fatal error
 
125
       which terminates the system will occur if the module cannot be
 
126
       located.
 
127
      </item>
 
128
      <item><c>{kernel_load_completed}</c> indicates that all modules
 
129
       which <em>must</em> be loaded <em>before</em> any processes
 
130
       are started are loaded. In interactive mode, all
 
131
      <c>{primLoad,[Mod]}</c> commands interpreted after this
 
132
       command are ignored, and these modules are loaded on demand.
 
133
       In embedded mode, <c>kernel_load_completed</c> is ignored, and
 
134
       all modules are loaded during system start.
 
135
      </item>
 
136
      <item><c>{kernelProcess, Name, {Mod, Func, Args}}</c> starts a
 
137
       "kernel process".  The kernel process <c>Name</c> is started
 
138
       by evaluating <c>apply(Mod, Func, Args)</c> which is expected
 
139
       to return <c>{ok, Pid}</c> or <c>ignore</c>.  The <c>init</c>
 
140
       process monitors the behaviour of <c>Pid</c> and terminates
 
141
       the system if <c>Pid</c> dies.  Kernel processes are key
 
142
       components of the runtime system.  Users do not normally add
 
143
       new kernel processes.
 
144
      </item>
 
145
      <item><c>{apply, {Mod, Func, Args}}</c>. The init process simply
 
146
       evaluates <c>apply(Mod, Func, Args)</c>.  The system
 
147
       terminates if this results in an error.  The boot procedure
 
148
       hangs if this function never returns.
 
149
      </item>
 
150
    </list>
 
151
    <note>
 
152
      <p>In the <c>interactive</c> system the code loader provides
 
153
        demand driven code loading, but in the <c>embedded</c> system
 
154
        the code loader loads all the code immediately.  The same
 
155
        version of <c>code</c> is used in both cases.  The code server
 
156
        calls <c>init:get_argument(mode)</c> to find out if it should
 
157
        run in demand mode, or non-demand driven mode.
 
158
        </p>
 
159
    </note>
 
160
  </section>
 
161
 
 
162
  <section>
 
163
    <title>SEE ALSO</title>
 
164
    <p>systools(3)
 
165
      </p>
 
166
  </section>
 
167
</fileref>
 
168