<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE fileref SYSTEM "fileref.dtd">

<fileref>
  <header>
    <copyright>
      <year>1997</year>
      <year>2016</year>
      <holder>Ericsson AB, All Rights Reserved</holder>
    </copyright>
    <legalnotice>
  Licensed under the Apache License, Version 2.0 (the "License");
  you may not use this file except in compliance with the License.
  You may obtain a copy of the License at
 
      http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing, software
  distributed under the License is distributed on an "AS IS" BASIS,
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  See the License for the specific language governing permissions 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>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 
    <seealso marker="systools#script2boot/1"><c>systools:script2boot/1</c></seealso>.</p>
    <p>The <c>.script</c> file is generated by <c>systools</c> from a
      <c>.rel</c> file and from <c>.app</c> files.</p>
  </description>

  <section>
    <title>File Syntax</title>
    <p>The boot script is stored in a file with extension
      <c>.script</c>. 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>
    <taglist>
      <tag><c>Name = string()</c></tag>
        <item><p>Defines the system name.</p></item>
      <tag><c>Vsn = string()</c></tag>
        <item><p>Defines the system version.</p></item>
      <tag><c>{progress, Term}</c></tag>
        <item><p>Sets the "progress" of the initialization
	  program. The
          <seealso marker="erts:init#get_status/0"><c>init:get_status/0</c></seealso>
	  function returns the current value of the progress, which is
      <c>{InternalStatus,Term}</c>.</p></item>
      <tag><c>{path, [Dir]}</c></tag>
        <item><p><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 that 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>DirN, DirN-1, ..., Dir2, Dir1</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 replace
              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>
      <tag><c>{primLoad, [Mod]}</c></tag>
        <item><p>Loads the modules <c>[Mod]</c>
        from the directories specified in <c>Path</c>. The script
        interpreter fetches the appropriate module by calling
        <seealso marker="erts:erl_prim_loader#get_file/1">
	  <c>erl_prim_loader:get_file(Mod)</c></seealso>. A fatal error
        that terminates the system occurs if the module cannot be
        located.</p></item>
      <tag><c>{kernel_load_completed}</c></tag>
        <item><p>Indicates that all modules
        that <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.</p></item>
      <tag><c>{kernelProcess, Name, {Mod, Func, Args}}</c></tag>
        <item><p>Starts the
        "kernel process" <c>Name</c>
        by evaluating <c>apply(Mod, Func, Args)</c>. The start function is
        to return <c>{ok, Pid}</c> or <c>ignore</c>. The <c>init</c>
        process monitors the behavior 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.</p></item>
      <tag><c>{apply, {Mod, Func, Args}}</c>.</tag>
        <item><p>The init process
        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.</p></item>
    </taglist>
    <note>
      <p>In an interactive system, the code loader provides
        demand-driven code loading, but in an embedded system
        the code loader loads all code immediately. The same
        version of <seealso marker="kernel:code"><c>code</c></seealso>
	is used in both cases. The code server calls
	<seealso marker="erts:init#get_argument/1"><c>init:get_argument(mode)</c></seealso>
	to determine if it is to run in demand mode or non-demand
        driven mode.</p>
    </note>
  </section>

  <section>
    <title>See Also</title>
    <p><seealso marker="systools"><c>systools(3)</c></seealso></p>
  </section>
</fileref>

