aboutsummaryrefslogtreecommitdiffstats
path: root/erts/doc/src/escript.xml
diff options
context:
space:
mode:
authorErlang/OTP <[email protected]>2009-11-20 14:54:40 +0000
committerErlang/OTP <[email protected]>2009-11-20 14:54:40 +0000
commit84adefa331c4159d432d22840663c38f155cd4c1 (patch)
treebff9a9c66adda4df2106dfd0e5c053ab182a12bd /erts/doc/src/escript.xml
downloadotp-84adefa331c4159d432d22840663c38f155cd4c1.tar.gz
otp-84adefa331c4159d432d22840663c38f155cd4c1.tar.bz2
otp-84adefa331c4159d432d22840663c38f155cd4c1.zip
The R13B03 release.OTP_R13B03
Diffstat (limited to 'erts/doc/src/escript.xml')
-rw-r--r--erts/doc/src/escript.xml232
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>
+