Skip to main content

erlang_escript

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

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.

Function Signature​

def erlang_escript(
    *,
    name: str,
    default_target_platform: None | str = None,
    target_compatible_with: list[str] = [],
    compatible_with: list[str] = [],
    exec_compatible_with: list[str] = [],
    visibility: list[str] = [],
    within_view: list[str] = ["PUBLIC"],
    metadata: OpaqueMetadata = {},
    tests: list[str] = [],
    modifiers: OpaqueMetadata = [],
    _apple_platforms: dict[str, str] = {},
    _toolchain: str = "gh_facebook_buck2_shims_meta//:erlang-default",
    configs: list[str] = [],
    contacts: list[str] = [],
    deps: list[str],
    emu_args: list[str] = [],
    include_priv: bool = False,
    labels: list[str] = [],
    main_module: None | str = None,
    os_env: None | dict[str, str] = None,
    resources: list[str] = [],
    script_name: None | str = None,
) -> None

Parameters​

  • name: (required)

    name of the target

  • default_target_platform: (defaults to: None)

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

  • target_compatible_with: (defaults to: [])

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

  • compatible_with: (defaults to: [])

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

  • exec_compatible_with: (defaults to: [])

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

  • visibility: (defaults to: [])

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

  • within_view: (defaults to: ["PUBLIC"])

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

  • metadata: (defaults to: {})

    a key-value map of metadata associated with this target

  • tests: (defaults to: [])

    a list of targets that provide tests for this one

  • modifiers: (defaults to: [])

    an array of modifiers associated with this target

  • configs: (defaults to: [])

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

  • deps: (required)

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

  • emu_args: (defaults to: [])

    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: (defaults to: False)

    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: (defaults to: None)

    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: (defaults to: None)

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

  • resources: (defaults to: [])

    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: (defaults to: None)

    Overrides the filename of the produced 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",
    ],
)