From 84adefa331c4159d432d22840663c38f155cd4c1 Mon Sep 17 00:00:00 2001 From: Erlang/OTP Date: Fri, 20 Nov 2009 14:54:40 +0000 Subject: The R13B03 release. --- erts/doc/src/escript.xml | 232 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 232 insertions(+) create mode 100644 erts/doc/src/escript.xml (limited to 'erts/doc/src/escript.xml') 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 @@ + + + + +
+ + 20072009 + Ericsson AB. All Rights Reserved. + + + 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. + + + + escript + + + + + escript.xml +
+ escript + Erlang scripting support + +

provides support for running short Erlang programs + without having to compile them first and an easy way to retrieve the + command line arguments.

+ + + + script-name script-arg1 script-arg2... + escript escript-flags script-name script-arg1 script-arg2... + Run a script written in Erlang + +

runs a script written in Erlang.

+

Here follows an example.

+ 
+$ cat factorial        
+#!/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).
+$ factorial 5
+factorial 5 = 120
+$ factorial
+usage: factorial integer
+$ factorial five
+usage: factorial integer
+

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 + . However if you invoke the + like this

+ 
+$ escript factorial 5
+

the contents of the first line does not matter, but it + cannot contain Erlang code as it will be ignored.

+

The second line in the example, contains an optional + directive to the Emacs 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.

+

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

+ 
+%%! -smp enable -sname factorial -mnesia debug verbose
+

Such an argument line must start with %%! and the + rest of the line will interpreted as arguments to the emulator.

+

If you know the location of the executable, the first + line can directly give the path to . For instance:

+ 
+#!/usr/local/bin/escript
+

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 to turn on the execution bit.) +

+ +

The rest of the Erlang script file may either contain + Erlang source code, an inlined beam file or an + inlined archive file.

+ +

An Erlang script file must always contain the function + main/1. When the script is run, the + function will be called with a list + of strings representing the arguments given to the script (not + changed or interpreted in any way).

+ +

If the 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.

+ +

To return your own non-zero exit code, call ; + for instance:

+ 
+halt(1).
+ +

Call from your to + script to retrieve the pathname of the script (the pathname + is usually, but not always, absolute).

+ +

If the file contains source code (as in the example above), + it will be processed by the preprocessor epp. This + means that you for example may use pre-defined macros (such as + ) as well as include directives like + the directive. For instance, use

+ 
+-include_lib("kernel/include/file.hrl").
+

to include the record definitions for the records used by the + function.

+ +

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.

+ +

Both the module declaration and the export declaration of + the function are optional.

+ +

By default, the script will be interpreted. You can force + it to be compiled by including the following line somewhere + in the script file:

+-mode(compile).
+ +

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.

+ +

As mentioned earlier, it is possible to have a script which + contains precompiled beam 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 beam file executable by + prepending the file with the lines starting with #! + and %%! mentioned above. In a precompiled script, the + function + main/1 must be exported.

+ +

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 #! and %%! mentioned + above. In an archive script, the function main/1 must + be exported. By default the main/1 function in the + module with the same name as the basename of the + escript file will be invoked. This behavior can be + overridden by setting the flag -escript main Module + as one of the emulator flags. The Module must be the + name of a module which has an exported main/1 + function. See code(3) + for more information about archives and code loading.

+ +

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:

+ 
+$ escript factorial.erl 5
+factorial 5 = 120
+$ escript factorial.beam 5
+factorial 5 = 120
+$ escript factorial.zip 5
+factorial 5 = 120
+
+ + + + +
+ Options accepted by escript + + -c + Compile the escript regardless of the value of the mode attribute. + + + -d + Debug the escript. Starts the debugger, loads the module + containing the main/1 function into the debugger, sets a + breakpoint in main/1 and invokes main/1. If the + module is precompiled, it must be explicitly compiled with the + debug_info option. + + + -i + Interpret the escript regardless of the value of the mode attribute. + + + -s + 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. + +
+ + -- cgit v1.2.3