escript — stdlib v6.2.2.2

Search documentation of stdlib

# escript (stdlib v6.2.2.2)

View Source

This module provides functions to create and inspect escripts.

See the escript program documentation for more details on how to use escripts.

# Summary

## Types

comment()
emu_args()

Any arguments that should be passed to erl when starting.

extract_option()
section()
section_name()
shebang()

The initial `#!` line.

zip_file()

## Functions

create(File, Options)

Creates an escript from a list of sections.

extract(File, Options)

Parses an escript and extracts its sections. This is the reverse of `create/2`.

script_name()

Returns the name of the escript that is executed.

# Types

# comment()

(not exported)

    -type comment() :: string().

# emu_args()

(not exported)

    -type emu_args() :: string().

Any arguments that should be passed to erl when starting.

# extract_option()

(not exported)

    -type extract_option() :: compile_source | {section, [section_name()]}.

# section()

(not exported)

    -type section() ::
              shebang |
              {shebang, shebang() | default | undefined} |
              comment |
              {comment, comment() | default | undefined} |
              {emu_args, emu_args() | undefined} |
              {source, file:filename() | binary()} |
              {beam, file:filename() | binary()} |
              {archive, zip:filename() | binary()} |
              {archive, [zip_file()], [zip:create_option()]}.

# section_name()

(not exported)

    -type section_name() :: shebang | comment | emu_args | body.

# shebang()

(not exported)

    -type shebang() :: string().

The initial `#!` line.

For example:

    #!/usr/bin/env escript

# zip_file()

(not exported)

    -type zip_file() ::
              zip:filename() | {zip:filename(), binary()} | {zip:filename(), binary(), file:file_info()}.

# Functions

# create(File, Options)

    -spec create(file:filename() | binary(), [section()]) -> ok | {ok, binary()} | {error, term()}.

Creates an escript from a list of sections.

The sections can be specified in any order. An escript begins with an optional `Header` followed by a mandatory `Body`. If the header is present, it does always begin with a `shebang`, possibly followed by a `comment` and `emu_args`. The `shebang` defaults to `"/usr/bin/env escript"`. The `comment` defaults to `"This is an -*- erlang -*- file"`. The created escript can either be returned as a binary or written to file.

As an example of how the function can be used, we create an interpreted escript that uses `emu_args` to set some emulator flag. In this case, it happens to set number of schedulers with `+S3`. We also extract the different sections from the newly created script:

    > Source = "%% Demo\nmain(_Args) ->\n    io:format(\"~p\",[erlang:system_info(schedulers)]).\n".
    "%% Demo\nmain(_Args) ->\n    io:format(erlang:system_info(schedulers)).\n"
    > io:format("~s\n", [Source]).
    %% Demo
    main(_Args) ->
        io:format(erlang:system_info(schedulers)).

    ok
    > {ok, Bin} = escript:create(binary, [shebang, comment, {emu_args, "+S3"},
                                          {source, list_to_binary(Source)}]).
    {ok,<<"#!/usr/bin/env escript\n%% This is an -*- erlang -*- file\n%%!+S3"...>>}
    > file:write_file("demo.escript", Bin).
    ok
    > os:cmd("escript demo.escript").
    "3"
    > escript:extract("demo.escript", []).
    {ok,[{shebang,default}, {comment,default}, {emu_args,"+S3"},
         {source,<<"%% Demo\nmain(_Args) ->\n    io:format(erlang:system_info(schedu"...>>}]}

An escript without header can be created as follows:

    > file:write_file("demo.erl",
                      ["%% demo.erl\n-module(demo).\n-export([main/1]).\n\n", Source]).
    ok
    > {ok, _, BeamCode} = compile:file("demo.erl", [binary, debug_info]).
    {ok,demo,
        <<70,79,82,49,0,0,2,208,66,69,65,77,65,116,111,109,0,0,0,
          79,0,0,0,9,4,100,...>>}
    > escript:create("demo.beam", [{beam, BeamCode}]).
    ok
    > escript:extract("demo.beam", []).
    {ok,[{shebang,undefined}, {comment,undefined}, {emu_args,undefined},
         {beam,<<70,79,82,49,0,0,3,68,66,69,65,77,65,116,
                 111,109,0,0,0,83,0,0,0,9,...>>}]}
    > os:cmd("escript demo.beam").
    "true"

Here we create an archive script containing both Erlang code and Beam code, then we iterate over all files in the archive and collect their contents and some information about them:

    > {ok, SourceCode} = file:read_file("demo.erl").
    {ok,<<"%% demo.erl\n-module(demo).\n-export([main/1]).\n\n%% Demo\nmain(_Arg"...>>}
    > escript:create("demo.escript",
                     [shebang,
                      {archive, [{"demo.erl", SourceCode},
                                 {"demo.beam", BeamCode}], []}]).
    ok
    > {ok, [{shebang,default}, {comment,undefined}, {emu_args,undefined},
         {archive, ArchiveBin}]} = escript:extract("demo.escript", []).
    {ok,[{shebang,default}, {comment,undefined}, {emu_args,undefined},
         {{archive,<<80,75,3,4,20,0,0,0,8,0,118,7,98,60,105,
                    152,61,93,107,0,0,0,118,0,...>>}]}
    > file:write_file("demo.zip", ArchiveBin).
    ok
    > zip:foldl(fun(N, I, B, A) -> [{N, I(), B()} | A] end, [], "demo.zip").
    {ok,[{"demo.beam",
          {file_info,748,regular,read_write,
                     {{2010,3,2},{0,59,22}},
                     {{2010,3,2},{0,59,22}},
                     {{2010,3,2},{0,59,22}},
                     54,1,0,0,0,0,0},
          <<70,79,82,49,0,0,2,228,66,69,65,77,65,116,111,109,0,0,0,
            83,0,0,...>>},
         {"demo.erl",
          {file_info,118,regular,read_write,
                     {{2010,3,2},{0,59,22}},
                     {{2010,3,2},{0,59,22}},
                     {{2010,3,2},{0,59,22}},
                     54,1,0,0,0,0,0},
          <<"%% demo.erl\n-module(demo).\n-export([main/1]).\n\n%% Demo\nmain(_Arg"...>>}]}

# extract(File, Options)

    -spec extract(file:filename(), [extract_option()]) -> {ok, [section()]} | {error, term()}.

Parses an escript and extracts its sections. This is the reverse of `create/2`.

All sections are returned even if they do not exist in the escript. If a particular section happens to have the same value as the default value, the extracted value is set to the atom `default`. If a section is missing, the extracted value is set to the atom `undefined`.

Option `compile_source` only affects the result if the escript contains `source` code. In this case the Erlang code is automatically compiled and `{source, BeamCode}` is returned instead of `{source, SourceCode}`.

Example:

    > escript:create("demo.escript",
                     [shebang, {archive, [{"demo.erl", SourceCode},
                                          {"demo.beam", BeamCode}], []}]).
    ok
    > {ok, [{shebang,default}, {comment,undefined}, {emu_args,undefined},
         {archive, ArchiveBin}]} =
                  escript:extract("demo.escript", []).
    {ok,[{{archive,<<80,75,3,4,20,0,0,0,8,0,118,7,98,60,105,
                    152,61,93,107,0,0,0,118,0,...>>}
         {emu_args,undefined}]}

# script_name()

    -spec script_name() -> string().

Returns the name of the escript that is executed.

If the function is invoked outside the context of an escript, the behavior is undefined.