The R13B03 release.OTP_R13B03

1 files changed, 249 insertions, 0 deletions

diff --git a/system/doc/embedded/starting.xml b/system/doc/embedded/starting.xml
new file mode 100644
index 0000000000..ddeaeb8bdf
--- /dev/null
+++ b/system/doc/embedded/starting.xml
@@ -0,0 +1,249 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE chapter SYSTEM "chapter.dtd">
+
+<chapter>
+  <header>
+    <copyright>
+      <year>1996</year><year>2009</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.
+    
+    </legalnotice>
+
+    <title>Starting an Embedded System</title>
+    <prepared>Martin Bj&ouml;rklund</prepared>
+    <responsible>Bjarne D&auml;cker</responsible>
+    <docno></docno>
+    <approved>Bjarne D&auml;cker</approved>
+    <checked></checked>
+    <date>1997-10-17</date>
+    <rev>D</rev>
+    <file>starting.sgml</file>
+  </header>
+
+  <section>
+    <title>Introduction</title>
+    <p>This chapter describes how an embedded system is started.
+      There are four programs involved, and they all normally reside
+      in the directory <c><![CDATA[<ERL_INSTALL_DIR>/bin]]></c>.  The only
+      exception is the program <c>start</c>, which may be located
+      anywhere, and also is the only program that must be modified by
+      the user.
+      </p>
+    <p>In an embedded system there usually is no interactive shell.
+      However, it is possible for an operator to attach to the
+      Erlang runtime system by giving the command <c>to_erl</c>.  He is
+      then connected to the Erlang shell, and may give ordinary Erlang
+      commands.  All interaction with the system through this shell is
+      logged in a special directory.
+      </p>
+    <p>Basically, the procedure is as follows.  The program
+      <c>start</c> is called when the machine is started.  It calls
+      <c>run_erl</c>, which sets things up so the operator can attach
+      to the system.  It calls <c>start_erl</c> which calls the
+      correct version of <c>erlexec</c> (which is located in
+      <c><![CDATA[<ERL_INSTALL_DIR>/erts-EVsn/bin]]></c>) with the correct
+      <c>boot</c> and <c>config</c> files.
+      </p>
+  </section>
+
+  <section>
+    <title>Programs</title>
+
+    <section>
+      <title>start</title>
+      <p>This program is called when the machine is started.  It may
+        be modified or re-written to suit a special system.  By
+        default, it must be called <c>start</c> and reside in
+        <c><![CDATA[<ERL_INSTALL_DIR>/bin]]></c>.  Another start program can be
+        used, by using the configuration parameter <c>start_prg</c> in
+        the application <c>sasl</c>.</p>
+      <p>The start program must call <c>run_erl</c> as shown below.
+        It must also take an optional parameter which defaults to
+        <c><![CDATA[<ERL_INSTALL_DIR>/bin/start_erl.data]]></c>.
+        </p>
+      <p>This program should set static parameters and environment
+        variables such as <c>-sname Name</c> and <c>HEART_COMMAND</c>
+        to reboot the machine.
+        </p>
+      <p>The <c><![CDATA[<RELDIR>]]></c> directory is where new release packets
+        are installed, and where the release handler keeps information
+        about releases.  See <c>release_handler(3)</c> in the
+        application <c>sasl</c> for further information.
+        </p>
+      <p>The following script illustrates the default behaviour of the
+        program.
+        </p>
+      <code type="none"><![CDATA[
+#!/bin/sh
+# Usage: start [DataFile]
+#
+ROOTDIR=/usr/local/otp
+
+if [ -z "$RELDIR" ]
+then
+   RELDIR=$ROOTDIR/releases
+fi
+
+START_ERL_DATA=${1:-$RELDIR/start_erl.data}
+
+$ROOTDIR/bin/run_erl /tmp/ $ROOTDIR/log "exec $ROOTDIR/bin/start_erl @@@
+                     $ROOTDIR $RELDIR $START_ERL_DATA" > /dev/null 2>&1 &]]></code>
+      <p>The following script illustrates a modification where the
+        node is given the name <c>cp1</c>, and the environment variables
+        <c>HEART_COMMAND</c> and <c>TERM</c> have been added to the
+        above script.
+        </p>
+      <code type="none"><![CDATA[
+#!/bin/sh
+# Usage: start [DataFile]
+#
+HEART_COMMAND=/usr/sbin/reboot
+TERM=sun
+export HEART_COMMAND TERM
+
+ROOTDIR=/usr/local/otp
+
+if [ -z "$RELDIR" ]
+then
+   RELDIR=$ROOTDIR/releases
+fi
+
+START_ERL_DATA=${1:-$RELDIR/start_erl.data}
+
+$ROOTDIR/bin/run_erl /tmp/ $ROOTDIR/log "exec $ROOTDIR/bin/start_erl @@@
+      $ROOTDIR $RELDIR $START_ERL_DATA -heart -sname cp1" > /dev/null 2>&1 &]]></code>
+      <p>If a diskless and/or read-only client node is about to start the
+        <c>start_erl.data</c> file is located in the client directory at
+        the master node. Thus, the <c>START_ERL_DATA</c> line should look
+        like:
+        </p>
+      <code type="none">
+CLIENTDIR=$ROOTDIR/clients/clientname
+START_ERL_DATA=${1:-$CLIENTDIR/bin/start_erl.data}</code>
+    </section>
+
+    <section>
+      <title>run_erl</title>
+      <p>This program is used to start the emulator, but you will not
+        be connected to the shell. <c>to_erl</c> is used to connect to the
+        Erlang shell.
+        </p>
+      <code type="none">
+Usage: run_erl pipe_dir/ log_dir "exec command [parameters ...]"</code>
+      <p>Where <c>pipe_dir/</c> should be <c>/tmp/</c>
+        (<c>to_erl</c> uses this name by default) and <c>log_dir</c> is
+        where the log files are written.  <c>command [parameters]</c> is
+        executed, and everything written to stdin and stdout is logged in
+        the <c>log_dir</c>.
+        </p>
+      <p>In the <c>log_dir</c>, log files are written.  Each logfile
+        has a name of the form: <c>erlang.log.N</c> where N is a
+        generation number, ranging from 1 to 5. Each logfile holds up to
+        100kB text. As time goes by the following logfiles will be found
+        in the logfile directory</p>
+      <code type="none">
+erlang.log.1
+erlang.log.1, erlang.log.2
+erlang.log.1, erlang.log.2, erlang.log.3
+erlang.log.1, erlang.log.2, erlang.log.3, erlang.log.4
+erlang.log.2, erlang.log.3, erlang.log.4, erlang.log.5
+erlang.log.3, erlang.log.4, erlang.log.5, erlang.log.1
+...      </code>
+      <p>with the most recent logfile being the right most in each row
+        of the above list. That is, the most recent file is the one with
+        the highest number, or if there are already four files, the one
+        before the skip. 
+        </p>
+      <p>When a logfile is opened (for appending or created) a time
+        stamp is written to the file.  If nothing has been written to
+        the log files for 15 minutes, a record is inserted that says
+        that we're still alive.
+        </p>
+    </section>
+
+    <section>
+      <title>to_erl</title>
+      <p>This program is used to attach to a running Erlang runtime system,
+        started with <c>run_erl</c>.
+        </p>
+      <code type="none">
+Usage: to_erl [pipe_name | pipe_dir]</code>
+      <p>Where <c>pipe_name</c> defaults to <c>/tmp/erlang.pipe.N</c>.
+        </p>
+      <p>To disconnect from the shell without exiting the Erlang
+        runtime system, type <c>Ctrl-D</c>.
+        </p>
+    </section>
+
+    <section>
+      <title>start_erl</title>
+      <p>This program starts the Erlang emulator with parameters
+        <c>-boot</c> and <c>-config</c> set.  It reads data about where
+        these files are located from a file called <c>start_erl.data</c>
+        which is located in the <c><![CDATA[<RELDIR>]]></c>.  Each new release
+        introduces a new data file.  This file is automatically
+        generated by the release handler in Erlang.
+        </p>
+      <p>The following script illustrates the behaviour of the
+        program.</p>
+      <code type="none">
+#!/bin/sh
+#
+# This program is called by run_erl.  It starts
+# the Erlang emulator and sets -boot and -config parameters.
+# It should only be used at an embedded target system.
+#
+# Usage: start_erl RootDir RelDir DataFile [ErlFlags ...]
+#
+ROOTDIR=$1
+shift
+RELDIR=$1
+shift
+DataFile=$1
+shift
+
+ERTS_VSN=`awk '{print $1}' $DataFile`
+VSN=`awk '{print $2}' $DataFile`
+
+BINDIR=$ROOTDIR/erts-$ERTS_VSN/bin
+EMU=beam
+PROGNAME=`echo $0 | sed 's/.*\\///'`
+export EMU
+export ROOTDIR
+export BINDIR
+export PROGNAME
+export RELDIR
+
+exec $BINDIR/erlexec -boot $RELDIR/$VSN/start -config $RELDIR/$VSN/sys $*      </code>
+      <p>If a diskless and/or read-only client node with the <c>sasl</c>
+        configuration parameter <c>static_emulator</c> set to <c>true</c>
+        is about to start the <c>-boot</c> and <c>-config</c> flags must be
+        changed. As such a client can not read a new <c>start_erl.data</c>
+        file (the file is not possible to change dynamically) the boot and
+        config files is always fetched from the same place (but with a new 
+        contents if a new release has been installed). The
+        <c>release_handler</c> copies this files to the <c>bin</c> directory
+        in the client directory at the master nodes whenever a new release
+        is made permanent.
+        </p>
+      <p>Assuming the same <c>CLIENTDIR</c> as above the last line should
+        look like:</p>
+      <code type="none">
+exec $BINDIR/erlexec -boot $CLIENTDIR/bin/start @@@
+     -config $CLIENTDIR/bin/sys $*      </code>
+    </section>
+  </section>
+</chapter>
+