1escript(1)                       User Commands                      escript(1)
2
3
4

NAME

6       escript - Erlang scripting support
7

DESCRIPTION

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

EXPORTS

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

OPTIONS ACCEPTED BY ESCRIPT

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)
Impressum