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: opaque_metadata = _,
tests: list[str] = _,
_apple_platforms: dict[str, str] = _,
actual: 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: opaque_metadata = _,
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 = _,
abi_generation_mode: None | str = _,
annotation_processing_tool: None | str = _,
annotation_processor_deps: list[str] = _,
annotation_processor_params: list[str] = _,
annotation_processors: list[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] = _,
deps_query: None | str = _,
enable_relinker: bool = _,
exported_deps: list[str] = _,
exported_provided_deps: list[str] = _,
extra_arguments: list[str] = _,
extra_kotlinc_arguments: list[str] = _,
extra_non_source_only_abi_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_localized_symbols: None | list[str] = _,
native_library_merge_map: None | dict[str, list[str]] = _,
native_library_merge_sequence: None | list[(str, list[str])] = _,
native_library_merge_sequence_blocklist: None | list[str] = _,
never_mark_as_unused_dependency: None | bool = _,
on_unused_dependencies: None | str = _,
package_asset_libraries: bool = _,
plugins: list[str] = _,
proguard_config: None | str = _,
provided_deps: list[str] = _,
provided_deps_query: None | 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] = _,
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 theBuildConfigclass files in the final .aar file. Needs to be set toTrueif any build_config_values are specified. This is normally only needed if the build tool that is consuming the .aar file does not generateBuildConfigclasses. Note: the AAR format does not specify a way to pass defaults that should be injected into the finalBuildConfigclass, 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 aandroid\_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: opaque_metadata = _,
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]] = _,
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: opaque_metadata = _,
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] = _,
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] = _,
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_localized_symbols: None | list[str] = _,
native_library_merge_map: None | dict[str, list[str]] = _,
native_library_merge_sequence: None | list[(str, list[str])] = _,
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] = _,
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_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_split_dex: bool = _,
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: opaque_metadata = _,
tests: list[str] = _,
_android_toolchain: str = _,
_apple_platforms: dict[str, str] = _,
_build_only_native_code: bool = _,
_is_building_android_binary: bool = _,
_java_toolchain: 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.javafile. 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.javafile. 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.javafile. 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.DEBUGfield will correspond to that of thepackage_typeargument 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: opaque_metadata = _,
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 = _,
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] = _,
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] = _,
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_localized_symbols: None | list[str] = _,
native_library_merge_map: None | dict[str, list[str]] = _,
native_library_merge_sequence: None | list[(str, list[str])] = _,
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] = _,
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_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_split_dex: bool = _,
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: opaque_metadata = _,
tests: list[str] = _,
_android_toolchain: str = _,
_apple_platforms: dict[str, str] = _,
_dex_toolchain: 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,
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 = _,
labels: list[str] = _,
licenses: list[str] = _,
manifest: None | str = _,
manifest_skeleton: None | str = _,
min_sdk_version: None | int = _,
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 a 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: opaque_metadata = _,
tests: list[str] = _,
_android_toolchain: str = _,
_apple_platforms: dict[str, str] = _,
_exec_os_type: str = _,
_inject_test_env: str = _,
_java_toolchain: str = _,
apk: str,
contacts: list[str] = _,
default_host_platform: None | str = _,
env: dict[str, str] = _,
labels: list[str] = _,
licenses: list[str] = _,
test_rule_timeout_ms: None | int = _
) -> None
A 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().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.,smokeorfast). A label can be used to filter or include a specific test rule when executingbuck testtest_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_timeoutif 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: opaque_metadata = _,
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 = _,
_is_building_android_binary: bool = _,
_java_toolchain: str = _,
_kotlin_toolchain: 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] = _,
contacts: list[str] = _,
default_host_platform: None | str = _,
deps: list[str] = _,
deps_query: None | str = _,
exported_deps: list[str] = _,
exported_provided_deps: list[str] = _,
extra_arguments: list[str] = _,
extra_kotlinc_arguments: list[str] = _,
extra_non_source_only_abi_kotlinc_arguments: list[str] = _,
friend_paths: 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] = _,
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 = _
) -> 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_libraryrules) that are used to generate the classpath required to compile thisandroid_library.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:attrfilterdepsexceptintersectfilterkindsetunion
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
literal set(//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.
exported_deps: Other rules that depend on this rule will also include itsexported_depsin 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_jarrules as a single target for callers to depend on. Targets inexported_depsare implicitly included in thedepsof this rule, so they don't need to be repeated there.exported_provided_deps: This is a combination ofprovided_depsandexported_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.javac: Specifies the Java compiler program to use for this rule. The value is a source path (e.g., //foo/bar:bar). Overrides the value in "javac" in the "tools" section of.buckconfig.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 aandroid\_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_depsinclude the JEE servlet APIs. When this rule is included in a , theprovided_depswill 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$declaredare 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 generationof 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.classfiles. 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 about
source-only ABI generation.
srcs: The set of.javafiles 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: opaque_metadata = _,
tests: list[str] = _,
_android_toolchain: str = _,
_apple_platforms: dict[str, 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 targetor 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 targetin 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: opaque_metadata = _,
tests: list[str] = _,
_apple_platforms: dict[str, str] = _,
base_platform: 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: opaque_metadata = _,
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,
contacts: list[str] = _,
default_host_platform: None | str = _,
deps: list[str] = _,
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.aarfile. This may also be a build target to a rule (such as agenrule()) whose output is an.aarfile.javadoc_url: URL to the Javadoc for the.classfiles in theaar.source_jar: Path to a JAR file that contains the.javafiles to create the.classin theaar. This is frequently provided for debugging purposes.use_system_library_loader: If this.aarfile contains native prebuilt.solibraries 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 toTruecauses all of these optimizations to skip the prebuilt.sofiles originating from this.aarfile. The.sofiles 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: opaque_metadata = _,
tests: list[str] = _,
_android_toolchain: str = _,
_apple_platforms: dict[str, str] = _,
_build_only_native_code: bool = _,
allowlisted_locales: None | list[str] = _,
assets: None | str | dict[str, 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_resourcerules to include via-Swhen 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 aandroid\_manifest()target.package: Java package for theR.javafile 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: opaque_metadata = _,
tests: list[str] = _,
_android_toolchain: str = _,
_apple_platforms: dict[str, str] = _,
_build_only_native_code: bool = _,
_genrule_toolchain: str = _,
aab: None | str = _,
apk: None | str = _,
bash: None | 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 = _,
is_cacheable: 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 = _,
remote: None | bool = _,
srcs: list[str] | dict[str, str] = _,
type: str = _
) -> 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 oneapk: The inputandroid_binary()rule. The path to the APK can be accessed with the$APKshell variable.bash: A platform-specific version of the shell command parametercmd. It runs on Linux and UNIX systems—including OSX—on whichbashis installed. It has a higher priority thancmd. Thebashargument is run with/usr/bin/env bash -c. It has access to the same set of macros and variables as thecmdargument.cmd: The shell command to run to generate the output file. It is the fallback forbashandcmd_exearguments. 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 the environment_expansion_separator argument
where each element of srcs will be translated
into an absolute path.
${SRCDIR}
The absolute 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
the out argument if not usingÂ
named outputs
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.
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.
String parameter macros
It is also possible to expand references to other rules within the
cmd, using builtin string parameter macros
.
All build rules expanded in the command are automatically considered
to be dependencies of the genrule().
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 the resources argument of
that sh_binary rule. These are the same targets that you
pass to the string parameter macros.
$(classpath //path/to:target)
Expands to the transitive classpath of the specified build rule, provided that the rule has a Java classpath. If the rule does not have (or contribute to) a classpath, then an exception is thrown and the build breaks.
$(exe //path/to:target)
Expands a build rule that results in an executable to the
commands necessary to run that executable. For example,
a java_binary() might expand to a call
to java -jar path/to/target.jar . Files that are
executable (perhaps generated by a genrule())
are also expanded. If the build rule does not generate an
executable output, then an exception is thrown and the build
breaks.
$(location //path/to:target)
Expands to the location of the output of the specified build rule. This means that you can refer to the output without needing to be aware of how Buck is storing data on the disk mid-build.
$(maven_coords //path/to:target)
Expands to the Maven coordinates for the specified build rule. This allows you to access the Maven coordinates for Maven-aware build rules. The format of the expansion is:
cmd_exe: A platform-specific version of the shell command parametercmd. It runs on Windows and has a higher priority thancmd. Thecmd_exeargument is run withcmd.exe /v:off /c. It has access to the same set of macros and variables as thecmdargument.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: This argument only exists for historical reasons and it does not have any effect. It will be deprecated and removed 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 theSRCDIRenvironment 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.
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: opaque_metadata = _,
tests: list[str] = _,
_apple_platforms: dict[str, str] = _,
app_icon: None | str = _,
contacts: list[str] = _,
default_host_platform: None | str = _,
dirs: list[str] = _,
labels: list[str] = _,
launch_image: None | str = _,
licenses: list[str] = _
) -> 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.appiconsetcontaining 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.launchimagecontaining 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: opaque_metadata = _,
tests: list[str] = _,
_apple_platforms: dict[str, str] = _,
_apple_toolchain: str = _,
_apple_tools: str = _,
_apple_xctoolchain: str = _,
_apple_xctoolchain_bundle_id: str = _,
_stripped_default: bool = _,
binary_linker_flags: list[str] = _,
bridging_header: None | str = _,
can_be_asset: None | bool = _,
compiler_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] = _,
devirt_enabled: bool = _,
diagnostics: dict[str, str] = _,
enable_cxx_interop: bool = _,
enable_distributed_thinlto: 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 = _,
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, 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] = _,
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 = _,
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_compiler_flags: list[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 = _,
xcode_private_headers_symlinks: None | bool = _,
xcode_public_headers_symlinks: None | bool = _
) -> 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 onecompiler_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 likeiphonesimulatorrequire 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_PREFIXis the value of the target'sheader_path_prefixattribute, and$HEADER_NAMEis the filename of the header file. If a dictionary is specified, each header can be imported with#import "$HEADER_NAME", where$HEADER_NAMEis the key corresponding to this file. In this case, theheader_path_prefixattribute 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$SDKROOTor$PLATFORM_DIRto 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 using
apple_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.h
Defaults to the short name of the target. Can contain forward slashes (/), but
cannot start with one. See headers 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_PREFIXis the value of the target'sheader_path_prefixattribute, and$HEADER_NAMEis the filename of the header file. If a dictionary is specified, each header can be imported with#import "$HEADER_NAME", where$HEADER_NAMEis the key corresponding to this file. In this case, theheader_path_prefixattribute 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_picorshared.linker_extra_outputs: Declares extra outputs that the linker emits. These identifiers can be used in$(output ...)macros inlinker_flagsto 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_flagsfor 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.Patternsyntax. 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. Seesrcsfor 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: opaque_metadata = _,
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 = _,
_bundling_path_conflicts_check_enabled: bool = _,
_codesign_entitlements: None | str = _,
_codesign_type: None | str = _,
_compile_resources_locally_override: None | bool = _,
_dry_run_code_signing: bool = _,
_fast_adhoc_signing_enabled: bool = _,
_incremental_bundling_enabled: bool = _,
_info_plist_identify_build_system_default: bool = _,
_profile_bundling_enabled: bool = _,
_provisioning_profiles: str = _,
_resource_bundle: None | str = _,
_use_entitlements_when_adhoc_code_signing: None | bool = _,
asset_catalogs_compilation_options: dict[str, typing.Any] = _,
binary: None | str = _,
codesign_flags: list[str] = _,
codesign_identity: None | str = _,
contacts: list[str] = _,
default_host_platform: None | str = _,
default_platform: None | str = _,
deps: list[str] = _,
extension: str,
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] = _,
platform_binary: None | list[(str, str)] = _,
product_name: 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 = _,
try_skip_code_signing: None | bool = _,
universal: None | bool = _,
use_entitlements_when_adhoc_code_signing: 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#watchto the target specification. Buck will automatically substitute the appropriate platform flavor (eitherwatchsimulatororwatchos) 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.plistfile that will be placed in the bundle. The specified file will be processed by substituting variable names with their values (seeinfo_plist_substitutionsfor 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.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: opaque_metadata = _,
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 = _,
_stripped_default: bool = _,
bridging_header: None | str = _,
can_be_asset: None | bool = _,
compiler_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] = _,
devirt_enabled: bool = _,
diagnostics: dict[str, str] = _,
enable_cxx_interop: 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_namespace: None | str = _,
header_path_prefix: None | str = _,
headers: list[str] | dict[str, str] = _,
headers_as_raw_headers_mode: None | str = _,
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, 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] = _,
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 = _,
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_compiler_flags: list[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 = _,
xcode_private_headers_symlinks: None | bool = _,
xcode_public_headers_symlinks: None | bool = _
) -> 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 onecompiler_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_PREFIXis the value of the target'sheader_path_prefixattribute, and$HEADER_NAMEis the filename of the header file. If a dictionary is specified, each header can be imported with#import "$HEADER_NAME", where$HEADER_NAMEis the key corresponding to this file. In this case, theheader_path_prefixattribute 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.Patternsyntax. 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$SDKROOTor$PLATFORM_DIRto 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. Seeheadersfor more information.header_path_prefix: A path prefix when including headers of this target. For example, headers from a library defined using
apple_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.h
Defaults to the short name of the target. Can contain forward slashes (/), but
cannot start with one. See headers 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_PREFIXis the value of the target'sheader_path_prefixattribute, and$HEADER_NAMEis the filename of the header file. If a dictionary is specified, each header can be imported with#import "$HEADER_NAME", where$HEADER_NAMEis the key corresponding to this file. In this case, theheader_path_prefixattribute 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_picorshared.linker_extra_outputs: Declares extra outputs that the linker emits. These identifiers can be used in$(output ...)macros inlinker_flagsto 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_flagsfor 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. Seesrcsfor 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: opaque_metadata = _,
tests: list[str] = _,
_apple_platforms: dict[str, str] = _,
_apple_toolchain: str = _,
_apple_tools: str = _,
_ipa_compression_level: str,
bundle: str,
contacts: list[str] = _,
default_host_platform: None | str = _,
default_platform: None | str = _,
labels: list[str] = _,
licenses: list[str] = _,
need_android_tools: bool = _,
validator: None | 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: opaque_metadata = _,
tests: list[str] = _,
_apple_platforms: dict[str, 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] = _,
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.lprojsuffix. (e.g.Base.lproj,en.lproj).resources_from_deps: Set of build targets whose transitiveapple_resources should be considered as part of the current resource when collecting resources for bundles.
Usually, an apple_bundle collects all apple_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_NAMEis 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: opaque_metadata = _,
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 = _,
_bundling_path_conflicts_check_enabled: bool = _,
_codesign_type: None | str = _,
_compile_resources_locally_override: None | bool = _,
_dry_run_code_signing: bool = _,
_fast_adhoc_signing_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 = _,
_use_entitlements_when_adhoc_code_signing: None | bool = _,
asset_catalogs_compilation_options: dict[str, typing.Any] = _,
binary: None | str = _,
bridging_header: None | str = _,
can_be_asset: None | bool = _,
codesign_flags: list[str] = _,
codesign_identity: None | str = _,
compiler_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] = _,
destination_specifier: dict[str, str] = _,
devirt_enabled: bool = _,
diagnostics: dict[str, str] = _,
enable_cxx_interop: 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] = _,
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 = _,
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 | list[(str, list[(str, str, None | str)])] = _,
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] = _,
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 = _,
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 = _,
stripped: bool = _,
supported_platforms_regex: None | str = _,
supports_merged_linking: None | bool = _,
swift_compiler_flags: list[str] = _,
swift_version: None | str = _,
target_sdk_version: None | str = _,
test_host_app: 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 = _,
xcode_private_headers_symlinks: None | bool = _,
xcode_product_type: None | str = _,
xcode_public_headers_symlinks: None | bool = _
) -> 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 onecompiler_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$SDKROOTor$PLATFORM_DIRto 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 using
apple_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.h
Defaults to the short name of the target. Can contain forward slashes (/), but
cannot start with one. See headers 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_PREFIXis the value of the target'sheader_path_prefixattribute, and$HEADER_NAMEis the filename of the header file. If a dictionary is specified, each header can be imported with#import "$HEADER_NAME", where$HEADER_NAMEis the key corresponding to this file. In this case, theheader_path_prefixattribute is ignored. In either case, quotes in the import statements can be replaced with angle brackets.info_plist: A path to anInfo.plistfile that will be placed in the bundle. The specified file will be processed by substituting variable names with their values (seeinfo_plist_substitutionsfor 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.,smokeorfast). A label can be used to filter or include a specific test rule when executingbuck testlink_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_flagsfor 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. Seesrcsfor 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).
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: opaque_metadata = _,
tests: list[str] = _,
_apple_platforms: dict[str, str] = _,
_internal_platform_path: None | str = _,
_internal_sdk_path: None | str = _,
actool: str,
architecture: 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,
min_version: None | str = _,
momc: str,
odrcov: 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: opaque_metadata = _,
tests: list[str] = _,
_apple_platforms: dict[str, str] = _,
apple_toolchains: list[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: opaque_metadata = _,
tests: list[str] = _,
_apple_platforms: dict[str, str] = _,
_apple_toolchain: str = _,
_apple_tools: str = _,
executable: str,
labels: list[str],
split_arch_dsym: bool = _,
universal: None | 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: opaque_metadata = _,
tests: list[str] = _,
_apple_platforms: dict[str, str] = _,
_cxx_toolchain: str = _,
_go_toolchain: str = _,
cgo_compiler_flags: list[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] = _,
deps_query: None | str = _,
devirt_enabled: bool = _,
embedcfg: None | str = _,
executable_name: None | str = _,
exported_deps: list[str] = _,
fat_lto: bool = _,
focused_list_target: None | str = _,
frameworks: list[str] = _,
go_assembler_flags: list[str] = _,
go_compiler_flags: list[str] = _,
go_srcs: 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_group: None | str = _,
link_group_map: None | list[(str, list[(str, str, None | str)])] = _,
link_style: None | str = _,
linker_extra_outputs: list[str] = _,
linker_flags: list[str] = _,
package_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 = _,
prefix_header: None | str = _,
preprocessor_flags: list[str] = _,
raw_headers: list[str] = _,
srcs: list[str | (str, list[str])] = _,
thin_lto: bool = _,
version_universe: None | str = _,
weak_framework_names: 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 onecgo_compiler_flags: The set of additional compiler flags to pass togo tool cgo.compiler_flags: Flags to use when compiling any of the above sources (which require compilation).go_assembler_flags: The set of additional assembler flags to pass togo tool asm.go_compiler_flags: The set of additional compiler flags to pass togo tool compile.go_srcs: The set of source files to be compiled by this rule. Go (.go) files are compiled with the Go compiler. In contrast to thesrcsargument, these files cannot haveimport "C"declared.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_NAMESPACEis the value of the target'sheader_namespaceattribute, and$HEADER_NAMEis the header name if specified, and the filename of the header file otherwise. Seeheader_namespacefor more information.link_style: Determines whether to build and link this rule's dependencies statically or dynamically. Can be eitherstatic,static_picorshared.linker_extra_outputs: Declares extra outputs that the linker emits. These identifiers can be used in$(output ...)macros inlinker_flagsto 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.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")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_flagsfor 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.Patternsyntax. 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_flagsfor 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_directoriesandpublic_include_directoriesare the recommended way to add raw headers to the search path (they will be added via-I).compiler_flags,preprocessor_flagsandexported_preprocessor_flagscan also be used to add such raw headers to the search path if inclusion via-isystemor-iquoteis needed.raw_headerscannot be used together withheadersorexported_headersin the same target.srcs: The set of source files to be compiled by this rule. .go files will be compiled with the CGO compiler. Each file needs to haveimport "C"declared.
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: opaque_metadata = _,
tests: list[str] = _,
_apple_platforms: dict[str, str] = _,
_exec_os_type: str = _,
_target_os_type: str = _,
args: list[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 byexeat 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 byexeon startup. Environment variables support the same macros as arguments.exe: Abuild targetfor a rule that outputs an executable, such as ansh\_binary().platform_exe: A mapping from platforms tobuild target. enables you to overrideexeper host platform.
If present, exe will be used as a fallback on host platforms that are not
specified in platform_exe.
It is possible to omit exe when providing platform_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 :
FREEBSDLINUXMACOSWINDOWS
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: opaque_metadata = _,
tests: list[str] = _,
_apple_platforms: dict[str, str] = _,
constraint_values: list[str] = _,
values: dict[str, str] = _
) -> None