Rules
These rules are available as standard in Buck2.
def alias(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
actual: str,
buck2_compatibility: str = _,
contacts: list[str] = _,
default_host_platform: None | str = _,
labels: list[str] = _,
licenses: list[str] = _
) -> None
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this one
android_aar
def android_aar(
*,
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] = _,
_android_toolchain: str = _,
_apple_platforms: dict[str, str] = _,
_cxx_toolchain: str = _,
_is_building_android_binary: bool = _,
_is_force_single_cpu: bool = _,
_is_force_single_default_cpu: bool = _,
_java_toolchain: str = _,
_wip_java_plugin_arguments: dict[str, list[str]] = _,
abi_generation_mode: None | str = _,
annotation_processing_tool: None | str = _,
annotation_processor_deps: list[str] = _,
annotation_processor_params: list[str] = _,
annotation_processors: list[str] = _,
buck2_compatibility: str = _,
build_config_values: list[str] = _,
build_config_values_file: None | str = _,
compress_asset_libraries: bool = _,
contacts: list[str] = _,
cpu_filters: list[str] = _,
default_host_platform: None | str = _,
deps: list[str] = _,
enable_relinker: bool = _,
excluded_java_deps: list[str] = _,
extra_arguments: list[str] = _,
extra_kotlinc_arguments: list[str] = _,
friend_paths: list[str] = _,
include_build_config_class: bool = _,
java_version: None | str = _,
javac: None | str = _,
kotlin_compiler_plugins: dict[str, dict[str, str]] = _,
labels: list[str] = _,
language: None | str = _,
licenses: list[str] = _,
manifest: None | str = _,
manifest_file: None | str = _,
manifest_skeleton: str,
maven_coords: None | str = _,
min_sdk_version: None | int = _,
native_library_merge_code_generator: None | str = _,
native_library_merge_glue: None | str = _,
native_library_merge_linker_args: None | dict[str, list[str]] = _,
native_library_merge_localized_symbols: None | list[str] = _,
native_library_merge_map: None | dict[str, list[str]] = _,
native_library_merge_sequence: None | list[typing.Any] = _,
native_library_merge_sequence_blocklist: None | list[str] = _,
never_mark_as_unused_dependency: None | bool = _,
on_unused_dependencies: None | str = _,
package_asset_libraries: bool = _,
package_resources: bool = _,
plugins: list[str] = _,
proguard_config: None | str = _,
relinker_extra_deps: list[str] = _,
relinker_whitelist: list[str] = _,
remove_classes: list[str] = _,
required_for_source_only_abi: bool = _,
resource_union_package: None | str = _,
resources: list[str] = _,
resources_root: None | str = _,
runtime_deps: list[str] = _,
source: None | str = _,
source_abi_verification_mode: None | str = _,
source_only_abi_deps: list[str] = _,
srcs: list[str] = _,
strip_libraries: bool = _,
target: None | str = _,
use_jvm_abi_gen: None | bool = _
) -> None
An android_aar()
rule is used to generate an Android AAR.
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this onebuild_config_values
: See the documentation on the values argument forandroid_build_config()
.include_build_config_class
: Whether to include theBuildConfig
class files in the final .aar file. Needs to be set toTrue
if any build_config_values are specified. This is normally only needed if the build tool that is consuming the .aar file does not generateBuildConfig
classes. Note: the AAR format does not specify a way to pass defaults that should be injected into the finalBuildConfig
class, therefore that information might need to be replicated manually in the build that's consuming the .aar file.manifest_skeleton
: The skeleton manifest file used to generate the finalAndroidManifest.xml
. May either be a file or anandroid_manifest()
target.remove_classes
: List of classes to remove from the output aar. It removes classes from the target's own sources, and its dependencies.
Details
See the official Android documentation for details about the .aar
format.
Examples:
android_resource(
name = 'res',
res = 'res',
assets = 'assets',
package = 'com.example',
)
android_library(
name = 'lib',
srcs = glob(['**/*.java']),
)
android_aar(
name = 'app',
manifest_skeleton = 'AndroidManifestSkeleton.xml',
deps = [
':res',
':lib',
],
)
android_app_modularity
def android_app_modularity(
*,
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] = _,
_android_toolchain: str = _,
_apple_platforms: dict[str, str] = _,
_build_only_native_code: bool = _,
application_module_blacklist: None | list[str] = _,
application_module_configs: dict[str, list[str]] = _,
application_module_dependencies: None | dict[str, list[str]] = _,
buck2_compatibility: str = _,
contacts: list[str] = _,
default_host_platform: None | str = _,
deps: list[str] = _,
labels: list[str] = _,
licenses: list[str] = _,
no_dx: list[str] = _,
should_include_classes: bool = _,
should_include_libraries: bool = _
) -> None
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this one
android_binary
def android_binary(
*,
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] = _,
_android_toolchain: str = _,
_apple_platforms: dict[str, str] = _,
_cxx_toolchain: str = _,
_dex_toolchain: str = _,
_exec_os_type: str = _,
_is_building_android_binary: bool = _,
_is_force_single_cpu: bool = _,
_is_force_single_default_cpu: bool = _,
_java_toolchain: str = _,
aapt2_keep_raw_values: bool = _,
aapt2_locale_filtering: bool = _,
aapt2_preferred_density: None | str = _,
aapt_mode: str = _,
additional_aapt_params: list[str] = _,
allow_r_dot_java_in_secondary_dex: bool = _,
allowed_duplicate_resource_types: list[str] = _,
android_sdk_proguard_config: None | str = _,
application_module_blacklist: None | list[str] = _,
application_module_configs: dict[str, list[str]] = _,
application_module_dependencies: None | dict[str, list[str]] = _,
asset_compression_algorithm: None | str = _,
banned_duplicate_resource_types: list[str] = _,
buck2_compatibility: str = _,
build_config_values: list[str] = _,
build_config_values_file: None | str = _,
build_string_source_map: bool = _,
compress_asset_libraries: bool = _,
constraint_overrides: list[str] = _,
contacts: list[str] = _,
cpu_filters: list[str] = _,
default_host_platform: None | str = _,
deps: list[str] = _,
dex_compression: None | str = _,
dex_group_lib_limit: int = _,
dex_tool: str = _,
disable_pre_dex: bool = _,
duplicate_resource_behavior: str = _,
duplicate_resource_whitelist: None | str = _,
enable_relinker: bool = _,
exopackage_modes: list[str] = _,
extra_filtered_resources: list[str] = _,
extra_no_compress_asset_extensions: list[str] = _,
field_ref_count_buffer_space: int = _,
ignore_aapt_proguard_config: bool = _,
includes_vector_drawables: bool = _,
is_cacheable: bool = _,
is_voltron_language_pack_enabled: bool = _,
keystore: str,
labels: list[str] = _,
licenses: list[str] = _,
linear_alloc_hard_limit: int = _,
locales: list[str] = _,
manifest: None | str = _,
manifest_entries: dict[str, typing.Any] = _,
manifest_skeleton: None | str = _,
method_ref_count_buffer_space: int = _,
min_sdk_version: None | int = _,
minimize_primary_dex_size: bool = _,
module_manifest_skeleton: None | str = _,
native_library_merge_code_generator: None | str = _,
native_library_merge_glue: None | str = _,
native_library_merge_linker_args: None | dict[str, list[str]] = _,
native_library_merge_localized_symbols: None | list[str] = _,
native_library_merge_map: None | dict[str, list[str]] = _,
native_library_merge_sequence: None | list[typing.Any] = _,
native_library_merge_sequence_blocklist: None | list[str] = _,
no_auto_add_overlay_resources: bool = _,
no_auto_version_resources: bool = _,
no_dx: list[str] = _,
no_version_transitions_resources: bool = _,
optimization_passes: int = _,
package_asset_libraries: bool = _,
package_type: str = _,
packaged_locales: list[str] = _,
packaging_options: dict[str, list[str]] = _,
post_filter_resources_cmd: None | str = _,
preprocess_java_classes_bash: None | str = _,
preprocess_java_classes_cmd: None | str = _,
preprocess_java_classes_deps: list[str] = _,
primary_dex_patterns: list[str] = _,
proguard_config: None | str = _,
proguard_jvm_args: list[str] = _,
relinker_extra_deps: list[str] = _,
relinker_whitelist: list[str] = _,
resource_compression: str = _,
resource_filter: list[str] = _,
resource_stable_ids: None | str = _,
resource_union_package: None | str = _,
secondary_dex_weight_limit: None | int = _,
skip_crunch_pngs: None | bool = _,
skip_proguard: bool = _,
strip_libraries: bool = _,
trim_resource_ids: bool = _,
use_split_dex: bool = _,
validation_deps: list[str] = _,
xz_compression_level: int = _
) -> None
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this one
android_build_config
def android_build_config(
*,
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] = _,
_android_toolchain: str = _,
_apple_platforms: dict[str, str] = _,
_build_only_native_code: bool = _,
_is_building_android_binary: bool = _,
_java_toolchain: str = _,
buck2_compatibility: str = _,
contacts: list[str] = _,
default_host_platform: None | str = _,
labels: list[str] = _,
licenses: list[str] = _,
package: str = _,
values: list[str] = _,
values_file: None | str = _
) -> None
An android_build_config()
rule is used to generate a BuildConfig
class with global configuration variables that other android_library()
rules can compile against. Currently, the only variable exposed by BuildConfig
is a global boolean
named DEBUG
, much like the BuildConfig.java
generated by the official Android build tools based on Gradle.
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this onepackage
: Name of the Java package to use in the generatedBuildConfig.java
file. Most developers set this to the application id declared in the manifest via<manifest package="APP_ID">
. Example:com.facebook.orca
.values
: List of strings that defines additional fields (and values) that should be declared in the generatedBuildConfig.java
file. LikeDEBUG
, the values will be non-constant-expressions that evaluate to the value specified in the file at compilation time. To override the values in an APK, specify build_config_values or build_config_values_file inandroid_binary()
.values_file
: Optional path to a file that defines additional fields (and values) that should be declared in the generatedBuildConfig.java
file. LikeDEBUG
, the values will be non-constant-expressions that evaluate to the value specified in the file at compilation time. To override the values in an APK, specify build_config_values or build_config_values_file inandroid_binary()
.Note that values_file can be a generated file, as can build_config_values_file as demonstrated in the example below.
Details
The fields in the generated BuildConfig
class will
be non-constant-expressions (see JLS 15.28).
However, if BuildConfig
is packaged into an APK, it will
be replaced with a new version where:
- The fields will be set to literal values (i.e., constant expressions).
- The
boolean BuildConfig.DEBUG
field will correspond to that of thepackage_type
argument to theandroid_binary()
rule that is packaging it.
This transformation is done before ProGuard is applied (if applicable), so
that it can propagate constants from BuildConfig
and eliminate
dead code.
Examples:
Here is an example of an android_build_config()
rule that
is transitively included by both debug and release versions
of an android_binary()
rule. The value
of com.example.pkg.BuildConfig.DEBUG
will be different in each APK
even though they both transitively depend on the same :build_config
rule.
android_build_config(
name = 'build_config',
package = 'com.example.pkg',
values = [
'String COMMIT_ID = "0000000000000000000000000000000000000000"',
],
)
# The .java files in this library may contain references to the boolean
# com.example.pkg.BuildConfig.DEBUG because :build_config is in the deps.
# It could also reference BuildConfig.COMMIT_ID.
android_library(
name = 'mylib',
srcs = glob(['src/**/*.java']),
deps = [
':build_config',
],
)
android_binary(
name = 'debug',
package_type = 'DEBUG',
keystore = '//keystores:debug',
manifest = 'AndroidManifest.xml',
target = 'Google Inc.:Google APIs:19',
deps = [
':mylib',
],
)
# The contents of the file generated by this rule might be:
#
# String COMMIT_ID = "7bf804bdf71fdbfc99cce3b155b3643f022c6fa4"
#
# Note that the output of :build_config_release_values will be cached by Buck.
# Assuming that generate_release_build_config.py depends on state that is not
# expressed by its deps (which violates a fundamental invariant in Buck!), a
# workaround is to ensure that the inputs to :build_config_release_values are
# changed in some way before :release is built to ensure that the output from
# :build_config_release_values is not pulled from cache. For example:
#
# $ buck build :release
# $ uuidgen > dummy_state_file.txt
# $ buck build :release
#
# This makes sure that generate_release_build_config.py is re-run before
# :release is rebuilt. This is much cheaper than deleting your build cache
# before rebuilding.
genrule(
name = 'build_config_release_values',
srcs = [ 'generate_release_build_config.py', 'dummy_state_file.txt' ],
bash = 'generate_release_build_config.py $OUT',
out = 'build_config_release_values.txt',
)
android_binary(
name = 'release',
package_type = 'RELEASE',
keystore = '//keystores:release',
manifest = 'AndroidManifest.xml',
target = 'Google Inc.:Google APIs:19',
build_config_values_file = ':build_config_release_values',
deps = [
':mylib',
],
)
android_bundle
def android_bundle(
*,
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] = _,
_android_toolchain: str = _,
_apple_platforms: dict[str, str] = _,
_cxx_toolchain: str = _,
_dex_toolchain: str = _,
_exec_os_type: str = _,
_is_building_android_binary: bool = _,
_is_force_single_cpu: bool = _,
_is_force_single_default_cpu: bool = _,
_java_toolchain: str = _,
aapt2_keep_raw_values: bool = _,
aapt2_locale_filtering: bool = _,
aapt2_preferred_density: None | str = _,
aapt_mode: str = _,
additional_aapt_params: list[str] = _,
allow_r_dot_java_in_secondary_dex: bool = _,
allowed_duplicate_resource_types: list[str] = _,
android_sdk_proguard_config: None | str = _,
application_module_blacklist: None | list[str] = _,
application_module_configs: dict[str, list[str]] = _,
application_module_dependencies: None | dict[str, list[str]] = _,
asset_compression_algorithm: None | str = _,
banned_duplicate_resource_types: list[str] = _,
buck2_compatibility: str = _,
build_config_values: list[str] = _,
build_config_values_file: None | str = _,
build_string_source_map: bool = _,
bundle_config_file: None | str = _,
compress_asset_libraries: bool = _,
contacts: list[str] = _,
cpu_filters: list[str] = _,
default_host_platform: None | str = _,
deps: list[str] = _,
dex_compression: None | str = _,
dex_group_lib_limit: int = _,
dex_tool: str = _,
disable_pre_dex: bool = _,
duplicate_resource_behavior: str = _,
duplicate_resource_whitelist: None | str = _,
enable_relinker: bool = _,
exopackage_modes: list[str] = _,
extra_filtered_resources: list[str] = _,
extra_no_compress_asset_extensions: list[str] = _,
field_ref_count_buffer_space: int = _,
ignore_aapt_proguard_config: bool = _,
includes_vector_drawables: bool = _,
is_cacheable: bool = _,
is_voltron_language_pack_enabled: bool = _,
keystore: str,
labels: list[str] = _,
licenses: list[str] = _,
linear_alloc_hard_limit: int = _,
locales: list[str] = _,
manifest: None | str = _,
manifest_entries: dict[str, typing.Any] = _,
manifest_skeleton: None | str = _,
method_ref_count_buffer_space: int = _,
min_sdk_version: None | int = _,
minimize_primary_dex_size: bool = _,
module_manifest_skeleton: None | str = _,
native_library_merge_code_generator: None | str = _,
native_library_merge_glue: None | str = _,
native_library_merge_linker_args: None | dict[str, list[str]] = _,
native_library_merge_localized_symbols: None | list[str] = _,
native_library_merge_map: None | dict[str, list[str]] = _,
native_library_merge_sequence: None | list[typing.Any] = _,
native_library_merge_sequence_blocklist: None | list[str] = _,
no_auto_add_overlay_resources: bool = _,
no_auto_version_resources: bool = _,
no_dx: list[str] = _,
no_version_transitions_resources: bool = _,
optimization_passes: int = _,
package_asset_libraries: bool = _,
package_type: str = _,
packaged_locales: list[str] = _,
packaging_options: dict[str, list[str]] = _,
post_filter_resources_cmd: None | str = _,
preprocess_java_classes_bash: None | str = _,
preprocess_java_classes_cmd: None | str = _,
preprocess_java_classes_deps: list[str] = _,
primary_dex_patterns: list[str] = _,
proguard_config: None | str = _,
proguard_jvm_args: list[str] = _,
relinker_extra_deps: list[str] = _,
relinker_whitelist: list[str] = _,
resource_compression: str = _,
resource_filter: list[str] = _,
resource_stable_ids: None | str = _,
resource_union_package: None | str = _,
secondary_dex_weight_limit: None | int = _,
skip_crunch_pngs: None | bool = _,
skip_proguard: bool = _,
trim_resource_ids: bool = _,
use_derived_apk: bool = _,
use_split_dex: bool = _,
validation_deps: list[str] = _,
xz_compression_level: int = _
) -> None
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this one
android_instrumentation_apk
def android_instrumentation_apk(
*,
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] = _,
_android_toolchain: str = _,
_apple_platforms: dict[str, str] = _,
_dex_toolchain: str = _,
_exec_os_type: str = _,
_is_building_android_binary: bool = _,
_is_force_single_cpu: bool = _,
_is_force_single_default_cpu: bool = _,
_java_toolchain: str = _,
aapt_mode: str = _,
apk: str,
buck2_compatibility: str = _,
contacts: list[str] = _,
cpu_filters: list[str] = _,
default_host_platform: None | str = _,
deps: list[str] = _,
dex_tool: str = _,
disable_pre_dex: bool = _,
includes_vector_drawables: bool = _,
is_self_instrumenting: bool = _,
labels: list[str] = _,
licenses: list[str] = _,
manifest: None | str = _,
manifest_skeleton: None | str = _,
min_sdk_version: None | int = _,
native_library_merge_map: None | dict[str, list[str]] = _,
native_library_merge_sequence: None | list[typing.Any] = _,
preprocess_java_classes_bash: None | str = _,
preprocess_java_classes_cmd: None | str = _,
preprocess_java_classes_deps: list[str] = _,
primary_dex_patterns: list[str] = _,
use_split_dex: None | bool = _
) -> None
An android_instrumentation_apk()
rule is used to generate an Android Instrumentation APK.
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this one
Details
Android's Testing Fundamentals documentation includes a diagram that shows the relationship between an "application package" and a "test package" when running a test. This rule corresponds to a test package. Note that a test package has an interesting quirk where it is compiled against an application package, but must not include the resources or Java classes of the application package. Therefore, this class takes responsibility for making sure the appropriate bits are excluded. Failing to do so will generate mysterious runtime errors when running the test.
Examples:
Here is an example of an android_instrumentation_apk()
rule that tests an android_binary()
, and depends on a test
package.
android_library(
name = 'test',
srcs = glob(['test/**/*.java']),
)
android_binary(
name = 'messenger',
manifest = 'AndroidManifest.xml',
keystore = '//keystores:prod',
package_type = 'release',
proguard_config = 'proguard.cfg',
deps = [
...
],
)
# Building this rule will produce a file named messenger_test.apk
android_instrumentation_apk(
name = 'messenger_test',
manifest = 'AndroidInstrumentationManifest.xml',
apk = ':messenger',
deps = [
':test',
],
)
android_instrumentation_test
def android_instrumentation_test(
*,
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] = _,
_android_toolchain: str = _,
_apple_platforms: dict[str, str] = _,
_exec_os_type: str = _,
_inject_test_env: str = _,
_java_test_toolchain: str = _,
_java_toolchain: str = _,
apk: str,
buck2_compatibility: str = _,
clear_package_data: bool = _,
collect_tombstones: bool = _,
contacts: list[str] = _,
default_host_platform: None | str = _,
disable_animations: bool = _,
env: dict[str, str] = _,
extra_instrumentation_args: None | dict[str, str] = _,
instrumentation_test_listener: None | str = _,
instrumentation_test_listener_class: None | str = _,
is_self_instrumenting: bool = _,
labels: list[str] = _,
licenses: list[str] = _,
log_extractors: dict[str, str] = _,
re_caps: None | dict[str, dict[str, str]] = _,
re_use_case: None | dict[str, str] = _,
record_video: bool = _,
test_rule_timeout_ms: None | int = _
) -> None
An android_instrumentation_test()
rule is used to define apks that should be used to run Android instrumentation tests.
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this oneapk
: The APK containing the tests. Can be anandroid_binary()
, anapk_genrule()
or anandroid_instrumentation_apk()
.clear_package_data
: Runspm clear
on the app and test packages before the test run if set to True.collect_tombstones
: Checks whether the test generated any tombstones, and downloads them from the emulator if true.disable_animations
: Disables animations on the emulator if set to True.labels
: A list of labels to be applied to these tests. These labels are arbitrary text strings and have no meaning within buck itself. They can, however, have meaning for you as a test author (e.g.,smoke
orfast
). A label can be used to filter or include a specific test rule when executingbuck test
record_video
: Record video of test run and collect it as TRAtest_rule_timeout_ms
: If set specifies the maximum amount of time (in milliseconds) in which all of the tests in this rule should complete. This overrides the defaultrule_timeout
if any has been specified in.buckconfig
.
Details
Examples:
Here is an example of an android_instrumentation_test()
rule that tests an android_binary()
.
android_binary(
name = 'messenger',
manifest = 'AndroidManifest.xml',
keystore = '//keystores:prod',
package_type = 'release',
proguard_config = 'proguard.cfg',
deps = [
...
],
)
android_instrumentation_apk(
name = 'messenger_test',
manifest = 'AndroidInstrumentationManifest.xml',
apk = ':messenger',
deps = [
...
],
)
android_instrumentation_test(
name = 'messenger_instrumentation_test',
apk = ':messenger_test',
)
android_library
def android_library(
*,
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] = _,
_android_toolchain: str = _,
_apple_platforms: dict[str, str] = _,
_build_only_native_code: bool = _,
_compose_stability_config: None | str = _,
_dex_min_sdk_version: None | int = _,
_dex_toolchain: str = _,
_exec_os_type: str = _,
_is_building_android_binary: bool = _,
_java_toolchain: str = _,
_kotlin_toolchain: str = _,
_wip_java_plugin_arguments: dict[str, list[str]] = _,
abi_generation_mode: None | str = _,
android_optional_jars: None | list[str] = _,
annotation_processing_tool: None | str = _,
annotation_processor_deps: list[str] = _,
annotation_processor_params: list[str] = _,
annotation_processors: list[str] = _,
buck2_compatibility: str = _,
contacts: list[str] = _,
default_host_platform: None | str = _,
deps: list[str] = _,
exported_deps: list[str] = _,
exported_provided_deps: list[str] = _,
extra_arguments: list[str] = _,
extra_kotlinc_arguments: list[str] = _,
friend_paths: list[str] = _,
incremental: bool = _,
jar_postprocessor: None | str = _,
java_version: None | str = _,
javac: None | str = _,
k2: bool = _,
kotlin_compiler_plugins: dict[str, dict[str, str]] = _,
labels: list[str] = _,
language: None | str = _,
licenses: list[str] = _,
manifest: None | str = _,
manifest_file: None | str = _,
maven_coords: None | str = _,
never_mark_as_unused_dependency: None | bool = _,
on_unused_dependencies: None | str = _,
plugins: list[str] = _,
proguard_config: None | str = _,
provided_deps: list[str] = _,
provided_deps_query: None | str = _,
remove_classes: list[str] = _,
required_for_source_only_abi: bool = _,
resource_union_package: None | str = _,
resources: list[str] = _,
resources_root: None | str = _,
runtime_deps: list[str] = _,
source: None | str = _,
source_abi_verification_mode: None | str = _,
source_only_abi_deps: list[str] = _,
srcs: list[str] = _,
target: None | str = _,
use_jvm_abi_gen: None | bool = _,
validation_deps: list[str] = _
) -> None
An android_library()
rule is used to define a set of Java files that can be compiled together against the Android SDK. The main output of an android_library()
rule is a single JAR file containing all of the compiled class files and resources.
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this oneannotation_processing_tool
: Specifies the tool to use for annotation processing. Possible values: "kapt" or "javac". "kapt" allows running Java annotation processors against Kotlin sources while backporting it for Java sources too. "javac" works only against Java sources, Kotlin sources won't have access to generated classes at compile time.deps
: Rules (usually otherandroid_library
rules) that are used to generate the classpath required to compile thisandroid_library
.exported_deps
: Other rules that depend on this rule will also include itsexported_deps
in their classpaths. This is useful when the public API of a rule has return types or checked exceptions that are defined in another rule, which would otherwise require callers to add an extra dependency. It's also useful for exposing e.g. a collection ofprebuilt_jar
rules as a single target for callers to depend on. Targets inexported_deps
are implicitly included in thedeps
of this rule, so they don't need to be repeated there.exported_provided_deps
: This is a combination ofprovided_deps
andexported_deps
. Rules listed in this parameter will be added to classpath of rules that depend on this rule, but they will not be included in a binary if binary depends on a such target.extra_arguments
: List of additional arguments to pass into the Java compiler. These arguments follow the ones specified in.buckconfig
.extra_kotlinc_arguments
: List of additional arguments to pass into the Kotlin compiler.incremental
: Enables Kotlin incremental compilation.k2
: Enables the Kotlin K2 compiler.manifest
: An optional Android Manifest for the to declare any permissions or intents it may need or want to handle. May either be a file or anandroid_manifest()
target.provided_deps
: These represent dependencies that are known to be provided at run time, but are required in order for the code to compile. Examples ofprovided_deps
include the JEE servlet APIs. When this rule is included in a , theprovided_deps
will not be packaged into the output.provided_deps_query
: Status: experimental/unstable. The provided deps query functions in the same way as the deps query, but the referenced deps using$declared
are the provided deps of the target, and the results of the query are appended to the declared provided deps.remove_classes
: List of classes to remove from the output jar. It only removes classes from the target's own sources, not from any of its dependencies.required_for_source_only_abi
: Indicates that this rule must be present on the classpath duringsource-only ABI generation
of any rule that depends on it. Typically this is done when a rule contains annotations, enums, constants, or interfaces.Having rules present on the classpath during source-only ABI generation prevents Buck from completely flattening the build graph, thus reducing the performance win from source-only ABI generation. These rules should be kept small (ideally just containing annotations, constants, enums, and interfaces) and with minimal dependencies of their own.
resources
: Static files to include among the compiled.class
files. These files can be loaded via Class.getResource().Note: Buck uses the
src_roots
property in.buckconfig
to help determine where resources should be placed within the generated JAR file.source
: Specifies the version of Java (as a string) to interpret source files as. Overrides the value in "source_level" in the "java" section of.buckconfig
.source_only_abi_deps
: These are dependencies that must be present duringsource-only ABI generation
. Typically such dependencies are added when some property of the code in this rule prevents source-only ABI generation from being correct without these dependencies being present.Having
source_only_abi_deps
prevents Buck from completely flattening the build graph, thus reducing the performance win from source-only ABI generation. They should be avoided when possible. Often only a small code change is needed to avoid them. For more information on such code changes, read aboutsource-only ABI generation
.srcs
: The set of.java
files to compile for this rule.target
: Specifies the version of Java (as a string) for which to generate code. Overrides the value in "target_level" in the "java" section of.buckconfig
.
Details
Examples:
An android_library
rule used in concert with an
android_resource()
rule.
This would be a common arrangement for a standard Android Library project
as defined by
http://developer.android.com/tools/projects/index.html
android_resource(
name = 'res',
res = 'res',
package = 'com.example',
)
android_library(
name = 'my_library',
srcs = glob(['src/**/*.java']),
deps = [
':res',
],
)
android_manifest
def android_manifest(
*,
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] = _,
_android_toolchain: str = _,
_apple_platforms: dict[str, str] = _,
buck2_compatibility: str = _,
contacts: list[str] = _,
default_host_platform: None | str = _,
deps: list[str] = _,
labels: list[str] = _,
licenses: list[str] = _,
skeleton: str
) -> None
An android_manifest()
rule is used to generate an Android Manifest to be used by android_binary()
and android_aar()
rules. This rule takes a skeleton manifest, and merges it with manifests found in any deps.
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this onedeps
: A collection of dependencies that includes android_library rules. The manifest files of theandroid_library()
rules will be filtered out to become dependent source files for the manifest.skeleton
: Either abuild target
or a path to a file representing the manifest that will be merged with any manifests associated with this rule'sdeps
.
Details
Examples:
Here's an example of an android_manifest()
that has no deps.
android_manifest(
name = 'my-manifest',
skeleton = 'AndroidManifestSkeleton.xml',
)
This is what AndroidManifestSkeleton.xml
looks like.
<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
package="com.example"
android:versionCode="1"
android:versionName="1.0">
<uses-sdk targetSdkVersion="19" minSdkVersion="17"/>
<application
android:label="@string/app_name"
android:icon="@drawable/ic_launcher">
<activity
android:name="MyActivity"
android:label="@string/app_name">
<intent-filter>
<action android:name="android.intent.action.MAIN"/>
<category android:name="android.intent.category.LAUNCHER"/>
</intent-filter>
</activity>
</application>
</manifest>
You could also use a genrule()
to generate the manifest file and reference the
build target
in the skeleton
argument.
android_platform
def android_platform(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
base_platform: str,
buck2_compatibility: str = _,
native_platforms: dict[str, str] = _
) -> None
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this one
android_prebuilt_aar
def android_prebuilt_aar(
*,
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] = _,
_android_toolchain: str = _,
_apple_platforms: dict[str, str] = _,
_build_only_native_code: bool = _,
_dex_min_sdk_version: None | int = _,
_dex_toolchain: str = _,
_exec_os_type: str = _,
_java_toolchain: str = _,
aar: str,
buck2_compatibility: str = _,
contacts: list[str] = _,
default_host_platform: None | str = _,
deps: list[str] = _,
desugar_deps: list[str] = _,
for_primary_apk: bool = _,
javadoc_url: None | str = _,
labels: list[str] = _,
licenses: list[str] = _,
maven_coords: None | str = _,
required_for_source_only_abi: bool = _,
source_jar: None | str = _,
use_system_library_loader: bool = _
) -> None
An android_prebuilt_aar()
rule takes an .aar
file and makes it available as an Android dependency. As expected, an android_binary()
that transitively depends on an android_prebuilt_aar()
will include its contents in the generated APK.
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this oneaar
: Path to the.aar
file. This may also be a build target to a rule (such as agenrule()
) whose output is an.aar
file.javadoc_url
: URL to the Javadoc for the.class
files in theaar
.source_jar
: Path to a JAR file that contains the.java
files to create the.class
in theaar
. This is frequently provided for debugging purposes.use_system_library_loader
: If this.aar
file contains native prebuilt.so
libraries and the Java code uses these libraries via a call toSystem.loadLibrary()
, then many optimizations—such as exopackage, compression, or asset packaging—may not be compatible with these prebuilt libs. Setting this parameter toTrue
causes all of these optimizations to skip the prebuilt.so
files originating from this.aar
file. The.so
files will always be packaged directly into the main.apk
.
Details
See the official Android documentation for details about the .aar
format.
Examples:
android_prebuilt_aar(
name = 'play-services',
aar = 'play-services-4.0.30.aar',
source_jar = 'play-services-4.0.30-sources.jar',
javadoc_url = 'file:///opt/android-sdk/extras/google/google_play_services/docs/reference',
)
android_library(
name = 'lib',
# This Java code can compile against Play services and reference its resources.
srcs = glob(['*.java']),
deps = [ ':play-services' ],
)
android_resource
def android_resource(
*,
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] = _,
_android_toolchain: str = _,
_apple_platforms: dict[str, str] = _,
_build_only_native_code: bool = _,
_java_toolchain: str = _,
allowlisted_locales: None | list[str] = _,
assets: None | str | dict[str, str] = _,
buck2_compatibility: str = _,
contacts: list[str] = _,
default_host_platform: None | str = _,
deps: list[str] = _,
has_whitelisted_strings: bool = _,
labels: list[str] = _,
licenses: list[str] = _,
manifest: None | str = _,
package: None | str = _,
project_assets: None | str = _,
project_res: None | str = _,
res: None | str | dict[str, str] = _,
resource_union: bool = _
) -> None
An android_resource()
rule is used to bundle Android resources that are traditionally stored in res
and assets
directories.
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this onedeps
: Otherandroid_resource
rules to include via-S
when runningaapt
.manifest
: An optional Android Manifest for the to declare any permissions or intents it may need or want to handle. May either be a file or anandroid_manifest()
target.package
: Java package for theR.java
file that will be generated for these resources.
Details
The output of an android_resource()
is an R.txt
file
generated via aapt --output-text-symbols
.
Examples:
Most of the time, an android_resource
rule defines only name
, res
, and package
. By convention,
such simple rules are often named res
:
android_resource(
name = 'res',
res = subdir_glob([('res', '**')]),
package = 'com.example',
)
apk_genrule
def apk_genrule(
*,
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] = _,
_android_toolchain: str = _,
_apple_platforms: dict[str, str] = _,
_build_only_native_code: bool = _,
_exec_os_type: str = _,
_genrule_toolchain: str = _,
_java_toolchain: str = _,
aab: None | str = _,
always_print_stderr: bool = _,
apk: None | str = _,
bash: None | str = _,
buck2_compatibility: str = _,
cacheable: None | bool = _,
cmd: None | str = _,
cmd_exe: None | str = _,
contacts: list[str] = _,
default_host_platform: None | str = _,
default_outs: None | list[str] = _,
enable_sandbox: None | bool = _,
environment_expansion_separator: None | str = _,
is_cacheable: bool = _,
keystore: None | str = _,
labels: list[str] = _,
licenses: list[str] = _,
metadata_env_var: None | str = _,
metadata_path: None | str = _,
need_android_tools: bool = _,
no_outputs_cleanup: bool = _,
out: None | str = _,
outs: None | dict[str, list[str]] = _,
remote: None | bool = _,
remote_execution_dependencies: list[dict[str, str]] = _,
srcs: list[str] | dict[str, str] = _,
type: str = _,
use_derived_apk: bool = _,
weight: None | int = _
) -> None
An apk_genrule()
rule is used to post-process an APK. What separates an apk_genrule from a genrule is apk_genrules are known by BUCK to produce APKs, so commands like buck install
or buck uninstall
still work. Additionally, apk_genrule()
rules can be inputs to other apk_genrule()
rules.
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this oneaab
: The inputandroid_binary()
rule. The path to the AAB can be accessed with the$AAB
shell variable. Only one ofapk
oraab
can be provided.apk
: The inputandroid_binary()
rule. The path to the APK can be accessed with the$APK
shell variable. Only one ofapk
oraab
can be provided.bash
: A platform-specific version of the shell command parametercmd
. It runs on Linux and UNIX systems—including OSX—on whichbash
is installed. It has a higher priority thancmd
. Thebash
argument is run with/usr/bin/env bash -c
. It has access to the same set of macros and variables as thecmd
argument.cmd
: The shell command to run to generate the output file. It is the fallback forbash
andcmd_exe
arguments. The following environment variables are populated by Buck and available to the shell command. They are accessed using the syntax:${<variable>}
Example:
${SRCS}
${SRCS}
A string expansion of the
srcs
argument delimited by theenvironment_expansion_separator
argument where each element ofsrcs
will be translated into a relative path.${SRCDIR}
The relative path to a directory to which sources are copied prior to running the command.
${OUT}
The output file or directory for the
genrule()
. This variable will have whatever value is specified by theout
argument if not using named outputs. If using named outputs, this variable will be the output directory.The value should be a valid filepath. The semantics of the shell command determine whether this filepath is treated as a file or a directory. If the filepath is a directory, then the shell command needs to create it if not using named outputs. Otherwise, it will be automatically created. All outputs (directories and files) must be readable, writable, and (in the case of directories) executable by the current user.
The file or directory specified by this variable must always be written by this command. If not, the execution of this rule will be considered a failure, halting the build process.
${TMP}
A temporary directory which can be used for intermediate results and will not be bundled into the output.
cmd_exe
: A platform-specific version of the shell command parametercmd
. It runs on Windows and has a higher priority thancmd
. Thecmd_exe
argument is run withcmd.exe /v:off /c
. It has access to the same set of macros and variables as thecmd
argument.environment_expansion_separator
: The delimiter between paths in environment variables, such as SRCS, that can contain multiple paths. It can be useful to specify this parameter if the paths could contain spaces.out
: The name of the output file or directory. The complete path to this argument is provided to the shell command through theOUT
environment variable. Only one ofout
orouts
may be present.For an apk_genrule the output should be a '.apk' or '.aab' file.
srcs
: Either a list or a map of the source files which Buck makes available to the shell command at the path in theSRCDIR
environment variable. If you specify a list, the source files are the names in the list. If you specify a map, the source files are made available as the names in the keys of the map, where the values of the map are the original source file names.weight
: How many local slots these genrule should take when executing locally.
Details
Examples:
Here is an example of a couple apk_genrule()
open up an APK, do
some super signing, and then zipalign that APK again.
# Building this rule will produce a file named messenger.apk.
android_binary(
name = 'messenger',
manifest = 'AndroidManifest.xml',
target = 'Google Inc.:Google APIs:16',
keystore = '//keystores:prod',
package_type = 'release',
proguard_config = 'proguard.cfg',
deps = [
':res',
':src',
],
)
apk_genrule(
name = 'messenger_super_sign_unalign',
apk = ':messenger',
bash = '$(exe //java/com/facebook/sign:super_sign) --input $APK --output $OUT',
cmd_exe = '$(exe //java/com/facebook/sign:super_sign) --input %APK% --output %OUT%',
out = 'messenger_super_sign_unalign.apk',
)
apk_genrule(
name = 'messenger_super_sign',
apk = ':messenger_super_sign_unalign',
bash = '$ANDROID_HOME/tools/zipalign -f 4 $APK $OUT',
cmd_exe = '%ANDROID_HOME%\tools\zipalign -f 4 %APK% %OUT%',
out = 'messenger_super_sign.apk',
)
apple_asset_catalog
def apple_asset_catalog(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
app_icon: None | str = _,
buck2_compatibility: str = _,
contacts: list[str] = _,
default_host_platform: None | str = _,
dirs: list[str] = _,
labels: list[str] = _,
launch_image: None | str = _,
licenses: list[str] = _,
skip_universal_resource_dedupe: bool = _
) -> None
An apple_asset_catalog()
rule contains resources stored in Apple asset catalog directories. This rule does not have any output on its own and can be built only as a dependency (either direct or transitive) of an apple_bundle()
rule, in which case all apple_asset_catalog()
rules that the bundle rule depends on are merged and placed into the final output bundle together.
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this oneapp_icon
: An optional reference to a.appiconset
containing a image set representing an application icon. (The extension itself should not be included.) This parameter may be specified at most once in a givenapple_bundle
's transitive dependencies.launch_image
: An optional reference to a.launchimage
containing a image set representing an application launch image. (The extension itself should not be included.) This parameter may be specified at most once in a givenapple_bundle
's transitive dependencies.
Details
Examples:
apple_asset_catalog(
name = 'MyAssetCatalog',
dirs = [
'MyResources.xcassets',
],
)
# A asset catalog with a app icon and launch image
apple_asset_catalog(
name = 'AssetCatalog',
dirs = [ 'AssetCatalog.xcassets' ],
app_icon = 'Icon',
launch_image = 'LaunchImage',
)
apple_binary
def apple_binary(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
_apple_toolchain: str = _,
_apple_tools: str = _,
_apple_xctoolchain: str = _,
_apple_xctoolchain_bundle_id: str = _,
_dsymutil_extra_flags: list[str],
_enable_library_evolution: bool = _,
_stripped_default: bool = _,
allow_cache_upload: None | bool = _,
attrs_validators: None | list[str] = _,
binary_linker_flags: list[str] = _,
bridging_header: None | str = _,
buck2_compatibility: str = _,
can_be_asset: None | bool = _,
compiler_flags: list[str] = _,
contacts: list[str] = _,
cxx_runtime_type: None | str = _,
default_host_platform: None | str = _,
default_platform: None | str = _,
defaults: dict[str, str] = _,
deps: list[str] = _,
devirt_enabled: bool = _,
diagnostics: dict[str, str] = _,
dist_thin_lto_codegen_flags: list[str] = _,
enable_cxx_interop: bool = _,
enable_distributed_thinlto: bool = _,
enable_library_evolution: None | bool = _,
entitlements_file: None | str = _,
executable_name: None | str = _,
exported_deps: list[str] = _,
exported_header_style: str = _,
exported_headers: list[str] | dict[str, str] = _,
exported_lang_platform_preprocessor_flags: dict[str, list[(str, list[str])]] = _,
exported_lang_preprocessor_flags: dict[str, list[str]] = _,
exported_linker_flags: list[str] = _,
exported_platform_deps: list[(str, list[str])] = _,
exported_platform_headers: list[(str, list[str] | dict[str, str])] = _,
exported_platform_linker_flags: list[(str, list[str])] = _,
exported_platform_preprocessor_flags: list[(str, list[str])] = _,
exported_post_linker_flags: list[str] = _,
exported_post_platform_linker_flags: list[(str, list[str])] = _,
exported_preprocessor_flags: list[str] = _,
extra_xcode_files: list[str] = _,
extra_xcode_sources: list[str] = _,
fat_lto: bool = _,
focused_list_target: None | str = _,
force_static: None | bool = _,
frameworks: list[str] = _,
header_namespace: None | str = _,
header_path_prefix: None | str = _,
headers: list[str] | dict[str, str] = _,
headers_as_raw_headers_mode: None | str = _,
import_obj_c_forward_declarations: bool = _,
include_directories: list[str] = _,
info_plist: None | str = _,
info_plist_substitutions: dict[str, str] = _,
labels: list[str] = _,
lang_compiler_flags: dict[str, list[str]] = _,
lang_platform_compiler_flags: dict[str, list[(str, list[str])]] = _,
lang_platform_preprocessor_flags: dict[str, list[(str, list[str])]] = _,
lang_preprocessor_flags: dict[str, list[str]] = _,
libraries: list[str] = _,
licenses: list[str] = _,
link_execution_preference: None | str = _,
link_group: None | str = _,
link_group_map: None | str | list[(str, list[(None | str | list[None | str], str, None | str | list[str], None | str)], None | dict[str, typing.Any])] = _,
link_group_public_deps_label: None | str = _,
link_ordering: None | str = _,
link_style: None | str = _,
link_whole: None | bool = _,
linker_extra_outputs: list[str] = _,
linker_flags: list[str] = _,
modular: bool = _,
module_name: None | str = _,
module_requires_cxx: bool = _,
platform_compiler_flags: list[(str, list[str])] = _,
platform_deps: list[(str, list[str])] = _,
platform_headers: list[(str, list[str] | dict[str, str])] = _,
platform_linker_flags: list[(str, list[str])] = _,
platform_preprocessor_flags: list[(str, list[str])] = _,
platform_srcs: list[(str, list[str | (str, list[str])])] = _,
post_linker_flags: list[str] = _,
post_platform_linker_flags: list[(str, list[str])] = _,
precompiled_header: None | str = _,
prefer_stripped_objects: bool = _,
preferred_linkage: str = _,
prefix_header: None | str = _,
preprocessor_flags: list[str] = _,
propagated_target_sdk_version: None | str = _,
public_include_directories: list[str] = _,
public_system_include_directories: list[str] = _,
raw_headers: list[str] = _,
reexport_all_header_dependencies: None | bool = _,
sanitizer_runtime_enabled: None | bool = _,
sdk_modules: list[str] = _,
serialize_debugging_options: bool = _,
soname: None | str = _,
srcs: list[str | (str, list[str])] = _,
static_library_basename: None | str = _,
stripped: None | bool = _,
supported_platforms_regex: None | str = _,
supports_merged_linking: None | bool = _,
swift_compilation_mode: str = _,
swift_compiler_flags: list[str] = _,
swift_module_skip_function_bodies: bool = _,
swift_package_name: None | str = _,
swift_version: None | str = _,
target_sdk_version: None | str = _,
thin_lto: bool = _,
use_submodules: bool = _,
uses_cxx_explicit_modules: bool = _,
uses_explicit_modules: bool = _,
uses_modules: bool = _,
validation_deps: list[str] = _
) -> None
An apple_binary()
rule builds a native executable - such as an iOS or OSX app - from the supplied set of Objective-C/C++ source files and dependencies. It is similar to a cxx_binary()
rule with which it shares many attributes. In addition to those common attributes, apple_binary()
has a some additional attributes that are specific to binaries intended to be built using the Apple toolchain. Note, however, that apple_binary()
and cxx_binary()
differ in the way that they import header files, in order to better accommodate existing conventions. See the sections for the headers
and exported_headers
attributes for more details.
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this oneallow_cache_upload
: Whether to allow uploading the output of this rule to be uploaded to cache when the action is executed locally if the configuration allows (i.e. there is a cache configured and the client has permission to write to it).compiler_flags
: Flags to use when compiling any of the above sources (which require compilation).entitlements_file
: An optional name of a plist file to be embedded in the binary. Some platforms likeiphonesimulator
require this to run properly.exported_headers
: The set of header files that are made available for inclusion to the source files in this target and all targets that transitively depend on this one. These should be specified as either a list of header files or a dictionary of header names to header files. The header names can contain forward slashes (/
). If a list of header files is specified, the headers can be imported with#import "$HEADER_PATH_PREFIX/$HEADER_NAME"
or, if a header file that belongs to the same rule is being imported, with#import "$HEADER_NAME"
, where$HEADER_PATH_PREFIX
is the value of the target'sheader_path_prefix
attribute, and$HEADER_NAME
is the filename of the header file. If a dictionary is specified, each header can be imported with#import "$HEADER_NAME"
, where$HEADER_NAME
is the key corresponding to this file. In this case, theheader_path_prefix
attribute is ignored. In either case, quotes in the import statements can be replaced with angle brackets.exported_linker_flags
: Flags to add to the linker command line when the output from this rule, or the output from any rule that transitively depends on this rule, is used in a link operation.extra_xcode_files
: When the project is generated, this is the list of files that will added to the project. Those files won't be added to the build phase "Compile Sources".frameworks
: A list of system frameworks that the code in this target uses. Each entry should be a path starting with$SDKROOT
or$PLATFORM_DIR
to denote that the rest of the path is relative to the root of the SDK used for the build or to the platform toolchain directory.header_path_prefix
: A path prefix when including headers of this target. For example, headers from a library defined usingapple_library(
name = "Library",
headers = glob(["**/*.h"]),
header_path_prefix = "Lib",
)can be imported using following mapping
Library/SubDir/Header1.h -> Lib/Header1.h
Library/Header2.h -> Lib/Header2.hDefaults to the short name of the target. Can contain forward slashes (
/
), but cannot start with one. Seeheaders
for more information.headers
: The set of header files that are made available for inclusion to the source files in this target. These should be specified as either a list of header files or a dictionary of header names to header files. The header names can contain forward slashes (/
). If a list of header files is specified, the headers can be imported with#import "$HEADER_PATH_PREFIX/$HEADER_NAME"
or#import "$HEADER_NAME"
, where$HEADER_PATH_PREFIX
is the value of the target'sheader_path_prefix
attribute, and$HEADER_NAME
is the filename of the header file. If a dictionary is specified, each header can be imported with#import "$HEADER_NAME"
, where$HEADER_NAME
is the key corresponding to this file. In this case, theheader_path_prefix
attribute is ignored. In either case, quotes in the import statements can be replaced with angle brackets.link_execution_preference
: The execution preference for linking. Options are:- any : No preference is set, and the link action will be performed based on buck2's executor configuration.
- full_hybrid : The link action will execute both locally and remotely, regardless of buck2's executor configuration (if the executor is capable of hybrid execution). The use_limited_hybrid setting of the hybrid executor is ignored.
- local : The link action will execute locally if compatible on current host platform.
- local_only : The link action will execute locally, and error if the current platform is not compatible.
- remote : The link action will execute remotely if a compatible remote platform exists, otherwise locally.
The default is None, expressing that no preference has been set on the target itself.
link_group_public_deps_label
: Surface nodes with this label as "public" nodes in the main executable when linking with with link groups.link_style
: Determines whether to build and link this rule's dependencies statically or dynamically. Can be eitherstatic
,static_pic
orshared
.linker_extra_outputs
: Declares extra outputs that the linker emits. These identifiers can be used in$(output ...)
macros inlinker_flags
to interpolate the output path into the linker command line. Useful for custom linkers that emit extra output files.linker_flags
: Flags to add to the linker command line whenever the output from this rule is used in a link operation, such as linked into an executable or a shared library.platform_compiler_flags
: Platform specific compiler flags. These should be specified as a list of pairs where the first element is an un-anchored regex (in java.util.regex.Pattern syntax) against which the platform name is matched, and the second element is a list of flags to use when compiling the target's sources. Seecompiler_flags
for more information.platform_linker_flags
: Platform-specific linker flags. This argument is specified as a list of pairs where the first element in each pair is an un-anchored regex against which the platform name is matched. The regex should usejava.util.regex.Pattern
syntax. The second element in each pair is a list of linker flags. If the regex matches the platform, these flags are added to the linker command line when the output from this rule is used in a link operation.platform_srcs
: Platform specific source files. These should be specified as a list of pairs where the first element is an un-anchored regex (in java.util.regex.Pattern syntax) against which the platform name is matched, and the second element is either a list of source files or a list of tuples of source files and a list of compilation flags to be preprocessed, compiled and assembled if the platform matches the regex. Seesrcs
for more information.preprocessor_flags
: Flags to use when preprocessing any of the above sources (which require preprocessing).srcs
: The set of C, C++, Objective-C, Objective-C++, or assembly source files to be preprocessed, compiled, and assembled by this rule. We determine which stages to run on each input source based on its file extension. See the GCC documentation for more detail on how file extensions are interpreted. Each element can be either a string specifying a source file (e.g.''
) or a tuple of a string specifying a source file and a list of compilation flags (e.g.('', ['-Wall', '-Werror'])
). In the latter case the specified flags will be used in addition to the rule's other flags when preprocessing and compiling that file (if applicable).target_sdk_version
: The minimum OS version that the library target should support, overriding the minimum set in.buckconfig
. When set, Buck will automatically add flags to both Objective-C and Swift compilation that will allow the use of the new APIs without guarding code inside availability checks.
Details
Buck enables you to override components of the Apple toolchain with
alternate tools, either from the Xcode search paths or from directories
that you specify.
See .buckconfig
and .buckconfig
for more information.
Examples:
apple_binary(
name = 'MyBinary',
deps = [
':MyLibrary',
'//Libraries:AnotherLibrary',
],
preprocessor_flags = ['-fobjc-arc'],
headers = [
'MyHeader.h',
],
srcs = [
'MySource.m',
],
frameworks = [
'$SDKROOT/System/Library/Frameworks/UIKit.framework',
'$SDKROOT/System/Library/Frameworks/Foundation.framework',
],
)
apple_bundle
def apple_bundle(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
_apple_toolchain: str = _,
_apple_tools: str = _,
_apple_xctoolchain: str = _,
_apple_xctoolchain_bundle_id: str = _,
_bundling_cache_buster: None | str = _,
_bundling_log_file_enabled: bool = _,
_bundling_log_file_level: None | str = _,
_code_signing_configuration: None | str = _,
_codesign_entitlements: None | str = _,
_codesign_identities_command_override: None | str = _,
_codesign_type: None | str = _,
_compile_resources_locally_override: None | bool = _,
_dsymutil_extra_flags: list[str],
_embed_provisioning_profile_when_adhoc_code_signing: None | bool = _,
_fast_adhoc_signing_enabled_default: bool = _,
_fast_provisioning_profile_parsing_enabled: bool = _,
_incremental_bundling_enabled: bool = _,
_info_plist_identify_build_system_default: bool = _,
_profile_bundling_enabled: bool = _,
_provisioning_profiles: str = _,
_resource_bundle: None | str = _,
_strict_provisioning_profile_search_default: bool = _,
_use_entitlements_when_adhoc_code_signing: None | bool = _,
asset_catalogs_compilation_options: dict[str, typing.Any] = _,
binary: None | str = _,
buck2_compatibility: str = _,
bundle_type: None | str = _,
codesign_flags: list[str] = _,
codesign_identity: None | str = _,
codesign_type: None | str = _,
contacts: list[str] = _,
copy_public_framework_headers: None | bool = _,
debug_artifacts_validators: dict[str, (str, str)] = _,
default_host_platform: None | str = _,
default_platform: None | str = _,
deps: list[str] = _,
embed_provisioning_profile_when_adhoc_code_signing: bool = _,
extension: str,
fast_adhoc_signing_enabled: None | bool = _,
ibtool_flags: None | list[str] = _,
ibtool_module_flag: None | bool = _,
incremental_bundling_enabled: None | bool = _,
info_plist: str,
info_plist_identify_build_system: None | bool = _,
info_plist_substitutions: dict[str, str] = _,
labels: list[str] = _,
licenses: list[str] = _,
module_map: None | str = _,
platform_binary: None | list[(str, str)] = _,
privacy_manifest: None | str = _,
product_name: None | str = _,
propagated_target_sdk_version: None | str = _,
provisioning_profile_filter: None | str = _,
resource_group: None | str = _,
resource_group_map: None | str = _,
selective_debugging: None | str = _,
skip_copying_swift_stdlib: None | bool = _,
split_arch_dsym: bool = _,
strict_provisioning_profile_search: None | bool = _,
try_skip_code_signing: None | bool = _,
universal: None | bool = _,
use_entitlements_when_adhoc_code_signing: bool = _,
validation_deps: list[str] = _,
versioned_macos_bundle: bool = _,
xcode_product_type: None | str = _
) -> None
An apple_bundle()
rule takes an Apple binary and all of the resources and asset catalogs in the rule's transitive dependencies and generates a bundle containing all of those files. Optionally the generated bundle can also be signed using specified provisioning profiles.
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this oneasset_catalogs_compilation_options
: A dict holding parameters for asset catalogs compiler (actool). Its options include:notices
(defaults toTrue
)warnings
(defaults toTrue
)errors
(defaults toTrue
)compress_pngs
(defaults toTrue
)optimization
(defaults to'space'
)output_format
(defaults to'human-readable-text'
)extra_flags
(defaults to[]
)
deps
: A list of dependencies of this bundle as build targets. You can embed application extensions by specifying the extension's bundle target. To include a WatchKit app, append the flavor#watch
to the target specification. Buck will automatically substitute the appropriate platform flavor (eitherwatchsimulator
orwatchos
) based on the parent.extension
: The extension of the generated bundle. For example'app'
for an application bundle or'appex'
for an application extension bundle.ibtool_flags
: List of flags to be passed to ibtool during interface builder file compilation.info_plist
: A path to anInfo.plist
file that will be placed in the bundle. The specified file will be processed by substituting variable names with their values (seeinfo_plist_substitutions
for more information).info_plist_substitutions
: A dictionary that assigns variable names to their values. It is used for variable substitution when processing the file specified ininfo_plist
. For example if this argument is set to{'VAR': 'MyValue'}
, then each occurrence of$(VAR)
or${VAR}
in the file will be replaced byMyValue
.privacy_manifest
: A path to an.xcprivacy
file that will be placed in the bundle.product_name
: The name of the resulting bundle and binary. The setting behaves like PRODUCT_NAME Xcode build setting. For example, if your rule is named "MyApp" and extension is "app", by default buck will generate MyApp.app bundle. But if you will set product name to "SuperApp", bundle will get "SuperApp.app" name.
Details
Code signing will embed entitlements pointed to by the entitlements_file
arg in
the bundle's apple_binary
. This is the preferred way to specify entitlements
when building with Buck.
If the entitlements file is not present, it falls back to the CODE_SIGN_ENTITLEMENTS
entry in
info_plist_substitutions
.
If after these checks, an entitlements file is still not specified, it will be derived based
on the entitlements of the selected provisioning profile. Provisioning profiles will be selected
from profiles pointed to by apple.provisioning_profile_search_path
, based on a
non-expired profile that matches the bundle id and entitlements.
Code signing will embed entitlements pointed to by the CODE_SIGN_ENTITLEMENTS
entry in
info_plist_substitutions
. If an entitlements file is omitted, it will be derived based
on the entitlements of the selected provisioning profile. Provisioning profiles will be selected
from profiles pointed to by apple.provisioning_profile_search_path
, based on a
non-expired profile that matches the bundle id and entitlements.
Examples:
apple_bundle(
name = 'AppBundle',
binary = ':MyBinary',
extension = 'app',
info_plist = 'Info.plist',
)
# iOS app with embedded WatchOS 2.0 app/extension
apple_bundle(
name = 'DemoWatchAppExtension',
binary = ':DemoWatchAppExtensionBinary',
extension = 'appex',
info_plist = 'WatchExtension/Resources/Info.plist',
)
apple_bundle(
name = 'DemoWatchApp',
binary = ':DemoWatchAppBinary',
deps = [':DemoWatchAppResources', ':DemoWatchAppExtension'],
extension = 'app',
info_plist = 'WatchApplication/Info.plist',
)
apple_bundle(
name = 'DemoApp',
binary = ':DemoAppBinary',
deps = [':DemoWatchApp#watch'],
extension = 'app',
info_plist = 'Info.plist',
)
# iOS app using safeAreaInsets delivering to iOS 9.x
apple_bundle(
name = 'DemoIBApp',
binary = ':DemoIBAppBinary',
deps = [':DemoIBAppResources'],
extension = 'app',
ibtool_flags = ["--minimum-deployment-target", "9.0"],
info_plist = 'Info.plist',
)
apple_library
def apple_library(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
_apple_toolchain: str = _,
_apple_tools: str = _,
_apple_xctoolchain: str = _,
_apple_xctoolchain_bundle_id: str = _,
_archive_objects_locally_override: None | bool = _,
_dsymutil_extra_flags: list[str],
_enable_library_evolution: bool = _,
_stripped_default: bool = _,
allow_cache_upload: None | bool = _,
attrs_validators: None | list[str] = _,
bridging_header: None | str = _,
buck2_compatibility: str = _,
can_be_asset: None | bool = _,
compiler_flags: list[str] = _,
contacts: list[str] = _,
cxx_runtime_type: None | str = _,
default_host_platform: None | str = _,
default_platform: None | str = _,
defaults: dict[str, str] = _,
deps: list[str] = _,
devirt_enabled: bool = _,
diagnostics: dict[str, str] = _,
dist_thin_lto_codegen_flags: list[str] = _,
enable_cxx_interop: bool = _,
enable_distributed_thinlto: bool = _,
enable_library_evolution: None | bool = _,
executable_name: None | str = _,
exported_deps: list[str] = _,
exported_header_style: str = _,
exported_headers: list[str] | dict[str, str] = _,
exported_lang_platform_preprocessor_flags: dict[str, list[(str, list[str])]] = _,
exported_lang_preprocessor_flags: dict[str, list[str]] = _,
exported_linker_flags: list[str] = _,
exported_platform_deps: list[(str, list[str])] = _,
exported_platform_headers: list[(str, list[str] | dict[str, str])] = _,
exported_platform_linker_flags: list[(str, list[str])] = _,
exported_platform_preprocessor_flags: list[(str, list[str])] = _,
exported_post_linker_flags: list[str] = _,
exported_post_platform_linker_flags: list[(str, list[str])] = _,
exported_preprocessor_flags: list[str] = _,
extra_xcode_files: list[str] = _,
extra_xcode_sources: list[str] = _,
fat_lto: bool = _,
focused_list_target: None | str = _,
force_static: None | bool = _,
frameworks: list[str] = _,
header_mode: None | str = _,
header_namespace: None | str = _,
header_path_prefix: None | str = _,
headers: list[str] | dict[str, str] = _,
headers_as_raw_headers_mode: None | str = _,
import_obj_c_forward_declarations: bool = _,
include_directories: list[str] = _,
info_plist: None | str = _,
info_plist_substitutions: dict[str, str] = _,
labels: list[str] = _,
lang_compiler_flags: dict[str, list[str]] = _,
lang_platform_compiler_flags: dict[str, list[(str, list[str])]] = _,
lang_platform_preprocessor_flags: dict[str, list[(str, list[str])]] = _,
lang_preprocessor_flags: dict[str, list[str]] = _,
libraries: list[str] = _,
licenses: list[str] = _,
link_execution_preference: None | str = _,
link_group: None | str = _,
link_group_map: None | str | list[(str, list[(None | str | list[None | str], str, None | str | list[str], None | str)], None | dict[str, typing.Any])] = _,
link_ordering: None | str = _,
link_style: None | str = _,
link_whole: None | bool = _,
linker_extra_outputs: list[str] = _,
linker_flags: list[str] = _,
modular: bool = _,
module_name: None | str = _,
module_requires_cxx: bool = _,
platform_compiler_flags: list[(str, list[str])] = _,
platform_deps: list[(str, list[str])] = _,
platform_headers: list[(str, list[str] | dict[str, str])] = _,
platform_linker_flags: list[(str, list[str])] = _,
platform_preprocessor_flags: list[(str, list[str])] = _,
platform_srcs: list[(str, list[str | (str, list[str])])] = _,
post_linker_flags: list[str] = _,
post_platform_linker_flags: list[(str, list[str])] = _,
precompiled_header: None | str = _,
preferred_linkage: str = _,
prefix_header: None | str = _,
preprocessor_flags: list[str] = _,
propagated_target_sdk_version: None | str = _,
public_framework_headers: list[str] | dict[str, str] = _,
public_include_directories: list[str] = _,
public_system_include_directories: list[str] = _,
raw_headers: list[str] = _,
reexport_all_header_dependencies: None | bool = _,
sdk_modules: list[str] = _,
serialize_debugging_options: bool = _,
shared_library_macho_file_type: str = _,
soname: None | str = _,
srcs: list[str | (str, list[str])] = _,
static_library_basename: None | str = _,
stripped: None | bool = _,
supported_platforms_regex: None | str = _,
supports_header_symlink_subtarget: bool = _,
supports_merged_linking: None | bool = _,
supports_shlib_interfaces: bool = _,
swift_compilation_mode: str = _,
swift_compiler_flags: list[str] = _,
swift_module_skip_function_bodies: bool = _,
swift_package_name: None | str = _,
swift_version: None | str = _,
target_sdk_version: None | str = _,
thin_lto: bool = _,
use_archive: None | bool = _,
use_submodules: bool = _,
uses_cxx_explicit_modules: bool = _,
uses_explicit_modules: bool = _,
uses_modules: bool = _,
validation_deps: list[str] = _
) -> None
An apple_library()
rule represents a set of Objective-C/C++/Swift source files and is similar to a cxx_library()
rule with which it shares many attributes. In addition to those common attributes, apple_library()
has a some additional attributes that are specific to binaries intended to be built using the Apple toolchain. Note, however, that apple_library()
and cxx_library()
differ in the way that they import header files, in order to better accommodate existing conventions. See the sections for the headers
and exported_headers
attributes for more details.
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this oneallow_cache_upload
: Whether to allow uploading the output of this rule to be uploaded to cache when the action is executed locally if the configuration allows (i.e. there is a cache configured and the client has permission to write to it).compiler_flags
: Flags to use when compiling any of the above sources (which require compilation).exported_deps
: Dependencies that will also appear to belong to any rules that depend on this one. This has two effects: Exported dependencies will also be included in the link line of dependents of this rules, but normal dependencies will not. Whenreexport_all_header_dependencies = False
, only exported headers of the rules specified here are re-exported.exported_headers
: The set of header files that are made available for inclusion to the source files in this target and all targets that transitively depend on this one. These should be specified as either a list of header files or a dictionary of header names to header files. The header names can contain forward slashes (/
). If a list of header files is specified, the headers can be imported with#import "$HEADER_PATH_PREFIX/$HEADER_NAME"
or, if a header file that belongs to the same rule is being imported, with#import "$HEADER_NAME"
, where$HEADER_PATH_PREFIX
is the value of the target'sheader_path_prefix
attribute, and$HEADER_NAME
is the filename of the header file. If a dictionary is specified, each header can be imported with#import "$HEADER_NAME"
, where$HEADER_NAME
is the key corresponding to this file. In this case, theheader_path_prefix
attribute is ignored. In either case, quotes in the import statements can be replaced with angle brackets.exported_linker_flags
: Flags to add to the linker command line when the output from this rule, or the output from any rule that transitively depends on this rule, is used in a link operation.exported_platform_linker_flags
: Platform-specific linker flags for this rule and for all rules that transitively depend on this rule. This argument is specified as a list of pairs where the first element in each pair is an un-anchored regex against which the platform name is matched. The regex should usejava.util.regex.Pattern
syntax. The second element in each pair is a list of linker flags. If the regex matches the platform, these flags are added to the linker command line when the output from this rule, or the output from any rule that transitively depends on this rule, is used in a link operation.extra_xcode_files
: When the project is generated, this is the list of files that will added to the project. Those files won't be added to the build phase "Compile Sources".frameworks
: A list of system frameworks that the code in this target uses. Each entry should be a path starting with$SDKROOT
or$PLATFORM_DIR
to denote that the rest of the path is relative to the root of the SDK used for the build or to the platform toolchain directory.header_namespace
: A path prefix when including headers of this target. Defaults to the path from the root of the repository to the directory where this target is defined. Can contain forward slashes (/
), but cannot start with one. Seeheaders
for more information.header_path_prefix
: A path prefix when including headers of this target. For example, headers from a library defined usingapple_library(
name = "Library",
headers = glob(["**/*.h"]),
header_path_prefix = "Lib",
)can be imported using following mapping
Library/SubDir/Header1.h -> Lib/Header1.h
Library/Header2.h -> Lib/Header2.hDefaults to the short name of the target. Can contain forward slashes (
/
), but cannot start with one. Seeheaders
for more information.headers
: The set of header files that are made available for inclusion to the source files in this target. These should be specified as either a list of header files or a dictionary of header names to header files. The header names can contain forward slashes (/
). If a list of header files is specified, the headers can be imported with#import "$HEADER_PATH_PREFIX/$HEADER_NAME"
or#import "$HEADER_NAME"
, where$HEADER_PATH_PREFIX
is the value of the target'sheader_path_prefix
attribute, and$HEADER_NAME
is the filename of the header file. If a dictionary is specified, each header can be imported with#import "$HEADER_NAME"
, where$HEADER_NAME
is the key corresponding to this file. In this case, theheader_path_prefix
attribute is ignored. In either case, quotes in the import statements can be replaced with angle brackets.link_execution_preference
: The execution preference for linking. Options are:- any : No preference is set, and the link action will be performed based on buck2's executor configuration.
- full_hybrid : The link action will execute both locally and remotely, regardless of buck2's executor configuration (if the executor is capable of hybrid execution). The use_limited_hybrid setting of the hybrid executor is ignored.
- local : The link action will execute locally if compatible on current host platform.
- local_only : The link action will execute locally, and error if the current platform is not compatible.
- remote : The link action will execute remotely if a compatible remote platform exists, otherwise locally.
The default is None, expressing that no preference has been set on the target itself.
link_style
: Determines whether to build and link this rule's dependencies statically or dynamically. Can be eitherstatic
,static_pic
orshared
.linker_extra_outputs
: Declares extra outputs that the linker emits. These identifiers can be used in$(output ...)
macros inlinker_flags
to interpolate the output path into the linker command line. Useful for custom linkers that emit extra output files.linker_flags
: Flags to add to the linker command line whenever the output from this rule is used in a link operation, such as linked into an executable or a shared library.platform_compiler_flags
: Platform specific compiler flags. These should be specified as a list of pairs where the first element is an un-anchored regex (in java.util.regex.Pattern syntax) against which the platform name is matched, and the second element is a list of flags to use when compiling the target's sources. Seecompiler_flags
for more information.platform_srcs
: Platform specific source files. These should be specified as a list of pairs where the first element is an un-anchored regex (in java.util.regex.Pattern syntax) against which the platform name is matched, and the second element is either a list of source files or a list of tuples of source files and a list of compilation flags to be preprocessed, compiled and assembled if the platform matches the regex. Seesrcs
for more information.preprocessor_flags
: Flags to use when preprocessing any of the above sources (which require preprocessing).reexport_all_header_dependencies
: Whether to automatically re-export the exported headers of all dependencies.When this is set to false, only exported headers from
exported_deps
are re-exported.srcs
: The set of C, C++, Objective-C, Objective-C++, or assembly source files to be preprocessed, compiled, and assembled by this rule. We determine which stages to run on each input source based on its file extension. See the GCC documentation for more detail on how file extensions are interpreted. Each element can be either a string specifying a source file (e.g.''
) or a tuple of a string specifying a source file and a list of compilation flags (e.g.('', ['-Wall', '-Werror'])
). In the latter case the specified flags will be used in addition to the rule's other flags when preprocessing and compiling that file (if applicable).target_sdk_version
: The minimum OS version that the library target should support, overriding the minimum set in.buckconfig
. When set, Buck will automatically add flags to both Objective-C and Swift compilation that will allow the use of the new APIs without guarding code inside availability checks.
Details
Buck enables you to override components of the Apple toolchain with
alternate tools, either from the Xcode search paths or from directories
that you specify.
See .buckconfig
and .buckconfig
for more information.
Examples:
apple_library(
name = 'MyLibrary',
deps = [
':OtherLibrary',
'//Libraries:YetAnotherLibrary',
],
preprocessor_flags = ['-fobjc-arc'],
headers = [
'MyHeader.h',
],
srcs = [
'MySource.m',
'MySource.swift',
],
frameworks = [
'$SDKROOT/System/Library/Frameworks/UIKit.framework',
'$SDKROOT/System/Library/Frameworks/Foundation.framework',
],
)
apple_package
def apple_package(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
_apple_tools: str = _,
_ipa_compression_level: str,
_ipa_package: str,
buck2_compatibility: str = _,
bundle: str,
contacts: list[str] = _,
default_host_platform: None | str = _,
default_platform: None | str = _,
ext: str = _,
labels: list[str] = _,
licenses: list[str] = _,
need_android_tools: bool = _,
package_name: None | str = _,
packager: None | str = _,
packager_args: list[str] = _,
prepackaged_validators: list[str | (str, list[str])] = _
) -> None
An apple_package()
rule takes the output of an apple_bundle()
rule and compresses it in an IPA (iOS App Store Package) file.
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this one
Details
This rule can be customized using the config options .buckconfig
and .buckconfig
.
Examples:
apple_package(
name = 'AppPackage',
bundle = ':AppBundle',
)
apple_resource
def apple_resource(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
buck2_compatibility: str = _,
codesign_entitlements: None | str = _,
codesign_flags_override: None | list[str] = _,
codesign_on_copy: bool = _,
contacts: list[str] = _,
content_dirs: list[str] = _,
default_host_platform: None | str = _,
destination: None | str = _,
dirs: list[str] = _,
files: list[str] = _,
labels: list[str] = _,
licenses: list[str] = _,
named_variants: dict[str, list[str]] = _,
resources_from_deps: list[str] = _,
skip_universal_resource_dedupe: bool = _,
variants: list[str] = _
) -> None
An apple_resource()
rule contains sets of resource directories, files and file variants that can be bundled in an application bundle. This rule does not have any output on its own and can be built only as a dependency (either direct or transitive) of an apple_bundle()
rule.
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this onedestination
: Specifies the destination in the final application bundle where resource will be copied. Possible values: "resources", "frameworks", "executables", "plugins", "xpcservices".named_variants
: Mapping from a variant name to the list of resource file paths which should be placed in an application bundle. Those files will be placed in a directory with name equal to the corresponding key in this mapping. Keys should end with.lproj
suffix. (e.g.Base.lproj
,en.lproj
).resources_from_deps
: Set of build targets whose transitiveapple_resource
s should be considered as part of the current resource when collecting resources for bundles.Usually, an
apple_bundle
collects allapple_resource
rules transitively reachable through apple_library rules. This field allows for resources which are not reachable using the above traversal strategy to be considered for inclusion in the bundle.variants
: Set of paths of resource file variants that should be placed in an application bundle. The files mentioned here should be placed in a directory named$VARIANT_NAME.lproj
, where$VARIANT_NAME
is the name of the variant (e.g.Base
,en
). This argument makes it possible to use different resource files based on the active locale.
Details
Examples:
apple_resource(
name = 'Images',
files = glob([
'*.png',
]),
dirs = [
'PrettyImages',
],
)
apple_test
def apple_test(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
_apple_toolchain: str = _,
_apple_tools: str = _,
_apple_xctoolchain: str = _,
_apple_xctoolchain_bundle_id: str = _,
_bundling_cache_buster: None | str = _,
_bundling_log_file_enabled: bool = _,
_bundling_log_file_level: None | str = _,
_code_signing_configuration: None | str = _,
_codesign_identities_command_override: None | str = _,
_codesign_type: None | str = _,
_compile_resources_locally_override: None | bool = _,
_dsymutil_extra_flags: list[str],
_embed_provisioning_profile_when_adhoc_code_signing: None | bool = _,
_enable_library_evolution: bool = _,
_fast_adhoc_signing_enabled_default: bool = _,
_fast_provisioning_profile_parsing_enabled: bool = _,
_incremental_bundling_enabled: bool = _,
_info_plist_identify_build_system_default: bool = _,
_inject_test_env: str = _,
_ios_booted_simulator: str = _,
_ios_unbooted_simulator: str = _,
_macos_idb_companion: str = _,
_profile_bundling_enabled: bool = _,
_provisioning_profiles: str = _,
_resource_bundle: None | str = _,
_strict_provisioning_profile_search_default: bool = _,
_use_entitlements_when_adhoc_code_signing: None | bool = _,
allow_cache_upload: None | bool = _,
asset_catalogs_compilation_options: dict[str, typing.Any] = _,
attrs_validators: None | list[str] = _,
binary: None | str = _,
bridging_header: None | str = _,
buck2_compatibility: str = _,
can_be_asset: None | bool = _,
codesign_flags: list[str] = _,
codesign_identity: None | str = _,
codesign_type: None | str = _,
compiler_flags: list[str] = _,
contacts: list[str] = _,
cxx_runtime_type: None | str = _,
default_host_platform: None | str = _,
default_platform: None | str = _,
defaults: dict[str, str] = _,
deps: list[str] = _,
destination_specifier: dict[str, str] = _,
devirt_enabled: bool = _,
diagnostics: dict[str, str] = _,
embed_provisioning_profile_when_adhoc_code_signing: bool = _,
enable_cxx_interop: bool = _,
enable_library_evolution: None | bool = _,
entitlements_file: None | str = _,
env: None | dict[str, str] = _,
executable_name: None | str = _,
exported_deps: list[str] = _,
exported_header_style: str = _,
exported_headers: list[str] | dict[str, str] = _,
exported_lang_platform_preprocessor_flags: dict[str, list[(str, list[str])]] = _,
exported_lang_preprocessor_flags: dict[str, list[str]] = _,
exported_linker_flags: list[str] = _,
exported_platform_deps: list[(str, list[str])] = _,
exported_platform_headers: list[(str, list[str] | dict[str, str])] = _,
exported_platform_linker_flags: list[(str, list[str])] = _,
exported_platform_preprocessor_flags: list[(str, list[str])] = _,
exported_post_linker_flags: list[str] = _,
exported_post_platform_linker_flags: list[(str, list[str])] = _,
exported_preprocessor_flags: list[str] = _,
extension: str,
extra_xcode_files: list[str] = _,
extra_xcode_sources: list[str] = _,
fast_adhoc_signing_enabled: None | bool = _,
fat_lto: bool = _,
focused_list_target: None | str = _,
force_static: None | bool = _,
frameworks: list[str] = _,
header_namespace: None | str = _,
header_path_prefix: None | str = _,
headers: list[str] | dict[str, str] = _,
headers_as_raw_headers_mode: None | str = _,
import_obj_c_forward_declarations: bool = _,
include_directories: list[str] = _,
incremental_bundling_enabled: None | bool = _,
info_plist: str,
info_plist_identify_build_system: None | bool = _,
info_plist_substitutions: dict[str, str] = _,
is_ui_test: bool = _,
labels: list[str] = _,
lang_compiler_flags: dict[str, list[str]] = _,
lang_platform_compiler_flags: dict[str, list[(str, list[str])]] = _,
lang_platform_preprocessor_flags: dict[str, list[(str, list[str])]] = _,
lang_preprocessor_flags: dict[str, list[str]] = _,
libraries: list[str] = _,
licenses: list[str] = _,
link_execution_preference: None | str = _,
link_group: None | str = _,
link_group_map: None | str | list[(str, list[(None | str | list[None | str], str, None | str | list[str], None | str)], None | dict[str, typing.Any])] = _,
link_ordering: None | str = _,
link_style: str = _,
link_whole: None | bool = _,
linker_extra_outputs: list[str] = _,
linker_flags: list[str] = _,
modular: bool = _,
module_name: None | str = _,
module_requires_cxx: bool = _,
platform_compiler_flags: list[(str, list[str])] = _,
platform_deps: list[(str, list[str])] = _,
platform_headers: list[(str, list[str] | dict[str, str])] = _,
platform_linker_flags: list[(str, list[str])] = _,
platform_preprocessor_flags: list[(str, list[str])] = _,
platform_srcs: list[(str, list[str | (str, list[str])])] = _,
post_linker_flags: list[str] = _,
post_platform_linker_flags: list[(str, list[str])] = _,
precompiled_header: None | str = _,
preferred_linkage: str = _,
prefix_header: None | str = _,
preprocessor_flags: list[str] = _,
propagated_target_sdk_version: None | str = _,
provisioning_profile_filter: None | str = _,
public_include_directories: list[str] = _,
public_system_include_directories: list[str] = _,
raw_headers: list[str] = _,
reexport_all_header_dependencies: None | bool = _,
resource_group: None | str = _,
resource_group_map: None | str = _,
run_test_separately: bool = _,
runner: None | str = _,
sanitizer_runtime_enabled: None | bool = _,
sdk_modules: list[str] = _,
serialize_debugging_options: bool = _,
skip_copying_swift_stdlib: None | bool = _,
snapshot_reference_images_path: None | str = _,
soname: None | str = _,
specs: None | str = _,
srcs: list[str | (str, list[str])] = _,
static_library_basename: None | str = _,
strict_provisioning_profile_search: None | bool = _,
stripped: bool = _,
supported_platforms_regex: None | str = _,
supports_merged_linking: None | bool = _,
swift_compilation_mode: str = _,
swift_compiler_flags: list[str] = _,
swift_module_skip_function_bodies: bool = _,
swift_package_name: None | str = _,
swift_version: None | str = _,
target_sdk_version: None | str = _,
test_host_app: None | str = _,
test_re_capabilities: None | dict[str, str] = _,
test_re_use_case: None | str = _,
test_rule_timeout_ms: None | int = _,
thin_lto: bool = _,
try_skip_code_signing: None | bool = _,
ui_test_target_app: None | str = _,
use_entitlements_when_adhoc_code_signing: bool = _,
use_submodules: bool = _,
uses_cxx_explicit_modules: bool = _,
uses_explicit_modules: bool = _,
uses_modules: bool = _,
validation_deps: list[str] = _,
versioned_macos_bundle: bool = _,
xcode_product_type: None | str = _
) -> None
An apple_test()
rule contains Objective-C/C++ code which can be built and used to test code contained in other rules. The tests can be executed by running buck test
.
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this oneallow_cache_upload
: Whether to allow uploading the output of this rule to be uploaded to cache when the action is executed locally if the configuration allows (i.e. there is a cache configured and the client has permission to write to it).compiler_flags
: Flags to use when compiling any of the above sources (which require compilation).extra_xcode_files
: When the project is generated, this is the list of files that will added to the project. Those files won't be added to the build phase "Compile Sources".frameworks
: A list of system frameworks that the code in this target uses. Each entry should be a path starting with$SDKROOT
or$PLATFORM_DIR
to denote that the rest of the path is relative to the root of the SDK used for the build or to the platform toolchain directory.header_path_prefix
: A path prefix when including headers of this target. For example, headers from a library defined usingapple_library(
name = "Library",
headers = glob(["**/*.h"]),
header_path_prefix = "Lib",
)can be imported using following mapping
Library/SubDir/Header1.h -> Lib/Header1.h
Library/Header2.h -> Lib/Header2.hDefaults to the short name of the target. Can contain forward slashes (
/
), but cannot start with one. Seeheaders
for more information.headers
: The set of header files that are made available for inclusion to the source files in this target. These should be specified as either a list of header files or a dictionary of header names to header files. The header names can contain forward slashes (/
). If a list of header files is specified, the headers can be imported with#import "$HEADER_PATH_PREFIX/$HEADER_NAME"
or#import "$HEADER_NAME"
, where$HEADER_PATH_PREFIX
is the value of the target'sheader_path_prefix
attribute, and$HEADER_NAME
is the filename of the header file. If a dictionary is specified, each header can be imported with#import "$HEADER_NAME"
, where$HEADER_NAME
is the key corresponding to this file. In this case, theheader_path_prefix
attribute is ignored. In either case, quotes in the import statements can be replaced with angle brackets.info_plist
: A path to anInfo.plist
file that will be placed in the bundle. The specified file will be processed by substituting variable names with their values (seeinfo_plist_substitutions
for more information).info_plist_substitutions
: A dictionary that assigns variable names to their values. It is used for variable substitution when processing the file specified ininfo_plist
. For example if this argument is set to{'VAR': 'MyValue'}
, then each occurrence of$(VAR)
or${VAR}
in the file will be replaced byMyValue
.labels
: A list of labels to be applied to these tests. These labels are arbitrary text strings and have no meaning within buck itself. They can, however, have meaning for you as a test author (e.g.,smoke
orfast
). A label can be used to filter or include a specific test rule when executingbuck test
link_execution_preference
: The execution preference for linking. Options are:- any : No preference is set, and the link action will be performed based on buck2's executor configuration.
- full_hybrid : The link action will execute both locally and remotely, regardless of buck2's executor configuration (if the executor is capable of hybrid execution). The use_limited_hybrid setting of the hybrid executor is ignored.
- local : The link action will execute locally if compatible on current host platform.
- local_only : The link action will execute locally, and error if the current platform is not compatible.
- remote : The link action will execute remotely if a compatible remote platform exists, otherwise locally.
The default is None, expressing that no preference has been set on the target itself.
linker_flags
: Flags to add to the linker command line whenever the output from this rule is used in a link operation, such as linked into an executable or a shared library.platform_compiler_flags
: Platform specific compiler flags. These should be specified as a list of pairs where the first element is an un-anchored regex (in java.util.regex.Pattern syntax) against which the platform name is matched, and the second element is a list of flags to use when compiling the target's sources. Seecompiler_flags
for more information.platform_srcs
: Platform specific source files. These should be specified as a list of pairs where the first element is an un-anchored regex (in java.util.regex.Pattern syntax) against which the platform name is matched, and the second element is either a list of source files or a list of tuples of source files and a list of compilation flags to be preprocessed, compiled and assembled if the platform matches the regex. Seesrcs
for more information.preprocessor_flags
: Flags to use when preprocessing any of the above sources (which require preprocessing).srcs
: The set of C, C++, Objective-C, Objective-C++, or assembly source files to be preprocessed, compiled, and assembled by this rule. We determine which stages to run on each input source based on its file extension. See the GCC documentation for more detail on how file extensions are interpreted. Each element can be either a string specifying a source file (e.g.''
) or a tuple of a string specifying a source file and a list of compilation flags (e.g.('', ['-Wall', '-Werror'])
). In the latter case the specified flags will be used in addition to the rule's other flags when preprocessing and compiling that file (if applicable).target_sdk_version
: The minimum OS version that the library target should support, overriding the minimum set in.buckconfig
. When set, Buck will automatically add flags to both Objective-C and Swift compilation that will allow the use of the new APIs without guarding code inside availability checks.test_host_app
: A build target identifying anapple_bundle()
rule that builds an application bundle. Output of the specified rule will be used as a test host of this test. This impliesrun_test_separately
. Since symbols that are defined in the test host application and its dependencies will not be linked into the test binary, to make those symbols accessible to the test target they need to be specified as a dependency of this target and['-undefined', 'dynamic_lookup']
needs to be added to this target'slinker_flags
(this will suppress undefined reference errors during compilation, but if the symbols do not exist, it might result in runtime crashes).test_re_capabilities
: An optional dictionary with the RE capabilities for the test execution. Overrides a default selection mechanism.test_re_use_case
: An optional name of the RE use case for the test execution. Overrides a default selection mechanism.
Details
Examples:
apple_test(
name = 'MyTest',
info_plist = 'MyTest-Info.plist',
preprocessor_flags = ['-fobjc-arc'],
srcs = [
'MyTest.m',
],
deps = [
':MyLibrary',
],
frameworks = [
'$SDKROOT/System/Library/Frameworks/Foundation.framework',
'$SDKROOT/System/Library/Frameworks/UIKit.framework',
'$PLATFORM_DIR/Developer/Library/Frameworks/XCTest.framework',
],
)
apple_toolchain
def apple_toolchain(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
_internal_platform_path: None | str = _,
_internal_sdk_path: None | str = _,
actool: str,
architecture: str = _,
buck2_compatibility: str = _,
build_version: None | str = _,
codesign: str,
codesign_allocate: str,
codesign_identities_command: None | str = _,
compile_resources_locally: bool = _,
contacts: list[str] = _,
copy_scene_kit_assets: str,
cxx_toolchain: str,
default_host_platform: None | str = _,
developer_path: None | str = _,
dsymutil: str,
dwarfdump: None | str = _,
extra_linker_outputs: list[str] = _,
ibtool: str,
installer: str = _,
labels: list[str] = _,
libtool: str,
licenses: list[str] = _,
lipo: str,
mapc: None | str = _,
merge_index_store: str = _,
min_version: str = _,
momc: str,
objdump: None | str = _,
placeholder_tool: None | str = _,
platform_path: None | str = _,
requires_xcode_version_match: bool = _,
sdk_environment: None | str = _,
sdk_name: str = _,
sdk_path: None | str = _,
swift_toolchain: None | str = _,
version: None | str = _,
watch_kit_stub_binary: None | str = _,
work_around_dsymutil_lto_stack_overflow_bug: None | bool = _,
xcode_build_version: None | str = _,
xcode_version: None | str = _,
xctest: str
) -> None
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this one
apple_toolchain_set
def apple_toolchain_set(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
apple_toolchains: list[str] = _,
buck2_compatibility: str = _,
contacts: list[str] = _,
default_host_platform: None | str = _,
labels: list[str] = _,
licenses: list[str] = _
) -> None
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this one
apple_universal_executable
def apple_universal_executable(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
_apple_toolchain: str = _,
_apple_tools: str = _,
_dsymutil_extra_flags: list[str],
buck2_compatibility: str = _,
executable: str,
executable_name: None | str = _,
labels: list[str] = _,
split_arch_dsym: bool = _,
universal: None | bool = _
) -> None
An apple_universal_executable()
rule takes a target via its binary
attribute, builds it for multiple architectures and combines the result into a single binary using lipo
.
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this oneexecutable
: A build target identifying the binary which will be built for multiple architectures. The target will be transitioned into different configurations, with distinct architectures.The target can be one of:
apple_binary()
andcxx_binary()
[shared]
subtarget ofapple_library()
andcxx_library()
apple_library()
andcxx_library()
which havepreferred_linkage = shared
attribute
executable_name
: By default, the name of the universal executable is same as the name of the binary from thebinary
target attribute. Setexecutable_name
to override the default.split_arch_dsym
: If enabled, each architecture gets its own dSYM binary. Use this if the combined universal dSYM binary exceeds 4GiB.universal
: Controls whether the output is universal binary. Any value overrides the presence of theconfig//cpu/constraints:universal-enabled
constraint. Read the rule docs for more information on resolution.
Details
The output of the rule is a universal binary:
- If
config//cpu/constraints:universal-enabled
is present in the target platform. - If the
universal
attribute is set toTrue
.
If none of the conditions are met, then the rule acts as a nop alias()
.
The universal
attribute, if present, takes precedence over constraint.
For example, if universal = False
, then the presence of the constraint
would not affect the output.
apple_bundle()
supports building of universal binaries,
apple_universal_executable()
is only needed if you have a standalone
binary target which is not embedded in an apple_bundle()
(usually a
CLI tool).
apple_xcframework
def apple_xcframework(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
_apple_tools: str = _,
buck2_compatibility: str = _
) -> None
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this one
apple_xcuitest
def apple_xcuitest(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
_apple_toolchain: str = _,
_apple_tools: str = _,
_apple_xctoolchain: str = _,
_apple_xctoolchain_bundle_id: str = _,
_bundling_cache_buster: None | str = _,
_bundling_log_file_enabled: bool = _,
_bundling_log_file_level: None | str = _,
_code_signing_configuration: None | str = _,
_codesign_identities_command_override: None | str = _,
_codesign_type: None | str = _,
_compile_resources_locally_override: None | bool = _,
_embed_provisioning_profile_when_adhoc_code_signing: None | bool = _,
_enable_library_evolution: bool = _,
_fast_adhoc_signing_enabled_default: bool = _,
_fast_provisioning_profile_parsing_enabled: bool = _,
_incremental_bundling_enabled: bool = _,
_info_plist_identify_build_system_default: bool = _,
_profile_bundling_enabled: bool = _,
_provisioning_profiles: str = _,
_resource_bundle: None | str = _,
_strict_provisioning_profile_search_default: bool = _,
_use_entitlements_when_adhoc_code_signing: None | bool = _,
binary: None | str = _,
buck2_compatibility: str = _,
codesign_identity: None | str = _,
codesign_type: None | str = _,
embed_provisioning_profile_when_adhoc_code_signing: bool = _,
enable_library_evolution: None | bool = _,
entitlements_file: None | str = _,
extension: str = _,
fast_adhoc_signing_enabled: None | bool = _,
incremental_bundling_enabled: bool = _,
info_plist: str,
info_plist_identify_build_system: None | bool = _,
info_plist_substitutions: dict[str, str] = _,
provisioning_profile_filter: None | str = _,
strict_provisioning_profile_search: None | bool = _,
target_sdk_version: None | str = _,
test_bundle: str,
use_entitlements_when_adhoc_code_signing: bool = _,
validation_deps: list[str] = _,
versioned_macos_bundle: bool = _
) -> None
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this one
cgo_library
def cgo_library(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
_asan: bool = _,
_coverage_mode: None | str = _,
_cxx_toolchain: str = _,
_exec_os_type: str = _,
_go_stdlib: str = _,
_go_toolchain: str = _,
_race: bool = _,
_tags: list[str] = _,
allow_cache_upload: None | bool = _,
assembler_flags: list[str] = _,
buck2_compatibility: str = _,
compiler_flags: list[str] = _,
contacts: list[str] = _,
cxx_compiler_flags: list[str] = _,
cxx_preprocessor_flags: list[str] = _,
default_host_platform: None | str = _,
default_platform: None | str = _,
deps: list[str] = _,
embedcfg: None | str = _,
exported_deps: list[str] = _,
generate_exported_header: bool = _,
header_namespace: None | str = _,
headers: list[str] | dict[str, str] = _,
labels: list[str] = _,
licenses: list[str] = _,
link_style: None | str = _,
package_name: None | str = _,
package_root: None | str = _,
srcs: list[str] = _
) -> None
A cgo_library() rule builds an object from the supplied set of Go/C source files and dependencies. The outputs are linked into go executable in the last step (compile).
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this oneallow_cache_upload
: Whether to allow uploading the output of this rule to be uploaded to cache when the action is executed locally if the configuration allows (i.e. there is a cache configured and the client has permission to write to it).assembler_flags
: The set of additional assembler flags to pass togo tool asm
.compiler_flags
: The set of additional compiler flags to pass togo tool compile
.cxx_compiler_flags
: GCC/Clang flags to use when compiling any of the above C/C++ sources (which require compilation).cxx_preprocessor_flags
: GCC/Clang flags to use when preprocessing any of the above C/C++ sources (which require preprocessing).generate_exported_header
: Generate header file with declaration for functions exported with//export
The header name for targetcell//foo/bar:lib
will befoo/bar/lib.h
header_namespace
: A path prefix when including headers of this target. Defaults to the path from the root of the repository to the directory where this target is defined. Can contain forward slashes (/
), but cannot start with one. Seeheaders
for more information.headers
: The set of header files that are made available for inclusion to the source files in this target. These should be specified as either a list of header files or a dictionary of header names to header files. The header name can contain forward slashes (/
). The headers can be included with#include "$HEADER_NAMESPACE/$HEADER_NAME"
or#include <$HEADER_NAMESPACE/$HEADER_NAME>
, where$HEADER_NAMESPACE
is the value of the target'sheader_namespace
attribute, and$HEADER_NAME
is the header name if specified, and the filename of the header file otherwise. Seeheader_namespace
for more information.link_style
: Determines whether to build and link this rule's dependencies statically or dynamically. Can be eitherstatic
,static_pic
orshared
.package_name
: Sets the full name of the package being compiled. This defaults to the path from the buck root. (e.g. given a ./.buckconfig, a rule in ./a/b/BUCK defaults to package "a/b")package_root
: Sets Go package direactory (relative to BUCK file). By default (or if None passes) package_root is being detected automatically. Empty string of Go package is on the same level as BUCK file otherwise the subdirectory name. Example for srcs = ["foo/bar.go"], package_root = "foo"srcs
: The set of source files to be compiled by this rule. .go files will be compiled with the Go compiler, .s files will be compiled with the assembler, and everything else is assumed to be files that may be#include
d by the assembler.
Details
The 'go build' command would collect the cgo directives from the source files, however with buck the flags needs to be passed in the cgo_library manually
This rule borrows from cxx_binary()
since C/C++ sources are being compiled.
Examples:
# A rule that builds a Go native executable with linked cgo library based on
# C/C++ util library.
go_binary(
name = "bin",
srcs = ["main.go"],
deps = [":lib"]
)
cgo_library(
name = "lib",
srcs = ["cgo_source.go"],
deps = [":util"],
)
cxx_library(
name = "util",
srcs = ["util.c"],
headers = ["util.h"],
)
command_alias
def command_alias(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
_exec_os_type: str = _,
_target_os_type: str = _,
args: list[str] = _,
buck2_compatibility: str = _,
contacts: list[str] = _,
default_host_platform: None | str = _,
env: dict[str, str] = _,
exe: None | str = _,
labels: list[str] = _,
licenses: list[str] = _,
platform_exe: dict[str, str] = _,
resources: list[str] = _
) -> None
The command_alias
rule enables you to wrap build rules that create binaries and to pre-apply command-line arguments and environment variables.
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this oneargs
: A string of arguments that is passed to the executable specified byexe
at startup. These arguments support a subset of Buck'sstring parameter macros
. Only the$(location ...)
and$(exe ...)
macros are supported currently.env
: A map of environment variables that will be passed to the executable represented byexe
on startup. Environment variables support the same macros as arguments.exe
: Abuild target
for a rule that outputs an executable, such as ansh_binary()
, or an executable source file.platform_exe
: A mapping from platforms tobuild target
. enables you to overrideexe
per host platform.If present,
exe
will be used as a fallback on host platforms that are not specified inplatform_exe
.It is possible to omit
exe
when providingplatform_exe
. In that case, the build will fail if the command is invoked on a platform not specified in the mapping.Valid platforms are all values of the
Platform
enum :FREEBSD
LINUX
MACOS
WINDOWS
Details
Example uses include running a command written in a scripting language with a specific interpreter, and transparently wrapping sub-commands of a binary.
You can reference a command_alias
target in
the cmd
parameter of a genrule()
by
using the exe
macro:
$(exe //path/to:target)
Examples:
# Combining an interpreter and a script
cxx_binary(
name = "node-js",
srcs = [
# ...
],
headers = [
# ...
],
)
export_file(
name = "scripts"
)
command_alias(
name = "server",
exe = ":node-js",
args = [
"$(location :scripts)/start-server.js",
],
)
# Exposing sub commands
export_file(
name = "yarn",
src = "yarn.sh",
)
command_alias(
name = "add",
exe = ":yarn",
args = ["add"],
)
command_alias(
name = "install",
exe = ":yarn",
args = ["install"],
)
command_alias(
name = "run",
exe = ":yarn",
args = ["run"],
)
# Platform specific commands
export_file(
name = "node-windows",
src = "windows/node.exe",
)
export_file(
name = "node-linux",
src = "linux/node",
)
export_file(
name = "node-macos",
src = "macos/node",
)
command_alias(
name = "node",
platform_exe = {
"windows": ":node-windows",
"linux": ":node-linux",
"macos": ":node-macos",
},
)
config_setting
def config_setting(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
buck2_compatibility: str = _,
constraint_values: list[str] = _,
values: dict[str, str] = _
) -> None
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this one
configuration_alias
def configuration_alias(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
actual: str,
buck2_compatibility: str = _
) -> None
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this one
configured_alias
def configured_alias(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
actual: str,
buck2_compatibility: str = _,
configured_actual: None | (str, str) = _,
contacts: list[str] = _,
default_host_platform: None | str = _,
fallback_actual: None | str = _,
labels: list[str] = _,
licenses: list[str] = _,
platform: None | str = _,
propagate_flavors: bool = _
) -> None
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this one
constraint_setting
def constraint_setting(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
buck2_compatibility: str = _
) -> None
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this one
constraint_value
def constraint_value(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
buck2_compatibility: str = _,
constraint_setting: str
) -> None
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this one
core_data_model
def core_data_model(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
buck2_compatibility: str = _,
contacts: list[str] = _,
default_host_platform: None | str = _,
labels: list[str] = _,
licenses: list[str] = _,
module: None | str = _,
path: str
) -> None
An core_data_model()
rule contains models for Apple's Core Data framework. This rule does not have any output on its own and can be built only as a dependency (either direct or transitive) of an apple_bundle()
rule in which case all core_data_model()
rules that the bundle rule depends on are merged and placed into the final output bundle together.
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this one
Details
Examples:
core_data_model(
name = 'MyCoreDataModel',
path = 'MyCoreDataModel.xcdatamodeld',
)
csharp_library
def csharp_library(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
_csharp_toolchain: str = _,
buck2_compatibility: str = _,
compiler_flags: list[str] = _,
contacts: list[str] = _,
default_host_platform: None | str = _,
deps: list[str] = _,
dll_name: str = _,
framework_ver: str,
labels: list[str] = _,
licenses: list[str] = _,
resources: dict[str, str] = _,
srcs: list[str] = _
) -> None
A csharp_library() rule builds a .Net library from the supplied set of C# source files and dependencies by invoking csc.
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this onecompiler_flags
: The set of additional compiler flags to pass to the compiler.deps
: The set of targets or system-provided assemblies to rely on. Any values that are targets must be either csharp_library orprebuilt_dotnet_library
instances.dll_name
: The output name of the dll. This allows you to specify the name of the dll exactly. When this is not set, the dll will be named after the short name of the target.framework_ver
: The version of the .Net framework that this library targets. This is one of 'net35', 'net40', 'net45' and 'net46'.resources
: Resources that should be embedded within the built DLL. The format is the name of the resource once mapped into the DLL as the key, and the value being the resource that should be merged. This allows non-unique keys to be identified quickly.srcs
: The collection of source files to compile.
Details
Examples:
For more examples, check out our integration tests.
csharp_library(
name = 'simple',
dll_name = 'Cake.dll',
framework_ver = 'net46',
srcs = [
'Hello.cs',
],
resources = {
'greeting.txt': '//some:target',
},
deps=[
':other',
'System.dll',
],
)
prebuilt_dotnet_library(
name = 'other',
assembly = 'other-1.0.dll',
)
cxx_binary
def cxx_binary(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
_cxx_hacks: str = _,
_cxx_toolchain: str = _,
allow_cache_upload: None | bool = _,
anonymous_link_groups: bool = _,
auto_link_groups: bool = _,
binary_linker_flags: list[str] = _,
bolt_flags: list[str] = _,
bolt_profile: None | str = _,
buck2_compatibility: str = _,
compiler_flags: list[str] = _,
constraint_overrides: list[str] = _,
contacts: list[str] = _,
coverage_instrumentation_compiler_flags: list[str] = _,
cxx_runtime_type: None | str = _,
default_host_platform: None | str = _,
default_platform: None | str = _,
defaults: dict[str, str] = _,
deps: list[str] = _,
deps_query: None | str = _,
devirt_enabled: bool = _,
distributed_thinlto_partial_split_dwarf: bool = _,
enable_distributed_thinlto: bool = _,
executable_name: None | str = _,
exported_needs_coverage_instrumentation: bool = _,
fat_lto: bool = _,
focused_list_target: None | str = _,
frameworks: list[str] = _,
header_namespace: None | str = _,
headers: list[str] | dict[str, str] = _,
headers_as_raw_headers_mode: None | str = _,
include_directories: list[str] = _,
labels: list[str] = _,
lang_compiler_flags: dict[str, list[str]] = _,
lang_platform_compiler_flags: dict[str, list[(str, list[str])]] = _,
lang_platform_preprocessor_flags: dict[str, list[(str, list[str])]] = _,
lang_preprocessor_flags: dict[str, list[str]] = _,
libraries: list[str] = _,
licenses: list[str] = _,
link_deps_query_whole: bool = _,
link_execution_preference: None | str = _,
link_group: None | str = _,
link_group_deps: list[str] = _,
link_group_map: None | str | list[(str, list[(None | str | list[None | str], str, None | str | list[str], None | str)], None | dict[str, typing.Any])] = _,
link_group_min_binary_node_count: None | int = _,
link_group_public_deps_label: None | str = _,
link_ordering: None | str = _,
link_style: None | str = _,
link_whole: bool = _,
linker_extra_outputs: list[str] = _,
linker_flags: list[str] = _,
platform_compiler_flags: list[(str, list[str])] = _,
platform_deps: list[(str, list[str])] = _,
platform_headers: list[(str, list[str] | dict[str, str])] = _,
platform_linker_flags: list[(str, list[str])] = _,
platform_preprocessor_flags: list[(str, list[str])] = _,
platform_srcs: list[(str, list[str | (str, list[str])])] = _,
post_linker_flags: list[str] = _,
post_platform_linker_flags: list[(str, list[str])] = _,
precompiled_header: None | str = _,
prefer_stripped_objects: bool = _,
prefix_header: None | str = _,
preprocessor_flags: list[str] = _,
raw_headers: list[str] = _,
resources: list[str] | dict[str, str] = _,
srcs: list[str | (str, list[str])] = _,
thin_lto: bool = _,
version_universe: None | str = _,
weak_framework_names: list[str] = _
) -> None
A cxx_binary() rule builds a native executable from the supplied set of C/C++ source files and dependencies. If C/C++ library dependencies are listed, the generated native executable will request and link against their static archives (which are *not* built using PIC).
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this oneallow_cache_upload
: Whether to allow uploading the output of this rule to be uploaded to cache when the action is executed locally if the configuration allows (i.e. there is a cache configured and the client has permission to write to it).compiler_flags
: Flags to use when compiling any of the above sources (which require compilation).deps_query
: Status: experimental/unstable. The deps query takes a query string that accepts the following query functions, and appends the output of the query to the declared deps:attrfilter
deps
except
intersect
filter
kind
set
union
The macro
$declared_deps
may be used anywhere a target literal pattern is expected in order to refer to the explicit deps of this rule as they appear in the rule's definition. For example, if your build rule declares
android_library(
name = 'lib',
deps = ['//foo:foo'],
deps_query = '$declared_deps',
)then the macro
$declared_deps
would be expanded to a literalset(//foo:foo)
. Some example queries:
"filter({name_regex}, $declared_deps)".format(name_regex='//.*')
"attrfilter(annotation_processors, com.foo.Processor, $declared_deps)"
"deps('//foo:foo', 1)"Note: any targets included in this query must also be present in
deps
.header_namespace
: A path prefix when including headers of this target. Defaults to the path from the root of the repository to the directory where this target is defined. Can contain forward slashes (/
), but cannot start with one. Seeheaders
for more information.headers
: The set of header files that are made available for inclusion to the source files in this target. These should be specified as either a list of header files or a dictionary of header names to header files. The header name can contain forward slashes (/
). The headers can be included with#include "$HEADER_NAMESPACE/$HEADER_NAME"
or#include <$HEADER_NAMESPACE/$HEADER_NAME>
, where$HEADER_NAMESPACE
is the value of the target'sheader_namespace
attribute, and$HEADER_NAME
is the header name if specified, and the filename of the header file otherwise. Seeheader_namespace
for more information.include_directories
: A list of include directories (withraw_headers
) to be added to the compile command for compiling this target (via-I
). An include directory is relative to the current package.link_execution_preference
: The execution preference for linking. Options are:- any : No preference is set, and the link action will be performed based on buck2's executor configuration.
- full_hybrid : The link action will execute both locally and remotely, regardless of buck2's executor configuration (if the executor is capable of hybrid execution). The use_limited_hybrid setting of the hybrid executor is ignored.
- local : The link action will execute locally if compatible on current host platform.
- local_only : The link action will execute locally, and error if the current platform is not compatible.
- remote : The link action will execute remotely if a compatible remote platform exists, otherwise locally.
The default is None, expressing that no preference has been set on the target itself.
link_group_deps
: Additional targets to traverse when building link groups, but which should not be direct dependencies of the main executable.link_group_public_deps_label
: Surface nodes with this label as "public" nodes in the main executable when linking with with link groups.link_style
: Determines whether to build and link this rule's dependencies statically or dynamically. Can be eitherstatic
,static_pic
orshared
.linker_extra_outputs
: Declares extra outputs that the linker emits. These identifiers can be used in$(output ...)
macros inlinker_flags
to interpolate the output path into the linker command line. Useful for custom linkers that emit extra output files.linker_flags
: Flags to add to the linker command line whenever the output from this rule is used in a link operation, such as linked into an executable or a shared library.platform_compiler_flags
: Platform specific compiler flags. These should be specified as a list of pairs where the first element is an un-anchored regex (in java.util.regex.Pattern syntax) against which the platform name is matched, and the second element is a list of flags to use when compiling the target's sources. Seecompiler_flags
for more information.platform_headers
: Platform specific header files. These should be specified as a list of pairs where the first element is an un-anchored regex (in java.util.regex.Pattern syntax) against which the platform name is matched, and the second element is either a list of header files or a dictionary of header names to header files that will be made available for inclusion to the source files in the target if the platform matches the regex. Seeheaders
for more information.platform_linker_flags
: Platform-specific linker flags. This argument is specified as a list of pairs where the first element in each pair is an un-anchored regex against which the platform name is matched. The regex should usejava.util.regex.Pattern
syntax. The second element in each pair is a list of linker flags. If the regex matches the platform, these flags are added to the linker command line when the output from this rule is used in a link operation.platform_preprocessor_flags
: Platform specific preprocessor flags. These should be specified as a list of pairs where the first element is an un-anchored regex (in java.util.regex.Pattern syntax) against which the platform name is matched, and the second element is a list of flags to use when preprocessing the target's sources. Seepreprocessor_flags
for more information.platform_srcs
: Platform specific source files. These should be specified as a list of pairs where the first element is an un-anchored regex (in java.util.regex.Pattern syntax) against which the platform name is matched, and the second element is either a list of source files or a list of tuples of source files and a list of compilation flags to be preprocessed, compiled and assembled if the platform matches the regex. Seesrcs
for more information.preprocessor_flags
: Flags to use when preprocessing any of the above sources (which require preprocessing).raw_headers
: The set of header files that can be used for inclusion to the source files in the target and all targets that transitively depend on it. Buck doesn't add raw headers to the search path of a compiler/preprocessor automatically.include_directories
andpublic_include_directories
are the recommended way to add raw headers to the search path (they will be added via-I
).compiler_flags
,preprocessor_flags
andexported_preprocessor_flags
can also be used to add such raw headers to the search path if inclusion via-isystem
or-iquote
is needed.raw_headers
cannot be used together withheaders
orexported_headers
in the same target.srcs
: The set of C, C++, Objective-C, Objective-C++, or assembly source files to be preprocessed, compiled, and assembled by this rule. We determine which stages to run on each input source based on its file extension. See the GCC documentation for more detail on how file extensions are interpreted. Each element can be either a string specifying a source file (e.g.''
) or a tuple of a string specifying a source file and a list of compilation flags (e.g.('', ['-Wall', '-Werror'])
). In the latter case the specified flags will be used in addition to the rule's other flags when preprocessing and compiling that file (if applicable).
Details
Examples:
# A rule that builds a C/C++ native executable from a single .cpp file
# its corresponding header, and a C/C++ library dependency.
cxx_binary(
name = 'echo',
srcs = [
'echo.cpp',
],
headers = [
'echo.h',
],
deps = [
':util',
],
)
cxx_library(
name = 'util',
srcs = [
'util.cpp',
],
headers = [
'util.h',
],
)
# To build without stripping:
buck build :echo
# To build with stripping debug symbols only:
buck build :echo#strip-debug
cxx_genrule
def cxx_genrule(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
_build_only_native_code: bool = _,
_cxx_toolchain: str = _,
_exec_os_type: str = _,
_genrule_toolchain: str = _,
always_print_stderr: bool = _,
bash: None | str = _,
buck2_compatibility: str = _,
cacheable: None | bool = _,
cmd: None | str = _,
cmd_exe: None | str = _,
contacts: list[str] = _,
default_host_platform: None | str = _,
default_outs: None | list[str] = _,
enable_sandbox: None | bool = _,
env: dict[str, str] = _,
environment_expansion_separator: None | str = _,
labels: list[str] = _,
licenses: list[str] = _,
metadata_env_var: None | str = _,
metadata_path: None | str = _,
need_android_tools: bool = _,
no_outputs_cleanup: bool = _,
out: None | str = _,
outs: None | dict[str, list[str]] = _,
remote: None | bool = _,
remote_execution_dependencies: list[dict[str, str]] = _,
srcs: list[str] | dict[str, str] = _,
type: None | str = _,
weight: None | int = _
) -> None
A cxx_genrule()
enables you to run shell commands as part of the Buck build process. A cxx_genrule()
exposes - through a set of string parameter macros and variables - information about the tools and configuration options used by the Buck environment, specifically those related to the C/C++ toolchain.
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this onebash
: A platform-specific version of the shell command parametercmd
. It runs on Linux and UNIX systems—including OSX—on whichbash
is installed. It has a higher priority thancmd
. Thebash
argument is run with/usr/bin/env bash -c
. It has access to the same set of macros and variables as thecmd
argument.cmd
: The shell command to run to generate the output file. It is the fallback ofbash
andcmd_exe
. The shell command can access information about the buck build environment through a set of macros, parameterized macros, and variables.Macros
The following macros are available to the shell command and are accessed using the following syntax.
$(<macro>)
Example:
$(cc)
$(cc)
Path to the C compiler.$(cxx)
Path to the C++ compiler.$(cflags)
Flags passed to the C compiler.$(cppflags)
Flags passed to the C preprocessor.$(cxxflags)
Flags passed to the C++ compiler.$(cxxppflags)
Flags to pass to the C++ preprocessor.$(ld)
Path to the linker.$(ldflags-pic)
Flags passed to the linker for binaries that use position-independent code (PIC).$(ldflags-pic-filter <pattern>)
Flags passed to the linker for binaries that use position-independent code (PIC). Use the pattern parameter to specify a regular expression that matches the build targets that use these flags.$(ldflags-shared)
Flags passed to the linker for shared libraries, such as dynamic-link libraries (DLLs).$(ldflags-shared-filter <pattern>)
Flags passed to the linker for shared libraries, such as dynamic-link libraries (DLLs). Use the pattern parameter to specify a regular expression that matches the build targets that use these flags.$(ldflags-static)
Flags passed to the linker for statically-linked libraries.$(ldflags-static-filter <pattern>)
Flags passed to the linker for statically-linked libraries. Use the pattern parameter to specify a regular expression that matches the build targets that use these flags.$(platform-name)
The platform flavor with which thiscxx_genrule
was specified.Parameterized Macros
It is also possible to expand references to other rules within the shell command, using the following subset of the builtin
string parameter macros
. Note that all build rules expanded in the command are automatically considered to be dependencies of thegenrule()
.Note that the paths returned by these macros are absolute paths. You should convert these paths to be relative paths before embedding them in, for example, a shell script or batch file. Using relative paths ensures that your builds are hermetic, that is, they are reproducible across different machine environments.
Additionally, if you embed these paths in a shell script, you should execute that script using the
sh_binary()
rule and include the targets for these paths in theresources
argument of thatsh_binary
rule. These are the same targets that you pass to the string parameter macros.$(exe //path/to:target)
Expands to the commands necessary to run the executable generated by the specified build rule. For a C++ executable, this will typically just be the name of the output executable itself, such asmain
. If the specified build rule does not generate an executable output, an exception will be thrown and the build will fail.$(location //path/to:target)
Expands to the path of the output of the build rule. This means that you can refer to these without needing to be aware of how Buck is storing data on the disk mid-build.Variables
Finally, Buck adds the following variables to the environment in which the shell command runs. They are accessed using the following syntax. Note the use of braces rather than parentheses.
${<variable>}
Example:
${SRCS}
${SRCS}
A string expansion of thesrcs
argument delimited by theenvironment_expansion_separator
argument where each element ofsrcs
will be translated into an absolute path.${SRCDIR}
The absolute path to the to which sources are copied prior to running the command.${OUT}
The output file for thegenrule()
. The file specified by this variable must always be written by this command. If not, the execution of this rule will be considered a failure, halting the build process.${TMP}
A temporary directory which can be used for intermediate results and will not be bundled into the output.cmd_exe
: A platform-specific version of the shell command parametercmd
. It runs on Windows and has a higher priority thancmd
. Thecmd_exe
argument is run withcmd.exe /v:off /c
. It has access to the same set of macros and variables as thecmd
argument.enable_sandbox
: Whether this target should be executed in a sandbox or not.env
: A map of variables to be set in the environment where the shell command is run.environment_expansion_separator
: The delimiter between paths in environment variables, such as SRCS, that can contain multiple paths. It can be useful to specify this parameter if the paths could contain spaces.out
: The name of the output file or directory. The complete path to this argument is provided to the shell command through theOUT
environment variable.srcs
: Either a list or a map of the source files which Buck makes available to the shell command at the path in theSRCDIR
environment variable. If you specify a list, the source files are the names in the list. If you specify a map, the source files are made available as the names in the keys of the map, where the values of the map are the original source file names.type
: Specifies the type of this genrule. This is used for logging and is particularly useful for grouping genrules that share an underlying logical "type".For example, if you have the following
cxx_genrule
defined in the root directory of your Buck project
cxx_genrule(
name = 'cxx_gen',
type = 'epilog',
cmd = 'touch finish.txt; cp finish.txt $OUT',
out = 'finish.txt'
)then the following
buck query
command
buck query "attrfilter( type, 'epilog', '//...' )"returns
//:cxx_genweight
: How many local slots these genrule should take when executing locally.
Details
The information exposed through these tools and configuration options is a reflection of:
Buck's built-in settings,
the settings in .buckconfig
and .buckconfig.local
,
and the result of various command-line overrides specified through
the common_parameters
command-line option.
This information is available only
to the shell commands specified in the cxx_genrule
.
The information is not available to other arguments of the rule.
A cxx_genrule()
can be an input to
another cxx_genrule()
.
Note that if you specify the cxx_genrule
as a command-line
target to buck build
, you must include a platform flavor.
For example:
buck build :cxx_gr_name#iphonesimulator-x86_64
You could also just specify the default platform flavor explicitly:
buck build :cxx_gr_name#default
cxx_library
def cxx_library(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
_create_third_party_build_root: str = _,
_cxx_hacks: str = _,
_cxx_toolchain: str = _,
_is_building_android_binary: bool = _,
allow_cache_upload: None | bool = _,
auto_link_groups: bool = _,
bridging_header: None | str = _,
buck2_compatibility: str = _,
can_be_asset: None | bool = _,
compiler_flags: list[str] = _,
contacts: list[str] = _,
coverage_instrumentation_compiler_flags: list[str] = _,
cxx_runtime_type: None | str = _,
default_host_platform: None | str = _,
default_platform: None | str = _,
defaults: dict[str, str] = _,
deffile: None | str = _,
deps: list[str] = _,
deps_query: None | str = _,
devirt_enabled: bool = _,
diagnostics: dict[str, str] = _,
executable_name: None | str = _,
exported_deps: list[str] = _,
exported_header_style: str = _,
exported_headers: list[str] | dict[str, str] = _,
exported_lang_platform_preprocessor_flags: dict[str, list[(str, list[str])]] = _,
exported_lang_preprocessor_flags: dict[str, list[str]] = _,
exported_linker_flags: list[str] = _,
exported_needs_coverage_instrumentation: bool = _,
exported_platform_deps: list[(str, list[str])] = _,
exported_platform_headers: list[(str, list[str] | dict[str, str])] = _,
exported_platform_linker_flags: list[(str, list[str])] = _,
exported_platform_preprocessor_flags: list[(str, list[str])] = _,
exported_post_linker_flags: list[str] = _,
exported_post_platform_linker_flags: list[(str, list[str])] = _,
exported_preprocessor_flags: list[str] = _,
extra_xcode_files: list[str] = _,
extra_xcode_sources: list[str] = _,
fat_lto: bool = _,
focused_list_target: None | str = _,
force_static: None | bool = _,
frameworks: list[str] = _,
header_mode: None | str = _,
header_namespace: None | str = _,
headers: list[str] | dict[str, str] = _,
headers_as_raw_headers_mode: None | str = _,
include_directories: list[str] = _,
include_in_android_merge_map_output: bool = _,
labels: list[str] = _,
lang_compiler_flags: dict[str, list[str]] = _,
lang_platform_compiler_flags: dict[str, list[(str, list[str])]] = _,
lang_platform_preprocessor_flags: dict[str, list[(str, list[str])]] = _,
lang_preprocessor_flags: dict[str, list[str]] = _,
libraries: list[str] = _,
licenses: list[str] = _,
link_deps_query_whole: bool = _,
link_execution_preference: None | str = _,
link_group: None | str = _,
link_group_map: None | str | list[(str, list[(None | str | list[None | str], str, None | str | list[str], None | str)], None | dict[str, typing.Any])] = _,
link_ordering: None | str = _,
link_style: None | str = _,
link_whole: None | bool = _,
linker_extra_outputs: list[str] = _,
linker_flags: list[str] = _,
local_linker_flags: list[str] = _,
module_name: None | str = _,
platform_compiler_flags: list[(str, list[str])] = _,
platform_deps: list[(str, list[str])] = _,
platform_headers: list[(str, list[str] | dict[str, str])] = _,
platform_linker_flags: list[(str, list[str])] = _,
platform_preprocessor_flags: list[(str, list[str])] = _,
platform_srcs: list[(str, list[str | (str, list[str])])] = _,
post_linker_flags: list[str] = _,
post_platform_linker_flags: list[(str, list[str])] = _,
precompiled_header: None | str = _,
prefer_stripped_objects: bool = _,
preferred_linkage: str = _,
prefix_header: None | str = _,
preprocessor_flags: list[str] = _,
public_include_directories: list[str] = _,
public_system_include_directories: list[str] = _,
raw_headers: list[str] = _,
reexport_all_header_dependencies: None | bool = _,
resources: list[str] | dict[str, str] = _,
sdk_modules: list[str] = _,
soname: None | str = _,
srcs: list[str | (str, list[str])] = _,
static_library_basename: None | str = _,
supported_platforms_regex: None | str = _,
supports_header_symlink_subtarget: bool = _,
supports_merged_linking: None | bool = _,
supports_python_dlopen: None | bool = _,
supports_shlib_interfaces: bool = _,
thin_lto: bool = _,
use_archive: None | bool = _,
used_by_wrap_script: bool = _,
uses_cxx_explicit_modules: bool = _,
uses_explicit_modules: bool = _,
version_universe: None | str = _,
weak_framework_names: list[str] = _
) -> None
A cxx_library()
rule specifies a set of C/C++ source files and also provides flags that specify how those files should be built.
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this oneallow_cache_upload
: Whether to allow uploading the output of this rule to be uploaded to cache when the action is executed locally if the configuration allows (i.e. there is a cache configured and the client has permission to write to it).compiler_flags
: Flags to use when compiling any of the above sources (which require compilation).deffile
: Specifies the *.def file used on windows to modify a dll's exports in place of explicit__declspec(dllexport)
declarations. The default is to not use a defile.exported_deps
: Dependencies that will also appear to belong to any rules that depend on this one. This has two effects: Exported dependencies will also be included in the link line of dependents of this rules, but normal dependencies will not. Whenreexport_all_header_dependencies = False
, only exported headers of the rules specified here are re-exported.exported_header_style
: How dependents should include exported headers from this rule. Can be eitherlocal
(e.g.-I
) orsystem
(e.g.-isystem
).exported_headers
: The set of header files that are made available for inclusion to the source files in the target and all targets that transitively depend on it. These should be specified as either a list of header files or a dictionary of header names to header files. The headers can be included with#include "$HEADER_NAMESPACE/$HEADER_NAME"
or#include <$HEADER_NAMESPACE/$HEADER_NAME>
, where$HEADER_NAMESPACE
is the value of the target'sheader_namespace
attribute, and$HEADER_NAME
is the header name if specified, and the filename of the header file otherwise. Note that the header name can contain forward slashes (/
). Seeheader_namespace
for more information.exported_lang_platform_preprocessor_flags
: Just aslang_platform_preprocessor_flags
, but these flags also apply to rules that transitively depend on this rule.exported_lang_preprocessor_flags
: Just aslang_preprocessor_flags
, but these flags also apply to rules that transitively depend on this rule.exported_linker_flags
: Flags to add to the linker command line when the output from this rule, or the output from any rule that transitively depends on this rule, is used in a link operation.exported_platform_deps
: Platform specific dependencies that will also appear to belong to any rules that depend on this one. These should be specified as a list of pairs where the first element is an un-anchored regex (in java.util.regex.Pattern syntax) against which the platform name is matched, and the second element is a list of external dependencies (same format asexported_deps
) that are exported if the platform matches the regex. Seeexported_deps
for more information.exported_platform_headers
: Platform specific header files. These should be specified as a list of pairs where the first element is an un-anchored regex (in java.util.regex.Pattern syntax) against which the platform name is matched, and the second element is either a list of header files or a dictionary of header names to header files that will be made available for inclusion to the source files in the target and all targets that transitively depend on it if the platform matches the regex. Seeheaders
for more information.exported_platform_linker_flags
: Platform-specific linker flags for this rule and for all rules that transitively depend on this rule. This argument is specified as a list of pairs where the first element in each pair is an un-anchored regex against which the platform name is matched. The regex should usejava.util.regex.Pattern
syntax. The second element in each pair is a list of linker flags. If the regex matches the platform, these flags are added to the linker command line when the output from this rule, or the output from any rule that transitively depends on this rule, is used in a link operation.exported_platform_preprocessor_flags
: Platform specific exported preprocessor flags. These should be specified as a list of pairs where the first element is an un-anchored regex (in java.util.regex.Pattern syntax) against which the platform name is matched, and the second element is a list of flags to use when preprocessing the source files in the target and all targets that transitively depend on it if the platform matches the regex. Seeexported_preprocessor_flags
for more information.exported_post_linker_flags
: Flags to add to the linker command line when the output from this rule, or the output from any rule that transitively depends on this rule, is used in a link operation—with the additional feature that these flags are guaranteed to be placed after the compiled object (.o
) files on the linker command line.exported_post_platform_linker_flags
: Platform-specific linker flags for this rule and for all rules that transitively depend on this rule—and that are guaranteed to be placed after the compiled object (.o
) files on the linker command line. In other respects, the syntax and semantics of this argument are the same as for theexported_platform_linker_flags
argument.extra_xcode_files
: When the project is generated, this is the list of files that will added to the project. Those files won't be added to the build phase "Compile Sources".header_namespace
: A path prefix when including headers of this target. Defaults to the path from the root of the repository to the directory where this target is defined. Can contain forward slashes (/
), but cannot start with one. Seeheaders
for more information.headers
: The set of header files that are made available for inclusion to the source files in this target. These should be specified as either a list of header files or a dictionary of header names to header files. The header name can contain forward slashes (/
). The headers can be included with#include "$HEADER_NAMESPACE/$HEADER_NAME"
or#include <$HEADER_NAMESPACE/$HEADER_NAME>
, where$HEADER_NAMESPACE
is the value of the target'sheader_namespace
attribute, and$HEADER_NAME
is the header name if specified, and the filename of the header file otherwise. Seeheader_namespace
for more information.include_directories
: A list of include directories (withraw_headers
) to be added to the compile command for compiling this target (via-I
). An include directory is relative to the current package.lang_compiler_flags
: Language-specific compiler flags. These should be specified as a map of C-family language short names to lists of flags and is used to target flags to sources files for a specific language in the C-family (C, C++, assembler, etc.). The keys in the map can be:cpp-output
for Cc++-cpp-output
for C++objective-c-cpp-output
for Objective-Cobjective-c++-cpp-output
for Objective-C++cuda-cpp-output
for Cudaassembler
for Assembly *asm
for ASMlang_platform_compiler_flags
: Language- and platform-specific compiler flags. These should be specified as a map of C-family language short names, as described inlang_compiler_flags
, to lists of pairs, as described inplatform_compiler_flags
.lang_platform_preprocessor_flags
: Language- and platform-specific preprocessor flags. These should be specified as a map of C-family language short names, as described inlang_preprocessor_flags
, to lists of pairs, as described inplatform_preprocessor_flags
.lang_preprocessor_flags
: Language-specific preprocessor flags. These should be specified as a map of C-family language short names to lists of flags and is used to target flags to sources files for a specific language in the C-family (C, C++, assembler, etc.). The keys in the map can be:c
for Cc++
for C++objective-c
for Objective-Cobjective-c++
for Objective-C++cuda
for Cudaassembler-with-cpp
for Assembly *asm-with-cpp
for ASMlink_execution_preference
: The execution preference for linking. Options are:- any : No preference is set, and the link action will be performed based on buck2's executor configuration.
- full_hybrid : The link action will execute both locally and remotely, regardless of buck2's executor configuration (if the executor is capable of hybrid execution). The use_limited_hybrid setting of the hybrid executor is ignored.
- local : The link action will execute locally if compatible on current host platform.
- local_only : The link action will execute locally, and error if the current platform is not compatible.
- remote : The link action will execute remotely if a compatible remote platform exists, otherwise locally.
The default is None, expressing that no preference has been set on the target itself.
link_style
: Determines whether to build and link this rule's dependencies statically or dynamically. Can be eitherstatic
,static_pic
orshared
.linker_extra_outputs
: Declares extra outputs that the linker emits. These identifiers can be used in$(output ...)
macros inlinker_flags
to interpolate the output path into the linker command line. Useful for custom linkers that emit extra output files.linker_flags
: Flags to add to the linker command line whenever the output from this rule is used in a link operation, such as linked into an executable or a shared library.local_linker_flags
: Flags to add to the linker command line whenever the output from this rule is used in a link operation driven by this rule (e.g. when this rule links a shared library, but not when the output is linked into a shared library by another rule's link group links).platform_compiler_flags
: Platform specific compiler flags. These should be specified as a list of pairs where the first element is an un-anchored regex (in java.util.regex.Pattern syntax) against which the platform name is matched, and the second element is a list of flags to use when compiling the target's sources. Seecompiler_flags
for more information.platform_headers
: Platform specific header files. These should be specified as a list of pairs where the first element is an un-anchored regex (in java.util.regex.Pattern syntax) against which the platform name is matched, and the second element is either a list of header files or a dictionary of header names to header files that will be made available for inclusion to the source files in the target if the platform matches the regex. Seeheaders
for more information.platform_linker_flags
: Platform-specific linker flags. This argument is specified as a list of pairs where the first element in each pair is an un-anchored regex against which the platform name is matched. The regex should usejava.util.regex.Pattern
syntax. The second element in each pair is a list of linker flags. If the regex matches the platform, these flags are added to the linker command line when the output from this rule is used in a link operation.platform_preprocessor_flags
: Platform specific preprocessor flags. These should be specified as a list of pairs where the first element is an un-anchored regex (in java.util.regex.Pattern syntax) against which the platform name is matched, and the second element is a list of flags to use when preprocessing the target's sources. Seepreprocessor_flags
for more information.platform_srcs
: Platform specific source files. These should be specified as a list of pairs where the first element is an un-anchored regex (in java.util.regex.Pattern syntax) against which the platform name is matched, and the second element is either a list of source files or a list of tuples of source files and a list of compilation flags to be preprocessed, compiled and assembled if the platform matches the regex. Seesrcs
for more information.preferred_linkage
: Determines what linkage is used when the library is depended on by another target. To control how the dependencies of this library are linked, uselink_style
instead.preprocessor_flags
: Flags to use when preprocessing any of the above sources (which require preprocessing).public_include_directories
: A list of include directories (withraw_headers
) to be added to the compile command for compiling this target and every target that depends on it (via-I
). An include directory is relative to the current package.public_system_include_directories
: A list of include directories (withraw_headers
) to be added to the compile command for compiling this target and every target that depends on it (via-isystem
if the compiler supports it of via-I
otherwise). An include directory is relative to the current package.raw_headers
: The set of header files that can be used for inclusion to the source files in the target and all targets that transitively depend on it. Buck doesn't add raw headers to the search path of a compiler/preprocessor automatically.include_directories
andpublic_include_directories
are the recommended way to add raw headers to the search path (they will be added via-I
).compiler_flags
,preprocessor_flags
andexported_preprocessor_flags
can also be used to add such raw headers to the search path if inclusion via-isystem
or-iquote
is needed.raw_headers
cannot be used together withheaders
orexported_headers
in the same target.reexport_all_header_dependencies
: Whether to automatically re-export the exported headers of all dependencies.When this is set to false, only exported headers from
exported_deps
are re-exported.soname
: Sets the soname ("shared object name") of any shared library produced from this rule. The default value is based on the full rule name. The macro$(ext)
will be replaced with a platform-appropriate extension. An argument can be provided, which is a library version. For examplesoname = 'libfoo.$(ext 2.3)'
will belibfoo.2.3.dylib
on Mac andlibfoo.so.2.3
on Linux.srcs
: The set of C, C++, Objective-C, Objective-C++, or assembly source files to be preprocessed, compiled, and assembled by this rule. We determine which stages to run on each input source based on its file extension. See the GCC documentation for more detail on how file extensions are interpreted. Each element can be either a string specifying a source file (e.g.''
) or a tuple of a string specifying a source file and a list of compilation flags (e.g.('', ['-Wall', '-Werror'])
). In the latter case the specified flags will be used in addition to the rule's other flags when preprocessing and compiling that file (if applicable).supported_platforms_regex
: If present, an un-anchored regex (in java.util.regex.Pattern syntax) that matches all platforms that this library supports. It will not be built for other platforms.used_by_wrap_script
: When using an exopackage Android, if this parameter is set toTrue
, then the library is included in the primary APK even if native libraries would otherwise not be placed in it. This is intended for native libraries that are used by a wrap.sh script, which must be placed in the primary APK. Only one ofcan_be_asset
andused_by_wrap_script
can be set for a rule.
Details
Building requires a specified top-level target
Whether a Buck command builds the cxx_library
is
determined by the inclusion of a top-level target, such as
a cxx_binary()
or android_binary()
, that
transitively depends on the cxx_library
. The set of
targets specified to the Buck command (buck build
, buck run
, etc) must
include one of these top-level targets in order for Buck to build
the cxx_library
. Note that you could specify the top-level target
implicitly using a build target pattern
or you could also specify
the top-level target using a buckconfig alias
defined in .buckconfig
.
How Buck builds the library also depends on the specified top-level target.
For example, a C/C++ binary (cxx_binary
) would require a static non-PIC build of the library,
whereas an Android APK (android_binary
) would require a shared PIC-enabled build.
(PIC stands for position-independent code.)
Dependencies of the cxx_library also require a top-level target
Similarly, in order for Buck to build a target that
the cxx_library
depends on, such as a cxx_genrule()
,
you must specify in the Buck command a top-level target that depends on
the cxx_library
. For example, you could specify
to build
a cxx_binary
that
depends on the cxx_library
. If you specify as
your build target the cxx_library
itself, the build targets
that the cxx_library
depends on might not be built.
Examples:
# A rule that includes a single .cpp file and its corresponding header and
# also supplies an additional flag for compilation.
cxx_library(
name = 'fileutil',
srcs = [
'fileutil.cpp',
],
exported_headers = [
'fileutil.h',
],
compiler_flags = [
'-fno-omit-frame-pointer',
],
)
# A rule that defines explicit names for its headers
cxx_library(
name = 'mathutils',
header_namespace = 'math',
srcs = [
'trig/src/cos.cpp',
'trig/src/tan.cpp',
],
exported_headers = {
# These are included as <math/trig/cos.h> and <math/trig/tan.h>
'trig/cos.h': 'trig/include/cos.h',
'trig/tan.h': 'trig/include/tan.h',
},
compiler_flags = [
'-fno-omit-frame-pointer',
],
)
# A rule that uses different headers and sources per platform
cxx_library(
name = 'vector',
# Because of platform_headers, this file can include "config.h"
# and get the architecture specific header
srcs = ['vector.cpp'],
platform_srcs = [
('.*armv7$', 'armv7.S'),
('.*x86_64$', 'x86_64.S'),
],
exported_headers = [
'vector.h',
],
platform_headers = [
(
'.*armv7$',
{
'config.h': 'config-armv7.h',
}
),
(
'.*x86_64$',
{
'config.h': 'config-x86_64.h',
}
),
],
)
cxx_lua_extension
def cxx_lua_extension(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
base_module: None | str = _,
buck2_compatibility: str = _,
compiler_flags: list[str] = _,
contacts: list[str] = _,
cxx_runtime_type: None | str = _,
default_host_platform: None | str = _,
default_platform: None | str = _,
defaults: dict[str, str] = _,
deps: list[str] = _,
executable_name: None | str = _,
frameworks: list[str] = _,
header_namespace: None | str = _,
headers: list[str] | dict[str, str] = _,
headers_as_raw_headers_mode: None | str = _,
include_directories: list[str] = _,
labels: list[str] = _,
lang_compiler_flags: dict[str, list[str]] = _,
lang_platform_compiler_flags: dict[str, list[(str, list[str])]] = _,
lang_platform_preprocessor_flags: dict[str, list[(str, list[str])]] = _,
lang_preprocessor_flags: dict[str, list[str]] = _,
libraries: list[str] = _,
licenses: list[str] = _,
linker_extra_outputs: list[str] = _,
linker_flags: list[str] = _,
platform_compiler_flags: list[(str, list[str])] = _,
platform_deps: list[(str, list[str])] = _,
platform_headers: list[(str, list[str] | dict[str, str])] = _,
platform_linker_flags: list[(str, list[str])] = _,
platform_preprocessor_flags: list[(str, list[str])] = _,
platform_srcs: list[(str, list[str | (str, list[str])])] = _,
post_linker_flags: list[str] = _,
post_platform_linker_flags: list[(str, list[str])] = _,
precompiled_header: None | str = _,
prefix_header: None | str = _,
preprocessor_flags: list[str] = _,
raw_headers: list[str] = _,
srcs: list[str | (str, list[str])] = _,
version_universe: None | str = _
) -> None
A cxx_lua_extension() rule is a variant of a C/C++ library which is built as a Lua module. As such, it has a module name formed by the base_module
parameter and the rule name and implicitly depends on Lua C library (configured via the .buckconfig
parameter.
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this onebase_module
: The package for which the given specified sources and resources should reside in their final location in the top-level binary. If unset, the project relative directory that houses the BUCK file is used.compiler_flags
: Flags to use when compiling any of the above sources (which require compilation).header_namespace
: A path prefix when including headers of this target. Defaults to the path from the root of the repository to the directory where this target is defined. Can contain forward slashes (/
), but cannot start with one. Seeheaders
for more information.headers
: The set of header files that are made available for inclusion to the source files in this target. These should be specified as either a list of header files or a dictionary of header names to header files. The header name can contain forward slashes (/
). The headers can be included with#include "$HEADER_NAMESPACE/$HEADER_NAME"
or#include <$HEADER_NAMESPACE/$HEADER_NAME>
, where$HEADER_NAMESPACE
is the value of the target'sheader_namespace
attribute, and$HEADER_NAME
is the header name if specified, and the filename of the header file otherwise. Seeheader_namespace
for more information.linker_flags
: Flags to add to the linker command line whenever the output from this rule is used in a link operation, such as linked into an executable or a shared library.platform_compiler_flags
: Platform specific compiler flags. These should be specified as a list of pairs where the first element is an un-anchored regex (in java.util.regex.Pattern syntax) against which the platform name is matched, and the second element is a list of flags to use when compiling the target's sources. Seecompiler_flags
for more information.platform_headers
: Platform specific header files. These should be specified as a list of pairs where the first element is an un-anchored regex (in java.util.regex.Pattern syntax) against which the platform name is matched, and the second element is either a list of header files or a dictionary of header names to header files that will be made available for inclusion to the source files in the target if the platform matches the regex. Seeheaders
for more information.platform_linker_flags
: Platform-specific linker flags. This argument is specified as a list of pairs where the first element in each pair is an un-anchored regex against which the platform name is matched. The regex should usejava.util.regex.Pattern
syntax. The second element in each pair is a list of linker flags. If the regex matches the platform, these flags are added to the linker command line when the output from this rule is used in a link operation.platform_preprocessor_flags
: Platform specific preprocessor flags. These should be specified as a list of pairs where the first element is an un-anchored regex (in java.util.regex.Pattern syntax) against which the platform name is matched, and the second element is a list of flags to use when preprocessing the target's sources. Seepreprocessor_flags
for more information.platform_srcs
: Platform specific source files. These should be specified as a list of pairs where the first element is an un-anchored regex (in java.util.regex.Pattern syntax) against which the platform name is matched, and the second element is either a list of source files or a list of tuples of source files and a list of compilation flags to be preprocessed, compiled and assembled if the platform matches the regex. Seesrcs
for more information.preprocessor_flags
: Flags to use when preprocessing any of the above sources (which require preprocessing).srcs
: The set of C, C++, Objective-C, Objective-C++, or assembly source files to be preprocessed, compiled, and assembled by this rule. We determine which stages to run on each input source based on its file extension. See the GCC documentation for more detail on how file extensions are interpreted. Each element can be either a string specifying a source file (e.g.''
) or a tuple of a string specifying a source file and a list of compilation flags (e.g.('', ['-Wall', '-Werror'])
). In the latter case the specified flags will be used in addition to the rule's other flags when preprocessing and compiling that file (if applicable).
Details
Examples:
# A rule that builds a Lua extension from a single .cpp file.
cxx_lua_extension(
name = 'mymodule',
base_module = 'foo.bar',
srcs = [
'mymodule.cpp',
],
compiler_flags = [
'-fno-omit-frame-pointer',
],
)
# A library rule which has a single source importing the above extension.
lua_library(
name = 'utils',
srcs = [
'utils.lua',
],
deps = [
':mymodule',
],
)
-- The `utils.lua` source, wrapped by the `utils` rule above.
-- Import the C/C++ extension build above.
require "foo.bar.mymodule"
...
cxx_precompiled_header
def cxx_precompiled_header(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
buck2_compatibility: str = _,
contacts: list[str] = _,
default_host_platform: None | str = _,
deps: list[str] = _,
labels: list[str] = _,
licenses: list[str] = _,
src: str,
version_universe: None | str = _
) -> None
A cxx_precompiled_header
rule specifies a single header file that can be precompiled and made available for use in other build rules such as a cxx_library()
or a cxx_binary()
.
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this onedeps
: Dependency rules which export headers used by the header specified insrc
.src
: The path to the header file that should be precompiled. Only one header file can be specified. But of course this header could include any number of other headers. The included headers could belong to -- that is, beexported_headers
from -- another rule, in which case, the rule would have to be added todeps
as usual.
Details
This header file is precompiled by the preprocessor on behalf of the
C, C++, Objective-C, or Objective-C++ rule using it, via its precompiled_header
parameter.
Afterwards the precompiled header is applied during the rule's own compilation
(often with an appreciable reduction in build time, the main benefit of PCH).
This PCH is built once per combination of build flags which might affect the PCH's compatibility.
For example, a distinct pre-compilation of the header occurs per combination of flags related to
optimization, debug, architecture, and so on, used by rules which employ PCH.
The flags used during the build of the dependent rule (that is, the "PCH-using rule")
are in effect while building the PCH itself. Similarly, to the same end, the include paths used
when building the PCH are applied to the dependent rule. For example, deps
in the
PCH rule are propagated back to the dependent rule, and the PCH's header search paths
(e.g. -I
or -isystem
options) are prefixed onto the list of
include paths for the dependent rule.
Examples:
The best way to see how the cxx_precompiled_header()
rule works is with an
example. Let there be a header called common.h
which has the following:
#pragma once
/* Include common C++ files. */
#include <string>
#include <map>
#include <set>
#include <type_traits>
#include <vector>
/* Some frequently-used headers from the Folly project. */
#include <folly/Conv.h>
#include <folly/Executor.h>
#include <folly/io/async/EventBase.h>
cxx_precompiled_header(
name = 'common_pch',
src = 'common.h',
deps = [
# Needed for standard C++ headers:
'//external/libcxx:headers',
# Needed for the Folly includes:
'//folly:folly',
'//folly/io/async:async',
],
)
cxx_binary(
name = 'main',
srcs = ['main.cpp'],
precompiled_header = ':common_pch',
deps = [ ... ],
compiler_flags = ['-g', '-O2', '-fPIC'],
)
The cxx_precompiled_header
rule declares a precompiled header "template"
containing the header file path, and dependencies.
In this example we indicate that common.h
is to be precompiled when used by another build rule.
Note that, by itself, this cxx_precompiled_header
rule will not result
in anything being built. The usage of this rule from another rule --
an "instantiation" of this precompiled header template -- is what will trigger the
PCH build.
In the example above, the build for the binary named "main"
will depend on
the header being precompiled in a separate step, prior to compiling main.cpp
,
and the resulting PCH will be used in main
's compilation.
The dependencies specified in this precompiled header rule's deps
are transitive; they
will propagate to rules using this PCH, so that during link time, any libraries which are
required by the code made available in the header will be included in the final binary build.
The precompiled header dynamically created from the "template" will be built with flags
which would be used in the dependent rule. In this case, main
's use of specific
compiler flags -g -O2 -fPIC
will result in the production of a precompiled header
with the same flags. This is so the precompiled code fully jives with rules using the PCH,
i.e. they will have the same debug, optimization, CPU, etc. options. (The compiler is usually
smart enough to reject a bad PCH, fortunately. But we want to ensure we take the appropriate
steps to ensure we always have a PCH which works with any build that uses it.)
Another effect of a rule using a precompiled header is that the rule's list of
build flags will change; not just to employ PCH with e.g. -include-pch
(if using Clang), but also, to alter the sequence of header search paths.
The rule using the precompiled header will "inherit" the lists of paths used
during the PCH build, applying them first in its own search paths.
This is to ensure that an #include
directive will resolve in exactly
the same way in this build as it would have in the PCH, to ensure full compatibility
between the PCH and other rule's builds. For example, if the PCH were to use one version
of stdcxx
and another rule use a different version, the version differences
won't clash, thereby avoiding different versions of the <cstring>
header
used between the precompiled header and the dependent rule, and preventing confused
structure definitions, ABI incompatibility, and so on (catastrophe, in other words).
cxx_python_extension
def cxx_python_extension(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
_cxx_hacks: str = _,
_cxx_toolchain: str = _,
_python_toolchain: str = _,
_target_os_type: str = _,
allow_cache_upload: None | bool = _,
allow_embedding: bool = _,
allow_suffixing: bool = _,
auto_link_groups: bool = _,
base_module: None | str = _,
bridging_header: None | str = _,
buck2_compatibility: str = _,
can_be_asset: None | bool = _,
compiler_flags: list[str] = _,
contacts: list[str] = _,
coverage_instrumentation_compiler_flags: list[str] = _,
cxx_runtime_type: None | str = _,
default_host_platform: None | str = _,
default_platform: None | str = _,
defaults: dict[str, str] = _,
deffile: None | str = _,
deps: list[str] = _,
devirt_enabled: bool = _,
diagnostics: dict[str, str] = _,
executable_name: None | str = _,
exported_deps: list[str] = _,
exported_header_style: str = _,
exported_headers: list[str] | dict[str, str] = _,
exported_lang_platform_preprocessor_flags: dict[str, list[(str, list[str])]] = _,
exported_lang_preprocessor_flags: dict[str, list[str]] = _,
exported_linker_flags: list[str] = _,
exported_needs_coverage_instrumentation: bool = _,
exported_platform_deps: list[(str, list[str])] = _,
exported_platform_headers: list[(str, list[str] | dict[str, str])] = _,
exported_platform_linker_flags: list[(str, list[str])] = _,
exported_platform_preprocessor_flags: list[(str, list[str])] = _,
exported_post_linker_flags: list[str] = _,
exported_post_platform_linker_flags: list[(str, list[str])] = _,
exported_preprocessor_flags: list[str] = _,
extra_xcode_files: list[str] = _,
extra_xcode_sources: list[str] = _,
fat_lto: bool = _,
focused_list_target: None | str = _,
force_static: None | bool = _,
frameworks: list[str] = _,
header_namespace: None | str = _,
headers: list[str] | dict[str, str] = _,
headers_as_raw_headers_mode: None | str = _,
include_directories: list[str] = _,
include_in_android_merge_map_output: bool = _,
labels: list[str] = _,
lang_compiler_flags: dict[str, list[str]] = _,
lang_platform_compiler_flags: dict[str, list[(str, list[str])]] = _,
lang_platform_preprocessor_flags: dict[str, list[(str, list[str])]] = _,
lang_preprocessor_flags: dict[str, list[str]] = _,
libraries: list[str] = _,
licenses: list[str] = _,
link_group: None | str = _,
link_group_map: None | str | list[(str, list[(None | str | list[None | str], str, None | str | list[str], None | str)], None | dict[str, typing.Any])] = _,
link_ordering: None | str = _,
link_style: None | str = _,
link_whole: bool = _,
linker_extra_outputs: list[str] = _,
linker_flags: list[str] = _,
local_linker_flags: list[str] = _,
module_name: None | str = _,
platform_compiler_flags: list[(str, list[str])] = _,
platform_deps: list[(str, list[str])] = _,
platform_headers: list[(str, list[str] | dict[str, str])] = _,
platform_linker_flags: list[(str, list[str])] = _,
platform_preprocessor_flags: list[(str, list[str])] = _,
platform_srcs: list[(str, list[str | (str, list[str])])] = _,
post_linker_flags: list[str] = _,
post_platform_linker_flags: list[(str, list[str])] = _,
precompiled_header: None | str = _,
preferred_linkage: str = _,
prefix_header: None | str = _,
preprocessor_flags: list[str] = _,
public_include_directories: list[str] = _,
public_system_include_directories: list[str] = _,
raw_headers: list[str] = _,
reexport_all_header_dependencies: None | bool = _,
resources: list[str] | dict[str, str] = _,
sdk_modules: list[str] = _,
soname: None | str = _,
srcs: list[str | (str, list[str])] = _,
static_library_basename: None | str = _,
suffix_all: bool = _,
support_shlib_interfaces: bool = _,
supported_platforms_regex: None | str = _,
supports_merged_linking: None | bool = _,
thin_lto: bool = _,
type_stub: None | str = _,
use_archive: None | bool = _,
used_by_wrap_script: bool = _,
uses_cxx_explicit_modules: bool = _,
uses_explicit_modules: bool = _,
version_universe: None | str = _,
weak_framework_names: list[str] = _
) -> None
A cxx_python_extension()
rule is a variant of a C/C++ library which is built as a Python module. As such, it has a module name formed by the base_module
parameter and the rule name.
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this onebase_module
: The package in which the specified source files and resources should reside in their final location in the top-level binary. If unset, Buck uses the project-relative directory that contains the BUCK file.compiler_flags
: Flags to use when compiling any of the above sources (which require compilation).deps
: Other rules that listsrcs
from which this rule imports.header_namespace
: A path prefix when including headers of this target. Defaults to the path from the root of the repository to the directory where this target is defined. Can contain forward slashes (/
), but cannot start with one. Seeheaders
for more information.headers
: The set of header files that are made available for inclusion to the source files in this target. These should be specified as either a list of header files or a dictionary of header names to header files. The header name can contain forward slashes (/
). The headers can be included with#include "$HEADER_NAMESPACE/$HEADER_NAME"
or#include <$HEADER_NAMESPACE/$HEADER_NAME>
, where$HEADER_NAMESPACE
is the value of the target'sheader_namespace
attribute, and$HEADER_NAME
is the header name if specified, and the filename of the header file otherwise. Seeheader_namespace
for more information.labels
: Set of arbitrary strings which allow you to annotate abuild rule
with tags that can be searched for over an entire dependency tree usingbuck query()
.link_style
: Determines whether to build and link this rule's dependencies statically or dynamically. Can be eitherstatic
,static_pic
orshared
. Note: since shared libraries re-export its dependencies, depending on multiple shared libraries which themselves have overlapping static dependencies may cause problems if they init using global state.linker_extra_outputs
: Declares extra outputs that the linker emits. These identifiers can be used in$(output ...)
macros inlinker_flags
to interpolate the output path into the linker command line. Useful for custom linkers that emit extra output files.linker_flags
: Flags to add to the linker command line whenever the output from this rule is used in a link operation, such as linked into an executable or a shared library.local_linker_flags
: Flags to add to the linker command line whenever the output from this rule is used in a link operation driven by this rule (e.g. when this rule links a shared library, but not when the output is linked into a shared library by another rule's link group links).platform_compiler_flags
: Platform specific compiler flags. These should be specified as a list of pairs where the first element is an un-anchored regex (in java.util.regex.Pattern syntax) against which the platform name is matched, and the second element is a list of flags to use when compiling the target's sources. Seecompiler_flags
for more information.platform_headers
: Platform specific header files. These should be specified as a list of pairs where the first element is an un-anchored regex (in java.util.regex.Pattern syntax) against which the platform name is matched, and the second element is either a list of header files or a dictionary of header names to header files that will be made available for inclusion to the source files in the target if the platform matches the regex. Seeheaders
for more information.platform_linker_flags
: Platform-specific linker flags. This argument is specified as a list of pairs where the first element in each pair is an un-anchored regex against which the platform name is matched. The regex should usejava.util.regex.Pattern
syntax. The second element in each pair is a list of linker flags. If the regex matches the platform, these flags are added to the linker command line when the output from this rule is used in a link operation.platform_preprocessor_flags
: Platform specific preprocessor flags. These should be specified as a list of pairs where the first element is an un-anchored regex (in java.util.regex.Pattern syntax) against which the platform name is matched, and the second element is a list of flags to use when preprocessing the target's sources. Seepreprocessor_flags
for more information.platform_srcs
: Platform specific source files. These should be specified as a list of pairs where the first element is an un-anchored regex (in java.util.regex.Pattern syntax) against which the platform name is matched, and the second element is either a list of source files or a list of tuples of source files and a list of compilation flags to be preprocessed, compiled and assembled if the platform matches the regex. Seesrcs
for more information.preprocessor_flags
: Flags to use when preprocessing any of the above sources (which require preprocessing).srcs
: The set of C, C++, Objective-C, Objective-C++, or assembly source files to be preprocessed, compiled, and assembled by this rule. We determine which stages to run on each input source based on its file extension. See the GCC documentation for more detail on how file extensions are interpreted. Each element can be either a string specifying a source file (e.g.''
) or a tuple of a string specifying a source file and a list of compilation flags (e.g.('', ['-Wall', '-Werror'])
). In the latter case the specified flags will be used in addition to the rule's other flags when preprocessing and compiling that file (if applicable).
Details
Examples:
# A rule that builds a Python extension from a single .cpp file.
cxx_python_extension(
name = 'mymodule',
base_module = 'foo.bar',
srcs = [
'mymodule.cpp',
],
)
# A library rule which has a single source importing the above extension.
python_library(
name = 'utils',
srcs = [
'utils.py',
],
deps = [
':mymodule',
],
)
## The `utils.py` source, wrapped by the `utils` rule above.
## Import the C/C++ extension build above.
from foo.bar import mymodule
...
cxx_test
def cxx_test(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
_cxx_hacks: str = _,
_cxx_toolchain: str = _,
_inject_test_env: str = _,
_remote_test_execution_toolchain: str = _,
additional_coverage_targets: list[str] = _,
allow_cache_upload: None | bool = _,
anonymous_link_groups: bool = _,
args: list[str] = _,
auto_link_groups: bool = _,
binary_linker_flags: list[str] = _,
bolt_flags: list[str] = _,
bolt_profile: None | str = _,
buck2_compatibility: str = _,
compiler_flags: list[str] = _,
constraint_overrides: list[str] = _,
contacts: list[str] = _,
coverage_instrumentation_compiler_flags: list[str] = _,
cxx_runtime_type: None | str = _,
default_host_platform: None | str = _,
default_platform: None | str = _,
defaults: dict[str, str] = _,
deps: list[str] = _,
deps_query: None | str = _,
devirt_enabled: bool = _,
distributed_thinlto_partial_split_dwarf: bool = _,
enable_distributed_thinlto: bool = _,
env: dict[str, str] = _,
executable_name: None | str = _,
exported_needs_coverage_instrumentation: bool = _,
fat_lto: bool = _,
focused_list_target: None | str = _,
framework: None | str = _,
frameworks: list[str] = _,
header_namespace: None | str = _,
headers: list[str] | dict[str, str] = _,
headers_as_raw_headers_mode: None | str = _,
include_directories: list[str] = _,
labels: list[str] = _,
lang_compiler_flags: dict[str, list[str]] = _,
lang_platform_compiler_flags: dict[str, list[(str, list[str])]] = _,
lang_platform_preprocessor_flags: dict[str, list[(str, list[str])]] = _,
lang_preprocessor_flags: dict[str, list[str]] = _,
libraries: list[str] = _,
licenses: list[str] = _,
link_deps_query_whole: bool = _,
link_execution_preference: None | str = _,
link_group: None | str = _,
link_group_deps: list[str] = _,
link_group_map: None | str | list[(str, list[(None | str | list[None | str], str, None | str | list[str], None | str)], None | dict[str, typing.Any])] = _,
link_group_min_binary_node_count: None | int = _,
link_group_public_deps_label: None | str = _,
link_ordering: None | str = _,
link_style: None | str = _,
link_whole: bool = _,
linker_extra_outputs: list[str] = _,
linker_flags: list[str] = _,
platform_compiler_flags: list[(str, list[str])] = _,
platform_deps: list[(str, list[str])] = _,
platform_headers: list[(str, list[str] | dict[str, str])] = _,
platform_linker_flags: list[(str, list[str])] = _,
platform_preprocessor_flags: list[(str, list[str])] = _,
platform_srcs: list[(str, list[str | (str, list[str])])] = _,
post_linker_flags: list[str] = _,
post_platform_linker_flags: list[(str, list[str])] = _,
precompiled_header: None | str = _,
prefer_stripped_objects: bool = _,
prefix_header: None | str = _,
preprocessor_flags: list[str] = _,
raw_headers: list[str] = _,
remote_execution: None | str | dict[str, None | bool | int | str | list[dict[str, str]] | dict[str, str]] = _,
remote_execution_action_key_providers: None | str = _,
resources: list[str] | dict[str, str] = _,
run_test_separately: None | bool = _,
srcs: list[str | (str, list[str])] = _,
test_rule_timeout_ms: None | int = _,
thin_lto: bool = _,
use_default_test_main: None | bool = _,
version_universe: None | str = _,
weak_framework_names: list[str] = _
) -> None
A cxx_test() rule builds a C/C++ binary against a C/C++ testing framework and runs it as part of test
.
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this oneallow_cache_upload
: Whether to allow uploading the output of this rule to be uploaded to cache when the action is executed locally if the configuration allows (i.e. there is a cache configured and the client has permission to write to it).args
: A list of additional arguments to pass to the test when it's run.It is also possible to expand references to other rules within these arguments, using builtin
string parameter macros
:$(location //path/to:target)
Expands to the location of the output of the build rule. This means that you can refer to these without needing to be aware of how Buck is storing data on the disk mid-build.compiler_flags
: Flags to use when compiling any of the above sources (which require compilation).deps_query
: Status: experimental/unstable. The deps query takes a query string that accepts the following query functions, and appends the output of the query to the declared deps:attrfilter
deps
except
intersect
filter
kind
set
union
The macro
$declared_deps
may be used anywhere a target literal pattern is expected in order to refer to the explicit deps of this rule as they appear in the rule's definition. For example, if your build rule declares
android_library(
name = 'lib',
deps = ['//foo:foo'],
deps_query = '$declared_deps',
)then the macro
$declared_deps
would be expanded to a literalset(//foo:foo)
. Some example queries:
"filter({name_regex}, $declared_deps)".format(name_regex='//.*')
"attrfilter(annotation_processors, com.foo.Processor, $declared_deps)"
"deps('//foo:foo', 1)"Note: any targets included in this query must also be present in
deps
.env
: A map of environment names and values to set when running the test.It is also possible to expand references to other rules within the values of these environment variables, using builtin
string parameter macros
:$(location //path/to:target)
Expands to the location of the output of the build rule. This means that you can refer to these without needing to be aware of how Buck is storing data on the disk mid-build.framework
: Unused.headers
: The set of header files that are made available for inclusion to the source files in this target. These should be specified as either a list of header files or a dictionary of header names to header files. The header name can contain forward slashes (/
). The headers can be included with#include "$HEADER_NAMESPACE/$HEADER_NAME"
or#include <$HEADER_NAMESPACE/$HEADER_NAME>
, where$HEADER_NAMESPACE
is the value of the target'sheader_namespace
attribute, and$HEADER_NAME
is the header name if specified, and the filename of the header file otherwise. Seeheader_namespace
for more information.include_directories
: A list of include directories (withraw_headers
) to be added to the compile command for compiling this target (via-I
). An include directory is relative to the current package.link_execution_preference
: The execution preference for linking. Options are:- any : No preference is set, and the link action will be performed based on buck2's executor configuration.
- full_hybrid : The link action will execute both locally and remotely, regardless of buck2's executor configuration (if the executor is capable of hybrid execution). The use_limited_hybrid setting of the hybrid executor is ignored.
- local : The link action will execute locally if compatible on current host platform.
- local_only : The link action will execute locally, and error if the current platform is not compatible.
- remote : The link action will execute remotely if a compatible remote platform exists, otherwise locally.
The default is None, expressing that no preference has been set on the target itself.
link_group_deps
: Additional targets to traverse when building link groups, but which should not be direct dependencies of the main executable.link_group_public_deps_label
: Surface nodes with this label as "public" nodes in the main executable when linking with with link groups.link_style
: Determines whether to build and link this rule's dependencies statically or dynamically. Can be eitherstatic
,static_pic
orshared
.linker_flags
: Flags to add to the linker command line whenever the output from this rule is used in a link operation, such as linked into an executable or a shared library.preprocessor_flags
: Flags to use when preprocessing any of the above sources (which require preprocessing).raw_headers
: The set of header files that can be used for inclusion to the source files in the target and all targets that transitively depend on it. Buck doesn't add raw headers to the search path of a compiler/preprocessor automatically.include_directories
andpublic_include_directories
are the recommended way to add raw headers to the search path (they will be added via-I
).compiler_flags
,preprocessor_flags
andexported_preprocessor_flags
can also be used to add such raw headers to the search path if inclusion via-isystem
or-iquote
is needed.raw_headers
cannot be used together withheaders
orexported_headers
in the same target.srcs
: The set of C, C++, Objective-C, Objective-C++, or assembly source files to be preprocessed, compiled, and assembled by this rule. We determine which stages to run on each input source based on its file extension. See the GCC documentation for more detail on how file extensions are interpreted. Each element can be either a string specifying a source file (e.g.''
) or a tuple of a string specifying a source file and a list of compilation flags (e.g.('', ['-Wall', '-Werror'])
). In the latter case the specified flags will be used in addition to the rule's other flags when preprocessing and compiling that file (if applicable).test_rule_timeout_ms
: If set specifies the maximum amount of time (in milliseconds) in which all of the tests in this rule should complete. This overrides the defaultrule_timeout
if any has been specified in.buckconfig
.
Details
Examples:
# A rule that builds and runs C/C++ test using gtest.
cxx_test(
name = 'echo_test',
srcs = [
'echo_test.cpp',
],
)
cxx_toolchain
def cxx_toolchain(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
_dep_files_processor: str = _,
_dumpbin_toolchain_path: None | str = _,
_mk_comp_db: str = _,
_mk_hmap: str = _,
_msvc_hermetic_exec: str = _,
_remap_cwd_tool: str = _,
archive_contents: str = _,
archive_symbol_table: bool = _,
archiver: str,
archiver_flags: list[str] = _,
archiver_reads_inputs: bool = _,
archiver_supports_argfiles: bool = _,
archiver_type: str,
asm_compiler: None | str = _,
asm_compiler_flags: list[str] = _,
asm_compiler_type: None | str = _,
asm_preprocessor: None | str = _,
asm_preprocessor_flags: list[str] = _,
asm_preprocessor_type: None | str = _,
assembler: str,
assembler_flags: list[str] = _,
assembler_preprocessor: None | str = _,
assembler_preprocessor_flags: list[str] = _,
assembler_preprocessor_type: None | str = _,
assembler_type: None | str = _,
binary_extension: None | str = _,
bolt_enabled: bool = _,
buck2_compatibility: str = _,
c_compiler: str,
c_compiler_allow_cache_upload: None | bool = _,
c_compiler_flags: list[str] = _,
c_compiler_type: None | str = _,
c_preprocessor_flags: list[str] = _,
cache_links: bool = _,
clang_remarks: None | str = _,
clang_trace: None | bool = _,
compiler_type: None | str = _,
conflicting_header_basename_exemptions: list[str] = _,
contacts: list[str] = _,
cpp_dep_tracking_mode: str = _,
cuda_compiler: None | str = _,
cuda_compiler_flags: list[str] = _,
cuda_compiler_type: None | str = _,
cuda_dep_tracking_mode: str = _,
cuda_preprocessor_flags: list[str] = _,
cvtres_compiler: None | str = _,
cvtres_compiler_flags: list[str] = _,
cvtres_compiler_type: None | str = _,
cvtres_preprocessor_flags: list[str] = _,
cxx_compiler: str,
cxx_compiler_allow_cache_upload: None | bool = _,
cxx_compiler_flags: list[str] = _,
cxx_compiler_type: None | str = _,
cxx_preprocessor_flags: list[str] = _,
debug_path_prefix_map_sanitizer_format: None | str = _,
default_host_platform: None | str = _,
detailed_untracked_header_messages: bool = _,
dist_lto_tools: str = _,
dist_thin_lto_codegen_flags: list[str] = _,
filepath_length_limited: bool = _,
gcno_files: bool = _,
generate_linker_maps: bool = _,
headers_as_raw_headers_mode: None | str = _,
headers_whitelist: list[str] = _,
hip_compiler: None | str = _,
hip_compiler_flags: list[str] = _,
hip_compiler_type: None | str = _,
hip_preprocessor_flags: list[str] = _,
labels: list[str] = _,
licenses: list[str] = _,
link_ordering: str = _,
link_path_normalization_args_enabled: bool = _,
link_style: str = _,
link_weight: int = _,
linker: str,
linker_flags: list[str] = _,
linker_type: str,
llvm_link: None | str = _,
lto_mode: str = _,
min_sdk_version: None | str = _,
nm: str,
objcopy_for_shared_library_interface: str,
objcopy_recalculates_layout: bool = _,
objdump: None | str = _,
object_file_extension: str = _,
object_format: str = _,
pic_behavior: str = _,
pic_type_for_shared_linking: str = _,
placeholder_tool: None | str = _,
platform_name: None | str = _,
post_linker_flags: list[str] = _,
private_headers_symlinks_enabled: bool = _,
public_headers_symlinks_enabled: bool = _,
ranlib: None | str = _,
ranlib_flags: list[str] = _,
rc_compiler: None | str = _,
rc_compiler_flags: list[str] = _,
rc_compiler_type: None | str = _,
rc_preprocessor_flags: list[str] = _,
remap_cwd: bool = _,
requires_archives: bool = _,
requires_objects: bool = _,
sanitizer_runtime_enabled: bool = _,
sanitizer_runtime_files: list[str] = _,
shared_dep_runtime_ld_flags: list[str] = _,
shared_library_extension: str = _,
shared_library_interface_flags: list[str] = _,
shared_library_interface_mode: str = _,
shared_library_interface_producer: None | str = _,
shared_library_interface_type: str,
shared_library_versioned_extension_format: str = _,
split_debug_mode: str = _,
static_dep_runtime_ld_flags: list[str] = _,
static_library_extension: str = _,
static_pic_dep_runtime_ld_flags: list[str] = _,
strip: str,
strip_all_flags: None | list[str] = _,
strip_debug_flags: None | list[str] = _,
strip_non_global_flags: None | list[str] = _,
supports_distributed_thinlto: bool = _,
target_sdk_version: None | str = _,
use_archiver_flags: bool = _,
use_arg_file: bool = _,
use_dep_files: None | bool = _,
use_header_map: bool = _
) -> None
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this onec_compiler_allow_cache_upload
: Whether to allow uploading of object files to cache when the compile action is executed locally and the configuration allows uploads (i.e., there is a cache configured and the client has permission to write to it).cxx_compiler_allow_cache_upload
: Whether to allow uploading of object files to cache when the compile action is executed locally and the configuration allows uploads (i.e., there is a cache configured and the client has permission to write to it).link_style
: The default value of thelink_style
attribute for rules that use this toolchain.
d_binary
def d_binary(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
buck2_compatibility: str = _,
contacts: list[str] = _,
default_host_platform: None | str = _,
deps: list[str] = _,
labels: list[str] = _,
licenses: list[str] = _,
linker_flags: list[str] = _,
srcs: list[str] | dict[str, str] = _
) -> None
A d_binary() rule builds a native executable from the supplied set of D source files and dependencies.
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this onedeps
: The set of dependencies of this rule. Each element should be a string specifying a d_library rule defined elsewhere (e.g.':foo'
or '//foo:bar').linker_flags
: The list of flags to be passed to the linker. Each element should be a string specifying a linker flag (e.g.'--as-needed'
).srcs
: The set of D source files to be compiled by this rule. Each element should be a string specifying a source file (e.g.'foo/bar.d'
).
Details
Examples:
# A rule that builds a D native executable from a single .d file
# and a library dependency.
d_binary(
name='greet',
srcs=[
'greet.d',
],
deps=[
':greeting',
],
)
d_library(
name='greeting',
srcs=[
'greeting.d',
],
deps=[
':join',
],
)
d_library(
name='join',
srcs=[
'join.d',
],
)
d_library
def d_library(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
buck2_compatibility: str = _,
contacts: list[str] = _,
default_host_platform: None | str = _,
deps: list[str] = _,
labels: list[str] = _,
licenses: list[str] = _,
linker_flags: list[str] = _,
srcs: list[str] | dict[str, str] = _
) -> None
A d_library() rule represents a set of D source files.
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this onedeps
: The set of dependencies of this rule. Each element should be a string specifying a d_library rule defined elsewhere (e.g.':foo'
or '//foo:bar').srcs
: The set of D source files to be compiled by this rule. Each element should be a string specifying a source file (e.g.'foo/bar.d'
).
Details
Examples:
# A simple library with a single source file and a single dependency.
d_library(
name='greeting',
srcs=[
'greeting.d',
],
deps=[
':join',
],
)
d_library(
name='join',
srcs=[
'join.d',
],
)
d_test
def d_test(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
buck2_compatibility: str = _,
contacts: list[str] = _,
default_host_platform: None | str = _,
deps: list[str] = _,
labels: list[str] = _,
licenses: list[str] = _,
linker_flags: list[str] = _,
srcs: list[str] | dict[str, str] = _,
test_rule_timeout_ms: None | int = _
) -> None
A d_test()
rule is used to define a set of D source files that contain tests to run via D's unittest support. The source code of the test must provide a main() function.
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this onedeps
: The set of dependencies of this rule. Each element should be a string specifying a d_library rule defined elsewhere (e.g.':foo'
or '//foo:bar').labels
: A list of labels to be applied to these tests. These labels are arbitrary text strings and have no meaning within buck itself. They can, however, have meaning for you as a test author (e.g.,smoke
orfast
). A label can be used to filter or include a specificd_test()
rule when executingbuck test
srcs
: The set of D source files to be compiled by this rule. Each element should be a string specifying a source file (e.g.'foo/bar.d'
).test_rule_timeout_ms
: If set specifies the maximum amount of time (in milliseconds) in which all of the tests in this rule should complete. This overrides the defaultrule_timeout
if any has been specified in.buckconfig
.
Details
Examples:
# A rule that builds and runs D test with a single source file.
d_test(
name = 'test',
srcs = [
'test.d',
],
)
erlang_app
def erlang_app(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
_toolchain: str = _,
app_src: None | str = _,
applications: list[str] = _,
buck2_compatibility: str = _,
build_edoc_chunks: bool = _,
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, list[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 targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this oneapp_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.build_edoc_chunks
: This attribute controls if the output of the builds also create edoc chunks.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",
],
)
erlang_app_includes
def erlang_app_includes(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
_toolchain: str = _,
application_name: str,
buck2_compatibility: str = _,
contacts: list[str] = _,
includes: list[str] = _,
labels: list[str] = _,
os_env: None | dict[str, str] = _
) -> None
This rule is a supplementary 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 targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this oneos_env
: This attribute allows to set additional values for the operating system environment for invocations to the Erlang toolchain.
erlang_escript
def erlang_escript(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
_toolchain: str = _,
buck2_compatibility: str = _,
bundled: bool = _,
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 targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this onebundled
: Setting bundled toTrue
does generate a folder structure and escript trampoline instead of an archive.configs
: This attribute allows to set config files for the escript. The dependencies that are typically used here areexport_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 applicationspriv
directory in the escript. Similar to files added through theresources
field, thepriv
folders files can then be accessed byescript"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 amain/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 useescript:extract/2
, which will extract the entire escript in memory. The relevant files can then be accessed through thearchive
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",
],
)
erlang_otp_binaries
def erlang_otp_binaries(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
buck2_compatibility: str = _,
contacts: list[str] = _,
erl: str,
erlc: str,
escript: str,
labels: list[str] = _,
os_env: None | dict[str, str] = _
) -> None
This target defines the executables for the Erlang toolchains, and is required to defined a toolchain.
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this oneerl
: Reference toerl
binaryerlc
: Reference toerlc
binaryescript
: Reference toescript
binaryos_env
: This attribute allows to set additional values for the operating system environment for invocations to the Erlang toolchain.
Details
Examples:
erlang_otp_binaries( name = "local", erl = "local/erl", erlc = "local/erlc", escript = "local/escript", )
erlang_release
def erlang_release(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
_toolchain: str = _,
applications: list[str | (str, str)],
buck2_compatibility: str = _,
contacts: list[str] = _,
include_erts: bool = _,
labels: list[str] = _,
multi_toolchain: None | list[str] = _,
os_env: None | dict[str, str] = _,
overlays: dict[str, list[str]] = _,
release_name: None | str = _,
version: str = _
) -> None
The erlang_release
target builds OTP releases. Please refer to the OTP documentation for more details about releases.
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this oneapplications
: This field specifies the list of applications that the release should start in the given order, and optionally the start type. Top-level applications without given start type are started with typepermanent
.include_erts
: This field controls whether OTP applications and the Erlang runtime system should be included as part of the release. Please note, that at the moment the erts folder is justerts/
.multi_toolchain
: This field controls whether the release should be built with a single toolchain, or multiple toolchains. In the latter case, all output paths are prefixed with the toolchain name.os_env
: This attribute allows to set additional values for the operating system environment for invocations to the Erlang toolchain.overlays
: Overlays can be used to add files to the release. They are specified as mapping from path (from the release root) to list of targets. The targets files are places flat at the target location with their basename.release_name
: The release name can explicitly be set by this field. This overwrites the default from the target name.version
: Theversion
field specifies the release version. The release version is used in the release resource file, and is part of the path for the folder containing the boot scripts.
Details
The erlang_release
target does by default (without overlays) package:
- applications that are required to start the release
- release resource file
<relname>.rel
(see rel(4)) - boot script
start.script
(see rel(4)) - binary boot script
start.boot
bin/release_variables
The release_variables
file contains release name, version, and erts version in shell syntax, e.g.
ERTS_VSN="12.1.2"
REL_NAME="rel1"
REL_VSN="1.0.0"
The target name doubles as the default release name. If the release_name
attribute is used, the release name will be
sources from there instead.
Examples:
erlang_release(
name = "world",
version = "1.0.0",
applications = [
"//apps//app_a:app_a",
"//apps//app_b:app_b",
],
overlays = {
"releases/1.0.0": [
":sys.config.src",
],
"bin": [
":start.sh",
],
},
)
export_file(
name = "sys.config.src",
src = "sys.config",
)
export_file(
name = "start.sh",
src = "start.sh",
)
erlang_test
def erlang_test(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
_artifact_annotation_mfa: str = _,
_cli_lib: str = _,
_ct_opts: str = _,
_providers: str = _,
_test_binary: str = _,
_test_binary_lib: str = _,
_toolchain: str = _,
_trampoline: None | str = _,
_trampolines: None | list[str] = _,
buck2_compatibility: str = _,
common_app_env: dict[str, str] = _,
config_files: list[str] = _,
contacts: list[str] = _,
deps: list[str] = _,
env: dict[str, str] = _,
extra_ct_hooks: list[str] = _,
extra_erl_flags: list[str] = _,
labels: list[str] = _,
os_env: None | dict[str, str] = _,
preamble: str = _,
property_tests: list[str] = _,
remote_execution: None | str | dict[str, None | bool | int | str | list[dict[str, str]] | dict[str, str]] = _,
resources: list[str] = _,
shell_configs: list[str] = _,
shell_libs: list[str] = _,
suite: str
) -> None
The erlang_test
ruls defines a test target for a single test suite. In most cases you want to define multiple suites in one go. The erlang_tests
macro allows users to generate erlang_test
targets for multiple test suites. Each suite <name>_SUITE.erl
will have a generated hidden erlang_test
target whose name is <name>_SUITE
.
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this one_trampoline
: DEPRECATED. Use _trampolines instead.common_app_env
: Application environment variables for thecommon
application.config_files
: Will specify what config files the erlang beam machine running test with should load, for reference look at OTP documentation. These ones should consist of default_output of some targets. In general, this field is filled with target coming from thenexport_file
rule, as in the example below.deps
: The set of dependencies needed for all suites included in the target to compile and run. They could be eithererlang_app(lication)
orerlang_test
targets, although the latter is discouraged. If some suites need to access common methods, a common helper file should be created and included in thesrcs
field of theerlang_tests
target. If some applications are included as dependencies of this target, their private include will automatically be pulled and made available for the test. That allows tests to access the private header files from the applications under test.env
: Add the given values to the environment variables with which the test is executed.extra_ct_hooks
: List of additional Common Test hooks. The strings are interpreted as Erlang terms.extra_erl_flags
: List of additional command line arguments given to the erl command invocation. These arguments are added to the front of the argument list.os_env
: This attribute allows to set additional values for the operating system environment for invocations to the Erlang toolchain.resources
: Theresources
field specifies targets whose default output are placed in the testdata_dir
directory for all the suites present in the macro target. Additionally, if data directory are present in the directory along the suite, this one will be pulled automatically for the relevant suite.Any target can be used, e.g. if you want to place a built escript in the
data_dir
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.suite
: The source file for the test suite. If you are using the macro, you should use thesuites
attribute instead.The suites attribute specifies which erlang_test targets should be generated. For each suite "path_to_suite/suite_SUITE.erl" an implicit 'erlang_test' target suite_SUITE will be generated.
Details
Each erlang_test
target implements tests using the Common Test library
OTP documentation. They can,
although it is not recommended, also act as dependencies of other tests. The
default output of this rule is a "test_folder", consisting of the compiled test suite
and the data directory.
For each suite <name>_SUITE.erl
, if a data_dir <name>_SUITE_data
is present along the suite,
(as per the data_dir naming scheme for ct),
it will automatically adds the corresponding resource target to the generated test target of the suite.
Resources will be placed in the Data directory (data_dir)
of each of the suite.
It allows the writer of the rule to add global configuration files and global default
dependencies (e.g meck
). These ones should be specified using global
variables erlang.erlang_tests_default_apps
and erlang.erlang_tests_default_config
respectively.
The erlang_tests
macro forwards all attributes to the erlang_test
. It defines some attributes
that control how the targets get generated:
srcs
([source]): Set of files that the suites might depend on and that are not part of any specific application. A "meta" application having those files as sources will automatically be created, and included in the dependencies of the tests.
One can call
buck2 build //my_app:test_SUITE
to compile the test files together with its dependencies.buck2 test //my_app:other_test_SUITE
to run the test.buck2 run //my_app:other_test_SUITE
to open an interactive test shell, where tests can be run iteratively.
buck2 test will rely on tpx to run the suite. To get access to tpx commands, add --
after the
target. For example:
buck2 test //my_app:other_test_SUITE -- --help
will print the list of tpx available command line parameters.buck2 test //my_app:other_test_SUITE -- group.mycase
will only run those test cases that match the patterngroup.mycase
Examples:
erlang_test( name = "unit_test_SUITE", suite = "unit_test_SUTIE.erl", deps = [":my_other_app"], contacts = ["author@email.com"], )
erlang_tests( suites = ["test_SUITE.erl", "other_test_SUITE".erl], deps = [":my_app"], contacts = ["author@email.com"], )
export_file
def export_file(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
buck2_compatibility: str = _,
contacts: list[str] = _,
default_host_platform: None | str = _,
labels: list[str] = _,
licenses: list[str] = _,
mode: None | str = _,
out: None | str = _,
src: None | str = _
) -> None
An export_file()
takes a single file or folder and exposes it so other rules can use it.
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this onemode
: How files are referenced internally in buck. If set to 'copy', then a full copy will be made into the new location in buck-out. If set to 'reference', the original file will be used by internal build rules in-place. However, this mode does not work across repositories or if the 'out' property is set. For read-only operations, 'reference' can be more performant.out
: The name which the file will be called if another rule depends on it instead of the name it already has.src
: The path to the file that should be exported.
Details
Examples:
The best way to see how the export_file()
rule works is with some examples. The
common case is:
export_file(
name = 'example.html',
)
# This is equivalent to
export_file(
name = 'example.html',
src = 'example.html',
out = 'example.html',
)
It is sometimes useful to refer to the file not by its path, but by a more logical name:
export_file(
name = 'example',
src = 'example.html',
)
# This is equivalent to
export_file(
name = 'example',
src = 'example.html',
out = 'example.html',
)
Finally, there are occasions where you want to export a file more than once but want to copy it to a different name for each output:
export_file(
name = 'runner',
src = 'RemoteRunner.html',
)
export_file(
name = 'runner_hta',
src = 'RemoteRunner.html',
out = 'RemoteRunner.hta',
)
Using the export_file()
rule is also simple:
export_file(
name = 'example',
src = 'example.html',
)
genrule(
name = 'demo',
out = 'result.html',
cmd = 'cp $(location :example) $OUT',
)
external_test_runner
def external_test_runner(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
binary: str,
buck2_compatibility: str = _,
contacts: list[str] = _,
default_host_platform: None | str = _,
labels: list[str] = _,
licenses: list[str] = _
) -> None
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this one
filegroup
def filegroup(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
buck2_compatibility: str = _,
contacts: list[str] = _,
copy: bool = _,
default_host_platform: None | str = _,
labels: list[str] = _,
licenses: list[str] = _,
srcs: list[str] | dict[str, str] = _
) -> None
This rule provides access to a set of files.
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this onesrcs
: The set of files to include in this rule.
Details
Files are accessible to genrule()
s by using their relative path
after a $(location)
string parameter macro.
Other rules may handle filegroup()
rules natively for attributes
such as resources.
Examples:
In this example a target exports .xml
files from all subdirectories
in resources
.
filegroup(
name = 'example',
srcs = glob(['resources/**/*.xml']),
)
genrule(
name = 'process_xml',
out = 'processed.xml',
cmd = '$(exe //example:tool) -in $(location :example)/resources/file.xml > $OUT',
)
gen_aidl
def gen_aidl(
*,
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] = _,
_android_toolchain: str = _,
_apple_platforms: dict[str, str] = _,
_exec_os_type: str = _,
_java_toolchain: str = _,
aidl: str,
aidl_srcs: list[str] = _,
buck2_compatibility: str = _,
contacts: list[str] = _,
default_host_platform: None | str = _,
deps: list[str] = _,
import_path: str = _,
import_paths: list[str] = _,
labels: list[str] = _,
licenses: list[str] = _
) -> None
A gen_aidl()
rule is used to generate .java
files from .aidl
files.
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this oneaidl
: The path to an.aidl
file to convert to a.java
file.aidl_srcs
: Path to.aidl
files the targetaidl
file imports.deps
: A list of rules that must be built before this rule.import_path
: The search path for import statements for the aidl command. (This is the-I
argument when invoking aidl from the command line. For many apps it will be the base dir where all aidl files are, with project root as its parent, e.g.app/src/main/aidl
.). This is the same as the path to theaidl
file relative to what would be returned fromroot
.
Details
Examples:
android_library(
name = 'lib',
srcs = glob(['**/*.java']) + [':aidl'],
manifest = '//res/org/opencv:manifest',
deps = [
'//res/org/opencv:res',
],
visibility = [ 'PUBLIC' ],
)
gen_aidl(
name = 'aidl',
aidl = 'engine/OpenCVEngineInterface.aidl',
import_path = 'java/',
)
genrule
def genrule(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
_build_only_native_code: bool = _,
_exec_os_type: str = _,
_genrule_toolchain: str = _,
always_print_stderr: bool = _,
bash: None | str = _,
buck2_compatibility: str = _,
cacheable: None | bool = _,
cmd: None | str = _,
cmd_exe: None | str = _,
contacts: list[str] = _,
default_host_platform: None | str = _,
default_outs: None | list[str] = _,
enable_sandbox: None | bool = _,
env: dict[str, str] = _,
environment_expansion_separator: None | str = _,
executable: None | bool = _,
labels: list[str] = _,
licenses: list[str] = _,
metadata_env_var: None | str = _,
metadata_path: None | str = _,
need_android_tools: bool = _,
no_outputs_cleanup: bool = _,
out: None | str = _,
outs: None | dict[str, list[str]] = _,
remote: None | bool = _,
remote_execution_dependencies: list[dict[str, str]] = _,
srcs: list[str] | dict[str, str] = _,
type: None | str = _,
weight: None | int = _
) -> None
A genrule()
is used to generate files from a shell command. It must produce a single output file or folder.
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this onebash
: A platform-specific version of the shell command parametercmd
. It runs on Linux and UNIX systems—including OSX—on whichbash
is installed. It has a higher priority thancmd
. Thebash
argument is run with/usr/bin/env bash -c
. It has access to the same set of macros and variables as thecmd
argument.cmd
: The shell command to run to generate the output file. It is the fallback forbash
andcmd_exe
arguments. The following environment variables are populated by Buck and available to the shell command. They are accessed using the syntax:${<variable>}
Example:
${SRCS}
${SRCS}
A string expansion of the
srcs
argument delimited by theenvironment_expansion_separator
argument where each element ofsrcs
will be translated into a relative path.${SRCDIR}
The relative path to a directory to which sources are copied prior to running the command.
${OUT}
The output file or directory for the
genrule()
. This variable will have whatever value is specified by theout
argument if not using named outputs. If using named outputs, this variable will be the output directory.The value should be a valid filepath. The semantics of the shell command determine whether this filepath is treated as a file or a directory. If the filepath is a directory, then the shell command needs to create it if not using named outputs. Otherwise, it will be automatically created. All outputs (directories and files) must be readable, writable, and (in the case of directories) executable by the current user.
The file or directory specified by this variable must always be written by this command. If not, the execution of this rule will be considered a failure, halting the build process.
${TMP}
A temporary directory which can be used for intermediate results and will not be bundled into the output.
cmd_exe
: A platform-specific version of the shell command parametercmd
. It runs on Windows and has a higher priority thancmd
. Thecmd_exe
argument is run withcmd.exe /v:off /c
. It has access to the same set of macros and variables as thecmd
argument.default_outs
: Default output which must be present if theouts
arg is present. Otherwise does not apply.If a rule with
outs
is consumed without an output label, the default output is returned. The default output does not need to be present in any of the named outputs defined inouts
.Note that a maximum of one value may be present in this list. For example:
default_outs = [ "output_one", ]
is valid, whereas
default_outs = [ "output_one", "output_two", ]
is not.
enable_sandbox
: Whether this target should be executed in a sandbox or not.env
: A map of variables to be set in the environment where the shell command is run.environment_expansion_separator
: The delimiter between paths in environment variables, such as SRCS, that can contain multiple paths. It can be useful to specify this parameter if the paths could contain spaces.executable
: Whether the output of the genrule is itself executable. Marking an output as executable makesbuck run
and$(exe ...)
macro expansion work with this target.out
: The name of the output file or directory. The complete path to this argument is provided to the shell command through theOUT
environment variable. Only one ofout
orouts
may be present.outs
: Mapping definingnamed outputs
to output paths relative to the rule's output directory. Only one ofout
orouts
may be present.Example:
genrule(
name = "named_outputs",
outs = {
"output1": [
"out1.txt",
],
"output2": [
"out2.txt",
],
},
default_outs = [ "out1.txt" ],
cmd = "echo something> $OUT/out1.txt && echo another> $OUT/out2.txt",
)Note that a maximum of one value may be present in the list in this map. For example:
outs = {
"output1": [
"out1.txt",
],
},is valid, whereas
outs = {
"output1": [
"out1.txt",
"out2.txt",
],
},is not.
remote
: Opts this genrule in to remote execution. Note that it is only safe to execute a genrule remotely if it is completely hermetic and completely and correctly describes its dependencies. Defaults to false. This parameter is unstable. It is subject to removal, default reversal, and other arbitrary changes in the future.srcs
: Either a list or a map of the source files which Buck makes available to the shell command at the path in theSRCDIR
environment variable. If you specify a list, the source files are the names in the list. If you specify a map, the source files are made available as the names in the keys of the map, where the values of the map are the original source file names.type
: Specifies the type of this genrule. This is used for logging and is particularly useful for grouping genrules that share an underlying logical "type".For example, if you have the following
cxx_genrule
defined in the root directory of your Buck project
cxx_genrule(
name = 'cxx_gen',
type = 'epilog',
cmd = 'touch finish.txt; cp finish.txt $OUT',
out = 'finish.txt'
)then the following
buck query
command
buck query "attrfilter( type, 'epilog', '//...' )"returns
//:cxx_genweight
: How many local slots these genrule should take when executing locally.
Details
Examples:
This genrule() uses a Python script to derive a new
AndroidManifest.xml
from an
AndroidManifest.xml
in the source tree.
Note you don't need to prepend execution commands with
python
: Buck knows how to execute different
kinds of binaries using $(exe)
command.
genrule(
name = 'generate_manifest',
srcs = [
'AndroidManifest.xml',
],
bash = '$(exe //python/android:basic_to_full) ' '$SRCDIR/AndroidManifest.xml > $OUT',
cmd_exe = '$(exe //python/android:basic_to_full) ' '%SRCDIR%\AndroidManifest.xml > %OUT%',
out = 'AndroidManifest.xml',
)
genrule(
name = 'generate_manifest_with_named_outputs',
srcs = [
'AndroidManifest.xml',
],
bash = '$(exe //python/android:basic_to_full) ' '$SRCDIR/AndroidManifest.xml > $OUT/AndroidManifest.xml',
cmd_exe = '$(exe //python/android:basic_to_full) ' '%SRCDIR%\AndroidManifest.xml > %OUT%\AndroidManifest.xml',
outs = {
"manifest": [ "AndroidManifest.xml" ],
},
default_outs = [ "AndroidManifest.xml" ],
)
For named outputs, build with any of the following:
buck build //:generate_manifest_with_named_outputs
buck build //:generate_manifest_with_named_outputs[manifest]
Consume in srcs
with:
export_file(
name = "magic1",
src = ":generate_manifest_with_named_outputs",
out = "some_dir_to_copy_to/AndroidManifest.xml",
)
export_file(
name = "magic2",
src = ":generate_manifest_with_named_outputs[manifest]",
out = "some_dir_to_copy_to/AndroidManifest.xml",
)
Note that magic1
consumes generate_manifest_with_named_outputs
's default
output. magic2
consumes generate_manifest_with_named_outputs
's named
output "manifest," which happen to be pointing to the same output as the default output in this
case, but they do not have to point to the same output.
git_fetch
def git_fetch(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
_git_fetch_tool: str = _,
buck2_compatibility: str = _,
contacts: list[str] = _,
default_host_platform: None | str = _,
labels: list[str] = _,
licenses: list[str] = _,
repo: str,
rev: str
) -> None
Checkout a commit from a git repository.
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this onerepo
: Url suitable as a git remote.rev
: 40-digit hex SHA-1 of the git commit.
Details
Examples:
git_fetch(
name = "serde.git",
repo = "https://github.com/serde-rs/serde",
rev = "fccb9499bccbaca0b7eef91a3a82dfcb31e0b149",
)
go_binary
def go_binary(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
_asan: bool = _,
_cxx_toolchain: str = _,
_exec_os_type: str = _,
_go_stdlib: str = _,
_go_toolchain: str = _,
_race: bool = _,
_tags: list[str] = _,
asan: bool = _,
assembler_flags: list[str] = _,
buck2_compatibility: str = _,
cgo_enabled: None | bool = _,
compiler_flags: list[str] = _,
contacts: list[str] = _,
default_host_platform: None | str = _,
deps: list[str] = _,
embedcfg: None | str = _,
external_linker_flags: list[str] = _,
labels: list[str] = _,
licenses: list[str] = _,
link_mode: None | str = _,
link_style: None | str = _,
linker_flags: list[str] = _,
package_root: None | str = _,
platform: None | str = _,
race: bool = _,
resources: list[str] = _,
srcs: list[str] = _,
tags: list[str] = _
) -> None
A go_binary() rule builds a native executable from the supplied set of Go source files and dependencies. The files supplied are expected to be in the main package, implicitly.
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this oneasan
: If true, enable ASAN.assembler_flags
: The set of additional assembler flags to pass togo tool asm
.cgo_enabled
: Experimental: Analog of CGO_ENABLED environment-variable. None will be converted to True if cxx_toolchain available for current configuration, otherwise False.compiler_flags
: The set of additional compiler flags to pass togo tool compile
.deps
: The set of dependencies of this rule. Currently, this only supports go_library rules.external_linker_flags
: Extra external linker flags passed to go link via-extld
argument. If argument is non-empty orcgo_library
is used, the link mode will switch toexternal
.link_mode
: Determines the link mode (equivalent of-mode
). Can be one of the following values:internal
,external
. If no value is provided, the mode is set automatically depending on the other args.link_style
: Determines whether to build and link this rule's dependencies statically or dynamically. Can be one of the following values:static
,static_pic
orshared
. This argument is relevant only if the cgo extension is enabled. Otherwise, Buck ignores this argument.linker_flags
: Extra linker flags passed to go linkpackage_root
: Sets Go package direactory (relative to BUCK file). By default (or if None passes) package_root is being detected automatically. Empty string of Go package is on the same level as BUCK file otherwise the subdirectory name. Example for srcs = ["foo/bar.go"], package_root = "foo"race
: If true, enable data race detection.srcs
: The set of source files to be compiled by this rule. .go files will be compiled with the Go compiler, .s files will be compiled with the assembler, and everything else is assumed to be files that may be#include
d by the assembler.tags
: Build tags to apply to this target and its dependencies.
Details
Examples:
For more examples, check out our integration tests.
go_binary(
name='greet',
srcs=[
'main.go',
],
deps=[
':greeting',
],
)
go_library(
name='greeting',
srcs=[
'greeting.go',
],
deps=[
':join',
],
)
go_library(
name='join',
srcs=[
'join.go',
],
)
go_bootstrap_binary
def go_bootstrap_binary(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
_exec_os_type: str = _,
_go_bootstrap_toolchain: str = _,
buck2_compatibility: str = _,
entrypoints: list[str] = _,
srcs: list[str] = _
) -> None
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this oneentrypoints
: Package name or file namessrcs
: The set of source files to be compiled by this rule. .go files will be compiled with the Go compiler, .s files will be compiled with the assembler, and everything else is assumed to be files that may be#include
d by the assembler.
go_exported_library
def go_exported_library(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
_asan: bool = _,
_cxx_toolchain: str = _,
_exec_os_type: str = _,
_go_stdlib: str = _,
_go_toolchain: str = _,
_race: bool = _,
_tags: list[str] = _,
asan: bool = _,
assembler_flags: list[str] = _,
buck2_compatibility: str = _,
build_mode: str,
cgo_enabled: None | bool = _,
compiler_flags: list[str] = _,
contacts: list[str] = _,
cxx_compiler_flags: list[str] = _,
cxx_preprocessor_flags: list[str] = _,
default_host_platform: None | str = _,
deps: list[str] = _,
embedcfg: None | str = _,
external_linker_flags: list[str] = _,
generate_exported_header: bool = _,
header_namespace: None | str = _,
headers: list[str] | dict[str, str] = _,
labels: list[str] = _,
licenses: list[str] = _,
link_mode: None | str = _,
link_style: None | str = _,
linker_flags: list[str] = _,
package_root: None | str = _,
platform: None | str = _,
race: bool = _,
resources: list[str] = _,
srcs: list[str] = _,
tags: list[str] = _
) -> None
A go_exported_library() rule builds a C library from the supplied set of Go source files and dependencies. This is done via -buildmode
flag and "//export" annotations in the code.
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this oneasan
: If true, enable ASAN.assembler_flags
: The set of additional assembler flags to pass togo tool asm
.build_mode
: Determines the build mode (equivalent of-buildmode
). Can be one of the following values:c_archive
,c_shared
. This argument is valid only if at there is at least onecgo_library declared in deps. In addition you should make sure that
-sharedflag is added to
compiler_flagsand go version under
go.gorootis compiled with that flag present in:
gcflags,
ldflagsand
asmflags``cgo_enabled
: Experimental: Analog of CGO_ENABLED environment-variable. None will be converted to True if cxx_toolchain available for current configuration, otherwise False.compiler_flags
: The set of additional compiler flags to pass togo tool compile
.cxx_compiler_flags
: GCC/Clang flags to use when compiling any of the above C/C++ sources (which require compilation).cxx_preprocessor_flags
: GCC/Clang flags to use when preprocessing any of the above C/C++ sources (which require preprocessing).deps
: The set of dependencies of this rule. Currently, this only supports go_library rules.external_linker_flags
: Extra external linker flags passed to go link via-extld
argument. If argument is non-empty orcgo_library
is used, the link mode will switch toexternal
.generate_exported_header
: Generate header file with declaration for functions exported with//export
The header name for targetcell//foo/bar:lib
will befoo/bar/lib.h
header_namespace
: A path prefix when including headers of this target. Defaults to the path from the root of the repository to the directory where this target is defined. Can contain forward slashes (/
), but cannot start with one. Seeheaders
for more information.headers
: The set of header files that are made available for inclusion to the source files in this target. These should be specified as either a list of header files or a dictionary of header names to header files. The header name can contain forward slashes (/
). The headers can be included with#include "$HEADER_NAMESPACE/$HEADER_NAME"
or#include <$HEADER_NAMESPACE/$HEADER_NAME>
, where$HEADER_NAMESPACE
is the value of the target'sheader_namespace
attribute, and$HEADER_NAME
is the header name if specified, and the filename of the header file otherwise. Seeheader_namespace
for more information.link_mode
: Determines the link mode (equivalent of-mode
). Can be one of the following values:internal
,external
. If no value is provided, the mode is set automatically depending on the other args.link_style
: Determines whether to build and link this rule's dependencies statically or dynamically. Can be one of the following values:static
,static_pic
orshared
. This argument is relevant only if the cgo extension is enabled. Otherwise, Buck ignores this argument.linker_flags
: Extra linker flags passed to go linkpackage_root
: Sets Go package direactory (relative to BUCK file). By default (or if None passes) package_root is being detected automatically. Empty string of Go package is on the same level as BUCK file otherwise the subdirectory name. Example for srcs = ["foo/bar.go"], package_root = "foo"race
: If true, enable data race detection.resources
: Static files to be symlinked into the working directory of the test. You can access these in your by opening the files as relative paths, e.g.ioutil.ReadFile("testdata/input")
.srcs
: The set of source files to be compiled by this rule. .go files will be compiled with the Go compiler, .s files will be compiled with the assembler, and everything else is assumed to be files that may be#include
d by the assembler.tags
: Build tags to apply to this target and its dependencies.
Details
Examples:
For more examples, check out our integration tests.
go_exported_library(
name = "shared",
srcs = ["main.go"],
build_mode = "c_shared",
compiler_flags = ["-shared"],
deps = [":example"],
)
cgo_library(
name = "example",
package_name = "cgo",
srcs = [
"export-to-c.go", # file with //export annotations
],
compiler_flags = [],
headers = [],
)
cxx_genrule(
name = "cgo_exported_headers",
out = "includes",
cmd = (
"mkdir -p $OUT && " +
"cat `dirname $(location :shared)`/includes/*.h > $OUT/_cgo_export.h"
),
)
prebuilt_cxx_library(
name = "cxx_so_with_header",
header_dirs = [":cgo_exported_headers"],
shared_lib = ":shared",
)
go_library
def go_library(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
_asan: bool = _,
_cgo_enabled: None | bool = _,
_coverage_mode: None | str = _,
_cxx_toolchain: str = _,
_go_stdlib: str = _,
_go_toolchain: str = _,
_race: bool = _,
_tags: list[str] = _,
assembler_flags: list[str] = _,
buck2_compatibility: str = _,
compiler_flags: list[str] = _,
contacts: list[str] = _,
default_host_platform: None | str = _,
deps: list[str] = _,
embedcfg: None | str = _,
exported_deps: list[str] = _,
labels: list[str] = _,
licenses: list[str] = _,
package_name: None | str = _,
package_root: None | str = _,
srcs: list[str] = _
) -> None
A go_library() rule builds a native library from the supplied set of Go source files and dependencies.
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this oneassembler_flags
: The set of additional assembler flags to pass togo tool asm
.compiler_flags
: The set of additional compiler flags to pass togo tool compile
.deps
: The set of dependencies of this rule. Currently, this only supports go_library rules.package_name
: Sets the full name of the package being compiled. This defaults to the path from the buck root. (e.g. given a ./.buckconfig, a rule in ./a/b/BUCK defaults to package "a/b")package_root
: Sets Go package direactory (relative to BUCK file). By default (or if None passes) package_root is being detected automatically. Empty string of Go package is on the same level as BUCK file otherwise the subdirectory name. Example for srcs = ["foo/bar.go"], package_root = "foo"srcs
: The set of source files to be compiled by this rule. .go files will be compiled with the Go compiler, .s files will be compiled with the assembler, and everything else is assumed to be files that may be#include
d by the assembler.
Details
Examples:
For more examples, check out our integration tests.
go_library(
name='greeting',
srcs=[
'greeting.go',
],
deps=[
':join',
],
)
go_stdlib
def go_stdlib(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
_asan: bool = _,
_cgo_enabled: None | bool = _,
_cxx_toolchain: str = _,
_exec_os_type: str = _,
_go_toolchain: str = _,
_race: bool = _,
_tags: list[str] = _,
buck2_compatibility: str = _
) -> None
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this one
go_test
def go_test(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
_asan: bool = _,
_coverage_mode: None | str = _,
_cxx_toolchain: str = _,
_exec_os_type: str = _,
_go_stdlib: str = _,
_go_toolchain: str = _,
_inject_test_env: str = _,
_race: bool = _,
_remote_test_execution_toolchain: str = _,
_tags: list[str] = _,
_testmaingen: str = _,
asan: bool = _,
assembler_flags: list[str] = _,
buck2_compatibility: str = _,
cgo_enabled: None | bool = _,
compiler_flags: list[str] = _,
contacts: list[str] = _,
coverage_mode: None | str = _,
default_host_platform: None | str = _,
deps: list[str] = _,
embedcfg: None | str = _,
env: dict[str, str] = _,
external_linker_flags: list[str] = _,
labels: list[str] = _,
library: None | str = _,
licenses: list[str] = _,
link_mode: None | str = _,
link_style: None | str = _,
linker_flags: list[str] = _,
package_name: None | str = _,
package_root: None | str = _,
platform: None | str = _,
race: bool = _,
remote_execution: None | str | dict[str, None | bool | int | str | list[dict[str, str]] | dict[str, str]] = _,
remote_execution_action_key_providers: None | str = _,
resources: list[str] = _,
run_test_separately: bool = _,
runner: None | str = _,
specs: None | str = _,
srcs: list[str] = _,
tags: list[str] = _,
test_rule_timeout_ms: None | int = _
) -> None
A go_test()
rule builds a native binary from the specified Go source and resource files—and a generated main file. It's similar to the go test
command.
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this oneasan
: If true, enable ASAN.assembler_flags
: The set of additional assembler flags to pass togo tool asm
.cgo_enabled
: Experimental: Analog of CGO_ENABLED environment-variable. None will be converted to True if cxx_toolchain available for current configuration, otherwise False.compiler_flags
: The set of additional compiler flags to pass togo tool compile
.deps
: The set of dependencies of this rule. Currently, this only supports go_library rules.env
: A map of environment variables and values to set when running the test.external_linker_flags
: Extra external linker flags passed to go link via-extld
argument. If argument is non-empty orcgo_library
is used, the link mode will switch toexternal
.labels
: A list of labels to be applied to these tests. These labels are arbitrary text strings and have no meaning within buck itself. They can, however, have meaning for you as a test author (e.g.,smoke
orfast
). A label can be used to filter or include a specific test rule when executingbuck test
library
: Specify the library that this internal test is testing. This will copy thesrcs
,package_name
anddeps
from the target specified so you don't have to duplicate them.link_mode
: Determines the link mode (equivalent of-mode
). Can be one of the following values:internal
,external
. If no value is provided, the mode is set automatically depending on the other args.link_style
: Determines whether to build and link this rule's dependencies statically or dynamically. Can be one of the following values:static
,static_pic
orshared
. This argument is relevant only if the cgo extension is enabled. Otherwise, Buck ignores this argument.linker_flags
: Extra linker flags passed to go linkpackage_name
: Sets the full name of the test package being compiled. This defaults to the path from the buck root with "_test" appended. (e.g. given a ./.buckconfig, a rule in ./a/b/BUCK defaults to package "a/b_test")Note: if you want to test packages internally (i.e. same package name), use the
library
parameter instead of settingpackage_name
to include the tested source files.package_root
: Sets Go package direactory (relative to BUCK file). By default (or if None passes) package_root is being detected automatically. Empty string of Go package is on the same level as BUCK file otherwise the subdirectory name. Example for srcs = ["foo/bar.go"], package_root = "foo"race
: If true, enable data race detection.srcs
: The set of source files to be compiled by this rule. .go files will be compiled with the Go compiler, .s files will be compiled with the assembler, and everything else is assumed to be files that may be#include
d by the assembler.tags
: Build tags to apply to this target and its dependencies.test_rule_timeout_ms
: If set specifies the maximum amount of time (in milliseconds) in which all of the tests in this rule should complete. This overrides the defaultrule_timeout
if any has been specified in.buckconfig
.
Details
If your test requires static files you should specify these in the resources argument. If you do not specify these files, they won't be available when your test runs.
Examples:
For more examples, check out our integration tests.
go_library(
name='greeting',
srcs=[
'greeting.go',
],
deps=[
':join',
],
)
go_test(
name='greeting-test',
srcs=[
'greeting_ext_test.go',
],
deps=[
':greeting'
],
)
go_test(
name='greeting-internal-test',
package_name='greeting',
srcs=[
'greeting.go',
'greeting_test.go',
],
deps=[
':join',
],
)
# Or
go_test(
name='greeting-better-internal-test',
srcs=['greeting_test.go'],
library=':greeting',
)
groovy_library
def groovy_library(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
_wip_java_plugin_arguments: dict[str, list[str]] = _,
annotation_processor_deps: list[str] = _,
annotation_processor_params: list[str] = _,
annotation_processors: list[str] = _,
buck2_compatibility: str = _,
contacts: list[str] = _,
default_host_platform: None | str = _,
deps: list[str] = _,
exported_deps: list[str] = _,
exported_provided_deps: list[str] = _,
extra_arguments: list[str] = _,
extra_groovyc_arguments: list[str] = _,
java_version: None | str = _,
javac: None | str = _,
labels: list[str] = _,
licenses: list[str] = _,
manifest_file: None | str = _,
maven_coords: None | str = _,
never_mark_as_unused_dependency: None | bool = _,
on_unused_dependencies: None | str = _,
plugins: list[str] = _,
proguard_config: None | str = _,
provided_deps: list[str] = _,
remove_classes: list[str] = _,
required_for_source_only_abi: bool = _,
resources: list[str] = _,
resources_root: None | str = _,
runtime_deps: list[str] = _,
source: None | str = _,
source_abi_verification_mode: None | str = _,
source_only_abi_deps: list[str] = _,
srcs: list[str] = _,
target: None | str = _
) -> None
A groovy_library()
rule is used to define a set of Groovy files that can be compiled together. It can also be used to cross compile a set of Groovy and Java files. The main output of a groovy_library()
rule is a single JAR file containing all of the compiled class files and resources.
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this onedeps
: Rules (usually othergroovy_library
orjava_library()
rules) that are used to generate the classpath required to compile thisgroovy_library
.This is the same as in
java_library()
.exported_deps
: Othergroovy_library
andjava_library()
rules that depend on this rule will also include itsexported_deps
in their classpaths.This is the same as in
java_library()
.extra_arguments
: Only used during cross compilation.This is the same as in
java_library()
.extra_groovyc_arguments
: List of additional arguments to pass into the Groovy compiler.java_version
: Only used during cross compilation.This is the same as in
java_library()
.provided_deps
: This is the same as injava_library()
.resources
: This is the same as injava_library()
.source
: Only used during cross compilation.This is the same as in
java_library()
.srcs
: The set of files to compile for this rule. Usually these will all end in.groovy
, but if any of the files end in.java
, cross compilation using the jdk found inJAVA_HOME
will occur.target
: Only used during cross compilation.This is the same as in
java_library()
.
Details
Examples:
# A rule that compiles a single .groovy file.
groovy_library(
name = 'example',
srcs = ['MySourceFile.groovy'],
)
# A rule that compiles all of the .groovy files under the directory in
# which the rule is defined using glob()
groovy_library(
name = 'groovy-only',
srcs = glob(['**/*.groovy']),
)
# A rule that cross compiles all of the .groovy and .java files under
# the directory in which the rule is defined, failing if compiling the
# java files generates any compiler warnings
groovy_library(
name = 'cross-compilation',
srcs = glob(['**/*.groovy', '**/*.java']),
java_version = 8,
extra_arguments = [
'-Werror',
],
)
groovy_test
def groovy_test(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
_wip_java_plugin_arguments: dict[str, list[str]] = _,
annotation_processor_deps: list[str] = _,
annotation_processor_params: list[str] = _,
annotation_processors: list[str] = _,
buck2_compatibility: str = _,
contacts: list[str] = _,
cxx_library_whitelist: list[str] = _,
default_cxx_platform: None | str = _,
default_host_platform: None | str = _,
deps: list[str] = _,
deps_query: None | str = _,
env: dict[str, str] = _,
exported_deps: list[str] = _,
exported_provided_deps: list[str] = _,
extra_arguments: list[str] = _,
extra_groovyc_arguments: list[str] = _,
fork_mode: str = _,
java_version: None | str = _,
javac: None | str = _,
labels: list[str] = _,
licenses: list[str] = _,
manifest_file: None | str = _,
maven_coords: None | str = _,
never_mark_as_unused_dependency: None | bool = _,
on_unused_dependencies: None | str = _,
plugins: list[str] = _,
proguard_config: None | str = _,
provided_deps: list[str] = _,
remove_classes: list[str] = _,
required_for_source_only_abi: bool = _,
resources: list[str] = _,
resources_root: None | str = _,
run_test_separately: bool = _,
runtime_deps: list[str] = _,
source: None | str = _,
source_abi_verification_mode: None | str = _,
source_only_abi_deps: list[str] = _,
srcs: list[str] = _,
std_err_log_level: None | int | str = _,
std_out_log_level: None | int | str = _,
target: None | str = _,
test_case_timeout_ms: None | int = _,
test_rule_timeout_ms: None | int = _,
test_type: None | str = _,
use_cxx_libraries: None | bool = _,
use_dependency_order_classpath: None | bool = _,
vm_args: list[str] = _
) -> None
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this one
gwt_binary
def gwt_binary(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
_exec_os_type: str = _,
_java_toolchain: str = _,
buck2_compatibility: str = _,
contacts: list[str] = _,
default_host_platform: None | str = _,
deps: list[str] = _,
draft_compile: bool = _,
experimental_args: list[str] = _,
labels: list[str] = _,
licenses: list[str] = _,
local_workers: int = _,
module_deps: list[str] = _,
modules: list[str] = _,
optimize: int = _,
strict: bool = _,
style: str = _,
vm_args: list[str] = _
) -> None
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this one
halide_library
def halide_library(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
buck2_compatibility: str = _,
compiler_deps: list[str] = _,
compiler_flags: list[str] = _,
compiler_invocation_flags: list[str] = _,
configs: dict[str, dict[str, str]] = _,
contacts: list[str] = _,
cxx_runtime_type: None | str = _,
default_host_platform: None | str = _,
default_platform: None | str = _,
defaults: dict[str, str] = _,
deps: list[str] = _,
deps_query: None | str = _,
devirt_enabled: bool = _,
executable_name: None | str = _,
fat_lto: bool = _,
focused_list_target: None | str = _,
frameworks: list[str] = _,
function_name: None | str = _,
header_namespace: None | str = _,
headers: list[str] | dict[str, str] = _,
headers_as_raw_headers_mode: None | str = _,
include_directories: list[str] = _,
labels: list[str] = _,
lang_compiler_flags: dict[str, list[str]] = _,
lang_platform_compiler_flags: dict[str, list[(str, list[str])]] = _,
lang_platform_preprocessor_flags: dict[str, list[(str, list[str])]] = _,
lang_preprocessor_flags: dict[str, list[str]] = _,
libraries: list[str] = _,
licenses: list[str] = _,
link_deps_query_whole: bool = _,
link_group: None | str = _,
link_group_map: None | str | list[(str, list[(None | str | list[None | str], str, None | str | list[str], None | str)], None | dict[str, typing.Any])] = _,
link_style: None | str = _,
linker_extra_outputs: list[str] = _,
linker_flags: list[str] = _,
platform_compiler_flags: list[(str, list[str])] = _,
platform_deps: list[(str, list[str])] = _,
platform_headers: list[(str, list[str] | dict[str, str])] = _,
platform_linker_flags: list[(str, list[str])] = _,
platform_preprocessor_flags: list[(str, list[str])] = _,
platform_srcs: list[(str, list[str | (str, list[str])])] = _,
post_linker_flags: list[str] = _,
post_platform_linker_flags: list[(str, list[str])] = _,
precompiled_header: None | str = _,
prefer_stripped_objects: bool = _,
prefix_header: None | str = _,
preprocessor_flags: list[str] = _,
raw_headers: list[str] = _,
srcs: list[str | (str, list[str])] = _,
supported_platforms_regex: None | str = _,
thin_lto: bool = _,
version_universe: None | str = _,
weak_framework_names: list[str] = _
) -> None
A halide_library() rule represents a set of Halide sources, along with the "compiler" code needed to compile them into object format (see the Halide site for information about Halide and about static compilation of Halide pipelines). The object code will be generated for the target architecture.
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this onecompiler_deps
: The dependencies of the halide compiler itself. Targets that depend on the halide_library rule will not include or link the outputs of these targets.compiler_flags
: Flags to use when compiling any of the above sources (which require compilation).deps
: The dependencies of the generated halide pipeline code. This is useful if, for example, your pipeline calls an external function using Halide::Func::define_extern.linker_flags
: Flags to add to the linker command line whenever the output from this rule is used in a link operation, such as linked into an executable or a shared library.platform_compiler_flags
: Platform specific compiler flags. These should be specified as a list of pairs where the first element is an un-anchored regex (in java.util.regex.Pattern syntax) against which the platform name is matched, and the second element is a list of flags to use when compiling the target's sources. Seecompiler_flags
for more information.platform_linker_flags
: Platform-specific linker flags. This argument is specified as a list of pairs where the first element in each pair is an un-anchored regex against which the platform name is matched. The regex should usejava.util.regex.Pattern
syntax. The second element in each pair is a list of linker flags. If the regex matches the platform, these flags are added to the linker command line when the output from this rule is used in a link operation.srcs
: The set of halide sources to compile for this rule. The sources will be compiled and linked for the host architecture, and the resulting binary will be run to produce the object code for the Halide pipeline.supported_platforms_regex
: If present, an un-anchored regex (in java.util.regex.Pattern syntax) that matches all platforms that this library supports. It will not be built for other platforms.
Details
Examples:
halide_library(
# Your library name.
name = 'brighter',
# Your pipeline + compiler sources.
srcs = ['halide/main.cpp'],
# Any dependencies for your compiler. Note that targets that depend on
# this rule WILL NOT include or link the output(s) of these targets.
compiler_deps = [
# You'll need libHalide to use this rule; in our example, we assume it's
# located in the 'third-party/halide' directory.
'//third-party/halide:halide'
],
# Any dependencies for your generated shader. Targets that depend on this
# rule will include and/or link the output(s) of these targets.
deps = [
# ...
],
)
haskell_binary
def haskell_binary(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
_cxx_toolchain: str = _,
_haskell_toolchain: str = _,
auto_link_groups: bool = _,
buck2_compatibility: str = _,
compiler_flags: list[str] = _,
contacts: list[str] = _,
default_host_platform: None | str = _,
deps: list[str] = _,
deps_query: None | str = _,
enable_profiling: bool = _,
ghci_platform_preload_deps: list[(str, list[str])] = _,
ghci_preload_deps: list[str] = _,
labels: list[str] = _,
licenses: list[str] = _,
link_deps_query_whole: bool = _,
link_group_deps: list[str] = _,
link_group_map: None | str | list[(str, list[(None | str | list[None | str], str, None | str | list[str], None | str)], None | dict[str, typing.Any])] = _,
link_group_public_deps_label: None | str = _,
link_style: None | str = _,
linker_flags: list[str] = _,
main: None | str = _,
platform: None | str = _,
platform_deps: list[(str, list[str])] = _,
platform_linker_flags: list[(str, list[str])] = _,
srcs: list[str] | dict[str, str] = _,
template_deps: list[str] = _
) -> None
A haskell_binary()
rule represents a groups of Haskell sources and deps which build an executable.
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this onecompiler_flags
: Flags to pass to the Haskell compiler when compiling this rule's sources.deps
: Eitherhaskell_library()
orprebuilt_haskell_library()
rules from which this rules sources import modules or native linkable rules exporting symbols this rules sources call into.link_group_deps
: Additional targets to traverse when building link groups, but which should not be direct dependencies of the main executable.link_group_public_deps_label
: Surface nodes with this label as "public" nodes in the main executable when linking with with link groups.link_style
: Determines whether to build and link this rule's dependencies statically or dynamically. Can be eitherstatic
,static_pic
orshared
.main
: The main module serving as the entry point into the binary. If not specified, the compiler default is used.platform_deps
: Platform specific dependencies. These should be specified as a list of pairs where the first element is an un-anchored regex (in java.util.regex.Pattern syntax) against which the platform name is matched, and the second element is a list of dependencies (same format asdeps
) that are exported if the platform matches the regex. Seedeps
for more information.srcs
: A list of Haskell sources to be built by this rule. The dictionary option is deprecated.
Details
Examples:
haskell_binary(
name = 'foo',
srcs = [
'Foo.hs',
],
)
haskell_ghci
def haskell_ghci(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
_cxx_toolchain: str = _,
_haskell_toolchain: str = _,
buck2_compatibility: str = _,
compiler_flags: list[str] = _,
contacts: list[str] = _,
default_host_platform: None | str = _,
deps: list[str] = _,
deps_query: None | str = _,
enable_profiling: bool = _,
extra_script_templates: list[str] = _,
ghci_bin_dep: None | str = _,
ghci_init: None | str = _,
labels: list[str] = _,
licenses: list[str] = _,
linker_flags: list[str] = _,
platform: None | str = _,
platform_deps: list[(str, list[str])] = _,
platform_preload_deps: list[(str, list[str])] = _,
preload_deps: list[str] = _,
srcs: list[str] | dict[str, str] = _,
template_deps: list[str] = _
) -> None
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this one
haskell_haddock
def haskell_haddock(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
_cxx_toolchain: str = _,
_haskell_toolchain: str = _,
buck2_compatibility: str = _,
contacts: list[str] = _,
default_host_platform: None | str = _,
deps: list[str] = _,
deps_query: None | str = _,
haddock_flags: list[str] = _,
labels: list[str] = _,
licenses: list[str] = _,
platform: None | str = _,
platform_deps: list[(str, list[str])] = _
) -> None
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this one
haskell_ide
def haskell_ide(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
_haskell_toolchain: str = _,
buck2_compatibility: str = _,
compiler_flags: list[str] = _,
contacts: list[str] = _,
default_host_platform: None | str = _,
deps: list[str] = _,
deps_query: None | str = _,
extra_script_templates: list[str] = _,
include_projects: list[str] = _,
labels: list[str] = _,
licenses: list[str] = _,
link_style: str,
linker_flags: list[str] = _,
platform: None | str = _,
platform_deps: list[(str, list[str])] = _,
srcs: list[str] | dict[str, str] = _
) -> None
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this one
haskell_library
def haskell_library(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
_cxx_toolchain: str = _,
_haskell_toolchain: str = _,
buck2_compatibility: str = _,
compiler_flags: list[str] = _,
contacts: list[str] = _,
default_host_platform: None | str = _,
deps: list[str] = _,
enable_profiling: bool = _,
ghci_platform_preload_deps: list[(str, list[str])] = _,
ghci_preload_deps: list[str] = _,
haddock_flags: list[str] = _,
labels: list[str] = _,
licenses: list[str] = _,
link_whole: bool = _,
linker_flags: list[str] = _,
platform: None | str = _,
platform_deps: list[(str, list[str])] = _,
platform_linker_flags: list[(str, list[str])] = _,
preferred_linkage: str = _,
srcs: list[str] | dict[str, str] = _,
template_deps: list[str] = _
) -> None
A haskell_library()
rule is used to identity a group of Haskell sources.
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this onecompiler_flags
: Flags to pass to the Haskell compiler when compiling this rule's sources.deps
: Eitherhaskell_library()
orprebuilt_haskell_library()
rules from which this rules sources import modules or native linkable rules exporting symbols this rules sources call into.platform_deps
: Platform specific dependencies. These should be specified as a list of pairs where the first element is an un-anchored regex (in java.util.regex.Pattern syntax) against which the platform name is matched, and the second element is a list of dependencies (same format asdeps
) that are exported if the platform matches the regex. Seedeps
for more information.srcs
: A list of Haskell sources to be built by this rule. The dictionary option is deprecated.
Details
Examples:
haskell_library(
name = 'fileutil',
srcs = [
'FileUtil.hs',
],
)
haskell_prebuilt_library
def haskell_prebuilt_library(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
buck2_compatibility: str = _,
contacts: list[str] = _,
cxx_header_dirs: list[str] = _,
db: str,
default_host_platform: None | str = _,
deps: list[str] = _,
enable_profiling: bool = _,
exported_compiler_flags: list[str] = _,
exported_linker_flags: list[str] = _,
exported_post_linker_flags: list[str] = _,
id: str = _,
import_dirs: list[str] = _,
labels: list[str] = _,
licenses: list[str] = _,
pic_profiled_static_libs: list[str] = _,
pic_static_libs: list[str] = _,
profiled_static_libs: list[str] = _,
shared_libs: dict[str, str] = _,
static_libs: list[str] = _,
version: str = _
) -> None
A prebuilt_haskell_library()
rule is used to identify Haskell prebuilt libraries and their associated interface files.
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this onedeps
: Otherprebuilt_haskell_library()
rules from which this library imports modules.exported_compiler_flags
: Compiler flags used by dependent rules when compiling with this library.exported_linker_flags
: Linker flags used by dependent rules when linking with this library.shared_libs
: A map of shared library names to shared library paths to use when building a dynamically linked top-level target.static_libs
: The libraries to use when building a statically linked top-level target.
Details
Examples:
prebuilt_haskell_library(
name = 'file',
static_interfaces = [
'interfaces',
],
shared_interfaces = [
'interfaces_dyn',
],
static_libs = [
'libFileUtil.a',
],
shared_libs = {
'libFileUtil.so': 'libFileUtil.so',
},
)
http_archive
def http_archive(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
buck2_compatibility: str = _,
contacts: list[str] = _,
default_host_platform: None | str = _,
excludes: list[str] = _,
exec_deps: str = _,
labels: list[str] = _,
licenses: list[str] = _,
out: None | str = _,
sha1: None | str = _,
sha256: None | str = _,
strip_prefix: None | str = _,
sub_targets: list[str] = _,
type: None | str = _,
urls: list[str] = _,
vpnless_urls: list[str] = _
) -> None
An http_archive()
rule is used to download and extract archives from the Internet to be used as dependencies for other rules. These rules are downloaded by running fetch
, or can be downloaded as part of build
by setting .buckconfig
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this oneexcludes
: An optional list of regex patterns. All file paths in the extracted archive which match any of the given patterns will be omitted.exec_deps
: When using http_archive as an anon target, the rule invoking the anon target needs to mirror this attribute into its own attributes, and forward the provider into the anon target invocation.When using http_archive normally not as an anon target, the default value is always fine.
out
: An optional name to call the directory that the downloaded artifact is extracted into. Buck will generate a default name if one is not provided that uses thename
of the rule.sha256
: TheSHA-256
hash of the downloaded artifact. Buck verifies this is correct and fails the fetch command if it doesn't match in order to guarantee repeatable builds.strip_prefix
: If set, files under this path will be extracted to the root of the output directory. Siblings or cousins to this prefix will not be extracted at all.For example, if a tarball has the layout:
foo/bar/bar-0.1.2/data.dat
foo/baz/baz-0.2.3
foo_prime/bar-0.1.2
Only
data.dat
will be extracted, and it will be extracted into the output directory specified inout
.
sub_targets
: A list of filepaths within the archive to be made accessible as sub-targets. For example if we have an http_archive withname = "archive"
andsub_targets = ["src/lib.rs"]
, then other targets would be able to refer to that file as":archive[src/lib.rs]"
.type
: Normally, archive type is determined by the file's extension. Iftype
is set, then autodetection is overridden, and the specified type is used instead.Supported values are:
zip
,tar
,tar.gz
,tar.bz2
,tar.xz
, andtar.zst
.urls
: A list of urls to attempt to download from. They are tried in order, and subsequent ones are only tried if the download fails. If validation fails, a new URL is not used. Supported protocols are "http", "https", and "mvn".vpnless_urls
: Additional URLs from which this resource can be downloaded when off VPN. Meta-internal only.
Details
Examples:
Using http_archive()
, third party packages can be downloaded from
an https
URL and used in other library types.
http_archive(
name = 'thrift-archive',
urls = [
'https://internal-mirror.example.com/bin/thrift-compiler-0.1.tar.gz.badextension',
],
sha256 = '7baa80df284117e5b945b19b98d367a85ea7b7801bd358ff657946c3bd1b6596',
type='tar.gz',
strip_prefix='thrift-compiler-0.1'
)
genrule(
name = 'thrift-compiler-bin',
out = 'thrift',
cmd = 'cp $(location :thrift-archive)/bin/thrift $OUT',
executable = True,
)
genrule(
name="my-thrift-lib-cpp2",
cmd="$(exe :thrift-compiler-bin) --gen cpp2 -o $OUT $(location //:thrift-file)",
out="gen-cpp2",
)
http_file
def http_file(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
buck2_compatibility: str = _,
contacts: list[str] = _,
default_host_platform: None | str = _,
executable: None | bool = _,
labels: list[str] = _,
licenses: list[str] = _,
out: None | str = _,
sha1: None | str = _,
sha256: None | str = _,
urls: list[str] = _,
vpnless_urls: list[str] = _
) -> None
An http_file()
rule is used to download files from the Internet to be used as dependencies for other rules. This rule only downloads single files, and can optionally make them executable (see http_file()executable
) These rules are downloaded by running fetch
, or can be downloaded as part of build
by setting .buckconfig
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this oneexecutable
: Whether or not the file should be made executable after downloading. If true, this can also be used viarun
and the$(exe )
string parameter macros
out
: An optional name to call the downloaded artifact. Buck will generate a default name if one is not provided that uses thename
of the rule.sha256
: TheSHA-256
hash of the downloaded artifact. Buck verifies this is correct and fails the fetch command if it doesn't match in order to guarantee repeatable builds.urls
: A list of urls to attempt to download from. They are tried in order, and subsequent ones are only tried if the download fails. If validation fails, a new URL is not used. Supported protocols are "http", "https", and "mvn".vpnless_urls
: Additional URLs from which this resource can be downloaded when off VPN. Meta-internal only.
Details
Examples:
Using http_file()
, third party packages can be downloaded from
an https
URL and used in java libraries.
http_file(
name = 'guava-23-bin',
urls = [
'http://search.maven.org/remotecontent?filepath=com/google/guava/guava/23.0/guava-23.0.jar',
],
sha256 = '7baa80df284117e5b945b19b98d367a85ea7b7801bd358ff657946c3bd1b6596',
)
http_file(
name = 'guava-23-sources',
urls = [
'http://search.maven.org/remotecontent?filepath=com/google/guava/guava/23.0/guava-23.0-sources.jar',
],
sha256 = '37fe8ba804fb3898c3c8f0cbac319cc9daa58400e5f0226a380ac94fb2c3ca14',
)
prebuilt_java_library(
name = 'guava-23',
binary_jar = ':guava-23-bin',
source_jar = ':guava-23-source',
)
Tooling can also be fetched with http_file()
and used by a genrule()
.
genrule(
name="my-thrift-lib-cpp2",
cmd="$(exe :thrift-compiler-bin) --gen cpp2 -o $OUT $(location //:thrift-file)",
out="gen-cpp2",
)
http_file(
name = 'thrift-compiler-bin',
url = 'https://internal-mirror.example.com/bin/thrift-compiler',
sha256 = 'c24932ccabb66fffb2d7122298f7f1f91e0b1f14e05168e3036333f84bdf58dc',
executable = True,
)
Here's an example of a http_file()
using a mvn URI which uses a Maven classifier.
http_file(
name = 'guava-23-bin',
urls = [
'mvn:com.google.guava:guava:jar:23.0',
],
sha256 = '7baa80df284117e5b945b19b98d367a85ea7b7801bd358ff657946c3bd1b6596',
)
jar_genrule
def jar_genrule(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
_build_only_native_code: bool = _,
_genrule_toolchain: str = _,
_java_toolchain: str = _,
always_print_stderr: bool = _,
bash: None | str = _,
buck2_compatibility: str = _,
cacheable: None | bool = _,
cmd: None | str = _,
cmd_exe: None | str = _,
contacts: list[str] = _,
default_host_platform: None | str = _,
enable_sandbox: None | bool = _,
environment_expansion_separator: None | str = _,
labels: list[str] = _,
licenses: list[str] = _,
metadata_env_var: None | str = _,
metadata_path: None | str = _,
need_android_tools: bool = _,
no_outputs_cleanup: bool = _,
remote: None | bool = _,
remote_execution_dependencies: list[dict[str, str]] = _,
srcs: list[str] | dict[str, str] = _,
type: None | str = _,
weight: None | int = _
) -> None
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this one
java_annotation_processor
def java_annotation_processor(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
_build_only_native_code: bool = _,
buck2_compatibility: str = _,
contacts: list[str] = _,
default_host_platform: None | str = _,
deps: list[str] = _,
does_not_affect_abi: bool = _,
isolate_class_loader: bool = _,
labels: list[str] = _,
licenses: list[str] = _,
processor_class: str = _,
supports_abi_generation_from_source: bool = _
) -> None
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this one
java_binary
def java_binary(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
_build_only_native_code: bool = _,
_exec_os_type: str = _,
_is_building_android_binary: bool = _,
_java_toolchain: str = _,
blacklist: list[str] = _,
buck2_compatibility: str = _,
contacts: list[str] = _,
default_cxx_platform: None | str = _,
default_host_platform: None | str = _,
deps: list[str] = _,
do_not_create_inner_jar: bool = _,
generate_wrapper: bool = _,
java_args_for_run_info: list[str] = _,
labels: list[str] = _,
licenses: list[str] = _,
main_class: None | str = _,
manifest_file: None | str = _,
meta_inf_directory: None | str = _
) -> None
A java_binary()
rule is used to create a JAR file of the compiled .class files and resources of the java_library()
rules on which it depends.
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this oneblacklist
: A list of patterns that identify files to exclude from the final generated JAR file. Example:
java_binary(
name = 'example',
blacklist = [
# Excludes com.example.A and com.example.Alligator,
# as well as their inner classes and any non-class files that happen to match
# the pattern
'com.example.A',
# Excludes all files from org/slf4j/**/*.
'org.slf4j',
],
deps = [
':example1',
':third-party-stuff',
],
)deps
: Rules (normally of typejava_library
) that should be compiled and whose.class
files and resources should be included in the generated JAR file.main_class
: If provided, this will be the value specified as theMain-Class
attribute of theMETA-INF/MANIFEST.MF
file in the generated JAR file. Also, when this rule is used as an executable in agenrule()
,main_class
will indicate the class whosemain()
method will be invoked to process the command-line arguments. This is consistent with the expected usage ofjava -jar *<name.jar>* *<args>*
.manifest_file
: If provided, this manifest will be used when generating the JAR file. If combined withmain_class
, the specified manifest file will be used but themain_class
will override the main class in the manifest.
java_library
def java_library(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
_build_only_native_code: bool = _,
_dex_min_sdk_version: None | int = _,
_dex_toolchain: str = _,
_exec_os_type: str = _,
_is_building_android_binary: bool = _,
_java_toolchain: str = _,
_wip_java_plugin_arguments: dict[str, list[str]] = _,
abi_generation_mode: None | str = _,
annotation_processor_deps: list[str] = _,
annotation_processor_params: list[str] = _,
annotation_processors: list[str] = _,
buck2_compatibility: str = _,
contacts: list[str] = _,
default_host_platform: None | str = _,
deps: list[str] = _,
exported_deps: list[str] = _,
exported_provided_deps: list[str] = _,
extra_arguments: list[str] = _,
jar_postprocessor: None | str = _,
java_version: None | str = _,
javac: None | str = _,
labels: list[str] = _,
licenses: list[str] = _,
manifest_file: None | str = _,
maven_coords: None | str = _,
never_mark_as_unused_dependency: None | bool = _,
on_unused_dependencies: None | str = _,
plugins: list[str] = _,
proguard_config: None | str = _,
provided_deps: list[str] = _,
remove_classes: list[str] = _,
required_for_source_only_abi: bool = _,
resources: list[str] = _,
resources_root: None | str = _,
runtime_deps: list[str] = _,
source: None | str = _,
source_abi_verification_mode: None | str = _,
source_only_abi_deps: list[str] = _,
srcs: list[str] = _,
target: None | str = _,
validation_deps: list[str] = _
) -> None
A java_library()
rule defines a set of Java files that can be compiled together. The main output of a java_library()
rule is a single JAR file containing all of the compiled class files, as well as the static files specified in the resources
argument.
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this onedeps
: Rules (usually otherjava_library
rules) that are used to generate the classpath required to compile thisjava_library
.exported_deps
: Other rules that depend on this rule will also include itsexported_deps
in their classpaths. This is useful when the public API of a rule has return types or checked exceptions that are defined in another rule, which would otherwise require callers to add an extra dependency. It's also useful for exposing e.g. a collection ofprebuilt_jar
rules as a single target for callers to depend on. Targets inexported_deps
are implicitly included in thedeps
of this rule, so they don't need to be repeated there.exported_provided_deps
: This is a combination ofprovided_deps
andexported_deps
. Rules listed in this parameter will be added to classpath of rules that depend on this rule, but they will not be included in a binary if binary depends on a such target.extra_arguments
: List of additional arguments to pass into the Java compiler. These arguments follow the ones specified in.buckconfig
.java_version
: Equivalent to setting bothsource
andtarget
to the given value. Setting this andsource
ortarget
(or both!) is an error.on_unused_dependencies
: Action performed when Buck detects that some dependencies are not used during Java compilation.Note that this feature is experimental and does not handle runtime dependencies.
The valid values are:
ignore
(default): ignore unused dependencies,warn
: emit a warning to the console,fail
: fail the compilation.
This option overrides the default value from .
provided_deps
: These represent dependencies that are known to be provided at run time, but are required in order for the code to compile. Examples ofprovided_deps
include the JEE servlet APIs. When this rule is included in a , theprovided_deps
will not be packaged into the output.remove_classes
: Specifies a list ofPatterns
that are used to excludeclasses
from theJAR
. The pattern matching is based on the name of the class. This can be used to exclude a member class or delete a local view of a class that will be replaced during a later stage of the build.required_for_source_only_abi
: Indicates that this rule must be present on the classpath duringsource-only ABI generation
of any rule that depends on it. Typically this is done when a rule contains annotations, enums, constants, or interfaces.Having rules present on the classpath during source-only ABI generation prevents Buck from completely flattening the build graph, thus reducing the performance win from source-only ABI generation. These rules should be kept small (ideally just containing annotations, constants, enums, and interfaces) and with minimal dependencies of their own.
resources
: Static files to include with the compiled.class
files. These files can be loaded via Class.getResource().Note: If
resources_root
isn't set, Buck uses the.buckconfig
property in.buckconfig
to determine where resources should be placed within the generated JAR file.source
: Specifies the version of Java (as a string) to interpret source files as. Overrides the value in "source_level" in the "java" section of.buckconfig
.source_only_abi_deps
: These are dependencies that must be present duringsource-only ABI generation
. Typically such dependencies are added when some property of the code in this rule prevents source-only ABI generation from being correct without these dependencies being present.Having
source_only_abi_deps
prevents Buck from completely flattening the build graph, thus reducing the performance win from source-only ABI generation. They should be avoided when possible. Often only a small code change is needed to avoid them. For more information on such code changes, read aboutsource-only ABI generation
.srcs
: The set of.java
files to compile for this rule. If any of the files in this list end in.src.zip
, then the entries in the ZIP file that end in.java
will be included as ordinary inputs to compilation. This is common when using agenrule()
to auto-generate some Java source code that needs to be compiled with some hand-written Java code.target
: Specifies the version of Java (as a string) for which to generate code. Overrides the value in "target_level" in the "java" section of.buckconfig
.
Details
Examples:
# A rule that compiles a single .java file.
java_library(
name = 'JsonUtil',
srcs = ['JsonUtil.java'],
deps = [
'//third_party/guava:guava',
'//third_party/jackson:jackson',
],
)
# A rule that compiles all of the .java files under the directory in
# which the rule is defined using glob(). It also excludes an
# individual file that may have additional dependencies, so it is
# compiled by a separate rule.
java_library(
name = 'messenger',
srcs = glob(['**/*.java'], excludes = ['MessengerModule.java']),
deps = [
'//src/com/facebook/base:base',
'//third_party/guava:guava',
],
)
java_library(
name = 'MessengerModule',
srcs = ['MessengerModule.java'],
deps = [
'//src/com/facebook/base:base',
'//src/com/google/inject:inject',
'//third_party/guava:guava',
'//third_party/jsr-330:jsr-330',
],
)
# A rule that builds a library with both relative and
# fully-qualified deps.
java_library(
name = 'testutil',
srcs = glob(['tests/**/*.java'], excludes = 'tests/**/*Test.java'),
deps = [
':lib-fb4a',
'//java/com/facebook/base:base',
],
)
java_plugin
def java_plugin(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
_build_only_native_code: bool = _,
buck2_compatibility: str = _,
contacts: list[str] = _,
default_host_platform: None | str = _,
deps: list[str] = _,
does_not_affect_abi: bool = _,
isolate_class_loader: bool = _,
labels: list[str] = _,
licenses: list[str] = _,
plugin_name: str = _,
supports_abi_generation_from_source: bool = _
) -> None
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this one
java_test
def java_test(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
_build_only_native_code: bool = _,
_exec_os_type: str = _,
_inject_test_env: str = _,
_is_building_android_binary: bool = _,
_java_test_toolchain: str = _,
_java_toolchain: str = _,
_remote_test_execution_toolchain: str = _,
_wip_java_plugin_arguments: dict[str, list[str]] = _,
abi_generation_mode: None | str = _,
annotation_processor_deps: list[str] = _,
annotation_processor_params: list[str] = _,
annotation_processors: list[str] = _,
buck2_compatibility: str = _,
contacts: list[str] = _,
cxx_library_whitelist: list[str] = _,
default_cxx_platform: None | str = _,
default_host_platform: None | str = _,
deps: list[str] = _,
deps_query: None | str = _,
env: dict[str, str] = _,
exported_deps: list[str] = _,
exported_provided_deps: list[str] = _,
extra_arguments: list[str] = _,
fork_mode: str = _,
jar_postprocessor: None | str = _,
java: None | str = _,
java_agents: list[str] = _,
java_version: None | str = _,
javac: None | str = _,
labels: list[str] = _,
licenses: list[str] = _,
manifest_file: None | str = _,
maven_coords: None | str = _,
never_mark_as_unused_dependency: None | bool = _,
on_unused_dependencies: None | str = _,
plugins: list[str] = _,
proguard_config: None | str = _,
provided_deps: list[str] = _,
remote_execution: None | str | dict[str, None | bool | int | str | list[dict[str, str]] | dict[str, str]] = _,
remote_execution_action_key_providers: None | str = _,
remove_classes: list[str] = _,
required_for_source_only_abi: bool = _,
resources: list[str] = _,
resources_root: None | str = _,
run_test_separately: bool = _,
runner: None | str = _,
runtime_deps: list[str] = _,
source: None | str = _,
source_abi_verification_mode: None | str = _,
source_only_abi_deps: list[str] = _,
specs: None | str = _,
srcs: list[str] = _,
std_err_log_level: None | int | str = _,
std_out_log_level: None | int | str = _,
target: None | str = _,
test_case_timeout_ms: None | int = _,
test_class_names_file: None | str = _,
test_rule_timeout_ms: None | int = _,
test_type: None | str = _,
unbundled_resources_root: None | str = _,
use_cxx_libraries: None | bool = _,
use_dependency_order_classpath: None | bool = _,
vm_args: list[str] = _
) -> None
A java_test()
rule is used to define a set of .java
files that contain tests to run via JUnit.
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this onecxx_library_whitelist
: EXPERIMENTAL. List of cxx_libraries to build, if use_cxx_libraries is true. This can be useful if some dependencies are Android-only and won't build on the default platform.deps
: Same asjava_library()
. // org.junit.rules.Timeout was not introduced until 4.7. Must include JUnit (version 4.7 or later) as a dependency for JUnit tests. Must include TestNG (version 6.2 or later) and hamcrest as a dependencies for TestNG tests.env
: A map of environment names and values to set when running the test.fork_mode
: Controls whether tests will all be run in the same process or a process will be started for each set of tests in a class.(This is mainly useful when porting Java tests to Buck from Apache Ant which allows JUnit tasks to set a
fork="yes"
property. It should not be used for new tests since it encourages tests to not cleanup after themselves and increases the tests' computational resources and running time.)none
All tests will run in the same process.per_test
A process will be started for each test class in which all tests of that test class will run.labels
: A list of labels to be applied to these tests. These labels are arbitrary text strings and have no meaning within buck itself. They can, however, have meaning for you as a test author (e.g.,smoke
orfast
). A label can be used to filter or include a specific test rule when executingbuck test
resources
: Same asjava_library()
.source
: Java language level for compiling. Corresponds to the-source
argument forjavac
.srcs
: Likejava_library()
, all of the.java
files specified by thesrcs
argument will be compiled when this rule is built. In addition, all of the corresponding.class
files that are built by this rule will be passed as arguments to JUnit when this rule is run as a test..class
files that are passed to JUnit that do not have any methods annotated with@Test
are considered failed tests, so make sure that only test case classes are specified assrcs
. This is frequently done by specifyingsrcs
asglob(['**/*Test.java'])
.std_err_log_level
: Same asstd_out_log_level
, but for std err.std_out_log_level
: Log level for messages from the source under test that buck will output to std out. Value must be a validjava.util.logging.Level
value.target
: Bytecode target level for compiling. Corresponds to the-target
argument forjavac
.test_rule_timeout_ms
: If set specifies the maximum amount of time (in milliseconds) in which all of the tests in this rule should complete. This overrides the defaultrule_timeout
if any has been specified in.buckconfig
.test_type
: Specifies which test framework to use. The currently supported options are 'junit' and 'testng'.use_cxx_libraries
: Whether or not to build and link againstcxx_library()
dependencies when testing.vm_args
: Runtime arguments to the JVM running the tests.
java_test_runner
def java_test_runner(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
_wip_java_plugin_arguments: dict[str, list[str]] = _,
abi_generation_mode: None | str = _,
annotation_processor_deps: list[str] = _,
annotation_processor_params: list[str] = _,
annotation_processors: list[str] = _,
buck2_compatibility: str = _,
contacts: list[str] = _,
default_host_platform: None | str = _,
deps: list[str] = _,
exported_deps: list[str] = _,
exported_provided_deps: list[str] = _,
extra_arguments: list[str] = _,
java_version: None | str = _,
javac: None | str = _,
labels: list[str] = _,
licenses: list[str] = _,
main_class: str = _,
manifest_file: None | str = _,
maven_coords: None | str = _,
never_mark_as_unused_dependency: None | bool = _,
on_unused_dependencies: None | str = _,
plugins: list[str] = _,
proguard_config: None | str = _,
provided_deps: list[str] = _,
remove_classes: list[str] = _,
required_for_source_only_abi: bool = _,
resources: list[str] = _,
resources_root: None | str = _,
runtime_deps: list[str] = _,
source: None | str = _,
source_abi_verification_mode: None | str = _,
source_only_abi_deps: list[str] = _,
srcs: list[str] = _,
target: None | str = _
) -> None
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this one
js_bundle
def js_bundle(
*,
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] = _,
_android_toolchain: str = _,
_apple_platforms: dict[str, str] = _,
_is_release: bool = _,
_platform: str = _,
android_package: None | str = _,
buck2_compatibility: str = _,
bundle_name: None | str = _,
bundle_name_for_flavor: list[(str, str)] = _,
contacts: list[str] = _,
default_host_platform: None | str = _,
deps: list[str] = _,
entry: str | list[str],
extra_json: None | str = _,
fallback_transform_profile: None | str = _,
labels: list[str] = _,
licenses: list[str] = _,
worker: str
) -> None
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this one
js_bundle_genrule
def js_bundle_genrule(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
_build_only_native_code: bool = _,
_exec_os_type: str = _,
_genrule_toolchain: str = _,
_is_release: bool = _,
_platform: str = _,
always_print_stderr: bool = _,
bash: None | str = _,
buck2_compatibility: str = _,
bundle_name: None | str = _,
bundle_name_for_flavor: list[(str, str)] = _,
cacheable: None | bool = _,
cmd: None | str = _,
cmd_exe: None | str = _,
contacts: list[str] = _,
default_host_platform: None | str = _,
enable_sandbox: None | bool = _,
environment_expansion_separator: None | str = _,
js_bundle: str,
labels: list[str] = _,
licenses: list[str] = _,
metadata_env_var: None | str = _,
metadata_path: None | str = _,
need_android_tools: bool = _,
no_outputs_cleanup: bool = _,
remote: None | bool = _,
remote_execution_dependencies: list[dict[str, str]] = _,
rewrite_deps_file: bool = _,
rewrite_misc: bool = _,
rewrite_sourcemap: bool = _,
skip_resources: bool = _,
srcs: list[str] | dict[str, str] = _,
type: str = _,
weight: None | int = _
) -> None
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this one
js_library
def js_library(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
_asset_dest_path_resolver: None | str = _,
_build_only_native_code: bool = _,
_is_release: bool = _,
_platform: str = _,
asset_extensions: None | list[str] = _,
asset_platforms: None | list[str] = _,
base_path: None | str = _,
buck2_compatibility: str = _,
contacts: list[str] = _,
default_host_platform: None | str = _,
deps: list[str] = _,
deps_query: None | str = _,
extra_json: None | str = _,
labels: list[str] = _,
licenses: list[str] = _,
srcs: list[str | (str, str)] = _,
worker: str
) -> None
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this one
julia_binary
def julia_binary(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
_julia_toolchain: str = _,
buck2_compatibility: str = _,
deps: list[str] = _,
julia_args: list[str] = _,
julia_flags: list[str] = _,
main: str,
srcs: list[str] = _
) -> None
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this one
julia_jll_library
def julia_jll_library(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
_julia_toolchain: str = _,
buck2_compatibility: str = _,
jll_name: str,
lib_mapping: list[str] | dict[str, str],
uuid: str
) -> None
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this one
julia_library
def julia_library(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
_julia_toolchain: str = _,
buck2_compatibility: str = _,
deps: list[str] = _,
project_toml: str,
resources: list[str] = _,
srcs: list[str] = _
) -> None
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this one
julia_test
def julia_test(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
_inject_test_env: str = _,
_julia_toolchain: str = _,
buck2_compatibility: str = _,
contacts: list[str] = _,
deps: list[str] = _,
julia_args: list[str] = _,
julia_flags: list[str] = _,
main: str,
srcs: list[str] = _
) -> None
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this one
keystore
def keystore(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
buck2_compatibility: str = _,
contacts: list[str] = _,
default_host_platform: None | str = _,
deps: list[str] = _,
labels: list[str] = _,
licenses: list[str] = _,
properties: str,
store: str
) -> None
A keystore()
contains the data for a key pair created by the keytool
executable that comes with the JDK. This is a required input for an android_binary()
rule.
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this oneproperties
: The path to the.properties
file that contains the following values:
# The value that you passed as the argument to -alias
# when you ran keytool.
key.alias=my_alias
# The value that you entered in response to
# the "Enter keystore password:" prompt.
key.store.password=store_password
# The value that you entered in response to
# the "Enter key password for <my_alias>" prompt.
key.alias.password=alias_passwordstore
: The path to the file that contains the key. This is the path that was passed as the-keystore
argument when you rankeytool
.
kotlin_library
def kotlin_library(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
_build_only_native_code: bool = _,
_dex_min_sdk_version: None | int = _,
_dex_toolchain: str = _,
_exec_os_type: str = _,
_is_building_android_binary: bool = _,
_java_toolchain: str = _,
_kotlin_toolchain: str = _,
_wip_java_plugin_arguments: dict[str, list[str]] = _,
abi_generation_mode: None | str = _,
annotation_processing_tool: None | str = _,
annotation_processor_deps: list[str] = _,
annotation_processor_params: list[str] = _,
annotation_processors: list[str] = _,
buck2_compatibility: str = _,
contacts: list[str] = _,
default_host_platform: None | str = _,
deps: list[str] = _,
exported_deps: list[str] = _,
exported_provided_deps: list[str] = _,
extra_arguments: list[str] = _,
extra_kotlinc_arguments: list[str] = _,
friend_paths: list[str] = _,
incremental: bool = _,
jar_postprocessor: None | str = _,
java_version: None | str = _,
javac: None | str = _,
k2: bool = _,
kotlin_compiler_plugins: dict[str, dict[str, str]] = _,
labels: list[str] = _,
licenses: list[str] = _,
manifest_file: None | str = _,
maven_coords: None | str = _,
never_mark_as_unused_dependency: None | bool = _,
on_unused_dependencies: None | str = _,
plugins: list[str] = _,
proguard_config: None | str = _,
provided_deps: list[str] = _,
remove_classes: list[str] = _,
required_for_source_only_abi: bool = _,
resources: list[str] = _,
resources_root: None | str = _,
runtime_deps: list[str] = _,
source: None | str = _,
source_abi_verification_mode: None | str = _,
source_only_abi_deps: list[str] = _,
srcs: list[str] = _,
target: None | str = _,
use_jvm_abi_gen: None | bool = _,
validation_deps: list[str] = _
) -> None
A kotlin_library()
rule is used to define a set of Kotlin files that can be compiled together. The main output of a kotlin_library()
rule is a single JAR file containing all of the compiled class files, as well as the static files specified in the resources
argument.
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this oneannotation_processing_tool
: Specifies the tool to use for annotation processing. Possible values: "kapt" or "javac". "kapt" allows running Java annotation processors against Kotlin sources while backporting it for Java sources too. "javac" works only against Java sources, Kotlin sources won't have access to generated classes at compile time.deps
: Rules (usually otherkotlin_library
rules) that are used to generate the classpath required to compile thiskotlin_library
.exported_deps
: Other rules that depend on this rule will also include itsexported_deps
in their classpaths. This is useful when the public API of a rule has return types or checked exceptions that are defined in another rule, which would otherwise require callers to add an extra dependency. It's also useful for exposing e.g. a collection ofprebuilt_jar
rules as a single target for callers to depend on. Targets inexported_deps
are implicitly included in thedeps
of this rule, so they don't need to be repeated there.exported_provided_deps
: This is a combination ofprovided_deps
andexported_deps
. Rules listed in this parameter will be added to classpath of rules that depend on this rule, but they will not be included in a binary if binary depends on a such target.extra_kotlinc_arguments
: List of additional arguments to pass into the Kotlin compiler.friend_paths
: List of source paths to pass into the Kotlin compiler as friend-paths, that is, modules you can have access to internal methods.incremental
: Enables Kotlin incremental compilation.k2
: Enables the Kotlin K2 compiler.kotlin_compiler_plugins
: Use this to specify Kotlin compiler plugins to use when compiling this library. This takes a map, with each entry specify one plugin. Entry's key is plugin source path, and value is a map of plugin option key value pair. Unlikeextra_kotlinc_arguments
, these can be source paths, not just strings.A special option value is
__codegen_dir__
, in which case Buck will provide a default codegen folder's path as option value instead. E.g.
kotlin_compiler_plugins = {
"somePluginSourcePath": {
"plugin:somePluginId:somePluginOptionKey": "somePluginOptionValue",
"plugin:somePluginId:someDirectoryRelatedOptionKey": "__codegen_dir__",
},
},Each plugin source path will be prefixed with
-Xplugin=
and passed as extra arguments to the compiler. Plugin options will be appended after its plugin with-P
.A specific example is, if you want to use kotlinx.serialization with
kotlin_library()
, you need to specifykotlinx-serialization-compiler-plugin.jar
underkotlin_compiler_plugins
andkotlinx-serialization-runtime.jar
(which you may have to fetch from Maven) in yourdeps
:
kotlin_library(
name = "example",
srcs = glob(["*.kt"]),
deps = [
":kotlinx-serialization-runtime",
],
kotlin_compiler_plugins = {
# Likely copied from your $KOTLIN_HOME directory.
"kotlinx-serialization-compiler-plugin.jar": {},
},
)
prebuilt_jar(
name = "kotlinx-serialization-runtime",
binary_jar = ":kotlinx-serialization-runtime-0.10.0",
)
# Note you probably want to set
# maven_repo=http://jcenter.bintray.com/ in your .buckconfig until
# https://github.com/Kotlin/kotlinx.serialization/issues/64
# is closed.
remote_file(
name = "kotlinx-serialization-runtime-0.10.0",
out = "kotlinx-serialization-runtime-0.10.0.jar",
url = "mvn:org.jetbrains.kotlinx:kotlinx-serialization-runtime:jar:0.10.0",
sha1 = "23d777a5282c1957c7ce35946374fff0adab114c"
)labels
: Set of arbitrary strings which allow you to annotate abuild rule
with tags that can be searched for over an entire dependency tree usingbuck query()
.provided_deps
: These represent dependencies that are known to be provided at run time, but are required in order for the code to compile. Examples ofprovided_deps
include the JEE servlet APIs. When this rule is included in a , theprovided_deps
will not be packaged into the output.remove_classes
: Specifies a list ofPatterns
that are used to excludeclasses
from theJAR
. The pattern matching is based on the name of the class. This can be used to exclude a member class or delete a local view of a class that will be replaced during a later stage of the build.resources
: Static files to include with the compiled.class
files. These files can be loaded via Class.getResource().Note: If
resources_root
isn't set, Buck uses the.buckconfig
property in.buckconfig
to determine where resources should be placed within the generated JAR file.srcs
: The set of.kt
,.java
or.kts
files to compile for this rule. If any of the files in this list end in.src.zip
, then the entries in the ZIP file that end in.java
or.kt
will be included as ordinary inputs to compilation.
Details
Examples:
# A rule that compiles a single .kt file.
kotlin_library(
name = 'JsonUtil',
srcs = ['JsonUtil.kt'],
deps = [
'//third_party/guava:guava',
'//third_party/jackson:jackson',
],
)
# A rule that compiles all of the .kt files under the directory in
# which the rule is defined using glob(). It also excludes an
# individual file that may have additional dependencies, so it is
# compiled by a separate rule.
kotlin_library(
name = 'messenger',
srcs = glob(['**/*.kt'], excludes = ['MessengerModule.kt']),
deps = [
'//src/com/facebook/base:base',
'//third_party/guava:guava',
],
)
kotlin_library(
name = 'MessengerModule',
srcs = ['MessengerModule.kt'],
deps = [
'//src/com/facebook/base:base',
'//src/com/google/inject:inject',
'//third_party/guava:guava',
'//third_party/jsr-330:jsr-330',
],
)
# A rule that builds a library with both relative and
# fully-qualified deps.
kotlin_library(
name = 'testutil',
srcs = glob(['tests/**/*.kt'], excludes = 'tests/**/*Test.kt'),
deps = [
':lib-fb4a',
'//java/com/facebook/base:base',
],
)
kotlin_test
def kotlin_test(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
_build_only_native_code: bool = _,
_exec_os_type: str = _,
_inject_test_env: str = _,
_is_building_android_binary: bool = _,
_java_test_toolchain: str = _,
_java_toolchain: str = _,
_kotlin_toolchain: str = _,
_remote_test_execution_toolchain: str = _,
_wip_java_plugin_arguments: dict[str, list[str]] = _,
abi_generation_mode: None | str = _,
annotation_processing_tool: None | str = _,
annotation_processor_deps: list[str] = _,
annotation_processor_params: list[str] = _,
annotation_processors: list[str] = _,
buck2_compatibility: str = _,
contacts: list[str] = _,
cxx_library_whitelist: list[str] = _,
default_cxx_platform: None | str = _,
default_host_platform: None | str = _,
deps: list[str] = _,
deps_query: None | str = _,
env: dict[str, str] = _,
exported_deps: list[str] = _,
exported_provided_deps: list[str] = _,
extra_arguments: list[str] = _,
extra_kotlinc_arguments: list[str] = _,
fork_mode: str = _,
friend_paths: list[str] = _,
incremental: bool = _,
java: None | str = _,
java_agents: list[str] = _,
java_version: None | str = _,
javac: None | str = _,
k2: bool = _,
kotlin_compiler_plugins: dict[str, dict[str, str]] = _,
labels: list[str] = _,
licenses: list[str] = _,
manifest_file: None | str = _,
maven_coords: None | str = _,
never_mark_as_unused_dependency: None | bool = _,
on_unused_dependencies: None | str = _,
plugins: list[str] = _,
proguard_config: None | str = _,
provided_deps: list[str] = _,
remote_execution: None | str | dict[str, None | bool | int | str | list[dict[str, str]] | dict[str, str]] = _,
remote_execution_action_key_providers: None | str = _,
remove_classes: list[str] = _,
required_for_source_only_abi: bool = _,
resources: list[str] = _,
resources_root: None | str = _,
run_test_separately: bool = _,
runtime_deps: list[str] = _,
source: None | str = _,
source_abi_verification_mode: None | str = _,
source_only_abi_deps: list[str] = _,
srcs: list[str] = _,
std_err_log_level: None | int | str = _,
std_out_log_level: None | int | str = _,
target: None | str = _,
test_case_timeout_ms: None | int = _,
test_class_names_file: None | str = _,
test_rule_timeout_ms: None | int = _,
test_type: None | str = _,
unbundled_resources_root: None | str = _,
use_cxx_libraries: None | bool = _,
use_dependency_order_classpath: None | bool = _,
use_jvm_abi_gen: None | bool = _,
vm_args: list[str] = _
) -> None
A kotlin_test()
rule is used to define a set of .kt
files that contain tests to run via JUnit.
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this onedeps
: Same askotlin_library()
. // org.junit.rules.Timeout was not introduced until 4.7. Must include JUnit (version 4.7 or later) as a dependency for JUnit tests. Must include TestNG (version 6.2 or later) and hamcrest as a dependencies for TestNG tests.env
: A map of environment names and values to set when running the test.fork_mode
: Controls whether tests will all be run in the same process or a process will be started for each set of tests in a class.(This is mainly useful when porting Java tests to Buck from Apache Ant which allows JUnit tasks to set a
fork="yes"
property. It should not be used for new tests since it encourages tests to not cleanup after themselves and increases the tests' computational resources and running time.)none
All tests will run in the same process.per_test
A process will be started for each test class in which all tests of that test class will run.incremental
: Enables Kotlin incremental compilation.k2
: Enables the Kotlin K2 compiler.labels
: A list of labels to be applied to these tests. These labels are arbitrary text strings and have no meaning within buck itself. They can, however, have meaning for you as a test author (e.g.,smoke
orfast
). A label can be used to filter or include a specific test rule when executingbuck test
resources
: Same askotlin_library()
.srcs
: Likekotlin_library()
, all of the.kt
files specified by thesrcs
argument will be compiled when this rule is built. In addition, all of the corresponding.class
files that are built by this rule will be passed as arguments to JUnit when this rule is run as a test..class
files that are passed to JUnit that do not have any methods annotated with@Test
are considered failed tests, so make sure that only test case classes are specified assrcs
. This is frequently done by specifyingsrcs
asglob(['**/*Test.kt'])
.std_err_log_level
: Same asstd_out_log_level
, but for std err.std_out_log_level
: Log level for messages from the source under test that buck will output to std out. Value must be a validjava.util.logging.Level
value.test_rule_timeout_ms
: If set specifies the maximum amount of time (in milliseconds) in which all of the tests in this rule should complete. This overrides the defaultrule_timeout
if any has been specified in.buckconfig
.test_type
: Specifies which test framework to use. The currently supported options are 'junit' and 'testng'.vm_args
: Runtime arguments to the JVM running the tests.
legacy_toolchain
def legacy_toolchain(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
buck2_compatibility: str = _,
contacts: list[str] = _,
default_host_platform: None | str = _,
labels: list[str] = _,
licenses: list[str] = _,
toolchain_name: str = _
) -> None
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this one
llvm_link_bitcode
def llvm_link_bitcode(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
_cxx_toolchain: str = _,
buck2_compatibility: str = _,
deps: list[str] = _,
deps_query: None | str = _,
srcs: list[str | (str, list[str])] = _
) -> None
A llvm_link_bitcode() rule builds a LLVM bitcode object from a given set LLVM bitcode inputs.
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this onedeps_query
: Status: experimental/unstable. The deps query takes a query string that accepts the following query functions, and appends the output of the query to the declared deps:attrfilter
deps
except
intersect
filter
kind
set
union
The macro
$declared_deps
may be used anywhere a target literal pattern is expected in order to refer to the explicit deps of this rule as they appear in the rule's definition. For example, if your build rule declares
android_library(
name = 'lib',
deps = ['//foo:foo'],
deps_query = '$declared_deps',
)then the macro
$declared_deps
would be expanded to a literalset(//foo:foo)
. Some example queries:
"filter({name_regex}, $declared_deps)".format(name_regex='//.*')
"attrfilter(annotation_processors, com.foo.Processor, $declared_deps)"
"deps('//foo:foo', 1)"Note: any targets included in this query must also be present in
deps
.srcs
: The set of C, C++, Objective-C, Objective-C++, or assembly source files to be preprocessed, compiled, and assembled by this rule. We determine which stages to run on each input source based on its file extension. See the GCC documentation for more detail on how file extensions are interpreted. Each element can be either a string specifying a source file (e.g.''
) or a tuple of a string specifying a source file and a list of compilation flags (e.g.('', ['-Wall', '-Werror'])
). In the latter case the specified flags will be used in addition to the rule's other flags when preprocessing and compiling that file (if applicable).
Details
Examples:
# A rule that builds and runs C/C++ test using gtest.
llvm_link_bitcode(
name = 'echo_test',
srcs = [
'echo_test.o', // Where this is a LLVM bitcode object.
'echo_other.o', // And this is another LLVM bitcode object.
],
)
lua_binary
def lua_binary(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
buck2_compatibility: str = _,
contacts: list[str] = _,
default_host_platform: None | str = _,
deps: list[str] = _,
labels: list[str] = _,
licenses: list[str] = _,
main_module: str = _,
native_starter_library: None | str = _,
package_style: None | str = _,
platform: None | str = _,
platform_deps: list[(str, list[str])] = _,
python_platform: None | str = _
) -> None
A lua_library()
rule is used to group together Lua sources to be packaged into a top-level lua_binary()
rule.
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this onedeps
:lua_library()
rules to this binary will access.main_module
: The module which serves as the entry point for this rule.
Details
Examples:
lua_binary(
name = 'tailer',
main_module = 'tailer',
deps = [
':tailerutils',
],
)
lua_library(
name = 'tailerutils',
srcs = glob(['*.lua']),
)
lua_library
def lua_library(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
base_module: None | str = _,
buck2_compatibility: str = _,
contacts: list[str] = _,
default_host_platform: None | str = _,
deps: list[str] = _,
labels: list[str] = _,
licenses: list[str] = _,
platform_deps: list[(str, list[str])] = _,
srcs: list[str] | dict[str, str] = _
) -> None
A lua_library()
rule is used to group together Lua sources to be packaged into a top-level lua_binary()
rule.
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this onebase_module
: The package for which the given specified sources and resources should reside in their final location in the top-level binary. If unset, the project relative directory that houses the BUCK file is used.deps
: Otherlua_library()
rules which listsrcs
from which this rule imports modules.srcs
: The set of.lua
files included in this library.
Details
Examples:
# A rule that includes a single .py file.
lua_library(
name = 'fileutil',
srcs = ['fileutil.lua'],
)
# A rule that uses glob() to include all sources in the directory which the
# rule is defined. It also lists a resource file that gets packaged with
# the sources in this rule.
lua_library(
name = 'testutil',
srcs = glob(['testutil/**/*.lua'],
)
matlab_program
def matlab_program(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
_matlab_toolchain: str = _,
buck2_compatibility: str = _,
main: str
) -> None
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this one
ndk_library
def ndk_library(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
buck2_compatibility: str = _,
contacts: list[str] = _,
default_host_platform: None | str = _,
deps: list[str] = _,
flags: list[str] = _,
is_asset: bool = _,
labels: list[str] = _,
licenses: list[str] = _,
srcs: list[str] = _
) -> None
An ndk_library()
is used to define a set of C/C++ files, an Android.mk
and an Application.mk
file that are used by the NDK's ndk-build
tool to generate one or more shared objects.
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this onedeps
: List of build targets to build before this rule.flags
: Array of strings passed verbatim tondk-build
. Normally this is not needed, but in some cases you may want to put something here. For example, this can be used to build the libraries in debug mode (NDK_DEBUG=1
) or set the number of jobs spawned byndk-build
(by default, the same as the number of cores).is_asset
: Normally native shared objects end up in a directory in the root of the APK namedlib/
. If this parameter is set toTrue
, then these objects are placed inassets/lib/
. Placing shared objects in a non-standard location prevents Android from extracting them to the device's internal storage.srcs
: The set of files to compile for this rule. If not provided,buck
assumes that all files with the following extensions are part of the build:c, cpp, cc, cxx, h, hpp, mk
.
Details
Additional notes:
An android_binary()
that includes this library will
aggregate all of the native shared objects into a directory in the
root of the APK named lib/
or assets/lib/
.
Unlike the default invocation of ndk-build
,
buck
will put all intermediate files and build output
into a subdirectory under buck-out/gen
.
ndk_toolchain
def ndk_toolchain(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
buck2_compatibility: str = _,
contacts: list[str] = _,
cxx_runtime: None | str = _,
cxx_toolchain: str,
default_host_platform: None | str = _,
labels: list[str] = _,
licenses: list[str] = _,
objdump: str,
shared_runtime_path: None | str = _,
strip_apk_libs_flags: None | list[str] = _
) -> None
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this one
ocaml_binary
def ocaml_binary(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
_cxx_toolchain: str = _,
_ocaml_toolchain: str = _,
buck2_compatibility: str = _,
bytecode_only: None | bool = _,
compiler_flags: list[str] = _,
contacts: list[str] = _,
default_host_platform: None | str = _,
deps: list[str] = _,
labels: list[str] = _,
licenses: list[str] = _,
linker_flags: list[str] = _,
ocamldep_flags: list[str] = _,
platform: None | str = _,
platform_compiler_flags: list[(str, list[str])] = _,
platform_deps: list[(str, list[str])] = _,
platform_linker_flags: list[(str, list[str])] = _,
srcs: None | list[str] | dict[str, str] = _,
warnings_flags: None | str = _
) -> None
A ocaml_binary() rule builds both native and bytecode executables from the supplied set of OCaml and C source files and dependencies.
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this onecompiler_flags
: The set of additional compiler flags to pass to ocaml compiler. It supports specifying ppx (see for example).deps
: The set of dependencies of this rule. It could include references to ocaml_library and cxx_library rules.platform_deps
: Platform specific dependencies. These should be specified as a list of pairs where the first element is an un-anchored regex (in java.util.regex.Pattern syntax) against which the platform name is matched, and the second element is a list of dependencies (same format asdeps
) that are exported if the platform matches the regex. Seedeps
for more information.srcs
: The set of source files to be compiled by this rule. It supports *.ml, *.mli, *.mly, *.mll, and *.c files. (see this test as C interop example and this test as parser and lexer example).
Details
Note: Buck is currently tested with 4.X OCaml series.
Examples:
For more examples, check out our integration tests.
ocaml_binary(
name='greet',
srcs=[
'main.ml',
'lex.mll',
'parser.mly',
'hashtable.c',
],
deps=[
':greeting',
':bridge',
],
)
ocaml_library(
name='greeting',
srcs=[
'greeting.ml',
],
deps=[
':join',
],
)
ocaml_library(
name='join',
srcs=[
'join.ml',
],
)
cxx_library(
name='bridge',
srcs=[
'bridge.c',
],
)
ocaml_library
def ocaml_library(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
_cxx_toolchain: str = _,
_ocaml_toolchain: str = _,
buck2_compatibility: str = _,
bytecode_only: bool = _,
compiler_flags: list[str] = _,
contacts: list[str] = _,
default_host_platform: None | str = _,
deps: list[str] = _,
labels: list[str] = _,
licenses: list[str] = _,
linker_flags: list[str] = _,
native_plugin: bool = _,
ocamldep_flags: list[str] = _,
platform_compiler_flags: list[(str, list[str])] = _,
platform_deps: list[(str, list[str])] = _,
srcs: None | list[str] | dict[str, str] = _,
warnings_flags: None | str = _
) -> None
A ocaml_library() rule builds a native and a bytecode libraries from the supplied set of OCaml source files and dependencies.
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this onecompiler_flags
: The set of additional compiler flags to pass to ocaml compiler. It supports specifying ppx (see for example).deps
: The set of dependencies of this rule. It could include references to ocaml_library and cxx_library rules.platform_deps
: Platform specific dependencies. These should be specified as a list of pairs where the first element is an un-anchored regex (in java.util.regex.Pattern syntax) against which the platform name is matched, and the second element is a list of dependencies (same format asdeps
) that are exported if the platform matches the regex. Seedeps
for more information.srcs
: The set of source files to be compiled by this rule. It supports *.ml, *.mli, *.mly, *.mll, and *.c files. (see this test as C interop example and this test as parser and lexer example).
Details
Note: Buck is currently tested with 4.X OCaml series.
Examples:
For more examples, check out our integration tests.
ocaml_library(
name='greeting',
srcs=[
'greeting.ml',
],
deps=[
':join',
],
)
ocaml_object
def ocaml_object(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
_cxx_toolchain: str = _,
_ocaml_toolchain: str = _,
buck2_compatibility: str = _,
bytecode_only: None | bool = _,
compiler_flags: list[str] = _,
contacts: list[str] = _,
default_host_platform: None | str = _,
deps: list[str] = _,
labels: list[str] = _,
licenses: list[str] = _,
linker_flags: list[str] = _,
ocamldep_flags: list[str] = _,
platform: None | str = _,
platform_deps: list[(str, list[str])] = _,
platform_linker_flags: list[(str, list[str])] = _,
srcs: None | list[str] | dict[str, str] = _,
warnings_flags: None | str = _
) -> None
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this one
ocaml_shared
def ocaml_shared(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
_cxx_toolchain: str = _,
_ocaml_toolchain: str = _,
buck2_compatibility: str = _,
bytecode_only: None | bool = _,
compiler_flags: list[str] = _,
contacts: list[str] = _,
default_host_platform: None | str = _,
deps: list[str] = _,
labels: list[str] = _,
licenses: list[str] = _,
linker_flags: list[str] = _,
ocamldep_flags: list[str] = _,
platform: None | str = _,
platform_deps: list[(str, list[str])] = _,
platform_linker_flags: list[(str, list[str])] = _,
srcs: None | list[str] | dict[str, str] = _,
warnings_flags: None | str = _
) -> None
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this one
platform
def platform(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
buck2_compatibility: str = _,
constraint_values: list[str] = _,
deps: list[str] = _
) -> None
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this one
prebuilt_apple_framework
def prebuilt_apple_framework(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
_apple_toolchain: str = _,
_apple_tools: str = _,
_stripped_default: bool = _,
buck2_compatibility: str = _,
contacts: list[str] = _,
default_host_platform: None | str = _,
deps: list[str] = _,
dsyms: list[str] = _,
exported_linker_flags: list[str] = _,
exported_platform_linker_flags: list[(str, list[str])] = _,
framework: None | str = _,
frameworks: list[str] = _,
labels: list[str] = _,
libraries: list[str] = _,
licenses: list[str] = _,
preferred_linkage: str = _,
stripped: None | bool = _,
supported_platforms_regex: None | str = _
) -> None
A prebuilt_apple_framework()
rule represents a set of Objective-C/C++ source files and is very similar to a prebuilt_cxx_library()
rule.
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this one
Details
Examples:
prebuilt_apple_framework(
name = 'MyPrebuiltFramework',
framework = 'myPrebuiltFramework.framework',
preferred_linkage = 'static',
visibility = [
'PUBLIC'
]
)
prebuilt_cxx_library
def prebuilt_cxx_library(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
_create_third_party_build_root: str = _,
_cxx_toolchain: str = _,
_target_os_type: str = _,
allow_cache_upload: None | bool = _,
buck2_compatibility: str = _,
can_be_asset: bool = _,
contacts: list[str] = _,
default_host_platform: None | str = _,
deffile: None | str = _,
deps: list[str] = _,
exported_deps: list[str] = _,
exported_header_style: str = _,
exported_headers: list[str] | dict[str, str] = _,
exported_lang_platform_preprocessor_flags: dict[str, list[(str, list[str])]] = _,
exported_lang_preprocessor_flags: dict[str, list[str]] = _,
exported_linker_flags: list[str] = _,
exported_platform_deps: list[(str, list[str])] = _,
exported_platform_headers: list[(str, list[str] | dict[str, str])] = _,
exported_platform_linker_flags: list[(str, list[str])] = _,
exported_platform_preprocessor_flags: list[(str, list[str])] = _,
exported_post_linker_flags: list[str] = _,
exported_post_platform_linker_flags: list[(str, list[str])] = _,
exported_preprocessor_flags: list[str] = _,
extract_soname: bool = _,
force_static: bool = _,
frameworks: list[str] = _,
header_dirs: None | list[str] = _,
header_namespace: None | str = _,
header_only: bool = _,
import_lib: None | str = _,
include_in_android_merge_map_output: bool = _,
labels: list[str] = _,
libraries: list[str] = _,
licenses: list[str] = _,
link_whole: bool = _,
link_without_soname: bool = _,
linker_flags: list[str] = _,
local_linker_flags: list[str] = _,
platform_header_dirs: None | list[(str, list[str])] = _,
platform_import_lib: None | list[(str, str)] = _,
platform_shared_lib: None | list[(str, str)] = _,
platform_static_lib: None | list[(str, str)] = _,
platform_static_pic_lib: None | list[(str, str)] = _,
post_linker_flags: list[str] = _,
preferred_linkage: str = _,
provided: bool = _,
public_include_directories: list[str] = _,
public_system_include_directories: list[str] = _,
raw_headers: list[str] = _,
shared_lib: None | str = _,
soname: None | str = _,
static_lib: None | str = _,
static_pic_lib: None | str = _,
supported_platforms_regex: None | str = _,
supports_merged_linking: None | bool = _,
supports_python_dlopen: bool = _,
supports_shared_library_interface: bool = _,
versioned_exported_lang_platform_preprocessor_flags: list[(dict[str, str], dict[str, list[(str, list[str])]])] = _,
versioned_exported_lang_preprocessor_flags: list[(dict[str, str], dict[str, list[str]])] = _,
versioned_exported_platform_preprocessor_flags: list[(dict[str, str], list[(str, list[str])])] = _,
versioned_exported_preprocessor_flags: list[(dict[str, str], list[str])] = _,
versioned_header_dirs: None | list[(dict[str, str], list[str])] = _,
versioned_import_lib: None | list[(dict[str, str], str)] = _,
versioned_shared_lib: None | list[(dict[str, str], str)] = _,
versioned_soname: None | list[(dict[str, str], str)] = _,
versioned_static_lib: None | list[(dict[str, str], str)] = _,
versioned_static_pic_lib: None | list[(dict[str, str], str)] = _
) -> None
A prebuilt_cxx_library()
rule represents a set of native libraries and C/C++ header files and provides various flags to control how they are linked and exported.
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this oneallow_cache_upload
: Whether to allow uploading the output of this rule to be uploaded to cache when the action is executed locally if the configuration allows (i.e. there is a cache configured and the client has permission to write to it).deffile
: Specifies the *.def file used on windows to modify a dll's exports in place of explicit__declspec(dllexport)
declarations. The default is to not use a defile.exported_deps
: Dependencies that will also appear to belong to any rules that depend on this one. This has two effects: Exported dependencies will also be included in the link line of dependents of this rules, but normal dependencies will not. Whenreexport_all_header_dependencies = False
, only exported headers of the rules specified here are re-exported.exported_headers
: The set of header files that are made available for inclusion to the source files in the target and all targets that transitively depend on it. These should be specified as either a list of header files or a dictionary of header names to header files. The headers can be included with#include "$HEADER_NAMESPACE/$HEADER_NAME"
or#include <$HEADER_NAMESPACE/$HEADER_NAME>
, where$HEADER_NAMESPACE
is the value of the target'sheader_namespace
attribute, and$HEADER_NAME
is the header name if specified, and the filename of the header file otherwise. Note that the header name can contain forward slashes (/
). Seeheader_namespace
for more information.exported_linker_flags
: Flags to add to the linker command line when the output from this rule, or the output from any rule that transitively depends on this rule, is used in a link operation.exported_platform_deps
: Platform specific dependencies that will also appear to belong to any rules that depend on this one. These should be specified as a list of pairs where the first element is an un-anchored regex (in java.util.regex.Pattern syntax) against which the platform name is matched, and the second element is a list of external dependencies (same format asexported_deps
) that are exported if the platform matches the regex. Seeexported_deps
for more information.exported_platform_headers
: Platform specific header files. These should be specified as a list of pairs where the first element is an un-anchored regex (in java.util.regex.Pattern syntax) against which the platform name is matched, and the second element is either a list of header files or a dictionary of header names to header files that will be made available for inclusion to the source files in the target and all targets that transitively depend on it if the platform matches the regex. Seeheaders
for more information.exported_platform_preprocessor_flags
: Platform specific exported preprocessor flags. These should be specified as a list of pairs where the first element is an un-anchored regex (in java.util.regex.Pattern syntax) against which the platform name is matched, and the second element is a list of flags to use when preprocessing the source files in the target and all targets that transitively depend on it if the platform matches the regex. Seeexported_preprocessor_flags
for more information.header_namespace
: A path prefix when including headers of this target. Defaults to the path from the root of the repository to the directory where this target is defined. Can contain forward slashes (/
), but cannot start with one. Seeheaders
for more information.header_only
: Indicates if this library only consists of headers or not. If this is set toTrue
, Buck will not link this library into any library that depends on it.local_linker_flags
: Flags to add to the linker command line whenever the output from this rule is used in a link operation driven by this rule (e.g. when this rule links a shared library, but not when the output is linked into a shared library by another rule's link group links).platform_shared_lib
: Platform specific shared library. These should be specified as a list of pairs where the first element is an un-anchored regex (in java.util.regex.Pattern syntax) against which the platform name is matched, and the second element the path to the library. Seeshared_lib
for more information.platform_static_lib
: Platform specific static library. These should be specified as a list of pairs where the first element is an un-anchored regex (in java.util.regex.Pattern syntax) against which the platform name is matched, and the second element the path to the library. Seestatic_lib
for more information.platform_static_pic_lib
: Platform specific static PIC library. These should be specified as a list of pairs where the first element is an un-anchored regex (in java.util.regex.Pattern syntax) against which the platform name is matched, and the second element the path to the library. Seestatic_pic_lib
for more information.preferred_linkage
: Determines what linkage is used when the library is depended on by another target. To control how the dependencies of this library are linked, uselink_style
instead.shared_lib
: The path to the library to use when performing shared linking.static_lib
: The path to the library to use when performing static linking.static_pic_lib
: The path to the library to use when performing static PIC linking.supported_platforms_regex
: If present, an un-anchored regex (in java.util.regex.Pattern syntax) that matches all platforms that this library supports. It will not be built for other platforms.supports_merged_linking
: Whether this rule supports building with the merged linking strategy when building for non-native binaries (e.g. when using.buckconfig
smerged
setting).
Details
Examples:
A prebuilt library containing only headers that other libraries may need.
prebuilt_cxx_library(
name = 'stdutil',
header_only = True,
header_dirs = [
'include',
],
)
A prebuilt library with static and shared libs.
prebuilt_cxx_library(
name = 'mylib',
soname = 'libmylib.so',
static_lib = 'libmylib.a',
static_pic_lib = 'libmylib_pic.a',
shared_lib = 'libmylib.so',
exported_headers = [
'mylib.h',
],
)
A prebuilt library with multiple builds for multiple platforms.
prebuilt_cxx_library(
name = 'mylib',
soname = 'libmylib.so',
platform_shared_lib = [
('android-arm', 'android-arm/libmylib.so'),
('android-x86', 'android-x86/libmylib.so'),
('iphonesimulator-x86_64', 'iphonesimulator-x86_64/libmylib.so'),
],
platform_static_lib = [
('android-arm', 'android-arm/libmylib.a'),
('android-x86', 'android-x86/libmylib.a'),
('iphonesimulator-x86_64', 'iphonesimulator-x86_64/libmylib.a'),
],
exported_headers = [
'mylib.h',
],
)
prebuilt_cxx_library_group
def prebuilt_cxx_library_group(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
_cxx_toolchain: str = _,
buck2_compatibility: str = _,
contacts: list[str] = _,
default_host_platform: None | str = _,
deps: list[str] = _,
exported_deps: list[str] = _,
exported_platform_deps: list[(str, list[str])] = _,
exported_preprocessor_flags: list[str] = _,
import_libs: dict[str, str] = _,
include_dirs: list[str] = _,
include_in_android_merge_map_output: bool = _,
labels: list[str] = _,
licenses: list[str] = _,
provided_shared_libs: dict[str, str] = _,
shared_libs: dict[str, str] = _,
shared_link: list[str] = _,
static_libs: list[str] = _,
static_link: list[str] = _,
static_pic_libs: list[str] = _,
static_pic_link: list[str] = _,
supported_platforms_regex: None | str = _,
supports_shared_library_interface: bool = _
) -> None
A prebuilt_cxx_library_group()
rule represents a group of native libraries which should be handled together in a single rule, perhaps using special link-line construction.
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this oneexported_deps
: Dependencies that will also appear to belong to any rules that depend on this one. This has two effects: Exported dependencies will also be included in the link line of dependents of this rules, but normal dependencies will not. Whenreexport_all_header_dependencies = False
, only exported headers of the rules specified here are re-exported.exported_platform_deps
: Platform specific dependencies that will also appear to belong to any rules that depend on this one. These should be specified as a list of pairs where the first element is an un-anchored regex (in java.util.regex.Pattern syntax) against which the platform name is matched, and the second element is a list of external dependencies (same format asexported_deps
) that are exported if the platform matches the regex. Seeexported_deps
for more information.provided_shared_libs
: The map of system-provided shared library names to paths used when using the shared link style. Theshared_link
parameter should refer to these libs using their library name.shared_libs
: The map of shared library names to paths used when using the shared link style. Theshared_link
parameter should refer to these libs using their library name.shared_link
: The arguments to use when linking this library group using the shared link style. The actual paths to libraries should be listed in theshared_libs
parameter, and referenced via the the$(lib [name])
macro (or the$(rel-lib [name])
macro, when the shared library should be linked using the-L[dir] -l[name]
style) in these args.static_libs
: The paths to the libraries used when using the static link style. Thestatic_link
parameter should refer to these libs using their index number.static_link
: The arguments to use when linking this library group using the static link style. The actual paths to libraries should be listed in thestatic_libs
parameter, and referenced via the the$(lib [index])
macro in these args.static_pic_libs
: The paths to the libraries used when using the static link style. Thestatic_pic_link
parameter should refer to these libs using their index number.static_pic_link
: The arguments to use when linking this library group using the static-pic link style. The actual paths to libraries should be listed in thestatic_pic_libs
parameter, and referenced via the the$(lib [index])
macro in these args.
Details
Examples:
A prebuilt library group wrapping two libraries that must be linked together.
prebuilt_cxx_library_group(
name = 'util',
static_link = [
'-Wl,--start-group',
'$(lib 0)',
'$(lib 1)',
'-Wl,--end-group',
],
static_libs = [
'lib/liba.a',
'lib/libb.a',
],
static_pic_link = [
'-Wl,--start-group',
'$(lib 0)',
'$(lib 1)',
'-Wl,--end-group',
],
static_libs = [
'lib/liba_pic.a',
'lib/libb_pic.a',
],
shared_link = [
'$(rel-lib liba.so)',
'$(rel-lib libb.so)',
],
shared_libs = {
'liba.so': 'lib/liba.so',
},
provided_shared_libs = {
'libb.so': 'lib/libb.so',
},
)
prebuilt_dotnet_library
def prebuilt_dotnet_library(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
assembly: str,
buck2_compatibility: str = _,
contacts: list[str] = _,
default_host_platform: None | str = _,
labels: list[str] = _,
licenses: list[str] = _
) -> None
A prebuilt_dotnet_library()
rule is used to include prebuilt .Net assembles into your .Net code.
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this oneassembly
: The path to the DLL that this rule provides.
Details
Examples:
prebuilt_dotnet_library(
name = 'log4net',
assembly = 'log4net.dll',
)
csharp_library(
name = 'example',
srcs = [
'Hello.cs',
],
framework_ver = 'net46',
deps = [
':log4net',
'System.dll',
],
)
prebuilt_jar
def prebuilt_jar(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
_build_only_native_code: bool = _,
_dex_min_sdk_version: None | int = _,
_dex_toolchain: str = _,
_exec_os_type: str = _,
_prebuilt_jar_toolchain: str = _,
binary_jar: str,
buck2_compatibility: str = _,
contacts: list[str] = _,
default_host_platform: None | str = _,
deps: list[str] = _,
desugar_deps: list[str] = _,
generate_abi: bool = _,
javadoc_url: None | str = _,
labels: list[str] = _,
licenses: list[str] = _,
maven_coords: None | str = _,
never_mark_as_unused_dependency: bool = _,
required_for_source_only_abi: bool = _,
source_jar: None | str = _
) -> None
A prebuilt_jar()
rule is used to identify a JAR file that is checked into our repository as a precompiled binary rather than one that is built from source by Buck. Frequently, these are used to reference third-party JAR files (such as junit.jar) and are used as dependencies of java_library()
rules.
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this onebinary_jar
: Path to the pre-built JAR file.deps
: Rules that must be built before this rule. Because thebinary_jar
is already built, there should be nothing to build, so this should be empty.javadoc_url
: URL to the Javadoc for the.class
files in thebinary_jar
.source_jar
: Path to a JAR file that contains the.java
files to create the.class
in thebinary_jar
. This is frequently provided for debugging purposes.
Details
Examples:
prebuilt_jar(
name = 'junit',
binary_jar = 'junit-4.8.2.jar',
source_jar = 'junit-4.8.2-sources.jar',
javadoc_url = 'http://kentbeck.github.com/junit/javadoc/4.8/',
)
java_library(
name = 'tests',
srcs = glob(['tests/**/*Test.java']),
deps = [
':junit',
],
)
prebuilt_native_library
def prebuilt_native_library(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
buck2_compatibility: str = _,
contacts: list[str] = _,
default_host_platform: None | str = _,
deps: list[str] = _,
has_wrap_script: bool = _,
is_asset: bool = _,
labels: list[str] = _,
licenses: list[str] = _,
native_libs: str
) -> None
A prebuilt_native_library()
rule is used to bundle native libraries (i.e., .so
files) for Android.
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this onehas_wrap_script
: When using an exopackage, if this parameter is set toTrue
, then the libraries for this rule are included in the primary APK even if native libraries would otherwise not be placed in it. This is intended for a native library directory that contains a wrap.sh script, which must be included in the primary APK to take effect. Only one ofis_asset
andhas_wrap_script
can be set for a rule.is_asset
: Normally native shared objects end up in a directory in the root of the APK namedlib/
. If this parameter is set toTrue
, then these objects are placed inassets/lib/
. Placing shared objects in a non-standard location prevents Android from extracting them to the device's internal storage.
Details
Examples:
Most of the time, a prebuilt_native_library
is private to the android_library()
that uses it:
prebuilt_native_library(
name = 'native_libs',
native_libs = 'libs',
)
android_library(
name = 'my_lib',
srcs = glob(['*.java']),
deps = [
':native_libs',
],
)
prebuilt_ocaml_library
def prebuilt_ocaml_library(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
buck2_compatibility: str = _,
bytecode_c_libs: list[str] = _,
bytecode_lib: None | str = _,
bytecode_only: bool = _,
c_libs: list[str] = _,
contacts: list[str] = _,
default_host_platform: None | str = _,
deps: list[str] = _,
include_dir: None | str = _,
labels: list[str] = _,
lib_dir: str = _,
lib_name: str = _,
licenses: list[str] = _,
native_c_libs: list[str] = _,
native_lib: None | str = _,
platform_deps: list[(str, list[str])] = _
) -> None
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this one
prebuilt_python_library
def prebuilt_python_library(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
_create_manifest_for_source_dir: str = _,
_create_third_party_build_root: str = _,
_extract: str = _,
_python_toolchain: str = _,
binary_src: str,
buck2_compatibility: str = _,
compile: bool = _,
contacts: list[str] = _,
cxx_header_dirs: None | list[str] = _,
default_host_platform: None | str = _,
deps: list[str] = _,
exclude_deps_from_merged_linking: bool = _,
ignore_compile_errors: bool = _,
infer_cxx_header_dirs: bool = _,
labels: list[str] = _,
licenses: list[str] = _,
strip_soabi_tags: bool = _
) -> None
A prebuilt_python_library()
rule is used to include prebuilt python packages into the output of a top-level python_binary()
or python_test()
rule.
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this onebinary_src
: The path to the.whl
or.egg
to use.Note:
.egg
files have a very particular naming convention that must be followed - otherwise it will not be found at runtime!deps
: Otherprebuilt_python_library()
rules which this library depends on. These may also bepython_library
rules if you want to depend on a source-based copy of the library.exclude_deps_from_merged_linking
: When linking the top-level binary with amerged
.buckconfig
, do not merge or re-link any native transitive deps of this library. This is useful if this library wraps prebuilt native extensions which cannot be re-linked as part of library merging.labels
: Set of arbitrary strings which allow you to annotate abuild rule
with tags that can be searched for over an entire dependency tree usingbuck query()
.strip_soabi_tags
: Strip the SOABI tags from extensions in the prebuilt library.Note that this should be considered unsafe, as it removes builtin protections that fail fast when a potententially incompatible native extension is imported.
Details
These prebuilt libraries can either be whl files or eggs
whls for most packages are available for download from PyPI. The whl used may be
downloaded with remote_file()
. However, Buck does not attempt to infer dependency information from pip,
so that information will have to be imparted by the user.
To create an egg for a package, run python setup.py bdist_egg
in the package source distribution.
Examples:
# A simple prebuilt_python_library with no external dependencies.
remote_file(
name = "requests-download",
url = "https://files.pythonhosted.org/packages/51/bd/23c926cd341ea6b7dd0b2a00aba99ae0f828be89d72b2190f27c11d4b7fb/requests-2.22.0-py2.py3-none-any.whl",
sha1 = "e1fc28120002395fe1f2da9aacea4e15a449d9ee",
out = "requests-2.22.0-py2.py3-none-any.whl",
)
prebuilt_python_library(
name = "requests",
binary_src = ":requests-download",
)
# A slightly more complex example
prebuilt_python_library(
name = "greenlet",
binary_src = "greenlet-0.4.7-py2.7-macosx-10.10-x86_64.egg",
)
prebuilt_python_library(
name = "gevent",
binary_src = "gevent-1.0.2-py2.7-macosx-10.10-x86_64.egg",
deps = [
":greenlet",
],
)
python_binary
def python_binary(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
_create_manifest_for_source_dir: str = _,
_cxx_hacks: str = _,
_cxx_toolchain: str = _,
_exec_os_type: str = _,
_package_remotely: bool = _,
_python_toolchain: str = _,
_target_os_type: str = _,
allow_cache_upload: None | bool = _,
anonymous_link_groups: bool = _,
auto_link_groups: bool = _,
base_module: None | str = _,
binary_linker_flags: list[str] = _,
bolt_flags: list[str] = _,
bolt_profile: None | str = _,
buck2_compatibility: str = _,
build_args: list[str] = _,
compile: None | bool = _,
compiler_flags: list[str] = _,
constraint_overrides: list[str] = _,
contacts: list[str] = _,
coverage_instrumentation_compiler_flags: list[str] = _,
cxx_main: str = _,
cxx_platform: None | str = _,
cxx_runtime_type: None | str = _,
deduplicate_merged_link_roots: None | bool = _,
default_host_platform: None | str = _,
default_platform: None | str = _,
defaults: dict[str, str] = _,
deps: list[str] = _,
deps_query: None | str = _,
devirt_enabled: bool = _,
distributed_thinlto_partial_split_dwarf: bool = _,
dummy_omnibus: None | str = _,
enable_distributed_thinlto: bool = _,
executable_deps: list[str] = _,
executable_name: None | str = _,
exported_needs_coverage_instrumentation: bool = _,
extension: None | str = _,
fat_lto: bool = _,
focused_list_target: None | str = _,
frameworks: list[str] = _,
header_namespace: None | str = _,
headers: list[str] | dict[str, str] = _,
headers_as_raw_headers_mode: None | str = _,
include_directories: list[str] = _,
inplace_build_args: list[str] = _,
labels: list[str] = _,
lang_compiler_flags: dict[str, list[str]] = _,
lang_platform_compiler_flags: dict[str, list[(str, list[str])]] = _,
lang_platform_preprocessor_flags: dict[str, list[(str, list[str])]] = _,
lang_preprocessor_flags: dict[str, list[str]] = _,
libraries: list[str] = _,
licenses: list[str] = _,
link_deps_query_whole: bool = _,
link_execution_preference: None | str = _,
link_group: None | str = _,
link_group_deps: list[str] = _,
link_group_map: None | str | list[(str, list[(None | str | list[None | str], str, None | str | list[str], None | str)], None | dict[str, typing.Any])] = _,
link_group_min_binary_node_count: None | int = _,
link_group_public_deps_label: None | str = _,
link_ordering: None | str = _,
link_style: str = _,
link_whole: bool = _,
linker_extra_outputs: list[str] = _,
linker_flags: list[str] = _,
main: None | str = _,
main_function: None | str = _,
main_module: None | str = _,
make_py_package: None | str = _,
manifest_module_entries: None | dict[str, list[str] | dict[str, typing.Any]] = _,
native_link_strategy: None | str = _,
package_split_dwarf_dwp: bool = _,
package_style: None | str = _,
par_style: None | str = _,
platform: None | str = _,
platform_compiler_flags: list[(str, list[str])] = _,
platform_deps: list[(str, list[str])] = _,
platform_headers: list[(str, list[str] | dict[str, str])] = _,
platform_linker_flags: list[(str, list[str])] = _,
platform_preload_deps: list[(str, list[str])] = _,
platform_preprocessor_flags: list[(str, list[str])] = _,
platform_srcs: list[(str, list[str | (str, list[str])])] = _,
post_linker_flags: list[str] = _,
post_platform_linker_flags: list[(str, list[str])] = _,
precompiled_header: None | str = _,
prefer_stripped_native_objects: bool = _,
prefer_stripped_objects: bool = _,
prefix_header: None | str = _,
preload_deps: list[str] = _,
preprocessor_flags: list[str] = _,
py_version_for_type_checking: None | str = _,
raw_headers: list[str] = _,
repl_main: None | str = _,
repl_only_deps: list[str] = _,
resources: list[str] | dict[str, str] = _,
run_with_inplace: bool = _,
runtime_env: None | dict[str, str] = _,
standalone_build_args: list[str] = _,
static_extension_finder: str = _,
static_extension_utils: str = _,
strip_libpar: str = _,
strip_stapsdt: bool = _,
thin_lto: bool = _,
typing: bool = _,
version_universe: None | str = _,
weak_framework_names: list[str] = _,
zip_safe: None | bool = _
) -> None
A python_binary()
rule is used to build an executable Python package that includes Python sources and resources from all transitive dependencies.
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this oneallow_cache_upload
: Whether to allow uploading the output of this rule to be uploaded to cache when the action is executed locally if the configuration allows (i.e. there is a cache configured and the client has permission to write to it).base_module
: The package in which the main module should reside in its final location in the binary. If unset, Buck uses the project-relative directory that contains the BUCK file.deduplicate_merged_link_roots
: When linking multiple top-level binaries with themerged
.buckconfig
, coalesce root link rules which are identical across independent merged links.deps
: A list ofpython_library()
rules that specify Python modules to include in the binary — including all transitive dependencies of these rules.labels
: Set of arbitrary strings which allow you to annotate abuild rule
with tags that can be searched for over an entire dependency tree usingbuck query()
.link_group_deps
: Additional targets to traverse when building link groups, but which should not be direct dependencies of the main executable.link_group_public_deps_label
: Surface nodes with this label as "public" nodes in the main executable when linking with with link groups.linker_flags
: Additional linker flags that should be applied to any linking which is specific to this rule. Note that whether these flags are used is dependent on the native link strategy selected in.buckconfig
and currently applies only to the merged.buckconfig
; theseparate
link strategy pulls in shared libraries that are linked in the context of the rules that own them, such ascxx_library()
.main
: The Python file which serves as the entry point for the binary. The interpreter initiates execution of the binary with the code in this file.main_function
: Name of a Python function that will serve as the main entry point of the binary. The name is either a fully qualified name likefoo.bar.baz
or it starts with a.
like.bar.baz
, in which case it is relative to the package containing the target. This should usually be a function defined within one of the dependencies of this target. This attribute should be preferred overmain_module
ormain
, and it is an error to specify more than one of these.main_module
: The python module that should be the entry point of the binary. This should be a module name within apython_library
that this binary depends on. Note that module names takebase_module
of the library into account. This property is mutually exclusive withmain
, and should be preferred tomain
, which is deprecated.manifest_module_entries
: If present, it should be astring
->entry
mapping that gets generated into a__manifest__
module in the executable. Top level string keys will be the names of variables in this module (so they must be valid Python identifiers). Anentry
can be a list ofstring
s, or a furtherstring
-keyed dictionary.package_style
: Used to override the global packaging style that is set in[
.buckconfig]
.platform
: The name of the Python platform flavor to build against by default as defined in the buckconfig#python
section of.buckconfig
.preload_deps
: A list of C/C++ library dependencies that need to be loaded before any other libraries when the PEX starts up. This requires dynamic loader support, such asLD_PRELOAD
, found on most systems. This list is order- sensitive and the preload libraries listed here are passed down to the dynamic linker in the same order.py_version_for_type_checking
: This option will force the type checker to perform checking under a specific version of Python interpreter.typing
: Determines whether to perform type checking on the given target. Default is False.
Details
Examples:
Build an executable from the Python files in the BUCK directory.
# BUCK
python_binary(
name = 'tailer',
main_module = 'tailer',
deps = [
':tailerutils',
],
)
python_library(
name = 'tailerutils',
# The main module, tailer.py, is specified here.
# (Separated out from the glob pattern for clarity.)
srcs = glob(['tailer.py', '*.py']),
)
python_bootstrap_binary
def python_bootstrap_binary(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
_exec_os_type: str = _,
_python_bootstrap_toolchain: str = _,
_win_python_wrapper: None | str = _,
buck2_compatibility: str = _,
deps: list[str] = _,
main: str
) -> None
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this one
python_bootstrap_library
def python_bootstrap_library(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
buck2_compatibility: str = _,
deps: list[str] = _,
srcs: list[str]
) -> None
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this one
python_library
def python_library(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
_create_manifest_for_source_dir: str = _,
_create_third_party_build_root: str = _,
_cxx_toolchain: str = _,
_python_toolchain: str = _,
base_module: None | str = _,
buck2_compatibility: str = _,
contacts: list[str] = _,
cxx_platform: None | str = _,
default_host_platform: None | str = _,
deps: list[str] = _,
exclude_deps_from_merged_linking: bool = _,
ignore_compile_errors: bool = _,
labels: list[str] = _,
licenses: list[str] = _,
platform: None | str = _,
platform_deps: list[(str, list[str])] = _,
platform_resources: list[(str, list[str] | dict[str, str])] = _,
platform_srcs: list[(str, list[str] | dict[str, str])] = _,
py_version_for_type_checking: None | str = _,
resources: list[str] | dict[str, str] = _,
srcs: list[str] | dict[str, str] = _,
type_stubs: list[str] | dict[str, str] = _,
typing: bool = _,
version_universe: None | str = _,
versioned_resources: None | list[(dict[str, str], list[str] | dict[str, str])] = _,
versioned_srcs: None | list[(dict[str, str], list[str] | dict[str, str])] = _,
zip_safe: None | bool = _
) -> None
A python_library()
rule is used to group together Python source files and resources to be passed together in as a dep
of other rules.
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this onebase_module
: The package in which the specified source files and resources should reside in their final location in the top-level binary. If unset, Buck uses the project-relative directory that contains the BUCK file.deps
: Otherpython_library()
rules that listsrcs
from which this rule imports modules.exclude_deps_from_merged_linking
: When linking the top-level binary with amerged
.buckconfig
, do not merge or re-link any native transitive deps of this library. This is useful if this library wraps prebuilt native extensions which cannot be re-linked as part of library merging.labels
: Set of arbitrary strings which allow you to annotate abuild rule
with tags that can be searched for over an entire dependency tree usingbuck query()
.platform_resources
: Python-platform-specific resource files. These should be specified as a list of pairs where the first element in each pair is an un-anchored regex against which the platform name is matched, and the second element is a list of resource files. The regex should usejava.util.regex.Pattern
syntax. The platform name is a Python platform flavor defined in the buckconfig#python
section of.buckconfig
.platform_srcs
: Python-platform-specific source files. These should be specified as a list of pairs where the first element in each pair is an un-anchored regex against which the platform name is matched, and the second element is a list of source files. The regex should usejava.util.regex.Pattern
syntax. The platform name is a Python platform flavor defined in the buckconfig#python
section of.buckconfig
.py_version_for_type_checking
: This option will force the type checker to perform checking under a specific version of Python interpreter.srcs
: The set of Python (.py
) files to include in this library.typing
: Determines whether to perform type checking on the given target. Default is False.
Details
Examples:
Include Python source files and resource files.
# BUCK
# A rule that includes a single Python file.
python_library(
name = 'fileutil',
srcs = ['fileutil.py'],
deps = [
'//third_party/python-magic:python-magic',
],
)
# A rule that uses glob() to include all Python source files in the
# directory in which the rule is defined. The rule also specifies a
# resource file that gets packaged with the source file.
python_library(
name = 'testutil',
srcs = glob(['testutil/**/*.py']),
resources = [
'testdata.dat',
],
)
python_needed_coverage_test
def python_needed_coverage_test(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
_inject_test_env: str = _,
_remote_test_execution_toolchain: str = _,
buck2_compatibility: str = _,
contacts: list[str] = _,
env: dict[str, str] = _,
labels: list[str] = _,
needed_coverage: list[(int, str, None | str)] = _,
remote_execution: None | str | dict[str, None | bool | int | str | list[dict[str, str]] | dict[str, str]] = _,
remote_execution_action_key_providers: None | str = _,
test: str
) -> None
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this one
python_test
def python_test(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
_create_manifest_for_source_dir: str = _,
_cxx_hacks: str = _,
_cxx_toolchain: str = _,
_exec_os_type: str = _,
_inject_test_env: str = _,
_python_toolchain: str = _,
_remote_test_execution_toolchain: str = _,
_target_os_type: str = _,
_test_main: str = _,
additional_coverage_targets: list[str] = _,
anonymous_link_groups: bool = _,
auto_link_groups: bool = _,
base_module: None | str = _,
binary_linker_flags: list[str] = _,
bolt_flags: list[str] = _,
bolt_profile: None | str = _,
buck2_compatibility: str = _,
build_args: list[str] = _,
compile: None | bool = _,
compiler_flags: list[str] = _,
constraint_overrides: list[str] = _,
contacts: list[str] = _,
coverage_instrumentation_compiler_flags: list[str] = _,
cxx_main: str = _,
cxx_platform: None | str = _,
cxx_runtime_type: None | str = _,
deduplicate_merged_link_roots: None | bool = _,
default_host_platform: None | str = _,
default_platform: None | str = _,
defaults: dict[str, str] = _,
deps: list[str] = _,
deps_query: None | str = _,
devirt_enabled: bool = _,
distributed_thinlto_partial_split_dwarf: bool = _,
dummy_omnibus: None | str = _,
enable_distributed_thinlto: bool = _,
env: dict[str, str] = _,
exclude_deps_from_merged_linking: bool = _,
executable_deps: list[str] = _,
executable_name: None | str = _,
exported_needs_coverage_instrumentation: bool = _,
extension: None | str = _,
fat_lto: bool = _,
focused_list_target: None | str = _,
frameworks: list[str] = _,
header_namespace: None | str = _,
headers: list[str] | dict[str, str] = _,
headers_as_raw_headers_mode: None | str = _,
implicit_test_library: None | str = _,
include_directories: list[str] = _,
inplace_build_args: list[str] = _,
labels: list[str] = _,
lang_compiler_flags: dict[str, list[str]] = _,
lang_platform_compiler_flags: dict[str, list[(str, list[str])]] = _,
lang_platform_preprocessor_flags: dict[str, list[(str, list[str])]] = _,
lang_preprocessor_flags: dict[str, list[str]] = _,
libraries: list[str] = _,
licenses: list[str] = _,
link_deps_query_whole: bool = _,
link_execution_preference: None | str = _,
link_group: None | str = _,
link_group_deps: list[str] = _,
link_group_map: None | str | list[(str, list[(None | str | list[None | str], str, None | str | list[str], None | str)], None | dict[str, typing.Any])] = _,
link_group_min_binary_node_count: None | int = _,
link_group_public_deps_label: None | str = _,
link_ordering: None | str = _,
link_style: str = _,
link_whole: bool = _,
linker_extra_outputs: list[str] = _,
linker_flags: list[str] = _,
main_function: None | str = _,
main_module: None | str = _,
make_py_package: None | str = _,
manifest_module_entries: None | dict[str, list[str] | dict[str, typing.Any]] = _,
native_link_strategy: None | str = _,
needed_coverage: list[(int, str, None | str)] = _,
package_split_dwarf_dwp: bool = _,
package_style: None | str = _,
par_style: None | str = _,
platform: None | str = _,
platform_compiler_flags: list[(str, list[str])] = _,
platform_deps: list[(str, list[str])] = _,
platform_headers: list[(str, list[str] | dict[str, str])] = _,
platform_linker_flags: list[(str, list[str])] = _,
platform_preload_deps: list[(str, list[str])] = _,
platform_preprocessor_flags: list[(str, list[str])] = _,
platform_resources: list[(str, list[str] | dict[str, str])] = _,
platform_srcs: list[(str, list[str | (str, list[str])])] = _,
post_linker_flags: list[str] = _,
post_platform_linker_flags: list[(str, list[str])] = _,
precompiled_header: None | str = _,
prefer_stripped_native_objects: bool = _,
prefer_stripped_objects: bool = _,
prefix_header: None | str = _,
preload_deps: list[str] = _,
preprocessor_flags: list[str] = _,
py_version_for_type_checking: None | str = _,
raw_headers: list[str] = _,
remote_execution: None | str | dict[str, None | bool | int | str | list[dict[str, str]] | dict[str, str]] = _,
remote_execution_action_key_providers: None | str = _,
repl_main: None | str = _,
repl_only_deps: list[str] = _,
resources: list[str] | dict[str, str] = _,
run_with_inplace: bool = _,
runner: None | str = _,
runtime_env: None | dict[str, str] = _,
specs: None | str = _,
srcs: list[str] | dict[str, str] = _,
standalone_build_args: list[str] = _,
static_extension_finder: str = _,
static_extension_utils: str = _,
strip_libpar: str = _,
strip_stapsdt: bool = _,
test_rule_timeout_ms: None | int = _,
thin_lto: bool = _,
typing: bool = _,
version_universe: None | str = _,
versioned_resources: None | list[(dict[str, str], list[str] | dict[str, str])] = _,
versioned_srcs: None | list[(dict[str, str], list[str] | dict[str, str])] = _,
weak_framework_names: list[str] = _,
zip_safe: None | bool = _
) -> None
A python_test()
rule defines a set of .py
files that contain tests to run via the Python unit testing framework.
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this onebase_module
: The package in which the specified source files and resources should reside in their final location in the top-level binary. If unset, Buck uses the project-relative directory that contains the BUCK file.deduplicate_merged_link_roots
: When linking multiple top-level binaries with themerged
.buckconfig
, coalesce root link rules which are identical across independent merged links.deps
: other rules used by the tests in this rule's sources.env
: A map of environment names and values to set when running the test.It is also possible to expand references to other rules within the values of these environment variables, using builtin
string parameter macros
:$(location //path/to:target)
Expands to the location of the output of the build rule. This means that you can refer to these without needing to be aware of how Buck is storing data on the disk mid-build.exclude_deps_from_merged_linking
: When linking the top-level binary with amerged
.buckconfig
, do not merge or re-link any native transitive deps of this library. This is useful if this library wraps prebuilt native extensions which cannot be re-linked as part of library merging.labels
: Set of arbitrary strings which allow you to annotate abuild rule
with tags that can be searched for over an entire dependency tree usingbuck query()
.link_group_deps
: Additional targets to traverse when building link groups, but which should not be direct dependencies of the main executable.link_group_public_deps_label
: Surface nodes with this label as "public" nodes in the main executable when linking with with link groups.linker_flags
: Additional linker flags that should be applied to any linking which is specific to this rule. Note that whether these flags are used is dependent on the native link strategy selected in.buckconfig
and currently applies only to the merged.buckconfig
; theseparate
link strategy pulls in shared libraries that are linked in the context of the rules that own them, such ascxx_library()
.main_function
: Name of a Python function that will serve as the main entry point of the binary. The name is either a fully qualified name likefoo.bar.baz
or it starts with a.
like.bar.baz
, in which case it is relative to the package containing the target. This should usually be a function defined within one of the dependencies of this target. This attribute should be preferred overmain_module
ormain
, and it is an error to specify more than one of these.main_module
: The main module used to run the tests. This parameter is normally not needed, as Buck will provide a default main module that runs all tests. However, you can override this with your own module to perform custom initialization or command line processing. Your custom module can import the standard Buck test main as__test_main__
, and can invoke it's normal main function as__test_main__.main(sys.argv)
.manifest_module_entries
: If present, it should be astring
->entry
mapping that gets generated into a__manifest__
module in the executable. Top level string keys will be the names of variables in this module (so they must be valid Python identifiers). Anentry
can be a list ofstring
s, or a furtherstring
-keyed dictionary.package_style
: Used to override the global packaging style that is set in[
.buckconfig]
.platform
: The name of the Python platform flavor to build against by default as defined in the buckconfig#python
section of.buckconfig
.platform_resources
: Python-platform-specific resource files. These should be specified as a list of pairs where the first element in each pair is an un-anchored regex against which the platform name is matched, and the second element is a list of resource files. The regex should usejava.util.regex.Pattern
syntax. The platform name is a Python platform flavor defined in the buckconfig#python
section of.buckconfig
.preload_deps
: A list of C/C++ library dependencies that need to be loaded before any other libraries when the PEX starts up. This requires dynamic loader support, such asLD_PRELOAD
, found on most systems. This list is order- sensitive and the preload libraries listed here are passed down to the dynamic linker in the same order.py_version_for_type_checking
: This option will force the type checker to perform checking under a specific version of Python interpreter.srcs
: The set of Python (.py
) files to include in this library.test_rule_timeout_ms
: If set specifies the maximum amount of time (in milliseconds) in which all of the tests in this rule should complete. This overrides the defaultrule_timeout
if any has been specified in.buckconfig
.typing
: Determines whether to perform type checking on the given target. Default is False.
Details
If your test requires static files you should specify these in the resources or platform_resources arguments. If you do not specify these files, they won't be available when your test runs.
Examples:
# A rule that includes a single .py file containing tests.
python_test(
name = 'fileutil_test',
srcs = ['fileutil_tests.py'],
deps = [
':fileutil',
],
)
# A rule that uses glob() to include all sources in the directory which the
# rule is defined. It also lists a resource file that gets packaged with
# the sources in this rule.
python_library(
name = 'fileutil',
srcs = glob(['fileutil/**/*.py']),
resources = [
'testdata.dat',
],
)
python_test_runner
def python_test_runner(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
buck2_compatibility: str = _,
contacts: list[str] = _,
default_host_platform: None | str = _,
labels: list[str] = _,
licenses: list[str] = _,
main_module: str = _,
src: str
) -> None
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this onelabels
: Set of arbitrary strings which allow you to annotate abuild rule
with tags that can be searched for over an entire dependency tree usingbuck query()
.
remote_file
def remote_file(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
_unzip_tool: str = _,
buck2_compatibility: str = _,
contacts: list[str] = _,
default_host_platform: None | str = _,
labels: list[str] = _,
licenses: list[str] = _,
out: None | str = _,
sha1: None | str = _,
sha256: None | str = _,
type: None | str = _,
url: str,
vpnless_url: None | str = _
) -> None
A remote_file()
rule is used to download files from the Internet to be used as dependencies for other rules. These rules are downloaded by running fetch
, or can be downloaded as part of build
. See the note there about the .buckconfig
setting to configure that.
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this oneout
: An optional name to call the downloaded artifact. Buck will generate a default name if one is not provided that uses thename
of the rule.type
: An optional type of the downloaded file.data
Regular data file.executable
Executable file. Buck will ensure that output has appropriate permissions if applicable.
exploded_zip
Zip archive which will be automatically unzipped into an output directory.
url
: You can specify anhttp
,https
, or amvn
URL. If you specify amvn
URL, it will be decoded as described in the javadocs for MavenUrlDecoder See the example section below.vpnless_url
: An optional additional URL from which this resource can be downloaded when off VPN. Meta-internal only.
Details
Examples:
Here's an example of a remote_file()
using an https
URL.
remote_file(
name = 'android-ndk-r10e-darwin-x86_64',
url = 'https://dl.google.com/android/ndk/android-ndk-r10e-darwin-x86_64.bin',
sha1 = 'b57c2b9213251180dcab794352bfc9a241bf2557',
)
Here's an example of a remote_file()
using a mvn
URL being referenced
by a prebuilt_jar()
.
prebuilt_jar(
name = 'jetty-all',
binary_jar = 'jetty-all-9.2.10.v20150310.jar',
source_jar = ':jetty-source',
)
remote_file(
name = 'jetty-source',
out = 'jetty-all-9.2.10.v20150310-sources.jar',
url = 'mvn:org.eclipse.jetty.aggregate:jetty-all:src:9.2.10.v20150310',
sha1 = '311da310416d2feb3de227081d7c3f48742d7075',
)
Here's an example of a remote_file()
using a mvn
URI which uses a
non-default maven repository host.
remote_file(
name = 'jetty-source',
out = 'jetty-all-9.2.10.v20150310-sources.jar',
url = 'mvn:https://maven-repo.com:org.eclipse.jetty.aggregate:jetty-all:src:9.2.10.v20150310',
sha1 = '311da310416d2feb3de227081d7c3f48742d7075',
)
Here's an example of a remote_file()
using a mvn
URI which uses a
Maven classifier.
remote_file(
name = 'groovy-groovysh-indy',
out = 'jetty-all-9.2.10.v20150310-sources.jar',
url = 'mvn:org.codehaus.groovy:groovy-groovysh:jar:indy:2.4.1',
sha1 = '1600fde728c885cc9506cb102deb1b494bd7c130',
)
robolectric_test
def robolectric_test(
*,
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] = _,
_android_toolchain: str = _,
_apple_platforms: dict[str, str] = _,
_build_only_native_code: bool = _,
_exec_os_type: str = _,
_inject_test_env: str = _,
_is_building_android_binary: bool = _,
_java_test_toolchain: str = _,
_java_toolchain: str = _,
_kotlin_toolchain: str = _,
_remote_test_execution_toolchain: str = _,
_wip_java_plugin_arguments: dict[str, list[str]] = _,
abi_generation_mode: None | str = _,
android_optional_jars: None | list[str] = _,
annotation_processing_tool: None | str = _,
annotation_processor_deps: list[str] = _,
annotation_processor_params: list[str] = _,
annotation_processors: list[str] = _,
buck2_compatibility: str = _,
contacts: list[str] = _,
cxx_library_whitelist: list[str] = _,
default_cxx_platform: None | str = _,
default_host_platform: None | str = _,
deps: list[str] = _,
env: dict[str, str] = _,
exported_deps: list[str] = _,
exported_provided_deps: list[str] = _,
extra_arguments: list[str] = _,
extra_kotlinc_arguments: list[str] = _,
fork_mode: str = _,
friend_paths: list[str] = _,
incremental: bool = _,
jar_postprocessor: None | str = _,
java: None | str = _,
java_agents: list[str] = _,
java_version: None | str = _,
javac: None | str = _,
k2: bool = _,
kotlin_compiler_plugins: dict[str, dict[str, str]] = _,
labels: list[str] = _,
language: None | str = _,
licenses: list[str] = _,
locales_for_binary_resources: list[str] = _,
manifest: None | str = _,
manifest_entries: dict[str, typing.Any] = _,
manifest_file: None | str = _,
maven_coords: None | str = _,
never_mark_as_unused_dependency: None | bool = _,
on_unused_dependencies: None | str = _,
plugins: list[str] = _,
preferred_density_for_binary_resources: None | str = _,
proguard_config: None | str = _,
provided_deps: list[str] = _,
provided_deps_query: None | str = _,
remote_execution: None | str | dict[str, None | bool | int | str | list[dict[str, str]] | dict[str, str]] = _,
remote_execution_action_key_providers: None | str = _,
remove_classes: list[str] = _,
required_for_source_only_abi: bool = _,
resource_stable_ids: None | str = _,
resource_union_package: None | str = _,
resources: list[str] = _,
resources_root: None | str = _,
robolectric_manifest: str,
robolectric_runtime_dependencies: list[str] = _,
robolectric_runtime_dependency: None | str = _,
run_test_separately: bool = _,
runtime_deps: list[str] = _,
source: None | str = _,
source_abi_verification_mode: None | str = _,
source_only_abi_deps: list[str] = _,
srcs: list[str] = _,
std_err_log_level: None | int | str = _,
std_out_log_level: None | int | str = _,
target: None | str = _,
test_case_timeout_ms: None | int = _,
test_class_names_file: None | str = _,
test_rule_timeout_ms: None | int = _,
test_type: None | str = _,
unbundled_resources_root: None | str = _,
use_cxx_libraries: None | bool = _,
use_dependency_order_classpath: None | bool = _,
use_jvm_abi_gen: None | bool = _,
used_as_dependency_deprecated_do_not_use: bool = _,
vm_args: list[str] = _
) -> None
A robolectric_test()
rule is used to define a set of .java
files that contain tests to run via JUnit with Robolectric test runner. It extends from java_test()
rule.
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this oneextra_kotlinc_arguments
: List of additional arguments to pass into the Kotlin compiler.incremental
: Enables Kotlin incremental compilation.k2
: Enables the Kotlin K2 compiler.robolectric_manifest
: An Android Manifest for the rule to declare any permissions or intents it may need or want to handle. May either be a file or anandroid_manifest()
target.robolectric_runtime_dependency
: Robolectric only runs in offline mode with buck. Specify the relative directory containing all the jars Robolectric uses at runtime.
rust_binary
def rust_binary(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
_cxx_toolchain: str = _,
_exec_os_type: str = _,
_rust_toolchain: str = _,
_target_os_type: str = _,
_workspaces: list[str] = _,
allow_cache_upload: None | bool = _,
anonymous_link_groups: bool = _,
auto_link_groups: bool = _,
buck2_compatibility: str = _,
clippy_configuration: None | str = _,
contacts: list[str] = _,
coverage: bool = _,
crate: None | str = _,
crate_root: None | str = _,
default_host_platform: None | str = _,
default_platform: None | str = _,
deps: list[str] = _,
edition: None | str = _,
enable_distributed_thinlto: bool = _,
env: dict[str, str] = _,
features: list[str] = _,
flagged_deps: list[(str, list[str])] = _,
incremental_build_mode: None | str = _,
incremental_enabled: bool = _,
labels: list[str] = _,
licenses: list[str] = _,
link_group: None | str = _,
link_group_map: None | str | list[(str, list[(None | str | list[None | str], str, None | str | list[str], None | str)], None | dict[str, typing.Any])] = _,
link_group_min_binary_node_count: None | int = _,
link_style: None | str = _,
linker_flags: list[str] = _,
mapped_srcs: dict[str, str] = _,
named_deps: list[(str, str)] | dict[str, str] = _,
resources: list[str] | dict[str, str] = _,
rpath: bool = _,
rustc_flags: list[str] = _,
rustdoc_flags: list[str] = _,
srcs: list[str] = _,
version_universe: None | str = _
) -> None
A rust_binary() rule builds a native executable from the supplied set of Rust source files and dependencies.
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this one_workspaces
: Internal implementation detail of Rust workspaces. This should not be set manually and will be replaced in favor of metadata in a future version of buck2.allow_cache_upload
: Whether to allow uploading the output of this rule to be uploaded to cache when the action is executed locally if the configuration allows (i.e. there is a cache configured and the client has permission to write to it).crate_root
: Set the name of the top-level source file for the crate, which can be used to override the default (seesrcs
).deps
: The set of dependencies of this rule. Currently, this supports rust_library and prebuilt_rust_library rules.edition
: Set the language edition to be used for this rule. Can be set to any edition the compiler supports (2018
right now). If unset it uses the compiler's default (2015
).env
: Set environment variables for this rule's invocations of rustc. The environment variable values may include macros which are expanded.features
: The set of features to be enabled for this rule.These are passed to
rustc
with--cfg feature="{feature}"
, and can be used in the code with#[cfg(feature = "{feature}")]
.link_style
: Determines whether to build and link this rule's dependencies statically or dynamically. Can be eitherstatic
,static_pic
orshared
.linker_flags
: The set of additional flags to pass to the linker.mapped_srcs
: Add source files along with a local path mapping. Rust is sensitive to the layout of source files, as the directory structure follows the module structure. However this is awkward if the source file is, for example, generated by another rule. In this case, you can set up a mapping from the actual source path to something that makes sense locally. For examplemapped_srcs = {":generate-module", "src/generated.rs" }
. These are added to the regularsrcs
, so a file should not be listed in both.named_deps
: Add crate dependencies and define a local name by which to use that dependency by. This allows a crate to have multiple dependencies with the same crate name. For example:named_deps = {"local_name", ":some_rust_crate" }
. The dependencies may also be non-Rust, but the alias is ignored. It has no effect on the symbols provided by a C/C++ library.rpath
: Set the "rpath" in the executable when using a shared link style.rustc_flags
: The set of additional compiler flags to pass torustc
.srcs
: The set of Rust source files to be compiled by this rule.One of the source files is the root module of the crate. By default this is
lib.rs
for libraries,main.rs
for executables, or the crate's name with.rs
appended. This can be overridden with thecrate_root
rule parameter.
Details
If you invoke a build with the check
flavor, then Buck will invoke rustc
to check the code (typecheck, produce warnings, etc), but won't generate an executable code.
When applied to binaries it produces no output; for libraries it produces metadata for
consumers of the library.
Note: Buck is currently tested with (and therefore supports) version 1.32.0 of Rust.
Examples:
For more examples, check out our integration tests.
rust_binary(
name='greet',
srcs=[
'greet.rs',
],
deps=[
':greeting',
],
)
rust_library(
name='greeting',
srcs=[
'greeting.rs',
],
deps=[
':join',
],
)
rust_library(
name='join',
srcs=[
'join.rs',
],
)
rust_library
def rust_library(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
_cxx_toolchain: str = _,
_exec_os_type: str = _,
_rust_toolchain: str = _,
_target_os_type: str = _,
_workspaces: list[str] = _,
buck2_compatibility: str = _,
clippy_configuration: None | str = _,
contacts: list[str] = _,
coverage: bool = _,
crate: None | str = _,
crate_dynamic: None | str = _,
crate_root: None | str = _,
default_host_platform: None | str = _,
default_platform: None | str = _,
deps: list[str] = _,
doc_deps: list[str] = _,
doc_env: dict[str, str] = _,
doc_link_style: None | str = _,
doc_linker_flags: list[str] = _,
doc_named_deps: list[(str, str)] | dict[str, str] = _,
doctests: None | bool = _,
edition: None | str = _,
env: dict[str, str] = _,
exported_linker_flags: list[str] = _,
exported_post_linker_flags: list[str] = _,
features: list[str] = _,
flagged_deps: list[(str, list[str])] = _,
incremental_build_mode: None | str = _,
incremental_enabled: bool = _,
labels: list[str] = _,
licenses: list[str] = _,
link_style: None | str = _,
linker_flags: list[str] = _,
mapped_srcs: dict[str, str] = _,
named_deps: list[(str, str)] | dict[str, str] = _,
preferred_linkage: str = _,
proc_macro: bool = _,
resources: list[str] | dict[str, str] = _,
rustc_flags: list[str] = _,
rustdoc_flags: list[str] = _,
soname: None | str = _,
srcs: list[str] = _,
supports_python_dlopen: None | bool = _,
version_universe: None | str = _
) -> None
A rust_library() rule builds a native library from the supplied set of Rust source files and dependencies.
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this one_workspaces
: Internal implementation detail of Rust workspaces. This should not be set manually and will be replaced in favor of metadata in a future version of buck2.crate_root
: Set the name of the top-level source file for the crate, which can be used to override the default (seesrcs
).deps
: The set of dependencies of this rule. Currently, this supports rust_library and prebuilt_rust_library rules.doc_deps
: The set of dependencies of this rule. Currently, this supports rust_library and prebuilt_rust_library rules.doc_env
: Set environment variables for this rule's invocations of rustc. The environment variable values may include macros which are expanded.doc_link_style
: Determines whether to build and link this rule's dependencies statically or dynamically. Can be eitherstatic
,static_pic
orshared
.doc_linker_flags
: The set of additional flags to pass to the linker.doc_named_deps
: Add crate dependencies and define a local name by which to use that dependency by. This allows a crate to have multiple dependencies with the same crate name. For example:named_deps = {"local_name", ":some_rust_crate" }
. The dependencies may also be non-Rust, but the alias is ignored. It has no effect on the symbols provided by a C/C++ library.edition
: Set the language edition to be used for this rule. Can be set to any edition the compiler supports (2018
right now). If unset it uses the compiler's default (2015
).env
: Set environment variables for this rule's invocations of rustc. The environment variable values may include macros which are expanded.exported_linker_flags
: A set of additional flag to pass before this item on the link line, even if this items is compiled to a DSO.exported_post_linker_flags
: A set of additional flag to pass after this item on the link line, even if this items is compiled to a DSO.features
: The set of features to be enabled for this rule.These are passed to
rustc
with--cfg feature="{feature}"
, and can be used in the code with#[cfg(feature = "{feature}")]
.link_style
: Determines whether to build and link this rule's dependencies statically or dynamically. Can be eitherstatic
,static_pic
orshared
.linker_flags
: The set of additional flags to pass to the linker.mapped_srcs
: Add source files along with a local path mapping. Rust is sensitive to the layout of source files, as the directory structure follows the module structure. However this is awkward if the source file is, for example, generated by another rule. In this case, you can set up a mapping from the actual source path to something that makes sense locally. For examplemapped_srcs = {":generate-module", "src/generated.rs" }
. These are added to the regularsrcs
, so a file should not be listed in both.named_deps
: Add crate dependencies and define a local name by which to use that dependency by. This allows a crate to have multiple dependencies with the same crate name. For example:named_deps = {"local_name", ":some_rust_crate" }
. The dependencies may also be non-Rust, but the alias is ignored. It has no effect on the symbols provided by a C/C++ library.rustc_flags
: The set of additional compiler flags to pass torustc
.soname
: Sets the soname ("shared object name") of any shared library produced from this rule. The default value is based on the full rule name. The macro$(ext)
will be replaced with a platform-appropriate extension. An argument can be provided, which is a library version. For examplesoname = 'libfoo.$(ext 2.3)'
will belibfoo.2.3.dylib
on Mac andlibfoo.so.2.3
on Linux.srcs
: The set of Rust source files to be compiled by this rule.One of the source files is the root module of the crate. By default this is
lib.rs
for libraries,main.rs
for executables, or the crate's name with.rs
appended. This can be overridden with thecrate_root
rule parameter.
Details
If you invoke a build with the check
flavor, then Buck will invoke rustc
to check the code (typecheck, produce warnings, etc), but won't generate an executable code.
When applied to binaries it produces no output; for libraries it produces metadata for
consumers of the library.
Note: Buck is currently tested with (and therefore supports) version 1.32.0 of Rust.
Examples:
For more examples, check out our integration tests.
rust_library(
name='greeting',
srcs=[
'greeting.rs',
],
deps=[
':join',
],
)
rust_test
def rust_test(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
_cxx_toolchain: str = _,
_exec_os_type: str = _,
_inject_test_env: str = _,
_remote_test_execution_toolchain: str = _,
_rust_toolchain: str = _,
_target_os_type: str = _,
_workspaces: list[str] = _,
anonymous_link_groups: bool = _,
auto_link_groups: bool = _,
buck2_compatibility: str = _,
clippy_configuration: None | str = _,
contacts: list[str] = _,
coverage: bool = _,
crate: None | str = _,
crate_root: None | str = _,
default_host_platform: None | str = _,
default_platform: None | str = _,
deps: list[str] = _,
edition: None | str = _,
enable_distributed_thinlto: bool = _,
env: dict[str, str] = _,
features: list[str] = _,
flagged_deps: list[(str, list[str])] = _,
framework: bool = _,
incremental_build_mode: None | str = _,
incremental_enabled: bool = _,
labels: list[str] = _,
licenses: list[str] = _,
link_group: None | str = _,
link_group_map: None | str | list[(str, list[(None | str | list[None | str], str, None | str | list[str], None | str)], None | dict[str, typing.Any])] = _,
link_group_min_binary_node_count: None | int = _,
link_style: None | str = _,
linker_flags: list[str] = _,
mapped_srcs: dict[str, str] = _,
named_deps: list[(str, str)] | dict[str, str] = _,
remote_execution: None | str | dict[str, None | bool | int | str | list[dict[str, str]] | dict[str, str]] = _,
remote_execution_action_key_providers: None | str = _,
resources: list[str] | dict[str, str] = _,
rpath: bool = _,
run_env: dict[str, str] = _,
rustc_flags: list[str] = _,
rustdoc_flags: list[str] = _,
srcs: list[str] = _,
version_universe: None | str = _
) -> None
A rust_test() rule builds a Rust test native executable from the supplied set of Rust source files and dependencies and runs this test.
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this one_workspaces
: Internal implementation detail of Rust workspaces. This should not be set manually and will be replaced in favor of metadata in a future version of buck2.crate_root
: Set the name of the top-level source file for the crate, which can be used to override the default (seesrcs
).deps
: The set of dependencies of this rule. Currently, this supports rust_library and prebuilt_rust_library rules.edition
: Set the language edition to be used for this rule. Can be set to any edition the compiler supports (2018
right now). If unset it uses the compiler's default (2015
).env
: Set environment variables for this rule's invocations of rustc and during execution of the tests. The environment variable values may include macros which are expanded.features
: The set of features to be enabled for this rule.These are passed to
rustc
with--cfg feature="{feature}"
, and can be used in the code with#[cfg(feature = "{feature}")]
.framework
: Use the standard test framework. If this is set to false, then the result is a normal executable which requires amain()
, etc. It is still expected to accept the same command-line parameters and produce the same output as the test framework.link_style
: Determines whether to build and link this rule's dependencies statically or dynamically. Can be eitherstatic
,static_pic
orshared
.linker_flags
: The set of additional flags to pass to the linker.mapped_srcs
: Add source files along with a local path mapping. Rust is sensitive to the layout of source files, as the directory structure follows the module structure. However this is awkward if the source file is, for example, generated by another rule. In this case, you can set up a mapping from the actual source path to something that makes sense locally. For examplemapped_srcs = {":generate-module", "src/generated.rs" }
. These are added to the regularsrcs
, so a file should not be listed in both.named_deps
: Add crate dependencies and define a local name by which to use that dependency by. This allows a crate to have multiple dependencies with the same crate name. For example:named_deps = {"local_name", ":some_rust_crate" }
. The dependencies may also be non-Rust, but the alias is ignored. It has no effect on the symbols provided by a C/C++ library.rpath
: Set the "rpath" in the executable when using a shared link style.run_env
: Set environment variables during test execution. The environment variable values may include macros which are expanded.rustc_flags
: The set of additional compiler flags to pass torustc
.srcs
: The set of Rust source files to be compiled by this rule.One of the source files is the root module of the crate. By default this is
lib.rs
for libraries,main.rs
for executables, or the crate's name with.rs
appended. This can be overridden with thecrate_root
rule parameter.
Details
Note: Buck is currently tested with (and therefore supports) version 1.32.0 of Rust.
Examples:
For more examples, check out our integration tests.
rust_test(
name='greet',
srcs=[
'greet.rs',
],
deps=[
':greeting',
],
)
rust_library(
name='greeting',
srcs=[
'greeting.rs',
],
deps=[
':join',
],
)
rust_library(
name='join',
srcs=[
'join.rs',
],
)
scala_library
def scala_library(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
_wip_java_plugin_arguments: dict[str, list[str]] = _,
abi_generation_mode: None | str = _,
annotation_processor_deps: list[str] = _,
annotation_processor_params: list[str] = _,
annotation_processors: list[str] = _,
buck2_compatibility: str = _,
contacts: list[str] = _,
default_host_platform: None | str = _,
deps: list[str] = _,
exported_deps: list[str] = _,
exported_provided_deps: list[str] = _,
extra_arguments: list[str] = _,
java_version: None | str = _,
javac: None | str = _,
labels: list[str] = _,
licenses: list[str] = _,
manifest_file: None | str = _,
maven_coords: None | str = _,
never_mark_as_unused_dependency: None | bool = _,
on_unused_dependencies: None | str = _,
plugins: list[str] = _,
proguard_config: None | str = _,
provided_deps: list[str] = _,
remove_classes: list[str] = _,
required_for_source_only_abi: bool = _,
resources: list[str] = _,
resources_root: None | str = _,
runtime_deps: list[str] = _,
source: None | str = _,
source_abi_verification_mode: None | str = _,
source_only_abi_deps: list[str] = _,
srcs: list[str] = _,
target: None | str = _
) -> None
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this one
scala_test
def scala_test(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
_wip_java_plugin_arguments: dict[str, list[str]] = _,
abi_generation_mode: None | str = _,
annotation_processor_deps: list[str] = _,
annotation_processor_params: list[str] = _,
annotation_processors: list[str] = _,
buck2_compatibility: str = _,
contacts: list[str] = _,
cxx_library_whitelist: list[str] = _,
default_cxx_platform: None | str = _,
default_host_platform: None | str = _,
deps: list[str] = _,
deps_query: None | str = _,
env: dict[str, str] = _,
exported_deps: list[str] = _,
exported_provided_deps: list[str] = _,
extra_arguments: list[str] = _,
fork_mode: str = _,
java_version: None | str = _,
javac: None | str = _,
labels: list[str] = _,
licenses: list[str] = _,
manifest_file: None | str = _,
maven_coords: None | str = _,
never_mark_as_unused_dependency: None | bool = _,
on_unused_dependencies: None | str = _,
plugins: list[str] = _,
proguard_config: None | str = _,
provided_deps: list[str] = _,
remove_classes: list[str] = _,
required_for_source_only_abi: bool = _,
resources: list[str] = _,
resources_root: None | str = _,
run_test_separately: bool = _,
runtime_deps: list[str] = _,
source: None | str = _,
source_abi_verification_mode: None | str = _,
source_only_abi_deps: list[str] = _,
srcs: list[str] = _,
std_err_log_level: None | int | str = _,
std_out_log_level: None | int | str = _,
target: None | str = _,
test_case_timeout_ms: None | int = _,
test_rule_timeout_ms: None | int = _,
test_type: None | str = _,
use_cxx_libraries: None | bool = _,
use_dependency_order_classpath: None | bool = _,
vm_args: list[str] = _
) -> None
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this one
scene_kit_assets
def scene_kit_assets(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
buck2_compatibility: str = _,
contacts: list[str] = _,
default_host_platform: None | str = _,
labels: list[str] = _,
licenses: list[str] = _,
path: str
) -> None
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this one
sh_binary
def sh_binary(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
_target_os_type: str = _,
append_script_extension: bool = _,
buck2_compatibility: str = _,
contacts: list[str] = _,
default_host_platform: None | str = _,
deps: list[str] = _,
labels: list[str] = _,
licenses: list[str] = _,
main: str,
resources: list[str] = _
) -> None
An sh_binary()
is used to execute a shell script.
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this oneappend_script_extension
: By default, sh_binary ensures that the script has an appropriate extension (e.g..sh
or.bat
), appending one itself if necessary. Setting this to False prevents that behavior and makes the caller responsible for ensuring an existing appropriate extension.main
: Either the path to the script (relative to the build file), or abuild target
. This file must be executable in order to be run.resources
: A list of files or build rules that this rule requires in order to run. These could be things such as random data files.When the script runs, the
$BUCK_DEFAULT_RUNTIME_RESOURCES
environment variable specifies the directory that contains these resources. This directory's location is determined entirely by Buck; the script should not assume the directory's location.The resources are also made available in a tree structure that mirrors their locations in the source and
buck-out
trees. The environment variable$BUCK_PROJECT_ROOT
specifies a directory that contains all the resources, laid out in their locations relative to the original buck project root.
Details
Examples:
This sh_binary() just cats a sample data file back at the user.
# $REPO/BUCK
sh_binary(
name = "script",
main = "script.sh",
resources = [
"data.dat",
],
)
# Sample data file with data we need at runtime
$ echo "I'm a datafile" > data.dat
# Create a simple script that prints out the resource
$ cat > script.sh
#!/bin/sh
cat $BUCK_DEFAULT_RUNTIME_RESOURCES/data.dat
# Make sure the script is executable
$ chmod u+x script.sh
# Run the script, and see that it prints out the resource we provided
$ buck run //:script
Jobs completed: 4. Time elapsed: 0.2s.
BUILD SUCCEEDED
I'm a datafile
sh_test
def sh_test(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
_inject_test_env: str = _,
_remote_test_execution_toolchain: str = _,
args: list[str] = _,
buck2_compatibility: str = _,
contacts: list[str] = _,
default_host_platform: None | str = _,
deps: list[str] = _,
env: dict[str, str] = _,
labels: list[str] = _,
licenses: list[str] = _,
list_args: None | list[str] = _,
list_env: None | dict[str, str] = _,
remote_execution: None | str | dict[str, None | bool | int | str | list[dict[str, str]] | dict[str, str]] = _,
remote_execution_action_key_providers: None | str = _,
resources: list[str] = _,
run_args: list[str] = _,
run_env: dict[str, str] = _,
run_test_separately: bool = _,
test: None | str = _,
test_rule_timeout_ms: None | int = _,
type: None | str = _
) -> None
A sh_test()
is a test rule that can pass results to the test runner by invoking a shell script.
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this oneargs
: The list of arguments to invoke this script with. These are literal values, and no shell interpolation is done.These can contain
string parameter macros
, for example, to give the location of a generated binary to the test script.env
: Environment variable overrides that should be used when running the script. The key is the variable name, and the value is its value.The values can contain
string parameter macros
such as the location of a generated binary to be used by the test script.test
: Either the path to the script (relative to the build file), or abuild target
. This file must be executable in order to be run.type
: If provided, this will be sent to any configured.buckconfig
Details
NOTE: This rule is not currently supported on Windows.
Examples:
This sh_test() fails if a string does not match a value.
# $REPO/BUCK
sh_test(
name = "script_pass",
test = "script.sh",
args = ["--pass"],
)
sh_test(
name = "script_fail",
test = "script.sh",
args = ["--fail"],
)
# Create a simple script that prints out the resource
$ cat > script.sh
#!/bin/sh
for arg in $@; do
if [ "$arg" == "--pass" ]; then
echo "Passed"
exit 0;
fi
done
echo "Failed"
exit 1
# Make sure the script is executable
$ chmod u+x script.sh
# Run the script, and see that one test passes, one fails
$ buck test //:script_pass //:script_fail
FAILURE script.sh sh_test
Building: finished in 0.0 sec (100%) 2/2 jobs, 0 updated
Total time: 0.0 sec
Testing: finished in 0.0 sec (1 PASS/1 FAIL)
RESULTS FOR //:script_fail //:script_pass
FAIL <100ms 0 Passed 0 Skipped 1 Failed //:script_fail
FAILURE script.sh sh_test
====STANDARD OUT====
Failed
PASS <100ms 1 Passed 0 Skipped 0 Failed //:script_pass
TESTS FAILED: 1 FAILURE
Failed target: //:script_fail
FAIL //:script_fail
supermodule_target_graph
def supermodule_target_graph(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
buck2_compatibility: str = _,
contacts: list[str] = _,
default_host_platform: None | str = _,
deps: list[str] = _,
label_pattern: None | str = _,
labels: list[str] = _,
licenses: list[str] = _,
on_duplicate_entry: str = _,
out: str = _
) -> None
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this one
swift_library
def swift_library(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
bridging_header: None | str = _,
buck2_compatibility: str = _,
compiler_flags: list[str] = _,
contacts: list[str] = _,
default_host_platform: None | str = _,
deps: list[str] = _,
enable_cxx_interop: bool = _,
frameworks: list[str] = _,
import_obj_c_forward_declarations: bool = _,
labels: list[str] = _,
libraries: list[str] = _,
licenses: list[str] = _,
module_name: None | str = _,
preferred_linkage: str = _,
sdk_modules: list[str] = _,
serialize_debugging_options: bool = _,
soname: None | str = _,
srcs: list[str] = _,
supported_platforms_regex: None | str = _,
target_sdk_version: None | str = _,
uses_explicit_modules: bool = _,
version: None | str = _
) -> None
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this one
swift_toolchain
def swift_toolchain(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
_internal_platform_path: None | str = _,
_internal_sdk_path: None | str = _,
_swiftc_wrapper: str = _,
architecture: None | str = _,
buck2_compatibility: str = _,
can_toolchain_emit_obj_c_header_textually: bool = _,
contacts: list[str] = _,
default_host_platform: None | str = _,
explicit_modules_uses_gmodules: bool = _,
labels: list[str] = _,
licenses: list[str] = _,
make_swift_comp_db: str = _,
make_swift_interface: str = _,
object_format: str = _,
placeholder_tool: None | str = _,
platform_path: None | str = _,
prefix_serialized_debug_info: bool = _,
resource_dir: None | str = _,
runtime_paths_for_bundling: list[str] = _,
runtime_paths_for_linking: list[str] = _,
runtime_run_paths: list[str] = _,
sdk_dependencies_path: None | str = _,
sdk_modules: list[str] = _,
sdk_path: None | str = _,
static_runtime_paths: list[str] = _,
supports_cxx_interop_requirement_at_import: bool = _,
supports_relative_resource_dir: bool = _,
supports_swift_cxx_interoperability_mode: bool = _,
supports_swift_importing_obj_c_forward_declarations: bool = _,
swift_ide_test_tool: None | str = _,
swift_stdlib_tool: str,
swift_stdlib_tool_flags: list[str] = _,
swiftc: str,
swiftc_flags: list[str] = _
) -> None
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this one
test_suite
def test_suite(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
buck2_compatibility: str = _,
contacts: list[str] = _,
default_host_platform: None | str = _,
labels: list[str] = _,
licenses: list[str] = _,
test_deps: list[str] = _
) -> None
A test_suite()
is used to create a grouping of tests that should all be run by just testing this rule.
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this one
Details
This rule can then be given to buck test
, and all tests that it depends on will be invoked.
Note that the test_suite() target is not tested itself, it just tells buck to run other
tests. It will not show up in calls to the external runner nor in the normal test output.
Examples:
This test_suite() sets up two different sets of tests to run, 'all' tests and 'slow' tests. Note that all_tests
can depend on slow_tests
, and all three tests are run.
# instrumentation_tests/BUCK:
sh_test(
name = "instrumentation_tests",
test = "instrumentation_tests.sh",
visibility = ["PUBLIC"],
)
# integration_tests/BUCK:
sh_test(
name = "integration_tests",
test = "integration_tests.sh",
visibility = ["PUBLIC"],
)
# unit_tests/BUCK:
sh_test(
name = "unit_tests",
test = "unit_tests.sh",
visibility = ["PUBLIC"],
)
# BUCK:
test_suite(
name = "slow_tests",
tests = [
"//instrumentation_tests:instrumentation_tests",
"//integration_tests:integration_tests",
],
)
test_suite(
name = "all_tests",
tests = [
":slow_tests",
"//unit_tests:unit_tests",
],
)
Yields output like this when run:
$ buck test //:slow_tests
...
RESULTS FOR //instrumentation_tests:instrumentation_tests //integration_tests:integration_tests
PASS <100ms 1 Passed 0 Skipped 0 Failed //instrumentation_tests:instrumentation_tests
PASS <100ms 1 Passed 0 Skipped 0 Failed //integration_tests:integration_tests
TESTS PASSED
...
$ buck test //:all_tests
RESULTS FOR //instrumentation_tests:instrumentation_tests //integration_tests:integration_tests //unit_tests:unit_tests
PASS <100ms 1 Passed 0 Skipped 0 Failed //instrumentation_tests:instrumentation_tests
PASS <100ms 1 Passed 0 Skipped 0 Failed //integration_tests:integration_tests
PASS <100ms 1 Passed 0 Skipped 0 Failed //unit_tests:unit_tests
TESTS PASSED
toolchain_alias
def toolchain_alias(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
actual: str,
buck2_compatibility: str = _
) -> None
toolchain_alias acts like alias but for toolchain rules.
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this oneactual
: The actual toolchain that is being aliased. This should be a toolchain rule.
Details
The toolchain_alias itself is a toolchain rule and the actual
argument is
expected to be a toolchain_rule as well.
versioned_alias
def versioned_alias(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
buck2_compatibility: str = _,
contacts: list[str] = _,
default_host_platform: None | str = _,
labels: list[str] = _,
licenses: list[str] = _,
versions: dict[str, str] = _
) -> None
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this one
windows_resource
def windows_resource(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
_cxx_toolchain: str = _,
buck2_compatibility: str = _,
header_namespace: None | str = _,
headers: list[str] | dict[str, str] = _,
include_directories: list[str] = _,
labels: list[str] = _,
platform_headers: list[(str, list[str] | dict[str, str])] = _,
raw_headers: list[str] = _,
srcs: list[str | (str, list[str])] = _
) -> None
A windows_resource()
rule specifies a set of Window's Resource File (.rc) that are compiled into object files.
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this oneheader_namespace
: A path prefix when including headers of this target. Defaults to the path from the root of the repository to the directory where this target is defined. Can contain forward slashes (/
), but cannot start with one. Seeheaders
for more information.headers
: The set of header files that are made available for inclusion to the source files in this target. These should be specified as either a list of header files or a dictionary of header names to header files. The header name can contain forward slashes (/
). The headers can be included with#include "$HEADER_NAMESPACE/$HEADER_NAME"
or#include <$HEADER_NAMESPACE/$HEADER_NAME>
, where$HEADER_NAMESPACE
is the value of the target'sheader_namespace
attribute, and$HEADER_NAME
is the header name if specified, and the filename of the header file otherwise. Seeheader_namespace
for more information.include_directories
: A list of include directories (withraw_headers
) to be added to the compile command for compiling this target (via-I
). An include directory is relative to the current package.platform_headers
: Platform specific header files. These should be specified as a list of pairs where the first element is an un-anchored regex (in java.util.regex.Pattern syntax) against which the platform name is matched, and the second element is either a list of header files or a dictionary of header names to header files that will be made available for inclusion to the source files in the target if the platform matches the regex. Seeheaders
for more information.raw_headers
: The set of header files that can be used for inclusion to the source files in the target and all targets that transitively depend on it. Buck doesn't add raw headers to the search path of a compiler/preprocessor automatically.include_directories
andpublic_include_directories
are the recommended way to add raw headers to the search path (they will be added via-I
).compiler_flags
,preprocessor_flags
andexported_preprocessor_flags
can also be used to add such raw headers to the search path if inclusion via-isystem
or-iquote
is needed.raw_headers
cannot be used together withheaders
orexported_headers
in the same target.srcs
: The set of C, C++, Objective-C, Objective-C++, or assembly source files to be preprocessed, compiled, and assembled by this rule. We determine which stages to run on each input source based on its file extension. See the GCC documentation for more detail on how file extensions are interpreted. Each element can be either a string specifying a source file (e.g.''
) or a tuple of a string specifying a source file and a list of compilation flags (e.g.('', ['-Wall', '-Werror'])
). In the latter case the specified flags will be used in addition to the rule's other flags when preprocessing and compiling that file (if applicable).
Details
The files are compiled into .res files using rc.exe and then compiled into object files using cvtres.exe. They are not part of cxx_library because Microsoft's linker ignores the resources unless they are specified as an object file, meaning including them in a possibly static library is unintuitive.
Examples:
# A rule that includes a single .rc file and compiles it into an object file.
windows_resource(
name = "resources",
srcs = [
"resources.rc",
],
)
# A rule that links against the above windows_resource rule.
cxx_binary(
name = "app",
srcs = [
"main.cpp",
],
deps = [
":resources"
],
)
worker_tool
def worker_tool(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
_worker_tool_runner: str = _,
args: str | list[str] = _,
buck2_compatibility: str = _,
contacts: list[str] = _,
default_host_platform: None | str = _,
env: dict[str, str] = _,
exe: None | str = _,
labels: list[str] = _,
licenses: list[str] = _,
max_workers: None | int = _,
max_workers_per_thread_percent: None | int = _,
persistent: None | bool = _
) -> None
Some external tools have high startup costs. To amortize those costs over the whole build rather than paying them for each rule invocation, use the worker_tool()
rule in conjunction with genrule()
. Buck then starts the external tool once and reuses it by communicating with it over stdin
and stdout
using a simple JSON protocol.
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this oneargs
: A string of args that is passed to the executable represented byexe
on initial startup.env
: A map of environment variables that is passed to the executable represented byexe
on initial startup.exe
: Abuild target
for a rule that outputs an executable, such as ansh_binary()
. Buck runs this executable only once per build.max_workers
: The maximum number of workers of this type that Buck starts. Use-1
to allow the creation of as many workers as necessary.max_workers_per_thread_percent
: The maximum ratio of workers of this type that Buck starts per thread, specified as a positive integer percentage (1-100). Must be greater than or equal to1
and less than or equal to100
. Only one ofmax_workers
andmax_workers_per_thread_percent
may be specified.persistent
: If set to true, Buck does not restart the tool unless the tool itself changes. This means the tool persists across multiple Buck commands without being shut down and may see the same rule being built more than once. Be careful not to use this setting with tools that don't expect to process the same input—with different contents—twice!
Details
A worker_tool
rule can be referenced in the cmd
parameter of
a genrule
by using the macro:
$(exe //path/to:target)
Examples:
Consider the following build rules
:
#
# Buck
#
worker_tool(
name = 'ExternalToolWorker',
exe = ':ExternalTool',
args = '--arg1 --arg2'
)
sh_binary(
name = 'ExternalTool',
main = 'external_tool.sh',
)
genrule(
name = 'TransformA',
out = 'OutputA.txt',
cmd = '$(exe :ExternalToolWorker) argA',
)
genrule(
name = 'TransformB',
out = 'OutputB.txt',
cmd = '$(exe :ExternalToolWorker) argB',
)
genrule(
name = 'TransformC',
out = 'OutputC.txt',
cmd = '$(exe :ExternalToolWorker) argC',
)
When doing a buck build
on all three of the above genrules
, Buck
first creates the worker process by invoking:
./external_tool.sh --arg1 --arg2
Buck then communicates with this process using JSON over stdin
,
starting with a handshake:
[
{
"id": 0,
"type": "handshake",
"protocol_version": "0",
"capabilities": []
}
Buck then waits for the tool to reply on stdout
:
[
{
"id": 0,
"type": "handshake",
"protocol_version": "0",
"capabilities": []
}
Then, when building the first genrule
, Buck writes to stdin
:
,{
"id": 1,
"type": "command",
"args_path": "/tmp/1.args",
"stdout_path": "/tmp/1.out",
"stderr_path": "/tmp/1.err"
}
The file /tmp/1.args
contains argA
. The tool should
perform the necessary work for this job and then write the job's output to the files
supplied by Buck—in this case, /tmp/1.out
and /tmp/1.err
.
Once the job is done, the tool should reply to Buck on stdout
with:
,{
"id": 1,
"type": "result",
"exit_code": 0
}
Once Buck hears back from the first genrule's job, it submits the second genrule's job in the
same fashion and awaits the response. When the build is all finished,
Buck closes the JSON by writing to stdin
:
]
which signals the tool that it should exit after replying on stdout
with:
]
In this example, Buck is guaranteed to invoke
./external_tool.sh --arg1 --arg2
only once during the build. The three jobs corresponding to the three genrules are submitted synchronously to the single worker process.
Note that the id
values in the messages are not necessarily increasing or sequential,
but they do have to match between the request message and the response message of a given job as
well as in the initial handshake.
If the tool receives a message type it cannot interpret it should answer with:
{
"id": <n>,
"type": "error",
"exit_code": 1
}
If the tool receives a message type it can interpret, but the other attributes of the message are in an inconsistent state, it should answer with:
{
"id": <n>,
"type": "error",
"exit_code": 2
}
zip_file
def zip_file(
*,
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] = _,
_apple_platforms: dict[str, str] = _,
_zip_file_toolchain: str = _,
buck2_compatibility: str = _,
contacts: list[str] = _,
default_host_platform: None | str = _,
entries_to_exclude: list[str] = _,
labels: list[str] = _,
licenses: list[str] = _,
on_duplicate_entry: str = _,
out: str = _,
srcs: list[str] = _,
zip_srcs: list[str] = _
) -> None
A zip_file()
allows builds to create basic zip files in a platform-agnostic way.
Parameters
name
: name of the targetdefault_target_platform
: specifies the default target platform, used when no platforms are specified on the command linetarget_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationcompatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with a configurationexec_compatible_with
: a list of constraints that are required to be satisfied for this target to be compatible with an execution platformvisibility
: a list of visibility patterns restricting what targets can depend on this onewithin_view
: a list of visibility patterns restricting what this target can depend onmetadata
: a key-value map of metadata associated with this targettests
: a list of targets that provide tests for this oneentries_to_exclude
: List of regex expressions that describe entries that should not be included in the output zip file.The regexes must be defined using
java.util.regex.Pattern
syntax.on_duplicate_entry
: Action performed when Buck detects that zip_file input contains multiple entries with the same name.The valid values are:
overwrite
(default): the last entry overwrites all previous entries with the same name.append
: all entries are added to the output file.fail
: fail the build when duplicate entries are present.
out
: The name of the zip file that should be generated. This allows builds to use a meaningful target name coupled with a meaningful zip file name. The default value takes the rule'sname
and appends.zip
.srcs
: The set of files to include in the zip.Each
src
will be added to the zip as follows:- If the
src
is the output of another rule, the output will be included using just the output's file name. - If the
src
is a file relative to the rule's declaration, it will be included in the zip with its relative file name.
- If the
zip_srcs
: The set of zip files whose content to include in the output zip file.Note that the order of files in
zip_srcs
matters because the same zip entry can be included from multiple files. See theon_duplicate_entry
argument to learn how to control the behavior when there are multiple entries with the same name.The entries from
zip_srcs
are added before files fromsrcs
.
Details
Examples:
This example will create a simple zip file.
zip_file(
# The output will be "example.zip"
name = 'example',
srcs =
# These files will be found in the zip under "dir/"
glob(['dir/**/*']) +
[
# Imagine this generates the output
# "buck-out/gen/foo/hello.txt". This output will
# be found in the zip at "hello.txt"
'//some/other:target',
],
zip_srcs = [
# The contents of this zip will be added to the generated zip.
'amazing-library-1.0-sources.zip',
],
entries_to_exclude = [
"com/example/amazinglibrary/Source1.java",
],
)
If you were to examine the generated zip, the contents would look
something like (assuming the output of
"//some/other:target
" was a file who's path ended with
hello.txt
, the "dir
" glob found two files,
and "amazing-library-1.0-sources.zip
" contained two Java
source files):
dir/file1.txt
dir/subdir/file2.txt
hello.txt
com/example/amazinglibrary/Source2.java