diff options
Diffstat (limited to 'erts/doc/src/escript.xml')
| -rw-r--r-- | erts/doc/src/escript.xml | 232 |
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> + |