1escript(1) User Commands escript(1)
2
3
4
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
13 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
21 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
36 escript runs a script written in Erlang.
37
38 Example:
39
40 $ 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
57 usage() ->
58 io:format("usage: factorial integer\n"),
59 halt(1).
60
61 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
70 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
74 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
78 $ escript factorial 5
79
80 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
85 If a comment selecting the encoding exists, it can be located on
86 the second line.
87
88 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
93 io:setopts([{encoding, unicode}])
94
95 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
99
100 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
104 %%! -smp enable -sname factorial -mnesia debug verbose
105
106 Such an argument line must start with %%! and the remaining line
107 is interpreted as arguments to the emulator.
108
109 If you know the location of the escript executable, the first
110 line can directly give the path to escript, for example:
111
112 #!/usr/local/bin/escript
113
114 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
118 The remaining Erlang script file can either contain Erlang
119 source code, an inlined beam file, or an inlined archive file.
120
121 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
126 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
131 To return your own non-zero exit code, call halt(ExitCode), for
132 example:
133
134 halt(1).
135
136 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
140 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
145 -include_lib("kernel/include/file.hrl").
146
147 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
152 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
158 Both the module declaration and the export declaration of the
159 main/1 function are optional.
160
161 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
165 -mode(compile).
166
167 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
174 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
181 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
194 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
200 $ 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
207 escript:create(FileOrBin, Sections) -> ok | {ok, binary()} | {error,
208 term()}
209
210 Types:
211
212 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
228 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
237 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
243 > 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
250 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
261 An escript without header can be created as follows:
262
263 > 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
278 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
282 > {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
309 escript:extract(File, Options) -> {ok, Sections} | {error, term()}
310
311 Types:
312
313 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
325 Parses an escript and extracts its sections. This is the reverse
326 of create/2.
327
328 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
334 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
339 Example:
340
341 > 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
348 escript:script_name() -> File
349
350 Types:
351
352 File = filename()
353
354 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
362 -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
368 -i:
369 Interprets the escript regardless of the value of the mode
370 attribute.
371
372 -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
378 -n:
379 Compiles the escript using flag +native.
380
381
382
383Ericsson AB erts 10.3.5.2 escript(1)