The R13B03 release.OTP_R13B03

1 files changed, 126 insertions, 0 deletions

diff --git a/erts/doc/src/start_erl.xml b/erts/doc/src/start_erl.xml
new file mode 100644
index 0000000000..21cc901f52
--- /dev/null
+++ b/erts/doc/src/start_erl.xml
@@ -0,0 +1,126 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE comref SYSTEM "comref.dtd">
+
+<comref>
+  <header>
+    <copyright>
+      <year>1998</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>start_erl</title>
+    <prepared>Patrik Nyblom</prepared>
+    <responsible></responsible>
+    <docno></docno>
+    <approved></approved>
+    <checked></checked>
+    <date>98-08-05</date>
+    <rev></rev>
+    <file>start_erl.xml</file>
+  </header>
+  <com>start_erl</com>
+  <comsummary>Start Erlang for embedded systems on Windows NT&reg;</comsummary>
+  <description>
+    <p>This describes the <c><![CDATA[start_erl]]></c> program specific to Windows
+      NT. Although there exists programs with the same name on other
+      platforms, their functionality is not the same.</p>
+    <p>The <c><![CDATA[start_erl]]></c> program is distributed both in compiled
+      form (under &lt;Erlang root&gt;\\erts-&lt;version&gt;\\bin) and
+      in source form (under &lt;Erlang
+      root&gt;\\erts-&lt;version&gt;\\src).
+      The purpose of the source code is to make it possible to easily
+      customize the program for local needs, such as cyclic restart
+      detection etc. There is also a "make"-file, written for the
+      <c><![CDATA[nmake]]></c> program distributed with Microsoft&reg; Visual
+      C++&reg;. The program can however be compiled with
+      any Win32 C compiler (possibly with slight modifications).</p>
+    <p>The purpose of the program is to aid release handling on
+      Windows NT&reg;. The program should be called by the
+      <c><![CDATA[erlsrv]]></c> program, read up the release data file
+      start_erl.data and start Erlang. Certain options to start_erl
+      are added and removed by the release handler during upgrade with
+      emulator restart (more specifically the <c><![CDATA[-data]]></c> option).</p>
+  </description>
+  <funcs>
+    <func>
+      <name>start_erl [&lt;erl options>] ++ [&lt;start_erl options>]</name>
+      <fsummary>Start the Erlang emulator with the correct release data</fsummary>
+      <desc>
+        <p>The <c><![CDATA[start_erl]]></c> program  in its original form 
+          recognizes the following options:</p>
+        <taglist>
+          <tag>++</tag>
+          <item>Mandatory, delimits start_erl options from normal Erlang
+           options. Everything on the command line <em>before</em> the
+          <c><![CDATA[++]]></c> is interpreted as options to be sent to the
+          <c><![CDATA[erl]]></c> program. Everything <em>after</em><c><![CDATA[++]]></c> is
+           interpreted as options to <c><![CDATA[start_erl]]></c> itself.</item>
+          <tag>-reldir &lt;release root&gt;</tag>
+          <item>Mandatory if the environment variable <c><![CDATA[RELDIR]]></c> is not
+           specified. Tells start_erl where the root of the
+           release tree is placed in the file-system 
+           (like &lt;Erlang root&gt;\\releases). The
+          <c><![CDATA[start_erl.data]]></c> file is expected to be placed in
+           this directory (if not otherwise specified).</item>
+          <tag>-data &lt;data file name&gt;</tag>
+          <item>Optional, specifies another data file than start_erl.data
+           in the &lt;release root&gt;. It is specified relative to the
+           &lt;release root&gt; or absolute (including drive letter
+           etc.). This option is used by the release handler during
+           upgrade and should not be used during normal
+           operation. The release data file should not normally be
+           named differently.</item>
+          <tag>-bootflags &lt;boot flags file name&gt;</tag>
+          <item>Optional, specifies a file name relative to actual release
+           directory (that is the subdirectory of &lt;release
+           root&gt; where the <c><![CDATA[.boot]]></c> file etc. are placed).
+           The contents of this file is appended to the command line
+           when Erlang is started. This makes it easy to start the
+           emulator with different options for different releases.</item>
+        </taglist>
+      </desc>
+    </func>
+  </funcs>
+
+  <section>
+    <title>NOTES</title>
+    <p>As the source code is distributed, it can easily be modified to
+      accept other options. The program must still accept the
+      <c><![CDATA[-data]]></c> option with the semantics described above for the
+      release handler to work correctly.</p>
+    <p>The Erlang emulator is found by examining the registry keys for
+      the emulator version specified in the release data file. The new
+      emulator needs to be properly installed before the upgrade for
+      this to work.</p>
+    <p>Although the program is located together with files specific to
+      emulator version, it is not expected to be specific to the
+      emulator version. The release handler does <em>not</em> change the
+      <c><![CDATA[-machine]]></c> option to <c><![CDATA[erlsrv]]></c> during emulator restart.
+      Place the (possibly customized) <c><![CDATA[start_erl]]></c> program so that
+      it is not overwritten during upgrade. </p>
+    <p>The <c><![CDATA[erlsrv]]></c> program's default options are not
+      sufficient for release handling. The machine <c><![CDATA[erlsrv]]></c>
+      starts should be specified as the <c><![CDATA[start_erl]]></c> program and
+      the arguments should contain the <c><![CDATA[++]]></c> followed by desired
+      options.</p>
+  </section>
+
+  <section>
+    <title>SEE ALSO</title>
+    <p>erlsrv(1), release_handler(3)</p>
+  </section>
+</comref>
+