aboutsummaryrefslogtreecommitdiffstats
path: root/erts/doc/src/escript.xml
diff options
context:
space:
mode:
Diffstat (limited to 'erts/doc/src/escript.xml')
-rw-r--r--erts/doc/src/escript.xml400
1 files changed, 192 insertions, 208 deletions
diff --git a/erts/doc/src/escript.xml b/erts/doc/src/escript.xml
index f12f76890c..1d5d280338 100644
--- a/erts/doc/src/escript.xml
+++ b/erts/doc/src/escript.xml
@@ -4,7 +4,7 @@
<comref>
<header>
<copyright>
- <year>2007</year><year>2015</year>
+ <year>2007</year><year>2016</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
@@ -33,17 +33,18 @@
<comsummary>Erlang scripting support</comsummary>
<description>
<p><c>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>
+ 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>
+ <fsummary>Run a script written in Erlang.</fsummary>
<desc>
<p><c>escript</c> runs a script written in Erlang.</p>
- <p>Here follows an example.</p>
+ <p>Example:</p>
<pre>
$ <input>chmod u+x factorial</input>
$ <input>cat factorial</input>
@@ -73,195 +74,183 @@ factorial 5 = 120
$ <input>./factorial</input>
usage: factorial integer
$ <input>./factorial five</input>
-usage: factorial integer
- </pre>
+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>escript</c>. However if you
- invoke the <c>escript</c> like this</p>
+ a normal Erlang module. The first line is intended to be the
+ interpreter line, which invokes <c>escript</c>.</p>
+ <p>However, if you invoke the <c>escript</c> as follows,
+ the contents of the first line does not matter, but it
+ cannot contain Erlang code as it will be ignored:</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
+$ <input>escript factorial 5</input></pre>
+ <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
+ directive is present, it must be located on the second
line.</p>
-
- <p>If there is a comment selecting the <seealso
- marker="stdlib:epp#encoding">encoding</seealso> it can be
+ <p>If a comment selecting the <seealso
+ marker="stdlib:epp#encoding">encoding</seealso> exists, it can be
located on the second line.</p>
-
- <note><p>
- The encoding specified by the above mentioned comment
- applies to the script itself. The encoding of the
- I/O-server, however, has to be set explicitly like this:</p>
-<code>io:setopts([{encoding, unicode}])</code>
+ <note>
+ <p>The encoding specified by the above mentioned comment
+ applies to the script itself. The encoding of the
+ I/O-server, however, must be set explicitly as follows:</p>
+ <code>
+io:setopts([{encoding, unicode}])</code>
<p>The default encoding of the I/O-server for <c>standard_io</c>
- is <c>latin1</c>
- since the script runs in a non-interactive terminal
- (see <seealso marker="stdlib:unicode_usage#unicode_options_summary">
- Using Unicode in Erlang</seealso>).
- </p></note>
-
- <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>
+ is <c>latin1</c>, as the script runs in a non-interactive terminal
+ (see section
+ <seealso marker="stdlib:unicode_usage#unicode_options_summary">
+ Summary of Options</seealso>) in the STDLIB User's Guide.</p>
+ </note>
+ <p>On the third line (or second line depending on the presence
+ of the Emacs directive), arguments can be specified to
+ the emulator, for example:</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>
+ remaining line is interpreted as arguments to the emulator.</p>
<p>If you know the location of the <c>escript</c> executable, the first
- line can directly give the path to <c>escript</c>. For instance:</p>
+ line can directly give the path to <c>escript</c>, for example:</p>
<pre>
-#!/usr/local/bin/escript </pre>
- <p>As any other kind of scripts, Erlang scripts will not work on
+#!/usr/local/bin/escript</pre>
+ <p>As any other type of scripts, Erlang scripts do not work on
Unix platforms if the execution bit for the script file is not set.
- (Use <c>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>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>
-
+ (To turn on the execution bit, use <c>chmod +x script-name</c>.)</p>
+ <p>The remaining Erlang script file can either contain
+ Erlang <em>source code</em>, an <em>inlined beam file</em>, or an
+ <em>inlined archive file</em>.</p>
+ <p>An Erlang script file must always contain the <c>main/1</c>
+ function. When the script is run, the
+ <c>main/1</c> function is called with a list
+ of strings representing the arguments specified to the script (not
+ changed or interpreted in any way).</p>
<p>If the <c>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>halt(ExitCode)</c>;
- for instance:</p>
+ the exit status for the script is <c>0</c>. If an exception is
+ generated during execution, a short message is printed and the script
+ terminates with exit status <c>127</c>.</p>
+ <p>To return your own non-zero exit code, call <c>halt(ExitCode)</c>,
+ for example:</p>
<pre>
halt(1).</pre>
-
- <p>Call <seealso marker="#script_name_0">escript:script_name()</seealso>
- from your to script to retrieve the pathname of the script
- (the pathname is usually, but not always, absolute).</p>
-
+ <p>To retrieve the pathname of the script, call
+ <seealso marker="#script_name_0">
+ <c>escript:script_name()</c></seealso> from your 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>?MODULE</c>) as well as include directives like
- the <c>-include_lib</c> directive. For instance, use</p>
+ it is processed by the
+ <seealso marker="stdlib:epp"><c>epp</c></seealso> preprocessor.
+ This means that you, for example, can use predefined macros
+ (such as <c>?MODULE</c>) and include directives like
+ the <c>-include_lib</c> directive. For example, use</p>
<pre>
-include_lib("kernel/include/file.hrl").</pre>
- <p>to include the record definitions for the records used by the
- <c>file:read_link_info/1</c> function. You can also select
- encoding by including a encoding comment here, but if there
- is a valid encoding comment on the second line it takes
+ <p>to include the record definitions for the records used by function
+ <seealso marker="kernel:file#read_link_info/1">
+ <c>file:read_link_info/1</c></seealso>. You can also select
+ encoding by including an encoding comment here, but if
+ a valid encoding comment exists on the second line, it takes
precedence.</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>The script is checked for syntactic and semantic
+ correctness before it is run. If there are warnings (such as
+ unused variables), they are printed and the script will
+ still be run. If there are errors, they are printed and
+ the script will not be run and its exit status is
+ <c>127</c>.</p>
<p>Both the module declaration and the export declaration of
the <c>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>
+ 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. It is also possible to supply
- <c>native</c> instead of <c>compile</c>, this will compile the script
- using the native flag, again depending on the characteristics
- of the escript this could or could not be worth while.</p>
-
- <p>As mentioned earlier, it is possible to have a script which
+ If much of the execution takes place in interpreted code, it
+ can be worthwhile to compile it, although the compilation
+ itself takes a little while. Also, <c>native</c> can be supplied
+ instead of <c>compile</c>. This compiles the script
+ using the native flag and may or may not be worthwhile
+ depending on the escript characteristics.</p>
+ <p>As mentioned earlier, a script can
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
+ script, the interpretation of the script header is
+ the same as in a script containing source code. This 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
+ <c>main/1</c> function must be exported.</p>
+ <p>Another option is to have an entire
+ Erlang archive in the script. In an archive script, the
+ interpretation of the script header is the same as
+ in a script containing source code. This 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
+ above. In an archive script, the <c>main/1</c> function 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>
+ <c>escript</c> file is invoked. This behavior can be
+ overridden by setting flag <c>-escript main Module</c>
+ as one of the emulator flags. <c>Module</c> must be the
+ name of a module that has an exported <c>main/1</c>
+ function. For more information about archives and code loading, see
+ <seealso marker="kernel:code"><c>code(3)</c></seealso>.</p>
+ <p>It is often very convenient to have a header in
+ the escript, especially on Unix platforms. However, the header
+ is optional, so 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
+ as follows:</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>
+factorial 5 = 120</pre>
</desc>
</func>
+
<func>
- <name>escript:create(FileOrBin, Sections) -> ok | {ok, binary()} | {error, term()}</name>
- <fsummary>Create an escript</fsummary>
+ <name>escript:create(FileOrBin, Sections) -> ok | {ok, binary()} |
+ {error, term()}</name>
+ <fsummary>Create an escript.</fsummary>
<type>
<v>FileOrBin = filename() | 'binary'</v>
<v>Sections = [Header] Body | Body</v>
<v>Header = shebang | {shebang, Shebang}
- | comment | {comment, Comment}
- | {emu_args, EmuArgs}</v>
+ &nbsp;&nbsp;&nbsp;| comment | {comment, Comment}
+ &nbsp;&nbsp;&nbsp;| {emu_args, EmuArgs}</v>
<v>Shebang = string() | 'default' | 'undefined'</v>
<v>Comment = string() | 'default' | 'undefined'</v>
<v>EmuArgs = string() | 'undefined'</v>
- <v>Body = {source, SourceCode}
- | {beam, BeamCode}
- | {archive, ZipArchive}
- | {archive, ZipFiles, ZipOptions}</v>
+ <v>Body = {source, SourceCode} | {beam, BeamCode}
+ &nbsp;&nbsp;&nbsp;| {archive, ZipArchive}
+ &nbsp;&nbsp;&nbsp;| {archive, ZipFiles, ZipOptions}</v>
<v>SourceCode = BeamCode = file:filename() | binary()</v>
- <v>ZipArchive = <seealso marker="stdlib:zip#type-filename">zip:filename()</seealso> | binary()</v>
+ <v>ZipArchive = <seealso marker="stdlib:zip#type-filename">
+ zip:filename()</seealso> | binary()</v>
<v>ZipFiles = [ZipFile]</v>
- <v>ZipFile = file:filename() | {file:filename(), binary()} | {file:filename(), binary(), file:file_info()}</v>
- <v>ZipOptions = [<seealso marker="stdlib:zip#type-create_option">zip:create_option()</seealso>]</v>
+ <v>ZipFile = file:filename()
+ &nbsp;&nbsp;&nbsp;| {file:filename(), binary()}
+ &nbsp;&nbsp;&nbsp;| {file:filename(), binary(), file:file_info()}</v>
+ <v>ZipOptions = [<seealso marker="stdlib:zip#type-create_option">
+ zip:create_option()</seealso>]</v>
</type>
<desc>
- <p>The <marker id="create_2"></marker> <c>create/2</c>
- function creates an escript from a list of sections. The
- sections can be given in any order. An escript begins with an
- optional <c>Header</c> followed by a mandatory <c>Body</c>. If
- the header is present, it does always begin with a
- <c>shebang</c>, possibly followed by a <c>comment</c> and
- <c>emu_args</c>. The <c>shebang</c> defaults to
- <c>"/usr/bin/env escript"</c>. The comment defaults to
- <c>"This is an -*- erlang -*- file"</c>. The created escript
- can either be returned as a binary or written to file.</p>
-
- <p>As an example of how the function can be used, we create an
- interpreted escript which uses <c>emu_args</c> to set some emulator
- flag. In this case it happens to disable the smp_support. We
- do also extract the different sections from the newly created
- script:</p>
+ <p><marker id="create_2"></marker>
+ Creates an escript from a list of sections. The
+ sections can be specified in any order. An escript begins with an
+ optional <c>Header</c> followed by a mandatory <c>Body</c>. If
+ the header is present, it does always begin with a
+ <c>shebang</c>, possibly followed by a <c>comment</c> and
+ <c>emu_args</c>. The <c>shebang</c> defaults to
+ <c>"/usr/bin/env escript"</c>. The <c>comment</c> defaults to
+ <c>"This is an -*- erlang -*- file"</c>. The created escript
+ can either be returned as a binary or written to file.</p>
+ <p>As an example of how the function can be used, we create an
+ interpreted escript that uses <c>emu_args</c> to set some emulator
+ flag. In this case, it happens to disable the <c>smp_support</c>. We
+ also extract the different sections from the newly created script:</p>
<pre>
&gt; <input>Source = "%% Demo\nmain(_Args) ->\n io:format(erlang:system_info(smp_support)).\n".</input>
"%% Demo\nmain(_Args) ->\n io:format(erlang:system_info(smp_support)).\n"
@@ -280,11 +269,9 @@ ok
"false"
&gt; <input>escript:extract("demo.escript", []).</input>
{ok,[{shebang,default}, {comment,default}, {emu_args,"-smp disable"},
- {source,&lt;&lt;"%% Demo\nmain(_Args) ->\n io:format(erlang:system_info(smp_su"...&gt;&gt;}]}
- </pre>
-
- <p>An escript without header can be created like this:</p>
-<pre>
+ {source,&lt;&lt;"%% Demo\nmain(_Args) ->\n io:format(erlang:system_info(smp_su"...&gt;&gt;}]}</pre>
+ <p>An escript without header can be created as follows:</p>
+ <pre>
&gt; <input>file:write_file("demo.erl",
["%% demo.erl\n-module(demo).\n-export([main/1]).\n\n", Source]).</input>
ok
@@ -299,14 +286,12 @@ ok
{beam,&lt;&lt;70,79,82,49,0,0,3,68,66,69,65,77,65,116,
111,109,0,0,0,83,0,0,0,9,...&gt;&gt;}]}
&gt; <input>os:cmd("escript demo.beam").</input>
-"true"
-</pre>
- <p>Here we create an archive script containing both Erlang
- code as well as beam code. Then we iterate over all files in
- the archive and collect their contents and some info about
- them.
- </p>
-<pre>
+"true"</pre>
+ <p>Here we create an archive script containing both Erlang
+ code and Beam code, then we iterate over all files in
+ the archive and collect their contents and some information about
+ them:</p>
+ <pre>
&gt; <input>{ok, SourceCode} = file:read_file("demo.erl").</input>
{ok,&lt;&lt;"%% demo.erl\n-module(demo).\n-export([main/1]).\n\n%% Demo\nmain(_Arg"...&gt;&gt;}
&gt; <input>escript:create("demo.escript",
@@ -339,43 +324,43 @@ ok
&lt;&lt;"%% demo.erl\n-module(demo).\n-export([main/1]).\n\n%% Demo\nmain(_Arg"...&gt;&gt;}]}</pre>
</desc>
</func>
+
<func>
- <name>escript:extract(File, Options) -> {ok, Sections} | {error, term()}</name>
- <fsummary>Parses an escript and extracts its sections</fsummary>
+ <name>escript:extract(File, Options) -> {ok, Sections} |
+ {error, term()}</name>
+ <fsummary>Parse an escript and extract its sections.</fsummary>
<type>
<v>File = filename()</v>
<v>Options = [] | [compile_source]</v>
<v>Sections = Headers Body</v>
<v>Headers = {shebang, Shebang}
- {comment, Comment}
- {emu_args, EmuArgs}</v>
+ {comment, Comment}
+ {emu_args, EmuArgs}</v>
<v>Shebang = string() | 'default' | 'undefined'</v>
<v>Comment = string() | 'default' | 'undefined'</v>
<v>EmuArgs = string() | 'undefined'</v>
<v>Body = {source, SourceCode}
- | {source, BeamCode}
- | {beam, BeamCode}
- | {archive, ZipArchive}</v>
+ &nbsp;&nbsp;&nbsp;| {source, BeamCode}
+ &nbsp;&nbsp;&nbsp;| {beam, BeamCode}
+ &nbsp;&nbsp;&nbsp;| {archive, ZipArchive}</v>
<v>SourceCode = BeamCode = ZipArchive = binary()</v>
</type>
<desc>
- <p>The <marker id="extract_2"></marker> <c>extract/2</c>
- function parses an escript and extracts its sections. This is
- the reverse of <c>create/2</c>.</p>
-
- <p>All sections are returned even if they do not exist in the
- escript. If a particular section happens to have the same
- value as the default value, the extracted value is set to the
- atom <c>default</c>. If a section is missing, the extracted
- value is set to the atom <c>undefined</c>. </p>
-
- <p>The <c>compile_source</c> option only affects the result if
- the escript contains <c>source</c> code. In that case the
- Erlang code is automatically compiled and <c>{source,
- BeamCode}</c> is returned instead of <c>{source,
- SourceCode}</c>.</p>
-
- <pre>
+ <p><marker id="extract_2"></marker>
+ Parses an escript and extracts its sections. This is the reverse
+ of <seealso marker="#create_2"><c>create/2</c></seealso>.</p>
+ <p>All sections are returned even if they do not exist in the
+ escript. If a particular section happens to have the same
+ value as the default value, the extracted value is set to the
+ atom <c>default</c>. If a section is missing, the extracted
+ value is set to the atom <c>undefined</c>.</p>
+ <p>Option <c>compile_source</c> only affects the result if
+ the escript contains <c>source</c> code. In this case the
+ Erlang code is automatically compiled and <c>{source,
+ BeamCode}</c> is returned instead of <c>{source,
+ SourceCode}</c>.</p>
+ <p>Example:</p>
+ <pre>
&gt; <input>escript:create("demo.escript",
[shebang, {archive, [{"demo.erl", SourceCode},
{"demo.beam", BeamCode}], []}]).</input>
@@ -385,52 +370,51 @@ ok
escript:extract("demo.escript", []).</input>
{ok,[{{archive,&lt;&lt;80,75,3,4,20,0,0,0,8,0,118,7,98,60,105,
152,61,93,107,0,0,0,118,0,...&gt;&gt;}
- {emu_args,undefined}]}
- </pre>
+ {emu_args,undefined}]}</pre>
</desc>
</func>
+
<func>
<name>escript:script_name() -> File</name>
- <fsummary>Returns the name of an escript</fsummary>
+ <fsummary>Return the name of an escript.</fsummary>
<type>
<v>File = filename()</v>
</type>
<desc>
- <p>The <marker id="script_name_0"></marker>
- <c>script_name/0</c> function returns the name of the escript
- being executed. If the function is invoked outside the context
- of an escript, the behavior is undefined.</p>
+ <p><marker id="script_name_0"></marker>
+ Returns the name of the escript that is executed.
+ If the function is invoked outside the context
+ of an escript, the behavior is undefined.</p>
</desc>
</func>
</funcs>
<section>
- <title>Options accepted by escript</title>
+ <title>Options Accepted By escript</title>
<taglist>
- <tag>-c</tag>
- <item>Compile the escript regardless of the value of the mode attribute.
+ <tag><c>-c</c></tag>
+ <item>Compiles 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.
+ <tag><c>-d</c></tag>
+ <item>Debugs 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 option
+ <c>debug_info</c>.
</item>
-
- <tag>-i</tag>
- <item>Interpret the escript regardless of the value of the mode attribute.
+ <tag><c>-i</c></tag>
+ <item>Interprets the escript regardless of the value of the mode
+ attribute.
+ </item>
+ <tag><c>-s</c></tag>
+ <item>Performs 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 is <c>0</c> if any errors
+ are found, otherwise <c>127</c>.
+ </item>
+ <tag><c>-n</c></tag>
+ <item>Compiles the escript using flag <c>+native</c>.
</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>
-
- <tag>-n</tag>
- <item>Compile the escript using the +native flag.</item>
</taglist>
</section>
</comref>