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 scripts 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
24 escript program itself. But for standalone systems with one or more
25 escripts 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
72 interpreter line, which invokes escript.
73 However, if you invoke the escript as follows, the contents of
75 the first line does not matter, but it cannot contain Erlang
76 code 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
137 escript: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
149 including 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
153 before 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
187 exported. 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,
195 especially on Unix platforms. However, the header is optional,
196 so you directly can "execute" an Erlang module, Beam file, or
197 archive file without adding any header to them. But then you
198 have 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
233 escript". 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
238 interpreted escript that uses emu_args to set some emulator
239 flag. In this case, it happens to disable the smp_support. We
240 also extract the different sections from the newly created
241 script:
242 > Source = "%% Demo\nmain(_Args) ->\n io:format(erlang:system_info(smp_support)).\n".
244 "%% Demo\nmain(_Args) ->\n io:format(erlang:system_info(smp_support)).\n"
245 > io:format("~s\n", [Source]).
246 %% Demo
247 main(_Args) ->
248 io:format(erlang:system_info(smp_support)).
249 ok
251 > {ok, Bin} = escript:create(binary, [shebang, comment, {emu_args, "-smp disable"}, {source, list_to_binary(Source)}]).
252 {ok,<<"#!/usr/bin/env escript\n%% This is an -*- erlang -*- file\n%%!-smp disabl"...>>}
253 > file:write_file("demo.escript", Bin).
254 ok
255 > os:cmd("escript demo.escript").
256 "false"
257 > escript:extract("demo.escript", []).
258 {ok,[{shebang,default}, {comment,default}, {emu_args,"-smp disable"},
259 {source,<<"%% Demo\nmain(_Args) ->\n io:format(erlang:system_info(smp_su"...>>}]}
260 An escript without header can be created as follows:
262 > file:write_file("demo.erl", ["%% demo.erl\n-module(demo).\n-export([main/1]).\n\n", Source]).
264 ok
265 > {ok, _, BeamCode} = compile:file("demo.erl", [binary, debug_info]).
266 {ok,demo,
267 <<70,79,82,49,0,0,2,208,66,69,65,77,65,116,111,109,0,0,0,
268 79,0,0,0,9,4,100,...>>}
269 > escript:create("demo.beam", [{beam, BeamCode}]).
270 ok
271 > escript:extract("demo.beam", []).
272 {ok,[{shebang,undefined}, {comment,undefined}, {emu_args,undefined},
273 {beam,<<70,79,82,49,0,0,3,68,66,69,65,77,65,116,
274 111,109,0,0,0,83,0,0,0,9,...>>}]}
275 > os:cmd("escript demo.beam").
276 "true"
277 Here we create an archive script containing both Erlang code and
279 Beam code, then we iterate over all files in the archive and
280 collect their contents and some information about them:
281 > {ok, SourceCode} = file:read_file("demo.erl").
283 {ok,<<"%% demo.erl\n-module(demo).\n-export([main/1]).\n\n%% Demo\nmain(_Arg"...>>}
284 > escript:create("demo.escript", [shebang, {archive, [{"demo.erl", SourceCode}, {"demo.beam", BeamCode}], []}]).
285 ok
286 > {ok, [{shebang,default}, {comment,undefined}, {emu_args,undefined}, {archive, ArchiveBin}]} = escript:extract("demo.escript", []).
287 {ok,[{shebang,default}, {comment,undefined}, {emu_args,undefined},
288 {{archive,<<80,75,3,4,20,0,0,0,8,0,118,7,98,60,105,
289 152,61,93,107,0,0,0,118,0,...>>}]}
290 > file:write_file("demo.zip", ArchiveBin).
291 ok
292 > zip:foldl(fun(N, I, B, A) -> [{N, I(), B()} | A] end, [], "demo.zip").
293 {ok,[{"demo.beam",
294 {file_info,748,regular,read_write,
295 {{2010,3,2},{0,59,22}},
296 {{2010,3,2},{0,59,22}},
297 {{2010,3,2},{0,59,22}},
298 54,1,0,0,0,0,0},
299 <<70,79,82,49,0,0,2,228,66,69,65,77,65,116,111,109,0,0,0,
300 83,0,0,...>>},
301 {"demo.erl",
302 {file_info,118,regular,read_write,
303 {{2010,3,2},{0,59,22}},
304 {{2010,3,2},{0,59,22}},
305 {{2010,3,2},{0,59,22}},
306 54,1,0,0,0,0,0},
307 <<"%% demo.erl\n-module(demo).\n-export([main/1]).\n\n%% Demo\nmain(_Arg"...>>}]}
308 escript:extract(File, Options) -> {ok, Sections} | {error, term()}
310 Types:
312 File = filename()
314 Options = [] | [compile_source]
315 Sections = Headers Body
316 Headers = {shebang, Shebang} {comment, Comment} {emu_args,
317 EmuArgs}
318 Shebang = string() | 'default' | 'undefined'
319 Comment = string() | 'default' | 'undefined'
320 EmuArgs = string() | 'undefined'
321 Body = {source, SourceCode} | {source, BeamCode} | {beam,
322 BeamCode} | {archive, ZipArchive}
323 SourceCode = BeamCode = ZipArchive = binary()
324 Parses an escript and extracts its sections. This is the reverse
326 of create/2.
327 All sections are returned even if they do not exist in the
329 escript. If a particular section happens to have the same value
330 as the default value, the extracted value is set to the atom
331 default. If a section is missing, the extracted value is set to
332 the atom undefined.
333 Option compile_source only affects the result if the escript
335 contains source code. In this case the Erlang code is automati‐
336 cally compiled and {source, BeamCode} is returned instead of
337 {source, SourceCode}.
338 Example:
340 > escript:create("demo.escript", [shebang, {archive, [{"demo.erl", SourceCode}, {"demo.beam", BeamCode}], []}]).
342 ok
343 > {ok, [{shebang,default}, {comment,undefined}, {emu_args,undefined}, {archive, ArchiveBin}]} = escript:extract("demo.escript", []).
344 {ok,[{{archive,<<80,75,3,4,20,0,0,0,8,0,118,7,98,60,105,
345 152,61,93,107,0,0,0,118,0,...>>}
346 {emu_args,undefined}]}
347 escript:script_name() -> File
349 Types:
351 File = filename()
353 Returns the name of the escript that is executed. If the func‐
355 tion is invoked outside the context of an escript, the behavior
356 is undefined.
357
359 -c:
360 Compiles the escript regardless of the value of the mode attribute.
361 -d:
363 Debugs the escript. Starts the debugger, loads the module contain‐
364 ing the main/1 function into the debugger, sets a breakpoint in
365 main/1, and invokes main/1. If the module is precompiled, it must
366 be explicitly compiled with option debug_info.
367 -i:
369 Interprets the escript regardless of the value of the mode
370 attribute.
371 -s:
373 Performs a syntactic and semantic check of the script file. Warn‐
374 ings and errors (if any) are written to the standard output, but
375 the script will not be run. The exit status is 0 if any errors are
376 found, otherwise 127.
377 -n:
379 Compiles the escript using flag +native.
380Ericsson AB erts 10.7.1 escript(1)