<?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>

