Chapter 11. Escripts

Escripts are an alternative to release. They are meant to be used for small command line executables written in Erlang.

They are not self-contained, unlike releases. Erlang must be installed for them to run. This however means that they are fairly small compared to releases.

For self-contained executables, check self-extracting releases.

11.1. Requirements uses p7zip by default to generate the escript archive. Make sure it is installed. On most systems the package is named p7zip; on Ubuntu you need p7zip-full.

If p7zip is unavailable, zip may be used by setting the ESCRIPT_ZIP variable. For example:

$ make escript ESCRIPT_ZIP=zip

11.2. Generating an escript

Run the following command to generate an escript:

$ make escript

This will by default create an escript with the same name as the project, in the project’s directory. If the project is called relx then the escript will be in ./relx.

You can run the escript as you would any executable:

$ ./relx

11.3. Configuration

You can change the name of the escript by setting ESCRIPT_NAME. The name determines both the default output file name and the entry module containing the function main/1.

ESCRIPT_FILE can be set if you need a different file name or location.

The escript header can be entirely customized. The first line is the shebang, set by ESCRIPT_SHEBANG. The second line is a comment, set by ESCRIPT_COMMENT. The third line is the arguments the VM will use when running the escript, set by ESCRIPT_EMU_ARGS.

Finally, ESCRIPT_ZIP can be set to customize the command used to create the zip file. Read on for more information.

11.4. Extra files

Generating an escript is a two-part process. First, a zip file is created with the contents of the escript. Then a header is added to this file to create the escript.

It is possible to add commands that will be executed between the two steps. You can for example add extra files to the zip archive:

    $(verbose) $(ESCRIPT_ZIP) $(ESCRIPT_ZIP_FILE) priv/templates/*

The ESCRIPT_ZIP variable contains the command to run to add files to the zip archive ESCRIPT_ZIP_FILE.

11.5. Optimizing for size will by default compile BEAM files with debug information. You may want to disable this behavior to obtain smaller escript files. Simply set ERLC_OPTS to a value that does not include +debug_info.