erlang_app

This rule is the main rule for Erlang applications. It gets generated by using the erlang_application macro, that takes as attributes the same attributes as this rule. You should always use the erlang_application macro instead of using this rule directly.

Details

Erlang Applications are the basic building block of our buck2 integration and used by many other Erlang targets, e.g. erlang_escript, erlang_test, or erlang_release.

The erlang_application targets build OTP applications and as such many attributes that are used have equivalent meaning to the fields in the currently (by rebar3) used *.app.src files and OTP *.app files. Please familiarize yourself with the semantics of these fields by consulting the OTP documentation.

The target enforces uniqueness during builds, and fails to build if duplicated artifacts in the global namespaces are detected:

• duplicated application names in the dependencies
• duplicated module names across any of the applications or dependencies modules
• ambiguity when resolving header files

The default output of this rule is the application folder of the target application and all transitive dependencies.

Function Signature

def erlang_app(
    *,
    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] = {},
    _includes_target: None | str = None,
    _toolchain: str = "gh_facebook_buck2_shims_meta//:erlang-default",
    app_name: None | str = None,
    app_src: None | str = None,
    applications: list[str] = [],
    contacts: list[str] = [],
    env: None | dict[str, str] = None,
    erl_opts: None | list[str] = None,
    extra_includes: list[str] = [],
    extra_properties: None | dict[str, str | list[str]] = None,
    include_src: bool = True,
    included_applications: list[str] = [],
    includes: list[str] = [],
    labels: list[str] = [],
    mod: None | (str, str) = None,
    os_env: None | dict[str, str] = None,
    peek_private_includes: bool = False,
    resources: list[str] = [],
    shell_configs: list[str] = [],
    shell_libs: list[str] = ["prelude//erlang/shell:buck2_shell_utils"],
    srcs: list[str] = [],
    use_global_parse_transforms: bool = True,
    version: str = "1.0.0",
    xrl_includefile: None | str = None,
    yrl_includefile: 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

• _includes_target: (defaults to: None)

  Internal, used by the erlang_application macro to link the proper application target and include_only targets.

• app_name: (defaults to: None)

  This attribute allows the user to overwrite the Erlang application name, which otherwise defaults to the target name.

• app_src: (defaults to: None)

  The app_src field allows to optionally reference a *.app.src template file. This template file will then be used by buck2 to generate the *.app output file in the applications ebin/ directory. This is useful during the migration from rebar3 to buck2 to avoid duplicated entries, of e.g. the version.

  Buck2 will use or check all fields present in the template, and fill out the fields with the information provided in the target, e.g. if the version is specified in both, buck2 will check that they are identical. Otherwise, it uses the information from the template if the target doesn't specify it, and vice versa.

  NOTE: If you use the app_src field and the references application resource file template specifies applications or included_applications buck2 checks that the target definitions and information in the template are equivalent to prevent these definitions from drifting apart during migration.

• applications: (defaults to: [])

  Equivalent to the corresponding applications and included_applications fields you will find in *.app.src or *.app files and specify the application dependencies. Contrary to the fields in the *.app.src or *.app files, it is necessary to use target paths to the application where a dependency is desired. These fields will be used to construct equally named fields in the generated *.app file for the application.

  OTP applications are specified with the target path prelude//erlang/applications:<application>.

  NOTE: If you use the app_src field and the references application resource file template specifies applications or included_applications buck2 checks that the target definitions and information in the template are equivalent to prevent these definitions from drifting apart during migration.

• env: (defaults to: None)

  The env field allows to set the application env variables. The key value pairs will materialise in the application's .app file and can then be accessed by application:get_env/2.

• erl_opts: (defaults to: None)

  Typically compile options are managed by global config files, however, sometimes it is desirable to overwrite the pre-defined compile options. The erl_opts field allows developers to do so for individual applications.

  The main use-case are the applications listed in third-party/. This option should not be used by other applications without consultation. Please ask in the WhatsApp Dev Infra Q&A workplace group for support.

