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 %%! -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, latin1}])
94 The default encoding of the I/O-server for standard_io is uni‐
96 code if its supported. (see section Summary of Options) in the
97 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 %%! -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.
171 As mentioned earlier, a script can contains precompiled beam
173 code. In a precompiled script, the interpretation of the script
174 header is the same as in a script containing source code. This
175 means that you can make a beam file executable by prepending the
176 file with the lines starting with #! and %%! mentioned above. In
177 a precompiled script, the main/1 function must be exported.
178 Another option is to have an entire Erlang archive in the
180 script. In an archive script, the interpretation of the script
181 header is the same as in a script containing source code. This
182 means that you can make an archive file executable by prepending
183 the file with the lines starting with #! and %%! mentioned
184 above. In an archive script, the main/1 function must be ex‐
185 ported. By default the main/1 function in the module with the
186 same name as the basename of the escript file is invoked. This
187 behavior can be overridden by setting flag -escript main Module
188 as one of the emulator flags. Module must be the name of a mod‐
189 ule that has an exported main/1 function. For more information
190 about archives and code loading, see code(3).
191 It is often very convenient to have a header in the escript, es‐
193 pecially on Unix platforms. However, the header is optional, so
194 you directly can "execute" an Erlang module, Beam file, or ar‐
195 chive file without adding any header to them. But then you have
196 to invoke the script as follows:
197 $ escript factorial.erl 5
199 factorial 5 = 120
200 $ escript factorial.beam 5
201 factorial 5 = 120
202 $ escript factorial.zip 5
203 factorial 5 = 120
204 escript:create(FileOrBin, Sections) -> ok | {ok, binary()} | {error,
206 term()}
207 Types:
209 FileOrBin = filename() | 'binary'
211 Sections = [Header] Body | Body
212 Header = shebang | {shebang, Shebang} | comment | {comment,
213 Comment} | {emu_args, EmuArgs}
214 Shebang = string() | 'default' | 'undefined'
215 Comment = string() | 'default' | 'undefined'
216 EmuArgs = string() | 'undefined'
217 Body = {source, SourceCode} | {beam, BeamCode} | {archive,
218 ZipArchive} | {archive, ZipFiles, ZipOptions}
219 SourceCode = BeamCode = file:filename() | binary()
220 ZipArchive = zip:filename() | binary()
221 ZipFiles = [ZipFile]
222 ZipFile = file:filename() | {file:filename(), binary()} |
223 {file:filename(), binary(), file:file_info()}
224 ZipOptions = [ zip:create_option()]
225 Creates an escript from a list of sections. The sections can be
227 specified in any order. An escript begins with an optional
228 Header followed by a mandatory Body. If the header is present,
229 it does always begin with a shebang, possibly followed by a com‐
230 ment and emu_args. The shebang defaults to "/usr/bin/env es‐
231 cript". The comment defaults to "This is an -*- erlang -*-
232 file". The created escript can either be returned as a binary or
233 written to file.
234 As an example of how the function can be used, we create an in‐
236 terpreted escript that uses emu_args to set some emulator flag.
237 In this case, it happens to set number of schedulers with +S3.
238 We also extract the different sections from the newly created
239 script:
240 > Source = "%% Demo\nmain(_Args) ->\n io:format(\"~p\",[erlang:system_info(schedulers)]).\n".
242 "%% Demo\nmain(_Args) ->\n io:format(erlang:system_info(schedulers)).\n"
243 > io:format("~s\n", [Source]).
244 %% Demo
245 main(_Args) ->
246 io:format(erlang:system_info(schedulers)).
247 ok
249 > {ok, Bin} = escript:create(binary, [shebang, comment, {emu_args, "+S3"}, {source, list_to_binary(Source)}]).
250 {ok,<<"#!/usr/bin/env escript\n%% This is an -*- erlang -*- file\n%%!+S3"...>>}
251 > file:write_file("demo.escript", Bin).
252 ok
253 > os:cmd("escript demo.escript").
254 "3"
255 > escript:extract("demo.escript", []).
256 {ok,[{shebang,default}, {comment,default}, {emu_args,"+S3"},
257 {source,<<"%% Demo\nmain(_Args) ->\n io:format(erlang:system_info(schedu"...>>}]}
258 An escript without header can be created as follows:
260 > file:write_file("demo.erl", ["%% demo.erl\n-module(demo).\n-export([main/1]).\n\n", Source]).
262 ok
263 > {ok, _, BeamCode} = compile:file("demo.erl", [binary, debug_info]).
264 {ok,demo,
265 <<70,79,82,49,0,0,2,208,66,69,65,77,65,116,111,109,0,0,0,
266 79,0,0,0,9,4,100,...>>}
267 > escript:create("demo.beam", [{beam, BeamCode}]).
268 ok
269 > escript:extract("demo.beam", []).
270 {ok,[{shebang,undefined}, {comment,undefined}, {emu_args,undefined},
271 {beam,<<70,79,82,49,0,0,3,68,66,69,65,77,65,116,
272 111,109,0,0,0,83,0,0,0,9,...>>}]}
273 > os:cmd("escript demo.beam").
274 "true"
275 Here we create an archive script containing both Erlang code and
277 Beam code, then we iterate over all files in the archive and
278 collect their contents and some information about them:
279 > {ok, SourceCode} = file:read_file("demo.erl").
281 {ok,<<"%% demo.erl\n-module(demo).\n-export([main/1]).\n\n%% Demo\nmain(_Arg"...>>}
282 > escript:create("demo.escript", [shebang, {archive, [{"demo.erl", SourceCode}, {"demo.beam", BeamCode}], []}]).
283 ok
284 > {ok, [{shebang,default}, {comment,undefined}, {emu_args,undefined}, {archive, ArchiveBin}]} = escript:extract("demo.escript", []).
285 {ok,[{shebang,default}, {comment,undefined}, {emu_args,undefined},
286 {{archive,<<80,75,3,4,20,0,0,0,8,0,118,7,98,60,105,
287 152,61,93,107,0,0,0,118,0,...>>}]}
288 > file:write_file("demo.zip", ArchiveBin).
289 ok
290 > zip:foldl(fun(N, I, B, A) -> [{N, I(), B()} | A] end, [], "demo.zip").
291 {ok,[{"demo.beam",
292 {file_info,748,regular,read_write,
293 {{2010,3,2},{0,59,22}},
294 {{2010,3,2},{0,59,22}},
295 {{2010,3,2},{0,59,22}},
296 54,1,0,0,0,0,0},
297 <<70,79,82,49,0,0,2,228,66,69,65,77,65,116,111,109,0,0,0,
298 83,0,0,...>>},
299 {"demo.erl",
300 {file_info,118,regular,read_write,
301 {{2010,3,2},{0,59,22}},
302 {{2010,3,2},{0,59,22}},
303 {{2010,3,2},{0,59,22}},
304 54,1,0,0,0,0,0},
305 <<"%% demo.erl\n-module(demo).\n-export([main/1]).\n\n%% Demo\nmain(_Arg"...>>}]}
306 escript:extract(File, Options) -> {ok, Sections} | {error, term()}
308 Types:
310 File = filename()
312 Options = [] | [compile_source]
313 Sections = Headers Body
314 Headers = {shebang, Shebang} {comment, Comment} {emu_args,
315 EmuArgs}
316 Shebang = string() | 'default' | 'undefined'
317 Comment = string() | 'default' | 'undefined'
318 EmuArgs = string() | 'undefined'
319 Body = {source, SourceCode} | {source, BeamCode} | {beam,
320 BeamCode} | {archive, ZipArchive}
321 SourceCode = BeamCode = ZipArchive = binary()
322 Parses an escript and extracts its sections. This is the reverse
324 of create/2.
325 All sections are returned even if they do not exist in the es‐
327 cript. If a particular section happens to have the same value as
328 the default value, the extracted value is set to the atom de‐
329 fault. If a section is missing, the extracted value is set to
330 the atom undefined.
331 Option compile_source only affects the result if the escript
333 contains source code. In this case the Erlang code is automati‐
334 cally compiled and {source, BeamCode} is returned instead of
335 {source, SourceCode}.
336 Example:
338 > escript:create("demo.escript", [shebang, {archive, [{"demo.erl", SourceCode}, {"demo.beam", BeamCode}], []}]).
340 ok
341 > {ok, [{shebang,default}, {comment,undefined}, {emu_args,undefined}, {archive, ArchiveBin}]} = escript:extract("demo.escript", []).
342 {ok,[{{archive,<<80,75,3,4,20,0,0,0,8,0,118,7,98,60,105,
343 152,61,93,107,0,0,0,118,0,...>>}
344 {emu_args,undefined}]}
345 escript:script_name() -> File
347 Types:
349 File = filename()
351 Returns the name of the escript that is executed. If the func‐
353 tion is invoked outside the context of an escript, the behavior
354 is undefined.
355
357 -c:
358 Compiles the escript regardless of the value of the mode attribute.
359 -d:
361 Debugs the escript. Starts the debugger, loads the module contain‐
362 ing the main/1 function into the debugger, sets a breakpoint in
363 main/1, and invokes main/1. If the module is precompiled, it must
364 be explicitly compiled with option debug_info.
365 -i:
367 Interprets the escript regardless of the value of the mode attri‐
368 bute.
369 -s:
371 Performs a syntactic and semantic check of the script file. Warn‐
372 ings and errors (if any) are written to the standard output, but
373 the script will not be run. The exit status is 0 if any errors are
374 found, otherwise 127.
375 Note:
377 The configuration of the Erlang emulator invoked by escript can be con‐
378 trolled using the environment variables understood by erl.
379Ericsson AB erts 14.1.1 escript(1)