The R13B03 release.OTP_R13B03

1 files changed, 168 insertions, 0 deletions

diff --git a/lib/sasl/doc/src/script.xml b/lib/sasl/doc/src/script.xml
new file mode 100644
index 0000000000..6bac07d106
--- /dev/null
+++ b/lib/sasl/doc/src/script.xml
@@ -0,0 +1,168 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE fileref SYSTEM "fileref.dtd">
+
+<fileref>
+  <header>
+    <copyright>
+      <year>1997</year>
+      <year>2007</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.
+
+  The Initial Developer of the Original Code is Ericsson AB.
+    </legalnotice>
+
+    <title>script</title>
+    <prepared>Martin Bj&ouml;rklund</prepared>
+    <responsible>Bjarne D&auml;cker</responsible>
+    <docno></docno>
+    <approved>Bjarne D&auml;cker</approved>
+    <checked></checked>
+    <date>97-06-03</date>
+    <rev>A</rev>
+    <file>script.sgml</file>
+  </header>
+  <file>script</file>
+  <filesummary>Boot script</filesummary>
+  <description>
+    <p>The <em>boot script</em> describes how the Erlang runtime system is
+      started.  It contains instructions on which code to load and
+      which processes and applications to start.
+      </p>
+    <p>The command <c>erl -boot Name</c> starts the system with a boot
+      file called <c>Name.boot</c>, which is generated from the
+      <c>Name.script</c> file, using <c>systools:script2boot/1</c>.
+      </p>
+    <p>The <c>.script</c> file is generated by <c>systools</c> from a
+      <c>.rel</c> file and <c>.app</c> files.
+      </p>
+  </description>
+
+  <section>
+    <title>FILE SYNTAX</title>
+    <p>The boot script is stored in a file with the extension
+      <c>.script</c></p>
+    <p>The file has the following syntax:
+      </p>
+    <code type="none">
+{script, {Name, Vsn},
+ [
+  {progress, loading},
+  {preLoaded, [Mod1, Mod2, ...]},
+  {path, [Dir1,"$ROOT/Dir",...]}.
+  {primLoad, [Mod1, Mod2, ...]},
+  ...
+  {kernel_load_completed},
+  {progress, loaded},
+  {kernelProcess, Name, {Mod, Func, Args}},
+  ...
+  {apply, {Mod, Func, Args}},
+  ...
+  {progress, started}]}.    </code>
+    <list type="bulleted">
+      <item><c>Name = string()</c> defines the name of the system.
+      </item>
+      <item><c>Vsn = string()</c> defines the version of the system.
+      </item>
+      <item><c>{progress, Term}</c> sets the "progress" of the
+       initialization program.  The function <c>init:get_status()</c>
+       returns the current value of the progress, which is
+      <c>{InternalStatus,Term}</c>.
+      </item>
+      <item>
+        <p><c>{path, [Dir]}</c> where <c>Dir</c> is a string.  This
+          argument sets the load path of the system to <c>[Dir]</c>. The
+          load path used to load modules is obtained from the initial
+          load path, which is given in the script file, together with
+          any path flags which were supplied in the command line
+          arguments. The command line arguments modify the path as
+          follows:</p>
+        <list type="bulleted">
+          <item><c>-pa Dir1 Dir2 ... DirN</c> adds the directories
+          <c>Dir1, Dir2, ..., DirN</c> to the front of the initial
+           load path.
+          </item>
+          <item><c>-pz Dir1 Dir2 ... DirN</c> adds the directories
+          <c>Dir1, Dir2, ..., DirN</c> to the end of the initial
+           load path.
+          </item>
+          <item>
+            <p><c>-path Dir1 Dir2 ... DirN</c> defines a set of
+              directories <c>Dir1, Dir2, ..., DirN</c> which replaces
+              the search path given in the script file. Directory names
+              in the path are interpreted as follows:</p>
+            <list type="bulleted">
+              <item>Directory names starting with <c>/</c> are assumed
+               to be absolute path names.
+              </item>
+              <item>Directory names not starting with <c>/</c> are
+               assumed to be relative the current working directory.
+              </item>
+              <item>The special <c>$ROOT</c> variable can only be used
+               in the script, not as a command line argument. The
+               given directory is relative the Erlang installation
+               directory.
+              </item>
+            </list>
+          </item>
+        </list>
+      </item>
+      <item><c>{primLoad, [Mod]}</c> loads the modules <c>[Mod]</c>
+       from the directories specified in <c>Path</c>.  The script
+       interpreter fetches the appropriate module by calling the
+       function <c>erl_prim_loader:get_file(Mod)</c>.  A fatal error
+       which terminates the system will occur if the module cannot be
+       located.
+      </item>
+      <item><c>{kernel_load_completed}</c> indicates that all modules
+       which <em>must</em> be loaded <em>before</em> any processes
+       are started are loaded. In interactive mode, all
+      <c>{primLoad,[Mod]}</c> commands interpreted after this
+       command are ignored, and these modules are loaded on demand.
+       In embedded mode, <c>kernel_load_completed</c> is ignored, and
+       all modules are loaded during system start.
+      </item>
+      <item><c>{kernelProcess, Name, {Mod, Func, Args}}</c> starts a
+       "kernel process".  The kernel process <c>Name</c> is started
+       by evaluating <c>apply(Mod, Func, Args)</c> which is expected
+       to return <c>{ok, Pid}</c> or <c>ignore</c>.  The <c>init</c>
+       process monitors the behaviour of <c>Pid</c> and terminates
+       the system if <c>Pid</c> dies.  Kernel processes are key
+       components of the runtime system.  Users do not normally add
+       new kernel processes.
+      </item>
+      <item><c>{apply, {Mod, Func, Args}}</c>. The init process simply
+       evaluates <c>apply(Mod, Func, Args)</c>.  The system
+       terminates if this results in an error.  The boot procedure
+       hangs if this function never returns.
+      </item>
+    </list>
+    <note>
+      <p>In the <c>interactive</c> system the code loader provides
+        demand driven code loading, but in the <c>embedded</c> system
+        the code loader loads all the code immediately.  The same
+        version of <c>code</c> is used in both cases.  The code server
+        calls <c>init:get_argument(mode)</c> to find out if it should
+        run in demand mode, or non-demand driven mode.
+        </p>
+    </note>
+  </section>
+
+  <section>
+    <title>SEE ALSO</title>
+    <p>systools(3)
+      </p>
+  </section>
+</fileref>
+