diff options
Diffstat (limited to 'erts/doc/src/escript.xml')
| -rw-r--r-- | erts/doc/src/escript.xml | 422 |
1 files changed, 214 insertions, 208 deletions
diff --git a/erts/doc/src/escript.xml b/erts/doc/src/escript.xml index f12f76890c..9b0d42185e 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>2017</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -33,17 +33,40 @@ <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> + + <p>It is possible to bundle <c>escript</c>(s) with an Erlang + runtime system to make it self-sufficient and relocatable. In such + a standalone system, the <c>escript</c>(s) should be located in + the top <c>bin</c> directory of the standalone system and given + <c>.escript</c> as file extension. Further the (built-in) + <c>escript</c> program should be copied to the same directory and + given the scripts original name (without the <c>.escript</c> + extension). This will enable use of the bundled Erlang runtime + system.</p> + + <p>The (built-in) <c>escript</c> program first determines which + Erlang runtime system to use and then starts it to execute your + script. Usually the runtime system is located in the same Erlang + installation as the <c>escript</c> program itself. But for + standalone systems with one or more escripts it may be the case + that the <c>escript</c> program in your path actually starts the + runtime system bundled with the escript. This is intentional, and + typically happens when the standalone system <c>bin</c> directory is not + in the execution path (as it may cause its <c>erl</c> program to + override the desired one) and the <c>escript</c>(s) are referred to via + symbolic links from a <c>bin</c> directory in the path.</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 +96,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> + | comment | {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} - | {beam, BeamCode} - | {archive, ZipArchive} - | {archive, ZipFiles, ZipOptions}</v> + <v>Body = {source, SourceCode} | {beam, BeamCode} + | {archive, ZipArchive} + | {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() + | {file:filename(), binary()} + | {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> > <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 +291,9 @@ ok "false" > <input>escript:extract("demo.escript", []).</input> {ok,[{shebang,default}, {comment,default}, {emu_args,"-smp disable"}, - {source,<<"%% Demo\nmain(_Args) ->\n io:format(erlang:system_info(smp_su"...>>}]} - </pre> - - <p>An escript without header can be created like this:</p> -<pre> + {source,<<"%% Demo\nmain(_Args) ->\n io:format(erlang:system_info(smp_su"...>>}]}</pre> + <p>An escript without header can be created as follows:</p> + <pre> > <input>file:write_file("demo.erl", ["%% demo.erl\n-module(demo).\n-export([main/1]).\n\n", Source]).</input> ok @@ -299,14 +308,12 @@ ok {beam,<<70,79,82,49,0,0,3,68,66,69,65,77,65,116, 111,109,0,0,0,83,0,0,0,9,...>>}]} > <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> > <input>{ok, SourceCode} = file:read_file("demo.erl").</input> {ok,<<"%% demo.erl\n-module(demo).\n-export([main/1]).\n\n%% Demo\nmain(_Arg"...>>} > <input>escript:create("demo.escript", @@ -339,43 +346,43 @@ ok <<"%% demo.erl\n-module(demo).\n-export([main/1]).\n\n%% Demo\nmain(_Arg"...>>}]}</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> + | {source, BeamCode} + | {beam, BeamCode} + | {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> > <input>escript:create("demo.escript", [shebang, {archive, [{"demo.erl", SourceCode}, {"demo.beam", BeamCode}], []}]).</input> @@ -385,52 +392,51 @@ ok escript:extract("demo.escript", []).</input> {ok,[{{archive,<<80,75,3,4,20,0,0,0,8,0,118,7,98,60,105, 152,61,93,107,0,0,0,118,0,...>>} - {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> |