The R13B03 release.OTP_R13B03

1 files changed, 232 insertions, 0 deletions

diff --git a/erts/doc/src/escript.xml b/erts/doc/src/escript.xml
new file mode 100644
index 0000000000..8df179b3e2
--- /dev/null
+++ b/erts/doc/src/escript.xml
@@ -0,0 +1,232 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE comref SYSTEM "comref.dtd">
+
+<comref>
+  <header>
+    <copyright>
+      <year>2007</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>escript</title>
+    <prepared></prepared>
+    <docno></docno>
+    <date></date>
+    <rev></rev>
+    <file>escript.xml</file>
+  </header>
+  <com>escript</com>
+  <comsummary>Erlang scripting support</comsummary>
+  <description>
+    <p><c><![CDATA[escript]]></c> provides support for running short Erlang programs
+      without having to compile them first and an easy way to retrieve the
+      command line arguments.</p>
+  </description>
+  <funcs>
+    <func>
+      <name>script-name script-arg1 script-arg2...</name>
+      <name>escript escript-flags script-name script-arg1 script-arg2...</name>
+      <fsummary>Run a script written in Erlang</fsummary>
+      <desc>
+        <p><c><![CDATA[escript]]></c> runs a script written in Erlang.</p>
+        <p>Here follows an example.</p>
+        <pre>
+$ <input>cat factorial</input>        
+#!/usr/bin/env escript
+%% -*- erlang -*-
+%%! -smp enable -sname factorial -mnesia debug verbose
+main([String]) ->
+    try
+\011N = list_to_integer(String),
+\011F = fac(N),
+\011io:format("factorial ~w = ~w\
+", [N,F])
+    catch
+\011_:_ ->
+\011    usage()
+    end;
+main(_) ->
+    usage().
+        
+usage() ->
+    io:format("usage: factorial integer\
+"),
+    halt(1).
+        
+fac(0) -> 1;
+fac(N) -> N * fac(N-1).
+$ <input>factorial 5</input>
+factorial 5 = 120
+$ <input>factorial</input>
+usage: factorial integer
+$ <input>factorial five</input>
+usage: factorial integer        </pre>
+        <p>The header of the Erlang script in the example differs from
+        a normal Erlang module.  The first line is intended to be the
+        interpreter line, which invokes
+        <c><![CDATA[escript]]></c>. However if you invoke the
+        <c><![CDATA[escript]]></c> like this</p>
+        <pre>
+$ <input>escript factorial 5</input>        </pre>
+        <p>the contents of the first line does not matter, but it
+        cannot contain Erlang code as it will be ignored.</p>
+        <p>The second line in the example, contains an optional
+          directive to the <c>Emacs</c> editor which causes it to
+          enter the major mode for editing Erlang source files. If the
+          directive is present it must be located on the second
+          line.</p>
+	<p>On the third line (or second line depending on the presence
+          of the Emacs directive), it is possible to give arguments to
+          the emulator, such as </p>
+        <pre>
+%%! -smp enable -sname factorial -mnesia debug verbose</pre>
+        <p>Such an argument line must start with <c>%%!</c> and the
+          rest of the line will interpreted as arguments to the emulator.</p>
+        <p>If you know the location of the <c><![CDATA[escript]]></c> executable, the first
+          line can directly give the path to <c><![CDATA[escript]]></c>. For instance:</p>
+        <pre>
+#!/usr/local/bin/escript        </pre>
+        <p>As any other kind of scripts, Erlang scripts will not work on
+          Unix platforms if the execution bit for the script file is not set.
+          (Use <c><![CDATA[chmod +x script-name]]></c> to turn on the execution bit.)
+          </p>
+
+        <p>The rest of the Erlang script file may either contain
+        Erlang <c>source code</c>, an <c>inlined beam file</c> or an
+        <c>inlined archive file</c>.</p>
+
+        <p>An Erlang script file must always contain the function
+        <em>main/1</em>.  When the script is run, the
+        <c><![CDATA[main/1]]></c> function will be called with a list
+        of strings representing the arguments given to the script (not
+        changed or interpreted in any way).</p>
+
+        <p>If the <c><![CDATA[main/1]]></c> function in the script returns successfully,
+          the exit status for the script will be 0. If an exception is generated
+          during execution, a short message will be printed and the script terminated
+          with exit status 127.</p>
+
+        <p>To return your own non-zero exit code, call <c><![CDATA[halt(ExitCode)]]></c>;
+          for instance:</p>
+        <pre>
+halt(1).</pre>
+
+        <p>Call <c><![CDATA[escript:script_name/0]]></c> from your to
+          script to retrieve the pathname of the script (the pathname
+          is usually, but not always, absolute).</p>
+
+        <p>If the file contains source code (as in the example above),
+          it will be processed by the preprocessor <c>epp</c>. This
+          means that you for example may use pre-defined macros (such as
+          <c><![CDATA[?MODULE]]></c>) as well as include directives like
+          the <c><![CDATA[-include_lib]]></c> directive. For instance, use</p>
+        <pre>
+-include_lib("kernel/include/file.hrl").        </pre>
+        <p>to include the record definitions for the records used by the
+          <c><![CDATA[file:read_link_info/1]]></c> function.</p>
+
+        <p>The script will be checked for syntactic and semantic
+          correctness before being run. If there are warnings (such as
+          unused variables), they will be printed and the script will
+          still be run. If there are errors, they will be printed and
+          the script will not be run and its exit status will be
+          127.</p>
+
+        <p>Both the module declaration and the export declaration of
+          the <c><![CDATA[main/1]]></c> function are optional.</p>
+
+        <p>By default, the script will be interpreted. You can force
+          it to be compiled by including the following line somewhere
+          in the script file:</p><pre>
+-mode(compile).</pre>
+
+        <p>Execution of interpreted code is slower than compiled code.
+          If much of the execution takes place in interpreted code it
+          may be worthwhile to compile it, even though the compilation
+          itself will take a little while.</p>
+
+        <p>As mentioned earlier, it is possible to have a script which
+          contains precompiled <c>beam</c> code. In a precompiled
+          script, the interpretation of the script header is exactly
+          the same as in a script containing source code. That means
+          that you can make a <c>beam</c> file executable by
+          prepending the file with the lines starting with <c>#!</c>
+          and <c>%%!</c> mentioned above. In a precompiled script, the
+          function
+          <c>main/1</c> must be exported.</p>
+
+        <p>As yet another option it is possible to have an entire
+          Erlang archive in the script. In a archive script, the
+          interpretation of the script header is exactly the same as
+          in a script containing source code. That means that you can
+          make an archive file executable by prepending the file with
+          the lines starting with <c>#!</c> and <c>%%!</c> mentioned
+          above. In an archive script, the function <c>main/1</c> must
+          be exported. By default the <c>main/1</c> function in the
+          module with the same name as the basename of the
+          <c>escript</c> file will be invoked. This behavior can be
+          overridden by setting the flag <c>-escript main Module</c>
+          as one of the emulator flags. The <c>Module</c> must be the
+          name of a module which has an exported <c>main/1</c>
+          function. See <seealso marker="kernel:code">code(3)</seealso>
+          for more information about archives and code loading.</p>
+
+	  <p>In many cases it is very convenient to have a header in
+	  the escript, especially on Unix platforms. But the header is
+	  in fact optional. This means that you directly can "execute"
+	  an Erlang module, beam file or archive file without adding
+	  any header to them. But then you have to invoke the script
+	  like this:</p>
+	  <pre>
+$ <input>escript factorial.erl 5</input>
+factorial 5 = 120
+$ <input>escript factorial.beam 5</input>
+factorial 5 = 120
+$ <input>escript factorial.zip 5</input>
+factorial 5 = 120
+</pre>
+      </desc>
+    </func>
+  </funcs>
+
+  <section>
+    <title>Options accepted by escript</title>
+    <taglist>
+      <tag>-c</tag>
+      <item>Compile the escript regardless of the value of the mode attribute.
+      </item>
+
+      <tag>-d</tag>
+      <item>Debug the escript. Starts the debugger, loads the module
+      containing the <c>main/1</c> function into the debugger, sets a
+      breakpoint in <c>main/1</c> and invokes <c>main/1</c>. If the
+      module is precompiled, it must be explicitly compiled with the
+      <c>debug_info</c> option.
+      </item>
+
+      <tag>-i</tag>
+      <item>Interpret the escript regardless of the value of the mode attribute.
+      </item>
+
+      <tag>-s</tag>
+      <item>Only perform a syntactic and semantic check of the script file.
+       Warnings and errors (if any) are written to the standard output, but
+       the script will not be run. The exit status will be 0 if there were
+       no errors, and 127 otherwise.</item>
+    </taglist>
+  </section>
+</comref>
+