• extra_includes: (defaults to: [])

  In some cases we might have the situation, where an application app_a depends through the applications and included_applications fields on application app_b and a source file in app_b includes a header file from app_a (e.g. -include_lib("app_a/include/header.hrl). This technically creates circular dependency from app_a to app_b (e.g. via applications field) and back from app_b to app_a (via -include_lib). To break the dependency developers can specify targets in the extra_includes field, whose public include files are accessible to the application target during build time.

  Only the includes of the specified application are available and eventual transitive dependencies need to be managed manually.

  NOTE: It is not possible (or even desired) to add OTP applications with this field.

  NOTE: This mechanism is added to circumvent unclean dependency relationships and the goal for developers should be to reduce usages of this field. DO NOT ADD ANY MORE USAGES!!

• extra_properties: (defaults to: None)

  The extra_properties field can be used to specify extra key-value pairs which is are not defined in application_opt(). The key-value pair will be stored in the applications .app file and can be accessed by file:consult/1.

• include_src: (defaults to: True)

  This field controls if the generated application directory contains a src/ directory with the Erlang code or not.

• included_applications: (defaults to: [])

  Check the documentation for applications.

• includes: (defaults to: [])

  The public header files accessible via -include_lib("appname/include/header.hrl") from other erlang files.

• mod: (defaults to: None)

  The mod field specifies the equivalent field in the generated *.app files. The format is similar, with the difference, that the module name, and the individual start arguments need to be given as the string representation of the corresponding Erlang terms.

• os_env: (defaults to: None)

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

• peek_private_includes: (defaults to: False)

  This attribute allows you to use the private includes of the application's dependencies. This can be useful for test applications, to create shared abstractions for tests. It's not advisable to use this attribute for prodution code. All private includes transitively must be non-ambiguous.

• resources: (defaults to: [])

  The resources field specifies targets whose default output are placed in the applications priv/ directory. For regular files this field is typically combined with export_file, filegroup, or similar targets. However, it is general, and any target can be used, e.g. if you want to place a built escript in the priv/ directory, you can use an erlang_escript target.

• shell_configs: (defaults to: [])

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

• shell_libs: (defaults to: ["prelude//erlang/shell:buck2_shell_utils"])

  This attribute allows to define additional dependencies for the shell. By default this is set to ["prelude//erlang/shell:buck2_shell_utils"] which includes a user_default module that loads and compiles modules with buck2 mechanisms.

• srcs: (defaults to: [])

  A list of *.erl, *.hrl, *.xrl, or *.yrl source inputs that are typically located in an application's src/ folder. Header files (i.e. *.hrl files) specified in this field are considered application private headers, and can only be accessed by the *.erl files of the application itself. *.xrl and *.yrl files are processed into *.erl files before all *.erl files are compiled into *.beam files.

• use_global_parse_transforms: (defaults to: True)

  This field indicates if global parse_tranforms should be applied to this application as well. It often makes sense for third-party dependencies to not be subjected to global parse_transforms, similar to OTP applications.

• version: (defaults to: "1.0.0")

  The version field specifies the applications version that is materialized as vsn field in the generated *.app file. If you use the the app_src field and specify a version in the referenced template in addition to the version field, the versions need to be identical.

  If no version is specified in either the app_src template or the version field, a fallback version string of "1.0.0" is used.

• xrl_includefile: (defaults to: None)

  Customised prologue file to replace the default. See includefile option for details.

• yrl_includefile: (defaults to: None)

  Customised prologue file to replace the default. See includefile option for details.

Examples

Minimal Erlang Application

erlang_application(
    name = "minimal",
)

With priv/ directory

erlang_application(
    name = "app_a",
    srcs = [
        "src/app_a.erl",
    ],
    includes = [],
    applications = [
        ":app_b",
    ],
    app_src = "src/app_a.app.src",
    resources = [
        ":readme",
    ],
)

export_file(
    name = "readme",
    src = "README.md",
)

Using OTP applications and mod field

erlang_application(
    name = "app_b",
    srcs = [
        "src/app_b.erl",
        "src/app_b.hrl",
    ],
    includes = [],
    applications = [
        "kernel",
        "stdlib",
        ":app_c",
    ],
    mod = ("app_b", [
        "some_atom",
        ""some string"",
        "{tagged_tuple, 42}",
    ]),
)

Using Yecc and Leex

erlang_application(
    name = "yecc_leex",
    srcs = [
        "src/leex_stub.xrl",
        "src/yecc_stub.yrl",
    ],
)