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 script's 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 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

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              %%! -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 in‐
72              terpreter line, which invokes escript.
73
74              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
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              %%! -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   es‐
137              cript: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  in‐
149              cluding  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 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
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.
171
172              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
179              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
192              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
198              $ 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
205       escript:create(FileOrBin, Sections) -> ok | {ok,  binary()}  |  {error,
206       term()}
207
208              Types:
209
210                 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
226              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
235              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
241              > 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
248              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
259              An escript without header can be created as follows:
260
261              > 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
276              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
280              > {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
307       escript:extract(File, Options) -> {ok, Sections} | {error, term()}
308
309              Types:
310
311                 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
323              Parses an escript and extracts its sections. This is the reverse
324              of create/2.
325
326              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
332              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
337              Example:
338
339              > 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
346       escript:script_name() -> File
347
348              Types:
349
350                 File = filename()
351
352              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

OPTIONS ACCEPTED BY ESCRIPT

357         -c:
358           Compiles the escript regardless of the value of the mode attribute.
359
360         -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
366         -i:
367           Interprets the escript regardless of the value of the  mode  attri‐
368           bute.
369
370         -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
376   Note:
377       The configuration of the Erlang emulator invoked by escript can be con‐
378       trolled using the  environment variables understood by erl.
379
380
381
382Ericsson AB                      erts 12.3.2.1                      escript(1)
Impressum