1escript(1) User Commands escript(1)
2
6 escript - Erlang scripting support
7
9 escript provides support for running short Erlang programs without hav‐
10 ing to compile them first, and an easy way to retrieve the command-line
11 arguments.
12 It is possible to bundle escript(s) with an Erlang runtime system to
14 make it self-sufficient and relocatable. In such a standalone system,
15 the escript(s) should be located in the top bin directory of the stand‐
16 alone system and given .escript as file extension. Further the (built-
17 in) escript program should be copied to the same directory and given
18 the script's original name (without the .escript extension). This will
19 enable use of the bundled Erlang runtime system.
20 The (built-in) escript program first determines which Erlang runtime
22 system to use and then starts it to execute your script. Usually the
23 runtime system is located in the same Erlang installation as the es‐
24 cript program itself. But for standalone systems with one or more es‐
25 cripts it may be the case that the escript program in your path actu‐
26 ally starts the runtime system bundled with the escript. This is inten‐
27 tional, and typically happens when the standalone system bin directory
28 is not in the execution path (as it may cause its erl program to over‐
29 ride the desired one) and the escript(s) are referred to via symbolic
30 links from a bin directory in the path.
31
33 script-name script-arg1 script-arg2...
34 escript escript-flags script-name script-arg1 script-arg2...
35 escript runs a script written in Erlang.
37 Example:
39 $ chmod u+x factorial
41 $ cat factorial
42 #!/usr/bin/env escript
43 %% -*- erlang -*-
44 %%! -smp enable -sname factorial -mnesia debug verbose
45 main([String]) ->
46 try
47 N = list_to_integer(String),
48 F = fac(N),
49 io:format("factorial ~w = ~w\n", [N,F])
50 catch
51 _:_ ->
52 usage()
53 end;
54 main(_) ->
55 usage().
56 usage() ->
58 io:format("usage: factorial integer\n"),
59 halt(1).
60 fac(0) -> 1;
62 fac(N) -> N * fac(N-1).
63 $ ./factorial 5
64 factorial 5 = 120
65 $ ./factorial
66 usage: factorial integer
67 $ ./factorial five
68 usage: factorial integer
69 The header of the Erlang script in the example differs from a
71 normal Erlang module. The first line is intended to be the in‐
72 terpreter line, which invokes escript.
73 However, if you invoke the escript as follows, the contents of
75 the first line do not matter, but it cannot contain Erlang code
76 as it will be ignored:
77 $ escript factorial 5
79 The second line in the example contains an optional directive to
81 the Emacs editor, which causes it to enter the major mode for
82 editing Erlang source files. If the directive is present, it
83 must be located on the second line.
84 If a comment selecting the encoding exists, it can be located on
86 the second line.
87 Note:
89 The encoding specified by the above mentioned comment applies to
90 the script itself. The encoding of the I/O-server, however, must
91 be set explicitly as follows:
92 io:setopts([{encoding, unicode}])
94 The default encoding of the I/O-server for standard_io is
96 latin1, as the script runs in a non-interactive terminal (see
97 section Summary of Options) in the STDLIB User's Guide.
98 On the third line (or second line depending on the presence of
101 the Emacs directive), arguments can be specified to the emula‐
102 tor, for example:
103 %%! -smp enable -sname factorial -mnesia debug verbose
105 Such an argument line must start with %%! and the remaining line
107 is interpreted as arguments to the emulator.
108 If you know the location of the escript executable, the first
110 line can directly give the path to escript, for example:
111 #!/usr/local/bin/escript
113 As any other type of scripts, Erlang scripts do not work on Unix
115 platforms if the execution bit for the script file is not set.
116 (To turn on the execution bit, use chmod +x script-name.)
117 The remaining Erlang script file can either contain Erlang
119 source code, an inlined beam file, or an inlined archive file.
120 An Erlang script file must always contain the main/1 function.
122 When the script is run, the main/1 function is called with a
123 list of strings representing the arguments specified to the
124 script (not changed or interpreted in any way).
125 If the main/1 function in the script returns successfully, the
127 exit status for the script is 0. If an exception is generated
128 during execution, a short message is printed and the script ter‐
129 minates with exit status 127.
130 To return your own non-zero exit code, call halt(ExitCode), for
132 example:
133 halt(1).
135 To retrieve the pathname of the script, call es‐
137 cript:script_name() from your script (the pathname is usually,
138 but not always, absolute).
139 If the file contains source code (as in the example above), it
141 is processed by the epp preprocessor. This means that you, for
142 example, can use predefined macros (such as ?MODULE) and include
143 directives like the -include_lib directive. For example, use
144 -include_lib("kernel/include/file.hrl").
146 to include the record definitions for the records used by func‐
148 tion file:read_link_info/1. You can also select encoding by in‐
149 cluding an encoding comment here, but if a valid encoding com‐
150 ment exists on the second line, it takes precedence.
151 The script is checked for syntactic and semantic correctness be‐
153 fore it is run. If there are warnings (such as unused vari‐
154 ables), they are printed and the script will still be run. If
155 there are errors, they are printed and the script will not be
156 run and its exit status is 127.
157 Both the module declaration and the export declaration of the
159 main/1 function are optional.
160 By default, the script will be interpreted. You can force it to
162 be compiled by including the following line somewhere in the
163 script file:
164 -mode(compile).
166 Execution of interpreted code is slower than compiled code. If
168 much of the execution takes place in interpreted code, it can be
169 worthwhile to compile it, although the compilation itself takes
170 a little while. Also, native can be supplied instead of compile.
171 This compiles the script using the native flag and may or may
172 not be worthwhile depending on the escript characteristics.
173 As mentioned earlier, a script can contains precompiled beam
175 code. In a precompiled script, the interpretation of the script
176 header is the same as in a script containing source code. This
177 means that you can make a beam file executable by prepending the
178 file with the lines starting with #! and %%! mentioned above. In
179 a precompiled script, the main/1 function must be exported.
180 Another option is to have an entire Erlang archive in the
182 script. In an archive script, the interpretation of the script
183 header is the same as in a script containing source code. This
184 means that you can make an archive file executable by prepending
185 the file with the lines starting with #! and %%! mentioned
186 above. In an archive script, the main/1 function must be ex‐
187 ported. By default the main/1 function in the module with the
188 same name as the basename of the escript file is invoked. This
189 behavior can be overridden by setting flag -escript main Module
190 as one of the emulator flags. Module must be the name of a mod‐
191 ule that has an exported main/1 function. For more information
192 about archives and code loading, see code(3).
193 It is often very convenient to have a header in the escript, es‐
195 pecially on Unix platforms. However, the header is optional, so
196 you directly can "execute" an Erlang module, Beam file, or ar‐
197 chive file without adding any header to them. But then you have
198 to invoke the script as follows:
199 $ escript factorial.erl 5
201 factorial 5 = 120
202 $ escript factorial.beam 5
203 factorial 5 = 120
204 $ escript factorial.zip 5
205 factorial 5 = 120
206 escript:create(FileOrBin, Sections) -> ok | {ok, binary()} | {error,
208 term()}
209 Types:
211 FileOrBin = filename() | 'binary'
213 Sections = [Header] Body | Body
214 Header = shebang | {shebang, Shebang} | comment | {comment,
215 Comment} | {emu_args, EmuArgs}
216 Shebang = string() | 'default' | 'undefined'
217 Comment = string() | 'default' | 'undefined'
218 EmuArgs = string() | 'undefined'
219 Body = {source, SourceCode} | {beam, BeamCode} | {archive,
220 ZipArchive} | {archive, ZipFiles, ZipOptions}
221 SourceCode = BeamCode = file:filename() | binary()
222 ZipArchive = zip:filename() | binary()
223 ZipFiles = [ZipFile]
224 ZipFile = file:filename() | {file:filename(), binary()} |
225 {file:filename(), binary(), file:file_info()}
226 ZipOptions = [ zip:create_option()]
227 Creates an escript from a list of sections. The sections can be
229 specified in any order. An escript begins with an optional
230 Header followed by a mandatory Body. If the header is present,
231 it does always begin with a shebang, possibly followed by a com‐
232 ment and emu_args. The shebang defaults to "/usr/bin/env es‐
233 cript". The comment defaults to "This is an -*- erlang -*-
234 file". The created escript can either be returned as a binary or
235 written to file.
236 As an example of how the function can be used, we create an in‐
238 terpreted escript that uses emu_args to set some emulator flag.
239 In this case, it happens to disable the smp_support. We also ex‐
240 tract the different sections from the newly created script:
241 > Source = "%% Demo\nmain(_Args) ->\n io:format(erlang:system_info(smp_support)).\n".
243 "%% Demo\nmain(_Args) ->\n io:format(erlang:system_info(smp_support)).\n"
244 > io:format("~s\n", [Source]).
245 %% Demo
246 main(_Args) ->
247 io:format(erlang:system_info(smp_support)).
248 ok
250 > {ok, Bin} = escript:create(binary, [shebang, comment, {emu_args, "-smp disable"}, {source, list_to_binary(Source)}]).
251 {ok,<<"#!/usr/bin/env escript\n%% This is an -*- erlang -*- file\n%%!-smp disabl"...>>}
252 > file:write_file("demo.escript", Bin).
253 ok
254 > os:cmd("escript demo.escript").
255 "false"
256 > escript:extract("demo.escript", []).
257 {ok,[{shebang,default}, {comment,default}, {emu_args,"-smp disable"},
258 {source,<<"%% Demo\nmain(_Args) ->\n io:format(erlang:system_info(smp_su"...>>}]}
259 An escript without header can be created as follows:
261 > file:write_file("demo.erl", ["%% demo.erl\n-module(demo).\n-export([main/1]).\n\n", Source]).
263 ok
264 > {ok, _, BeamCode} = compile:file("demo.erl", [binary, debug_info]).
265 {ok,demo,
266 <<70,79,82,49,0,0,2,208,66,69,65,77,65,116,111,109,0,0,0,
267 79,0,0,0,9,4,100,...>>}
268 > escript:create("demo.beam", [{beam, BeamCode}]).
269 ok
270 > escript:extract("demo.beam", []).
271 {ok,[{shebang,undefined}, {comment,undefined}, {emu_args,undefined},
272 {beam,<<70,79,82,49,0,0,3,68,66,69,65,77,65,116,
273 111,109,0,0,0,83,0,0,0,9,...>>}]}
274 > os:cmd("escript demo.beam").
275 "true"
276 Here we create an archive script containing both Erlang code and
278 Beam code, then we iterate over all files in the archive and
279 collect their contents and some information about them:
280 > {ok, SourceCode} = file:read_file("demo.erl").
282 {ok,<<"%% demo.erl\n-module(demo).\n-export([main/1]).\n\n%% Demo\nmain(_Arg"...>>}
283 > escript:create("demo.escript", [shebang, {archive, [{"demo.erl", SourceCode}, {"demo.beam", BeamCode}], []}]).
284 ok
285 > {ok, [{shebang,default}, {comment,undefined}, {emu_args,undefined}, {archive, ArchiveBin}]} = escript:extract("demo.escript", []).
286 {ok,[{shebang,default}, {comment,undefined}, {emu_args,undefined},
287 {{archive,<<80,75,3,4,20,0,0,0,8,0,118,7,98,60,105,
288 152,61,93,107,0,0,0,118,0,...>>}]}
289 > file:write_file("demo.zip", ArchiveBin).
290 ok
291 > zip:foldl(fun(N, I, B, A) -> [{N, I(), B()} | A] end, [], "demo.zip").
292 {ok,[{"demo.beam",
293 {file_info,748,regular,read_write,
294 {{2010,3,2},{0,59,22}},
295 {{2010,3,2},{0,59,22}},
296 {{2010,3,2},{0,59,22}},
297 54,1,0,0,0,0,0},
298 <<70,79,82,49,0,0,2,228,66,69,65,77,65,116,111,109,0,0,0,
299 83,0,0,...>>},
300 {"demo.erl",
301 {file_info,118,regular,read_write,
302 {{2010,3,2},{0,59,22}},
303 {{2010,3,2},{0,59,22}},
304 {{2010,3,2},{0,59,22}},
305 54,1,0,0,0,0,0},
306 <<"%% demo.erl\n-module(demo).\n-export([main/1]).\n\n%% Demo\nmain(_Arg"...>>}]}
307 escript:extract(File, Options) -> {ok, Sections} | {error, term()}
309 Types:
311 File = filename()
313 Options = [] | [compile_source]
314 Sections = Headers Body
315 Headers = {shebang, Shebang} {comment, Comment} {emu_args,
316 EmuArgs}
317 Shebang = string() | 'default' | 'undefined'
318 Comment = string() | 'default' | 'undefined'
319 EmuArgs = string() | 'undefined'
320 Body = {source, SourceCode} | {source, BeamCode} | {beam,
321 BeamCode} | {archive, ZipArchive}
322 SourceCode = BeamCode = ZipArchive = binary()
323 Parses an escript and extracts its sections. This is the reverse
325 of create/2.
326 All sections are returned even if they do not exist in the es‐
328 cript. If a particular section happens to have the same value as
329 the default value, the extracted value is set to the atom de‐
330 fault. If a section is missing, the extracted value is set to
331 the atom undefined.
332 Option compile_source only affects the result if the escript
334 contains source code. In this case the Erlang code is automati‐
335 cally compiled and {source, BeamCode} is returned instead of
336 {source, SourceCode}.
337 Example:
339 > escript:create("demo.escript", [shebang, {archive, [{"demo.erl", SourceCode}, {"demo.beam", BeamCode}], []}]).
341 ok
342 > {ok, [{shebang,default}, {comment,undefined}, {emu_args,undefined}, {archive, ArchiveBin}]} = escript:extract("demo.escript", []).
343 {ok,[{{archive,<<80,75,3,4,20,0,0,0,8,0,118,7,98,60,105,
344 152,61,93,107,0,0,0,118,0,...>>}
345 {emu_args,undefined}]}
346 escript:script_name() -> File
348 Types:
350 File = filename()
352 Returns the name of the escript that is executed. If the func‐
354 tion is invoked outside the context of an escript, the behavior
355 is undefined.
356
358 -c:
359 Compiles the escript regardless of the value of the mode attribute.
360 -d:
362 Debugs the escript. Starts the debugger, loads the module contain‐
363 ing the main/1 function into the debugger, sets a breakpoint in
364 main/1, and invokes main/1. If the module is precompiled, it must
365 be explicitly compiled with option debug_info.
366 -i:
368 Interprets the escript regardless of the value of the mode attri‐
369 bute.
370 -s:
372 Performs a syntactic and semantic check of the script file. Warn‐
373 ings and errors (if any) are written to the standard output, but
374 the script will not be run. The exit status is 0 if any errors are
375 found, otherwise 127.
376 -n:
378 Compiles the escript using flag +native.
379Ericsson AB erts 11.2.2.2 escript(1)