erlang_app
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] = ...,
_includes_target: None | str = ...,
_toolchain: str = ...,
app_name: None | str = ...,
app_src: None | str = ...,
applications: list[str] = ...,
contacts: list[str] = ...,
env: None | dict[str, str] = ...,
erl_opts: None | list[str] = ...,
extra_includes: list[str] = ...,
extra_properties: None | dict[str, str | list[str]] = ...,
include_src: bool = ...,
included_applications: list[str] = ...,
includes: list[str] = ...,
labels: list[str] = ...,
mod: None | (str, str) = ...,
os_env: None | dict[str, str] = ...,
peek_private_includes: bool = ...,
resources: list[str] = ...,
shell_configs: list[str] = ...,
shell_libs: list[str] = ...,
srcs: list[str] = ...,
use_global_parse_transforms: bool = ...,
version: str = ...,
xrl_includefile: None | str = ...,
yrl_includefile: None | str = ...,
) -> None
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.
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 -
_includes_target
: Internal, used by theerlang_application
macro to link the proper application target and include_only targets. -
app_name
: This attribute allows the user to overwrite the Erlang application name, which otherwise defaults to the target name. -
app_src
: Theapp_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 applicationsebin/
directory. This is useful during the migration from rebar3 to buck2 to avoid duplicated entries, of e.g. theversion
.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 specifiesapplications
orincluded_applications
buck2 checks that the target definitions and information in the template are equivalent to prevent these definitions from drifting apart during migration. -
applications
: Equivalent to the correspondingapplications
andincluded_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 specifiesapplications
orincluded_applications
buck2 checks that the target definitions and information in the template are equivalent to prevent these definitions from drifting apart during migration. -
env
: Theenv
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 byapplication:get_env/2
. -
erl_opts
: Typically compile options are managed by global config files, however, sometimes it is desirable to overwrite the pre-defined compile options. Theerl_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
: In some cases we might have the situation, where an applicationapp_a
depends through theapplications
andincluded_applications
fields on applicationapp_b
and a source file inapp_b
includes a header file fromapp_a
(e.g.-include_lib("app_a/include/header.hrl
). This technically creates circular dependency fromapp_a
toapp_b
(e.g. viaapplications
field) and back fromapp_b
toapp_a
(via-include_lib
). To break the dependency developers can specify targets in theextra_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
: 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 byfile:consult/1
. -
include_src
: This field controls if the generated application directory contains a src/ directory with the Erlang code or not. -
included_applications
: Check the documentation forapplications
. -
includes
: The public header files accessible via-include_lib("appname/include/header.hrl")
from other erlang files. -
mod
: Themod
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
: This attribute allows to set additional values for the operating system environment for invocations to the Erlang toolchain. -
peek_private_includes
: 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
: Theresources
field specifies targets whose default output are placed in the applicationspriv/
directory. For regular files this field is typically combined withexport_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 thepriv/
directory, you can use anerlang_escript
target. -
shell_configs
: This attribute allows to set config files for the shell. The dependencies that are typically used here areexport_file
targets. -
shell_libs
: This attribute allows to define additional dependencies for the shell. By default this is set to["prelude//erlang/shell:buck2_shell_utils"]
which includes auser_default
module that loads and compiles modules with buck2 mechanisms. -
srcs
: A list of*.erl
,*.hrl
,*.xrl
, or*.yrl
source inputs that are typically located in an application'ssrc/
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
: 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
: Theversion
field specifies the applications version that is materialized asvsn
field in the generated*.app
file. If you use the theapp_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 theversion
field, a fallback version string of"1.0.0"
is used. -
xrl_includefile
: Customised prologue file to replace the default. Seeincludefile
option for details. -
yrl_includefile
: Customised prologue file to replace the default. Seeincludefile
option for details.
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.
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",
],
)