Skip to main content

erlang_escript

name​

def name(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    _toolchain: str = ...,
    configs: list[str] = ...,
    contacts: list[str] = ...,
    deps: list[str],
    emu_args: list[str] = ...,
    include_priv: bool = ...,
    labels: list[str] = ...,
    main_module: None | str = ...,
    os_env: None | dict[str, str] = ...,
    resources: list[str] = ...,
    script_name: None | str = ...,
) -> None

The erlang_escript target builds and runs bundled escripts. Please refer to the OTP documentation for more details about escripts.

Parameters​

  • name: name of the target

  • default_target_platform: specifies the default target platform, used when no platforms are specified on the command line

  • target_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration

  • compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration

  • exec_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with an execution platform

  • visibility: a list of visibility patterns restricting what targets can depend on this one

  • within_view: a list of visibility patterns restricting what this target can depend on

  • metadata: a key-value map of metadata associated with this target

  • tests: a list of targets that provide tests for this one

  • modifiers: an array of modifiers associated with this target

  • configs: This attribute allows to set config files for the escript. The dependencies that are typically used here are export_file targets.

  • deps: List of Erlang applications that are bundled in the escript. This includes all transitive dependencies as well.

  • emu_args: This field specifies the emulator flags that the escript uses on execution. It is often desirable to specify the number of threads and schedulers the escript uses. Please refer to the OTP documentation for details.

  • include_priv: Setting this flag, will package the applications priv directory in the escript. Similar to files added through the resources field, the priv folders files can then be accessed by escript"extract/2.

  • main_module: Overrides the default main module. Instead of deferring the main module from the scripts filename, the specified module is used. That module needs to export a main/1 function that is called as entry point.

  • os_env: This attribute allows to set additional values for the operating system environment for invocations to the Erlang toolchain.

  • resources: This adds the targets default output to the escript archive. To access these files, you need to use escript:extract/2, which will extract the entire escript in memory. The relevant files can then be accessed through the archive section.

    Please refer to the escript:extract/2 for more details.

  • script_name: Overrides the filename of the produced escript.

Details​

Escripts by default always try to use the module that has the same name as the escripts basename as entry point, e.g. if the escript is called script.escript then running the escript will try to call script:main/1. Both name and main module can be overwritten though.

The target name doubles as the default escript name. If the main_module attribute is not used, the escript filename will be <name>.escript.

Examples:

erlang_escript(
    name = "script",
    main_module = "main_module",
    script_name = "the_script",
    deps = [
        ":escript_app",
    ],
    emu_args = ["+sbtu", "+A1"],
)

erlang_application(
    name = "escript_app",
    srcs = ["src/main_module.erl"],
    applications = [
        "kernel",
        "stdlib",
    ],
)