Skip to main content

Rules

These rules are available as standard in Buck2.

alias​

def alias(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _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 target
  • default_target_platform: specifies the default target platform, used when no platforms are specified on the command line
  • target_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • exec_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with an execution platform
  • visibility: a list of visibility patterns restricting what targets can depend on this one
  • within_view: a list of visibility patterns restricting what this target can depend on
  • metadata: a key-value map of metadata associated with this target
  • tests: a list of targets that provide tests for this one
  • modifiers: an array of modifiers associated with this target

android_aar​

def android_aar(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _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] = ...,
    enable_relinker: bool = ...,
    excluded_java_deps: list[str] = ...,
    extra_arguments: list[str] = ...,
    extra_kotlinc_arguments: list[str] = ...,
    friend_paths: list[str] = ...,
    include_build_config_class: bool = ...,
    java_version: None | str = ...,
    javac: None | str = ...,
    labels: list[str] = ...,
    language: None | str = ...,
    licenses: list[str] = ...,
    manifest: None | str = ...,
    manifest_entries: dict[str, typing.Any] = ...,
    manifest_file: None | str = ...,
    manifest_skeleton: str,
    maven_coords: None | str = ...,
    min_sdk_version: None | int = ...,
    native_library_merge_code_generator: None | str = ...,
    native_library_merge_glue: None | str = ...,
    native_library_merge_linker_args: None | dict[str, list[str]] = ...,
    native_library_merge_map: None | dict[str, list[str]] = ...,
    native_library_merge_non_asset_libs: bool = ...,
    native_library_merge_sequence: None | list = ...,
    native_library_merge_sequence_blocklist: None | list[str] = ...,
    never_mark_as_unused_dependency: None | bool = ...,
    on_unused_dependencies: None | str = ...,
    package_asset_libraries: bool = ...,
    package_resources: bool = ...,
    plugins: list[str | (str, list[str])] = ...,
    proguard_config: None | str = ...,
    relinker_extra_deps: list[str] = ...,
    relinker_whitelist: list[str] = ...,
    remove_classes: list[str] = ...,
    required_for_source_only_abi: bool = ...,
    resource_union_package: None | str = ...,
    resources: list[str] = ...,
    resources_root: None | str = ...,
    runtime_deps: list[str] = ...,
    source: None | str = ...,
    source_abi_verification_mode: None | str = ...,
    source_only_abi_deps: list[str] = ...,
    srcs: list[str] = ...,
    strip_libraries: bool = ...,
    target: None | str = ...,
    use_jvm_abi_gen: None | bool = ...,
) -> None

An android_aar() rule is used to generate an Android AAR.

Parameters​

  • name: name of the target
  • default_target_platform: specifies the default target platform, used when no platforms are specified on the command line
  • target_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • exec_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with an execution platform
  • visibility: a list of visibility patterns restricting what targets can depend on this one
  • within_view: a list of visibility patterns restricting what this target can depend on
  • metadata: a key-value map of metadata associated with this target
  • tests: a list of targets that provide tests for this one
  • modifiers: an array of modifiers associated with this target
  • build_config_values: See the documentation on the values argument for android_build_config().
  • include_build_config_class: Whether to include the BuildConfig class files in the final .aar file. Needs to be set to True if any build_config_values are specified. This is normally only needed if the build tool that is consuming the .aar file does not generate BuildConfig classes. Note: the AAR format does not specify a way to pass defaults that should be injected into the final BuildConfig class, therefore that information might need to be replicated manually in the build that's consuming the .aar file.
  • javac: Specifies the Java compiler program to use for this rule. The value is a source path or an execution dep (e.g., //foo/bar:bar). Overrides the value in "javac" in the "tools" section of .buckconfig.
  • manifest_skeleton: The skeleton manifest file used to generate the final AndroidManifest.xml . May either be a file or an android_manifest() target.
  • remove_classes: List of classes to remove from the output aar. It removes classes from the target's own sources, and its dependencies.

Details​

See the official Android documentation for details about the .aar format.

Examples:


android_resource(
  name = 'res',
  res = 'res',
  assets = 'assets',
  package = 'com.example',
)

android_library(
  name = 'lib',
  srcs = glob(['**/*.java']),
)

android_aar(
  name = 'app',
  manifest_skeleton = 'AndroidManifestSkeleton.xml',
  deps = [
    ':res',
    ':lib',
  ],
)

android_app_modularity​

def android_app_modularity(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _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 target
  • default_target_platform: specifies the default target platform, used when no platforms are specified on the command line
  • target_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • exec_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with an execution platform
  • visibility: a list of visibility patterns restricting what targets can depend on this one
  • within_view: a list of visibility patterns restricting what this target can depend on
  • metadata: a key-value map of metadata associated with this target
  • tests: a list of targets that provide tests for this one
  • modifiers: an array of modifiers associated with this target

android_binary​

def android_binary(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _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 = ...,
    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 = ...,
    disable_pre_dex: bool = ...,
    duplicate_resource_behavior: str = ...,
    duplicate_resource_whitelist: None | str = ...,
    enable_bootstrap_dexes: bool = ...,
    enable_relinker: bool = ...,
    exopackage_modes: list[str] = ...,
    extra_filtered_resources: list[str] = ...,
    extra_no_compress_asset_extensions: list[str] = ...,
    field_ref_count_buffer_space: int = ...,
    ignore_aapt_proguard_config: bool = ...,
    includes_vector_drawables: bool = ...,
    is_cacheable: bool = ...,
    is_voltron_language_pack_enabled: bool = ...,
    keystore: str,
    labels: list[str] = ...,
    licenses: list[str] = ...,
    linear_alloc_hard_limit: int = ...,
    locales: list[str] = ...,
    manifest: None | str = ...,
    manifest_entries: dict[str, typing.Any] = ...,
    manifest_skeleton: None | str = ...,
    method_ref_count_buffer_space: int = ...,
    min_sdk_version: None | int = ...,
    minimize_primary_dex_size: bool = ...,
    module_manifest_skeleton: None | str = ...,
    native_library_merge_code_generator: None | str = ...,
    native_library_merge_glue: None | str = ...,
    native_library_merge_linker_args: None | dict[str, list[str]] = ...,
    native_library_merge_map: None | dict[str, list[str]] = ...,
    native_library_merge_non_asset_libs: bool = ...,
    native_library_merge_sequence: None | list = ...,
    native_library_merge_sequence_blocklist: None | list[str] = ...,
    no_auto_add_overlay_resources: bool = ...,
    no_auto_version_resources: bool = ...,
    no_dx: list[str] = ...,
    no_version_transitions_resources: bool = ...,
    optimization_passes: int = ...,
    package_asset_libraries: bool = ...,
    package_type: str = ...,
    packaged_locales: list[str] = ...,
    packaging_options: dict[str, list[str]] = ...,
    platform_override: None | str = ...,
    post_filter_resources_cmd: None | str = ...,
    preprocess_java_classes_bash: None | str = ...,
    preprocess_java_classes_cmd: None | str = ...,
    preprocess_java_classes_deps: list[str] = ...,
    primary_dex_patterns: list[str] = ...,
    proguard_config: None | str = ...,
    proguard_jvm_args: list[str] = ...,
    relinker_extra_deps: list[str] = ...,
    relinker_whitelist: list[str] = ...,
    resource_compression: str = ...,
    resource_filter: list[str] = ...,
    resource_stable_ids: None | str = ...,
    resource_union_package: None | str = ...,
    secondary_dex_weight_limit: None | int = ...,
    skip_crunch_pngs: None | bool = ...,
    skip_proguard: bool = ...,
    strip_libraries: bool = ...,
    trim_resource_ids: bool = ...,
    use_split_dex: bool = ...,
    validation_deps: list[str] = ...,
    xz_compression_level: int = ...,
) -> None

Parameters​

  • name: name of the target
  • default_target_platform: specifies the default target platform, used when no platforms are specified on the command line
  • target_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • exec_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with an execution platform
  • visibility: a list of visibility patterns restricting what targets can depend on this one
  • within_view: a list of visibility patterns restricting what this target can depend on
  • metadata: a key-value map of metadata associated with this target
  • tests: a list of targets that provide tests for this one
  • modifiers: an array of modifiers associated with this target

android_build_config​

def android_build_config(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _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 target

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

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

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

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

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

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

  • metadata: a key-value map of metadata associated with this target

  • tests: a list of targets that provide tests for this one

  • modifiers: an array of modifiers associated with this target

  • package: Name of the Java package to use in the generated BuildConfig.java file. Most developers set this to the application id declared in the manifest via <manifest package="APP_ID">. Example: com.facebook.orca.

  • values: List of strings that defines additional fields (and values) that should be declared in the generated BuildConfig.java file. Like DEBUG, 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 in android_binary().

  • values_file: Optional path to a file that defines additional fields (and values) that should be declared in the generated BuildConfig.java file. Like DEBUG, 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 in android_binary().

    Note that values_file can be a generated file, as can build_config_values_file as demonstrated in the example below.

Details​

The fields in the generated BuildConfig class will be non-constant-expressions (see JLS 15.28). However, if BuildConfig is packaged into an APK, it will be replaced with a new version where:

  • The fields will be set to literal values (i.e., constant expressions).
  • The boolean BuildConfig.DEBUG field will correspond to that of the package_type argument to the android_binary() rule that is packaging it.

This transformation is done before ProGuard is applied (if applicable), so that it can propagate constants from BuildConfig and eliminate dead code.

Examples:

Here is an example of an android_build_config() rule that is transitively included by both debug and release versions of an android_binary() rule. The value of com.example.pkg.BuildConfig.DEBUG will be different in each APK even though they both transitively depend on the same :build_config rule.


android_build_config(
  name = 'build_config',
  package = 'com.example.pkg',
  values = [
    'String COMMIT_ID = "0000000000000000000000000000000000000000"',
  ],
)

# The .java files in this library may contain references to the boolean
# com.example.pkg.BuildConfig.DEBUG because :build_config is in the deps.
# It could also reference BuildConfig.COMMIT_ID.
android_library(
  name = 'mylib',
  srcs = glob(['src/**/*.java']),
  deps = [
    ':build_config',
  ],
)

android_binary(
  name = 'debug',
  package_type = 'DEBUG',
  keystore =  '//keystores:debug',
  manifest = 'AndroidManifest.xml',
  target = 'Google Inc.:Google APIs:19',
  deps = [
    ':mylib',
  ],
)

# The contents of the file generated by this rule might be:
#
# String COMMIT_ID = "7bf804bdf71fdbfc99cce3b155b3643f022c6fa4"
#
# Note that the output of :build_config_release_values will be cached by Buck.
# Assuming that generate_release_build_config.py depends on state that is not
# expressed by its deps (which violates a fundamental invariant in Buck!), a
# workaround is to ensure that the inputs to :build_config_release_values are
# changed in some way before :release is built to ensure that the output from
# :build_config_release_values is not pulled from cache. For example:
#
# $ buck build :release
# $ uuidgen > dummy_state_file.txt
# $ buck build :release
#
# This makes sure that generate_release_build_config.py is re-run before
# :release is rebuilt. This is much cheaper than deleting your build cache
# before rebuilding.
genrule(
  name = 'build_config_release_values',
  srcs = [ 'generate_release_build_config.py', 'dummy_state_file.txt' ],
  bash = 'generate_release_build_config.py $OUT',
  out = 'build_config_release_values.txt',
)

android_binary(
  name = 'release',
  package_type = 'RELEASE',
  keystore =  '//keystores:release',
  manifest = 'AndroidManifest.xml',
  target = 'Google Inc.:Google APIs:19',
  build_config_values_file = ':build_config_release_values',
  deps = [
    ':mylib',
  ],
)

android_bundle​

def android_bundle(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _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 = ...,
    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 = ...,
    disable_pre_dex: bool = ...,
    duplicate_resource_behavior: str = ...,
    duplicate_resource_whitelist: None | str = ...,
    enable_bootstrap_dexes: bool = ...,
    enable_relinker: bool = ...,
    exopackage_modes: list[str] = ...,
    extra_filtered_resources: list[str] = ...,
    extra_no_compress_asset_extensions: list[str] = ...,
    field_ref_count_buffer_space: int = ...,
    ignore_aapt_proguard_config: bool = ...,
    includes_vector_drawables: bool = ...,
    is_cacheable: bool = ...,
    is_voltron_language_pack_enabled: bool = ...,
    keystore: str,
    labels: list[str] = ...,
    licenses: list[str] = ...,
    linear_alloc_hard_limit: int = ...,
    locales: list[str] = ...,
    manifest: None | str = ...,
    manifest_entries: dict[str, typing.Any] = ...,
    manifest_skeleton: None | str = ...,
    method_ref_count_buffer_space: int = ...,
    min_sdk_version: None | int = ...,
    minimize_primary_dex_size: bool = ...,
    module_manifest_skeleton: None | str = ...,
    native_library_merge_code_generator: None | str = ...,
    native_library_merge_glue: None | str = ...,
    native_library_merge_linker_args: None | dict[str, list[str]] = ...,
    native_library_merge_map: None | dict[str, list[str]] = ...,
    native_library_merge_non_asset_libs: bool = ...,
    native_library_merge_sequence: None | list = ...,
    native_library_merge_sequence_blocklist: None | list[str] = ...,
    no_auto_add_overlay_resources: bool = ...,
    no_auto_version_resources: bool = ...,
    no_dx: list[str] = ...,
    no_version_transitions_resources: bool = ...,
    optimization_passes: int = ...,
    package_asset_libraries: bool = ...,
    package_type: str = ...,
    packaged_locales: list[str] = ...,
    packaging_options: dict[str, list[str]] = ...,
    post_filter_resources_cmd: None | str = ...,
    preprocess_java_classes_bash: None | str = ...,
    preprocess_java_classes_cmd: None | str = ...,
    preprocess_java_classes_deps: list[str] = ...,
    primary_dex_patterns: list[str] = ...,
    proguard_config: None | str = ...,
    proguard_jvm_args: list[str] = ...,
    relinker_extra_deps: list[str] = ...,
    relinker_whitelist: list[str] = ...,
    resource_compression: str = ...,
    resource_filter: list[str] = ...,
    resource_stable_ids: None | str = ...,
    resource_union_package: None | str = ...,
    secondary_dex_weight_limit: None | int = ...,
    skip_crunch_pngs: None | bool = ...,
    skip_proguard: bool = ...,
    trim_resource_ids: bool = ...,
    use_derived_apk: bool = ...,
    use_split_dex: bool = ...,
    validation_deps: list[str] = ...,
    xz_compression_level: int = ...,
) -> None

Parameters​

  • name: name of the target
  • default_target_platform: specifies the default target platform, used when no platforms are specified on the command line
  • target_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • exec_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with an execution platform
  • visibility: a list of visibility patterns restricting what targets can depend on this one
  • within_view: a list of visibility patterns restricting what this target can depend on
  • metadata: a key-value map of metadata associated with this target
  • tests: a list of targets that provide tests for this one
  • modifiers: an array of modifiers associated with this target

android_instrumentation_apk​

def android_instrumentation_apk(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _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 = ...,
    apk: str,
    contacts: list[str] = ...,
    cpu_filters: list[str] = ...,
    default_host_platform: None | str = ...,
    deps: list[str] = ...,
    disable_pre_dex: bool = ...,
    includes_vector_drawables: bool = ...,
    is_self_instrumenting: bool = ...,
    labels: list[str] = ...,
    licenses: list[str] = ...,
    manifest: None | str = ...,
    manifest_skeleton: None | str = ...,
    min_sdk_version: None | int = ...,
    native_library_merge_map: None | dict[str, list[str]] = ...,
    native_library_merge_sequence: None | list = ...,
    preprocess_java_classes_bash: None | str = ...,
    preprocess_java_classes_cmd: None | str = ...,
    preprocess_java_classes_deps: list[str] = ...,
    primary_dex_patterns: list[str] = ...,
    use_split_dex: None | bool = ...,
) -> None

An android_instrumentation_apk() rule is used to generate an Android Instrumentation APK.

Parameters​

  • name: name of the target
  • default_target_platform: specifies the default target platform, used when no platforms are specified on the command line
  • target_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • exec_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with an execution platform
  • visibility: a list of visibility patterns restricting what targets can depend on this one
  • within_view: a list of visibility patterns restricting what this target can depend on
  • metadata: a key-value map of metadata associated with this target
  • tests: a list of targets that provide tests for this one
  • modifiers: an array of modifiers associated with this target

Details​

Android's Testing Fundamentals documentation includes a diagram that shows the relationship between an "application package" and a "test package" when running a test. This rule corresponds to a test package. Note that a test package has an interesting quirk where it is compiled against an application package, but must not include the resources or Java classes of the application package. Therefore, this class takes responsibility for making sure the appropriate bits are excluded. Failing to do so will generate mysterious runtime errors when running the test.

Examples:

Here is an example of an android_instrumentation_apk() rule that tests an android_binary(), and depends on a test package.


android_library(
  name = 'test',
  srcs = glob(['test/**/*.java']),
)

android_binary(
  name = 'messenger',
  manifest = 'AndroidManifest.xml',
  keystore = '//keystores:prod',
  package_type = 'release',
  proguard_config = 'proguard.cfg',
  deps = [
    ...
  ],
)

# Building this rule will produce a file named messenger_test.apk
android_instrumentation_apk(
  name = 'messenger_test',
  manifest = 'AndroidInstrumentationManifest.xml',
  apk = ':messenger',
  deps = [
    ':test',
  ],
)

android_instrumentation_test​

def android_instrumentation_test(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _android_emulators: None | str = ...,
    _android_toolchain: str = ...,
    _apple_platforms: dict[str, str] = ...,
    _exec_os_type: str = ...,
    _inject_test_env: str = ...,
    _java_test_toolchain: str = ...,
    _java_toolchain: str = ...,
    _test_toolchain: str = ...,
    apk: str,
    clear_package_data: bool = ...,
    collect_tombstones: bool = ...,
    contacts: list[str] = ...,
    default_host_platform: None | str = ...,
    disable_animations: bool = ...,
    env: dict[str, str] = ...,
    extra_instrumentation_args: None | dict[str, str] = ...,
    instrumentation_test_listener: None | str = ...,
    instrumentation_test_listener_class: None | str = ...,
    is_self_instrumenting: bool = ...,
    labels: list[str] = ...,
    licenses: list[str] = ...,
    log_extractors: dict[str, str] = ...,
    re_caps: None | dict[str, dict[str, str]] = ...,
    re_use_case: None | dict[str, str] = ...,
    record_video: bool = ...,
    test_rule_timeout_ms: None | int = ...,
) -> None

An android_instrumentation_test() rule is used to define apks that should be used to run Android instrumentation tests.

Parameters​

  • name: name of the target
  • default_target_platform: specifies the default target platform, used when no platforms are specified on the command line
  • target_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • exec_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with an execution platform
  • visibility: a list of visibility patterns restricting what targets can depend on this one
  • within_view: a list of visibility patterns restricting what this target can depend on
  • metadata: a key-value map of metadata associated with this target
  • tests: a list of targets that provide tests for this one
  • modifiers: an array of modifiers associated with this target
  • _android_emulators: If provided, local resource of "android_emulators" type will be required to run this test locally and this target will be used to manage it. If omitted, local resource of "android_emulators" type will be ignored even if requested by the test runner.
  • apk: The APK containing the tests. Can be an android_binary(), an apk_genrule() or an android_instrumentation_apk().
  • clear_package_data: Runs pm clear on the app and test packages before the test run if set to True.
  • collect_tombstones: Checks whether the test generated any tombstones, and downloads them from the emulator if true.
  • disable_animations: Disables animations on the emulator if set to True.
  • labels: A list of labels to be applied to these tests. These labels are arbitrary text strings and have no meaning within buck itself. They can, however, have meaning for you as a test author (e.g., smoke or fast). A label can be used to filter or include a specific test rule when executing buck test
  • record_video: Record video of test run and collect it as TRA
  • test_rule_timeout_ms: If set specifies the maximum amount of time (in milliseconds) in which all of the tests in this rule should complete. This overrides the default rule_timeout if any has been specified in .buckconfig .

Details​

Examples:

Here is an example of an android_instrumentation_test() rule that tests an android_binary().


android_binary(
  name = 'messenger',
  manifest = 'AndroidManifest.xml',
  keystore = '//keystores:prod',
  package_type = 'release',
  proguard_config = 'proguard.cfg',
  deps = [
    ...
  ],
)

android_instrumentation_apk(
  name = 'messenger_test',
  manifest = 'AndroidInstrumentationManifest.xml',
  apk = ':messenger',
  deps = [
    ...
  ],
)

android_instrumentation_test(
  name = 'messenger_instrumentation_test',
  apk = ':messenger_test',
)

android_library​

def android_library(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _android_toolchain: str = ...,
    _apple_platforms: dict[str, str] = ...,
    _build_only_native_code: bool = ...,
    _compose_stability_config: None | str = ...,
    _dex_min_sdk_version: None | int = ...,
    _dex_toolchain: str = ...,
    _exec_os_type: str = ...,
    _is_building_android_binary: bool = ...,
    _java_toolchain: str = ...,
    _kotlin_toolchain: str = ...,
    abi_generation_mode: None | str = ...,
    android_optional_jars: None | list[str] = ...,
    annotation_processing_tool: None | str = ...,
    annotation_processor_deps: list[str] = ...,
    annotation_processor_params: list[str] = ...,
    annotation_processors: list[str] = ...,
    contacts: list[str] = ...,
    default_host_platform: None | str = ...,
    deps: list[str] = ...,
    enable_used_classes: bool = ...,
    exported_deps: list[str] = ...,
    exported_provided_deps: list[str] = ...,
    extra_arguments: list[str] = ...,
    extra_kotlinc_arguments: list[str] = ...,
    friend_paths: list[str] = ...,
    incremental: bool = ...,
    jar_postprocessor: None | str = ...,
    java_version: None | str = ...,
    javac: None | str = ...,
    k2: bool = ...,
    kotlin_compiler_plugins: dict[str, dict[str, str]] = ...,
    labels: list[str] = ...,
    language: None | str = ...,
    licenses: list[str] = ...,
    manifest: None | str = ...,
    manifest_file: None | str = ...,
    maven_coords: None | str = ...,
    never_mark_as_unused_dependency: None | bool = ...,
    on_unused_dependencies: None | str = ...,
    plugins: list[str | (str, list[str])] = ...,
    proguard_config: None | str = ...,
    provided_deps: list[str] = ...,
    provided_deps_query: None | str = ...,
    remove_classes: list[str] = ...,
    required_for_source_only_abi: bool = ...,
    resource_union_package: None | str = ...,
    resources: list[str] = ...,
    resources_root: None | str = ...,
    runtime_deps: list[str] = ...,
    source: None | str = ...,
    source_abi_verification_mode: None | str = ...,
    source_only_abi_deps: list[str] = ...,
    srcs: list[str] = ...,
    target: None | str = ...,
    use_jvm_abi_gen: None | bool = ...,
    validation_deps: list[str] = ...,
) -> None

An android_library() rule is used to define a set of Java files that can be compiled together against the Android SDK. The main output of an android_library() rule is a single JAR file containing all of the compiled class files and resources.

Parameters​

  • name: name of the target

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

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

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

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

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

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

  • metadata: a key-value map of metadata associated with this target

  • tests: a list of targets that provide tests for this one

  • modifiers: an array of modifiers associated with this target

  • annotation_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 other android_library rules) that are used to generate the classpath required to compile this android_library.

  • enable_used_classes: Deprecated: for an experiment only, will be removed

  • exported_deps: Other rules that depend on this rule will also include its exported_deps in their classpaths. This is useful when the public API of a rule has return types or checked exceptions that are defined in another rule, which would otherwise require callers to add an extra dependency. It's also useful for exposing e.g. a collection of prebuilt_jar rules as a single target for callers to depend on. Targets in exported_deps are implicitly included in the deps of this rule, so they don't need to be repeated there.

  • exported_provided_deps: This is a combination of provided_deps and exported_deps. Rules listed in this parameter will be added to classpath of rules that depend on this rule, but they will not be included in a binary if binary depends on a such target.

  • extra_arguments: List of additional arguments to pass into the Java compiler. These arguments follow the ones specified in .buckconfig.

  • extra_kotlinc_arguments: List of additional arguments to pass into the Kotlin compiler.

  • incremental: Enables Kotlin incremental compilation.

  • javac: Specifies the Java compiler program to use for this rule. The value is a source path or an execution dep (e.g., //foo/bar:bar). Overrides the value in "javac" in the "tools" section of .buckconfig.

  • k2: Enables the Kotlin K2 compiler.

  • kotlin_compiler_plugins: Use this to specify Kotlin compiler plugins to use when compiling this library. This takes a map, with each entry specify one plugin. Entry's key is plugin source path, and value is a map of plugin option key value pair. Unlike extra_kotlinc_arguments, these can be source paths, not just strings.

    A special option value is __codegen_dir__, in which case Buck will provide a default codegen folder's path as option value instead. E.g.

    fbcode/buck2/prelude/decls/jvm_common.bzl
    kotlin_compiler_plugins = {
        "somePluginSourcePath": {
            "plugin:somePluginId:somePluginOptionKey": "somePluginOptionValue",
            "plugin:somePluginId:someDirectoryRelatedOptionKey": "__codegen_dir__",
        },
    },

    Each plugin source path will be prefixed with -Xplugin= and passed as extra arguments to the compiler. Plugin options will be appended after its plugin with -P.

    A specific example is, if you want to use kotlinx.serialization with kotlin_library(), you need to specify kotlinx-serialization-compiler-plugin.jar under kotlin_compiler_plugins and kotlinx-serialization-runtime.jar (which you may have to fetch from Maven) in your deps:


    kotlin_library(
        name = "example",
        srcs = glob(["*.kt"]),
        deps = [
            ":kotlinx-serialization-runtime",
        ],
        kotlin_compiler_plugins = {
            # Likely copied from your $KOTLIN_HOME directory.
            "kotlinx-serialization-compiler-plugin.jar": {},
        },
    )

    prebuilt_jar(
        name = "kotlinx-serialization-runtime",
        binary_jar = ":kotlinx-serialization-runtime-0.10.0",
    )

    # Note you probably want to set
    # maven_repo=http://jcenter.bintray.com/ in your .buckconfig until
    # https://github.com/Kotlin/kotlinx.serialization/issues/64
    # is closed.
    remote_file(
        name = "kotlinx-serialization-runtime-0.10.0",
        out = "kotlinx-serialization-runtime-0.10.0.jar",
        url = "mvn:org.jetbrains.kotlinx:kotlinx-serialization-runtime:jar:0.10.0",
        sha1 = "23d777a5282c1957c7ce35946374fff0adab114c"
    )

  • 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 an android_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 of provided_deps include the JEE servlet APIs. When this rule is included in a , the provided_deps will not be packaged into the output.

  • provided_deps_query: Status: experimental/unstable. The provided deps query functions in the same way as the deps query, but the referenced deps using $declared are the provided deps of the target, and the results of the query are appended to the declared provided deps.

  • remove_classes: List of classes to remove from the output jar. It only removes classes from the target's own sources, not from any of its dependencies.

  • required_for_source_only_abi: Indicates that this rule must be present on the classpath during source-only ABI generation of any rule that depends on it. Typically this is done when a rule contains annotations, enums, constants, or interfaces.

    Having rules present on the classpath during source-only ABI generation prevents Buck from completely flattening the build graph, thus reducing the performance win from source-only ABI generation. These rules should be kept small (ideally just containing annotations, constants, enums, and interfaces) and with minimal dependencies of their own.

  • resources: Static files to include among the compiled .class files. These files can be loaded via Class.getResource().

    Note: Buck uses the src_roots property in .buckconfig to help determine where resources should be placed within the generated JAR file.

  • source: Specifies the version of Java (as a string) to interpret source files as. Overrides the value in "source_level" in the "java" section of .buckconfig.

  • source_only_abi_deps: These are dependencies that must be present during source-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 .java files to compile for this rule.

  • target: Specifies the version of Java (as a string) for which to generate code. Overrides the value in "target_level" in the "java" section of .buckconfig.

Details​

Examples:

An android_library rule used in concert with an android_resource() rule. This would be a common arrangement for a standard Android Library project as defined by http://developer.android.com/tools/projects/index.html


android_resource(
  name = 'res',
  res = 'res',
  package = 'com.example',
)

android_library(
  name = 'my_library',
  srcs = glob(['src/**/*.java']),
  deps = [
    ':res',
  ],
)

android_manifest​

def android_manifest(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _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 target
  • default_target_platform: specifies the default target platform, used when no platforms are specified on the command line
  • target_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • exec_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with an execution platform
  • visibility: a list of visibility patterns restricting what targets can depend on this one
  • within_view: a list of visibility patterns restricting what this target can depend on
  • metadata: a key-value map of metadata associated with this target
  • tests: a list of targets that provide tests for this one
  • modifiers: an array of modifiers associated with this target
  • deps: A collection of dependencies that includes android_library rules. The manifest files of the android_library() rules will be filtered out to become dependent source files for the manifest.
  • skeleton: Either a build target or a path to a file representing the manifest that will be merged with any manifests associated with this rule's deps.

Details​

Examples:

Here's an example of an android_manifest() that has no deps.


android_manifest(
  name = 'my-manifest',
  skeleton = 'AndroidManifestSkeleton.xml',
)

This is what AndroidManifestSkeleton.xml looks like.


<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
          package="com.example"
          android:versionCode="1"
          android:versionName="1.0">

    <uses-sdk targetSdkVersion="19" minSdkVersion="17"/>
    <application
        android:label="@string/app_name"
        android:icon="@drawable/ic_launcher">
        <activity
            android:name="MyActivity"
            android:label="@string/app_name">
            <intent-filter>
                <action android:name="android.intent.action.MAIN"/>
                <category android:name="android.intent.category.LAUNCHER"/>
            </intent-filter>
        </activity>
    </application>
</manifest>

You could also use a genrule() to generate the manifest file and reference the build target in the skeleton argument.

android_platform​

def android_platform(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    base_platform: str,
    native_platforms: dict[str, str] = ...,
) -> None

Parameters​

  • name: name of the target
  • default_target_platform: specifies the default target platform, used when no platforms are specified on the command line
  • target_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • exec_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with an execution platform
  • visibility: a list of visibility patterns restricting what targets can depend on this one
  • within_view: a list of visibility patterns restricting what this target can depend on
  • metadata: a key-value map of metadata associated with this target
  • tests: a list of targets that provide tests for this one
  • modifiers: an array of modifiers associated with this target

android_prebuilt_aar​

def android_prebuilt_aar(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _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] = ...,
    desugar_deps: list[str] = ...,
    for_primary_apk: bool = ...,
    javadoc_url: None | str = ...,
    labels: list[str] = ...,
    licenses: list[str] = ...,
    maven_coords: None | str = ...,
    required_for_source_only_abi: bool = ...,
    source_jar: None | str = ...,
    use_system_library_loader: bool = ...,
) -> None

An android_prebuilt_aar() rule takes an .aar file and makes it available as an Android dependency. As expected, an android_binary() that transitively depends on an android_prebuilt_aar() will include its contents in the generated APK.

Parameters​

  • name: name of the target
  • default_target_platform: specifies the default target platform, used when no platforms are specified on the command line
  • target_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • exec_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with an execution platform
  • visibility: a list of visibility patterns restricting what targets can depend on this one
  • within_view: a list of visibility patterns restricting what this target can depend on
  • metadata: a key-value map of metadata associated with this target
  • tests: a list of targets that provide tests for this one
  • modifiers: an array of modifiers associated with this target
  • aar: Path to the .aar file. This may also be a build target to a rule (such as a genrule()) whose output is an .aar file.
  • javadoc_url: URL to the Javadoc for the .class files in the aar.
  • source_jar: Path to a JAR file that contains the .java files to create the .class in the aar. This is frequently provided for debugging purposes.
  • use_system_library_loader: If this .aar file contains native prebuilt .so libraries and the Java code uses these libraries via a call to System.loadLibrary(), then many optimizations—such as exopackage, compression, or asset packaging—may not be compatible with these prebuilt libs. Setting this parameter to True causes all of these optimizations to skip the prebuilt .so files originating from this .aar file. The .so files will always be packaged directly into the main .apk.

Details​

See the official Android documentation for details about the .aar format.

Examples:


android_prebuilt_aar(
  name = 'play-services',
  aar = 'play-services-4.0.30.aar',
  source_jar = 'play-services-4.0.30-sources.jar',
  javadoc_url = 'file:///opt/android-sdk/extras/google/google_play_services/docs/reference',
)

android_library(
  name = 'lib',
  # This Java code can compile against Play services and reference its resources.
  srcs = glob(['*.java']),
  deps = [ ':play-services' ],
)

android_resource​

def android_resource(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _android_toolchain: str = ...,
    _apple_platforms: dict[str, str] = ...,
    _build_only_native_code: bool = ...,
    _java_toolchain: str = ...,
    allowlisted_locales: None | list[str] = ...,
    assets: None | str | dict[str, str] = ...,
    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 target
  • default_target_platform: specifies the default target platform, used when no platforms are specified on the command line
  • target_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • exec_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with an execution platform
  • visibility: a list of visibility patterns restricting what targets can depend on this one
  • within_view: a list of visibility patterns restricting what this target can depend on
  • metadata: a key-value map of metadata associated with this target
  • tests: a list of targets that provide tests for this one
  • modifiers: an array of modifiers associated with this target
  • deps: Other android_resource rules to include via -S when running aapt.
  • 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 an android_manifest() target.
  • package: Java package for the R.java file that will be generated for these resources.

Details​

The output of an android_resource() is an R.txt file generated via aapt --output-text-symbols.

Examples:

Most of the time, an android_resource rule defines only name, res, and package. By convention, such simple rules are often named res:


android_resource(
  name = 'res',
  res = subdir_glob([('res', '**')]),
  package = 'com.example',
)

apk_genrule​

def apk_genrule(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _android_toolchain: str = ...,
    _apple_platforms: dict[str, str] = ...,
    _build_only_native_code: bool = ...,
    _exec_os_type: str = ...,
    _genrule_toolchain: str = ...,
    _java_toolchain: str = ...,
    aab: None | str = ...,
    always_print_stderr: bool = ...,
    apk: None | str = ...,
    bash: None | str = ...,
    cacheable: None | bool = ...,
    cmd: None | str = ...,
    cmd_exe: None | str = ...,
    contacts: list[str] = ...,
    default_host_platform: None | str = ...,
    default_outs: None | list[str] = ...,
    enable_sandbox: None | bool = ...,
    environment_expansion_separator: None | str = ...,
    is_cacheable: bool = ...,
    keystore: None | str = ...,
    labels: list[str] = ...,
    licenses: list[str] = ...,
    metadata_env_var: None | str = ...,
    metadata_path: None | str = ...,
    need_android_tools: bool = ...,
    no_outputs_cleanup: bool = ...,
    out: None | str = ...,
    outs: None | dict[str, list[str]] = ...,
    remote: None | bool = ...,
    remote_execution_dependencies: list[dict[str, str]] = ...,
    srcs: list[str] | dict[str, str] = ...,
    type: str = ...,
    use_derived_apk: bool = ...,
    weight: None | int = ...,
) -> None

An apk_genrule() rule is used to post-process an APK. What separates an apk_genrule from a genrule is apk_genrules are known by BUCK to produce APKs, so commands like buck install or buck uninstall still work. Additionally, apk_genrule() rules can be inputs to other apk_genrule() rules.

Parameters​

  • name: name of the target

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

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

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

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

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

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

  • metadata: a key-value map of metadata associated with this target

  • tests: a list of targets that provide tests for this one

  • modifiers: an array of modifiers associated with this target

  • aab: The input android_binary() rule. The path to the AAB can be accessed with the $AAB shell variable. Only one of apk or aab can be provided.

  • apk: The input android_binary() rule. The path to the APK can be accessed with the $APK shell variable. Only one of apk or aab can be provided.

  • bash: A platform-specific version of the shell command parameter cmd. It runs on Linux and UNIX systems—including OSX—on which bash is installed. It has a higher priority than cmd. The bash argument is run with /usr/bin/env bash -c. It has access to the same set of macros and variables as the cmd argument.

  • cmd: The shell command to run to generate the output file. It is the fallback for bash and cmd_exe arguments. The following environment variables are populated by Buck and available to the shell command. They are accessed using the syntax:

    ${<variable>}

    Example:

    ${SRCS}

    ${SRCS}

    A string expansion of the srcs argument delimited by the environment_expansion_separator argument where each element of srcs will be translated into a relative path.

    ${SRCDIR}

    The relative path to a directory to which sources are copied prior to running the command.

    ${OUT}

    The output file or directory for the genrule(). This variable will have whatever value is specified by the out argument if not using named outputs. If using named outputs, this variable will be the output directory.

    The value should be a valid filepath. The semantics of the shell command determine whether this filepath is treated as a file or a directory. If the filepath is a directory, then the shell command needs to create it if not using named outputs. Otherwise, it will be automatically created. All outputs (directories and files) must be readable, writable, and (in the case of directories) executable by the current user.

    The file or directory specified by this variable must always be written by this command. If not, the execution of this rule will be considered a failure, halting the build process.

    ${TMP}

    A temporary directory which can be used for intermediate results and will not be bundled into the output.

  • cmd_exe: A platform-specific version of the shell command parameter cmd. It runs on Windows and has a higher priority than cmd. The cmd_exe argument is run with cmd.exe /v:off /c. It has access to the same set of macros and variables as the cmd argument.

  • environment_expansion_separator: The delimiter between paths in environment variables, such as SRCS, that can contain multiple paths. It can be useful to specify this parameter if the paths could contain spaces.

  • out: The name of the output file or directory. The complete path to this argument is provided to the shell command through the OUT environment variable. Only one of out or outs may be present.

    For an apk_genrule the output should be a '.apk' or '.aab' file.

  • srcs: Either a list or a map of the source files which Buck makes available to the shell command at the path in the SRCDIR environment variable. If you specify a list, the source files are the names in the list. If you specify a map, the source files are made available as the names in the keys of the map, where the values of the map are the original source file names.

  • weight: How many local slots these genrule should take when executing locally.

Details​

Examples:

Here is an example of a couple apk_genrule() open up an APK, do some super signing, and then zipalign that APK again.



# Building this rule will produce a file named messenger.apk.
android_binary(
  name = 'messenger',
  manifest = 'AndroidManifest.xml',
  target = 'Google Inc.:Google APIs:16',
  keystore = '//keystores:prod',
  package_type = 'release',
  proguard_config = 'proguard.cfg',
  deps = [
    ':res',
    ':src',
  ],
)

apk_genrule(
  name = 'messenger_super_sign_unalign',
  apk = ':messenger',
  bash = '$(exe //java/com/facebook/sign:super_sign) --input $APK --output $OUT',
  cmd_exe = '$(exe //java/com/facebook/sign:super_sign) --input %APK% --output %OUT%',
  out = 'messenger_super_sign_unalign.apk',
)

apk_genrule(
  name = 'messenger_super_sign',
  apk = ':messenger_super_sign_unalign',
  bash = '$ANDROID_HOME/tools/zipalign -f 4 $APK $OUT',
  cmd_exe = '%ANDROID_HOME%\tools\zipalign -f 4 %APK% %OUT%',
  out = 'messenger_super_sign.apk',
)


apple_asset_catalog​

def apple_asset_catalog(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _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] = ...,
    skip_universal_resource_dedupe: bool = ...,
) -> None

An apple_asset_catalog() rule contains resources stored in Apple asset catalog directories. This rule does not have any output on its own and can be built only as a dependency (either direct or transitive) of an apple_bundle() rule, in which case all apple_asset_catalog() rules that the bundle rule depends on are merged and placed into the final output bundle together.

Parameters​

  • name: name of the target
  • default_target_platform: specifies the default target platform, used when no platforms are specified on the command line
  • target_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • exec_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with an execution platform
  • visibility: a list of visibility patterns restricting what targets can depend on this one
  • within_view: a list of visibility patterns restricting what this target can depend on
  • metadata: a key-value map of metadata associated with this target
  • tests: a list of targets that provide tests for this one
  • modifiers: an array of modifiers associated with this target
  • app_icon: An optional reference to a .appiconset containing a image set representing an application icon. (The extension itself should not be included.) This parameter may be specified at most once in a given apple_bundle's transitive dependencies.
  • launch_image: An optional reference to a .launchimage containing a image set representing an application launch image. (The extension itself should not be included.) This parameter may be specified at most once in a given apple_bundle's transitive dependencies.

Details​

Examples:


apple_asset_catalog(
  name = 'MyAssetCatalog',
  dirs = [
    'MyResources.xcassets',
  ],
)

# A asset catalog with a app icon and launch image
apple_asset_catalog(
  name = 'AssetCatalog',
  dirs = [ 'AssetCatalog.xcassets' ],
  app_icon = 'Icon',
  launch_image = 'LaunchImage',
)

apple_binary​

def apple_binary(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    _apple_toolchain: str = ...,
    _apple_tools: str = ...,
    _apple_xctoolchain: str = ...,
    _apple_xctoolchain_bundle_id: str = ...,
    _dsymutil_extra_flags: list[str],
    _dsymutil_verify_dwarf: str,
    _enable_library_evolution: bool = ...,
    _stripped_default: bool = ...,
    _swift_enable_testing: bool = ...,
    allow_cache_upload: None | bool = ...,
    attrs_validators: None | list[str] = ...,
    binary_linker_flags: list[str] = ...,
    bridging_header: None | str = ...,
    can_be_asset: None | bool = ...,
    compiler_flags: list[str] = ...,
    constraint_overrides: list[str] = ...,
    contacts: list[str] = ...,
    cxx_runtime_type: None | str = ...,
    default_host_platform: None | str = ...,
    default_platform: None | str = ...,
    defaults: dict[str, str] = ...,
    deps: list[str] = ...,
    devirt_enabled: bool = ...,
    diagnostics: dict[str, str] = ...,
    dist_thin_lto_codegen_flags: list[str] = ...,
    dsym_uses_parallel_linker: bool = ...,
    enable_cxx_interop: bool = ...,
    enable_distributed_thinlto: bool = ...,
    enable_library_evolution: None | bool = ...,
    entitlements_file: None | str = ...,
    executable_name: None | 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 | 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_override: None | str = ...,
    platform_preprocessor_flags: list[(str, list[str])] = ...,
    platform_srcs: list[(str, list[str | (str, list[str])])] = ...,
    post_linker_flags: list[str] = ...,
    post_platform_linker_flags: list[(str, list[str])] = ...,
    precompiled_header: None | str = ...,
    prefer_stripped_objects: bool = ...,
    preferred_linkage: str = ...,
    prefix_header: None | str = ...,
    preprocessor_flags: list[str] = ...,
    propagated_target_sdk_version: None | str = ...,
    public_include_directories: list[str] = ...,
    public_system_include_directories: list[str] = ...,
    raw_headers: list[str] = ...,
    reexport_all_header_dependencies: None | bool = ...,
    sanitizer_runtime_enabled: None | bool = ...,
    sdk_modules: list[str] = ...,
    serialize_debugging_options: None | bool = ...,
    soname: None | str = ...,
    srcs: list[str | (str, list[str])] = ...,
    static_library_basename: None | str = ...,
    stripped: None | bool = ...,
    supported_platforms_regex: None | str = ...,
    supports_merged_linking: None | bool = ...,
    swift_compilation_mode: str = ...,
    swift_compiler_flags: list[str] = ...,
    swift_interface_compilation_enabled: bool = ...,
    swift_module_skip_function_bodies: bool = ...,
    swift_package_name: None | str = ...,
    swift_version: None | str = ...,
    target_sdk_version: None | str = ...,
    thin_lto: bool = ...,
    use_submodules: bool = ...,
    uses_cxx_explicit_modules: bool = ...,
    uses_explicit_modules: bool = ...,
    uses_modules: bool = ...,
    validation_deps: list[str] = ...,
) -> None

An apple_binary() rule builds a native executable - such as an iOS or OSX app - from the supplied set of Objective-C/C++ source files and dependencies. It is similar to a cxx_binary() rule with which it shares many attributes. In addition to those common attributes, apple_binary() has a some additional attributes that are specific to binaries intended to be built using the Apple toolchain. Note, however, that apple_binary() and cxx_binary() differ in the way that they import header files, in order to better accommodate existing conventions. See the sections for the headers and exported_headers attributes for more details.

Parameters​

  • name: name of the target

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

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

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

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

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

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

  • metadata: a key-value map of metadata associated with this target

  • tests: a list of targets that provide tests for this one

  • modifiers: an array of modifiers associated with this target

  • allow_cache_upload: Whether to allow uploading the output of this rule to be uploaded to cache when the action is executed locally if the configuration allows (i.e. there is a cache configured and the client has permission to write to it).

  • compiler_flags: Flags to use when compiling any of the above sources (which require compilation).

  • entitlements_file: An optional name of a plist file to be embedded in the binary. Some platforms like iphonesimulator require this to run properly.

  • exported_headers: The set of header files that are made available for inclusion to the source files in this target and all targets that transitively depend on this one. These should be specified as either a list of header files or a dictionary of header names to header files. The header names can contain forward slashes (/). If a list of header files is specified, the headers can be imported with #import "$HEADER_PATH_PREFIX/$HEADER_NAME" or, if a header file that belongs to the same rule is being imported, with #import "$HEADER_NAME", where $HEADER_PATH_PREFIX is the value of the target's header_path_prefix attribute, and $HEADER_NAME is the filename of the header file. If a dictionary is specified, each header can be imported with #import "$HEADER_NAME", where $HEADER_NAME is the key corresponding to this file. In this case, the header_path_prefix attribute is ignored. In either case, quotes in the import statements can be replaced with angle brackets.

  • exported_linker_flags: Flags to add to the linker command line when the output from this rule, or the output from any rule that transitively depends on this rule, is used in a link operation.

  • extra_xcode_files: When the project is generated, this is the list of files that will added to the project. Those files won't be added to the build phase "Compile Sources".

  • frameworks: A list of system frameworks that the code in this target uses. Each entry should be a path starting with $SDKROOT or $PLATFORM_DIR to denote that the rest of the path is relative to the root of the SDK used for the build or to the platform toolchain directory.

  • header_path_prefix: A path prefix when including headers of this target. For example, headers from a library defined 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_PREFIX is the value of the target's header_path_prefix attribute, and $HEADER_NAME is the filename of the header file. If a dictionary is specified, each header can be imported with #import "$HEADER_NAME", where $HEADER_NAME is the key corresponding to this file. In this case, the header_path_prefix attribute is ignored. In either case, quotes in the import statements can be replaced with angle brackets.

  • link_execution_preference: The execution preference for linking. Options are:

    • any : No preference is set, and the link action will be performed based on buck2's executor configuration.
    • full_hybrid : The link action will execute both locally and remotely, regardless of buck2's executor configuration (if the executor is capable of hybrid execution). The use_limited_hybrid setting of the hybrid executor is ignored.
    • local : The link action will execute locally if compatible on current host platform.
    • local_only : The link action will execute locally, and error if the current platform is not compatible.
    • remote : The link action will execute remotely if a compatible remote platform exists, otherwise locally.

    The default is None, expressing that no preference has been set on the target itself.

  • link_group_public_deps_label: Surface nodes with this label as "public" nodes in the main executable when linking with with link groups.

  • link_style: Determines whether to build and link this rule's dependencies statically or dynamically. Can be either static, static_pic or shared.

  • linker_extra_outputs: Declares extra outputs that the linker emits. These identifiers can be used in $(output ...) macros in linker_flags to interpolate the output path into the linker command line. Useful for custom linkers that emit extra output files.

  • linker_flags: Flags to add to the linker command line whenever the output from this rule is used in a link operation, such as linked into an executable or a shared library.

  • platform_compiler_flags: Platform specific compiler flags. These should be specified as a list of pairs where the first element is an un-anchored regex (in java.util.regex.Pattern syntax) against which the platform name is matched, and the second element is a list of flags to use when compiling the target's sources. See compiler_flags for more information.

  • platform_linker_flags: Platform-specific linker flags. This argument is specified as a list of pairs where the first element in each pair is an un-anchored regex against which the platform name is matched. The regex should use java.util.regex.Pattern syntax. The second element in each pair is a list of linker flags. If the regex matches the platform, these flags are added to the linker command line when the output from this rule is used in a link operation.

  • platform_srcs: Platform specific source files. These should be specified as a list of pairs where the first element is an un-anchored regex (in java.util.regex.Pattern syntax) against which the platform name is matched, and the second element is either a list of source files or a list of tuples of source files and a list of compilation flags to be preprocessed, compiled and assembled if the platform matches the regex. See srcs for more information.

  • preprocessor_flags: Flags to use when preprocessing any of the above sources (which require preprocessing).

  • srcs: The set of C, C++, Objective-C, Objective-C++, or assembly source files to be preprocessed, compiled, and assembled by this rule. We determine which stages to run on each input source based on its file extension. See the GCC documentation for more detail on how file extensions are interpreted. Each element can be either a string specifying a source file (e.g. '') or a tuple of a string specifying a source file and a list of compilation flags (e.g. ('', ['-Wall', '-Werror']) ). In the latter case the specified flags will be used in addition to the rule's other flags when preprocessing and compiling that file (if applicable).

  • target_sdk_version: The minimum OS version that the library target should support, overriding the minimum set in .buckconfig. When set, Buck will automatically add flags to both Objective-C and Swift compilation that will allow the use of the new APIs without guarding code inside availability checks.

Details​

Buck enables you to override components of the Apple toolchain with alternate tools, either from the Xcode search paths or from directories that you specify. See .buckconfig and .buckconfig for more information.

Examples:


apple_binary(
  name = 'MyBinary',
  deps = [
    ':MyLibrary',
    '//Libraries:AnotherLibrary',
  ],
  preprocessor_flags = ['-fobjc-arc'],
  headers = [
    'MyHeader.h',
  ],
  srcs = [
    'MySource.m',
  ],
  frameworks = [
    '$SDKROOT/System/Library/Frameworks/UIKit.framework',
    '$SDKROOT/System/Library/Frameworks/Foundation.framework',
  ],
)

apple_bundle​

def apple_bundle(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    _apple_toolchain: str = ...,
    _apple_tools: str = ...,
    _apple_xctoolchain: str = ...,
    _apple_xctoolchain_bundle_id: str = ...,
    _bundling_cache_buster: None | str = ...,
    _bundling_log_file_enabled: bool = ...,
    _bundling_log_file_level: None | str = ...,
    _code_signing_configuration: None | str = ...,
    _codesign_entitlements: None | str = ...,
    _codesign_identities_command_override: None | str = ...,
    _codesign_type: None | str = ...,
    _compile_resources_locally_override: None | bool = ...,
    _dsymutil_extra_flags: list[str],
    _dsymutil_verify_dwarf: str,
    _embed_provisioning_profile_when_adhoc_code_signing: None | bool = ...,
    _fast_adhoc_signing_enabled_default: bool = ...,
    _fast_provisioning_profile_parsing_enabled: bool = ...,
    _incremental_bundling_enabled: bool = ...,
    _info_plist_identify_build_system_default: bool = ...,
    _profile_bundling_enabled: bool = ...,
    _provisioning_profiles: str = ...,
    _resource_bundle: None | str = ...,
    _skip_adhoc_resigning_scrubbed_frameworks_default: bool = ...,
    _skip_adhoc_resigning_scrubbed_frameworks_override: None | bool = ...,
    _strict_provisioning_profile_search_default: bool = ...,
    _use_entitlements_when_adhoc_code_signing: None | bool = ...,
    asset_catalogs_compilation_options: dict[str, typing.Any] = ...,
    binary: None | str = ...,
    bundle_type: None | str = ...,
    code_signing_configuration: None | str = ...,
    codesign_flags: list[str] = ...,
    codesign_identity: None | str = ...,
    codesign_type: None | str = ...,
    contacts: list[str] = ...,
    copy_public_framework_headers: None | bool = ...,
    debug_artifacts_validators: dict[str, (str, str)] = ...,
    default_host_platform: None | str = ...,
    default_platform: None | str = ...,
    deps: list[str] = ...,
    dsym_uses_parallel_linker: bool = ...,
    embed_provisioning_profile_when_adhoc_code_signing: bool = ...,
    embed_xctest_frameworks: bool = ...,
    extension: str,
    fast_adhoc_signing_enabled: None | bool = ...,
    ibtool_flags: None | list[str] = ...,
    ibtool_module_flag: None | bool = ...,
    incremental_bundling_enabled: None | bool = ...,
    info_plist: str,
    info_plist_identify_build_system: None | bool = ...,
    info_plist_substitutions: dict[str, str] = ...,
    labels: list[str] = ...,
    licenses: list[str] = ...,
    module_map: None | str = ...,
    platform_binary: None | list[(str, str)] = ...,
    privacy_manifest: None | str = ...,
    product_name: None | str = ...,
    product_name_from_module_name: bool = ...,
    propagated_target_sdk_version: None | str = ...,
    provisioning_profile_filter: None | str = ...,
    resource_group: None | str = ...,
    resource_group_map: None | str = ...,
    selective_debugging: None | str = ...,
    skip_adhoc_resigning_scrubbed_frameworks: None | bool = ...,
    skip_copying_swift_stdlib: None | bool = ...,
    split_arch_dsym: bool = ...,
    strict_provisioning_profile_search: None | bool = ...,
    try_skip_code_signing: None | bool = ...,
    universal: None | bool = ...,
    use_entitlements_when_adhoc_code_signing: bool = ...,
    validation_deps: list[str] = ...,
    versioned_macos_bundle: bool = ...,
    xcode_product_type: None | str = ...,
) -> None

An apple_bundle() rule takes an Apple binary and all of the resources and asset catalogs in the rule's transitive dependencies and generates a bundle containing all of those files. Optionally the generated bundle can also be signed using specified provisioning profiles.

Parameters​

  • name: name of the target

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

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

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

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

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

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

  • metadata: a key-value map of metadata associated with this target

  • tests: a list of targets that provide tests for this one

  • modifiers: an array of modifiers associated with this target

  • asset_catalogs_compilation_options: A dict holding parameters for asset catalogs compiler (actool). Its options include:

    • notices (defaults to True)
    • warnings (defaults to True)
    • errors (defaults to True)
    • compress_pngs (defaults to True)
    • optimization (defaults to 'space')
    • output_format (defaults to 'human-readable-text')
    • extra_flags (defaults to [])

  • deps: A list of dependencies of this bundle as build targets. You can embed application extensions by specifying the extension's bundle target. To include a WatchKit app, append the flavor #watch to the target specification. Buck will automatically substitute the appropriate platform flavor (either watchsimulator or watchos) 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 an Info.plist file that will be placed in the bundle. The specified file will be processed by substituting variable names with their values (see info_plist_substitutions for more information).

  • info_plist_substitutions: A dictionary that assigns variable names to their values. It is used for variable substitution when processing the file specified in info_plist. For example if this argument is set to {'VAR': 'MyValue'}, then each occurrence of $(VAR) or ${VAR} in the file will be replaced by MyValue.

  • privacy_manifest: A path to an .xcprivacy file that will be placed in the bundle.

  • product_name: The name of the resulting bundle and binary. The setting behaves like PRODUCT_NAME Xcode build setting. For example, if your rule is named "MyApp" and extension is "app", by default buck will generate MyApp.app bundle. But if you will set product name to "SuperApp", bundle will get "SuperApp.app" name.

Details​

Code signing will embed entitlements pointed to by the entitlements_file arg in the bundle's apple_binary. This is the preferred way to specify entitlements when building with Buck.

If the entitlements file is not present, it falls back to the CODE_SIGN_ENTITLEMENTS entry in info_plist_substitutions.

If after these checks, an entitlements file is still not specified, it will be derived based on the entitlements of the selected provisioning profile. Provisioning profiles will be selected from profiles pointed to by apple.provisioning_profile_search_path, based on a non-expired profile that matches the bundle id and entitlements.

Code signing will embed entitlements pointed to by the CODE_SIGN_ENTITLEMENTS entry in info_plist_substitutions. If an entitlements file is omitted, it will be derived based on the entitlements of the selected provisioning profile. Provisioning profiles will be selected from profiles pointed to by apple.provisioning_profile_search_path, based on a non-expired profile that matches the bundle id and entitlements.

Examples:


apple_bundle(
  name = 'AppBundle',
  binary = ':MyBinary',
  extension = 'app',
  info_plist = 'Info.plist',
)


# iOS app with embedded WatchOS 2.0 app/extension
apple_bundle(
  name = 'DemoWatchAppExtension',
  binary = ':DemoWatchAppExtensionBinary',
  extension = 'appex',
  info_plist = 'WatchExtension/Resources/Info.plist',
)

apple_bundle(
  name = 'DemoWatchApp',
  binary = ':DemoWatchAppBinary',
  deps = [':DemoWatchAppResources', ':DemoWatchAppExtension'],
  extension = 'app',
  info_plist = 'WatchApplication/Info.plist',
)

apple_bundle(
  name = 'DemoApp',
  binary = ':DemoAppBinary',
  deps = [':DemoWatchApp#watch'],
  extension = 'app',
  info_plist = 'Info.plist',
)


# iOS app using safeAreaInsets delivering to iOS 9.x
apple_bundle(
  name = 'DemoIBApp',
  binary = ':DemoIBAppBinary',
  deps = [':DemoIBAppResources'],
  extension = 'app',
  ibtool_flags = ["--minimum-deployment-target", "9.0"],
  info_plist = 'Info.plist',
)

apple_library​

def apple_library(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    _apple_toolchain: str = ...,
    _apple_tools: str = ...,
    _apple_xctoolchain: str = ...,
    _apple_xctoolchain_bundle_id: str = ...,
    _archive_objects_locally_override: None | bool = ...,
    _dsymutil_extra_flags: list[str],
    _dsymutil_verify_dwarf: str,
    _enable_library_evolution: bool = ...,
    _meta_apple_library_validation_enabled: bool = ...,
    _stripped_default: bool = ...,
    _swift_enable_testing: bool = ...,
    allow_cache_upload: None | bool = ...,
    attrs_validators: None | list[str] = ...,
    bridging_header: None | str = ...,
    can_be_asset: None | bool = ...,
    compiler_flags: list[str] = ...,
    contacts: list[str] = ...,
    cxx_runtime_type: None | str = ...,
    default_host_platform: None | str = ...,
    default_platform: None | str = ...,
    defaults: dict[str, str] = ...,
    deps: list[str] = ...,
    devirt_enabled: bool = ...,
    diagnostics: dict[str, str] = ...,
    dist_thin_lto_codegen_flags: list[str] = ...,
    dsym_uses_parallel_linker: bool = ...,
    enable_cxx_interop: bool = ...,
    enable_distributed_thinlto: bool = ...,
    enable_library_evolution: None | bool = ...,
    enable_private_swift_module: bool = ...,
    executable_name: None | str = ...,
    exported_deps: list[str] = ...,
    exported_header_style: str = ...,
    exported_headers: list[str] | dict[str, str] = ...,
    exported_lang_platform_preprocessor_flags: dict[str, list[(str, list[str])]] = ...,
    exported_lang_preprocessor_flags: dict[str, list[str]] = ...,
    exported_linker_flags: list[str] = ...,
    exported_platform_deps: list[(str, list[str])] = ...,
    exported_platform_headers: list[(str, list[str] | dict[str, str])] = ...,
    exported_platform_linker_flags: list[(str, list[str])] = ...,
    exported_platform_preprocessor_flags: list[(str, list[str])] = ...,
    exported_post_linker_flags: list[str] = ...,
    exported_post_platform_linker_flags: list[(str, list[str])] = ...,
    exported_preprocessor_flags: list[str] = ...,
    extra_xcode_files: list[str] = ...,
    extra_xcode_sources: list[str] = ...,
    fat_lto: bool = ...,
    focused_list_target: None | str = ...,
    force_static: None | bool = ...,
    frameworks: list[str] = ...,
    header_mode: None | str = ...,
    header_namespace: None | str = ...,
    header_path_prefix: None | str = ...,
    headers: list[str] | dict[str, str] = ...,
    headers_as_raw_headers_mode: None | str = ...,
    include_directories: list[str] = ...,
    info_plist: None | str = ...,
    info_plist_substitutions: dict[str, str] = ...,
    labels: list[str] = ...,
    lang_compiler_flags: dict[str, list[str]] = ...,
    lang_platform_compiler_flags: dict[str, list[(str, list[str])]] = ...,
    lang_platform_preprocessor_flags: dict[str, list[(str, list[str])]] = ...,
    lang_preprocessor_flags: dict[str, list[str]] = ...,
    libraries: list[str] = ...,
    licenses: list[str] = ...,
    link_execution_preference: None | str = ...,
    link_group: None | str = ...,
    link_group_map: None | str | list[(str, list[(None | str | list[None | str], str, None | str | list[str], None | str)], None | dict[str, typing.Any])] = ...,
    link_ordering: None | str = ...,
    link_style: None | str = ...,
    link_whole: None | bool = ...,
    linker_extra_outputs: list[str] = ...,
    linker_flags: list[str] = ...,
    modular: bool = ...,
    module_name: None | str = ...,
    module_requires_cxx: bool = ...,
    platform_compiler_flags: list[(str, list[str])] = ...,
    platform_deps: list[(str, list[str])] = ...,
    platform_headers: list[(str, list[str] | dict[str, str])] = ...,
    platform_linker_flags: list[(str, list[str])] = ...,
    platform_preprocessor_flags: list[(str, list[str])] = ...,
    platform_srcs: list[(str, list[str | (str, list[str])])] = ...,
    post_linker_flags: list[str] = ...,
    post_platform_linker_flags: list[(str, list[str])] = ...,
    precompiled_header: None | str = ...,
    preferred_linkage: str = ...,
    prefix_header: None | str = ...,
    preprocessor_flags: list[str] = ...,
    propagated_target_sdk_version: None | str = ...,
    public_framework_headers: list[str] | dict[str, str] = ...,
    public_include_directories: list[str] = ...,
    public_system_include_directories: list[str] = ...,
    raw_headers: list[str] = ...,
    raw_headers_as_headers_mode: None | str = ...,
    reexport_all_header_dependencies: None | bool = ...,
    sdk_modules: list[str] = ...,
    serialize_debugging_options: None | bool = ...,
    shared_library_macho_file_type: str = ...,
    soname: None | str = ...,
    srcs: list[str | (str, list[str])] = ...,
    static_library_basename: None | str = ...,
    stripped: None | bool = ...,
    supported_platforms_regex: None | str = ...,
    supports_header_symlink_subtarget: bool = ...,
    supports_merged_linking: None | bool = ...,
    supports_shlib_interfaces: bool = ...,
    swift_compilation_mode: str = ...,
    swift_compiler_flags: list[str] = ...,
    swift_interface_compilation_enabled: bool = ...,
    swift_module_skip_function_bodies: bool = ...,
    swift_package_name: None | str = ...,
    swift_version: None | str = ...,
    target_sdk_version: None | str = ...,
    thin_lto: bool = ...,
    use_archive: None | bool = ...,
    use_submodules: bool = ...,
    uses_cxx_explicit_modules: bool = ...,
    uses_explicit_modules: bool = ...,
    uses_modules: bool = ...,
    validation_deps: list[str] = ...,
) -> None

An apple_library() rule represents a set of Objective-C/C++/Swift source files and is similar to a cxx_library() rule with which it shares many attributes. In addition to those common attributes, apple_library() has a some additional attributes that are specific to binaries intended to be built using the Apple toolchain. Note, however, that apple_library() and cxx_library() differ in the way that they import header files, in order to better accommodate existing conventions. See the sections for the headers and exported_headers attributes for more details.

Parameters​

  • name: name of the target

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

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

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

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

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

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

  • metadata: a key-value map of metadata associated with this target

  • tests: a list of targets that provide tests for this one

  • modifiers: an array of modifiers associated with this target

  • allow_cache_upload: Whether to allow uploading the output of this rule to be uploaded to cache when the action is executed locally if the configuration allows (i.e. there is a cache configured and the client has permission to write to it).

  • compiler_flags: Flags to use when compiling any of the above sources (which require compilation).

  • exported_deps: Dependencies that will also appear to belong to any rules that depend on this one. This has two effects: * Exported dependencies will also be included in the link line of dependents of this rules, but normal dependencies will not. * When reexport_all_header_dependencies = False, only exported headers of the rules specified here are re-exported.

  • exported_headers: The set of header files that are made available for inclusion to the source files in this target and all targets that transitively depend on this one. These should be specified as either a list of header files or a dictionary of header names to header files. The header names can contain forward slashes (/). If a list of header files is specified, the headers can be imported with #import "$HEADER_PATH_PREFIX/$HEADER_NAME" or, if a header file that belongs to the same rule is being imported, with #import "$HEADER_NAME", where $HEADER_PATH_PREFIX is the value of the target's header_path_prefix attribute, and $HEADER_NAME is the filename of the header file. If a dictionary is specified, each header can be imported with #import "$HEADER_NAME", where $HEADER_NAME is the key corresponding to this file. In this case, the header_path_prefix attribute is ignored. In either case, quotes in the import statements can be replaced with angle brackets.

  • exported_linker_flags: Flags to add to the linker command line when the output from this rule, or the output from any rule that transitively depends on this rule, is used in a link operation.

  • exported_platform_linker_flags: Platform-specific linker flags for this rule and for all rules that transitively depend on this rule. This argument is specified as a list of pairs where the first element in each pair is an un-anchored regex against which the platform name is matched. The regex should use java.util.regex.Pattern syntax. The second element in each pair is a list of linker flags. If the regex matches the platform, these flags are added to the linker command line when the output from this rule, or the output from any rule that transitively depends on this rule, is used in a link operation.

  • extra_xcode_files: When the project is generated, this is the list of files that will added to the project. Those files won't be added to the build phase "Compile Sources".

  • frameworks: A list of system frameworks that the code in this target uses. Each entry should be a path starting with $SDKROOT or $PLATFORM_DIR to denote that the rest of the path is relative to the root of the SDK used for the build or to the platform toolchain directory.

  • header_namespace: A path prefix when including headers of this target. Defaults to the path from the root of the repository to the directory where this target is defined. Can contain forward slashes (/), but cannot start with one. See headers for 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_PREFIX is the value of the target's header_path_prefix attribute, and $HEADER_NAME is the filename of the header file. If a dictionary is specified, each header can be imported with #import "$HEADER_NAME", where $HEADER_NAME is the key corresponding to this file. In this case, the header_path_prefix attribute is ignored. In either case, quotes in the import statements can be replaced with angle brackets.

  • include_directories: A list of include directories (with raw_headers) to be added to the compile command for compiling this target (via -I). An include directory is relative to the current package.

  • link_execution_preference: The execution preference for linking. Options are:

    • any : No preference is set, and the link action will be performed based on buck2's executor configuration.
    • full_hybrid : The link action will execute both locally and remotely, regardless of buck2's executor configuration (if the executor is capable of hybrid execution). The use_limited_hybrid setting of the hybrid executor is ignored.
    • local : The link action will execute locally if compatible on current host platform.
    • local_only : The link action will execute locally, and error if the current platform is not compatible.
    • remote : The link action will execute remotely if a compatible remote platform exists, otherwise locally.

    The default is None, expressing that no preference has been set on the target itself.

  • link_style: Determines whether to build and link this rule's dependencies statically or dynamically. Can be either static, static_pic or shared.

  • linker_extra_outputs: Declares extra outputs that the linker emits. These identifiers can be used in $(output ...) macros in linker_flags to interpolate the output path into the linker command line. Useful for custom linkers that emit extra output files.

  • linker_flags: Flags to add to the linker command line whenever the output from this rule is used in a link operation, such as linked into an executable or a shared library.

  • platform_compiler_flags: Platform specific compiler flags. These should be specified as a list of pairs where the first element is an un-anchored regex (in java.util.regex.Pattern syntax) against which the platform name is matched, and the second element is a list of flags to use when compiling the target's sources. See compiler_flags for more information.

  • platform_srcs: Platform specific source files. These should be specified as a list of pairs where the first element is an un-anchored regex (in java.util.regex.Pattern syntax) against which the platform name is matched, and the second element is either a list of source files or a list of tuples of source files and a list of compilation flags to be preprocessed, compiled and assembled if the platform matches the regex. See srcs for more information.

  • preprocessor_flags: Flags to use when preprocessing any of the above sources (which require preprocessing).

  • public_include_directories: A list of include directories (with raw_headers) to be added to the compile command for compiling this target and every target that depends on it (via -I). An include directory is relative to the current package.

  • public_system_include_directories: A list of include directories (with raw_headers) to be added to the compile command for compiling this target and every target that depends on it (via -isystem if the compiler supports it of via -I otherwise). An include directory is relative to the current package.

  • raw_headers: The set of header files that can be used for inclusion to the source files in the target and all targets that transitively depend on it. Buck doesn't add raw headers to the search path of a compiler/preprocessor automatically. include_directories and public_include_directories are the recommended way to add raw headers to the search path (they will be added via -I). compiler_flags, preprocessor_flags and exported_preprocessor_flags can also be used to add such raw headers to the search path if inclusion via -isystem or -iquote is needed. raw_headers cannot be used together with headers or exported_headers in the same target.

  • raw_headers_as_headers_mode: Controls whether raw_headers and *include_directories attributes should be automatically converted to headers and symlink trees and/or header maps via headers. Only has an effect if the cxx_toolchain has explicitly opted into supporting this behavior via a non-default value, even if the value is disabled.

  • reexport_all_header_dependencies: Whether to automatically re-export the exported headers of all dependencies.

    When this is set to false, only exported headers from exported_deps are re-exported.

  • srcs: The set of C, C++, Objective-C, Objective-C++, or assembly source files to be preprocessed, compiled, and assembled by this rule. We determine which stages to run on each input source based on its file extension. See the GCC documentation for more detail on how file extensions are interpreted. Each element can be either a string specifying a source file (e.g. '') or a tuple of a string specifying a source file and a list of compilation flags (e.g. ('', ['-Wall', '-Werror']) ). In the latter case the specified flags will be used in addition to the rule's other flags when preprocessing and compiling that file (if applicable).

  • target_sdk_version: The minimum OS version that the library target should support, overriding the minimum set in .buckconfig. When set, Buck will automatically add flags to both Objective-C and Swift compilation that will allow the use of the new APIs without guarding code inside availability checks.

Details​

Buck enables you to override components of the Apple toolchain with alternate tools, either from the Xcode search paths or from directories that you specify. See .buckconfig and .buckconfig for more information.

Examples:


apple_library(
  name = 'MyLibrary',
  deps = [
    ':OtherLibrary',
    '//Libraries:YetAnotherLibrary',
  ],
  preprocessor_flags = ['-fobjc-arc'],
  headers = [
    'MyHeader.h',
  ],
  srcs = [
    'MySource.m',
    'MySource.swift',
  ],
  frameworks = [
    '$SDKROOT/System/Library/Frameworks/UIKit.framework',
    '$SDKROOT/System/Library/Frameworks/Foundation.framework',
  ],
)

apple_package​

def apple_package(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    _apple_tools: str = ...,
    _ipa_compression_level: str,
    _ipa_package: str,
    bundle: str,
    contacts: list[str] = ...,
    default_host_platform: None | str = ...,
    default_platform: None | str = ...,
    ext: str = ...,
    labels: list[str] = ...,
    licenses: list[str] = ...,
    need_android_tools: bool = ...,
    package_name: None | str = ...,
    packager: None | str = ...,
    packager_args: list[str] = ...,
    prepackaged_validators: list[str | (str, list[str])] = ...,
) -> None

An apple_package() rule takes the output of an apple_bundle() rule and compresses it in an IPA (iOS App Store Package) file.

Parameters​

  • name: name of the target
  • default_target_platform: specifies the default target platform, used when no platforms are specified on the command line
  • target_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • exec_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with an execution platform
  • visibility: a list of visibility patterns restricting what targets can depend on this one
  • within_view: a list of visibility patterns restricting what this target can depend on
  • metadata: a key-value map of metadata associated with this target
  • tests: a list of targets that provide tests for this one
  • modifiers: an array of modifiers associated with this target

Details​

This rule can be customized using the config options .buckconfig and .buckconfig .

Examples:


apple_package(
  name = 'AppPackage',
  bundle = ':AppBundle',
)

apple_resource​

def apple_resource(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    codesign_entitlements: None | str = ...,
    codesign_flags_override: None | list[str] = ...,
    codesign_on_copy: bool = ...,
    contacts: list[str] = ...,
    content_dirs: list[str] = ...,
    default_host_platform: None | str = ...,
    destination: None | str = ...,
    dirs: list[str] = ...,
    files: list[str] = ...,
    labels: list[str] = ...,
    licenses: list[str] = ...,
    named_variants: dict[str, list[str]] = ...,
    resources_from_deps: list[str] = ...,
    skip_universal_resource_dedupe: bool = ...,
    variants: list[str] = ...,
) -> None

An apple_resource() rule contains sets of resource directories, files and file variants that can be bundled in an application bundle. This rule does not have any output on its own and can be built only as a dependency (either direct or transitive) of an apple_bundle() rule.

Parameters​

  • name: name of the target

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

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

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

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

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

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

  • metadata: a key-value map of metadata associated with this target

  • tests: a list of targets that provide tests for this one

  • modifiers: an array of modifiers associated with this target

  • destination: Specifies the destination in the final application bundle where resource will be copied. Possible values: "resources", "frameworks", "executables", "plugins", "xpcservices".

  • named_variants: Mapping from a variant name to the list of resource file paths which should be placed in an application bundle. Those files will be placed in a directory with name equal to the corresponding key in this mapping. Keys should end with .lproj suffix. (e.g. Base.lproj, en.lproj).

  • resources_from_deps: Set of build targets whose transitive apple_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_NAME is the name of the variant (e.g. Base, en). This argument makes it possible to use different resource files based on the active locale.

Details​

Examples:


apple_resource(
  name = 'Images',
  files = glob([
    '*.png',
  ]),
  dirs = [
    'PrettyImages',
  ],
)

apple_spm_package​

def apple_spm_package(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    _apple_tools: str = ...,
) -> None

Parameters​

  • name: name of the target
  • default_target_platform: specifies the default target platform, used when no platforms are specified on the command line
  • target_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • exec_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with an execution platform
  • visibility: a list of visibility patterns restricting what targets can depend on this one
  • within_view: a list of visibility patterns restricting what this target can depend on
  • metadata: a key-value map of metadata associated with this target
  • tests: a list of targets that provide tests for this one
  • modifiers: an array of modifiers associated with this target

apple_test​

def apple_test(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    _apple_toolchain: str = ...,
    _apple_tools: str = ...,
    _apple_xctoolchain: str = ...,
    _apple_xctoolchain_bundle_id: str = ...,
    _bundling_cache_buster: None | str = ...,
    _bundling_log_file_enabled: bool = ...,
    _bundling_log_file_level: None | str = ...,
    _code_signing_configuration: None | str = ...,
    _codesign_identities_command_override: None | str = ...,
    _codesign_type: None | str = ...,
    _compile_resources_locally_override: None | bool = ...,
    _dsymutil_extra_flags: list[str],
    _dsymutil_verify_dwarf: str,
    _embed_provisioning_profile_when_adhoc_code_signing: None | bool = ...,
    _enable_library_evolution: bool = ...,
    _fast_adhoc_signing_enabled_default: bool = ...,
    _fast_provisioning_profile_parsing_enabled: bool = ...,
    _incremental_bundling_enabled: bool = ...,
    _info_plist_identify_build_system_default: bool = ...,
    _inject_test_env: str = ...,
    _ios_booted_simulator: str = ...,
    _ios_unbooted_simulator: str = ...,
    _profile_bundling_enabled: bool = ...,
    _provisioning_profiles: str = ...,
    _resource_bundle: None | str = ...,
    _skip_adhoc_resigning_scrubbed_frameworks_default: bool = ...,
    _skip_adhoc_resigning_scrubbed_frameworks_override: None | bool = ...,
    _strict_provisioning_profile_search_default: bool = ...,
    _swift_enable_testing: bool = ...,
    _test_toolchain: str = ...,
    _use_entitlements_when_adhoc_code_signing: None | bool = ...,
    allow_cache_upload: None | bool = ...,
    asset_catalogs_compilation_options: dict[str, typing.Any] = ...,
    attrs_validators: None | list[str] = ...,
    binary: None | str = ...,
    bridging_header: None | str = ...,
    can_be_asset: None | bool = ...,
    code_signing_configuration: None | str = ...,
    codesign_flags: list[str] = ...,
    codesign_identity: None | str = ...,
    codesign_type: None | str = ...,
    compiler_flags: list[str] = ...,
    contacts: list[str] = ...,
    cxx_runtime_type: None | str = ...,
    default_host_platform: None | str = ...,
    default_platform: None | str = ...,
    defaults: dict[str, str] = ...,
    deps: list[str] = ...,
    destination_specifier: dict[str, str] = ...,
    devirt_enabled: bool = ...,
    diagnostics: dict[str, str] = ...,
    dsym_uses_parallel_linker: bool = ...,
    embed_provisioning_profile_when_adhoc_code_signing: bool = ...,
    embed_xctest_frameworks_in_test_host_app: None | bool = ...,
    enable_cxx_interop: bool = ...,
    enable_library_evolution: None | bool = ...,
    enable_private_swift_module: bool = ...,
    entitlements_file: None | str = ...,
    env: None | dict[str, str] = ...,
    executable_name: None | str = ...,
    exported_deps: list[str] = ...,
    exported_header_style: str = ...,
    exported_headers: list[str] | dict[str, str] = ...,
    exported_lang_platform_preprocessor_flags: dict[str, list[(str, list[str])]] = ...,
    exported_lang_preprocessor_flags: dict[str, list[str]] = ...,
    exported_linker_flags: list[str] = ...,
    exported_platform_deps: list[(str, list[str])] = ...,
    exported_platform_headers: list[(str, list[str] | dict[str, str])] = ...,
    exported_platform_linker_flags: list[(str, list[str])] = ...,
    exported_platform_preprocessor_flags: list[(str, list[str])] = ...,
    exported_post_linker_flags: list[str] = ...,
    exported_post_platform_linker_flags: list[(str, list[str])] = ...,
    exported_preprocessor_flags: list[str] = ...,
    extension: str,
    extra_xcode_files: list[str] = ...,
    extra_xcode_sources: list[str] = ...,
    fast_adhoc_signing_enabled: None | bool = ...,
    fat_lto: bool = ...,
    focused_list_target: None | str = ...,
    force_static: None | bool = ...,
    frameworks: list[str] = ...,
    header_namespace: None | str = ...,
    header_path_prefix: None | str = ...,
    headers: list[str] | dict[str, str] = ...,
    headers_as_raw_headers_mode: None | str = ...,
    include_directories: list[str] = ...,
    incremental_bundling_enabled: None | bool = ...,
    info_plist: str,
    info_plist_identify_build_system: None | bool = ...,
    info_plist_substitutions: dict[str, str] = ...,
    is_ui_test: bool = ...,
    labels: list[str] = ...,
    lang_compiler_flags: dict[str, list[str]] = ...,
    lang_platform_compiler_flags: dict[str, list[(str, list[str])]] = ...,
    lang_platform_preprocessor_flags: dict[str, list[(str, list[str])]] = ...,
    lang_preprocessor_flags: dict[str, list[str]] = ...,
    libraries: list[str] = ...,
    licenses: list[str] = ...,
    link_execution_preference: None | str = ...,
    link_group: None | str = ...,
    link_group_map: None | str | list[(str, list[(None | str | list[None | str], str, None | str | list[str], None | str)], None | dict[str, typing.Any])] = ...,
    link_ordering: None | str = ...,
    link_style: str = ...,
    link_whole: None | bool = ...,
    linker_extra_outputs: list[str] = ...,
    linker_flags: list[str] = ...,
    modular: bool = ...,
    module_name: None | str = ...,
    module_requires_cxx: bool = ...,
    platform_compiler_flags: list[(str, list[str])] = ...,
    platform_deps: list[(str, list[str])] = ...,
    platform_headers: list[(str, list[str] | dict[str, str])] = ...,
    platform_linker_flags: list[(str, list[str])] = ...,
    platform_preprocessor_flags: list[(str, list[str])] = ...,
    platform_srcs: list[(str, list[str | (str, list[str])])] = ...,
    post_linker_flags: list[str] = ...,
    post_platform_linker_flags: list[(str, list[str])] = ...,
    precompiled_header: None | str = ...,
    preferred_linkage: str = ...,
    prefix_header: None | str = ...,
    preprocessor_flags: list[str] = ...,
    propagated_target_sdk_version: None | str = ...,
    provisioning_profile_filter: None | str = ...,
    public_include_directories: list[str] = ...,
    public_system_include_directories: list[str] = ...,
    raw_headers: list[str] = ...,
    reexport_all_header_dependencies: None | bool = ...,
    resource_group: None | str = ...,
    resource_group_map: None | str = ...,
    run_test_separately: bool = ...,
    runner: None | str = ...,
    sanitizer_runtime_enabled: None | bool = ...,
    sdk_modules: list[str] = ...,
    serialize_debugging_options: None | bool = ...,
    skip_adhoc_resigning_scrubbed_frameworks: None | bool = ...,
    skip_copying_swift_stdlib: None | bool = ...,
    snapshot_reference_images_path: None | str = ...,
    soname: None | str = ...,
    specs: None | str = ...,
    srcs: list[str | (str, list[str])] = ...,
    static_library_basename: None | str = ...,
    strict_provisioning_profile_search: None | bool = ...,
    stripped: bool = ...,
    supported_platforms_regex: None | str = ...,
    supports_merged_linking: None | bool = ...,
    swift_compilation_mode: str = ...,
    swift_compiler_flags: list[str] = ...,
    swift_interface_compilation_enabled: bool = ...,
    swift_module_skip_function_bodies: bool = ...,
    swift_package_name: None | str = ...,
    swift_version: None | str = ...,
    target_sdk_version: None | str = ...,
    test_host_app: None | str = ...,
    test_re_capabilities: None | dict[str, str] = ...,
    test_re_use_case: None | str = ...,
    test_rule_timeout_ms: None | int = ...,
    thin_lto: bool = ...,
    try_skip_code_signing: None | bool = ...,
    ui_test_target_app: None | str = ...,
    use_entitlements_when_adhoc_code_signing: bool = ...,
    use_submodules: bool = ...,
    uses_cxx_explicit_modules: bool = ...,
    uses_explicit_modules: bool = ...,
    uses_modules: bool = ...,
    validation_deps: list[str] = ...,
    versioned_macos_bundle: bool = ...,
    xcode_product_type: None | str = ...,
) -> None

An apple_test() rule contains Objective-C/C++ code which can be built and used to test code contained in other rules. The tests can be executed by running buck test.

Parameters​

  • name: name of the target

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

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

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

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

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

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

  • metadata: a key-value map of metadata associated with this target

  • tests: a list of targets that provide tests for this one

  • modifiers: an array of modifiers associated with this target

  • allow_cache_upload: Whether to allow uploading the output of this rule to be uploaded to cache when the action is executed locally if the configuration allows (i.e. there is a cache configured and the client has permission to write to it).

  • compiler_flags: Flags to use when compiling any of the above sources (which require compilation).

  • embed_xctest_frameworks_in_test_host_app: Controls whether a marker constraint is added to the test_host_app.

  • extra_xcode_files: When the project is generated, this is the list of files that will added to the project. Those files won't be added to the build phase "Compile Sources".

  • frameworks: A list of system frameworks that the code in this target uses. Each entry should be a path starting with $SDKROOT or $PLATFORM_DIR to denote that the rest of the path is relative to the root of the SDK used for the build or to the platform toolchain directory.

  • header_path_prefix: A path prefix when including headers of this target. For example, headers from a library defined 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_PREFIX is the value of the target's header_path_prefix attribute, and $HEADER_NAME is the filename of the header file. If a dictionary is specified, each header can be imported with #import "$HEADER_NAME", where $HEADER_NAME is the key corresponding to this file. In this case, the header_path_prefix attribute is ignored. In either case, quotes in the import statements can be replaced with angle brackets.

  • info_plist: A path to an Info.plist file that will be placed in the bundle. The specified file will be processed by substituting variable names with their values (see info_plist_substitutions for more information).

  • info_plist_substitutions: A dictionary that assigns variable names to their values. It is used for variable substitution when processing the file specified in info_plist. For example if this argument is set to {'VAR': 'MyValue'}, then each occurrence of $(VAR) or ${VAR} in the file will be replaced by MyValue.

  • labels: A list of labels to be applied to these tests. These labels are arbitrary text strings and have no meaning within buck itself. They can, however, have meaning for you as a test author (e.g., smoke or fast). A label can be used to filter or include a specific test rule when executing buck test

  • link_execution_preference: The execution preference for linking. Options are:

    • any : No preference is set, and the link action will be performed based on buck2's executor configuration.
    • full_hybrid : The link action will execute both locally and remotely, regardless of buck2's executor configuration (if the executor is capable of hybrid execution). The use_limited_hybrid setting of the hybrid executor is ignored.
    • local : The link action will execute locally if compatible on current host platform.
    • local_only : The link action will execute locally, and error if the current platform is not compatible.
    • remote : The link action will execute remotely if a compatible remote platform exists, otherwise locally.

    The default is None, expressing that no preference has been set on the target itself.

  • linker_flags: Flags to add to the linker command line whenever the output from this rule is used in a link operation, such as linked into an executable or a shared library.

  • platform_compiler_flags: Platform specific compiler flags. These should be specified as a list of pairs where the first element is an un-anchored regex (in java.util.regex.Pattern syntax) against which the platform name is matched, and the second element is a list of flags to use when compiling the target's sources. See compiler_flags for more information.

  • platform_srcs: Platform specific source files. These should be specified as a list of pairs where the first element is an un-anchored regex (in java.util.regex.Pattern syntax) against which the platform name is matched, and the second element is either a list of source files or a list of tuples of source files and a list of compilation flags to be preprocessed, compiled and assembled if the platform matches the regex. See srcs for more information.

  • preprocessor_flags: Flags to use when preprocessing any of the above sources (which require preprocessing).

  • srcs: The set of C, C++, Objective-C, Objective-C++, or assembly source files to be preprocessed, compiled, and assembled by this rule. We determine which stages to run on each input source based on its file extension. See the GCC documentation for more detail on how file extensions are interpreted. Each element can be either a string specifying a source file (e.g. '') or a tuple of a string specifying a source file and a list of compilation flags (e.g. ('', ['-Wall', '-Werror']) ). In the latter case the specified flags will be used in addition to the rule's other flags when preprocessing and compiling that file (if applicable).

  • target_sdk_version: The minimum OS version that the library target should support, overriding the minimum set in .buckconfig. When set, Buck will automatically add flags to both Objective-C and Swift compilation that will allow the use of the new APIs without guarding code inside availability checks.

  • test_host_app: A build target identifying an apple_bundle() rule that builds an application bundle. Output of the specified rule will be used as a test host of this test. This implies run_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's linker_flags (this will suppress undefined reference errors during compilation, but if the symbols do not exist, it might result in runtime crashes).

  • test_re_capabilities: An optional dictionary with the RE capabilities for the test execution. Overrides a default selection mechanism.

  • test_re_use_case: An optional name of the RE use case for the test execution. Overrides a default selection mechanism.

Details​

Examples:


apple_test(
  name = 'MyTest',
  info_plist = 'MyTest-Info.plist',
  preprocessor_flags = ['-fobjc-arc'],
  srcs = [
    'MyTest.m',
  ],
  deps = [
    ':MyLibrary',
  ],
  frameworks = [
    '$SDKROOT/System/Library/Frameworks/Foundation.framework',
    '$SDKROOT/System/Library/Frameworks/UIKit.framework',
    '$PLATFORM_DIR/Developer/Library/Frameworks/XCTest.framework',
  ],
)

apple_toolchain​

def apple_toolchain(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _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,
    mapc: None | str = ...,
    merge_index_store: str = ...,
    min_version: str = ...,
    momc: str,
    objdump: None | str = ...,
    placeholder_tool: None | str = ...,
    platform_path: None | str = ...,
    requires_xcode_version_match: bool = ...,
    sdk_environment: None | str = ...,
    sdk_name: str = ...,
    sdk_path: None | str = ...,
    swift_toolchain: None | str = ...,
    version: None | str = ...,
    watch_kit_stub_binary: None | str = ...,
    work_around_dsymutil_lto_stack_overflow_bug: None | bool = ...,
    xcode_build_version: None | str = ...,
    xcode_version: None | str = ...,
    xctest: str,
) -> None

Parameters​

  • name: name of the target
  • default_target_platform: specifies the default target platform, used when no platforms are specified on the command line
  • target_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • exec_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with an execution platform
  • visibility: a list of visibility patterns restricting what targets can depend on this one
  • within_view: a list of visibility patterns restricting what this target can depend on
  • metadata: a key-value map of metadata associated with this target
  • tests: a list of targets that provide tests for this one
  • modifiers: an array of modifiers associated with this target

apple_toolchain_set​

def apple_toolchain_set(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _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 target
  • default_target_platform: specifies the default target platform, used when no platforms are specified on the command line
  • target_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • exec_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with an execution platform
  • visibility: a list of visibility patterns restricting what targets can depend on this one
  • within_view: a list of visibility patterns restricting what this target can depend on
  • metadata: a key-value map of metadata associated with this target
  • tests: a list of targets that provide tests for this one
  • modifiers: an array of modifiers associated with this target

apple_universal_executable​

def apple_universal_executable(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    _apple_toolchain: str = ...,
    _apple_tools: str = ...,
    _dsymutil_extra_flags: list[str],
    _dsymutil_verify_dwarf: str,
    dsym_uses_parallel_linker: bool = ...,
    executable: str,
    executable_name: None | str = ...,
    labels: list[str] = ...,
    split_arch_dsym: bool = ...,
    universal: None | bool = ...,
) -> None

An apple_universal_executable() rule takes a target via its binary attribute, builds it for multiple architectures and combines the result into a single binary using lipo.

Parameters​

  • name: name of the target

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

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

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

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

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

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

  • metadata: a key-value map of metadata associated with this target

  • tests: a list of targets that provide tests for this one

  • modifiers: an array of modifiers associated with this target

  • executable: A build target identifying the binary which will be built for multiple architectures. The target will be transitioned into different configurations, with distinct architectures.

    The target can be one of:

    • apple_binary() and cxx_binary()
    • [shared] subtarget of apple_library() and cxx_library()
    • apple_library() and cxx_library() which have preferred_linkage = shared attribute

  • executable_name: By default, the name of the universal executable is same as the name of the binary from the binary target attribute. Set executable_name to override the default.

  • split_arch_dsym: If enabled, each architecture gets its own dSYM binary. Use this if the combined universal dSYM binary exceeds 4GiB.

  • universal: Controls whether the output is universal binary. Any value overrides the presence of the config//cpu/constraints:universal-enabled constraint. Read the rule docs for more information on resolution.

Details​

The output of the rule is a universal binary:

  • If config//cpu/constraints:universal-enabled is present in the target platform.
  • If the universal attribute is set to True.

If none of the conditions are met, then the rule acts as a nop alias().

The universal attribute, if present, takes precedence over constraint. For example, if universal = False, then the presence of the constraint would not affect the output.

apple_bundle() supports building of universal binaries, apple_universal_executable() is only needed if you have a standalone binary target which is not embedded in an apple_bundle() (usually a CLI tool).

apple_xcuitest​

def apple_xcuitest(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    _apple_toolchain: str = ...,
    _apple_tools: str = ...,
    _apple_xctoolchain: str = ...,
    _apple_xctoolchain_bundle_id: str = ...,
    _bundling_cache_buster: None | str = ...,
    _bundling_log_file_enabled: bool = ...,
    _bundling_log_file_level: None | str = ...,
    _code_signing_configuration: None | str = ...,
    _codesign_identities_command_override: None | str = ...,
    _codesign_type: None | str = ...,
    _compile_resources_locally_override: None | bool = ...,
    _embed_provisioning_profile_when_adhoc_code_signing: None | bool = ...,
    _enable_library_evolution: bool = ...,
    _fast_adhoc_signing_enabled_default: bool = ...,
    _fast_provisioning_profile_parsing_enabled: bool = ...,
    _incremental_bundling_enabled: bool = ...,
    _info_plist_identify_build_system_default: bool = ...,
    _profile_bundling_enabled: bool = ...,
    _provisioning_profiles: str = ...,
    _resource_bundle: None | str = ...,
    _skip_adhoc_resigning_scrubbed_frameworks_default: bool = ...,
    _skip_adhoc_resigning_scrubbed_frameworks_override: None | bool = ...,
    _strict_provisioning_profile_search_default: bool = ...,
    _use_entitlements_when_adhoc_code_signing: None | bool = ...,
    binary: None | str = ...,
    code_signing_configuration: None | str = ...,
    codesign_identity: None | str = ...,
    codesign_type: None | str = ...,
    dsym_uses_parallel_linker: bool = ...,
    embed_provisioning_profile_when_adhoc_code_signing: bool = ...,
    enable_library_evolution: None | bool = ...,
    entitlements_file: None | str = ...,
    extension: str = ...,
    fast_adhoc_signing_enabled: None | bool = ...,
    incremental_bundling_enabled: bool = ...,
    info_plist: str,
    info_plist_identify_build_system: None | bool = ...,
    info_plist_substitutions: dict[str, str] = ...,
    provisioning_profile_filter: None | str = ...,
    skip_adhoc_resigning_scrubbed_frameworks: None | bool = ...,
    strict_provisioning_profile_search: None | bool = ...,
    target_sdk_version: None | str = ...,
    test_bundle: str,
    use_entitlements_when_adhoc_code_signing: bool = ...,
    validation_deps: list[str] = ...,
    versioned_macos_bundle: bool = ...,
) -> None

Parameters​

  • name: name of the target
  • default_target_platform: specifies the default target platform, used when no platforms are specified on the command line
  • target_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • exec_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with an execution platform
  • visibility: a list of visibility patterns restricting what targets can depend on this one
  • within_view: a list of visibility patterns restricting what this target can depend on
  • metadata: a key-value map of metadata associated with this target
  • tests: a list of targets that provide tests for this one
  • modifiers: an array of modifiers associated with this target

command_alias​

def command_alias(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _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 target

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

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

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

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

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

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

  • metadata: a key-value map of metadata associated with this target

  • tests: a list of targets that provide tests for this one

  • modifiers: an array of modifiers associated with this target

  • args: A string of arguments that is passed to the executable specified by exe at startup. These arguments support a subset of Buck's string 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 by exe on startup. Environment variables support the same macros as arguments.

  • exe: A build target for a rule that outputs an executable, such as an sh_binary(), or an executable source file.

  • platform_exe: A mapping from platforms to build target. enables you to override exe per 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 :

    • FREEBSD
    • LINUX
    • MACOS
    • WINDOWS

Details​

Example uses include running a command written in a scripting language with a specific interpreter, and transparently wrapping sub-commands of a binary.

You can reference a command_alias target in the cmd parameter of a genrule() by using the exe macro:



$(exe //path/to:target)

Examples:


# Combining an interpreter and a script

cxx_binary(
    name = "node-js",
    srcs = [
        # ...
    ],
    headers = [
        # ...
    ],
)

export_file(
    name = "scripts"
)

command_alias(
    name = "server",
    exe = ":node-js",
    args = [
        "$(location :scripts)/start-server.js",
    ],
)


# Exposing sub commands

export_file(
    name = "yarn",
    src = "yarn.sh",
)

command_alias(
    name = "add",
    exe = ":yarn",
    args = ["add"],
)

command_alias(
    name = "install",
    exe = ":yarn",
    args = ["install"],
)

command_alias(
    name = "run",
    exe = ":yarn",
    args = ["run"],
)


# Platform specific commands

export_file(
    name = "node-windows",
    src = "windows/node.exe",
)

export_file(
    name = "node-linux",
    src = "linux/node",
)

export_file(
    name = "node-macos",
    src = "macos/node",
)

command_alias(
    name = "node",
    platform_exe = {
        "windows": ":node-windows",
        "linux": ":node-linux",
        "macos": ":node-macos",
    },
)

config_setting​

def config_setting(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    constraint_values: list[str] = ...,
    values: dict[str, str] = ...,
) -> None

Parameters​

  • name: name of the target
  • default_target_platform: specifies the default target platform, used when no platforms are specified on the command line
  • target_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • exec_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with an execution platform
  • visibility: a list of visibility patterns restricting what targets can depend on this one
  • within_view: a list of visibility patterns restricting what this target can depend on
  • metadata: a key-value map of metadata associated with this target
  • tests: a list of targets that provide tests for this one
  • modifiers: an array of modifiers associated with this target

configuration_alias​

def configuration_alias(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    actual: str,
) -> None

Parameters​

  • name: name of the target
  • default_target_platform: specifies the default target platform, used when no platforms are specified on the command line
  • target_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • exec_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with an execution platform
  • visibility: a list of visibility patterns restricting what targets can depend on this one
  • within_view: a list of visibility patterns restricting what this target can depend on
  • metadata: a key-value map of metadata associated with this target
  • tests: a list of targets that provide tests for this one
  • modifiers: an array of modifiers associated with this target

configured_alias​

def configured_alias(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    actual: str,
    configured_actual: None | (str, str) = ...,
    contacts: list[str] = ...,
    default_host_platform: None | str = ...,
    fallback_actual: None | str = ...,
    labels: list[str] = ...,
    licenses: list[str] = ...,
    platform: None | str = ...,
    propagate_flavors: bool = ...,
) -> None

Parameters​

  • name: name of the target
  • default_target_platform: specifies the default target platform, used when no platforms are specified on the command line
  • target_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • exec_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with an execution platform
  • visibility: a list of visibility patterns restricting what targets can depend on this one
  • within_view: a list of visibility patterns restricting what this target can depend on
  • metadata: a key-value map of metadata associated with this target
  • tests: a list of targets that provide tests for this one
  • modifiers: an array of modifiers associated with this target

constraint_setting​

def constraint_setting(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
) -> None

Parameters​

  • name: name of the target
  • default_target_platform: specifies the default target platform, used when no platforms are specified on the command line
  • target_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • exec_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with an execution platform
  • visibility: a list of visibility patterns restricting what targets can depend on this one
  • within_view: a list of visibility patterns restricting what this target can depend on
  • metadata: a key-value map of metadata associated with this target
  • tests: a list of targets that provide tests for this one
  • modifiers: an array of modifiers associated with this target

constraint_value​

def constraint_value(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    constraint_setting: str,
) -> None

Parameters​

  • name: name of the target
  • default_target_platform: specifies the default target platform, used when no platforms are specified on the command line
  • target_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • exec_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with an execution platform
  • visibility: a list of visibility patterns restricting what targets can depend on this one
  • within_view: a list of visibility patterns restricting what this target can depend on
  • metadata: a key-value map of metadata associated with this target
  • tests: a list of targets that provide tests for this one
  • modifiers: an array of modifiers associated with this target

core_data_model​

def core_data_model(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    contacts: list[str] = ...,
    default_host_platform: None | str = ...,
    labels: list[str] = ...,
    licenses: list[str] = ...,
    module: None | str = ...,
    path: str,
) -> None

An core_data_model() rule contains models for Apple's Core Data framework. This rule does not have any output on its own and can be built only as a dependency (either direct or transitive) of an apple_bundle() rule in which case all core_data_model() rules that the bundle rule depends on are merged and placed into the final output bundle together.

Parameters​

  • name: name of the target
  • default_target_platform: specifies the default target platform, used when no platforms are specified on the command line
  • target_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • exec_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with an execution platform
  • visibility: a list of visibility patterns restricting what targets can depend on this one
  • within_view: a list of visibility patterns restricting what this target can depend on
  • metadata: a key-value map of metadata associated with this target
  • tests: a list of targets that provide tests for this one
  • modifiers: an array of modifiers associated with this target

Details​

Examples:


core_data_model(
  name = 'MyCoreDataModel',
  path = 'MyCoreDataModel.xcdatamodeld',
)

csharp_library​

def csharp_library(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    _csharp_toolchain: str = ...,
    compiler_flags: list[str] = ...,
    contacts: list[str] = ...,
    default_host_platform: None | str = ...,
    deps: list[str] = ...,
    dll_name: str = ...,
    framework_ver: str,
    labels: list[str] = ...,
    licenses: list[str] = ...,
    resources: dict[str, str] = ...,
    srcs: list[str] = ...,
) -> None

A csharp_library() rule builds a .Net library from the supplied set of C# source files and dependencies by invoking csc.

Parameters​

  • name: name of the target
  • default_target_platform: specifies the default target platform, used when no platforms are specified on the command line
  • target_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • exec_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with an execution platform
  • visibility: a list of visibility patterns restricting what targets can depend on this one
  • within_view: a list of visibility patterns restricting what this target can depend on
  • metadata: a key-value map of metadata associated with this target
  • tests: a list of targets that provide tests for this one
  • modifiers: an array of modifiers associated with this target
  • compiler_flags: The set of additional compiler flags to pass to the compiler.
  • deps: The set of targets or system-provided assemblies to rely on. Any values that are targets must be either csharp_library or prebuilt_dotnet_library instances.
  • dll_name: The output name of the dll. This allows you to specify the name of the dll exactly. When this is not set, the dll will be named after the short name of the target.
  • framework_ver: The version of the .Net framework that this library targets. This is one of 'net35', 'net40', 'net45' and 'net46'.
  • resources: Resources that should be embedded within the built DLL. The format is the name of the resource once mapped into the DLL as the key, and the value being the resource that should be merged. This allows non-unique keys to be identified quickly.
  • srcs: The collection of source files to compile.

Details​

Examples:

For more examples, check out our integration tests.


csharp_library(
  name = 'simple',
  dll_name = 'Cake.dll',
  framework_ver = 'net46',
  srcs = [
    'Hello.cs',
  ],
  resources = {
    'greeting.txt': '//some:target',
  },
  deps=[
    ':other',
    'System.dll',
  ],
)

prebuilt_dotnet_library(
  name = 'other',
  assembly = 'other-1.0.dll',
)

cxx_binary​

def cxx_binary(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    _build_info: dict[str, typing.Any] = ...,
    _cxx_hacks: str = ...,
    _cxx_toolchain: str = ...,
    allow_cache_upload: None | bool = ...,
    anonymous_link_groups: bool = ...,
    auto_link_groups: bool = ...,
    binary_linker_flags: list[str] = ...,
    bolt_flags: list[str] = ...,
    bolt_profile: None | str = ...,
    compiler_flags: list[str] = ...,
    constraint_overrides: list[str] = ...,
    contacts: list[str] = ...,
    coverage_instrumentation_compiler_flags: list[str] = ...,
    cxx_runtime_type: None | str = ...,
    default_host_platform: None | str = ...,
    default_platform: None | str = ...,
    defaults: dict[str, str] = ...,
    deps: list[str] = ...,
    deps_query: None | str = ...,
    devirt_enabled: bool = ...,
    distributed_thinlto_partial_split_dwarf: bool = ...,
    enable_distributed_thinlto: bool = ...,
    executable_name: None | str = ...,
    exported_needs_coverage_instrumentation: bool = ...,
    fat_lto: bool = ...,
    focused_list_target: None | str = ...,
    frameworks: list[str] = ...,
    header_namespace: None | str = ...,
    headers: list[str] | dict[str, str] = ...,
    headers_as_raw_headers_mode: None | str = ...,
    include_directories: list[str] = ...,
    labels: list[str] = ...,
    lang_compiler_flags: dict[str, list[str]] = ...,
    lang_platform_compiler_flags: dict[str, list[(str, list[str])]] = ...,
    lang_platform_preprocessor_flags: dict[str, list[(str, list[str])]] = ...,
    lang_preprocessor_flags: dict[str, list[str]] = ...,
    libraries: list[str] = ...,
    licenses: list[str] = ...,
    link_deps_query_whole: bool = ...,
    link_execution_preference: None | str = ...,
    link_group: None | str = ...,
    link_group_deps: list[str] = ...,
    link_group_map: None | str | list[(str, list[(None | str | list[None | str], str, None | str | list[str], None | str)], None | dict[str, typing.Any])] = ...,
    link_group_min_binary_node_count: None | int = ...,
    link_group_public_deps_label: None | str = ...,
    link_ordering: None | str = ...,
    link_style: None | str = ...,
    link_whole: bool = ...,
    linker_extra_outputs: list[str] = ...,
    linker_flags: list[str] = ...,
    platform_compiler_flags: list[(str, list[str])] = ...,
    platform_deps: list[(str, list[str])] = ...,
    platform_headers: list[(str, list[str] | dict[str, str])] = ...,
    platform_linker_flags: list[(str, list[str])] = ...,
    platform_override: None | 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] = ...,
    raw_headers_as_headers_mode: None | str = ...,
    resources: list[str] | dict[str, str] = ...,
    separate_debug_info: bool = ...,
    srcs: list[str | (str, list[str])] = ...,
    standalone_extensions: None | bool = ...,
    thin_lto: bool = ...,
    use_header_units: bool = ...,
    version_universe: None | str = ...,
    weak_framework_names: list[str] = ...,
) -> None

A cxx_binary() rule builds a native executable from the supplied set of C/C++ source files and dependencies. If C/C++ library dependencies are listed, the generated native executable will request and link against their static archives (which are *not* built using PIC).

Parameters​

  • name: name of the target

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

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

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

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

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

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

  • metadata: a key-value map of metadata associated with this target

  • tests: a list of targets that provide tests for this one

  • modifiers: an array of modifiers associated with this target

  • _build_info: Build info that is passed along here will be late-stamped into a fb_build_info section on the output binary

  • allow_cache_upload: Whether to allow uploading the output of this rule to be uploaded to cache when the action is executed locally if the configuration allows (i.e. there is a cache configured and the client has permission to write to it).

  • compiler_flags: Flags to use when compiling any of the above sources (which require compilation).

  • deps_query: Status: experimental/unstable. The deps query takes a query string that accepts the following query functions, and appends the output of the query to the declared deps:

    • attrfilter

    • deps

    • except

    • intersect

    • filter

    • kind

    • set

    • union

    The macro $declared_deps may be used anywhere a target literal pattern is expected in order to refer to the explicit deps of this rule as they appear in the rule's definition. For example, if your build rule declares


      android_library(
        name = 'lib',
        deps = ['//foo:foo'],
        deps_query = '$declared_deps',
      )

    then the macro $declared_deps would be expanded to a 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.

  • 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. 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 name can contain forward slashes (/). The headers can be included with #include "$HEADER_NAMESPACE/$HEADER_NAME" or #include <$HEADER_NAMESPACE/$HEADER_NAME> , where $HEADER_NAMESPACE is the value of the target's header_namespace attribute, and $HEADER_NAME is the header name if specified, and the filename of the header file otherwise. See header_namespace for more information.

  • include_directories: A list of include directories (with raw_headers) to be added to the compile command for compiling this target (via -I). An include directory is relative to the current package.

  • link_execution_preference: The execution preference for linking. Options are:

    • any : No preference is set, and the link action will be performed based on buck2's executor configuration.
    • full_hybrid : The link action will execute both locally and remotely, regardless of buck2's executor configuration (if the executor is capable of hybrid execution). The use_limited_hybrid setting of the hybrid executor is ignored.
    • local : The link action will execute locally if compatible on current host platform.
    • local_only : The link action will execute locally, and error if the current platform is not compatible.
    • remote : The link action will execute remotely if a compatible remote platform exists, otherwise locally.

    The default is None, expressing that no preference has been set on the target itself.

  • link_group_deps: Additional targets to traverse when building link groups, but which should not be direct dependencies of the main executable.

  • link_group_public_deps_label: Surface nodes with this label as "public" nodes in the main executable when linking with with link groups.

  • link_style: Determines whether to build and link this rule's dependencies statically or dynamically. Can be either static, static_pic or shared.

  • linker_extra_outputs: Declares extra outputs that the linker emits. These identifiers can be used in $(output ...) macros in linker_flags to interpolate the output path into the linker command line. Useful for custom linkers that emit extra output files.

  • linker_flags: Flags to add to the linker command line whenever the output from this rule is used in a link operation, such as linked into an executable or a shared library.

  • platform_compiler_flags: Platform specific compiler flags. These should be specified as a list of pairs where the first element is an un-anchored regex (in java.util.regex.Pattern syntax) against which the platform name is matched, and the second element is a list of flags to use when compiling the target's sources. See compiler_flags for more information.

  • platform_headers: Platform specific header files. These should be specified as a list of pairs where the first element is an un-anchored regex (in java.util.regex.Pattern syntax) against which the platform name is matched, and the second element is either a list of header files or a dictionary of header names to header files that will be made available for inclusion to the source files in the target if the platform matches the regex. See headers for more information.

  • platform_linker_flags: Platform-specific linker flags. This argument is specified as a list of pairs where the first element in each pair is an un-anchored regex against which the platform name is matched. The regex should use java.util.regex.Pattern syntax. The second element in each pair is a list of linker flags. If the regex matches the platform, these flags are added to the linker command line when the output from this rule is used in a link operation.

  • platform_preprocessor_flags: Platform specific preprocessor flags. These should be specified as a list of pairs where the first element is an un-anchored regex (in java.util.regex.Pattern syntax) against which the platform name is matched, and the second element is a list of flags to use when preprocessing the target's sources. See preprocessor_flags for more information.

  • platform_srcs: Platform specific source files. These should be specified as a list of pairs where the first element is an un-anchored regex (in java.util.regex.Pattern syntax) against which the platform name is matched, and the second element is either a list of source files or a list of tuples of source files and a list of compilation flags to be preprocessed, compiled and assembled if the platform matches the regex. See srcs for more information.

  • preprocessor_flags: Flags to use when preprocessing any of the above sources (which require preprocessing).

  • raw_headers: The set of header files that can be used for inclusion to the source files in the target and all targets that transitively depend on it. Buck doesn't add raw headers to the search path of a compiler/preprocessor automatically. include_directories and public_include_directories are the recommended way to add raw headers to the search path (they will be added via -I). compiler_flags, preprocessor_flags and exported_preprocessor_flags can also be used to add such raw headers to the search path if inclusion via -isystem or -iquote is needed. raw_headers cannot be used together with headers or exported_headers in the same target.

  • raw_headers_as_headers_mode: Controls whether raw_headers and *include_directories attributes should be automatically converted to headers and symlink trees and/or header maps via headers. Only has an effect if the cxx_toolchain has explicitly opted into supporting this behavior via a non-default value, even if the value is disabled.

  • srcs: The set of C, C++, Objective-C, Objective-C++, or assembly source files to be preprocessed, compiled, and assembled by this rule. We determine which stages to run on each input source based on its file extension. See the GCC documentation for more detail on how file extensions are interpreted. Each element can be either a string specifying a source file (e.g. '') or a tuple of a string specifying a source file and a list of compilation flags (e.g. ('', ['-Wall', '-Werror']) ). In the latter case the specified flags will be used in addition to the rule's other flags when preprocessing and compiling that file (if applicable).

Details​

Examples:


# A rule that builds a C/C++ native executable from a single .cpp file
# its corresponding header, and a C/C++ library dependency.
cxx_binary(
  name = 'echo',
  srcs = [
    'echo.cpp',
  ],
  headers = [
    'echo.h',
  ],
  deps = [
    ':util',
  ],
)

cxx_library(
  name = 'util',
  srcs = [
    'util.cpp',
  ],
  headers = [
    'util.h',
  ],
)

# To build without stripping:
buck build :echo

# To build with stripping debug symbols only:
buck build :echo#strip-debug

cxx_genrule​

def cxx_genrule(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    _build_only_native_code: bool = ...,
    _cxx_toolchain: str = ...,
    _exec_os_type: str = ...,
    _genrule_toolchain: str = ...,
    always_print_stderr: bool = ...,
    bash: None | str = ...,
    cacheable: None | bool = ...,
    cmd: None | str = ...,
    cmd_exe: None | str = ...,
    contacts: list[str] = ...,
    default_host_platform: None | str = ...,
    default_outs: None | list[str] = ...,
    enable_sandbox: None | bool = ...,
    env: dict[str, str] = ...,
    environment_expansion_separator: None | str = ...,
    labels: list[str] = ...,
    licenses: list[str] = ...,
    metadata_env_var: None | str = ...,
    metadata_path: None | str = ...,
    need_android_tools: bool = ...,
    no_outputs_cleanup: bool = ...,
    out: None | str = ...,
    outs: None | dict[str, list[str]] = ...,
    remote: None | bool = ...,
    remote_execution_dependencies: list[dict[str, str]] = ...,
    srcs: list[str] | dict[str, str] = ...,
    type: None | str = ...,
    weight: None | int = ...,
) -> None

A cxx_genrule() enables you to run shell commands as part of the Buck build process. A cxx_genrule() exposes - through a set of string parameter macros and variables - information about the tools and configuration options used by the Buck environment, specifically those related to the C/C++ toolchain.

Parameters​

  • name: name of the target

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

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

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

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

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

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

  • metadata: a key-value map of metadata associated with this target

  • tests: a list of targets that provide tests for this one

  • modifiers: an array of modifiers associated with this target

  • bash: A platform-specific version of the shell command parameter cmd. It runs on Linux and UNIX systems—including OSX—on which bash is installed. It has a higher priority than cmd. The bash argument is run with /usr/bin/env bash -c. It has access to the same set of macros and variables as the cmd argument.

  • cmd: The shell command to run to generate the output file. It is the fallback of bash and cmd_exe. The shell command can access information about the buck build environment through a set of macros, parameterized macros, and variables.

    Macros​

    The following macros are available to the shell command and are accessed using the following syntax.

    $(<macro>)

    Example:

    $(cc)

    $(cc) Path to the C compiler.

    $(cxx) Path to the C++ compiler.

    $(cflags) Flags passed to the C compiler.

    $(cppflags) Flags passed to the C preprocessor.

    $(cxxflags) Flags passed to the C++ compiler.

    $(cxxppflags) Flags to pass to the C++ preprocessor.

    $(ld) Path to the linker.

    $(ldflags-pic) Flags passed to the linker for binaries that use position-independent code (PIC).

    $(ldflags-pic-filter <pattern>) Flags passed to the linker for binaries that use position-independent code (PIC). Use the pattern parameter to specify a regular expression that matches the build targets that use these flags.

    $(ldflags-shared) Flags passed to the linker for shared libraries, such as dynamic-link libraries (DLLs).

    $(ldflags-shared-filter <pattern>) Flags passed to the linker for shared libraries, such as dynamic-link libraries (DLLs). Use the pattern parameter to specify a regular expression that matches the build targets that use these flags.

    $(ldflags-static) Flags passed to the linker for statically-linked libraries.

    $(ldflags-static-filter <pattern>) Flags passed to the linker for statically-linked libraries. Use the pattern parameter to specify a regular expression that matches the build targets that use these flags.

    $(platform-name) The platform flavor with which this cxx_genrule was specified.

    Parameterized Macros​

    It is also possible to expand references to other rules within the shell command, using the following subset of the builtin string parameter macros . Note that all build rules expanded in the command are automatically considered to be dependencies of 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.

    $(exe //path/to:target) Expands to the commands necessary to run the executable generated by the specified build rule. For a C++ executable, this will typically just be the name of the output executable itself, such as main. If the specified build rule does not generate an executable output, an exception will be thrown and the build will fail.

    $(location //path/to:target) Expands to the path of the output of the build rule. This means that you can refer to these without needing to be aware of how Buck is storing data on the disk mid-build.

    Variables​

    Finally, Buck adds the following variables to the environment in which the shell command runs. They are accessed using the following syntax. Note the use of braces rather than parentheses.

    ${<variable>}

    Example:

    ${SRCS}

    ${SRCS} A string expansion of 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 the to which sources are copied prior to running the command.

    ${OUT} The output file for the genrule(). The file specified by this variable must always be written by this command. If not, the execution of this rule will be considered a failure, halting the build process.

    ${TMP} A temporary directory which can be used for intermediate results and will not be bundled into the output.

  • cmd_exe: A platform-specific version of the shell command parameter cmd. It runs on Windows and has a higher priority than cmd. The cmd_exe argument is run with cmd.exe /v:off /c. It has access to the same set of macros and variables as the cmd argument.

  • enable_sandbox: Whether this target should be executed in a sandbox or not.

  • env: A map of variables to be set in the environment where the shell command is run.

  • environment_expansion_separator: The delimiter between paths in environment variables, such as SRCS, that can contain multiple paths. It can be useful to specify this parameter if the paths could contain spaces.

  • out: The name of the output file or directory. The complete path to this argument is provided to the shell command through the OUT environment variable.

  • srcs: Either a list or a map of the source files which Buck makes available to the shell command at the path in the SRCDIR environment variable. If you specify a list, the source files are the names in the list. If you specify a map, the source files are made available as the names in the keys of the map, where the values of the map are the original source file names.

  • type: Specifies the type of this genrule. This is used for logging and is particularly useful for grouping genrules that share an underlying logical "type".

    For example, if you have the following cxx_genrule defined in the root directory of your Buck project



    cxx_genrule(
      name = 'cxx_gen',
      type = 'epilog',
      cmd  = 'touch finish.txt; cp finish.txt $OUT',
      out  = 'finish.txt'
    )

    then the following buck query command



    buck query "attrfilter( type, 'epilog', '//...' )"

    returns



    //:cxx_gen

  • weight: How many local slots these genrule should take when executing locally.

Details​

The information exposed through these tools and configuration options is a reflection of: Buck's built-in settings, the settings in .buckconfig and .buckconfig.local, and the result of various command-line overrides specified through the common_parameters command-line option.

This information is available only to the shell commands specified in the cxx_genrule. The information is not available to other arguments of the rule.

A cxx_genrule() can be an input to another cxx_genrule().

Note that if you specify the cxx_genrule as a command-line target to buck build, you must include a platform flavor. For example:



buck build :cxx_gr_name#iphonesimulator-x86_64

You could also just specify the default platform flavor explicitly:



buck build :cxx_gr_name#default

cxx_library​

def cxx_library(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    _create_third_party_build_root: str = ...,
    _cxx_hacks: str = ...,
    _cxx_toolchain: str = ...,
    _is_building_android_binary: bool = ...,
    _meta_apple_library_validation_enabled: bool = ...,
    allow_cache_upload: None | bool = ...,
    archive_allow_cache_upload: bool = ...,
    auto_link_groups: bool = ...,
    bridging_header: None | str = ...,
    can_be_asset: None | bool = ...,
    compiler_flags: list[str] = ...,
    contacts: list[str] = ...,
    coverage_instrumentation_compiler_flags: list[str] = ...,
    cxx_runtime_type: None | str = ...,
    default_host_platform: None | str = ...,
    default_platform: None | str = ...,
    defaults: dict[str, str] = ...,
    deffile: None | str = ...,
    deps: list[str] = ...,
    deps_query: None | str = ...,
    devirt_enabled: bool = ...,
    diagnostics: dict[str, str] = ...,
    executable_name: None | str = ...,
    export_header_unit: None | str = ...,
    export_header_unit_filter: list[str] = ...,
    exported_deps: list[str] = ...,
    exported_header_style: str = ...,
    exported_headers: list[str] | dict[str, str] = ...,
    exported_lang_platform_preprocessor_flags: dict[str, list[(str, list[str])]] = ...,
    exported_lang_preprocessor_flags: dict[str, list[str]] = ...,
    exported_linker_flags: list[str] = ...,
    exported_needs_coverage_instrumentation: bool = ...,
    exported_platform_deps: list[(str, list[str])] = ...,
    exported_platform_headers: list[(str, list[str] | dict[str, str])] = ...,
    exported_platform_linker_flags: list[(str, list[str])] = ...,
    exported_platform_preprocessor_flags: list[(str, list[str])] = ...,
    exported_post_linker_flags: list[str] = ...,
    exported_post_platform_linker_flags: list[(str, list[str])] = ...,
    exported_preprocessor_flags: list[str] = ...,
    extra_xcode_files: list[str] = ...,
    extra_xcode_sources: list[str] = ...,
    fat_lto: bool = ...,
    focused_list_target: None | str = ...,
    force_static: None | bool = ...,
    frameworks: list[str] = ...,
    header_mode: None | str = ...,
    header_namespace: None | str = ...,
    headers: list[str] | dict[str, str] = ...,
    headers_as_raw_headers_mode: None | str = ...,
    include_directories: list[str] = ...,
    include_in_android_merge_map_output: bool = ...,
    labels: list[str] = ...,
    lang_compiler_flags: dict[str, list[str]] = ...,
    lang_platform_compiler_flags: dict[str, list[(str, list[str])]] = ...,
    lang_platform_preprocessor_flags: dict[str, list[(str, list[str])]] = ...,
    lang_preprocessor_flags: dict[str, list[str]] = ...,
    libraries: list[str] = ...,
    licenses: list[str] = ...,
    link_deps_query_whole: bool = ...,
    link_execution_preference: None | str = ...,
    link_group: None | str = ...,
    link_group_map: None | str | list[(str, list[(None | str | list[None | str], str, None | str | list[str], None | str)], None | dict[str, typing.Any])] = ...,
    link_ordering: None | str = ...,
    link_style: None | str = ...,
    link_whole: None | bool = ...,
    linker_extra_outputs: list[str] = ...,
    linker_flags: list[str] = ...,
    local_linker_flags: list[str] = ...,
    module_name: None | str = ...,
    platform_compiler_flags: list[(str, list[str])] = ...,
    platform_deps: list[(str, list[str])] = ...,
    platform_headers: list[(str, list[str] | dict[str, str])] = ...,
    platform_linker_flags: list[(str, list[str])] = ...,
    platform_preprocessor_flags: list[(str, list[str])] = ...,
    platform_srcs: list[(str, list[str | (str, list[str])])] = ...,
    post_linker_flags: list[str] = ...,
    post_platform_linker_flags: list[(str, list[str])] = ...,
    precompiled_header: None | str = ...,
    prefer_stripped_objects: bool = ...,
    preferred_linkage: str = ...,
    prefix_header: None | str = ...,
    preprocessor_flags: list[str] = ...,
    public_include_directories: list[str] = ...,
    public_system_include_directories: list[str] = ...,
    raw_headers: list[str] = ...,
    raw_headers_as_headers_mode: None | str = ...,
    reexport_all_header_dependencies: None | bool = ...,
    resources: list[str] | dict[str, str] = ...,
    sdk_modules: list[str] = ...,
    separate_debug_info: bool = ...,
    soname: None | str = ...,
    srcs: list[str | (str, list[str])] = ...,
    static_library_basename: None | str = ...,
    supported_platforms_regex: None | str = ...,
    supports_header_symlink_subtarget: bool = ...,
    supports_merged_linking: None | bool = ...,
    supports_python_dlopen: None | bool = ...,
    supports_shlib_interfaces: bool = ...,
    thin_lto: bool = ...,
    use_archive: None | bool = ...,
    use_header_units: bool = ...,
    used_by_wrap_script: bool = ...,
    uses_cxx_explicit_modules: bool = ...,
    uses_explicit_modules: bool = ...,
    version: None | str = ...,
    version_universe: None | str = ...,
    weak_framework_names: list[str] = ...,
) -> None

A cxx_library() rule specifies a set of C/C++ source files and also provides flags that specify how those files should be built.

Parameters​

  • name: name of the target

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

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

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

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

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

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

  • metadata: a key-value map of metadata associated with this target

  • tests: a list of targets that provide tests for this one

  • modifiers: an array of modifiers associated with this target

  • allow_cache_upload: Whether to allow uploading the output of this rule to be uploaded to cache when the action is executed locally if the configuration allows (i.e. there is a cache configured and the client has permission to write to it).

  • compiler_flags: Flags to use when compiling any of the above sources (which require compilation).

  • deffile: Specifies the *.def file used on windows to modify a dll's exports in place of explicit __declspec(dllexport) declarations. The default is to not use a defile.

  • export_header_unit: If not None, export a C++20 header unit visible to dependants (including recursively) with use_header_units set to True.

    "include": replace includes of each file in exported_headers or raw_headers with an import of the precompiled header unit; files that do not include any of those headers do not load the header unit.

    "preload": automatically load the precompiled header unit in any dependant that uses header units.

  • export_header_unit_filter: A list of regexes. Each regex should match a set of headers in exported_headers or raw_headers to be precompiled together into one C++20 header unit.

    When used with export_header_unit="include", this allows different subsets of headers to be loaded only by files that use them. Each group should only depend on headers in previous groups.

    If a header is not matched by any group, it is not precompiled and will be included textually. If no filter is specified, the rule excludes inline headers based on a name heuristics (e.g. "-inl.h").

  • 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. * When reexport_all_header_dependencies = False, only exported headers of the rules specified here are re-exported.

  • exported_header_style: How dependents should include exported headers from this rule. Can be either local (e.g. -I) or system (e.g. -isystem).

  • exported_headers: The set of header files that are made available for inclusion to the source files in the target and all targets that transitively depend on it. These should be specified as either a list of header files or a dictionary of header names to header files. The headers can be included with #include "$HEADER_NAMESPACE/$HEADER_NAME" or #include <$HEADER_NAMESPACE/$HEADER_NAME>, where $HEADER_NAMESPACE is the value of the target's header_namespace attribute, and $HEADER_NAME is the header name if specified, and the filename of the header file otherwise. Note that the header name can contain forward slashes (/). See header_namespace for more information.

  • exported_lang_platform_preprocessor_flags: Just as lang_platform_preprocessor_flags, but these flags also apply to rules that transitively depend on this rule.

  • exported_lang_preprocessor_flags: Just as lang_preprocessor_flags, but these flags also apply to rules that transitively depend on this rule.

  • exported_linker_flags: Flags to add to the linker command line when the output from this rule, or the output from any rule that transitively depends on this rule, is used in a link operation.

  • exported_platform_deps: Platform specific dependencies that will also appear to belong to any rules that depend on this one. These should be specified as a list of pairs where the first element is an un-anchored regex (in java.util.regex.Pattern syntax) against which the platform name is matched, and the second element is a list of external dependencies (same format as exported_deps) that are exported if the platform matches the regex. See exported_deps for more information.

  • exported_platform_headers: Platform specific header files. These should be specified as a list of pairs where the first element is an un-anchored regex (in java.util.regex.Pattern syntax) against which the platform name is matched, and the second element is either a list of header files or a dictionary of header names to header files that will be made available for inclusion to the source files in the target and all targets that transitively depend on it if the platform matches the regex. See headers for more information.

  • exported_platform_linker_flags: Platform-specific linker flags for this rule and for all rules that transitively depend on this rule. This argument is specified as a list of pairs where the first element in each pair is an un-anchored regex against which the platform name is matched. The regex should use java.util.regex.Pattern syntax. The second element in each pair is a list of linker flags. If the regex matches the platform, these flags are added to the linker command line when the output from this rule, or the output from any rule that transitively depends on this rule, is used in a link operation.

  • exported_platform_preprocessor_flags: Platform specific exported preprocessor flags. These should be specified as a list of pairs where the first element is an un-anchored regex (in java.util.regex.Pattern syntax) against which the platform name is matched, and the second element is a list of flags to use when preprocessing the source files in the target and all targets that transitively depend on it if the platform matches the regex. See exported_preprocessor_flags for more information.

  • exported_post_linker_flags: Flags to add to the linker command line when the output from this rule, or the output from any rule that transitively depends on this rule, is used in a link operation—with the additional feature that these flags are guaranteed to be placed after the compiled object (.o) files on the linker command line.

  • exported_post_platform_linker_flags: Platform-specific linker flags for this rule and for all rules that transitively depend on this rule—and that are guaranteed to be placed after the compiled object (.o) files on the linker command line. In other respects, the syntax and semantics of this argument are the same as for the exported_platform_linker_flags argument.

  • extra_xcode_files: When the project is generated, this is the list of files that will added to the project. Those files won't be added to the build phase "Compile Sources".

  • header_namespace: A path prefix when including headers of this target. Defaults to the path from the root of the repository to the directory where this target is defined. Can contain forward slashes (/), but cannot start with one. 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 name can contain forward slashes (/). The headers can be included with #include "$HEADER_NAMESPACE/$HEADER_NAME" or #include <$HEADER_NAMESPACE/$HEADER_NAME> , where $HEADER_NAMESPACE is the value of the target's header_namespace attribute, and $HEADER_NAME is the header name if specified, and the filename of the header file otherwise. See header_namespace for more information.

  • include_directories: A list of include directories (with raw_headers) to be added to the compile command for compiling this target (via -I). An include directory is relative to the current package.

  • lang_compiler_flags: Language-specific compiler flags. These should be specified as a map of C-family language short names to lists of flags and is used to target flags to sources files for a specific language in the C-family (C, C++, assembler, etc.). The keys in the map can be: * cpp-output for C * c++-cpp-output for C++ * objective-c-cpp-output for Objective-C * objective-c++-cpp-output for Objective-C++ * cuda-cpp-output for Cuda * assembler for Assembly * asm for ASM

  • lang_platform_compiler_flags: Language- and platform-specific compiler flags. These should be specified as a map of C-family language short names, as described in lang_compiler_flags, to lists of pairs, as described in platform_compiler_flags.

  • lang_platform_preprocessor_flags: Language- and platform-specific preprocessor flags. These should be specified as a map of C-family language short names, as described in lang_preprocessor_flags, to lists of pairs, as described in platform_preprocessor_flags.

  • lang_preprocessor_flags: Language-specific preprocessor flags. These should be specified as a map of C-family language short names to lists of flags and is used to target flags to sources files for a specific language in the C-family (C, C++, assembler, etc.). The keys in the map can be: * c for C * c++ for C++ * objective-c for Objective-C * objective-c++ for Objective-C++ * cuda for Cuda * assembler-with-cpp for Assembly * asm-with-cpp for ASM

  • 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 either static, static_pic or shared.

  • linker_extra_outputs: Declares extra outputs that the linker emits. These identifiers can be used in $(output ...) macros in linker_flags to interpolate the output path into the linker command line. Useful for custom linkers that emit extra output files.

  • linker_flags: Flags to add to the linker command line whenever the output from this rule is used in a link operation, such as linked into an executable or a shared library.

  • local_linker_flags: Flags to add to the linker command line whenever the output from this rule is used in a link operation driven by this rule (e.g. when this rule links a shared library, but not when the output is linked into a shared library by another rule's link group links).

  • platform_compiler_flags: Platform specific compiler flags. These should be specified as a list of pairs where the first element is an un-anchored regex (in java.util.regex.Pattern syntax) against which the platform name is matched, and the second element is a list of flags to use when compiling the target's sources. See compiler_flags for more information.

  • platform_headers: Platform specific header files. These should be specified as a list of pairs where the first element is an un-anchored regex (in java.util.regex.Pattern syntax) against which the platform name is matched, and the second element is either a list of header files or a dictionary of header names to header files that will be made available for inclusion to the source files in the target if the platform matches the regex. See headers for more information.

  • platform_linker_flags: Platform-specific linker flags. This argument is specified as a list of pairs where the first element in each pair is an un-anchored regex against which the platform name is matched. The regex should use java.util.regex.Pattern syntax. The second element in each pair is a list of linker flags. If the regex matches the platform, these flags are added to the linker command line when the output from this rule is used in a link operation.

  • platform_preprocessor_flags: Platform specific preprocessor flags. These should be specified as a list of pairs where the first element is an un-anchored regex (in java.util.regex.Pattern syntax) against which the platform name is matched, and the second element is a list of flags to use when preprocessing the target's sources. See preprocessor_flags for more information.

  • platform_srcs: Platform specific source files. These should be specified as a list of pairs where the first element is an un-anchored regex (in java.util.regex.Pattern syntax) against which the platform name is matched, and the second element is either a list of source files or a list of tuples of source files and a list of compilation flags to be preprocessed, compiled and assembled if the platform matches the regex. See srcs for more information.

  • preferred_linkage: Determines what linkage is used when the library is depended on by another target. To control how the dependencies of this library are linked, use link_style instead.

  • preprocessor_flags: Flags to use when preprocessing any of the above sources (which require preprocessing).

  • public_include_directories: A list of include directories (with raw_headers) to be added to the compile command for compiling this target and every target that depends on it (via -I). An include directory is relative to the current package.

  • public_system_include_directories: A list of include directories (with raw_headers) to be added to the compile command for compiling this target and every target that depends on it (via -isystem if the compiler supports it of via -I otherwise). An include directory is relative to the current package.

  • raw_headers: The set of header files that can be used for inclusion to the source files in the target and all targets that transitively depend on it. Buck doesn't add raw headers to the search path of a compiler/preprocessor automatically. include_directories and public_include_directories are the recommended way to add raw headers to the search path (they will be added via -I). compiler_flags, preprocessor_flags and exported_preprocessor_flags can also be used to add such raw headers to the search path if inclusion via -isystem or -iquote is needed. raw_headers cannot be used together with headers or exported_headers in the same target.

  • raw_headers_as_headers_mode: Controls whether raw_headers and *include_directories attributes should be automatically converted to headers and symlink trees and/or header maps via headers. Only has an effect if the cxx_toolchain has explicitly opted into supporting this behavior via a non-default value, even if the value is disabled.

  • reexport_all_header_dependencies: Whether to automatically re-export the exported headers of all dependencies.

    When this is set to false, only exported headers from exported_deps are re-exported.

  • soname: Sets the soname ("shared object name") of any shared library produced from this rule. The default value is based on the full rule name. The macro $(ext) will be replaced with a platform-appropriate extension. An argument can be provided, which is a library version. For example soname = 'libfoo.$(ext 2.3)' will be libfoo.2.3.dylib on Mac and libfoo.so.2.3 on Linux.

  • srcs: The set of C, C++, Objective-C, Objective-C++, or assembly source files to be preprocessed, compiled, and assembled by this rule. We determine which stages to run on each input source based on its file extension. See the GCC documentation for more detail on how file extensions are interpreted. Each element can be either a string specifying a source file (e.g. '') or a tuple of a string specifying a source file and a list of compilation flags (e.g. ('', ['-Wall', '-Werror']) ). In the latter case the specified flags will be used in addition to the rule's other flags when preprocessing and compiling that file (if applicable).

  • supported_platforms_regex: If present, an un-anchored regex (in java.util.regex.Pattern syntax) that matches all platforms that this library supports. It will not be built for other platforms.

  • use_header_units: If True, makes any header unit exported by a dependency (including recursively) through export_header_unit available to the compiler. If false, the compilation ignores header units, regardless of what is exported by dependencies.

  • used_by_wrap_script: When using an exopackage Android, if this parameter is set to True, then the library is included in the primary APK even if native libraries would otherwise not be placed in it. This is intended for native libraries that are used by a wrap.sh script, which must be placed in the primary APK. Only one of can_be_asset and used_by_wrap_script can be set for a rule.

  • version: A string denoting a meaningful version of this rule that is optionally passed to the linker as extra metadata.

Details​

Building requires a specified top-level target​

Whether a Buck command builds the cxx_library is determined by the inclusion of a top-level target, such as a cxx_binary() or android_binary(), that transitively depends on the cxx_library. The set of targets specified to the Buck command (buck build, buck run, etc) must include one of these top-level targets in order for Buck to build the cxx_library. Note that you could specify the top-level target implicitly using a build target pattern or you could also specify the top-level target using a buckconfig alias defined in .buckconfig.

How Buck builds the library also depends on the specified top-level target. For example, a C/C++ binary (cxx_binary) would require a static non-PIC build of the library, whereas an Android APK (android_binary) would require a shared PIC-enabled build. (PIC stands for position-independent code.)

Dependencies of the cxx_library also require a top-level target​

Similarly, in order for Buck to build a target that the cxx_library depends on, such as a cxx_genrule(), you must specify in the Buck command a top-level target that depends on the cxx_library. For example, you could specify to build a cxx_binary that depends on the cxx_library. If you specify as your build target the cxx_library itself, the build targets that the cxx_library depends on might not be built.

Examples:


# A rule that includes a single .cpp file and its corresponding header and
# also supplies an additional flag for compilation.
cxx_library(
  name = 'fileutil',
  srcs = [
    'fileutil.cpp',
  ],
  exported_headers = [
    'fileutil.h',
  ],
  compiler_flags = [
    '-fno-omit-frame-pointer',
  ],
)

# A rule that defines explicit names for its headers
cxx_library(
  name = 'mathutils',
  header_namespace = 'math',
  srcs = [
    'trig/src/cos.cpp',
    'trig/src/tan.cpp',
  ],
  exported_headers = {
    # These are included as <math/trig/cos.h> and <math/trig/tan.h>
    'trig/cos.h': 'trig/include/cos.h',
    'trig/tan.h': 'trig/include/tan.h',
  },
  compiler_flags = [
    '-fno-omit-frame-pointer',
  ],
)

# A rule that uses different headers and sources per platform
cxx_library(
  name = 'vector',
  # Because of platform_headers, this file can include "config.h"
  # and get the architecture specific header
  srcs = ['vector.cpp'],
  platform_srcs = [
    ('.*armv7$', 'armv7.S'),
    ('.*x86_64$', 'x86_64.S'),
  ],
  exported_headers = [
    'vector.h',
  ],
  platform_headers = [
    (
      '.*armv7$',
      {
        'config.h': 'config-armv7.h',
      }
    ),
    (
      '.*x86_64$',
      {
        'config.h': 'config-x86_64.h',
      }
    ),
  ],
)


cxx_lua_extension​

def cxx_lua_extension(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    base_module: None | str = ...,
    compiler_flags: list[str] = ...,
    contacts: list[str] = ...,
    cxx_runtime_type: None | str = ...,
    default_host_platform: None | str = ...,
    default_platform: None | str = ...,
    defaults: dict[str, str] = ...,
    deps: list[str] = ...,
    executable_name: None | str = ...,
    frameworks: list[str] = ...,
    header_namespace: None | str = ...,
    headers: list[str] | dict[str, str] = ...,
    headers_as_raw_headers_mode: None | str = ...,
    include_directories: list[str] = ...,
    labels: list[str] = ...,
    lang_compiler_flags: dict[str, list[str]] = ...,
    lang_platform_compiler_flags: dict[str, list[(str, list[str])]] = ...,
    lang_platform_preprocessor_flags: dict[str, list[(str, list[str])]] = ...,
    lang_preprocessor_flags: dict[str, list[str]] = ...,
    libraries: list[str] = ...,
    licenses: list[str] = ...,
    linker_extra_outputs: list[str] = ...,
    linker_flags: list[str] = ...,
    platform_compiler_flags: list[(str, list[str])] = ...,
    platform_deps: list[(str, list[str])] = ...,
    platform_headers: list[(str, list[str] | dict[str, str])] = ...,
    platform_linker_flags: list[(str, list[str])] = ...,
    platform_preprocessor_flags: list[(str, list[str])] = ...,
    platform_srcs: list[(str, list[str | (str, list[str])])] = ...,
    post_linker_flags: list[str] = ...,
    post_platform_linker_flags: list[(str, list[str])] = ...,
    precompiled_header: None | str = ...,
    prefix_header: None | str = ...,
    preprocessor_flags: list[str] = ...,
    raw_headers: list[str] = ...,
    srcs: list[str | (str, list[str])] = ...,
    version_universe: None | str = ...,
) -> None

A cxx_lua_extension() rule is a variant of a C/C++ library which is built as a Lua module. As such, it has a module name formed by the base_module parameter and the rule name and implicitly depends on Lua C library (configured via the .buckconfig parameter.

Parameters​

  • name: name of the target
  • default_target_platform: specifies the default target platform, used when no platforms are specified on the command line
  • target_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • exec_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with an execution platform
  • visibility: a list of visibility patterns restricting what targets can depend on this one
  • within_view: a list of visibility patterns restricting what this target can depend on
  • metadata: a key-value map of metadata associated with this target
  • tests: a list of targets that provide tests for this one
  • modifiers: an array of modifiers associated with this target
  • base_module: The package for which the given specified sources and resources should reside in their final location in the top-level binary. If unset, the project relative directory that houses the BUCK file is used.
  • compiler_flags: Flags to use when compiling any of the above sources (which require compilation).
  • header_namespace: A path prefix when including headers of this target. Defaults to the path from the root of the repository to the directory where this target is defined. Can contain forward slashes (/), but cannot start with one. 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 name can contain forward slashes (/). The headers can be included with #include "$HEADER_NAMESPACE/$HEADER_NAME" or #include <$HEADER_NAMESPACE/$HEADER_NAME> , where $HEADER_NAMESPACE is the value of the target's header_namespace attribute, and $HEADER_NAME is the header name if specified, and the filename of the header file otherwise. See header_namespace for more information.
  • linker_flags: Flags to add to the linker command line whenever the output from this rule is used in a link operation, such as linked into an executable or a shared library.
  • platform_compiler_flags: Platform specific compiler flags. These should be specified as a list of pairs where the first element is an un-anchored regex (in java.util.regex.Pattern syntax) against which the platform name is matched, and the second element is a list of flags to use when compiling the target's sources. See compiler_flags for more information.
  • platform_headers: Platform specific header files. These should be specified as a list of pairs where the first element is an un-anchored regex (in java.util.regex.Pattern syntax) against which the platform name is matched, and the second element is either a list of header files or a dictionary of header names to header files that will be made available for inclusion to the source files in the target if the platform matches the regex. See headers for more information.
  • platform_linker_flags: Platform-specific linker flags. This argument is specified as a list of pairs where the first element in each pair is an un-anchored regex against which the platform name is matched. The regex should use java.util.regex.Pattern syntax. The second element in each pair is a list of linker flags. If the regex matches the platform, these flags are added to the linker command line when the output from this rule is used in a link operation.
  • platform_preprocessor_flags: Platform specific preprocessor flags. These should be specified as a list of pairs where the first element is an un-anchored regex (in java.util.regex.Pattern syntax) against which the platform name is matched, and the second element is a list of flags to use when preprocessing the target's sources. See preprocessor_flags for more information.
  • platform_srcs: Platform specific source files. These should be specified as a list of pairs where the first element is an un-anchored regex (in java.util.regex.Pattern syntax) against which the platform name is matched, and the second element is either a list of source files or a list of tuples of source files and a list of compilation flags to be preprocessed, compiled and assembled if the platform matches the regex. See srcs for more information.
  • preprocessor_flags: Flags to use when preprocessing any of the above sources (which require preprocessing).
  • srcs: The set of C, C++, Objective-C, Objective-C++, or assembly source files to be preprocessed, compiled, and assembled by this rule. We determine which stages to run on each input source based on its file extension. See the GCC documentation for more detail on how file extensions are interpreted. Each element can be either a string specifying a source file (e.g. '') or a tuple of a string specifying a source file and a list of compilation flags (e.g. ('', ['-Wall', '-Werror']) ). In the latter case the specified flags will be used in addition to the rule's other flags when preprocessing and compiling that file (if applicable).

Details​

Examples:


# A rule that builds a Lua extension from a single .cpp file.
cxx_lua_extension(
  name = 'mymodule',
  base_module = 'foo.bar',
  srcs = [
    'mymodule.cpp',
  ],
  compiler_flags = [
    '-fno-omit-frame-pointer',
  ],
)

# A library rule which has a single source importing the above extension.
lua_library(
  name = 'utils',
  srcs = [
    'utils.lua',
  ],
  deps = [
    ':mymodule',
  ],
)


-- The `utils.lua` source, wrapped by the `utils` rule above.

-- Import the C/C++ extension build above.
require "foo.bar.mymodule"

...

cxx_precompiled_header​

def cxx_precompiled_header(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    contacts: list[str] = ...,
    default_host_platform: None | str = ...,
    deps: list[str] = ...,
    labels: list[str] = ...,
    licenses: list[str] = ...,
    src: str,
    version_universe: None | str = ...,
) -> None

A cxx_precompiled_header rule specifies a single header file that can be precompiled and made available for use in other build rules such as a cxx_library() or a cxx_binary().

Parameters​

  • name: name of the target
  • default_target_platform: specifies the default target platform, used when no platforms are specified on the command line
  • target_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • exec_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with an execution platform
  • visibility: a list of visibility patterns restricting what targets can depend on this one
  • within_view: a list of visibility patterns restricting what this target can depend on
  • metadata: a key-value map of metadata associated with this target
  • tests: a list of targets that provide tests for this one
  • modifiers: an array of modifiers associated with this target
  • deps: Dependency rules which export headers used by the header specified in src.
  • src: The path to the header file that should be precompiled. Only one header file can be specified. But of course this header could include any number of other headers. The included headers could belong to -- that is, be exported_headers from -- another rule, in which case, the rule would have to be added to deps as usual.

Details​

This header file is precompiled by the preprocessor on behalf of the C, C++, Objective-C, or Objective-C++ rule using it, via its precompiled_header parameter. Afterwards the precompiled header is applied during the rule's own compilation (often with an appreciable reduction in build time, the main benefit of PCH).

This PCH is built once per combination of build flags which might affect the PCH's compatibility. For example, a distinct pre-compilation of the header occurs per combination of flags related to optimization, debug, architecture, and so on, used by rules which employ PCH. The flags used during the build of the dependent rule (that is, the "PCH-using rule") are in effect while building the PCH itself. Similarly, to the same end, the include paths used when building the PCH are applied to the dependent rule. For example, deps in the PCH rule are propagated back to the dependent rule, and the PCH's header search paths (e.g. -I or -isystem options) are prefixed onto the list of include paths for the dependent rule.

Examples:

The best way to see how the cxx_precompiled_header() rule works is with an example. Let there be a header called common.h which has the following:


#pragma once

/* Include common C++ files. */
#include <string>
#include <map>
#include <set>
#include <type_traits>
#include <vector>

/* Some frequently-used headers from the Folly project. */
#include <folly/Conv.h>
#include <folly/Executor.h>
#include <folly/io/async/EventBase.h>


cxx_precompiled_header(
  name = 'common_pch',
  src = 'common.h',
  deps = [
    # Needed for standard C++ headers:
    '//external/libcxx:headers',
    # Needed for the Folly includes:
    '//folly:folly',
    '//folly/io/async:async',
  ],
)

cxx_binary(
  name = 'main',
  srcs = ['main.cpp'],
  precompiled_header = ':common_pch',
  deps = [ ... ],
  compiler_flags = ['-g', '-O2', '-fPIC'],
)

The cxx_precompiled_header rule declares a precompiled header "template" containing the header file path, and dependencies. In this example we indicate that common.h is to be precompiled when used by another build rule.

Note that, by itself, this cxx_precompiled_header rule will not result in anything being built. The usage of this rule from another rule -- an "instantiation" of this precompiled header template -- is what will trigger the PCH build.

In the example above, the build for the binary named "main" will depend on the header being precompiled in a separate step, prior to compiling main.cpp, and the resulting PCH will be used in main's compilation.

The dependencies specified in this precompiled header rule's deps are transitive; they will propagate to rules using this PCH, so that during link time, any libraries which are required by the code made available in the header will be included in the final binary build.

The precompiled header dynamically created from the "template" will be built with flags which would be used in the dependent rule. In this case, main's use of specific compiler flags -g -O2 -fPIC will result in the production of a precompiled header with the same flags. This is so the precompiled code fully jives with rules using the PCH, i.e. they will have the same debug, optimization, CPU, etc. options. (The compiler is usually smart enough to reject a bad PCH, fortunately. But we want to ensure we take the appropriate steps to ensure we always have a PCH which works with any build that uses it.)

Another effect of a rule using a precompiled header is that the rule's list of build flags will change; not just to employ PCH with e.g. -include-pch (if using Clang), but also, to alter the sequence of header search paths. The rule using the precompiled header will "inherit" the lists of paths used during the PCH build, applying them first in its own search paths. This is to ensure that an #include directive will resolve in exactly the same way in this build as it would have in the PCH, to ensure full compatibility between the PCH and other rule's builds. For example, if the PCH were to use one version of stdcxx and another rule use a different version, the version differences won't clash, thereby avoiding different versions of the <cstring> header used between the precompiled header and the dependent rule, and preventing confused structure definitions, ABI incompatibility, and so on (catastrophe, in other words).

cxx_python_extension​

def cxx_python_extension(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    _cxx_hacks: str = ...,
    _cxx_toolchain: str = ...,
    _meta_apple_library_validation_enabled: bool = ...,
    _python_toolchain: str = ...,
    _target_os_type: str = ...,
    allow_cache_upload: None | bool = ...,
    allow_embedding: bool = ...,
    allow_suffixing: bool = ...,
    archive_allow_cache_upload: bool = ...,
    auto_link_groups: bool = ...,
    base_module: None | str = ...,
    bridging_header: None | str = ...,
    can_be_asset: None | bool = ...,
    compiler_flags: list[str] = ...,
    contacts: list[str] = ...,
    coverage_instrumentation_compiler_flags: list[str] = ...,
    cxx_runtime_type: None | str = ...,
    default_host_platform: None | str = ...,
    default_platform: None | str = ...,
    defaults: dict[str, str] = ...,
    deffile: None | str = ...,
    deps: list[str] = ...,
    devirt_enabled: bool = ...,
    diagnostics: dict[str, str] = ...,
    executable_name: None | str = ...,
    export_header_unit: None | str = ...,
    export_header_unit_filter: list[str] = ...,
    exported_deps: list[str] = ...,
    exported_header_style: str = ...,
    exported_headers: list[str] | dict[str, str] = ...,
    exported_lang_platform_preprocessor_flags: dict[str, list[(str, list[str])]] = ...,
    exported_lang_preprocessor_flags: dict[str, list[str]] = ...,
    exported_linker_flags: list[str] = ...,
    exported_needs_coverage_instrumentation: bool = ...,
    exported_platform_deps: list[(str, list[str])] = ...,
    exported_platform_headers: list[(str, list[str] | dict[str, str])] = ...,
    exported_platform_linker_flags: list[(str, list[str])] = ...,
    exported_platform_preprocessor_flags: list[(str, list[str])] = ...,
    exported_post_linker_flags: list[str] = ...,
    exported_post_platform_linker_flags: list[(str, list[str])] = ...,
    exported_preprocessor_flags: list[str] = ...,
    extra_xcode_files: list[str] = ...,
    extra_xcode_sources: list[str] = ...,
    fat_lto: bool = ...,
    focused_list_target: None | str = ...,
    force_static: None | bool = ...,
    frameworks: list[str] = ...,
    header_namespace: None | str = ...,
    headers: list[str] | dict[str, str] = ...,
    headers_as_raw_headers_mode: None | str = ...,
    include_directories: list[str] = ...,
    include_in_android_merge_map_output: bool = ...,
    labels: list[str] = ...,
    lang_compiler_flags: dict[str, list[str]] = ...,
    lang_platform_compiler_flags: dict[str, list[(str, list[str])]] = ...,
    lang_platform_preprocessor_flags: dict[str, list[(str, list[str])]] = ...,
    lang_preprocessor_flags: dict[str, list[str]] = ...,
    libraries: list[str] = ...,
    licenses: list[str] = ...,
    link_group: None | str = ...,
    link_group_map: None | str | list[(str, list[(None | str | list[None | str], str, None | str | list[str], None | str)], None | dict[str, typing.Any])] = ...,
    link_ordering: None | str = ...,
    link_style: None | str = ...,
    link_whole: bool = ...,
    linker_extra_outputs: list[str] = ...,
    linker_flags: list[str] = ...,
    local_linker_flags: list[str] = ...,
    module_name: None | str = ...,
    platform_compiler_flags: list[(str, list[str])] = ...,
    platform_deps: list[(str, list[str])] = ...,
    platform_headers: list[(str, list[str] | dict[str, str])] = ...,
    platform_linker_flags: list[(str, list[str])] = ...,
    platform_preprocessor_flags: list[(str, list[str])] = ...,
    platform_srcs: list[(str, list[str | (str, list[str])])] = ...,
    post_linker_flags: list[str] = ...,
    post_platform_linker_flags: list[(str, list[str])] = ...,
    precompiled_header: None | str = ...,
    preferred_linkage: str = ...,
    prefix_header: None | str = ...,
    preprocessor_flags: list[str] = ...,
    public_include_directories: list[str] = ...,
    public_system_include_directories: list[str] = ...,
    raw_headers: list[str] = ...,
    raw_headers_as_headers_mode: None | str = ...,
    reexport_all_header_dependencies: None | bool = ...,
    resources: list[str] | dict[str, str] = ...,
    sdk_modules: list[str] = ...,
    separate_debug_info: bool = ...,
    soname: None | str = ...,
    srcs: list[str | (str, list[str])] = ...,
    static_library_basename: None | str = ...,
    suffix_all: bool = ...,
    support_shlib_interfaces: bool = ...,
    supported_platforms_regex: None | str = ...,
    supports_merged_linking: None | bool = ...,
    thin_lto: bool = ...,
    type_stub: None | str = ...,
    use_archive: None | bool = ...,
    use_header_units: bool = ...,
    used_by_wrap_script: bool = ...,
    uses_cxx_explicit_modules: bool = ...,
    uses_explicit_modules: bool = ...,
    version: None | str = ...,
    version_universe: None | str = ...,
    weak_framework_names: list[str] = ...,
) -> None

A cxx_python_extension() rule is a variant of a C/C++ library which is built as a Python module. As such, it has a module name formed by the base_module parameter and the rule name.

Parameters​

  • name: name of the target
  • default_target_platform: specifies the default target platform, used when no platforms are specified on the command line
  • target_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • exec_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with an execution platform
  • visibility: a list of visibility patterns restricting what targets can depend on this one
  • within_view: a list of visibility patterns restricting what this target can depend on
  • metadata: a key-value map of metadata associated with this target
  • tests: a list of targets that provide tests for this one
  • modifiers: an array of modifiers associated with this target
  • base_module: The package in which the specified source files and resources should reside in their final location in the top-level binary. If unset, Buck uses the project-relative directory that contains the BUCK file.
  • compiler_flags: Flags to use when compiling any of the above sources (which require compilation).
  • deps: Other rules that list srcs from which this rule imports.
  • header_namespace: A path prefix when including headers of this target. Defaults to the path from the root of the repository to the directory where this target is defined. Can contain forward slashes (/), but cannot start with one. 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 name can contain forward slashes (/). The headers can be included with #include "$HEADER_NAMESPACE/$HEADER_NAME" or #include <$HEADER_NAMESPACE/$HEADER_NAME> , where $HEADER_NAMESPACE is the value of the target's header_namespace attribute, and $HEADER_NAME is the header name if specified, and the filename of the header file otherwise. See header_namespace for more information.
  • labels: Set of arbitrary strings which allow you to annotate a build rule with tags that can be searched for over an entire dependency tree using buck query() .
  • link_style: Determines whether to build and link this rule's dependencies statically or dynamically. Can be either static, static_pic or shared. Note: since shared libraries re-export its dependencies, depending on multiple shared libraries which themselves have overlapping static dependencies may cause problems if they init using global state.
  • linker_extra_outputs: Declares extra outputs that the linker emits. These identifiers can be used in $(output ...) macros in linker_flags to interpolate the output path into the linker command line. Useful for custom linkers that emit extra output files.
  • linker_flags: Flags to add to the linker command line whenever the output from this rule is used in a link operation, such as linked into an executable or a shared library.
  • local_linker_flags: Flags to add to the linker command line whenever the output from this rule is used in a link operation driven by this rule (e.g. when this rule links a shared library, but not when the output is linked into a shared library by another rule's link group links).
  • platform_compiler_flags: Platform specific compiler flags. These should be specified as a list of pairs where the first element is an un-anchored regex (in java.util.regex.Pattern syntax) against which the platform name is matched, and the second element is a list of flags to use when compiling the target's sources. See compiler_flags for more information.
  • platform_headers: Platform specific header files. These should be specified as a list of pairs where the first element is an un-anchored regex (in java.util.regex.Pattern syntax) against which the platform name is matched, and the second element is either a list of header files or a dictionary of header names to header files that will be made available for inclusion to the source files in the target if the platform matches the regex. See headers for more information.
  • platform_linker_flags: Platform-specific linker flags. This argument is specified as a list of pairs where the first element in each pair is an un-anchored regex against which the platform name is matched. The regex should use java.util.regex.Pattern syntax. The second element in each pair is a list of linker flags. If the regex matches the platform, these flags are added to the linker command line when the output from this rule is used in a link operation.
  • platform_preprocessor_flags: Platform specific preprocessor flags. These should be specified as a list of pairs where the first element is an un-anchored regex (in java.util.regex.Pattern syntax) against which the platform name is matched, and the second element is a list of flags to use when preprocessing the target's sources. See preprocessor_flags for more information.
  • platform_srcs: Platform specific source files. These should be specified as a list of pairs where the first element is an un-anchored regex (in java.util.regex.Pattern syntax) against which the platform name is matched, and the second element is either a list of source files or a list of tuples of source files and a list of compilation flags to be preprocessed, compiled and assembled if the platform matches the regex. See srcs for more information.
  • preprocessor_flags: Flags to use when preprocessing any of the above sources (which require preprocessing).
  • srcs: The set of C, C++, Objective-C, Objective-C++, or assembly source files to be preprocessed, compiled, and assembled by this rule. We determine which stages to run on each input source based on its file extension. See the GCC documentation for more detail on how file extensions are interpreted. Each element can be either a string specifying a source file (e.g. '') or a tuple of a string specifying a source file and a list of compilation flags (e.g. ('', ['-Wall', '-Werror']) ). In the latter case the specified flags will be used in addition to the rule's other flags when preprocessing and compiling that file (if applicable).

Details​

Examples:


# A rule that builds a Python extension from a single .cpp file.
cxx_python_extension(
  name = 'mymodule',
  base_module = 'foo.bar',
  srcs = [
    'mymodule.cpp',
  ],
)

# A library rule which has a single source importing the above extension.
python_library(
  name = 'utils',
  srcs = [
    'utils.py',
  ],
  deps = [
    ':mymodule',
  ],
)


## The `utils.py` source, wrapped by the `utils` rule above.

## Import the C/C++ extension build above.
from foo.bar import mymodule

...

cxx_test​

def cxx_test(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    _build_info: dict[str, typing.Any] = ...,
    _cxx_hacks: str = ...,
    _cxx_toolchain: str = ...,
    _inject_test_env: str = ...,
    _remote_test_execution_toolchain: str = ...,
    _test_toolchain: str = ...,
    additional_coverage_targets: list[str] = ...,
    allow_cache_upload: None | bool = ...,
    anonymous_link_groups: bool = ...,
    args: list[str] = ...,
    auto_link_groups: bool = ...,
    binary_linker_flags: list[str] = ...,
    bolt_flags: list[str] = ...,
    bolt_profile: None | str = ...,
    compiler_flags: list[str] = ...,
    constraint_overrides: list[str] = ...,
    contacts: list[str] = ...,
    coverage_instrumentation_compiler_flags: list[str] = ...,
    cxx_runtime_type: None | str = ...,
    default_host_platform: None | str = ...,
    default_platform: None | str = ...,
    defaults: dict[str, str] = ...,
    deps: list[str] = ...,
    deps_query: None | str = ...,
    devirt_enabled: bool = ...,
    distributed_thinlto_partial_split_dwarf: bool = ...,
    enable_distributed_thinlto: bool = ...,
    env: dict[str, str] = ...,
    executable_name: None | str = ...,
    exported_needs_coverage_instrumentation: bool = ...,
    fat_lto: bool = ...,
    focused_list_target: None | str = ...,
    framework: None | str = ...,
    frameworks: list[str] = ...,
    header_namespace: None | str = ...,
    headers: list[str] | dict[str, str] = ...,
    headers_as_raw_headers_mode: None | str = ...,
    include_directories: list[str] = ...,
    labels: list[str] = ...,
    lang_compiler_flags: dict[str, list[str]] = ...,
    lang_platform_compiler_flags: dict[str, list[(str, list[str])]] = ...,
    lang_platform_preprocessor_flags: dict[str, list[(str, list[str])]] = ...,
    lang_preprocessor_flags: dict[str, list[str]] = ...,
    libraries: list[str] = ...,
    licenses: list[str] = ...,
    link_deps_query_whole: bool = ...,
    link_execution_preference: None | str = ...,
    link_group: None | str = ...,
    link_group_deps: list[str] = ...,
    link_group_map: None | str | list[(str, list[(None | str | list[None | str], str, None | str | list[str], None | str)], None | dict[str, typing.Any])] = ...,
    link_group_min_binary_node_count: None | int = ...,
    link_group_public_deps_label: None | str = ...,
    link_ordering: None | str = ...,
    link_style: None | str = ...,
    link_whole: bool = ...,
    linker_extra_outputs: list[str] = ...,
    linker_flags: list[str] = ...,
    platform_compiler_flags: list[(str, list[str])] = ...,
    platform_deps: list[(str, list[str])] = ...,
    platform_headers: list[(str, list[str] | dict[str, str])] = ...,
    platform_linker_flags: list[(str, list[str])] = ...,
    platform_override: None | 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] = ...,
    raw_headers_as_headers_mode: None | str = ...,
    remote_execution: None | str | dict[str, None | bool | int | str | list[dict[str, str]] | dict[str, str]] = ...,
    remote_execution_action_key_providers: None | str = ...,
    resources: list[str] | dict[str, str] = ...,
    run_test_separately: None | bool = ...,
    separate_debug_info: bool = ...,
    srcs: list[str | (str, list[str])] = ...,
    standalone_extensions: None | bool = ...,
    test_rule_timeout_ms: None | int = ...,
    thin_lto: bool = ...,
    use_default_test_main: None | bool = ...,
    use_header_units: bool = ...,
    version_universe: None | str = ...,
    weak_framework_names: list[str] = ...,
) -> None

A cxx_test() rule builds a C/C++ binary against a C/C++ testing framework and runs it as part of test.

Parameters​

  • name: name of the target

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

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

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

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

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

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

  • metadata: a key-value map of metadata associated with this target

  • tests: a list of targets that provide tests for this one

  • modifiers: an array of modifiers associated with this target

  • _build_info: Build info that is passed along here will be late-stamped into a fb_build_info section on the output binary

  • allow_cache_upload: Whether to allow uploading the output of this rule to be uploaded to cache when the action is executed locally if the configuration allows (i.e. there is a cache configured and the client has permission to write to it).

  • args: A list of additional arguments to pass to the test when it's run.

    It is also possible to expand references to other rules within these arguments, using builtin string parameter macros :

    $(location //path/to:target) Expands to the location of the output of the build rule. This means that you can refer to these without needing to be aware of how Buck is storing data on the disk mid-build.

  • compiler_flags: Flags to use when compiling any of the above sources (which require compilation).

  • deps_query: Status: experimental/unstable. The deps query takes a query string that accepts the following query functions, and appends the output of the query to the declared deps:

    • attrfilter

    • deps

    • except

    • intersect

    • filter

    • kind

    • set

    • union

    The macro $declared_deps may be used anywhere a target literal pattern is expected in order to refer to the explicit deps of this rule as they appear in the rule's definition. For example, if your build rule declares


      android_library(
        name = 'lib',
        deps = ['//foo:foo'],
        deps_query = '$declared_deps',
      )

    then the macro $declared_deps would be expanded to a 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.

  • env: A map of environment names and values to set when running the test.

    It is also possible to expand references to other rules within the values of these environment variables, using builtin string parameter macros :

    $(location //path/to:target) Expands to the location of the output of the build rule. This means that you can refer to these without needing to be aware of how Buck is storing data on the disk mid-build.

  • framework: Unused.

  • headers: The set of header files that are made available for inclusion to the source files in this target. These should be specified as either a list of header files or a dictionary of header names to header files. The header name can contain forward slashes (/). The headers can be included with #include "$HEADER_NAMESPACE/$HEADER_NAME" or #include <$HEADER_NAMESPACE/$HEADER_NAME> , where $HEADER_NAMESPACE is the value of the target's header_namespace attribute, and $HEADER_NAME is the header name if specified, and the filename of the header file otherwise. See header_namespace for more information.

  • include_directories: A list of include directories (with raw_headers) to be added to the compile command for compiling this target (via -I). An include directory is relative to the current package.

  • link_execution_preference: The execution preference for linking. Options are:

    • any : No preference is set, and the link action will be performed based on buck2's executor configuration.
    • full_hybrid : The link action will execute both locally and remotely, regardless of buck2's executor configuration (if the executor is capable of hybrid execution). The use_limited_hybrid setting of the hybrid executor is ignored.
    • local : The link action will execute locally if compatible on current host platform.
    • local_only : The link action will execute locally, and error if the current platform is not compatible.
    • remote : The link action will execute remotely if a compatible remote platform exists, otherwise locally.

    The default is None, expressing that no preference has been set on the target itself.

  • link_group_deps: Additional targets to traverse when building link groups, but which should not be direct dependencies of the main executable.

  • link_group_public_deps_label: Surface nodes with this label as "public" nodes in the main executable when linking with with link groups.

  • link_style: Determines whether to build and link this rule's dependencies statically or dynamically. Can be either static, static_pic or shared.

  • linker_flags: Flags to add to the linker command line whenever the output from this rule is used in a link operation, such as linked into an executable or a shared library.

  • preprocessor_flags: Flags to use when preprocessing any of the above sources (which require preprocessing).

  • raw_headers: The set of header files that can be used for inclusion to the source files in the target and all targets that transitively depend on it. Buck doesn't add raw headers to the search path of a compiler/preprocessor automatically. include_directories and public_include_directories are the recommended way to add raw headers to the search path (they will be added via -I). compiler_flags, preprocessor_flags and exported_preprocessor_flags can also be used to add such raw headers to the search path if inclusion via -isystem or -iquote is needed. raw_headers cannot be used together with headers or exported_headers in the same target.

  • raw_headers_as_headers_mode: Controls whether raw_headers and *include_directories attributes should be automatically converted to headers and symlink trees and/or header maps via headers. Only has an effect if the cxx_toolchain has explicitly opted into supporting this behavior via a non-default value, even if the value is disabled.

  • srcs: The set of C, C++, Objective-C, Objective-C++, or assembly source files to be preprocessed, compiled, and assembled by this rule. We determine which stages to run on each input source based on its file extension. See the GCC documentation for more detail on how file extensions are interpreted. Each element can be either a string specifying a source file (e.g. '') or a tuple of a string specifying a source file and a list of compilation flags (e.g. ('', ['-Wall', '-Werror']) ). In the latter case the specified flags will be used in addition to the rule's other flags when preprocessing and compiling that file (if applicable).

  • test_rule_timeout_ms: If set specifies the maximum amount of time (in milliseconds) in which all of the tests in this rule should complete. This overrides the default rule_timeout if any has been specified in .buckconfig .

  • use_header_units: If True, makes any header unit exported by a dependency (including recursively) through export_header_unit available to the compiler. If false, the compilation ignores header units, regardless of what is exported by dependencies.

Details​

Examples:


# A rule that builds and runs C/C++ test using gtest.
cxx_test(
  name = 'echo_test',
  srcs = [
    'echo_test.cpp',
  ],
)

cxx_toolchain​

def cxx_toolchain(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    _dumpbin_toolchain_path: None | str = ...,
    _internal_tools: str = ...,
    _msvc_hermetic_exec: str = ...,
    archive_contents: str = ...,
    archive_symbol_table: bool = ...,
    archiver: str,
    archiver_flags: list[str] = ...,
    archiver_reads_inputs: bool = ...,
    archiver_supports_argfiles: bool = ...,
    archiver_type: str,
    asm_compiler: None | str = ...,
    asm_compiler_flags: list[str] = ...,
    asm_compiler_type: None | str = ...,
    asm_preprocessor: None | str = ...,
    asm_preprocessor_flags: list[str] = ...,
    asm_preprocessor_type: None | str = ...,
    assembler: str,
    assembler_flags: list[str] = ...,
    assembler_preprocessor: None | str = ...,
    assembler_preprocessor_flags: list[str] = ...,
    assembler_preprocessor_type: None | str = ...,
    assembler_type: None | str = ...,
    binary_extension: None | str = ...,
    binary_linker_flags: list[str] = ...,
    bolt_enabled: bool = ...,
    c_compiler: str,
    c_compiler_allow_cache_upload: None | bool = ...,
    c_compiler_flags: list[str] = ...,
    c_compiler_type: None | str = ...,
    c_preprocessor_flags: list[str] = ...,
    cache_links: bool = ...,
    clang_remarks: None | str = ...,
    clang_trace: None | bool = ...,
    compiler_type: None | str = ...,
    conflicting_header_basename_exemptions: list[str] = ...,
    contacts: list[str] = ...,
    cpp_dep_tracking_mode: str = ...,
    cuda_compiler: None | str = ...,
    cuda_compiler_allow_cache_upload: None | bool = ...,
    cuda_compiler_flags: list[str] = ...,
    cuda_compiler_type: None | str = ...,
    cuda_dep_tracking_mode: str = ...,
    cuda_preprocessor_flags: list[str] = ...,
    cvtres_compiler: None | str = ...,
    cvtres_compiler_flags: list[str] = ...,
    cvtres_compiler_type: None | str = ...,
    cvtres_preprocessor_flags: list[str] = ...,
    cxx_compiler: str,
    cxx_compiler_allow_cache_upload: None | bool = ...,
    cxx_compiler_flags: list[str] = ...,
    cxx_compiler_type: None | str = ...,
    cxx_preprocessor_flags: list[str] = ...,
    debug_path_prefix_map_sanitizer_format: None | str = ...,
    default_host_platform: None | str = ...,
    detailed_untracked_header_messages: bool = ...,
    dist_thin_lto_codegen_flags: list[str] = ...,
    executable_linker_flags: list[str] = ...,
    gcno_files: bool = ...,
    generate_linker_maps: bool = ...,
    headers_as_raw_headers_mode: None | str = ...,
    headers_whitelist: list[str] = ...,
    hip_compiler: None | str = ...,
    hip_compiler_flags: list[str] = ...,
    hip_compiler_type: None | str = ...,
    hip_preprocessor_flags: list[str] = ...,
    labels: list[str] = ...,
    licenses: list[str] = ...,
    link_metadata_flag: None | str = ...,
    link_ordering: str = ...,
    link_path_normalization_args_enabled: bool = ...,
    link_style: str = ...,
    link_weight: int = ...,
    linker: str,
    linker_flags: list[str] = ...,
    linker_type: str,
    lipo: None | str = ...,
    llvm_link: None | str = ...,
    lto_mode: str = ...,
    min_sdk_version: None | str = ...,
    nm: str,
    objcopy_for_shared_library_interface: str,
    objdump: None | str = ...,
    object_file_extension: str = ...,
    object_format: str = ...,
    optimization_compiler_flags_EXPERIMENTAL: list[str] = ...,
    pic_behavior: str = ...,
    placeholder_tool: None | str = ...,
    platform_name: None | str = ...,
    post_linker_flags: list[str] = ...,
    private_headers_symlinks_enabled: bool = ...,
    public_headers_symlinks_enabled: bool = ...,
    ranlib: None | str = ...,
    ranlib_flags: list[str] = ...,
    raw_headers_as_headers_mode: None | str = ...,
    rc_compiler: None | str = ...,
    rc_compiler_flags: list[str] = ...,
    rc_compiler_type: None | str = ...,
    rc_preprocessor_flags: list[str] = ...,
    remap_cwd: bool = ...,
    requires_archives: bool = ...,
    requires_objects: bool = ...,
    sanitizer_runtime_enabled: bool = ...,
    sanitizer_runtime_files: list[str] = ...,
    shared_dep_runtime_ld_flags: list[str] = ...,
    shared_library_extension: str = ...,
    shared_library_interface_flags: list[str] = ...,
    shared_library_interface_mode: str = ...,
    shared_library_interface_producer: None | str = ...,
    shared_library_interface_type: str,
    shared_library_versioned_extension_format: str = ...,
    split_debug_mode: str = ...,
    static_dep_runtime_ld_flags: list[str] = ...,
    static_library_extension: str = ...,
    static_pic_dep_runtime_ld_flags: list[str] = ...,
    strip: str,
    strip_all_flags: None | list[str] = ...,
    strip_debug_flags: None | list[str] = ...,
    strip_non_global_flags: None | list[str] = ...,
    supports_distributed_thinlto: bool = ...,
    target_sdk_version: None | str = ...,
    thin_lto_premerger_enabled: bool = ...,
    use_archiver_flags: bool = ...,
    use_dep_files: None | bool = ...,
    use_header_map: bool = ...,
) -> None

Parameters​

  • name: name of the target
  • default_target_platform: specifies the default target platform, used when no platforms are specified on the command line
  • target_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • exec_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with an execution platform
  • visibility: a list of visibility patterns restricting what targets can depend on this one
  • within_view: a list of visibility patterns restricting what this target can depend on
  • metadata: a key-value map of metadata associated with this target
  • tests: a list of targets that provide tests for this one
  • modifiers: an array of modifiers associated with this target
  • binary_linker_flags: Linker flags that apply to all links coordinated by a binary rule. One key distinction between these and executable_linker_flags is that these will also apply to library links coordinated by binary rules (e.g. linking roots/deps when using native python or omnibus link strategies).
  • c_compiler_allow_cache_upload: Whether to allow uploading of object files to cache when the compile action is executed locally and the configuration allows uploads (i.e., there is a cache configured and the client has permission to write to it).
  • cuda_compiler_allow_cache_upload: Whether to allow uploading of object files to cache when the compile action is executed locally and the configuration allows uploads (i.e., there is a cache configured and the client has permission to write to it).
  • cxx_compiler_allow_cache_upload: Whether to allow uploading of object files to cache when the compile action is executed locally and the configuration allows uploads (i.e., there is a cache configured and the client has permission to write to it).
  • executable_linker_flags: Linker flags that only apply when linking an executable.
  • link_style: The default value of the link_style attribute for rules that use this toolchain.
  • raw_headers_as_headers_mode: Controls whether raw_headers and *include_directories attributes should be automatically converted to headers and symlink trees and/or header maps via headers. Only has an effect if the cxx_toolchain has explicitly opted into supporting this behavior via a non-default value, even if the value is disabled.

cxx_universal_executable​

def cxx_universal_executable(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    _cxx_toolchain: str = ...,
    executable: str,
    executable_name: None | str = ...,
    labels: list[str] = ...,
    universal: None | bool = ...,
) -> None

A cxx_universal_executable() rule takes a target via its binary attribute, builds it for multiple architectures and combines the result into a single binary using lipo.

Parameters​

  • name: name of the target

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

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

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

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

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

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

  • metadata: a key-value map of metadata associated with this target

  • tests: a list of targets that provide tests for this one

  • modifiers: an array of modifiers associated with this target

  • executable: A build target identifying the binary which will be built for multiple architectures. The target will be transitioned into different configurations, with distinct architectures.

    The target can be one of:

    • cxx_binary()
    • [shared] subtarget cxx_library()
    • cxx_library() which have preferred_linkage = shared attribute

  • executable_name: By default, the name of the universal executable is same as the name of the binary from the binary target attribute. Set executable_name to override the default.

  • universal: Controls whether the output is universal binary. Any value overrides the presence of the config//cpu/constraints:universal-enabled constraint. Read the rule docs for more information on resolution.

Details​

The output of the rule is a universal binary:

  • If config//cpu/constraints:universal-enabled is present in the target platform.
  • If the universal attribute is set to True.

If none of the conditions are met, then the rule acts as a nop alias().

The universal attribute, if present, takes precedence over constraint. For example, if universal = False, then the presence of the constraint would not affect the output.

d_binary​

def d_binary(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    contacts: list[str] = ...,
    default_host_platform: None | str = ...,
    deps: list[str] = ...,
    labels: list[str] = ...,
    licenses: list[str] = ...,
    linker_flags: list[str] = ...,
    srcs: list[str] | dict[str, str] = ...,
) -> None

A d_binary() rule builds a native executable from the supplied set of D source files and dependencies.

Parameters​

  • name: name of the target
  • default_target_platform: specifies the default target platform, used when no platforms are specified on the command line
  • target_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • exec_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with an execution platform
  • visibility: a list of visibility patterns restricting what targets can depend on this one
  • within_view: a list of visibility patterns restricting what this target can depend on
  • metadata: a key-value map of metadata associated with this target
  • tests: a list of targets that provide tests for this one
  • modifiers: an array of modifiers associated with this target
  • deps: The set of dependencies of this rule. Each element should be a string specifying a d_library rule defined elsewhere (e.g. ':foo' or '//foo:bar').
  • linker_flags: The list of flags to be passed to the linker. Each element should be a string specifying a linker flag (e.g. '--as-needed').
  • srcs: The set of D source files to be compiled by this rule. Each element should be a string specifying a source file (e.g. 'foo/bar.d').

Details​

Examples:


# A rule that builds a D native executable from a single .d file
# and a library dependency.
d_binary(
  name='greet',
  srcs=[
    'greet.d',
  ],
  deps=[
    ':greeting',
  ],
)

d_library(
  name='greeting',
  srcs=[
    'greeting.d',
  ],
  deps=[
    ':join',
  ],
)

d_library(
  name='join',
  srcs=[
    'join.d',
  ],
)

d_library​

def d_library(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    contacts: list[str] = ...,
    default_host_platform: None | str = ...,
    deps: list[str] = ...,
    labels: list[str] = ...,
    licenses: list[str] = ...,
    linker_flags: list[str] = ...,
    srcs: list[str] | dict[str, str] = ...,
) -> None

A d_library() rule represents a set of D source files.

Parameters​

  • name: name of the target
  • default_target_platform: specifies the default target platform, used when no platforms are specified on the command line
  • target_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • exec_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with an execution platform
  • visibility: a list of visibility patterns restricting what targets can depend on this one
  • within_view: a list of visibility patterns restricting what this target can depend on
  • metadata: a key-value map of metadata associated with this target
  • tests: a list of targets that provide tests for this one
  • modifiers: an array of modifiers associated with this target
  • deps: The set of dependencies of this rule. Each element should be a string specifying a d_library rule defined elsewhere (e.g. ':foo' or '//foo:bar').
  • srcs: The set of D source files to be compiled by this rule. Each element should be a string specifying a source file (e.g. 'foo/bar.d').

Details​

Examples:


# A simple library with a single source file and a single dependency.
d_library(
  name='greeting',
  srcs=[
    'greeting.d',
  ],
  deps=[
    ':join',
  ],
)

d_library(
  name='join',
  srcs=[
    'join.d',
  ],
)

d_test​

def d_test(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    contacts: list[str] = ...,
    default_host_platform: None | str = ...,
    deps: list[str] = ...,
    labels: list[str] = ...,
    licenses: list[str] = ...,
    linker_flags: list[str] = ...,
    srcs: list[str] | dict[str, str] = ...,
    test_rule_timeout_ms: None | int = ...,
) -> None

A d_test() rule is used to define a set of D source files that contain tests to run via D's unittest support. The source code of the test must provide a main() function.

Parameters​

  • name: name of the target
  • default_target_platform: specifies the default target platform, used when no platforms are specified on the command line
  • target_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • exec_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with an execution platform
  • visibility: a list of visibility patterns restricting what targets can depend on this one
  • within_view: a list of visibility patterns restricting what this target can depend on
  • metadata: a key-value map of metadata associated with this target
  • tests: a list of targets that provide tests for this one
  • modifiers: an array of modifiers associated with this target
  • deps: The set of dependencies of this rule. Each element should be a string specifying a d_library rule defined elsewhere (e.g. ':foo' or '//foo:bar').
  • labels: A list of labels to be applied to these tests. These labels are arbitrary text strings and have no meaning within buck itself. They can, however, have meaning for you as a test author (e.g., smoke or fast). A label can be used to filter or include a specific d_test() rule when executing buck test
  • srcs: The set of D source files to be compiled by this rule. Each element should be a string specifying a source file (e.g. 'foo/bar.d').
  • test_rule_timeout_ms: If set specifies the maximum amount of time (in milliseconds) in which all of the tests in this rule should complete. This overrides the default rule_timeout if any has been specified in .buckconfig .

Details​

Examples:


# A rule that builds and runs D test with a single source file.
d_test(
  name = 'test',
  srcs = [
    'test.d',
  ],
)

erlang_app​

def erlang_app(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    _toolchain: str = ...,
    app_src: None | str = ...,
    applications: list[str] = ...,
    build_edoc_chunks: bool = ...,
    contacts: list[str] = ...,
    env: None | dict[str, str] = ...,
    erl_opts: None | list[str] = ...,
    extra_includes: list[str] = ...,
    extra_properties: None | dict[str, str | list[str]] = ...,
    include_src: bool = ...,
    included_applications: list[str] = ...,
    includes: list[str] = ...,
    labels: list[str] = ...,
    mod: None | (str, list[str]) = ...,
    os_env: None | dict[str, str] = ...,
    peek_private_includes: bool = ...,
    resources: list[str] = ...,
    shell_configs: list[str] = ...,
    shell_libs: list[str] = ...,
    srcs: list[str] = ...,
    use_global_parse_transforms: bool = ...,
    version: str = ...,
    xrl_includefile: None | str = ...,
    yrl_includefile: None | str = ...,
) -> None

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

Parameters​

  • name: name of the target

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

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

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

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

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

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

  • metadata: a key-value map of metadata associated with this target

  • tests: a list of targets that provide tests for this one

  • modifiers: an array of modifiers associated with this target

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

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

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

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

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

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

  • build_edoc_chunks: This attribute controls if the output of the builds also create edoc chunks.

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

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

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

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

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

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

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

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

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

  • included_applications: Check the documentation for applications.

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

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

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

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

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

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

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

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

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

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

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

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

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

Details​

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

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

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

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

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

Examples:

Minimal Erlang Application​

erlang_application(
    name = "minimal",
)

With priv/ directory​

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

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

Using OTP applications and mod field​

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

Using Yecc and Leex​

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

erlang_app_includes​

def erlang_app_includes(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    _toolchain: str = ...,
    application_name: str,
    contacts: list[str] = ...,
    includes: list[str] = ...,
    labels: list[str] = ...,
    os_env: None | dict[str, str] = ...,
) -> None

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

Parameters​

  • name: name of the target
  • default_target_platform: specifies the default target platform, used when no platforms are specified on the command line
  • target_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • exec_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with an execution platform
  • visibility: a list of visibility patterns restricting what targets can depend on this one
  • within_view: a list of visibility patterns restricting what this target can depend on
  • metadata: a key-value map of metadata associated with this target
  • tests: a list of targets that provide tests for this one
  • modifiers: an array of modifiers associated with this target
  • os_env: This attribute allows to set additional values for the operating system environment for invocations to the Erlang toolchain.

erlang_escript​

def erlang_escript(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    _toolchain: str = ...,
    bundled: bool = ...,
    configs: list[str] = ...,
    contacts: list[str] = ...,
    deps: list[str],
    emu_args: list[str] = ...,
    include_priv: bool = ...,
    labels: list[str] = ...,
    main_module: None | str = ...,
    os_env: None | dict[str, str] = ...,
    resources: list[str] = ...,
    script_name: None | str = ...,
) -> None

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

Parameters​

  • name: name of the target

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

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

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

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

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

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

  • metadata: a key-value map of metadata associated with this target

  • tests: a list of targets that provide tests for this one

  • modifiers: an array of modifiers associated with this target

  • bundled: Setting bundled to True does generate a folder structure and escript trampoline instead of an archive.

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

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

  • emu_args: This field specifies the emulator flags that the escript uses on execution. It is often desirable to specify the number of threads and schedulers the escript uses. Please refer to the OTP documentation for details.

  • include_priv: Setting this flag, will package the applications priv directory in the escript. Similar to files added through the resources field, the priv folders files can then be accessed by escript"extract/2.

  • main_module: Overrides the default main module. Instead of deferring the main module from the scripts filename, the specified module is used. That module needs to export a main/1 function that is called as entry point.

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

  • resources: This adds the targets default output to the escript archive. To access these files, you need to use escript:extract/2, which will extract the entire escript in memory. The relevant files can then be accessed through the archive section.

    Please refer to the escript:extract/2 for more details.

  • script_name: Overrides the filename of the produced escript.

Details​

Escripts by default always try to use the module that has the same name as the escripts basename as entry point, e.g. if the escript is called script.escript then running the escript will try to call script:main/1. Both name and main module can be overwritten though.

The target name doubles as the default escript name. If the main_module attribute is not used, the escript filename will be <name>.escript.

Examples:

erlang_escript(
    name = "script",
    main_module = "main_module",
    script_name = "the_script",
    deps = [
        ":escript_app",
    ],
    emu_args = ["+sbtu", "+A1"],
)

erlang_application(
    name = "escript_app",
    srcs = ["src/main_module.erl"],
    applications = [
        "kernel",
        "stdlib",
    ],
)

erlang_otp_binaries​

def erlang_otp_binaries(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    contacts: list[str] = ...,
    erl: str,
    erlc: str,
    escript: str,
    labels: list[str] = ...,
    os_env: None | dict[str, str] = ...,
) -> None

This target defines the executables for the Erlang toolchains, and is required to defined a toolchain.

Parameters​

  • name: name of the target
  • default_target_platform: specifies the default target platform, used when no platforms are specified on the command line
  • target_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • exec_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with an execution platform
  • visibility: a list of visibility patterns restricting what targets can depend on this one
  • within_view: a list of visibility patterns restricting what this target can depend on
  • metadata: a key-value map of metadata associated with this target
  • tests: a list of targets that provide tests for this one
  • modifiers: an array of modifiers associated with this target
  • erl: Reference to erl binary
  • erlc: Reference to erlc binary
  • escript: Reference to escript binary
  • os_env: This attribute allows to set additional values for the operating system environment for invocations to the Erlang toolchain.

Details​

Examples:

erlang_otp_binaries( name = "local", erl = "local/erl", erlc = "local/erlc", escript = "local/escript", )

erlang_release​

def erlang_release(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    _toolchain: str = ...,
    applications: list[str | (str, str)],
    contacts: list[str] = ...,
    include_erts: bool = ...,
    labels: list[str] = ...,
    multi_toolchain: None | list[str] = ...,
    os_env: None | dict[str, str] = ...,
    overlays: dict[str, list[str]] = ...,
    release_name: None | str = ...,
    version: str = ...,
) -> None

The erlang_release target builds OTP releases. Please refer to the OTP documentation for more details about releases.

Parameters​

  • name: name of the target
  • default_target_platform: specifies the default target platform, used when no platforms are specified on the command line
  • target_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • exec_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with an execution platform
  • visibility: a list of visibility patterns restricting what targets can depend on this one
  • within_view: a list of visibility patterns restricting what this target can depend on
  • metadata: a key-value map of metadata associated with this target
  • tests: a list of targets that provide tests for this one
  • modifiers: an array of modifiers associated with this target
  • applications: This field specifies the list of applications that the release should start in the given order, and optionally the start type. Top-level applications without given start type are started with type permanent.
  • include_erts: This field controls whether OTP applications and the Erlang runtime system should be included as part of the release. Please note, that at the moment the erts folder is just erts/.
  • multi_toolchain: This field controls whether the release should be built with a single toolchain, or multiple toolchains. In the latter case, all output paths are prefixed with the toolchain name.
  • os_env: This attribute allows to set additional values for the operating system environment for invocations to the Erlang toolchain.
  • overlays: Overlays can be used to add files to the release. They are specified as mapping from path (from the release root) to list of targets. The targets files are places flat at the target location with their basename.
  • release_name: The release name can explicitly be set by this field. This overwrites the default from the target name.
  • version: The version field specifies the release version. The release version is used in the release resource file, and is part of the path for the folder containing the boot scripts.

Details​

The erlang_release target does by default (without overlays) package:

  • applications that are required to start the release
  • release resource file <relname>.rel (see rel(4))
  • boot script start.script (see rel(4))
  • binary boot script start.boot
  • bin/release_variables

The release_variables file contains release name, version, and erts version in shell syntax, e.g.

ERTS_VSN="12.1.2"
REL_NAME="rel1"
REL_VSN="1.0.0"

The target name doubles as the default release name. If the release_name attribute is used, the release name will be sources from there instead.

Examples:

erlang_release(
    name = "world",
    version = "1.0.0",
    applications = [
        "//apps//app_a:app_a",
        "//apps//app_b:app_b",
    ],
    overlays = {
        "releases/1.0.0": [
            ":sys.config.src",
        ],
        "bin": [
            ":start.sh",
        ],
    },
)

export_file(
    name = "sys.config.src",
    src = "sys.config",
)

export_file(
    name = "start.sh",
    src = "start.sh",
)

erlang_test​

def erlang_test(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    _artifact_annotation_mfa: str = ...,
    _cli_lib: str = ...,
    _ct_opts: str = ...,
    _providers: str = ...,
    _test_binary_lib: str = ...,
    _toolchain: str = ...,
    _trampoline: None | str = ...,
    _trampolines: None | list[str] = ...,
    common_app_env: dict[str, str] = ...,
    config_files: list[str] = ...,
    contacts: list[str] = ...,
    deps: list[str] = ...,
    env: dict[str, str] = ...,
    extra_ct_hooks: list[str] = ...,
    extra_erl_flags: list[str] = ...,
    labels: list[str] = ...,
    os_env: None | dict[str, str] = ...,
    preamble: str = ...,
    property_tests: list[str] = ...,
    remote_execution: None | str | dict[str, None | bool | int | str | list[dict[str, str]] | dict[str, str]] = ...,
    resources: list[str] = ...,
    shell_configs: list[str] = ...,
    shell_libs: list[str] = ...,
    suite: str,
) -> None

The erlang_test ruls defines a test target for a single test suite. In most cases you want to define multiple suites in one go. The erlang_tests macro allows users to generate erlang_test targets for multiple test suites. Each suite <name>_SUITE.erl will have a generated hidden erlang_test target whose name is <name>_SUITE.

Parameters​

  • name: name of the target

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

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

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

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

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

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

  • metadata: a key-value map of metadata associated with this target

  • tests: a list of targets that provide tests for this one

  • modifiers: an array of modifiers associated with this target

  • _trampoline: DEPRECATED. Use _trampolines instead.

  • common_app_env: Application environment variables for the common application.

  • config_files: Will specify what config files the erlang beam machine running test with should load, for reference look at OTP documentation. These ones should consist of default_output of some targets. In general, this field is filled with target coming from then export_file rule, as in the example below.

  • deps: The set of dependencies needed for all suites included in the target to compile and run. They could be either erlang_app(lication) or erlang_test targets, although the latter is discouraged. If some suites need to access common methods, a common helper file should be created and included in the srcs field of the erlang_tests target. If some applications are included as dependencies of this target, their private include will automatically be pulled and made available for the test. That allows tests to access the private header files from the applications under test.

  • env: Add the given values to the environment variables with which the test is executed.

  • extra_ct_hooks: List of additional Common Test hooks. The strings are interpreted as Erlang terms.

  • extra_erl_flags: List of additional command line arguments given to the erl command invocation. These arguments are added to the front of the argument list.

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

  • resources: The resources field specifies targets whose default output are placed in the test data_dir directory for all the suites present in the macro target. Additionally, if data directory are present in the directory along the suite, this one will be pulled automatically for the relevant suite.

    Any target can be used, e.g. if you want to place a built escript in the data_dir directory, you can use an erlang_escript target.

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

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

  • suite: The source file for the test suite. If you are using the macro, you should use the suites attribute instead.

    The suites attribute specifies which erlang_test targets should be generated. For each suite "path_to_suite/suite_SUITE.erl" an implicit 'erlang_test' target suite_SUITE will be generated.

Details​

Each erlang_test target implements tests using the Common Test library OTP documentation. They can, although it is not recommended, also act as dependencies of other tests. The default output of this rule is a "test_folder", consisting of the compiled test suite and the data directory.

For each suite <name>_SUITE.erl, if a data_dir <name>_SUITE_data is present along the suite, (as per the data_dir naming scheme for ct), it will automatically adds the corresponding resource target to the generated test target of the suite. Resources will be placed in the Data directory (data_dir) of each of the suite.

It allows the writer of the rule to add global configuration files and global default dependencies (e.g meck). These ones should be specified using global variables erlang.erlang_tests_default_apps and erlang.erlang_tests_default_config respectively.

The erlang_tests macro forwards all attributes to the erlang_test. It defines some attributes that control how the targets get generated:

  • srcs ([source]): Set of files that the suites might depend on and that are not part of any specific application. A "meta" application having those files as sources will automatically be created, and included in the dependencies of the tests.

One can call

  • buck2 build //my_app:test_SUITE to compile the test files together with its dependencies.
  • buck2 test //my_app:other_test_SUITE to run the test.
  • buck2 run //my_app:other_test_SUITE to open an interactive test shell, where tests can be run iteratively.

buck2 test will rely on tpx to run the suite. To get access to tpx commands, add -- after the target. For example:

  • buck2 test //my_app:other_test_SUITE -- --help will print the list of tpx available command line parameters.
  • buck2 test //my_app:other_test_SUITE -- group.mycase will only run those test cases that match the pattern group.mycase

Examples:

erlang_test( name = "unit_test_SUITE", suite = "unit_test_SUTIE.erl", deps = [":my_other_app"], contacts = ["author@email.com"], )

erlang_tests( suites = ["test_SUITE.erl", "other_test_SUITE".erl], deps = [":my_app"], contacts = ["author@email.com"], )

export_file​

def export_file(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    contacts: list[str] = ...,
    default_host_platform: None | str = ...,
    labels: list[str] = ...,
    licenses: list[str] = ...,
    mode: None | str = ...,
    out: None | str = ...,
    src: None | str = ...,
) -> None

An export_file() takes a single file or folder and exposes it so other rules can use it.

Parameters​

  • name: name of the target
  • default_target_platform: specifies the default target platform, used when no platforms are specified on the command line
  • target_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • exec_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with an execution platform
  • visibility: a list of visibility patterns restricting what targets can depend on this one
  • within_view: a list of visibility patterns restricting what this target can depend on
  • metadata: a key-value map of metadata associated with this target
  • tests: a list of targets that provide tests for this one
  • modifiers: an array of modifiers associated with this target
  • mode: How files are referenced internally in buck. If set to 'copy', then a full copy will be made into the new location in buck-out. If set to 'reference', the original file will be used by internal build rules in-place. However, this mode does not work across repositories or if the 'out' property is set. For read-only operations, 'reference' can be more performant.
  • out: The name which the file will be called if another rule depends on it instead of the name it already has.
  • src: The path to the file that should be exported.

Details​

Examples:

The best way to see how the export_file() rule works is with some examples. The common case is:


export_file(
  name = 'example.html',
)

# This is equivalent to

export_file(
  name = 'example.html',
  src = 'example.html',
  out = 'example.html',
)

It is sometimes useful to refer to the file not by its path, but by a more logical name:


export_file(
  name = 'example',
  src = 'example.html',
)

# This is equivalent to

export_file(
  name = 'example',
  src = 'example.html',
  out = 'example.html',
)

Finally, there are occasions where you want to export a file more than once but want to copy it to a different name for each output:


export_file(
  name = 'runner',
  src = 'RemoteRunner.html',
)

export_file(
  name = 'runner_hta',
  src = 'RemoteRunner.html',
  out = 'RemoteRunner.hta',
)

Using the export_file() rule is also simple:


export_file(
  name = 'example',
  src = 'example.html',
)

genrule(
  name = 'demo',
  out = 'result.html',
  cmd = 'cp $(location :example) $OUT',
)

external_test_runner​

def external_test_runner(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    binary: str,
    contacts: list[str] = ...,
    default_host_platform: None | str = ...,
    labels: list[str] = ...,
    licenses: list[str] = ...,
) -> None

Parameters​

  • name: name of the target
  • default_target_platform: specifies the default target platform, used when no platforms are specified on the command line
  • target_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • exec_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with an execution platform
  • visibility: a list of visibility patterns restricting what targets can depend on this one
  • within_view: a list of visibility patterns restricting what this target can depend on
  • metadata: a key-value map of metadata associated with this target
  • tests: a list of targets that provide tests for this one
  • modifiers: an array of modifiers associated with this target

filegroup​

def filegroup(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    contacts: list[str] = ...,
    copy: bool = ...,
    default_host_platform: None | str = ...,
    labels: list[str] = ...,
    licenses: list[str] = ...,
    srcs: list[str] | dict[str, str] = ...,
) -> None

This rule provides access to a set of files.

Parameters​

  • name: name of the target
  • default_target_platform: specifies the default target platform, used when no platforms are specified on the command line
  • target_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • exec_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with an execution platform
  • visibility: a list of visibility patterns restricting what targets can depend on this one
  • within_view: a list of visibility patterns restricting what this target can depend on
  • metadata: a key-value map of metadata associated with this target
  • tests: a list of targets that provide tests for this one
  • modifiers: an array of modifiers associated with this target
  • srcs: The set of files to include in this rule.

Details​

Files are accessible to genrule()s by using their relative path after a $(location) string parameter macro.

Other rules may handle filegroup() rules natively for attributes such as resources.

Examples:

In this example a target exports .xml files from all subdirectories in resources.


filegroup(
  name = 'example',
  srcs = glob(['resources/**/*.xml']),
)

genrule(
  name = 'process_xml',
  out = 'processed.xml',
  cmd = '$(exe //example:tool) -in $(location :example)/resources/file.xml > $OUT',
)

gen_aidl​

def gen_aidl(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _android_toolchain: str = ...,
    _apple_platforms: dict[str, str] = ...,
    _exec_os_type: str = ...,
    _java_toolchain: str = ...,
    aidl: str,
    aidl_srcs: list[str] = ...,
    contacts: list[str] = ...,
    default_host_platform: None | str = ...,
    deps: list[str] = ...,
    import_path: str = ...,
    import_paths: list[str] = ...,
    labels: list[str] = ...,
    licenses: list[str] = ...,
) -> None

A gen_aidl() rule is used to generate .java files from .aidl files.

Parameters​

  • name: name of the target
  • default_target_platform: specifies the default target platform, used when no platforms are specified on the command line
  • target_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • exec_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with an execution platform
  • visibility: a list of visibility patterns restricting what targets can depend on this one
  • within_view: a list of visibility patterns restricting what this target can depend on
  • metadata: a key-value map of metadata associated with this target
  • tests: a list of targets that provide tests for this one
  • modifiers: an array of modifiers associated with this target
  • aidl: The path to an .aidl file to convert to a .java file.
  • aidl_srcs: Path to .aidl files the target aidl file imports.
  • deps: A list of rules that must be built before this rule.
  • import_path: The search path for import statements for the aidl command. (This is the -I argument when invoking aidl from the command line. For many apps it will be the base dir where all aidl files are, with project root as its parent, e.g. app/src/main/aidl.). This is the same as the path to the aidl file relative to what would be returned from root.

Details​

Examples:


android_library(
  name = 'lib',
  srcs = glob(['**/*.java']) + [':aidl'],
  manifest = '//res/org/opencv:manifest',
  deps = [
    '//res/org/opencv:res',
  ],
  visibility = [ 'PUBLIC' ],
)

gen_aidl(
    name = 'aidl',
    aidl = 'engine/OpenCVEngineInterface.aidl',
    import_path = 'java/',
)

genrule​

def genrule(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    _build_only_native_code: bool = ...,
    _exec_os_type: str = ...,
    _genrule_toolchain: str = ...,
    always_print_stderr: bool = ...,
    bash: None | str = ...,
    cacheable: None | bool = ...,
    cmd: None | str = ...,
    cmd_exe: None | str = ...,
    contacts: list[str] = ...,
    default_host_platform: None | str = ...,
    default_outs: None | list[str] = ...,
    enable_sandbox: None | bool = ...,
    env: dict[str, str] = ...,
    environment_expansion_separator: None | str = ...,
    executable: None | bool = ...,
    executable_outs: None | list[str] = ...,
    labels: list[str] = ...,
    licenses: list[str] = ...,
    metadata_env_var: None | str = ...,
    metadata_path: None | str = ...,
    need_android_tools: bool = ...,
    no_outputs_cleanup: bool = ...,
    out: None | str = ...,
    outs: None | dict[str, list[str]] = ...,
    remote: None | bool = ...,
    remote_execution_dependencies: list[dict[str, str]] = ...,
    srcs: list[str] | dict[str, str] = ...,
    type: None | str = ...,
    weight: None | int = ...,
) -> None

A genrule() is used to generate files from a shell command. It must produce a single output file or folder.

Parameters​

  • name: name of the target

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

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

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

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

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

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

  • metadata: a key-value map of metadata associated with this target

  • tests: a list of targets that provide tests for this one

  • modifiers: an array of modifiers associated with this target

  • bash: A platform-specific version of the shell command parameter cmd. It runs on Linux and UNIX systems—including OSX—on which bash is installed. It has a higher priority than cmd. The bash argument is run with /usr/bin/env bash -c. It has access to the same set of macros and variables as the cmd argument.

  • cmd: The shell command to run to generate the output file. It is the fallback for bash and cmd_exe arguments. The following environment variables are populated by Buck and available to the shell command. They are accessed using the syntax:

    ${<variable>}

    Example:

    ${SRCS}

    ${SRCS}

    A string expansion of the srcs argument delimited by the environment_expansion_separator argument where each element of srcs will be translated into a relative path.

    ${SRCDIR}

    The relative path to a directory to which sources are copied prior to running the command.

    ${OUT}

    The output file or directory for the genrule(). This variable will have whatever value is specified by the out argument if not using named outputs. If using named outputs, this variable will be the output directory.

    The value should be a valid filepath. The semantics of the shell command determine whether this filepath is treated as a file or a directory. If the filepath is a directory, then the shell command needs to create it if not using named outputs. Otherwise, it will be automatically created. All outputs (directories and files) must be readable, writable, and (in the case of directories) executable by the current user.

    The file or directory specified by this variable must always be written by this command. If not, the execution of this rule will be considered a failure, halting the build process.

    ${TMP}

    A temporary directory which can be used for intermediate results and will not be bundled into the output.

  • cmd_exe: A platform-specific version of the shell command parameter cmd. It runs on Windows and has a higher priority than cmd. The cmd_exe argument is run with cmd.exe /v:off /c. It has access to the same set of macros and variables as the cmd argument.

  • default_outs: Default output which must be present if the outs arg is present. Otherwise does not apply.

    If a rule with outs is consumed without an output label, the default output is returned. The default output does not need to be present in any of the named outputs defined in outs.

    Note that a maximum of one value may be present in this list. For example:

    default_outs = [ "output_one", ]

    is valid, whereas

    default_outs = [ "output_one", "output_two", ]

    is not.

  • enable_sandbox: Whether this target should be executed in a sandbox or not.

  • env: A map of variables to be set in the environment where the shell command is run.

  • environment_expansion_separator: The delimiter between paths in environment variables, such as SRCS, that can contain multiple paths. It can be useful to specify this parameter if the paths could contain spaces.

  • executable: Whether the output of the genrule is itself executable. Marking an output as executable makes buck run and $(exe ...) macro expansion work with this target.

  • executable_outs: Only valid if the outs arg is present. Dictates which of those named outputs are marked as executable.

  • out: The name of the output file or directory. The complete path to this argument is provided to the shell command through the OUT environment variable. Only one of out or outs may be present.

  • outs: Mapping defining named outputs to output paths relative to the rule's output directory. Only one of out or outs may be present.

    Example:


    genrule(
      name = "named_outputs",
      outs = {
        "output1": [
          "out1.txt",
        ],
        "output2": [
          "out2.txt",
        ],
      },
      default_outs = [ "out1.txt" ],
      cmd = "echo something> $OUT/out1.txt && echo another> $OUT/out2.txt",
    )

    Note that a maximum of one value may be present in the list in this map. For example:


    outs = {
      "output1": [
        "out1.txt",
      ],
    },

    is valid, whereas


    outs = {
      "output1": [
        "out1.txt",
        "out2.txt",
      ],
    },

    is not.

  • remote: Opts this genrule in to remote execution. Note that it is only safe to execute a genrule remotely if it is completely hermetic and completely and correctly describes its dependencies. Defaults to false. This parameter is unstable. It is subject to removal, default reversal, and other arbitrary changes in the future.

  • srcs: Either a list or a map of the source files which Buck makes available to the shell command at the path in the SRCDIR environment variable. If you specify a list, the source files are the names in the list. If you specify a map, the source files are made available as the names in the keys of the map, where the values of the map are the original source file names.

  • type: Specifies the type of this genrule. This is used for logging and is particularly useful for grouping genrules that share an underlying logical "type".

    For example, if you have the following cxx_genrule defined in the root directory of your Buck project



    cxx_genrule(
      name = 'cxx_gen',
      type = 'epilog',
      cmd  = 'touch finish.txt; cp finish.txt $OUT',
      out  = 'finish.txt'
    )

    then the following buck query command



    buck query "attrfilter( type, 'epilog', '//...' )"

    returns



    //:cxx_gen

  • weight: How many local slots these genrule should take when executing locally.

Details​

Examples:

This genrule() uses a Python script to derive a new AndroidManifest.xml from an AndroidManifest.xml in the source tree. Note you don't need to prepend execution commands with python: Buck knows how to execute different kinds of binaries using $(exe) command.


genrule(
  name = 'generate_manifest',
  srcs = [
    'AndroidManifest.xml',
  ],
  bash = '$(exe //python/android:basic_to_full) '               '$SRCDIR/AndroidManifest.xml > $OUT',
  cmd_exe = '$(exe //python/android:basic_to_full) '               '%SRCDIR%\AndroidManifest.xml > %OUT%',
  out = 'AndroidManifest.xml',
)


genrule(
  name = 'generate_manifest_with_named_outputs',
  srcs = [
    'AndroidManifest.xml',
  ],
  bash = '$(exe //python/android:basic_to_full) '               '$SRCDIR/AndroidManifest.xml > $OUT/AndroidManifest.xml',
  cmd_exe = '$(exe //python/android:basic_to_full) '               '%SRCDIR%\AndroidManifest.xml > %OUT%\AndroidManifest.xml',
  outs =  {
    "manifest": [ "AndroidManifest.xml" ],
  },
  default_outs = [ "AndroidManifest.xml" ],
)

For named outputs, build with any of the following:


  buck build //:generate_manifest_with_named_outputs


  buck build //:generate_manifest_with_named_outputs[manifest]

Consume in srcs with:


export_file(
    name = "magic1",
    src = ":generate_manifest_with_named_outputs",
    out = "some_dir_to_copy_to/AndroidManifest.xml",
)


export_file(
    name = "magic2",
    src = ":generate_manifest_with_named_outputs[manifest]",
    out = "some_dir_to_copy_to/AndroidManifest.xml",
)

Note that magic1 consumes generate_manifest_with_named_outputs's default output. magic2 consumes generate_manifest_with_named_outputs's named output "manifest," which happen to be pointing to the same output as the default output in this case, but they do not have to point to the same output.

git_fetch​

def git_fetch(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    _git_fetch_tool: str = ...,
    contacts: list[str] = ...,
    default_host_platform: None | str = ...,
    labels: list[str] = ...,
    licenses: list[str] = ...,
    repo: str,
    rev: str,
) -> None

Checkout a commit from a git repository.

Parameters​

  • name: name of the target
  • default_target_platform: specifies the default target platform, used when no platforms are specified on the command line
  • target_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • exec_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with an execution platform
  • visibility: a list of visibility patterns restricting what targets can depend on this one
  • within_view: a list of visibility patterns restricting what this target can depend on
  • metadata: a key-value map of metadata associated with this target
  • tests: a list of targets that provide tests for this one
  • modifiers: an array of modifiers associated with this target
  • repo: Url suitable as a git remote.
  • rev: 40-digit hex SHA-1 of the git commit.

Details​

Examples:

git_fetch(
    name = "serde.git",
    repo = "https://github.com/serde-rs/serde",
    rev = "fccb9499bccbaca0b7eef91a3a82dfcb31e0b149",
)

go_binary​

def go_binary(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    _asan: bool = ...,
    _build_info: dict[str, typing.Any] = ...,
    _build_tags: list[str] = ...,
    _cxx_toolchain: str = ...,
    _exec_os_type: str = ...,
    _go_stdlib: str = ...,
    _go_toolchain: str = ...,
    _race: bool = ...,
    asan: bool = ...,
    assembler_flags: list[str] = ...,
    build_tags: list[str] = ...,
    cgo_enabled: None | bool = ...,
    compiler_flags: list[str] = ...,
    contacts: list[str] = ...,
    cxx_compiler_flags: list[str] = ...,
    cxx_preprocessor_flags: list[str] = ...,
    default_host_platform: None | str = ...,
    deps: list[str] = ...,
    embedcfg: None | str = ...,
    external_linker_flags: list[str] = ...,
    header_namespace: None | str = ...,
    headers: list[str] | dict[str, str] = ...,
    labels: list[str] = ...,
    licenses: list[str] = ...,
    link_mode: None | str = ...,
    link_style: None | str = ...,
    linker_flags: list[str] = ...,
    package_name: None | str = ...,
    package_root: None | str = ...,
    platform: None | str = ...,
    race: bool = ...,
    resources: list[str] = ...,
    srcs: list[str] = ...,
) -> None

A go_binary() rule builds a native executable from the supplied set of Go source files and dependencies. The files supplied are expected to be in the main package, implicitly.

Parameters​

  • name: name of the target
  • default_target_platform: specifies the default target platform, used when no platforms are specified on the command line
  • target_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • exec_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with an execution platform
  • visibility: a list of visibility patterns restricting what targets can depend on this one
  • within_view: a list of visibility patterns restricting what this target can depend on
  • metadata: a key-value map of metadata associated with this target
  • tests: a list of targets that provide tests for this one
  • modifiers: an array of modifiers associated with this target
  • _build_info: Build info that is passed along here will be late-stamped into a fb_build_info section on the output binary
  • asan: If true, enable ASAN.
  • assembler_flags: The set of additional assembler flags to pass to go tool asm.
  • build_tags: Build tags to apply to this target and its dependencies.
  • cgo_enabled: Analog of CGO_ENABLED env-var, applies to this target and its dependencies. If None go_toolchain.default_cgo_enabled value will be applied.
  • compiler_flags: The set of additional compiler flags to pass to go tool compile.
  • cxx_compiler_flags: GCC/Clang flags to use when compiling any of the above C/C++ sources (which require compilation).
  • cxx_preprocessor_flags: GCC/Clang flags to use when preprocessing any of the above C/C++ sources (which require preprocessing).
  • deps: The set of dependencies of this rule. Currently, this only supports go_library rules.
  • external_linker_flags: Extra external linker flags passed to go link via -extld argument.
  • 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. 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 name can contain forward slashes (/). The headers can be included with #include "$HEADER_NAMESPACE/$HEADER_NAME" or #include <$HEADER_NAMESPACE/$HEADER_NAME> , where $HEADER_NAMESPACE is the value of the target's header_namespace attribute, and $HEADER_NAME is the header name if specified, and the filename of the header file otherwise. See header_namespace for more information.
  • link_mode: Determines the link mode (equivalent of -mode). Can be one of the following values: internal, external. If no value is provided, the mode is set automatically depending on the other args.
  • link_style: Determines whether to build and link this rule's dependencies statically or dynamically. Can be one of the following values: static, static_pic or shared. This argument is relevant only if the cgo extension is enabled. Otherwise, Buck ignores this argument.
  • linker_flags: Extra linker flags passed to go link
  • package_name: Sets the full name of the package being compiled. This defaults to the path from the buck root. (e.g. given a ./.buckconfig, a rule in ./a/b/BUCK defaults to package "a/b")
  • package_root: Sets Go package direactory (relative to BUCK file). By default (or if None passes) package_root is being detected automatically. Empty string of Go package is on the same level as BUCK file otherwise the subdirectory name. Example for srcs = ["foo/bar.go"], package_root = "foo"
  • race: If true, enable data race detection.
  • srcs: The set of source files to be compiled by this rule. .go files will be compiled with the Go compiler, .s files will be compiled with the assembler, and everything else is assumed to be files that may be #included by the assembler.

Details​

Examples:

For more examples, check out our integration tests.


go_binary(
  name='greet',
  srcs=[
    'main.go',
  ],
  deps=[
    ':greeting',
  ],
)

go_library(
  name='greeting',
  srcs=[
    'greeting.go',
  ],
  deps=[
    ':join',
  ],
)

go_library(
  name='join',
  srcs=[
    'join.go',
  ],
)

go_bootstrap_binary​

def go_bootstrap_binary(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    _exec_os_type: str = ...,
    _go_bootstrap_toolchain: str = ...,
    entrypoints: list[str] = ...,
    srcs: list[str] = ...,
    workdir: str = ...,
) -> None

Parameters​

  • name: name of the target
  • default_target_platform: specifies the default target platform, used when no platforms are specified on the command line
  • target_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • exec_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with an execution platform
  • visibility: a list of visibility patterns restricting what targets can depend on this one
  • within_view: a list of visibility patterns restricting what this target can depend on
  • metadata: a key-value map of metadata associated with this target
  • tests: a list of targets that provide tests for this one
  • modifiers: an array of modifiers associated with this target
  • entrypoints: Package name or file names
  • srcs: The set of source files to be compiled by this rule. .go files will be compiled with the Go compiler, .s files will be compiled with the assembler, and everything else is assumed to be files that may be #included by the assembler.
  • workdir: Change to subdir before running the command

go_exported_library​

def go_exported_library(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    _asan: bool = ...,
    _build_info: dict[str, typing.Any] = ...,
    _build_tags: list[str] = ...,
    _cxx_toolchain: str = ...,
    _exec_os_type: str = ...,
    _go_stdlib: str = ...,
    _go_toolchain: str = ...,
    _race: bool = ...,
    asan: bool = ...,
    assembler_flags: list[str] = ...,
    build_mode: str,
    build_tags: list[str] = ...,
    cgo_enabled: None | bool = ...,
    compiler_flags: list[str] = ...,
    contacts: list[str] = ...,
    cxx_compiler_flags: list[str] = ...,
    cxx_preprocessor_flags: list[str] = ...,
    default_host_platform: None | str = ...,
    deps: list[str] = ...,
    embedcfg: None | str = ...,
    external_linker_flags: list[str] = ...,
    generate_exported_header: bool = ...,
    header_namespace: None | str = ...,
    headers: list[str] | dict[str, str] = ...,
    labels: list[str] = ...,
    licenses: list[str] = ...,
    link_mode: None | str = ...,
    link_style: None | str = ...,
    linker_flags: list[str] = ...,
    package_name: None | str = ...,
    package_root: None | str = ...,
    platform: None | str = ...,
    race: bool = ...,
    resources: list[str] = ...,
    srcs: list[str] = ...,
) -> None

A go_exported_library() rule builds a C library from the supplied set of Go source files and dependencies. This is done via -buildmode flag and "//export" annotations in the code.

Parameters​

  • name: name of the target
  • default_target_platform: specifies the default target platform, used when no platforms are specified on the command line
  • target_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • exec_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with an execution platform
  • visibility: a list of visibility patterns restricting what targets can depend on this one
  • within_view: a list of visibility patterns restricting what this target can depend on
  • metadata: a key-value map of metadata associated with this target
  • tests: a list of targets that provide tests for this one
  • modifiers: an array of modifiers associated with this target
  • _build_info: Build info that is passed along here will be late-stamped into a fb_build_info section on the output binary
  • asan: If true, enable ASAN.
  • assembler_flags: The set of additional assembler flags to pass to go tool asm.
  • build_mode: Determines the build mode (equivalent of -buildmode). Can be one of the following values: c_archive, c_shared. This argument is valid only if at there is at least one cgo_library declared in deps. In addition you should make sure that -sharedflag is added tocompiler_flagsand go version undergo.gorootis compiled with that flag present in:gcflags, ldflagsandasmflags``
  • build_tags: Build tags to apply to this target and its dependencies.
  • cgo_enabled: Analog of CGO_ENABLED env-var, applies to this target and its dependencies. If None go_toolchain.default_cgo_enabled value will be applied.
  • compiler_flags: The set of additional compiler flags to pass to go tool compile.
  • cxx_compiler_flags: GCC/Clang flags to use when compiling any of the above C/C++ sources (which require compilation).
  • cxx_preprocessor_flags: GCC/Clang flags to use when preprocessing any of the above C/C++ sources (which require preprocessing).
  • deps: The set of dependencies of this rule. Currently, this only supports go_library rules.
  • external_linker_flags: Extra external linker flags passed to go link via -extld argument.
  • generate_exported_header: Generate header file with declaration for functions exported with //export The header name for target cell//foo/bar:lib will be foo/bar/lib.h
  • header_namespace: A path prefix when including headers of this target. Defaults to the path from the root of the repository to the directory where this target is defined. Can contain forward slashes (/), but cannot start with one. 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 name can contain forward slashes (/). The headers can be included with #include "$HEADER_NAMESPACE/$HEADER_NAME" or #include <$HEADER_NAMESPACE/$HEADER_NAME> , where $HEADER_NAMESPACE is the value of the target's header_namespace attribute, and $HEADER_NAME is the header name if specified, and the filename of the header file otherwise. See header_namespace for more information.
  • link_mode: Determines the link mode (equivalent of -mode). Can be one of the following values: internal, external. If no value is provided, the mode is set automatically depending on the other args.
  • link_style: Determines whether to build and link this rule's dependencies statically or dynamically. Can be one of the following values: static, static_pic or shared. This argument is relevant only if the cgo extension is enabled. Otherwise, Buck ignores this argument.
  • linker_flags: Extra linker flags passed to go link
  • package_name: Sets the full name of the package being compiled. This defaults to the path from the buck root. (e.g. given a ./.buckconfig, a rule in ./a/b/BUCK defaults to package "a/b")
  • package_root: Sets Go package direactory (relative to BUCK file). By default (or if None passes) package_root is being detected automatically. Empty string of Go package is on the same level as BUCK file otherwise the subdirectory name. Example for srcs = ["foo/bar.go"], package_root = "foo"
  • race: If true, enable data race detection.
  • resources: Static files to be symlinked into the working directory of the test. You can access these in your by opening the files as relative paths, e.g. ioutil.ReadFile("testdata/input").
  • srcs: The set of source files to be compiled by this rule. .go files will be compiled with the Go compiler, .s files will be compiled with the assembler, and everything else is assumed to be files that may be #included by the assembler.

Details​

Examples:

For more examples, check out our integration tests.


go_exported_library(
    name = "shared",
    srcs = ["main.go"],
    build_mode = "c_shared",
    compiler_flags = ["-shared"],
    deps = [":example"],
)

go_library(
    name = "example",
    package_name = "cgo",
    srcs = [
        "export-to-c.go",  # file with //export annotations
    ],
    compiler_flags = [],
    headers = [],
)

cxx_genrule(
    name = "cgo_exported_headers",
    out = "includes",
    cmd = (
        "mkdir -p $OUT && " +
        "cat `dirname $(location :shared)`/includes/*.h > $OUT/_cgo_export.h"
    ),
)

prebuilt_cxx_library(
    name = "cxx_so_with_header",
    header_dirs = [":cgo_exported_headers"],
    shared_lib = ":shared",
)

go_library​

def go_library(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    _asan: bool = ...,
    _build_tags: list[str] = ...,
    _cgo_enabled: None | bool = ...,
    _coverage_mode: None | str = ...,
    _cxx_toolchain: str = ...,
    _exec_os_type: str = ...,
    _go_stdlib: str = ...,
    _go_toolchain: str = ...,
    _race: bool = ...,
    assembler_flags: list[str] = ...,
    compiler_flags: list[str] = ...,
    contacts: list[str] = ...,
    cxx_compiler_flags: list[str] = ...,
    cxx_preprocessor_flags: list[str] = ...,
    default_host_platform: None | str = ...,
    deps: list[str] = ...,
    embedcfg: None | str = ...,
    external_linker_flags: list[str] = ...,
    generate_exported_header: bool = ...,
    header_namespace: None | str = ...,
    headers: list[str] | dict[str, str] = ...,
    labels: list[str] = ...,
    licenses: list[str] = ...,
    link_style: None | str = ...,
    override_cgo_enabled: None | bool = ...,
    package_name: None | str = ...,
    package_root: None | str = ...,
    srcs: list[str] = ...,
) -> None

A go_library() rule builds a native library from the supplied set of Go source files and dependencies.

Parameters​

  • name: name of the target
  • default_target_platform: specifies the default target platform, used when no platforms are specified on the command line
  • target_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • exec_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with an execution platform
  • visibility: a list of visibility patterns restricting what targets can depend on this one
  • within_view: a list of visibility patterns restricting what this target can depend on
  • metadata: a key-value map of metadata associated with this target
  • tests: a list of targets that provide tests for this one
  • modifiers: an array of modifiers associated with this target
  • assembler_flags: The set of additional assembler flags to pass to go tool asm.
  • compiler_flags: The set of additional compiler flags to pass to go tool compile.
  • cxx_compiler_flags: GCC/Clang flags to use when compiling any of the above C/C++ sources (which require compilation).
  • cxx_preprocessor_flags: GCC/Clang flags to use when preprocessing any of the above C/C++ sources (which require preprocessing).
  • deps: The set of dependencies of this rule. Currently, this only supports go_library rules.
  • external_linker_flags: Extra external linker flags passed to go link via -extld argument.
  • generate_exported_header: Generate header file with declaration for functions exported with //export The header name for target cell//foo/bar:lib will be foo/bar/lib.h
  • header_namespace: A path prefix when including headers of this target. Defaults to the path from the root of the repository to the directory where this target is defined. Can contain forward slashes (/), but cannot start with one. 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 name can contain forward slashes (/). The headers can be included with #include "$HEADER_NAMESPACE/$HEADER_NAME" or #include <$HEADER_NAMESPACE/$HEADER_NAME> , where $HEADER_NAMESPACE is the value of the target's header_namespace attribute, and $HEADER_NAME is the header name if specified, and the filename of the header file otherwise. See header_namespace for more information.
  • link_style: Determines whether to build and link this rule's dependencies statically or dynamically. Can be one of the following values: static, static_pic or shared. This argument is relevant only if the cgo extension is enabled. Otherwise, Buck ignores this argument.
  • override_cgo_enabled: Per-target analog of CGO_ENABLED env-var, overrides its value for the target, but not for its dependencies.
  • package_name: Sets the full name of the package being compiled. This defaults to the path from the buck root. (e.g. given a ./.buckconfig, a rule in ./a/b/BUCK defaults to package "a/b")
  • package_root: Sets Go package direactory (relative to BUCK file). By default (or if None passes) package_root is being detected automatically. Empty string of Go package is on the same level as BUCK file otherwise the subdirectory name. Example for srcs = ["foo/bar.go"], package_root = "foo"
  • srcs: The set of source files to be compiled by this rule. .go files will be compiled with the Go compiler, .s files will be compiled with the assembler, and everything else is assumed to be files that may be #included by the assembler.

Details​

Examples:

For more examples, check out our integration tests.


go_library(
  name='greeting',
  srcs=[
    'greeting.go',
  ],
  deps=[
    ':join',
  ],
)

go_stdlib​

def go_stdlib(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    _asan: bool = ...,
    _build_tags: list[str] = ...,
    _cgo_enabled: None | bool = ...,
    _cxx_toolchain: str = ...,
    _exec_os_type: str = ...,
    _go_toolchain: str = ...,
    _race: bool = ...,
) -> None

Parameters​

  • name: name of the target
  • default_target_platform: specifies the default target platform, used when no platforms are specified on the command line
  • target_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • exec_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with an execution platform
  • visibility: a list of visibility patterns restricting what targets can depend on this one
  • within_view: a list of visibility patterns restricting what this target can depend on
  • metadata: a key-value map of metadata associated with this target
  • tests: a list of targets that provide tests for this one
  • modifiers: an array of modifiers associated with this target

go_test​

def go_test(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    _asan: bool = ...,
    _build_info: dict[str, typing.Any] = ...,
    _build_tags: list[str] = ...,
    _coverage_mode: None | str = ...,
    _cxx_toolchain: str = ...,
    _exec_os_type: str = ...,
    _go_stdlib: str = ...,
    _go_toolchain: str = ...,
    _inject_test_env: str = ...,
    _race: bool = ...,
    _remote_test_execution_toolchain: str = ...,
    _test_toolchain: str = ...,
    _testmaingen: str = ...,
    asan: bool = ...,
    assembler_flags: list[str] = ...,
    build_tags: list[str] = ...,
    cgo_enabled: None | bool = ...,
    compiler_flags: list[str] = ...,
    contacts: list[str] = ...,
    coverage_mode: None | str = ...,
    cxx_compiler_flags: list[str] = ...,
    cxx_preprocessor_flags: list[str] = ...,
    default_host_platform: None | str = ...,
    deps: list[str] = ...,
    embedcfg: None | str = ...,
    env: dict[str, str] = ...,
    external_linker_flags: list[str] = ...,
    header_namespace: None | str = ...,
    headers: list[str] | dict[str, str] = ...,
    labels: list[str] = ...,
    library: None | str = ...,
    licenses: list[str] = ...,
    link_mode: None | str = ...,
    link_style: None | str = ...,
    linker_flags: list[str] = ...,
    package_name: None | str = ...,
    package_root: None | str = ...,
    platform: None | str = ...,
    race: bool = ...,
    remote_execution: None | str | dict[str, None | bool | int | str | list[dict[str, str]] | dict[str, str]] = ...,
    remote_execution_action_key_providers: None | str = ...,
    resources: list[str] = ...,
    run_test_separately: bool = ...,
    runner: None | str = ...,
    specs: None | str = ...,
    srcs: list[str] = ...,
    test_rule_timeout_ms: None | int = ...,
) -> None

A go_test() rule builds a native binary from the specified Go source and resource files—and a generated main file. It's similar to the go test command.

Parameters​

  • name: name of the target

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

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

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

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

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

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

  • metadata: a key-value map of metadata associated with this target

  • tests: a list of targets that provide tests for this one

  • modifiers: an array of modifiers associated with this target

  • _build_info: Build info that is passed along here will be late-stamped into a fb_build_info section on the output binary

  • asan: If true, enable ASAN.

  • assembler_flags: The set of additional assembler flags to pass to go tool asm.

  • build_tags: Build tags to apply to this target and its dependencies.

  • cgo_enabled: Analog of CGO_ENABLED env-var, applies to this target and its dependencies. If None go_toolchain.default_cgo_enabled value will be applied.

  • compiler_flags: The set of additional compiler flags to pass to go tool compile.

  • cxx_compiler_flags: GCC/Clang flags to use when compiling any of the above C/C++ sources (which require compilation).

  • cxx_preprocessor_flags: GCC/Clang flags to use when preprocessing any of the above C/C++ sources (which require preprocessing).

  • deps: The set of dependencies of this rule. Currently, this only supports go_library rules.

  • env: A map of environment variables and values to set when running the test.

  • external_linker_flags: Extra external linker flags passed to go link via -extld argument.

  • 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. 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 name can contain forward slashes (/). The headers can be included with #include "$HEADER_NAMESPACE/$HEADER_NAME" or #include <$HEADER_NAMESPACE/$HEADER_NAME> , where $HEADER_NAMESPACE is the value of the target's header_namespace attribute, and $HEADER_NAME is the header name if specified, and the filename of the header file otherwise. See header_namespace for more information.

  • labels: A list of labels to be applied to these tests. These labels are arbitrary text strings and have no meaning within buck itself. They can, however, have meaning for you as a test author (e.g., smoke or fast). A label can be used to filter or include a specific test rule when executing buck test

  • library: Specify the library that this internal test is testing. This will copy the srcs, package_name and deps from the target specified so you don't have to duplicate them.

  • link_mode: Determines the link mode (equivalent of -mode). Can be one of the following values: internal, external. If no value is provided, the mode is set automatically depending on the other args.

  • link_style: Determines whether to build and link this rule's dependencies statically or dynamically. Can be one of the following values: static, static_pic or shared. This argument is relevant only if the cgo extension is enabled. Otherwise, Buck ignores this argument.

  • linker_flags: Extra linker flags passed to go link

  • package_name: Sets the full name of the test package being compiled. This defaults to the path from the buck root with "_test" appended. (e.g. given a ./.buckconfig, a rule in ./a/b/BUCK defaults to package "a/b_test")

    Note: if you want to test packages internally (i.e. same package name), use the library parameter instead of setting package_name to include the tested source files.

  • package_root: Sets Go package direactory (relative to BUCK file). By default (or if None passes) package_root is being detected automatically. Empty string of Go package is on the same level as BUCK file otherwise the subdirectory name. Example for srcs = ["foo/bar.go"], package_root = "foo"

  • race: If true, enable data race detection.

  • srcs: The set of source files to be compiled by this rule. .go files will be compiled with the Go compiler, .s files will be compiled with the assembler, and everything else is assumed to be files that may be #included by the assembler.

  • test_rule_timeout_ms: If set specifies the maximum amount of time (in milliseconds) in which all of the tests in this rule should complete. This overrides the default rule_timeout if any has been specified in .buckconfig .

Details​

If your test requires static files you should specify these in the resources argument. If you do not specify these files, they won't be available when your test runs.

Examples:

For more examples, check out our integration tests.


go_library(
  name='greeting',
  srcs=[
    'greeting.go',
  ],
  deps=[
    ':join',
  ],
)

go_test(
  name='greeting-test',
  srcs=[
    'greeting_ext_test.go',
  ],
  deps=[
    ':greeting'
  ],
)

go_test(
  name='greeting-internal-test',
  package_name='greeting',
  srcs=[
    'greeting.go',
    'greeting_test.go',
  ],
  deps=[
    ':join',
  ],
)

# Or

go_test(
  name='greeting-better-internal-test',
  srcs=['greeting_test.go'],
  library=':greeting',
)


groovy_library​

def groovy_library(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, 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] = ...,
    exported_deps: list[str] = ...,
    exported_provided_deps: list[str] = ...,
    extra_arguments: list[str] = ...,
    extra_groovyc_arguments: list[str] = ...,
    java_version: None | str = ...,
    javac: None | str = ...,
    labels: list[str] = ...,
    licenses: list[str] = ...,
    manifest_file: None | str = ...,
    maven_coords: None | str = ...,
    never_mark_as_unused_dependency: None | bool = ...,
    on_unused_dependencies: None | str = ...,
    plugins: list[str | (str, list[str])] = ...,
    proguard_config: None | str = ...,
    provided_deps: list[str] = ...,
    remove_classes: list[str] = ...,
    required_for_source_only_abi: bool = ...,
    resources: list[str] = ...,
    resources_root: None | str = ...,
    runtime_deps: list[str] = ...,
    source: None | str = ...,
    source_abi_verification_mode: None | str = ...,
    source_only_abi_deps: list[str] = ...,
    srcs: list[str] = ...,
    target: None | str = ...,
) -> None

A groovy_library() rule is used to define a set of Groovy files that can be compiled together. It can also be used to cross compile a set of Groovy and Java files. The main output of a groovy_library() rule is a single JAR file containing all of the compiled class files and resources.

Parameters​

  • name: name of the target

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

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

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

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

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

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

  • metadata: a key-value map of metadata associated with this target

  • tests: a list of targets that provide tests for this one

  • modifiers: an array of modifiers associated with this target

  • deps: Rules (usually other groovy_library or java_library() rules) that are used to generate the classpath required to compile this groovy_library.

    This is the same as in java_library().

  • exported_deps: Other groovy_library and java_library() rules that depend on this rule will also include its exported_deps in their classpaths.

    This is the same as in java_library().

  • extra_arguments: Only used during cross compilation.

    This is the same as in java_library().

  • extra_groovyc_arguments: List of additional arguments to pass into the Groovy compiler.

  • java_version: Only used during cross compilation.

    This is the same as in java_library().

  • javac: Specifies the Java compiler program to use for this rule. The value is a source path or an execution dep (e.g., //foo/bar:bar). Overrides the value in "javac" in the "tools" section of .buckconfig.

  • provided_deps: This is the same as in java_library().

  • resources: This is the same as in java_library().

  • source: Only used during cross compilation.

    This is the same as in java_library().

  • srcs: The set of files to compile for this rule. Usually these will all end in .groovy, but if any of the files end in .java, cross compilation using the jdk found in JAVA_HOME will occur.

  • target: Only used during cross compilation.

    This is the same as in java_library().

Details​

Examples:


# A rule that compiles a single .groovy file.
groovy_library(
  name = 'example',
  srcs = ['MySourceFile.groovy'],
)


# A rule that compiles all of the .groovy files under the directory in
# which the rule is defined using glob()
groovy_library(
  name = 'groovy-only',
  srcs = glob(['**/*.groovy']),
)


# A rule that cross compiles all of the .groovy and .java files under
# the directory in which the rule is defined, failing if compiling the
# java files generates any compiler warnings
groovy_library(
  name = 'cross-compilation',
  srcs = glob(['**/*.groovy', '**/*.java']),
  java_version = 8,
  extra_arguments = [
    '-Werror',
  ],
)

groovy_test​

def groovy_test(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    annotation_processor_deps: list[str] = ...,
    annotation_processor_params: list[str] = ...,
    annotation_processors: list[str] = ...,
    contacts: list[str] = ...,
    cxx_library_whitelist: list[str] = ...,
    default_cxx_platform: None | str = ...,
    default_host_platform: None | str = ...,
    deps: list[str] = ...,
    deps_query: None | str = ...,
    env: dict[str, str] = ...,
    exported_deps: list[str] = ...,
    exported_provided_deps: list[str] = ...,
    extra_arguments: list[str] = ...,
    extra_groovyc_arguments: list[str] = ...,
    fork_mode: str = ...,
    java_version: None | str = ...,
    javac: None | str = ...,
    labels: list[str] = ...,
    licenses: list[str] = ...,
    manifest_file: None | str = ...,
    maven_coords: None | str = ...,
    never_mark_as_unused_dependency: None | bool = ...,
    on_unused_dependencies: None | str = ...,
    plugins: list[str | (str, list[str])] = ...,
    proguard_config: None | str = ...,
    provided_deps: list[str] = ...,
    remove_classes: list[str] = ...,
    required_for_source_only_abi: bool = ...,
    resources: list[str] = ...,
    resources_root: None | str = ...,
    run_test_separately: bool = ...,
    runtime_deps: list[str] = ...,
    source: None | str = ...,
    source_abi_verification_mode: None | str = ...,
    source_only_abi_deps: list[str] = ...,
    srcs: list[str] = ...,
    std_err_log_level: None | int | str = ...,
    std_out_log_level: None | int | str = ...,
    target: None | str = ...,
    test_case_timeout_ms: None | int = ...,
    test_rule_timeout_ms: None | int = ...,
    test_type: None | str = ...,
    use_cxx_libraries: None | bool = ...,
    use_dependency_order_classpath: None | bool = ...,
    vm_args: list[str] = ...,
) -> None

Parameters​

  • name: name of the target
  • default_target_platform: specifies the default target platform, used when no platforms are specified on the command line
  • target_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • exec_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with an execution platform
  • visibility: a list of visibility patterns restricting what targets can depend on this one
  • within_view: a list of visibility patterns restricting what this target can depend on
  • metadata: a key-value map of metadata associated with this target
  • tests: a list of targets that provide tests for this one
  • modifiers: an array of modifiers associated with this target
  • javac: Specifies the Java compiler program to use for this rule. The value is a source path or an execution dep (e.g., //foo/bar:bar). Overrides the value in "javac" in the "tools" section of .buckconfig.

gwt_binary​

def gwt_binary(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    _exec_os_type: str = ...,
    _java_toolchain: str = ...,
    contacts: list[str] = ...,
    default_host_platform: None | str = ...,
    deps: list[str] = ...,
    draft_compile: bool = ...,
    experimental_args: list[str] = ...,
    labels: list[str] = ...,
    licenses: list[str] = ...,
    local_workers: int = ...,
    module_deps: list[str] = ...,
    modules: list[str] = ...,
    optimize: int = ...,
    strict: bool = ...,
    style: str = ...,
    vm_args: list[str] = ...,
) -> None

Parameters​

  • name: name of the target
  • default_target_platform: specifies the default target platform, used when no platforms are specified on the command line
  • target_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • exec_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with an execution platform
  • visibility: a list of visibility patterns restricting what targets can depend on this one
  • within_view: a list of visibility patterns restricting what this target can depend on
  • metadata: a key-value map of metadata associated with this target
  • tests: a list of targets that provide tests for this one
  • modifiers: an array of modifiers associated with this target

halide_library​

def halide_library(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    compiler_deps: list[str] = ...,
    compiler_flags: list[str] = ...,
    compiler_invocation_flags: list[str] = ...,
    configs: dict[str, dict[str, str]] = ...,
    contacts: list[str] = ...,
    cxx_runtime_type: None | str = ...,
    default_host_platform: None | str = ...,
    default_platform: None | str = ...,
    defaults: dict[str, str] = ...,
    deps: list[str] = ...,
    deps_query: None | str = ...,
    devirt_enabled: bool = ...,
    executable_name: None | str = ...,
    fat_lto: bool = ...,
    focused_list_target: None | str = ...,
    frameworks: list[str] = ...,
    function_name: None | str = ...,
    header_namespace: None | str = ...,
    headers: list[str] | dict[str, str] = ...,
    headers_as_raw_headers_mode: None | str = ...,
    include_directories: list[str] = ...,
    labels: list[str] = ...,
    lang_compiler_flags: dict[str, list[str]] = ...,
    lang_platform_compiler_flags: dict[str, list[(str, list[str])]] = ...,
    lang_platform_preprocessor_flags: dict[str, list[(str, list[str])]] = ...,
    lang_preprocessor_flags: dict[str, list[str]] = ...,
    libraries: list[str] = ...,
    licenses: list[str] = ...,
    link_deps_query_whole: bool = ...,
    link_group: None | str = ...,
    link_group_map: None | str | list[(str, list[(None | str | list[None | str], str, None | str | list[str], None | str)], None | dict[str, typing.Any])] = ...,
    link_style: None | str = ...,
    linker_extra_outputs: list[str] = ...,
    linker_flags: list[str] = ...,
    platform_compiler_flags: list[(str, list[str])] = ...,
    platform_deps: list[(str, list[str])] = ...,
    platform_headers: list[(str, list[str] | dict[str, str])] = ...,
    platform_linker_flags: list[(str, list[str])] = ...,
    platform_preprocessor_flags: list[(str, list[str])] = ...,
    platform_srcs: list[(str, list[str | (str, list[str])])] = ...,
    post_linker_flags: list[str] = ...,
    post_platform_linker_flags: list[(str, list[str])] = ...,
    precompiled_header: None | str = ...,
    prefer_stripped_objects: bool = ...,
    prefix_header: None | str = ...,
    preprocessor_flags: list[str] = ...,
    raw_headers: list[str] = ...,
    srcs: list[str | (str, list[str])] = ...,
    supported_platforms_regex: None | str = ...,
    thin_lto: bool = ...,
    version_universe: None | str = ...,
    weak_framework_names: list[str] = ...,
) -> None

A halide_library() rule represents a set of Halide sources, along with the "compiler" code needed to compile them into object format (see the Halide site for information about Halide and about static compilation of Halide pipelines). The object code will be generated for the target architecture.

Parameters​

  • name: name of the target
  • default_target_platform: specifies the default target platform, used when no platforms are specified on the command line
  • target_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • exec_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with an execution platform
  • visibility: a list of visibility patterns restricting what targets can depend on this one
  • within_view: a list of visibility patterns restricting what this target can depend on
  • metadata: a key-value map of metadata associated with this target
  • tests: a list of targets that provide tests for this one
  • modifiers: an array of modifiers associated with this target
  • compiler_deps: The dependencies of the halide compiler itself. Targets that depend on the halide_library rule will not include or link the outputs of these targets.
  • compiler_flags: Flags to use when compiling any of the above sources (which require compilation).
  • deps: The dependencies of the generated halide pipeline code. This is useful if, for example, your pipeline calls an external function using Halide::Func::define_extern.
  • linker_flags: Flags to add to the linker command line whenever the output from this rule is used in a link operation, such as linked into an executable or a shared library.
  • platform_compiler_flags: Platform specific compiler flags. These should be specified as a list of pairs where the first element is an un-anchored regex (in java.util.regex.Pattern syntax) against which the platform name is matched, and the second element is a list of flags to use when compiling the target's sources. See compiler_flags for more information.
  • platform_linker_flags: Platform-specific linker flags. This argument is specified as a list of pairs where the first element in each pair is an un-anchored regex against which the platform name is matched. The regex should use java.util.regex.Pattern syntax. The second element in each pair is a list of linker flags. If the regex matches the platform, these flags are added to the linker command line when the output from this rule is used in a link operation.
  • srcs: The set of halide sources to compile for this rule. The sources will be compiled and linked for the host architecture, and the resulting binary will be run to produce the object code for the Halide pipeline.
  • supported_platforms_regex: If present, an un-anchored regex (in java.util.regex.Pattern syntax) that matches all platforms that this library supports. It will not be built for other platforms.

Details​

Examples:


halide_library(
  # Your library name.
  name = 'brighter',

  # Your pipeline + compiler sources.
  srcs = ['halide/main.cpp'],

  # Any dependencies for your compiler. Note that targets that depend on
  # this rule WILL NOT include or link the output(s) of these targets.
  compiler_deps = [
    # You'll need libHalide to use this rule; in our example, we assume it's
    # located in the 'third-party/halide' directory.
    '//third-party/halide:halide'
  ],

  # Any dependencies for your generated shader. Targets that depend on this
  # rule will include and/or link the output(s) of these targets.
  deps = [
    # ...
  ],
)

haskell_binary​

def haskell_binary(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    _cxx_toolchain: str = ...,
    _haskell_toolchain: str = ...,
    auto_link_groups: bool = ...,
    compiler_flags: list[str] = ...,
    contacts: list[str] = ...,
    default_host_platform: None | str = ...,
    deps: list[str] = ...,
    deps_query: None | str = ...,
    enable_profiling: bool = ...,
    ghci_platform_preload_deps: list[(str, list[str])] = ...,
    ghci_preload_deps: list[str] = ...,
    labels: list[str] = ...,
    licenses: list[str] = ...,
    link_deps_query_whole: bool = ...,
    link_group_deps: list[str] = ...,
    link_group_map: None | str | list[(str, list[(None | str | list[None | str], str, None | str | list[str], None | str)], None | dict[str, typing.Any])] = ...,
    link_group_public_deps_label: None | str = ...,
    link_style: None | str = ...,
    linker_flags: list[str] = ...,
    main: None | str = ...,
    platform: None | str = ...,
    platform_deps: list[(str, list[str])] = ...,
    platform_linker_flags: list[(str, list[str])] = ...,
    srcs: list[str] | dict[str, str] = ...,
    template_deps: list[str] = ...,
) -> None

A haskell_binary() rule represents a groups of Haskell sources and deps which build an executable.

Parameters​

  • name: name of the target
  • default_target_platform: specifies the default target platform, used when no platforms are specified on the command line
  • target_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • exec_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with an execution platform
  • visibility: a list of visibility patterns restricting what targets can depend on this one
  • within_view: a list of visibility patterns restricting what this target can depend on
  • metadata: a key-value map of metadata associated with this target
  • tests: a list of targets that provide tests for this one
  • modifiers: an array of modifiers associated with this target
  • compiler_flags: Flags to pass to the Haskell compiler when compiling this rule's sources.
  • deps: Either haskell_library() or prebuilt_haskell_library() rules from which this rules sources import modules or native linkable rules exporting symbols this rules sources call into.
  • link_group_deps: Additional targets to traverse when building link groups, but which should not be direct dependencies of the main executable.
  • link_group_public_deps_label: Surface nodes with this label as "public" nodes in the main executable when linking with with link groups.
  • link_style: Determines whether to build and link this rule's dependencies statically or dynamically. Can be either static, static_pic or shared.
  • main: The main module serving as the entry point into the binary. If not specified, the compiler default is used.
  • platform_deps: Platform specific dependencies. These should be specified as a list of pairs where the first element is an un-anchored regex (in java.util.regex.Pattern syntax) against which the platform name is matched, and the second element is a list of dependencies (same format as deps) that are exported if the platform matches the regex. See deps for more information.
  • srcs: A list of Haskell sources to be built by this rule. The dictionary option is deprecated.

Details​

Examples:


haskell_binary(
  name = 'foo',
  srcs = [
    'Foo.hs',
  ],
)

haskell_ghci​

def haskell_ghci(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    _cxx_toolchain: str = ...,
    _haskell_toolchain: str = ...,
    compiler_flags: list[str] = ...,
    contacts: list[str] = ...,
    default_host_platform: None | str = ...,
    deps: list[str] = ...,
    deps_query: None | str = ...,
    enable_profiling: bool = ...,
    extra_script_templates: list[str] = ...,
    ghci_bin_dep: None | str = ...,
    ghci_init: None | str = ...,
    labels: list[str] = ...,
    licenses: list[str] = ...,
    linker_flags: list[str] = ...,
    platform: None | str = ...,
    platform_deps: list[(str, list[str])] = ...,
    platform_preload_deps: list[(str, list[str])] = ...,
    preload_deps: list[str] = ...,
    srcs: list[str] | dict[str, str] = ...,
    template_deps: list[str] = ...,
) -> None

Parameters​

  • name: name of the target
  • default_target_platform: specifies the default target platform, used when no platforms are specified on the command line
  • target_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • exec_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with an execution platform
  • visibility: a list of visibility patterns restricting what targets can depend on this one
  • within_view: a list of visibility patterns restricting what this target can depend on
  • metadata: a key-value map of metadata associated with this target
  • tests: a list of targets that provide tests for this one
  • modifiers: an array of modifiers associated with this target

haskell_haddock​

def haskell_haddock(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    _cxx_toolchain: str = ...,
    _haskell_toolchain: str = ...,
    contacts: list[str] = ...,
    default_host_platform: None | str = ...,
    deps: list[str] = ...,
    deps_query: None | str = ...,
    haddock_flags: list[str] = ...,
    labels: list[str] = ...,
    licenses: list[str] = ...,
    platform: None | str = ...,
    platform_deps: list[(str, list[str])] = ...,
) -> None

Parameters​

  • name: name of the target
  • default_target_platform: specifies the default target platform, used when no platforms are specified on the command line
  • target_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • exec_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with an execution platform
  • visibility: a list of visibility patterns restricting what targets can depend on this one
  • within_view: a list of visibility patterns restricting what this target can depend on
  • metadata: a key-value map of metadata associated with this target
  • tests: a list of targets that provide tests for this one
  • modifiers: an array of modifiers associated with this target

haskell_ide​

def haskell_ide(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    _haskell_toolchain: str = ...,
    compiler_flags: list[str] = ...,
    contacts: list[str] = ...,
    default_host_platform: None | str = ...,
    deps: list[str] = ...,
    deps_query: None | str = ...,
    extra_script_templates: list[str] = ...,
    include_projects: list[str] = ...,
    labels: list[str] = ...,
    licenses: list[str] = ...,
    link_style: str,
    linker_flags: list[str] = ...,
    platform: None | str = ...,
    platform_deps: list[(str, list[str])] = ...,
    srcs: list[str] | dict[str, str] = ...,
) -> None

Parameters​

  • name: name of the target
  • default_target_platform: specifies the default target platform, used when no platforms are specified on the command line
  • target_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • exec_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with an execution platform
  • visibility: a list of visibility patterns restricting what targets can depend on this one
  • within_view: a list of visibility patterns restricting what this target can depend on
  • metadata: a key-value map of metadata associated with this target
  • tests: a list of targets that provide tests for this one
  • modifiers: an array of modifiers associated with this target

haskell_library​

def haskell_library(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    _cxx_toolchain: str = ...,
    _haskell_toolchain: str = ...,
    compiler_flags: list[str] = ...,
    contacts: list[str] = ...,
    default_host_platform: None | str = ...,
    deps: list[str] = ...,
    enable_profiling: bool = ...,
    ghci_platform_preload_deps: list[(str, list[str])] = ...,
    ghci_preload_deps: list[str] = ...,
    haddock_flags: list[str] = ...,
    labels: list[str] = ...,
    licenses: list[str] = ...,
    link_whole: bool = ...,
    linker_flags: list[str] = ...,
    platform: None | str = ...,
    platform_deps: list[(str, list[str])] = ...,
    platform_linker_flags: list[(str, list[str])] = ...,
    preferred_linkage: str = ...,
    srcs: list[str] | dict[str, str] = ...,
    template_deps: list[str] = ...,
) -> None

A haskell_library() rule is used to identity a group of Haskell sources.

Parameters​

  • name: name of the target
  • default_target_platform: specifies the default target platform, used when no platforms are specified on the command line
  • target_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • exec_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with an execution platform
  • visibility: a list of visibility patterns restricting what targets can depend on this one
  • within_view: a list of visibility patterns restricting what this target can depend on
  • metadata: a key-value map of metadata associated with this target
  • tests: a list of targets that provide tests for this one
  • modifiers: an array of modifiers associated with this target
  • compiler_flags: Flags to pass to the Haskell compiler when compiling this rule's sources.
  • deps: Either haskell_library() or prebuilt_haskell_library() rules from which this rules sources import modules or native linkable rules exporting symbols this rules sources call into.
  • platform_deps: Platform specific dependencies. These should be specified as a list of pairs where the first element is an un-anchored regex (in java.util.regex.Pattern syntax) against which the platform name is matched, and the second element is a list of dependencies (same format as deps) that are exported if the platform matches the regex. See deps for more information.
  • srcs: A list of Haskell sources to be built by this rule. The dictionary option is deprecated.

Details​

Examples:


haskell_library(
  name = 'fileutil',
  srcs = [
    'FileUtil.hs',
  ],
)

haskell_prebuilt_library​

def haskell_prebuilt_library(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    contacts: list[str] = ...,
    cxx_header_dirs: list[str] = ...,
    db: str,
    default_host_platform: None | str = ...,
    deps: list[str] = ...,
    enable_profiling: bool = ...,
    exported_compiler_flags: list[str] = ...,
    exported_linker_flags: list[str] = ...,
    exported_post_linker_flags: list[str] = ...,
    id: str = ...,
    import_dirs: list[str] = ...,
    labels: list[str] = ...,
    licenses: list[str] = ...,
    pic_profiled_static_libs: list[str] = ...,
    pic_static_libs: list[str] = ...,
    profiled_static_libs: list[str] = ...,
    shared_libs: dict[str, str] = ...,
    static_libs: list[str] = ...,
    version: str = ...,
) -> None

A prebuilt_haskell_library() rule is used to identify Haskell prebuilt libraries and their associated interface files.

Parameters​

  • name: name of the target
  • default_target_platform: specifies the default target platform, used when no platforms are specified on the command line
  • target_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • exec_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with an execution platform
  • visibility: a list of visibility patterns restricting what targets can depend on this one
  • within_view: a list of visibility patterns restricting what this target can depend on
  • metadata: a key-value map of metadata associated with this target
  • tests: a list of targets that provide tests for this one
  • modifiers: an array of modifiers associated with this target
  • deps: Other prebuilt_haskell_library() rules from which this library imports modules.
  • exported_compiler_flags: Compiler flags used by dependent rules when compiling with this library.
  • exported_linker_flags: Linker flags used by dependent rules when linking with this library.
  • shared_libs: A map of shared library names to shared library paths to use when building a dynamically linked top-level target.
  • static_libs: The libraries to use when building a statically linked top-level target.

Details​

Examples:


prebuilt_haskell_library(
  name = 'file',
  static_interfaces = [
    'interfaces',
  ],
  shared_interfaces = [
    'interfaces_dyn',
  ],
  static_libs = [
    'libFileUtil.a',
  ],
  shared_libs = {
    'libFileUtil.so': 'libFileUtil.so',
  },
)

http_archive​

def http_archive(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    contacts: list[str] = ...,
    default_host_platform: None | str = ...,
    excludes: list[str] = ...,
    exec_deps: str = ...,
    labels: list[str] = ...,
    licenses: list[str] = ...,
    out: None | str = ...,
    sha1: None | str = ...,
    sha256: None | str = ...,
    strip_prefix: None | str = ...,
    sub_targets: list[str] = ...,
    type: None | str = ...,
    urls: list[str] = ...,
    vpnless_urls: list[str] = ...,
) -> None

An http_archive() rule is used to download and extract archives from the Internet to be used as dependencies for other rules. These rules are downloaded by running fetch, or can be downloaded as part of build by setting .buckconfig

Parameters​

  • name: name of the target

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

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

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

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

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

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

  • metadata: a key-value map of metadata associated with this target

  • tests: a list of targets that provide tests for this one

  • modifiers: an array of modifiers associated with this target

  • excludes: An optional list of regex patterns. All file paths in the extracted archive which match any of the given patterns will be omitted.

  • exec_deps: When using http_archive as an anon target, the rule invoking the anon target needs to mirror this attribute into its own attributes, and forward the provider into the anon target invocation.

    When using http_archive normally not as an anon target, the default value is always fine.

  • out: An optional name to call the directory that the downloaded artifact is extracted into. Buck will generate a default name if one is not provided that uses the name of the rule.

  • sha256: The SHA-256 hash of the downloaded artifact. Buck verifies this is correct and fails the fetch command if it doesn't match in order to guarantee repeatable builds.

  • strip_prefix: If set, files under this path will be extracted to the root of the output directory. Siblings or cousins to this prefix will not be extracted at all.

    For example, if a tarball has the layout:

    • foo/bar/bar-0.1.2/data.dat
    • foo/baz/baz-0.2.3
    • foo_prime/bar-0.1.2

    Only data.dat will be extracted, and it will be extracted into the output directory specified in out.

  • sub_targets: A list of filepaths within the archive to be made accessible as sub-targets. For example if we have an http_archive with name = "archive" and sub_targets = ["src/lib.rs"], then other targets would be able to refer to that file as ":archive[src/lib.rs]".

  • type: Normally, archive type is determined by the file's extension. If type is set, then autodetection is overridden, and the specified type is used instead.

    Supported values are: zip, tar, tar.gz, tar.bz2, tar.xz, and tar.zst.

  • urls: A list of urls to attempt to download from. They are tried in order, and subsequent ones are only tried if the download fails. If validation fails, a new URL is not used. Supported protocols are "http", "https", and "mvn".

  • vpnless_urls: Additional URLs from which this resource can be downloaded when off VPN. Meta-internal only.

Details​

Examples:

Using http_archive(), third party packages can be downloaded from an https URL and used in other library types.


http_archive(
  name = 'thrift-archive',
  urls = [
    'https://internal-mirror.example.com/bin/thrift-compiler-0.1.tar.gz.badextension',
  ],
  sha256 = '7baa80df284117e5b945b19b98d367a85ea7b7801bd358ff657946c3bd1b6596',
  type='tar.gz',
  strip_prefix='thrift-compiler-0.1'
)

genrule(
  name = 'thrift-compiler-bin',
  out = 'thrift',
  cmd = 'cp $(location :thrift-archive)/bin/thrift $OUT',
  executable = True,
)

genrule(
  name="my-thrift-lib-cpp2",
  cmd="$(exe :thrift-compiler-bin) --gen cpp2 -o $OUT $(location //:thrift-file)",
  out="gen-cpp2",
)

http_file​

def http_file(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    contacts: list[str] = ...,
    default_host_platform: None | str = ...,
    executable: None | bool = ...,
    labels: list[str] = ...,
    licenses: list[str] = ...,
    out: None | str = ...,
    sha1: None | str = ...,
    sha256: None | str = ...,
    urls: list[str] = ...,
    vpnless_urls: list[str] = ...,
) -> None

An http_file() rule is used to download files from the Internet to be used as dependencies for other rules. This rule only downloads single files, and can optionally make them executable (see http_file()executable) These rules are downloaded by running fetch, or can be downloaded as part of build by setting .buckconfig

Parameters​

  • name: name of the target
  • default_target_platform: specifies the default target platform, used when no platforms are specified on the command line
  • target_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • exec_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with an execution platform
  • visibility: a list of visibility patterns restricting what targets can depend on this one
  • within_view: a list of visibility patterns restricting what this target can depend on
  • metadata: a key-value map of metadata associated with this target
  • tests: a list of targets that provide tests for this one
  • modifiers: an array of modifiers associated with this target
  • executable: Whether or not the file should be made executable after downloading. If true, this can also be used via run and the $(exe ) string parameter macros
  • out: An optional name to call the downloaded artifact. Buck will generate a default name if one is not provided that uses the name of the rule.
  • sha256: The SHA-256 hash of the downloaded artifact. Buck verifies this is correct and fails the fetch command if it doesn't match in order to guarantee repeatable builds.
  • urls: A list of urls to attempt to download from. They are tried in order, and subsequent ones are only tried if the download fails. If validation fails, a new URL is not used. Supported protocols are "http", "https", and "mvn".
  • vpnless_urls: Additional URLs from which this resource can be downloaded when off VPN. Meta-internal only.

Details​

Examples:

Using http_file(), third party packages can be downloaded from an https URL and used in java libraries.


http_file(
  name = 'guava-23-bin',
  urls = [
    'http://search.maven.org/remotecontent?filepath=com/google/guava/guava/23.0/guava-23.0.jar',
  ],
  sha256 = '7baa80df284117e5b945b19b98d367a85ea7b7801bd358ff657946c3bd1b6596',
)
http_file(
  name = 'guava-23-sources',
  urls = [
    'http://search.maven.org/remotecontent?filepath=com/google/guava/guava/23.0/guava-23.0-sources.jar',
  ],
  sha256 = '37fe8ba804fb3898c3c8f0cbac319cc9daa58400e5f0226a380ac94fb2c3ca14',
)

prebuilt_java_library(
  name = 'guava-23',
  binary_jar = ':guava-23-bin',
  source_jar = ':guava-23-source',
)

Tooling can also be fetched with http_file() and used by a genrule().


genrule(
  name="my-thrift-lib-cpp2",
  cmd="$(exe :thrift-compiler-bin) --gen cpp2 -o $OUT $(location //:thrift-file)",
  out="gen-cpp2",
)

http_file(
  name = 'thrift-compiler-bin',
  url = 'https://internal-mirror.example.com/bin/thrift-compiler',
  sha256 = 'c24932ccabb66fffb2d7122298f7f1f91e0b1f14e05168e3036333f84bdf58dc',
  executable = True,
)

Here's an example of a http_file() using a mvn URI which uses a Maven classifier.


http_file(
  name = 'guava-23-bin',
  urls = [
    'mvn:com.google.guava:guava:jar:23.0',
  ],
  sha256 = '7baa80df284117e5b945b19b98d367a85ea7b7801bd358ff657946c3bd1b6596',
)

jar_genrule​

def jar_genrule(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    _build_only_native_code: bool = ...,
    _genrule_toolchain: str = ...,
    _java_toolchain: str = ...,
    always_print_stderr: bool = ...,
    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 = ...,
    labels: list[str] = ...,
    licenses: list[str] = ...,
    metadata_env_var: None | str = ...,
    metadata_path: None | str = ...,
    need_android_tools: bool = ...,
    no_outputs_cleanup: bool = ...,
    remote: None | bool = ...,
    remote_execution_dependencies: list[dict[str, str]] = ...,
    srcs: list[str] | dict[str, str] = ...,
    type: None | str = ...,
    weight: None | int = ...,
) -> None

Parameters​

  • name: name of the target
  • default_target_platform: specifies the default target platform, used when no platforms are specified on the command line
  • target_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • exec_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with an execution platform
  • visibility: a list of visibility patterns restricting what targets can depend on this one
  • within_view: a list of visibility patterns restricting what this target can depend on
  • metadata: a key-value map of metadata associated with this target
  • tests: a list of targets that provide tests for this one
  • modifiers: an array of modifiers associated with this target

java_annotation_processor​

def java_annotation_processor(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    _build_only_native_code: bool = ...,
    contacts: list[str] = ...,
    default_host_platform: None | str = ...,
    deps: list[str] = ...,
    does_not_affect_abi: bool = ...,
    isolate_class_loader: bool = ...,
    labels: list[str] = ...,
    licenses: list[str] = ...,
    processor_class: str = ...,
    supports_abi_generation_from_source: bool = ...,
) -> None

Parameters​

  • name: name of the target
  • default_target_platform: specifies the default target platform, used when no platforms are specified on the command line
  • target_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • exec_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with an execution platform
  • visibility: a list of visibility patterns restricting what targets can depend on this one
  • within_view: a list of visibility patterns restricting what this target can depend on
  • metadata: a key-value map of metadata associated with this target
  • tests: a list of targets that provide tests for this one
  • modifiers: an array of modifiers associated with this target

java_binary​

def java_binary(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    _build_only_native_code: bool = ...,
    _exec_os_type: str = ...,
    _is_building_android_binary: bool = ...,
    _java_toolchain: str = ...,
    base_dep: None | str = ...,
    blacklist: list[str] = ...,
    concat_deps: bool = ...,
    contacts: list[str] = ...,
    default_cxx_platform: None | str = ...,
    default_host_platform: None | str = ...,
    deps: list[str] = ...,
    do_not_create_inner_jar: bool = ...,
    generate_wrapper: bool = ...,
    incremental_target_prefix: None | str = ...,
    java_args_for_run_info: list[str] = ...,
    java_runtime: None | str = ...,
    java_version: None | str = ...,
    labels: list[str] = ...,
    licenses: list[str] = ...,
    main_class: None | str = ...,
    manifest_file: None | str = ...,
    meta_inf_directory: None | str = ...,
) -> None

A java_binary() rule is used to create a JAR file of the compiled .class files and resources of the java_library() rules on which it depends.

Parameters​

  • name: name of the target

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

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

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

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

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

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

  • metadata: a key-value map of metadata associated with this target

  • tests: a list of targets that provide tests for this one

  • modifiers: an array of modifiers associated with this target

  • base_dep: Rule (normally of type java_library) that should be compiled and used as a base JAR to receive all dependencies through an append operation.

  • blacklist: A list of patterns that identify files to exclude from the final generated JAR file. Example:


    java_binary(
      name = 'example',
      blacklist = [
        # Excludes com.example.A and com.example.Alligator,
        # as well as their inner classes and any non-class files that happen to match
        # the pattern
        'com.example.A',

        # Excludes all files from org/slf4j/**/*.
        'org.slf4j',
      ],
      deps = [
        ':example1',
        ':third-party-stuff',
      ],
    )

  • concat_deps: Use zip concatenation instead of repacking all dependency jars, which is faster

  • deps: Rules (normally of type java_library) that should be compiled and whose .class files and resources should be included in the generated JAR file.

  • java_runtime: Expected java version used at runtime

  • java_version: Expected java version used at compile time

  • main_class: If provided, this will be the value specified as the Main-Class attribute of the META-INF/MANIFEST.MF file in the generated JAR file. Also, when this rule is used as an executable in a genrule(), main_class will indicate the class whose main() method will be invoked to process the command-line arguments. This is consistent with the expected usage of java -jar *<name.jar>* *<args>*.

  • manifest_file: If provided, this manifest will be used when generating the JAR file. If combined with main_class, the specified manifest file will be used but the main_class will override the main class in the manifest.

java_library​

def java_library(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _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 = ...,
    abi_generation_mode: 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] = ...,
    exported_deps: list[str] = ...,
    exported_provided_deps: list[str] = ...,
    extra_arguments: list[str] = ...,
    jar_postprocessor: None | str = ...,
    java_version: None | str = ...,
    javac: None | str = ...,
    labels: list[str] = ...,
    licenses: list[str] = ...,
    manifest_file: None | str = ...,
    maven_coords: None | str = ...,
    never_mark_as_unused_dependency: None | bool = ...,
    on_unused_dependencies: None | str = ...,
    plugins: list[str | (str, list[str])] = ...,
    proguard_config: None | str = ...,
    provided_deps: list[str] = ...,
    remove_classes: list[str] = ...,
    required_for_source_only_abi: bool = ...,
    resources: list[str] = ...,
    resources_root: None | str = ...,
    runtime_deps: list[str] = ...,
    source: None | str = ...,
    source_abi_verification_mode: None | str = ...,
    source_only_abi_deps: list[str] = ...,
    srcs: list[str] = ...,
    target: None | str = ...,
    validation_deps: list[str] = ...,
) -> None

A java_library() rule defines a set of Java files that can be compiled together. The main output of a java_library() rule is a single JAR file containing all of the compiled class files, as well as the static files specified in the resources argument.

Parameters​

  • name: name of the target

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

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

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

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

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

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

  • metadata: a key-value map of metadata associated with this target

  • tests: a list of targets that provide tests for this one

  • modifiers: an array of modifiers associated with this target

  • deps: Rules (usually other java_library rules) that are used to generate the classpath required to compile this java_library.

  • exported_deps: Other rules that depend on this rule will also include its exported_deps in their classpaths. This is useful when the public API of a rule has return types or checked exceptions that are defined in another rule, which would otherwise require callers to add an extra dependency. It's also useful for exposing e.g. a collection of prebuilt_jar rules as a single target for callers to depend on. Targets in exported_deps are implicitly included in the deps of this rule, so they don't need to be repeated there.

  • exported_provided_deps: This is a combination of provided_deps and exported_deps. Rules listed in this parameter will be added to classpath of rules that depend on this rule, but they will not be included in a binary if binary depends on a such target.

  • extra_arguments: List of additional arguments to pass into the Java compiler. These arguments follow the ones specified in .buckconfig.

  • java_version: Equivalent to setting both source and target to the given value. Setting this and source or target (or both!) is an error.

  • javac: Specifies the Java compiler program to use for this rule. The value is a source path or an execution dep (e.g., //foo/bar:bar). Overrides the value in "javac" in the "tools" section of .buckconfig.

  • on_unused_dependencies: Action performed when Buck detects that some dependencies are not used during Java compilation.

    Note that this feature is experimental and does not handle runtime dependencies.

    The valid values are:

    • ignore (default): ignore unused dependencies,

    • warn: emit a warning to the console,

    • fail: fail the compilation.

    This option overrides the default value from .

  • provided_deps: These represent dependencies that are known to be provided at run time, but are required in order for the code to compile. Examples of provided_deps include the JEE servlet APIs. When this rule is included in a , the provided_deps will not be packaged into the output.

  • remove_classes: Specifies a list of Patterns that are used to exclude classes from the JAR. The pattern matching is based on the name of the class. This can be used to exclude a member class or delete a local view of a class that will be replaced during a later stage of the build.

  • required_for_source_only_abi: Indicates that this rule must be present on the classpath during source-only ABI generation of any rule that depends on it. Typically this is done when a rule contains annotations, enums, constants, or interfaces.

    Having rules present on the classpath during source-only ABI generation prevents Buck from completely flattening the build graph, thus reducing the performance win from source-only ABI generation. These rules should be kept small (ideally just containing annotations, constants, enums, and interfaces) and with minimal dependencies of their own.

  • resources: Static files to include with the compiled .class files. These files can be loaded via Class.getResource().

    Note: If resources_root isn't set, Buck uses the .buckconfig property in .buckconfig to determine where resources should be placed within the generated JAR file.

  • source: Specifies the version of Java (as a string) to interpret source files as. Overrides the value in "source_level" in the "java" section of .buckconfig.

  • source_only_abi_deps: These are dependencies that must be present during source-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 .java files to compile for this rule. If any of the files in this list end in .src.zip, then the entries in the ZIP file that end in .java will be included as ordinary inputs to compilation. This is common when using a genrule() to auto-generate some Java source code that needs to be compiled with some hand-written Java code.

  • target: Specifies the version of Java (as a string) for which to generate code. Overrides the value in "target_level" in the "java" section of .buckconfig.

Details​

Examples:


# A rule that compiles a single .java file.
java_library(
  name = 'JsonUtil',
  srcs = ['JsonUtil.java'],
  deps = [
    '//third_party/guava:guava',
    '//third_party/jackson:jackson',
  ],
)

# A rule that compiles all of the .java files under the directory in
# which the rule is defined using glob(). It also excludes an
# individual file that may have additional dependencies, so it is
# compiled by a separate rule.
java_library(
  name = 'messenger',
  srcs = glob(['**/*.java'], excludes = ['MessengerModule.java']),
  deps = [
    '//src/com/facebook/base:base',
    '//third_party/guava:guava',
  ],
)

java_library(
  name = 'MessengerModule',
  srcs = ['MessengerModule.java'],
  deps = [
    '//src/com/facebook/base:base',
    '//src/com/google/inject:inject',
    '//third_party/guava:guava',
    '//third_party/jsr-330:jsr-330',
  ],
)

# A rule that builds a library with both relative and
# fully-qualified deps.
java_library(
  name = 'testutil',
  srcs = glob(['tests/**/*.java'], excludes = 'tests/**/*Test.java'),
  deps = [
    ':lib-fb4a',
    '//java/com/facebook/base:base',
  ],
)

java_plugin​

def java_plugin(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    _build_only_native_code: bool = ...,
    contacts: list[str] = ...,
    default_host_platform: None | str = ...,
    deps: list[str] = ...,
    does_not_affect_abi: bool = ...,
    isolate_class_loader: bool = ...,
    labels: list[str] = ...,
    licenses: list[str] = ...,
    plugin_name: str = ...,
    supports_abi_generation_from_source: bool = ...,
) -> None

Parameters​

  • name: name of the target
  • default_target_platform: specifies the default target platform, used when no platforms are specified on the command line
  • target_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • exec_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with an execution platform
  • visibility: a list of visibility patterns restricting what targets can depend on this one
  • within_view: a list of visibility patterns restricting what this target can depend on
  • metadata: a key-value map of metadata associated with this target
  • tests: a list of targets that provide tests for this one
  • modifiers: an array of modifiers associated with this target

java_test​

def java_test(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    _build_only_native_code: bool = ...,
    _exec_os_type: str = ...,
    _inject_test_env: str = ...,
    _is_building_android_binary: bool = ...,
    _java_test_toolchain: str = ...,
    _java_toolchain: str = ...,
    _remote_test_execution_toolchain: str = ...,
    _test_toolchain: str = ...,
    abi_generation_mode: None | str = ...,
    annotation_processor_deps: list[str] = ...,
    annotation_processor_params: list[str] = ...,
    annotation_processors: list[str] = ...,
    contacts: list[str] = ...,
    cxx_library_whitelist: list[str] = ...,
    default_cxx_platform: None | str = ...,
    default_host_platform: None | str = ...,
    deps: list[str] = ...,
    deps_query: None | str = ...,
    env: dict[str, str] = ...,
    exported_deps: list[str] = ...,
    exported_provided_deps: list[str] = ...,
    extra_arguments: list[str] = ...,
    fork_mode: str = ...,
    jar_postprocessor: None | str = ...,
    java: None | str = ...,
    java_agents: list[str] = ...,
    java_version: None | str = ...,
    javac: None | str = ...,
    labels: list[str] = ...,
    licenses: list[str] = ...,
    manifest_file: None | str = ...,
    maven_coords: None | str = ...,
    never_mark_as_unused_dependency: None | bool = ...,
    on_unused_dependencies: None | str = ...,
    plugins: list[str | (str, list[str])] = ...,
    proguard_config: None | str = ...,
    provided_deps: list[str] = ...,
    remote_execution: None | str | dict[str, None | bool | int | str | list[dict[str, str]] | dict[str, str]] = ...,
    remote_execution_action_key_providers: None | str = ...,
    remove_classes: list[str] = ...,
    required_for_source_only_abi: bool = ...,
    resources: list[str] = ...,
    resources_root: None | str = ...,
    run_test_separately: bool = ...,
    runner: None | str = ...,
    runtime_deps: list[str] = ...,
    source: None | str = ...,
    source_abi_verification_mode: None | str = ...,
    source_only_abi_deps: list[str] = ...,
    specs: None | str = ...,
    srcs: list[str] = ...,
    std_err_log_level: None | int | str = ...,
    std_out_log_level: None | int | str = ...,
    target: None | str = ...,
    test_case_timeout_ms: None | int = ...,
    test_class_names_file: None | str = ...,
    test_rule_timeout_ms: None | int = ...,
    test_type: None | str = ...,
    unbundled_resources_root: None | str = ...,
    use_cxx_libraries: None | bool = ...,
    use_dependency_order_classpath: None | bool = ...,
    vm_args: list[str] = ...,
) -> None

A java_test() rule is used to define a set of .java files that contain tests to run via JUnit.

Parameters​

  • name: name of the target

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

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

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

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

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

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

  • metadata: a key-value map of metadata associated with this target

  • tests: a list of targets that provide tests for this one

  • modifiers: an array of modifiers associated with this target

  • cxx_library_whitelist: EXPERIMENTAL. List of cxx_libraries to build, if use_cxx_libraries is true. This can be useful if some dependencies are Android-only and won't build on the default platform.

  • deps: Same as java_library(). // org.junit.rules.Timeout was not introduced until 4.7. Must include JUnit (version 4.7 or later) as a dependency for JUnit tests. Must include TestNG (version 6.2 or later) and hamcrest as a dependencies for TestNG tests.

  • env: A map of environment names and values to set when running the test.

  • fork_mode: Controls whether tests will all be run in the same process or a process will be started for each set of tests in a class.

    (This is mainly useful when porting Java tests to Buck from Apache Ant which allows JUnit tasks to set a fork="yes" property. It should not be used for new tests since it encourages tests to not cleanup after themselves and increases the tests' computational resources and running time.)

    none All tests will run in the same process. per_test A process will be started for each test class in which all tests of that test class will run.

  • javac: Specifies the Java compiler program to use for this rule. The value is a source path or an execution dep (e.g., //foo/bar:bar). Overrides the value in "javac" in the "tools" section of .buckconfig.

  • labels: A list of labels to be applied to these tests. These labels are arbitrary text strings and have no meaning within buck itself. They can, however, have meaning for you as a test author (e.g., smoke or fast). A label can be used to filter or include a specific test rule when executing buck test

  • resources: Same as java_library().

  • source: Java language level for compiling. Corresponds to the -source argument for javac.

  • srcs: Like java_library(), all of the .java files specified by the srcs argument will be compiled when this rule is built. In addition, all of the corresponding .class files that are built by this rule will be passed as arguments to JUnit when this rule is run as a test. .class files that are passed to JUnit that do not have any methods annotated with @Test are considered failed tests, so make sure that only test case classes are specified as srcs. This is frequently done by specifying srcs as glob(['**/*Test.java']).

  • std_err_log_level: Same as std_out_log_level, but for std err.

  • std_out_log_level: Log level for messages from the source under test that buck will output to std out. Value must be a valid java.util.logging.Level value.

  • target: Bytecode target level for compiling. Corresponds to the -target argument for javac.

  • test_rule_timeout_ms: If set specifies the maximum amount of time (in milliseconds) in which all of the tests in this rule should complete. This overrides the default rule_timeout if any has been specified in .buckconfig .

  • test_type: Specifies which test framework to use. The currently supported options are 'junit' and 'testng'.

  • use_cxx_libraries: Whether or not to build and link against cxx_library() dependencies when testing.

  • vm_args: Runtime arguments to the JVM running the tests.

java_test_runner​

def java_test_runner(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    abi_generation_mode: 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] = ...,
    exported_deps: list[str] = ...,
    exported_provided_deps: list[str] = ...,
    extra_arguments: list[str] = ...,
    java_version: None | str = ...,
    javac: None | str = ...,
    labels: list[str] = ...,
    licenses: list[str] = ...,
    main_class: str = ...,
    manifest_file: None | str = ...,
    maven_coords: None | str = ...,
    never_mark_as_unused_dependency: None | bool = ...,
    on_unused_dependencies: None | str = ...,
    plugins: list[str | (str, list[str])] = ...,
    proguard_config: None | str = ...,
    provided_deps: list[str] = ...,
    remove_classes: list[str] = ...,
    required_for_source_only_abi: bool = ...,
    resources: list[str] = ...,
    resources_root: None | str = ...,
    runtime_deps: list[str] = ...,
    source: None | str = ...,
    source_abi_verification_mode: None | str = ...,
    source_only_abi_deps: list[str] = ...,
    srcs: list[str] = ...,
    target: None | str = ...,
) -> None

Parameters​

  • name: name of the target
  • default_target_platform: specifies the default target platform, used when no platforms are specified on the command line
  • target_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • exec_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with an execution platform
  • visibility: a list of visibility patterns restricting what targets can depend on this one
  • within_view: a list of visibility patterns restricting what this target can depend on
  • metadata: a key-value map of metadata associated with this target
  • tests: a list of targets that provide tests for this one
  • modifiers: an array of modifiers associated with this target
  • javac: Specifies the Java compiler program to use for this rule. The value is a source path or an execution dep (e.g., //foo/bar:bar). Overrides the value in "javac" in the "tools" section of .buckconfig.

js_bundle​

def js_bundle(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _android_toolchain: str = ...,
    _apple_platforms: dict[str, str] = ...,
    _is_release: bool = ...,
    _platform: str = ...,
    android_package: None | str = ...,
    bundle_name: None | str = ...,
    bundle_name_for_flavor: list[(str, str)] = ...,
    contacts: list[str] = ...,
    default_host_platform: None | str = ...,
    deps: list[str] = ...,
    entry: str | list[str],
    extra_json: None | str = ...,
    fallback_transform_profile: None | str = ...,
    labels: list[str] = ...,
    licenses: list[str] = ...,
    worker: str,
) -> None

Parameters​

  • name: name of the target
  • default_target_platform: specifies the default target platform, used when no platforms are specified on the command line
  • target_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • exec_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with an execution platform
  • visibility: a list of visibility patterns restricting what targets can depend on this one
  • within_view: a list of visibility patterns restricting what this target can depend on
  • metadata: a key-value map of metadata associated with this target
  • tests: a list of targets that provide tests for this one
  • modifiers: an array of modifiers associated with this target

js_bundle_genrule​

def js_bundle_genrule(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    _build_only_native_code: bool = ...,
    _exec_os_type: str = ...,
    _genrule_toolchain: str = ...,
    _is_release: bool = ...,
    _platform: str = ...,
    always_print_stderr: bool = ...,
    bash: None | str = ...,
    bundle_name: None | str = ...,
    bundle_name_for_flavor: list[(str, str)] = ...,
    cacheable: None | bool = ...,
    cmd: None | str = ...,
    cmd_exe: None | str = ...,
    contacts: list[str] = ...,
    default_host_platform: None | str = ...,
    enable_sandbox: None | bool = ...,
    environment_expansion_separator: None | str = ...,
    js_bundle: str,
    labels: list[str] = ...,
    licenses: list[str] = ...,
    metadata_env_var: None | str = ...,
    metadata_path: None | str = ...,
    need_android_tools: bool = ...,
    no_outputs_cleanup: bool = ...,
    remote: None | bool = ...,
    remote_execution_dependencies: list[dict[str, str]] = ...,
    rewrite_deps_file: bool = ...,
    rewrite_misc: bool = ...,
    rewrite_sourcemap: bool = ...,
    skip_resources: bool = ...,
    srcs: list[str] | dict[str, str] = ...,
    type: str = ...,
    weight: None | int = ...,
) -> None

Parameters​

  • name: name of the target
  • default_target_platform: specifies the default target platform, used when no platforms are specified on the command line
  • target_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • exec_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with an execution platform
  • visibility: a list of visibility patterns restricting what targets can depend on this one
  • within_view: a list of visibility patterns restricting what this target can depend on
  • metadata: a key-value map of metadata associated with this target
  • tests: a list of targets that provide tests for this one
  • modifiers: an array of modifiers associated with this target

js_library​

def js_library(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    _asset_dest_path_resolver: None | str = ...,
    _build_only_native_code: bool = ...,
    _is_release: bool = ...,
    _platform: str = ...,
    asset_extensions: None | list[str] = ...,
    asset_platforms: None | list[str] = ...,
    base_path: None | str = ...,
    contacts: list[str] = ...,
    default_host_platform: None | str = ...,
    deps: list[str] = ...,
    deps_query: None | str = ...,
    extra_json: None | str = ...,
    labels: list[str] = ...,
    licenses: list[str] = ...,
    srcs: list[str | (str, str)] = ...,
    worker: str,
) -> None

Parameters​

  • name: name of the target
  • default_target_platform: specifies the default target platform, used when no platforms are specified on the command line
  • target_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • exec_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with an execution platform
  • visibility: a list of visibility patterns restricting what targets can depend on this one
  • within_view: a list of visibility patterns restricting what this target can depend on
  • metadata: a key-value map of metadata associated with this target
  • tests: a list of targets that provide tests for this one
  • modifiers: an array of modifiers associated with this target

julia_binary​

def julia_binary(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    _julia_toolchain: str = ...,
    deps: list[str] = ...,
    julia_args: list[str] = ...,
    julia_flags: list[str] = ...,
    main: str,
    srcs: list[str] = ...,
) -> None

Parameters​

  • name: name of the target
  • default_target_platform: specifies the default target platform, used when no platforms are specified on the command line
  • target_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • exec_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with an execution platform
  • visibility: a list of visibility patterns restricting what targets can depend on this one
  • within_view: a list of visibility patterns restricting what this target can depend on
  • metadata: a key-value map of metadata associated with this target
  • tests: a list of targets that provide tests for this one
  • modifiers: an array of modifiers associated with this target

julia_jll_library​

def julia_jll_library(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    _julia_toolchain: str = ...,
    jll_name: str,
    lib_mapping: list[str] | dict[str, str],
    uuid: str,
) -> None

Parameters​

  • name: name of the target
  • default_target_platform: specifies the default target platform, used when no platforms are specified on the command line
  • target_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • exec_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with an execution platform
  • visibility: a list of visibility patterns restricting what targets can depend on this one
  • within_view: a list of visibility patterns restricting what this target can depend on
  • metadata: a key-value map of metadata associated with this target
  • tests: a list of targets that provide tests for this one
  • modifiers: an array of modifiers associated with this target

julia_library​

def julia_library(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    _julia_toolchain: str = ...,
    deps: list[str] = ...,
    project_toml: str,
    resources: list[str] = ...,
    srcs: list[str] = ...,
) -> None

Parameters​

  • name: name of the target
  • default_target_platform: specifies the default target platform, used when no platforms are specified on the command line
  • target_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • exec_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with an execution platform
  • visibility: a list of visibility patterns restricting what targets can depend on this one
  • within_view: a list of visibility patterns restricting what this target can depend on
  • metadata: a key-value map of metadata associated with this target
  • tests: a list of targets that provide tests for this one
  • modifiers: an array of modifiers associated with this target

julia_test​

def julia_test(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    _inject_test_env: str = ...,
    _julia_toolchain: str = ...,
    _test_toolchain: str = ...,
    contacts: list[str] = ...,
    deps: list[str] = ...,
    julia_args: list[str] = ...,
    julia_flags: list[str] = ...,
    main: str,
    srcs: list[str] = ...,
) -> None

Parameters​

  • name: name of the target
  • default_target_platform: specifies the default target platform, used when no platforms are specified on the command line
  • target_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • exec_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with an execution platform
  • visibility: a list of visibility patterns restricting what targets can depend on this one
  • within_view: a list of visibility patterns restricting what this target can depend on
  • metadata: a key-value map of metadata associated with this target
  • tests: a list of targets that provide tests for this one
  • modifiers: an array of modifiers associated with this target

keystore​

def keystore(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    contacts: list[str] = ...,
    default_host_platform: None | str = ...,
    deps: list[str] = ...,
    labels: list[str] = ...,
    licenses: list[str] = ...,
    properties: str,
    store: str,
) -> None

A keystore() contains the data for a key pair created by the keytool executable that comes with the JDK. This is a required input for an android_binary() rule.

Parameters​

  • name: name of the target

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

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

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

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

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

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

  • metadata: a key-value map of metadata associated with this target

  • tests: a list of targets that provide tests for this one

  • modifiers: an array of modifiers associated with this target

  • properties: The path to the .properties file that contains the following values:


    # The value that you passed as the argument to -alias
    # when you ran keytool.
    key.alias=my_alias

    # The value that you entered in response to
    # the "Enter keystore password:" prompt.
    key.store.password=store_password

    # The value that you entered in response to
    # the "Enter key password for <my_alias>" prompt.
    key.alias.password=alias_password

  • store: The path to the file that contains the key. This is the path that was passed as the -keystore argument when you ran keytool.

kotlin_library​

def kotlin_library(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _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] = ...,
    enable_used_classes: bool = ...,
    exported_deps: list[str] = ...,
    exported_provided_deps: list[str] = ...,
    extra_arguments: list[str] = ...,
    extra_kotlinc_arguments: list[str] = ...,
    friend_paths: list[str] = ...,
    incremental: bool = ...,
    jar_postprocessor: None | str = ...,
    java_version: None | str = ...,
    javac: None | str = ...,
    k2: bool = ...,
    kotlin_compiler_plugins: dict[str, dict[str, str]] = ...,
    labels: list[str] = ...,
    licenses: list[str] = ...,
    manifest_file: None | str = ...,
    maven_coords: None | str = ...,
    never_mark_as_unused_dependency: None | bool = ...,
    on_unused_dependencies: None | str = ...,
    plugins: list[str | (str, list[str])] = ...,
    proguard_config: None | str = ...,
    provided_deps: list[str] = ...,
    remove_classes: list[str] = ...,
    required_for_source_only_abi: bool = ...,
    resources: list[str] = ...,
    resources_root: None | str = ...,
    runtime_deps: list[str] = ...,
    source: None | str = ...,
    source_abi_verification_mode: None | str = ...,
    source_only_abi_deps: list[str] = ...,
    srcs: list[str] = ...,
    target: None | str = ...,
    use_jvm_abi_gen: None | bool = ...,
    validation_deps: list[str] = ...,
) -> None

A kotlin_library() rule is used to define a set of Kotlin files that can be compiled together. The main output of a kotlin_library() rule is a single JAR file containing all of the compiled class files, as well as the static files specified in the resources argument.

Parameters​

  • name: name of the target

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

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

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

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

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

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

  • metadata: a key-value map of metadata associated with this target

  • tests: a list of targets that provide tests for this one

  • modifiers: an array of modifiers associated with this target

  • annotation_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 other kotlin_library rules) that are used to generate the classpath required to compile this kotlin_library.

  • enable_used_classes: Deprecated: for an experiment only, will be removed

  • exported_deps: Other rules that depend on this rule will also include its exported_deps in their classpaths. This is useful when the public API of a rule has return types or checked exceptions that are defined in another rule, which would otherwise require callers to add an extra dependency. It's also useful for exposing e.g. a collection of prebuilt_jar rules as a single target for callers to depend on. Targets in exported_deps are implicitly included in the deps of this rule, so they don't need to be repeated there.

  • exported_provided_deps: This is a combination of provided_deps and exported_deps. Rules listed in this parameter will be added to classpath of rules that depend on this rule, but they will not be included in a binary if binary depends on a such target.

  • extra_kotlinc_arguments: List of additional arguments to pass into the Kotlin compiler.

  • friend_paths: List of source paths to pass into the Kotlin compiler as friend-paths, that is, modules you can have access to internal methods.

  • incremental: Enables Kotlin incremental compilation.

  • javac: Specifies the Java compiler program to use for this rule. The value is a source path or an execution dep (e.g., //foo/bar:bar). Overrides the value in "javac" in the "tools" section of .buckconfig.

  • k2: Enables the Kotlin K2 compiler.

  • kotlin_compiler_plugins: Use this to specify Kotlin compiler plugins to use when compiling this library. This takes a map, with each entry specify one plugin. Entry's key is plugin source path, and value is a map of plugin option key value pair. Unlike extra_kotlinc_arguments, these can be source paths, not just strings.

    A special option value is __codegen_dir__, in which case Buck will provide a default codegen folder's path as option value instead. E.g.

    fbcode/buck2/prelude/decls/jvm_common.bzl
    kotlin_compiler_plugins = {
        "somePluginSourcePath": {
            "plugin:somePluginId:somePluginOptionKey": "somePluginOptionValue",
            "plugin:somePluginId:someDirectoryRelatedOptionKey": "__codegen_dir__",
        },
    },

    Each plugin source path will be prefixed with -Xplugin= and passed as extra arguments to the compiler. Plugin options will be appended after its plugin with -P.

    A specific example is, if you want to use kotlinx.serialization with kotlin_library(), you need to specify kotlinx-serialization-compiler-plugin.jar under kotlin_compiler_plugins and kotlinx-serialization-runtime.jar (which you may have to fetch from Maven) in your deps:


    kotlin_library(
        name = "example",
        srcs = glob(["*.kt"]),
        deps = [
            ":kotlinx-serialization-runtime",
        ],
        kotlin_compiler_plugins = {
            # Likely copied from your $KOTLIN_HOME directory.
            "kotlinx-serialization-compiler-plugin.jar": {},
        },
    )

    prebuilt_jar(
        name = "kotlinx-serialization-runtime",
        binary_jar = ":kotlinx-serialization-runtime-0.10.0",
    )

    # Note you probably want to set
    # maven_repo=http://jcenter.bintray.com/ in your .buckconfig until
    # https://github.com/Kotlin/kotlinx.serialization/issues/64
    # is closed.
    remote_file(
        name = "kotlinx-serialization-runtime-0.10.0",
        out = "kotlinx-serialization-runtime-0.10.0.jar",
        url = "mvn:org.jetbrains.kotlinx:kotlinx-serialization-runtime:jar:0.10.0",
        sha1 = "23d777a5282c1957c7ce35946374fff0adab114c"
    )

  • labels: Set of arbitrary strings which allow you to annotate a build rule with tags that can be searched for over an entire dependency tree using buck query() .

  • provided_deps: These represent dependencies that are known to be provided at run time, but are required in order for the code to compile. Examples of provided_deps include the JEE servlet APIs. When this rule is included in a , the provided_deps will not be packaged into the output.

  • remove_classes: Specifies a list of Patterns that are used to exclude classes from the JAR. The pattern matching is based on the name of the class. This can be used to exclude a member class or delete a local view of a class that will be replaced during a later stage of the build.

  • resources: Static files to include with the compiled .class files. These files can be loaded via Class.getResource().

    Note: If resources_root isn't set, Buck uses the .buckconfig property in .buckconfig to determine where resources should be placed within the generated JAR file.

  • srcs: The set of .kt, .java or .kts files to compile for this rule. If any of the files in this list end in .src.zip, then the entries in the ZIP file that end in .java or .kt will be included as ordinary inputs to compilation.

Details​

Examples:


# A rule that compiles a single .kt file.
kotlin_library(
  name = 'JsonUtil',
  srcs = ['JsonUtil.kt'],
  deps = [
    '//third_party/guava:guava',
    '//third_party/jackson:jackson',
  ],
)

# A rule that compiles all of the .kt files under the directory in
# which the rule is defined using glob(). It also excludes an
# individual file that may have additional dependencies, so it is
# compiled by a separate rule.
kotlin_library(
  name = 'messenger',
  srcs = glob(['**/*.kt'], excludes = ['MessengerModule.kt']),
  deps = [
    '//src/com/facebook/base:base',
    '//third_party/guava:guava',
  ],
)

kotlin_library(
  name = 'MessengerModule',
  srcs = ['MessengerModule.kt'],
  deps = [
    '//src/com/facebook/base:base',
    '//src/com/google/inject:inject',
    '//third_party/guava:guava',
    '//third_party/jsr-330:jsr-330',
  ],
)

# A rule that builds a library with both relative and
# fully-qualified deps.
kotlin_library(
  name = 'testutil',
  srcs = glob(['tests/**/*.kt'], excludes = 'tests/**/*Test.kt'),
  deps = [
    ':lib-fb4a',
    '//java/com/facebook/base:base',
  ],
)

kotlin_test​

def kotlin_test(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    _build_only_native_code: bool = ...,
    _exec_os_type: str = ...,
    _inject_test_env: str = ...,
    _is_building_android_binary: bool = ...,
    _java_test_toolchain: str = ...,
    _java_toolchain: str = ...,
    _kotlin_toolchain: str = ...,
    _remote_test_execution_toolchain: str = ...,
    _test_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] = ...,
    cxx_library_whitelist: list[str] = ...,
    default_cxx_platform: None | str = ...,
    default_host_platform: None | str = ...,
    deps: list[str] = ...,
    deps_query: None | str = ...,
    enable_used_classes: bool = ...,
    env: dict[str, str] = ...,
    exported_deps: list[str] = ...,
    exported_provided_deps: list[str] = ...,
    extra_arguments: list[str] = ...,
    extra_kotlinc_arguments: list[str] = ...,
    fork_mode: str = ...,
    friend_paths: list[str] = ...,
    incremental: bool = ...,
    java: None | str = ...,
    java_agents: list[str] = ...,
    java_version: None | str = ...,
    javac: None | str = ...,
    k2: bool = ...,
    kotlin_compiler_plugins: dict[str, dict[str, str]] = ...,
    labels: list[str] = ...,
    licenses: list[str] = ...,
    manifest_file: None | str = ...,
    maven_coords: None | str = ...,
    never_mark_as_unused_dependency: None | bool = ...,
    on_unused_dependencies: None | str = ...,
    plugins: list[str] = ...,
    proguard_config: None | str = ...,
    provided_deps: list[str] = ...,
    remote_execution: None | str | dict[str, None | bool | int | str | list[dict[str, str]] | dict[str, str]] = ...,
    remote_execution_action_key_providers: None | str = ...,
    remove_classes: list[str] = ...,
    required_for_source_only_abi: bool = ...,
    resources: list[str] = ...,
    resources_root: None | str = ...,
    run_test_separately: bool = ...,
    runtime_deps: list[str] = ...,
    source: None | str = ...,
    source_abi_verification_mode: None | str = ...,
    source_only_abi_deps: list[str] = ...,
    srcs: list[str] = ...,
    std_err_log_level: None | int | str = ...,
    std_out_log_level: None | int | str = ...,
    target: None | str = ...,
    test_case_timeout_ms: None | int = ...,
    test_class_names_file: None | str = ...,
    test_rule_timeout_ms: None | int = ...,
    test_type: None | str = ...,
    unbundled_resources_root: None | str = ...,
    use_cxx_libraries: None | bool = ...,
    use_dependency_order_classpath: None | bool = ...,
    use_jvm_abi_gen: None | bool = ...,
    vm_args: list[str] = ...,
) -> None

A kotlin_test() rule is used to define a set of .kt files that contain tests to run via JUnit.

Parameters​

  • name: name of the target

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

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

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

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

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

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

  • metadata: a key-value map of metadata associated with this target

  • tests: a list of targets that provide tests for this one

  • modifiers: an array of modifiers associated with this target

  • deps: Same as kotlin_library(). // org.junit.rules.Timeout was not introduced until 4.7. Must include JUnit (version 4.7 or later) as a dependency for JUnit tests. Must include TestNG (version 6.2 or later) and hamcrest as a dependencies for TestNG tests.

  • enable_used_classes: Deprecated: for an experiment only, will be removed

  • env: A map of environment names and values to set when running the test.

  • fork_mode: Controls whether tests will all be run in the same process or a process will be started for each set of tests in a class.

    (This is mainly useful when porting Java tests to Buck from Apache Ant which allows JUnit tasks to set a fork="yes" property. It should not be used for new tests since it encourages tests to not cleanup after themselves and increases the tests' computational resources and running time.)

    none All tests will run in the same process. per_test A process will be started for each test class in which all tests of that test class will run.

  • incremental: Enables Kotlin incremental compilation.

  • javac: Specifies the Java compiler program to use for this rule. The value is a source path or an execution dep (e.g., //foo/bar:bar). Overrides the value in "javac" in the "tools" section of .buckconfig.

  • k2: Enables the Kotlin K2 compiler.

  • kotlin_compiler_plugins: Use this to specify Kotlin compiler plugins to use when compiling this library. This takes a map, with each entry specify one plugin. Entry's key is plugin source path, and value is a map of plugin option key value pair. Unlike extra_kotlinc_arguments, these can be source paths, not just strings.

    A special option value is __codegen_dir__, in which case Buck will provide a default codegen folder's path as option value instead. E.g.

    fbcode/buck2/prelude/decls/jvm_common.bzl
    kotlin_compiler_plugins = {
        "somePluginSourcePath": {
            "plugin:somePluginId:somePluginOptionKey": "somePluginOptionValue",
            "plugin:somePluginId:someDirectoryRelatedOptionKey": "__codegen_dir__",
        },
    },

    Each plugin source path will be prefixed with -Xplugin= and passed as extra arguments to the compiler. Plugin options will be appended after its plugin with -P.

    A specific example is, if you want to use kotlinx.serialization with kotlin_library(), you need to specify kotlinx-serialization-compiler-plugin.jar under kotlin_compiler_plugins and kotlinx-serialization-runtime.jar (which you may have to fetch from Maven) in your deps:


    kotlin_library(
        name = "example",
        srcs = glob(["*.kt"]),
        deps = [
            ":kotlinx-serialization-runtime",
        ],
        kotlin_compiler_plugins = {
            # Likely copied from your $KOTLIN_HOME directory.
            "kotlinx-serialization-compiler-plugin.jar": {},
        },
    )

    prebuilt_jar(
        name = "kotlinx-serialization-runtime",
        binary_jar = ":kotlinx-serialization-runtime-0.10.0",
    )

    # Note you probably want to set
    # maven_repo=http://jcenter.bintray.com/ in your .buckconfig until
    # https://github.com/Kotlin/kotlinx.serialization/issues/64
    # is closed.
    remote_file(
        name = "kotlinx-serialization-runtime-0.10.0",
        out = "kotlinx-serialization-runtime-0.10.0.jar",
        url = "mvn:org.jetbrains.kotlinx:kotlinx-serialization-runtime:jar:0.10.0",
        sha1 = "23d777a5282c1957c7ce35946374fff0adab114c"
    )

  • labels: A list of labels to be applied to these tests. These labels are arbitrary text strings and have no meaning within buck itself. They can, however, have meaning for you as a test author (e.g., smoke or fast). A label can be used to filter or include a specific test rule when executing buck test

  • resources: Same as kotlin_library().

  • srcs: Like kotlin_library(), all of the .kt files specified by the srcs argument will be compiled when this rule is built. In addition, all of the corresponding .class files that are built by this rule will be passed as arguments to JUnit when this rule is run as a test. .class files that are passed to JUnit that do not have any methods annotated with @Test are considered failed tests, so make sure that only test case classes are specified as srcs. This is frequently done by specifying srcs as glob(['**/*Test.kt']).

  • std_err_log_level: Same as std_out_log_level, but for std err.

  • std_out_log_level: Log level for messages from the source under test that buck will output to std out. Value must be a valid java.util.logging.Level value.

  • test_rule_timeout_ms: If set specifies the maximum amount of time (in milliseconds) in which all of the tests in this rule should complete. This overrides the default rule_timeout if any has been specified in .buckconfig .

  • test_type: Specifies which test framework to use. The currently supported options are 'junit' and 'testng'.

  • vm_args: Runtime arguments to the JVM running the tests.

legacy_toolchain​

def legacy_toolchain(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    contacts: list[str] = ...,
    default_host_platform: None | str = ...,
    labels: list[str] = ...,
    licenses: list[str] = ...,
    toolchain_name: str = ...,
) -> None

Parameters​

  • name: name of the target
  • default_target_platform: specifies the default target platform, used when no platforms are specified on the command line
  • target_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • exec_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with an execution platform
  • visibility: a list of visibility patterns restricting what targets can depend on this one
  • within_view: a list of visibility patterns restricting what this target can depend on
  • metadata: a key-value map of metadata associated with this target
  • tests: a list of targets that provide tests for this one
  • modifiers: an array of modifiers associated with this target
def llvm_link_bitcode(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    _cxx_toolchain: str = ...,
    deps: list[str] = ...,
    deps_query: None | str = ...,
    srcs: list[str | (str, list[str])] = ...,
) -> None

A llvm_link_bitcode() rule builds a LLVM bitcode object from a given set LLVM bitcode inputs.

Parameters​

  • name: name of the target

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

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

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

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

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

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

  • metadata: a key-value map of metadata associated with this target

  • tests: a list of targets that provide tests for this one

  • modifiers: an array of modifiers associated with this target

  • deps_query: Status: experimental/unstable. The deps query takes a query string that accepts the following query functions, and appends the output of the query to the declared deps:

    • attrfilter

    • deps

    • except

    • intersect

    • filter

    • kind

    • set

    • union

    The macro $declared_deps may be used anywhere a target literal pattern is expected in order to refer to the explicit deps of this rule as they appear in the rule's definition. For example, if your build rule declares


      android_library(
        name = 'lib',
        deps = ['//foo:foo'],
        deps_query = '$declared_deps',
      )

    then the macro $declared_deps would be expanded to a 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.

  • srcs: The set of C, C++, Objective-C, Objective-C++, or assembly source files to be preprocessed, compiled, and assembled by this rule. We determine which stages to run on each input source based on its file extension. See the GCC documentation for more detail on how file extensions are interpreted. Each element can be either a string specifying a source file (e.g. '') or a tuple of a string specifying a source file and a list of compilation flags (e.g. ('', ['-Wall', '-Werror']) ). In the latter case the specified flags will be used in addition to the rule's other flags when preprocessing and compiling that file (if applicable).

Details​

Examples:


# A rule that builds and runs C/C++ test using gtest.
llvm_link_bitcode(
  name = 'echo_test',
  srcs = [
    'echo_test.o',  // Where this is a LLVM bitcode object.
    'echo_other.o', // And this is another LLVM bitcode object.
  ],
)

lua_binary​

def lua_binary(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    contacts: list[str] = ...,
    default_host_platform: None | str = ...,
    deps: list[str] = ...,
    labels: list[str] = ...,
    licenses: list[str] = ...,
    main_module: str = ...,
    native_starter_library: None | str = ...,
    package_style: None | str = ...,
    platform: None | str = ...,
    platform_deps: list[(str, list[str])] = ...,
    python_platform: None | str = ...,
) -> None

A lua_library() rule is used to group together Lua sources to be packaged into a top-level lua_binary() rule.

Parameters​

  • name: name of the target
  • default_target_platform: specifies the default target platform, used when no platforms are specified on the command line
  • target_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • exec_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with an execution platform
  • visibility: a list of visibility patterns restricting what targets can depend on this one
  • within_view: a list of visibility patterns restricting what this target can depend on
  • metadata: a key-value map of metadata associated with this target
  • tests: a list of targets that provide tests for this one
  • modifiers: an array of modifiers associated with this target
  • deps: lua_library() rules to this binary will access.
  • main_module: The module which serves as the entry point for this rule.

Details​

Examples:


lua_binary(
  name = 'tailer',
  main_module = 'tailer',
  deps = [
    ':tailerutils',
  ],
)

lua_library(
  name = 'tailerutils',
  srcs = glob(['*.lua']),
)

lua_library​

def lua_library(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    base_module: None | str = ...,
    contacts: list[str] = ...,
    default_host_platform: None | str = ...,
    deps: list[str] = ...,
    labels: list[str] = ...,
    licenses: list[str] = ...,
    platform_deps: list[(str, list[str])] = ...,
    srcs: list[str] | dict[str, str] = ...,
) -> None

A lua_library() rule is used to group together Lua sources to be packaged into a top-level lua_binary() rule.

Parameters​

  • name: name of the target
  • default_target_platform: specifies the default target platform, used when no platforms are specified on the command line
  • target_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • exec_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with an execution platform
  • visibility: a list of visibility patterns restricting what targets can depend on this one
  • within_view: a list of visibility patterns restricting what this target can depend on
  • metadata: a key-value map of metadata associated with this target
  • tests: a list of targets that provide tests for this one
  • modifiers: an array of modifiers associated with this target
  • base_module: The package for which the given specified sources and resources should reside in their final location in the top-level binary. If unset, the project relative directory that houses the BUCK file is used.
  • deps: Other lua_library() rules which list srcs from which this rule imports modules.
  • srcs: The set of .lua files included in this library.

Details​

Examples:


# A rule that includes a single .py file.
lua_library(
  name = 'fileutil',
  srcs = ['fileutil.lua'],
)

# A rule that uses glob() to include all sources in the directory which the
# rule is defined.  It also lists a resource file that gets packaged with
# the sources in this rule.
lua_library(
  name = 'testutil',
  srcs = glob(['testutil/**/*.lua'],
)

matlab_program​

def matlab_program(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    _matlab_toolchain: str = ...,
    main: str,
) -> None

Parameters​

  • name: name of the target
  • default_target_platform: specifies the default target platform, used when no platforms are specified on the command line
  • target_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • exec_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with an execution platform
  • visibility: a list of visibility patterns restricting what targets can depend on this one
  • within_view: a list of visibility patterns restricting what this target can depend on
  • metadata: a key-value map of metadata associated with this target
  • tests: a list of targets that provide tests for this one
  • modifiers: an array of modifiers associated with this target

ndk_library​

def ndk_library(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    contacts: list[str] = ...,
    default_host_platform: None | str = ...,
    deps: list[str] = ...,
    flags: list[str] = ...,
    is_asset: bool = ...,
    labels: list[str] = ...,
    licenses: list[str] = ...,
    srcs: list[str] = ...,
) -> None

An ndk_library() is used to define a set of C/C++ files, an Android.mk and an Application.mk file that are used by the NDK's ndk-build tool to generate one or more shared objects.

Parameters​

  • name: name of the target
  • default_target_platform: specifies the default target platform, used when no platforms are specified on the command line
  • target_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • exec_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with an execution platform
  • visibility: a list of visibility patterns restricting what targets can depend on this one
  • within_view: a list of visibility patterns restricting what this target can depend on
  • metadata: a key-value map of metadata associated with this target
  • tests: a list of targets that provide tests for this one
  • modifiers: an array of modifiers associated with this target
  • deps: List of build targets to build before this rule.
  • flags: Array of strings passed verbatim to ndk-build. Normally this is not needed, but in some cases you may want to put something here. For example, this can be used to build the libraries in debug mode (NDK_DEBUG=1) or set the number of jobs spawned by ndk-build (by default, the same as the number of cores).
  • is_asset: Normally native shared objects end up in a directory in the root of the APK named lib/. If this parameter is set to True, then these objects are placed in assets/lib/. Placing shared objects in a non-standard location prevents Android from extracting them to the device's internal storage.
  • srcs: The set of files to compile for this rule. If not provided, buck assumes that all files with the following extensions are part of the build: c, cpp, cc, cxx, h, hpp, mk.

Details​

Additional notes:

An android_binary() that includes this library will aggregate all of the native shared objects into a directory in the root of the APK named lib/ or assets/lib/.

Unlike the default invocation of ndk-build, buck will put all intermediate files and build output into a subdirectory under buck-out/gen.

ndk_toolchain​

def ndk_toolchain(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    contacts: list[str] = ...,
    cxx_runtime: None | str = ...,
    cxx_toolchain: str,
    default_host_platform: None | str = ...,
    labels: list[str] = ...,
    licenses: list[str] = ...,
    objdump: str,
    shared_runtime_path: None | str = ...,
    strip_apk_libs_flags: None | list[str] = ...,
) -> None

Parameters​

  • name: name of the target
  • default_target_platform: specifies the default target platform, used when no platforms are specified on the command line
  • target_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • exec_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with an execution platform
  • visibility: a list of visibility patterns restricting what targets can depend on this one
  • within_view: a list of visibility patterns restricting what this target can depend on
  • metadata: a key-value map of metadata associated with this target
  • tests: a list of targets that provide tests for this one
  • modifiers: an array of modifiers associated with this target

ocaml_binary​

def ocaml_binary(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    _cxx_toolchain: str = ...,
    _ocaml_toolchain: str = ...,
    bytecode_only: None | bool = ...,
    compiler_flags: list[str] = ...,
    contacts: list[str] = ...,
    default_host_platform: None | str = ...,
    deps: list[str] = ...,
    labels: list[str] = ...,
    licenses: list[str] = ...,
    linker_flags: list[str] = ...,
    ocamldep_flags: list[str] = ...,
    platform: None | str = ...,
    platform_compiler_flags: list[(str, list[str])] = ...,
    platform_deps: list[(str, list[str])] = ...,
    platform_linker_flags: list[(str, list[str])] = ...,
    srcs: None | list[str] | dict[str, str] = ...,
    warnings_flags: None | str = ...,
) -> None

A ocaml_binary() rule builds both native and bytecode executables from the supplied set of OCaml and C source files and dependencies.

Parameters​

  • name: name of the target
  • default_target_platform: specifies the default target platform, used when no platforms are specified on the command line
  • target_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • exec_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with an execution platform
  • visibility: a list of visibility patterns restricting what targets can depend on this one
  • within_view: a list of visibility patterns restricting what this target can depend on
  • metadata: a key-value map of metadata associated with this target
  • tests: a list of targets that provide tests for this one
  • modifiers: an array of modifiers associated with this target
  • compiler_flags: The set of additional compiler flags to pass to ocaml compiler. It supports specifying ppx (see for example).
  • deps: The set of dependencies of this rule. It could include references to ocaml_library and cxx_library rules.
  • platform_deps: Platform specific dependencies. These should be specified as a list of pairs where the first element is an un-anchored regex (in java.util.regex.Pattern syntax) against which the platform name is matched, and the second element is a list of dependencies (same format as deps) that are exported if the platform matches the regex. See deps for more information.
  • srcs: The set of source files to be compiled by this rule. It supports *.ml, *.mli, *.mly, *.mll, and *.c files. (see this test as C interop example and this test as parser and lexer example).

Details​

Note: Buck is currently tested with 4.X OCaml series.

Examples:

For more examples, check out our integration tests.


ocaml_binary(
  name='greet',
  srcs=[
    'main.ml',
    'lex.mll',
    'parser.mly',
    'hashtable.c',
  ],
  deps=[
    ':greeting',
    ':bridge',
  ],
)

ocaml_library(
  name='greeting',
  srcs=[
    'greeting.ml',
  ],
  deps=[
    ':join',
  ],
)

ocaml_library(
  name='join',
  srcs=[
    'join.ml',
  ],
)

cxx_library(
  name='bridge',
  srcs=[
    'bridge.c',
  ],
)

ocaml_library​

def ocaml_library(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    _cxx_toolchain: str = ...,
    _ocaml_toolchain: str = ...,
    bytecode_only: bool = ...,
    compiler_flags: list[str] = ...,
    contacts: list[str] = ...,
    default_host_platform: None | str = ...,
    deps: list[str] = ...,
    labels: list[str] = ...,
    licenses: list[str] = ...,
    linker_flags: list[str] = ...,
    native_plugin: bool = ...,
    ocamldep_flags: list[str] = ...,
    platform_compiler_flags: list[(str, list[str])] = ...,
    platform_deps: list[(str, list[str])] = ...,
    srcs: None | list[str] | dict[str, str] = ...,
    warnings_flags: None | str = ...,
) -> None

A ocaml_library() rule builds a native and a bytecode libraries from the supplied set of OCaml source files and dependencies.

Parameters​

  • name: name of the target
  • default_target_platform: specifies the default target platform, used when no platforms are specified on the command line
  • target_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • exec_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with an execution platform
  • visibility: a list of visibility patterns restricting what targets can depend on this one
  • within_view: a list of visibility patterns restricting what this target can depend on
  • metadata: a key-value map of metadata associated with this target
  • tests: a list of targets that provide tests for this one
  • modifiers: an array of modifiers associated with this target
  • compiler_flags: The set of additional compiler flags to pass to ocaml compiler. It supports specifying ppx (see for example).
  • deps: The set of dependencies of this rule. It could include references to ocaml_library and cxx_library rules.
  • platform_deps: Platform specific dependencies. These should be specified as a list of pairs where the first element is an un-anchored regex (in java.util.regex.Pattern syntax) against which the platform name is matched, and the second element is a list of dependencies (same format as deps) that are exported if the platform matches the regex. See deps for more information.
  • srcs: The set of source files to be compiled by this rule. It supports *.ml, *.mli, *.mly, *.mll, and *.c files. (see this test as C interop example and this test as parser and lexer example).

Details​

Note: Buck is currently tested with 4.X OCaml series.

Examples:

For more examples, check out our integration tests.


ocaml_library(
  name='greeting',
  srcs=[
    'greeting.ml',
  ],
  deps=[
    ':join',
  ],
)

ocaml_object​

def ocaml_object(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    _cxx_toolchain: str = ...,
    _ocaml_toolchain: str = ...,
    bytecode_only: None | bool = ...,
    compiler_flags: list[str] = ...,
    contacts: list[str] = ...,
    default_host_platform: None | str = ...,
    deps: list[str] = ...,
    labels: list[str] = ...,
    licenses: list[str] = ...,
    linker_flags: list[str] = ...,
    ocamldep_flags: list[str] = ...,
    platform: None | str = ...,
    platform_deps: list[(str, list[str])] = ...,
    platform_linker_flags: list[(str, list[str])] = ...,
    srcs: None | list[str] | dict[str, str] = ...,
    warnings_flags: None | str = ...,
) -> None

Parameters​

  • name: name of the target
  • default_target_platform: specifies the default target platform, used when no platforms are specified on the command line
  • target_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • exec_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with an execution platform
  • visibility: a list of visibility patterns restricting what targets can depend on this one
  • within_view: a list of visibility patterns restricting what this target can depend on
  • metadata: a key-value map of metadata associated with this target
  • tests: a list of targets that provide tests for this one
  • modifiers: an array of modifiers associated with this target

ocaml_shared​

def ocaml_shared(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    _cxx_toolchain: str = ...,
    _ocaml_toolchain: str = ...,
    bytecode_only: None | bool = ...,
    compiler_flags: list[str] = ...,
    contacts: list[str] = ...,
    default_host_platform: None | str = ...,
    deps: list[str] = ...,
    labels: list[str] = ...,
    licenses: list[str] = ...,
    linker_flags: list[str] = ...,
    ocamldep_flags: list[str] = ...,
    platform: None | str = ...,
    platform_deps: list[(str, list[str])] = ...,
    platform_linker_flags: list[(str, list[str])] = ...,
    srcs: None | list[str] | dict[str, str] = ...,
    warnings_flags: None | str = ...,
) -> None

Parameters​

  • name: name of the target
  • default_target_platform: specifies the default target platform, used when no platforms are specified on the command line
  • target_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • exec_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with an execution platform
  • visibility: a list of visibility patterns restricting what targets can depend on this one
  • within_view: a list of visibility patterns restricting what this target can depend on
  • metadata: a key-value map of metadata associated with this target
  • tests: a list of targets that provide tests for this one
  • modifiers: an array of modifiers associated with this target

platform​

def platform(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    constraint_values: list[str] = ...,
    deps: list[str] = ...,
) -> None

Parameters​

  • name: name of the target
  • default_target_platform: specifies the default target platform, used when no platforms are specified on the command line
  • target_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • exec_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with an execution platform
  • visibility: a list of visibility patterns restricting what targets can depend on this one
  • within_view: a list of visibility patterns restricting what this target can depend on
  • metadata: a key-value map of metadata associated with this target
  • tests: a list of targets that provide tests for this one
  • modifiers: an array of modifiers associated with this target

prebuilt_apple_framework​

def prebuilt_apple_framework(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    _apple_toolchain: str = ...,
    _apple_tools: str = ...,
    _stripped_default: bool = ...,
    contacts: list[str] = ...,
    contains_swift: bool = ...,
    default_host_platform: None | str = ...,
    deps: list[str] = ...,
    dsyms: list[str] = ...,
    exported_linker_flags: list[str] = ...,
    exported_platform_linker_flags: list[(str, list[str])] = ...,
    extra_codesign_paths: list[str] = ...,
    framework: None | str = ...,
    frameworks: list[str] = ...,
    labels: list[str] = ...,
    libraries: list[str] = ...,
    licenses: list[str] = ...,
    modular: bool = ...,
    preferred_linkage: str = ...,
    sdk_modules: list[str] = ...,
    stripped: None | bool = ...,
    supported_platforms_regex: None | str = ...,
) -> None

A prebuilt_apple_framework() rule represents a set of Objective-C/C++ source files and is very similar to a prebuilt_cxx_library() rule.

Parameters​

  • name: name of the target
  • default_target_platform: specifies the default target platform, used when no platforms are specified on the command line
  • target_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • exec_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with an execution platform
  • visibility: a list of visibility patterns restricting what targets can depend on this one
  • within_view: a list of visibility patterns restricting what this target can depend on
  • metadata: a key-value map of metadata associated with this target
  • tests: a list of targets that provide tests for this one
  • modifiers: an array of modifiers associated with this target
  • extra_codesign_paths: A list of extra paths, relative to the framework root, that will be codesigned.

Details​

Examples:


prebuilt_apple_framework(
  name = 'MyPrebuiltFramework',
  framework = 'myPrebuiltFramework.framework',
  preferred_linkage = 'static',
  visibility = [
    'PUBLIC'
  ]
)

prebuilt_cxx_library​

def prebuilt_cxx_library(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    _create_third_party_build_root: str = ...,
    _cxx_toolchain: str = ...,
    _target_os_type: str = ...,
    allow_cache_upload: None | bool = ...,
    can_be_asset: bool = ...,
    contacts: list[str] = ...,
    default_host_platform: None | str = ...,
    deffile: None | str = ...,
    deps: list[str] = ...,
    exported_deps: list[str] = ...,
    exported_header_style: str = ...,
    exported_headers: list[str] | dict[str, str] = ...,
    exported_lang_platform_preprocessor_flags: dict[str, list[(str, list[str])]] = ...,
    exported_lang_preprocessor_flags: dict[str, list[str]] = ...,
    exported_linker_flags: list[str] = ...,
    exported_platform_deps: list[(str, list[str])] = ...,
    exported_platform_headers: list[(str, list[str] | dict[str, str])] = ...,
    exported_platform_linker_flags: list[(str, list[str])] = ...,
    exported_platform_preprocessor_flags: list[(str, list[str])] = ...,
    exported_post_linker_flags: list[str] = ...,
    exported_post_platform_linker_flags: list[(str, list[str])] = ...,
    exported_preprocessor_flags: list[str] = ...,
    extract_soname: bool = ...,
    force_static: bool = ...,
    frameworks: list[str] = ...,
    header_dirs: None | list[str] = ...,
    header_namespace: None | str = ...,
    header_only: bool = ...,
    import_lib: None | str = ...,
    include_in_android_merge_map_output: bool = ...,
    labels: list[str] = ...,
    libraries: list[str] = ...,
    licenses: list[str] = ...,
    link_whole: bool = ...,
    link_without_soname: bool = ...,
    linker_flags: list[str] = ...,
    local_linker_flags: list[str] = ...,
    platform_header_dirs: None | list[(str, list[str])] = ...,
    platform_import_lib: None | list[(str, str)] = ...,
    platform_shared_lib: None | list[(str, str)] = ...,
    platform_static_lib: None | list[(str, str)] = ...,
    platform_static_pic_lib: None | list[(str, str)] = ...,
    post_linker_flags: list[str] = ...,
    preferred_linkage: str = ...,
    prestripped: bool = ...,
    provided: bool = ...,
    public_include_directories: list[str] = ...,
    public_system_include_directories: list[str] = ...,
    raw_headers: list[str] = ...,
    shared_lib: None | str = ...,
    soname: None | str = ...,
    static_lib: None | str = ...,
    static_pic_lib: None | str = ...,
    supported_platforms_regex: None | str = ...,
    supports_lto: bool = ...,
    supports_merged_linking: None | bool = ...,
    supports_python_dlopen: bool = ...,
    supports_shared_library_interface: bool = ...,
    version: None | str = ...,
    versioned_exported_lang_platform_preprocessor_flags: list[(dict[str, str], dict[str, list[(str, list[str])]])] = ...,
    versioned_exported_lang_preprocessor_flags: list[(dict[str, str], dict[str, list[str]])] = ...,
    versioned_exported_platform_preprocessor_flags: list[(dict[str, str], list[(str, list[str])])] = ...,
    versioned_exported_preprocessor_flags: list[(dict[str, str], list[str])] = ...,
    versioned_header_dirs: None | list[(dict[str, str], list[str])] = ...,
    versioned_import_lib: None | list[(dict[str, str], str)] = ...,
    versioned_shared_lib: None | list[(dict[str, str], str)] = ...,
    versioned_soname: None | list[(dict[str, str], str)] = ...,
    versioned_static_lib: None | list[(dict[str, str], str)] = ...,
    versioned_static_pic_lib: None | list[(dict[str, str], str)] = ...,
) -> None

A prebuilt_cxx_library() rule represents a set of native libraries and C/C++ header files and provides various flags to control how they are linked and exported.

Parameters​

  • name: name of the target
  • default_target_platform: specifies the default target platform, used when no platforms are specified on the command line
  • target_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • exec_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with an execution platform
  • visibility: a list of visibility patterns restricting what targets can depend on this one
  • within_view: a list of visibility patterns restricting what this target can depend on
  • metadata: a key-value map of metadata associated with this target
  • tests: a list of targets that provide tests for this one
  • modifiers: an array of modifiers associated with this target
  • allow_cache_upload: Whether to allow uploading the output of this rule to be uploaded to cache when the action is executed locally if the configuration allows (i.e. there is a cache configured and the client has permission to write to it).
  • deffile: Specifies the *.def file used on windows to modify a dll's exports in place of explicit __declspec(dllexport) declarations. The default is to not use a defile.
  • exported_deps: Dependencies that will also appear to belong to any rules that depend on this one. This has two effects: * Exported dependencies will also be included in the link line of dependents of this rules, but normal dependencies will not. * When reexport_all_header_dependencies = False, only exported headers of the rules specified here are re-exported.
  • exported_headers: The set of header files that are made available for inclusion to the source files in the target and all targets that transitively depend on it. These should be specified as either a list of header files or a dictionary of header names to header files. The headers can be included with #include "$HEADER_NAMESPACE/$HEADER_NAME" or #include <$HEADER_NAMESPACE/$HEADER_NAME>, where $HEADER_NAMESPACE is the value of the target's header_namespace attribute, and $HEADER_NAME is the header name if specified, and the filename of the header file otherwise. Note that the header name can contain forward slashes (/). See header_namespace for more information.
  • exported_linker_flags: Flags to add to the linker command line when the output from this rule, or the output from any rule that transitively depends on this rule, is used in a link operation.
  • exported_platform_deps: Platform specific dependencies that will also appear to belong to any rules that depend on this one. These should be specified as a list of pairs where the first element is an un-anchored regex (in java.util.regex.Pattern syntax) against which the platform name is matched, and the second element is a list of external dependencies (same format as exported_deps) that are exported if the platform matches the regex. See exported_deps for more information.
  • exported_platform_headers: Platform specific header files. These should be specified as a list of pairs where the first element is an un-anchored regex (in java.util.regex.Pattern syntax) against which the platform name is matched, and the second element is either a list of header files or a dictionary of header names to header files that will be made available for inclusion to the source files in the target and all targets that transitively depend on it if the platform matches the regex. See headers for more information.
  • exported_platform_preprocessor_flags: Platform specific exported preprocessor flags. These should be specified as a list of pairs where the first element is an un-anchored regex (in java.util.regex.Pattern syntax) against which the platform name is matched, and the second element is a list of flags to use when preprocessing the source files in the target and all targets that transitively depend on it if the platform matches the regex. See exported_preprocessor_flags for more information.
  • header_namespace: A path prefix when including headers of this target. Defaults to the path from the root of the repository to the directory where this target is defined. Can contain forward slashes (/), but cannot start with one. See headers for more information.
  • header_only: Indicates if this library only consists of headers or not. If this is set to True, Buck will not link this library into any library that depends on it.
  • local_linker_flags: Flags to add to the linker command line whenever the output from this rule is used in a link operation driven by this rule (e.g. when this rule links a shared library, but not when the output is linked into a shared library by another rule's link group links).
  • platform_shared_lib: Platform specific shared library. These should be specified as a list of pairs where the first element is an un-anchored regex (in java.util.regex.Pattern syntax) against which the platform name is matched, and the second element the path to the library. See shared_lib for more information.
  • platform_static_lib: Platform specific static library. These should be specified as a list of pairs where the first element is an un-anchored regex (in java.util.regex.Pattern syntax) against which the platform name is matched, and the second element the path to the library. See static_lib for more information.
  • platform_static_pic_lib: Platform specific static PIC library. These should be specified as a list of pairs where the first element is an un-anchored regex (in java.util.regex.Pattern syntax) against which the platform name is matched, and the second element the path to the library. See static_pic_lib for more information.
  • preferred_linkage: Determines what linkage is used when the library is depended on by another target. To control how the dependencies of this library are linked, use link_style instead.
  • prestripped: When set, skips running strip commands when building this library.
  • shared_lib: The path to the library to use when performing shared linking.
  • static_lib: The path to the library to use when performing static linking.
  • static_pic_lib: The path to the library to use when performing static PIC linking.
  • supported_platforms_regex: If present, an un-anchored regex (in java.util.regex.Pattern syntax) that matches all platforms that this library supports. It will not be built for other platforms.
  • supports_merged_linking: Whether this rule supports building with the merged linking strategy when building for non-native binaries (e.g. when using .buckconfig s merged setting).
  • version: A string denoting a meaningful version of this rule that is optionally passed to the linker as extra metadata.

Details​

Examples:

A prebuilt library containing only headers that other libraries may need.


prebuilt_cxx_library(
  name = 'stdutil',
  header_only = True,
  header_dirs = [
    'include',
  ],
)

A prebuilt library with static and shared libs.


prebuilt_cxx_library(
  name = 'mylib',
  soname = 'libmylib.so',
  static_lib = 'libmylib.a',
  static_pic_lib = 'libmylib_pic.a',
  shared_lib = 'libmylib.so',
  exported_headers = [
    'mylib.h',
  ],
)

A prebuilt library with multiple builds for multiple platforms.


prebuilt_cxx_library(
  name = 'mylib',
  soname = 'libmylib.so',
  platform_shared_lib = [
    ('android-arm', 'android-arm/libmylib.so'),
    ('android-x86', 'android-x86/libmylib.so'),
    ('iphonesimulator-x86_64', 'iphonesimulator-x86_64/libmylib.so'),
  ],
  platform_static_lib = [
    ('android-arm', 'android-arm/libmylib.a'),
    ('android-x86', 'android-x86/libmylib.a'),
    ('iphonesimulator-x86_64', 'iphonesimulator-x86_64/libmylib.a'),
  ],
  exported_headers = [
    'mylib.h',
  ],
)

prebuilt_cxx_library_group​

def prebuilt_cxx_library_group(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    _cxx_toolchain: str = ...,
    contacts: list[str] = ...,
    default_host_platform: None | str = ...,
    deps: list[str] = ...,
    exported_deps: list[str] = ...,
    exported_platform_deps: list[(str, list[str])] = ...,
    exported_preprocessor_flags: list[str] = ...,
    import_libs: dict[str, str] = ...,
    include_dirs: list[str] = ...,
    include_in_android_merge_map_output: bool = ...,
    labels: list[str] = ...,
    licenses: list[str] = ...,
    provided_shared_libs: dict[str, str] = ...,
    shared_libs: dict[str, str] = ...,
    shared_link: list[str] = ...,
    static_libs: list[str] = ...,
    static_link: list[str] = ...,
    static_pic_libs: list[str] = ...,
    static_pic_link: list[str] = ...,
    supported_platforms_regex: None | str = ...,
    supports_shared_library_interface: bool = ...,
    version: None | str = ...,
) -> None

A prebuilt_cxx_library_group() rule represents a group of native libraries which should be handled together in a single rule, perhaps using special link-line construction.

Parameters​

  • name: name of the target
  • default_target_platform: specifies the default target platform, used when no platforms are specified on the command line
  • target_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • exec_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with an execution platform
  • visibility: a list of visibility patterns restricting what targets can depend on this one
  • within_view: a list of visibility patterns restricting what this target can depend on
  • metadata: a key-value map of metadata associated with this target
  • tests: a list of targets that provide tests for this one
  • modifiers: an array of modifiers associated with this target
  • 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. * When reexport_all_header_dependencies = False, only exported headers of the rules specified here are re-exported.
  • exported_platform_deps: Platform specific dependencies that will also appear to belong to any rules that depend on this one. These should be specified as a list of pairs where the first element is an un-anchored regex (in java.util.regex.Pattern syntax) against which the platform name is matched, and the second element is a list of external dependencies (same format as exported_deps) that are exported if the platform matches the regex. See exported_deps for more information.
  • provided_shared_libs: The map of system-provided shared library names to paths used when using the shared link style. The shared_link parameter should refer to these libs using their library name.
  • shared_libs: The map of shared library names to paths used when using the shared link style. The shared_link parameter should refer to these libs using their library name.
  • shared_link: The arguments to use when linking this library group using the shared link style. The actual paths to libraries should be listed in the shared_libs parameter, and referenced via the the $(lib [name]) macro (or the $(rel-lib [name]) macro, when the shared library should be linked using the -L[dir] -l[name] style) in these args.
  • static_libs: The paths to the libraries used when using the static link style. The static_link parameter should refer to these libs using their index number.
  • static_link: The arguments to use when linking this library group using the static link style. The actual paths to libraries should be listed in the static_libs parameter, and referenced via the the $(lib [index]) macro in these args.
  • static_pic_libs: The paths to the libraries used when using the static link style. The static_pic_link parameter should refer to these libs using their index number.
  • static_pic_link: The arguments to use when linking this library group using the static-pic link style. The actual paths to libraries should be listed in the static_pic_libs parameter, and referenced via the the $(lib [index]) macro in these args.
  • version: A string denoting a meaningful version of this rule that is optionally passed to the linker as extra metadata.

Details​

Examples:

A prebuilt library group wrapping two libraries that must be linked together.


prebuilt_cxx_library_group(
  name = 'util',
  static_link = [
    '-Wl,--start-group',
    '$(lib 0)',
    '$(lib 1)',
    '-Wl,--end-group',
  ],
  static_libs = [
    'lib/liba.a',
    'lib/libb.a',
  ],
  static_pic_link = [
    '-Wl,--start-group',
    '$(lib 0)',
    '$(lib 1)',
    '-Wl,--end-group',
  ],
  static_libs = [
    'lib/liba_pic.a',
    'lib/libb_pic.a',
  ],
  shared_link = [
    '$(rel-lib liba.so)',
    '$(rel-lib libb.so)',
  ],
  shared_libs = {
    'liba.so': 'lib/liba.so',
  },
  provided_shared_libs = {
    'libb.so': 'lib/libb.so',
  },
)

prebuilt_dotnet_library​

def prebuilt_dotnet_library(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    assembly: str,
    contacts: list[str] = ...,
    default_host_platform: None | str = ...,
    labels: list[str] = ...,
    licenses: list[str] = ...,
) -> None

A prebuilt_dotnet_library() rule is used to include prebuilt .Net assembles into your .Net code.

Parameters​

  • name: name of the target
  • default_target_platform: specifies the default target platform, used when no platforms are specified on the command line
  • target_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • exec_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with an execution platform
  • visibility: a list of visibility patterns restricting what targets can depend on this one
  • within_view: a list of visibility patterns restricting what this target can depend on
  • metadata: a key-value map of metadata associated with this target
  • tests: a list of targets that provide tests for this one
  • modifiers: an array of modifiers associated with this target
  • assembly: The path to the DLL that this rule provides.

Details​

Examples:


prebuilt_dotnet_library(
  name = 'log4net',
  assembly = 'log4net.dll',
)

csharp_library(
  name = 'example',
  srcs = [
    'Hello.cs',
  ],
  framework_ver = 'net46',
  deps = [
    ':log4net',
    'System.dll',
  ],
)

prebuilt_jar​

def prebuilt_jar(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    _build_only_native_code: bool = ...,
    _dex_min_sdk_version: None | int = ...,
    _dex_toolchain: str = ...,
    _exec_os_type: str = ...,
    _prebuilt_jar_toolchain: str = ...,
    binary_jar: str,
    contacts: list[str] = ...,
    default_host_platform: None | str = ...,
    deps: list[str] = ...,
    desugar_deps: list[str] = ...,
    generate_abi: bool = ...,
    is_executable: bool = ...,
    javadoc_url: None | str = ...,
    labels: list[str] = ...,
    licenses: list[str] = ...,
    maven_coords: None | str = ...,
    never_mark_as_unused_dependency: bool = ...,
    required_for_source_only_abi: bool = ...,
    source_jar: None | str = ...,
) -> None

A prebuilt_jar() rule is used to identify a JAR file that is checked into our repository as a precompiled binary rather than one that is built from source by Buck. Frequently, these are used to reference third-party JAR files (such as junit.jar) and are used as dependencies of java_library() rules.

Parameters​

  • name: name of the target
  • default_target_platform: specifies the default target platform, used when no platforms are specified on the command line
  • target_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • exec_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with an execution platform
  • visibility: a list of visibility patterns restricting what targets can depend on this one
  • within_view: a list of visibility patterns restricting what this target can depend on
  • metadata: a key-value map of metadata associated with this target
  • tests: a list of targets that provide tests for this one
  • modifiers: an array of modifiers associated with this target
  • binary_jar: Path to the pre-built JAR file.
  • deps: Rules that must be built before this rule. Because the binary_jar is already built, there should be nothing to build, so this should be empty.
  • javadoc_url: URL to the Javadoc for the .class files in the binary_jar.
  • source_jar: Path to a JAR file that contains the .java files to create the .class in the binary_jar. This is frequently provided for debugging purposes.

Details​

Examples:


prebuilt_jar(
  name = 'junit',
  binary_jar = 'junit-4.8.2.jar',
  source_jar = 'junit-4.8.2-sources.jar',
  javadoc_url = 'http://kentbeck.github.com/junit/javadoc/4.8/',
)

java_library(
  name = 'tests',
  srcs = glob(['tests/**/*Test.java']),
  deps = [
    ':junit',
  ],
)

prebuilt_native_library​

def prebuilt_native_library(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    contacts: list[str] = ...,
    default_host_platform: None | str = ...,
    deps: list[str] = ...,
    has_wrap_script: bool = ...,
    is_asset: bool = ...,
    labels: list[str] = ...,
    licenses: list[str] = ...,
    native_libs: str,
) -> None

A prebuilt_native_library() rule is used to bundle native libraries (i.e., .so files) for Android.

Parameters​

  • name: name of the target
  • default_target_platform: specifies the default target platform, used when no platforms are specified on the command line
  • target_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • exec_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with an execution platform
  • visibility: a list of visibility patterns restricting what targets can depend on this one
  • within_view: a list of visibility patterns restricting what this target can depend on
  • metadata: a key-value map of metadata associated with this target
  • tests: a list of targets that provide tests for this one
  • modifiers: an array of modifiers associated with this target
  • has_wrap_script: When using an exopackage, if this parameter is set to True, then the libraries for this rule are included in the primary APK even if native libraries would otherwise not be placed in it. This is intended for a native library directory that contains a wrap.sh script, which must be included in the primary APK to take effect. Only one of is_asset and has_wrap_script can be set for a rule.
  • is_asset: Normally native shared objects end up in a directory in the root of the APK named lib/. If this parameter is set to True, then these objects are placed in assets/lib/. Placing shared objects in a non-standard location prevents Android from extracting them to the device's internal storage.

Details​

Examples:

Most of the time, a prebuilt_native_library is private to the android_library() that uses it:


prebuilt_native_library(
  name = 'native_libs',
  native_libs = 'libs',
)

android_library(
  name = 'my_lib',
  srcs = glob(['*.java']),
  deps = [
    ':native_libs',
  ],
)

prebuilt_ocaml_library​

def prebuilt_ocaml_library(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    bytecode_c_libs: list[str] = ...,
    bytecode_lib: None | str = ...,
    bytecode_only: bool = ...,
    c_libs: list[str] = ...,
    contacts: list[str] = ...,
    default_host_platform: None | str = ...,
    deps: list[str] = ...,
    include_dir: None | str = ...,
    labels: list[str] = ...,
    lib_dir: str = ...,
    lib_name: str = ...,
    licenses: list[str] = ...,
    native_c_libs: list[str] = ...,
    native_lib: None | str = ...,
    platform_deps: list[(str, list[str])] = ...,
) -> None

Parameters​

  • name: name of the target
  • default_target_platform: specifies the default target platform, used when no platforms are specified on the command line
  • target_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • exec_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with an execution platform
  • visibility: a list of visibility patterns restricting what targets can depend on this one
  • within_view: a list of visibility patterns restricting what this target can depend on
  • metadata: a key-value map of metadata associated with this target
  • tests: a list of targets that provide tests for this one
  • modifiers: an array of modifiers associated with this target

prebuilt_python_library​

def prebuilt_python_library(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    _create_manifest_for_source_dir: str = ...,
    _create_third_party_build_root: str = ...,
    _extract: str = ...,
    _python_toolchain: str = ...,
    binary_src: str,
    compile: bool = ...,
    contacts: list[str] = ...,
    cxx_header_dirs: None | list[str] = ...,
    default_host_platform: None | str = ...,
    deps: list[str] = ...,
    exclude_deps_from_merged_linking: bool = ...,
    ignore_compile_errors: bool = ...,
    infer_cxx_header_dirs: bool = ...,
    labels: list[str] = ...,
    licenses: list[str] = ...,
    strip_soabi_tags: bool = ...,
) -> None

A prebuilt_python_library() rule is used to include prebuilt python packages into the output of a top-level python_binary() or python_test() rule.

Parameters​

  • name: name of the target

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

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

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

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

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

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

  • metadata: a key-value map of metadata associated with this target

  • tests: a list of targets that provide tests for this one

  • modifiers: an array of modifiers associated with this target

  • binary_src: The path to the .whl or .egg to use.

    Note: .egg files have a very particular naming convention that must be followed - otherwise it will not be found at runtime!

  • deps: Other prebuilt_python_library() rules which this library depends on. These may also be python_library rules if you want to depend on a source-based copy of the library.

  • exclude_deps_from_merged_linking: When linking the top-level binary with a merged .buckconfig, do not merge or re-link any native transitive deps of this library. This is useful if this library wraps prebuilt native extensions which cannot be re-linked as part of library merging.

  • labels: Set of arbitrary strings which allow you to annotate a build rule with tags that can be searched for over an entire dependency tree using buck query() .

  • strip_soabi_tags: Strip the SOABI tags from extensions in the prebuilt library.

    Note that this should be considered unsafe, as it removes builtin protections that fail fast when a potententially incompatible native extension is imported.

Details​

These prebuilt libraries can either be whl files or eggs

whls for most packages are available for download from PyPI. The whl used may be downloaded with remote_file(). However, Buck does not attempt to infer dependency information from pip, so that information will have to be imparted by the user.

To create an egg for a package, run python setup.py bdist_egg in the package source distribution.

Examples:


# A simple prebuilt_python_library with no external dependencies.
remote_file(
  name = "requests-download",
  url = "https://files.pythonhosted.org/packages/51/bd/23c926cd341ea6b7dd0b2a00aba99ae0f828be89d72b2190f27c11d4b7fb/requests-2.22.0-py2.py3-none-any.whl",
  sha1 = "e1fc28120002395fe1f2da9aacea4e15a449d9ee",
  out = "requests-2.22.0-py2.py3-none-any.whl",
)

prebuilt_python_library(
  name = "requests",
  binary_src = ":requests-download",
)

# A slightly more complex example
prebuilt_python_library(
  name = "greenlet",
  binary_src = "greenlet-0.4.7-py2.7-macosx-10.10-x86_64.egg",
)

prebuilt_python_library(
  name = "gevent",
  binary_src = "gevent-1.0.2-py2.7-macosx-10.10-x86_64.egg",
  deps = [
    ":greenlet",
  ],
)

python_binary​

def python_binary(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    _build_info: dict[str, typing.Any] = ...,
    _create_manifest_for_source_dir: str = ...,
    _cxx_hacks: str = ...,
    _cxx_toolchain: str = ...,
    _exec_os_type: str = ...,
    _package_remotely: bool = ...,
    _python_toolchain: str = ...,
    _target_os_type: str = ...,
    allow_cache_upload: None | bool = ...,
    anonymous_link_groups: bool = ...,
    auto_link_groups: bool = ...,
    base_module: None | str = ...,
    binary_linker_flags: list[str] = ...,
    bolt_flags: list[str] = ...,
    bolt_profile: None | str = ...,
    build_args: list[str] = ...,
    compile: None | bool = ...,
    compiler_flags: list[str] = ...,
    constraint_overrides: list[str] = ...,
    contacts: list[str] = ...,
    coverage_instrumentation_compiler_flags: list[str] = ...,
    cxx_main: str = ...,
    cxx_platform: None | str = ...,
    cxx_runtime_type: None | str = ...,
    deduplicate_merged_link_roots: None | bool = ...,
    default_host_platform: None | str = ...,
    default_platform: None | str = ...,
    defaults: dict[str, str] = ...,
    deps: list[str] = ...,
    deps_query: None | str = ...,
    devirt_enabled: bool = ...,
    distributed_thinlto_partial_split_dwarf: bool = ...,
    dummy_omnibus: None | str = ...,
    enable_distributed_thinlto: bool = ...,
    executable_deps: list[str] = ...,
    executable_name: None | str = ...,
    exported_needs_coverage_instrumentation: bool = ...,
    extension: None | str = ...,
    fat_lto: bool = ...,
    focused_list_target: None | str = ...,
    frameworks: list[str] = ...,
    header_namespace: None | str = ...,
    headers: list[str] | dict[str, str] = ...,
    headers_as_raw_headers_mode: None | str = ...,
    include_directories: list[str] = ...,
    inplace_build_args: list[str] = ...,
    labels: list[str] = ...,
    lang_compiler_flags: dict[str, list[str]] = ...,
    lang_platform_compiler_flags: dict[str, list[(str, list[str])]] = ...,
    lang_platform_preprocessor_flags: dict[str, list[(str, list[str])]] = ...,
    lang_preprocessor_flags: dict[str, list[str]] = ...,
    libraries: list[str] = ...,
    licenses: list[str] = ...,
    link_deps_query_whole: bool = ...,
    link_execution_preference: None | str = ...,
    link_group: None | str = ...,
    link_group_deps: list[str] = ...,
    link_group_map: None | str | list[(str, list[(None | str | list[None | str], str, None | str | list[str], None | str)], None | dict[str, typing.Any])] = ...,
    link_group_min_binary_node_count: None | int = ...,
    link_group_public_deps_label: None | str = ...,
    link_ordering: None | str = ...,
    link_style: str = ...,
    link_whole: bool = ...,
    linker_extra_outputs: list[str] = ...,
    linker_flags: list[str] = ...,
    main: None | str = ...,
    main_function: None | str = ...,
    main_module: None | str = ...,
    make_py_package: None | str = ...,
    manifest_module_entries: None | dict[str, list[str] | dict[str, typing.Any]] = ...,
    native_link_strategy: None | str = ...,
    package_split_dwarf_dwp: bool = ...,
    package_style: None | str = ...,
    par_style: None | str = ...,
    platform: None | str = ...,
    platform_compiler_flags: list[(str, list[str])] = ...,
    platform_deps: list[(str, list[str])] = ...,
    platform_headers: list[(str, list[str] | dict[str, str])] = ...,
    platform_linker_flags: list[(str, list[str])] = ...,
    platform_override: None | str = ...,
    platform_preload_deps: list[(str, list[str])] = ...,
    platform_preprocessor_flags: list[(str, list[str])] = ...,
    platform_srcs: list[(str, list[str | (str, list[str])])] = ...,
    post_linker_flags: list[str] = ...,
    post_platform_linker_flags: list[(str, list[str])] = ...,
    precompiled_header: None | str = ...,
    prefer_stripped_native_objects: bool = ...,
    prefer_stripped_objects: bool = ...,
    prefix_header: None | str = ...,
    preload_deps: list[str] = ...,
    preprocessor_flags: list[str] = ...,
    py_version_for_type_checking: None | str = ...,
    raw_headers: list[str] = ...,
    raw_headers_as_headers_mode: None | str = ...,
    repl_main: None | str = ...,
    repl_only_deps: list[str] = ...,
    resources: list[str] | dict[str, str] = ...,
    run_with_inplace: bool = ...,
    runtime_env: None | dict[str, str] = ...,
    separate_debug_info: bool = ...,
    shard_typing: None | bool = ...,
    standalone_build_args: list[str] = ...,
    standalone_extensions: None | bool = ...,
    static_extension_finder: str = ...,
    static_extension_utils: str = ...,
    strip_libpar: str = ...,
    strip_stapsdt: bool = ...,
    thin_lto: bool = ...,
    typing: bool = ...,
    use_header_units: bool = ...,
    version_universe: None | str = ...,
    weak_framework_names: list[str] = ...,
    zip_safe: None | bool = ...,
) -> None

A python_binary() rule is used to build an executable Python package that includes Python sources and resources from all transitive dependencies.

Parameters​

  • name: name of the target
  • default_target_platform: specifies the default target platform, used when no platforms are specified on the command line
  • target_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • exec_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with an execution platform
  • visibility: a list of visibility patterns restricting what targets can depend on this one
  • within_view: a list of visibility patterns restricting what this target can depend on
  • metadata: a key-value map of metadata associated with this target
  • tests: a list of targets that provide tests for this one
  • modifiers: an array of modifiers associated with this target
  • _build_info: Build info that is passed along here will be late-stamped into a fb_build_info section on the output binary
  • allow_cache_upload: Whether to allow uploading the output of this rule to be uploaded to cache when the action is executed locally if the configuration allows (i.e. there is a cache configured and the client has permission to write to it).
  • base_module: The package in which the main module should reside in its final location in the binary. If unset, Buck uses the project-relative directory that contains the BUCK file.
  • deduplicate_merged_link_roots: When linking multiple top-level binaries with the merged .buckconfig, coalesce root link rules which are identical across independent merged links.
  • deps: A list of python_library() rules that specify Python modules to include in the binary — including all transitive dependencies of these rules.
  • labels: Set of arbitrary strings which allow you to annotate a build rule with tags that can be searched for over an entire dependency tree using buck query() .
  • link_group_deps: Additional targets to traverse when building link groups, but which should not be direct dependencies of the main executable.
  • link_group_public_deps_label: Surface nodes with this label as "public" nodes in the main executable when linking with with link groups.
  • linker_flags: Additional linker flags that should be applied to any linking which is specific to this rule. Note that whether these flags are used is dependent on the native link strategy selected in .buckconfig and currently applies only to the merged .buckconfig; the separate link strategy pulls in shared libraries that are linked in the context of the rules that own them, such as cxx_library().
  • main: The Python file which serves as the entry point for the binary. The interpreter initiates execution of the binary with the code in this file.
  • main_function: Name of a Python function that will serve as the main entry point of the binary. The name is either a fully qualified name like foo.bar.baz or it starts with a . like .bar.baz, in which case it is relative to the package containing the target. This should usually be a function defined within one of the dependencies of this target. This attribute should be preferred over main_module or main, and it is an error to specify more than one of these.
  • main_module: The python module that should be the entry point of the binary. This should be a module name within a python_library that this binary depends on. Note that module names take base_module of the library into account. This property is mutually exclusive with main, and should be preferred to main, which is deprecated.
  • manifest_module_entries: If present, it should be a string -> entry mapping that gets generated into a __manifest__ module in the executable. Top level string keys will be the names of variables in this module (so they must be valid Python identifiers). An entry can be a list of strings, or a further string-keyed dictionary.
  • package_style: Used to override the global packaging style that is set in [.buckconfig ].
  • platform: The name of the Python platform flavor to build against by default as defined in the buckconfig#pythonsection of .buckconfig.
  • preload_deps: A list of C/C++ library dependencies that need to be loaded before any other libraries when the PEX starts up. This requires dynamic loader support, such as LD_PRELOAD, found on most systems. This list is order- sensitive and the preload libraries listed here are passed down to the dynamic linker in the same order.
  • py_version_for_type_checking: This option will force the type checker to perform checking under a specific version of Python interpreter.
  • shard_typing: Determines if sharding should be enabled on a given target.
  • typing: Determines whether to perform type checking on the given target. Default is False.

Details​

Examples:

Build an executable from the Python files in the BUCK directory.


# BUCK

python_binary(
  name = 'tailer',
  main_module = 'tailer',
  deps = [
    ':tailerutils',
  ],
)

python_library(
  name = 'tailerutils',
  # The main module, tailer.py, is specified here.
  # (Separated out from the glob pattern for clarity.)
  srcs = glob(['tailer.py', '*.py']),
)

python_bootstrap_binary​

def python_bootstrap_binary(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    _exec_os_type: str = ...,
    _python_bootstrap_toolchain: str = ...,
    _win_python_wrapper: None | str = ...,
    deps: list[str] = ...,
    main: str,
) -> None

Parameters​

  • name: name of the target
  • default_target_platform: specifies the default target platform, used when no platforms are specified on the command line
  • target_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • exec_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with an execution platform
  • visibility: a list of visibility patterns restricting what targets can depend on this one
  • within_view: a list of visibility patterns restricting what this target can depend on
  • metadata: a key-value map of metadata associated with this target
  • tests: a list of targets that provide tests for this one
  • modifiers: an array of modifiers associated with this target

python_bootstrap_library​

def python_bootstrap_library(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    deps: list[str] = ...,
    srcs: list[str],
) -> None

Parameters​

  • name: name of the target
  • default_target_platform: specifies the default target platform, used when no platforms are specified on the command line
  • target_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • exec_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with an execution platform
  • visibility: a list of visibility patterns restricting what targets can depend on this one
  • within_view: a list of visibility patterns restricting what this target can depend on
  • metadata: a key-value map of metadata associated with this target
  • tests: a list of targets that provide tests for this one
  • modifiers: an array of modifiers associated with this target

python_library​

def python_library(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    _create_manifest_for_source_dir: str = ...,
    _create_third_party_build_root: str = ...,
    _cxx_toolchain: str = ...,
    _python_toolchain: str = ...,
    base_module: None | str = ...,
    contacts: list[str] = ...,
    cxx_platform: None | str = ...,
    default_host_platform: None | str = ...,
    deps: list[str] = ...,
    exclude_deps_from_merged_linking: bool = ...,
    ignore_compile_errors: bool = ...,
    labels: list[str] = ...,
    licenses: list[str] = ...,
    platform: None | str = ...,
    platform_deps: list[(str, list[str])] = ...,
    platform_resources: list[(str, list[str] | dict[str, str])] = ...,
    platform_srcs: list[(str, list[str] | dict[str, str])] = ...,
    py_version_for_type_checking: None | str = ...,
    resources: list[str] | dict[str, str] = ...,
    shard_typing: None | bool = ...,
    srcs: list[str] | dict[str, str] = ...,
    type_stubs: list[str] | dict[str, str] = ...,
    typing: bool = ...,
    versioned_resources: None | list[(dict[str, str], list[str] | dict[str, str])] = ...,
    versioned_srcs: None | list[(dict[str, str], list[str] | dict[str, str])] = ...,
    zip_safe: None | bool = ...,
) -> None

A python_library() rule is used to group together Python source files and resources to be passed together in as a dep of other rules.

Parameters​

  • name: name of the target
  • default_target_platform: specifies the default target platform, used when no platforms are specified on the command line
  • target_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • exec_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with an execution platform
  • visibility: a list of visibility patterns restricting what targets can depend on this one
  • within_view: a list of visibility patterns restricting what this target can depend on
  • metadata: a key-value map of metadata associated with this target
  • tests: a list of targets that provide tests for this one
  • modifiers: an array of modifiers associated with this target
  • base_module: The package in which the specified source files and resources should reside in their final location in the top-level binary. If unset, Buck uses the project-relative directory that contains the BUCK file.
  • deps: Other python_library() rules that list srcs from which this rule imports modules.
  • exclude_deps_from_merged_linking: When linking the top-level binary with a merged .buckconfig, do not merge or re-link any native transitive deps of this library. This is useful if this library wraps prebuilt native extensions which cannot be re-linked as part of library merging.
  • labels: Set of arbitrary strings which allow you to annotate a build rule with tags that can be searched for over an entire dependency tree using buck query() .
  • platform_resources: Python-platform-specific resource files. These should be specified as a list of pairs where the first element in each pair is an un-anchored regex against which the platform name is matched, and the second element is a list of resource files. The regex should use java.util.regex.Pattern syntax. The platform name is a Python platform flavor defined in the buckconfig#python section of .buckconfig.
  • platform_srcs: Python-platform-specific source files. These should be specified as a list of pairs where the first element in each pair is an un-anchored regex against which the platform name is matched, and the second element is a list of source files. The regex should use java.util.regex.Pattern syntax. The platform name is a Python platform flavor defined in the buckconfig#python section of .buckconfig.
  • py_version_for_type_checking: This option will force the type checker to perform checking under a specific version of Python interpreter.
  • shard_typing: Determines if sharding should be enabled on a given target.
  • srcs: The set of Python (.py) files to include in this library.
  • typing: Determines whether to perform type checking on the given target. Default is False.

Details​

Examples:

Include Python source files and resource files.


# BUCK

# A rule that includes a single Python file.
python_library(
  name = 'fileutil',
  srcs = ['fileutil.py'],
  deps = [
    '//third_party/python-magic:python-magic',
  ],
)

# A rule that uses glob() to include all Python source files in the
# directory in which the rule is defined. The rule also specifies a
# resource file that gets packaged with the source file.
python_library(
  name = 'testutil',
  srcs = glob(['testutil/**/*.py']),
  resources = [
    'testdata.dat',
  ],
)

python_needed_coverage_test​

def python_needed_coverage_test(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    _inject_test_env: str = ...,
    _remote_test_execution_toolchain: str = ...,
    contacts: list[str] = ...,
    env: dict[str, str] = ...,
    labels: list[str] = ...,
    needed_coverage: list[(int, str, None | str)] = ...,
    remote_execution: None | str | dict[str, None | bool | int | str | list[dict[str, str]] | dict[str, str]] = ...,
    remote_execution_action_key_providers: None | str = ...,
    test: str,
) -> None

Parameters​

  • name: name of the target
  • default_target_platform: specifies the default target platform, used when no platforms are specified on the command line
  • target_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • exec_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with an execution platform
  • visibility: a list of visibility patterns restricting what targets can depend on this one
  • within_view: a list of visibility patterns restricting what this target can depend on
  • metadata: a key-value map of metadata associated with this target
  • tests: a list of targets that provide tests for this one
  • modifiers: an array of modifiers associated with this target

python_test​

def python_test(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    _build_info: dict[str, typing.Any] = ...,
    _create_manifest_for_source_dir: str = ...,
    _cxx_hacks: str = ...,
    _cxx_toolchain: str = ...,
    _exec_os_type: str = ...,
    _inject_test_env: str = ...,
    _python_toolchain: str = ...,
    _remote_test_execution_toolchain: str = ...,
    _target_os_type: str = ...,
    _test_main: str = ...,
    _test_toolchain: str = ...,
    additional_coverage_targets: list[str] = ...,
    anonymous_link_groups: bool = ...,
    auto_link_groups: bool = ...,
    base_module: None | str = ...,
    binary_linker_flags: list[str] = ...,
    bolt_flags: list[str] = ...,
    bolt_profile: None | str = ...,
    build_args: list[str] = ...,
    compile: None | bool = ...,
    compiler_flags: list[str] = ...,
    constraint_overrides: list[str] = ...,
    contacts: list[str] = ...,
    coverage_instrumentation_compiler_flags: list[str] = ...,
    cxx_main: str = ...,
    cxx_platform: None | str = ...,
    cxx_runtime_type: None | str = ...,
    deduplicate_merged_link_roots: None | bool = ...,
    default_host_platform: None | str = ...,
    default_platform: None | str = ...,
    defaults: dict[str, str] = ...,
    deps: list[str] = ...,
    deps_query: None | str = ...,
    devirt_enabled: bool = ...,
    distributed_thinlto_partial_split_dwarf: bool = ...,
    dummy_omnibus: None | str = ...,
    enable_distributed_thinlto: bool = ...,
    env: dict[str, str] = ...,
    exclude_deps_from_merged_linking: bool = ...,
    executable_deps: list[str] = ...,
    executable_name: None | str = ...,
    exported_needs_coverage_instrumentation: bool = ...,
    extension: None | str = ...,
    fat_lto: bool = ...,
    focused_list_target: None | str = ...,
    frameworks: list[str] = ...,
    header_namespace: None | str = ...,
    headers: list[str] | dict[str, str] = ...,
    headers_as_raw_headers_mode: None | str = ...,
    implicit_test_library: None | str = ...,
    include_directories: list[str] = ...,
    inplace_build_args: list[str] = ...,
    labels: list[str] = ...,
    lang_compiler_flags: dict[str, list[str]] = ...,
    lang_platform_compiler_flags: dict[str, list[(str, list[str])]] = ...,
    lang_platform_preprocessor_flags: dict[str, list[(str, list[str])]] = ...,
    lang_preprocessor_flags: dict[str, list[str]] = ...,
    libraries: list[str] = ...,
    licenses: list[str] = ...,
    link_deps_query_whole: bool = ...,
    link_execution_preference: None | str = ...,
    link_group: None | str = ...,
    link_group_deps: list[str] = ...,
    link_group_map: None | str | list[(str, list[(None | str | list[None | str], str, None | str | list[str], None | str)], None | dict[str, typing.Any])] = ...,
    link_group_min_binary_node_count: None | int = ...,
    link_group_public_deps_label: None | str = ...,
    link_ordering: None | str = ...,
    link_style: str = ...,
    link_whole: bool = ...,
    linker_extra_outputs: list[str] = ...,
    linker_flags: list[str] = ...,
    main_function: None | str = ...,
    main_module: None | str = ...,
    make_py_package: None | str = ...,
    manifest_module_entries: None | dict[str, list[str] | dict[str, typing.Any]] = ...,
    native_link_strategy: None | str = ...,
    needed_coverage: list[(int, str, None | str)] = ...,
    package_split_dwarf_dwp: bool = ...,
    package_style: None | str = ...,
    par_style: None | str = ...,
    platform: None | str = ...,
    platform_compiler_flags: list[(str, list[str])] = ...,
    platform_deps: list[(str, list[str])] = ...,
    platform_headers: list[(str, list[str] | dict[str, str])] = ...,
    platform_linker_flags: list[(str, list[str])] = ...,
    platform_override: None | str = ...,
    platform_preload_deps: list[(str, list[str])] = ...,
    platform_preprocessor_flags: list[(str, list[str])] = ...,
    platform_resources: list[(str, list[str] | dict[str, str])] = ...,
    platform_srcs: list[(str, list[str | (str, list[str])])] = ...,
    post_linker_flags: list[str] = ...,
    post_platform_linker_flags: list[(str, list[str])] = ...,
    precompiled_header: None | str = ...,
    prefer_stripped_native_objects: bool = ...,
    prefer_stripped_objects: bool = ...,
    prefix_header: None | str = ...,
    preload_deps: list[str] = ...,
    preprocessor_flags: list[str] = ...,
    py_version_for_type_checking: None | str = ...,
    raw_headers: list[str] = ...,
    raw_headers_as_headers_mode: None | str = ...,
    remote_execution: None | str | dict[str, None | bool | int | str | list[dict[str, str]] | dict[str, str]] = ...,
    remote_execution_action_key_providers: None | str = ...,
    repl_main: None | str = ...,
    repl_only_deps: list[str] = ...,
    resources: list[str] | dict[str, str] = ...,
    run_with_inplace: bool = ...,
    runner: None | str = ...,
    runtime_env: None | dict[str, str] = ...,
    separate_debug_info: bool = ...,
    shard_typing: None | bool = ...,
    specs: None | str = ...,
    srcs: list[str] | dict[str, str] = ...,
    standalone_build_args: list[str] = ...,
    standalone_extensions: None | bool = ...,
    static_extension_finder: str = ...,
    static_extension_utils: str = ...,
    strip_libpar: str = ...,
    strip_stapsdt: bool = ...,
    test_rule_timeout_ms: None | int = ...,
    thin_lto: bool = ...,
    typing: bool = ...,
    use_header_units: bool = ...,
    version_universe: None | str = ...,
    versioned_resources: None | list[(dict[str, str], list[str] | dict[str, str])] = ...,
    versioned_srcs: None | list[(dict[str, str], list[str] | dict[str, str])] = ...,
    weak_framework_names: list[str] = ...,
    zip_safe: None | bool = ...,
) -> None

A python_test() rule defines a set of .py files that contain tests to run via the Python unit testing framework.

Parameters​

  • name: name of the target

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

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

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

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

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

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

  • metadata: a key-value map of metadata associated with this target

  • tests: a list of targets that provide tests for this one

  • modifiers: an array of modifiers associated with this target

  • _build_info: Build info that is passed along here will be late-stamped into a fb_build_info section on the output binary

  • base_module: The package in which the specified source files and resources should reside in their final location in the top-level binary. If unset, Buck uses the project-relative directory that contains the BUCK file.

  • deduplicate_merged_link_roots: When linking multiple top-level binaries with the merged .buckconfig, coalesce root link rules which are identical across independent merged links.

  • deps: other rules used by the tests in this rule's sources.

  • env: A map of environment names and values to set when running the test.

    It is also possible to expand references to other rules within the values of these environment variables, using builtin string parameter macros :

    $(location //path/to:target) Expands to the location of the output of the build rule. This means that you can refer to these without needing to be aware of how Buck is storing data on the disk mid-build.

  • exclude_deps_from_merged_linking: When linking the top-level binary with a merged .buckconfig, do not merge or re-link any native transitive deps of this library. This is useful if this library wraps prebuilt native extensions which cannot be re-linked as part of library merging.

  • labels: Set of arbitrary strings which allow you to annotate a build rule with tags that can be searched for over an entire dependency tree using buck query() .

  • link_group_deps: Additional targets to traverse when building link groups, but which should not be direct dependencies of the main executable.

  • link_group_public_deps_label: Surface nodes with this label as "public" nodes in the main executable when linking with with link groups.

  • linker_flags: Additional linker flags that should be applied to any linking which is specific to this rule. Note that whether these flags are used is dependent on the native link strategy selected in .buckconfig and currently applies only to the merged .buckconfig; the separate link strategy pulls in shared libraries that are linked in the context of the rules that own them, such as cxx_library().

  • main_function: Name of a Python function that will serve as the main entry point of the binary. The name is either a fully qualified name like foo.bar.baz or it starts with a . like .bar.baz, in which case it is relative to the package containing the target. This should usually be a function defined within one of the dependencies of this target. This attribute should be preferred over main_module or main, and it is an error to specify more than one of these.

  • main_module: The main module used to run the tests. This parameter is normally not needed, as Buck will provide a default main module that runs all tests. However, you can override this with your own module to perform custom initialization or command line processing. Your custom module can import the standard Buck test main as __test_main__, and can invoke it's normal main function as __test_main__.main(sys.argv).

  • manifest_module_entries: If present, it should be a string -> entry mapping that gets generated into a __manifest__ module in the executable. Top level string keys will be the names of variables in this module (so they must be valid Python identifiers). An entry can be a list of strings, or a further string-keyed dictionary.

  • package_style: Used to override the global packaging style that is set in [.buckconfig ].

  • platform: The name of the Python platform flavor to build against by default as defined in the buckconfig#pythonsection of .buckconfig.

  • platform_resources: Python-platform-specific resource files. These should be specified as a list of pairs where the first element in each pair is an un-anchored regex against which the platform name is matched, and the second element is a list of resource files. The regex should use java.util.regex.Pattern syntax. The platform name is a Python platform flavor defined in the buckconfig#python section of .buckconfig.

  • preload_deps: A list of C/C++ library dependencies that need to be loaded before any other libraries when the PEX starts up. This requires dynamic loader support, such as LD_PRELOAD, found on most systems. This list is order- sensitive and the preload libraries listed here are passed down to the dynamic linker in the same order.

  • py_version_for_type_checking: This option will force the type checker to perform checking under a specific version of Python interpreter.

  • shard_typing: Determines if sharding should be enabled on a given target.

  • srcs: The set of Python (.py) files to include in this library.

  • test_rule_timeout_ms: If set specifies the maximum amount of time (in milliseconds) in which all of the tests in this rule should complete. This overrides the default rule_timeout if any has been specified in .buckconfig .

  • typing: Determines whether to perform type checking on the given target. Default is False.

Details​

If your test requires static files you should specify these in the resources or platform_resources arguments. If you do not specify these files, they won't be available when your test runs.

Examples:


# A rule that includes a single .py file containing tests.
python_test(
  name = 'fileutil_test',
  srcs = ['fileutil_tests.py'],
  deps = [
    ':fileutil',
  ],
)

# A rule that uses glob() to include all sources in the directory which the
# rule is defined.  It also lists a resource file that gets packaged with
# the sources in this rule.
python_library(
  name = 'fileutil',
  srcs = glob(['fileutil/**/*.py']),
  resources = [
    'testdata.dat',
  ],
)

python_test_runner​

def python_test_runner(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    contacts: list[str] = ...,
    default_host_platform: None | str = ...,
    labels: list[str] = ...,
    licenses: list[str] = ...,
    main_module: str = ...,
    src: str,
) -> None

Parameters​

  • name: name of the target
  • default_target_platform: specifies the default target platform, used when no platforms are specified on the command line
  • target_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • exec_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with an execution platform
  • visibility: a list of visibility patterns restricting what targets can depend on this one
  • within_view: a list of visibility patterns restricting what this target can depend on
  • metadata: a key-value map of metadata associated with this target
  • tests: a list of targets that provide tests for this one
  • modifiers: an array of modifiers associated with this target
  • labels: Set of arbitrary strings which allow you to annotate a build rule with tags that can be searched for over an entire dependency tree using buck query() .

remote_file​

def remote_file(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    _unzip_tool: str = ...,
    contacts: list[str] = ...,
    default_host_platform: None | str = ...,
    labels: list[str] = ...,
    licenses: list[str] = ...,
    out: None | str = ...,
    sha1: None | str = ...,
    sha256: None | str = ...,
    type: None | str = ...,
    url: str,
    vpnless_url: None | str = ...,
) -> None

A remote_file() rule is used to download files from the Internet to be used as dependencies for other rules. These rules are downloaded by running fetch, or can be downloaded as part of build. See the note there about the .buckconfig setting to configure that.

Parameters​

  • name: name of the target

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

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

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

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

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

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

  • metadata: a key-value map of metadata associated with this target

  • tests: a list of targets that provide tests for this one

  • modifiers: an array of modifiers associated with this target

  • out: An optional name to call the downloaded artifact. Buck will generate a default name if one is not provided that uses the name of the rule.

  • type: An optional type of the downloaded file.

    data Regular data file. executable

    Executable file. Buck will ensure that output has appropriate permissions if applicable.

    exploded_zip

    Zip archive which will be automatically unzipped into an output directory.

  • url: You can specify an http, https, or a mvn URL. If you specify a mvn URL, it will be decoded as described in the javadocs for MavenUrlDecoder See the example section below.

  • vpnless_url: An optional additional URL from which this resource can be downloaded when off VPN. Meta-internal only.

Details​

Examples:

Here's an example of a remote_file() using an https URL.


remote_file(
  name = 'android-ndk-r10e-darwin-x86_64',
  url = 'https://dl.google.com/android/ndk/android-ndk-r10e-darwin-x86_64.bin',
  sha1 = 'b57c2b9213251180dcab794352bfc9a241bf2557',
)

Here's an example of a remote_file() using a mvn URL being referenced by a prebuilt_jar().


prebuilt_jar(
  name = 'jetty-all',
  binary_jar = 'jetty-all-9.2.10.v20150310.jar',
  source_jar = ':jetty-source',
)

remote_file(
  name = 'jetty-source',
  out = 'jetty-all-9.2.10.v20150310-sources.jar',
  url = 'mvn:org.eclipse.jetty.aggregate:jetty-all:src:9.2.10.v20150310',
  sha1 = '311da310416d2feb3de227081d7c3f48742d7075',
)

Here's an example of a remote_file() using a mvn URI which uses a non-default maven repository host.


remote_file(
  name = 'jetty-source',
  out = 'jetty-all-9.2.10.v20150310-sources.jar',
  url = 'mvn:https://maven-repo.com:org.eclipse.jetty.aggregate:jetty-all:src:9.2.10.v20150310',
  sha1 = '311da310416d2feb3de227081d7c3f48742d7075',
)

Here's an example of a remote_file() using a mvn URI which uses a Maven classifier.


remote_file(
  name = 'groovy-groovysh-indy',
  out = 'jetty-all-9.2.10.v20150310-sources.jar',
  url = 'mvn:org.codehaus.groovy:groovy-groovysh:jar:indy:2.4.1',
  sha1 = '1600fde728c885cc9506cb102deb1b494bd7c130',
)

robolectric_test​

def robolectric_test(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _android_toolchain: str = ...,
    _apple_platforms: dict[str, str] = ...,
    _build_only_native_code: bool = ...,
    _exec_os_type: str = ...,
    _inject_test_env: str = ...,
    _is_building_android_binary: bool = ...,
    _java_test_toolchain: str = ...,
    _java_toolchain: str = ...,
    _kotlin_toolchain: str = ...,
    _remote_test_execution_toolchain: str = ...,
    _test_toolchain: str = ...,
    abi_generation_mode: None | str = ...,
    android_optional_jars: None | list[str] = ...,
    annotation_processing_tool: None | str = ...,
    annotation_processor_deps: list[str] = ...,
    annotation_processor_params: list[str] = ...,
    annotation_processors: list[str] = ...,
    contacts: list[str] = ...,
    cxx_library_whitelist: list[str] = ...,
    default_cxx_platform: None | str = ...,
    default_host_platform: None | str = ...,
    deps: list[str] = ...,
    enable_used_classes: bool = ...,
    env: dict[str, str] = ...,
    exported_deps: list[str] = ...,
    exported_provided_deps: list[str] = ...,
    extra_arguments: list[str] = ...,
    extra_kotlinc_arguments: list[str] = ...,
    fork_mode: str = ...,
    friend_paths: list[str] = ...,
    incremental: bool = ...,
    jar_postprocessor: None | str = ...,
    java: None | str = ...,
    java_agents: list[str] = ...,
    java_version: None | str = ...,
    javac: None | str = ...,
    k2: bool = ...,
    kotlin_compiler_plugins: dict[str, dict[str, str]] = ...,
    labels: list[str] = ...,
    language: None | str = ...,
    licenses: list[str] = ...,
    locales_for_binary_resources: list[str] = ...,
    manifest: None | str = ...,
    manifest_entries: dict[str, typing.Any] = ...,
    manifest_file: None | str = ...,
    maven_coords: None | str = ...,
    never_mark_as_unused_dependency: None | bool = ...,
    on_unused_dependencies: None | str = ...,
    plugins: list[str | (str, list[str])] = ...,
    preferred_density_for_binary_resources: None | str = ...,
    proguard_config: None | str = ...,
    provided_deps: list[str] = ...,
    provided_deps_query: None | str = ...,
    remote_execution: None | str | dict[str, None | bool | int | str | list[dict[str, str]] | dict[str, str]] = ...,
    remote_execution_action_key_providers: None | str = ...,
    remove_classes: list[str] = ...,
    required_for_source_only_abi: bool = ...,
    resource_stable_ids: None | str = ...,
    resource_union_package: None | str = ...,
    resources: list[str] = ...,
    resources_root: None | str = ...,
    robolectric_runtime_dependencies: list[str] = ...,
    robolectric_runtime_dependency: None | str = ...,
    run_test_separately: bool = ...,
    runtime_deps: list[str] = ...,
    source: None | str = ...,
    source_abi_verification_mode: None | str = ...,
    source_only_abi_deps: list[str] = ...,
    srcs: list[str] = ...,
    std_err_log_level: None | int | str = ...,
    std_out_log_level: None | int | str = ...,
    target: None | str = ...,
    test_case_timeout_ms: None | int = ...,
    test_class_names_file: None | str = ...,
    test_rule_timeout_ms: None | int = ...,
    test_type: None | str = ...,
    unbundled_resources_root: None | str = ...,
    use_cxx_libraries: None | bool = ...,
    use_dependency_order_classpath: None | bool = ...,
    use_jvm_abi_gen: None | bool = ...,
    used_as_dependency_deprecated_do_not_use: bool = ...,
    vm_args: list[str] = ...,
) -> None

A robolectric_test() rule is used to define a set of .java files that contain tests to run via JUnit with Robolectric test runner. It extends from java_test() rule.

Parameters​

  • name: name of the target

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

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

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

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

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

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

  • metadata: a key-value map of metadata associated with this target

  • tests: a list of targets that provide tests for this one

  • modifiers: an array of modifiers associated with this target

  • enable_used_classes: Deprecated: for an experiment only, will be removed

  • extra_kotlinc_arguments: List of additional arguments to pass into the Kotlin compiler.

  • incremental: Enables Kotlin incremental compilation.

  • javac: Specifies the Java compiler program to use for this rule. The value is a source path or an execution dep (e.g., //foo/bar:bar). Overrides the value in "javac" in the "tools" section of .buckconfig.

  • k2: Enables the Kotlin K2 compiler.

  • kotlin_compiler_plugins: Use this to specify Kotlin compiler plugins to use when compiling this library. This takes a map, with each entry specify one plugin. Entry's key is plugin source path, and value is a map of plugin option key value pair. Unlike extra_kotlinc_arguments, these can be source paths, not just strings.

    A special option value is __codegen_dir__, in which case Buck will provide a default codegen folder's path as option value instead. E.g.

    fbcode/buck2/prelude/decls/jvm_common.bzl
    kotlin_compiler_plugins = {
        "somePluginSourcePath": {
            "plugin:somePluginId:somePluginOptionKey": "somePluginOptionValue",
            "plugin:somePluginId:someDirectoryRelatedOptionKey": "__codegen_dir__",
        },
    },

    Each plugin source path will be prefixed with -Xplugin= and passed as extra arguments to the compiler. Plugin options will be appended after its plugin with -P.

    A specific example is, if you want to use kotlinx.serialization with kotlin_library(), you need to specify kotlinx-serialization-compiler-plugin.jar under kotlin_compiler_plugins and kotlinx-serialization-runtime.jar (which you may have to fetch from Maven) in your deps:


    kotlin_library(
        name = "example",
        srcs = glob(["*.kt"]),
        deps = [
            ":kotlinx-serialization-runtime",
        ],
        kotlin_compiler_plugins = {
            # Likely copied from your $KOTLIN_HOME directory.
            "kotlinx-serialization-compiler-plugin.jar": {},
        },
    )

    prebuilt_jar(
        name = "kotlinx-serialization-runtime",
        binary_jar = ":kotlinx-serialization-runtime-0.10.0",
    )

    # Note you probably want to set
    # maven_repo=http://jcenter.bintray.com/ in your .buckconfig until
    # https://github.com/Kotlin/kotlinx.serialization/issues/64
    # is closed.
    remote_file(
        name = "kotlinx-serialization-runtime-0.10.0",
        out = "kotlinx-serialization-runtime-0.10.0.jar",
        url = "mvn:org.jetbrains.kotlinx:kotlinx-serialization-runtime:jar:0.10.0",
        sha1 = "23d777a5282c1957c7ce35946374fff0adab114c"
    )

  • 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 an android_manifest() target.

  • robolectric_runtime_dependency: Robolectric only runs in offline mode with buck. Specify the relative directory containing all the jars Robolectric uses at runtime.

rust_binary​

def rust_binary(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    _cxx_toolchain: str = ...,
    _exec_os_type: str = ...,
    _rust_toolchain: str = ...,
    _target_os_type: str = ...,
    _workspaces: list[str] = ...,
    allow_cache_upload: None | bool = ...,
    anonymous_link_groups: bool = ...,
    auto_link_groups: bool = ...,
    clippy_configuration: None | str = ...,
    contacts: list[str] = ...,
    coverage: bool = ...,
    crate: None | str = ...,
    crate_root: None | str = ...,
    default_host_platform: None | str = ...,
    default_platform: None | str = ...,
    deps: list[str] = ...,
    edition: None | str = ...,
    enable_distributed_thinlto: bool = ...,
    env: dict[str, str] = ...,
    features: list[str] = ...,
    flagged_deps: list[(str, list[str])] = ...,
    incremental_build_mode: None | str = ...,
    incremental_enabled: bool = ...,
    labels: list[str] = ...,
    licenses: list[str] = ...,
    link_group: None | str = ...,
    link_group_map: None | str | list[(str, list[(None | str | list[None | str], str, None | str | list[str], None | str)], None | dict[str, typing.Any])] = ...,
    link_group_min_binary_node_count: None | int = ...,
    link_style: None | str = ...,
    linker_flags: list[str] = ...,
    mapped_srcs: dict[str, str] = ...,
    named_deps: list[(str, str)] | dict[str, str] = ...,
    resources: list[str] | dict[str, str] = ...,
    rpath: bool = ...,
    rustc_flags: list[str] = ...,
    rustdoc_flags: list[str] = ...,
    separate_debug_info: bool = ...,
    srcs: list[str] = ...,
) -> None

A rust_binary() rule builds a native executable from the supplied set of Rust source files and dependencies.

Parameters​

  • name: name of the target

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

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

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

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

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

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

  • metadata: a key-value map of metadata associated with this target

  • tests: a list of targets that provide tests for this one

  • modifiers: an array of modifiers associated with this target

  • _workspaces: Internal implementation detail of Rust workspaces. This should not be set manually and will be replaced in favor of metadata in a future version of buck2.

  • allow_cache_upload: Whether to allow uploading the output of this rule to be uploaded to cache when the action is executed locally if the configuration allows (i.e. there is a cache configured and the client has permission to write to it).

  • crate_root: Set the name of the top-level source file for the crate, which can be used to override the default (see srcs).

  • deps: The set of dependencies of this rule. Currently, this supports rust_library and prebuilt_rust_library rules.

  • edition: Set the language edition to be used for this rule. Can be set to any edition the compiler supports (2018 right now). If unset it uses the compiler's default (2015).

  • env: Set environment variables for this rule's invocations of rustc. The environment variable values may include macros which are expanded.

  • features: The set of features to be enabled for this rule.

    These are passed to rustc with --cfg feature="{feature}", and can be used in the code with #[cfg(feature = "{feature}")].

  • link_style: Determines whether to build and link this rule's dependencies statically or dynamically. Can be either static, static_pic or shared.

  • linker_flags: The set of additional flags to pass to the linker.

  • mapped_srcs: Add source files along with a local path mapping. Rust is sensitive to the layout of source files, as the directory structure follows the module structure. However this is awkward if the source file is, for example, generated by another rule. In this case, you can set up a mapping from the actual source path to something that makes sense locally. For example mapped_srcs = {":generate-module", "src/generated.rs" }. These are added to the regular srcs, so a file should not be listed in both.

  • named_deps: Add crate dependencies and define a local name by which to use that dependency by. This allows a crate to have multiple dependencies with the same crate name. For example: named_deps = {"local_name", ":some_rust_crate" }. The dependencies may also be non-Rust, but the alias is ignored. It has no effect on the symbols provided by a C/C++ library.

  • rpath: Set the "rpath" in the executable when using a shared link style.

  • rustc_flags: The set of additional compiler flags to pass to rustc.

  • srcs: The set of Rust source files to be compiled by this rule.

    One of the source files is the root module of the crate. By default this is lib.rs for libraries, main.rs for executables, or the crate's name with .rs appended. This can be overridden with the crate_root rule parameter.

Details​

If you invoke a build with the check flavor, then Buck will invoke rustc to check the code (typecheck, produce warnings, etc), but won't generate an executable code. When applied to binaries it produces no output; for libraries it produces metadata for consumers of the library.

Note: Buck is currently tested with (and therefore supports) version 1.32.0 of Rust.

Examples:

For more examples, check out our integration tests.


rust_binary(
  name='greet',
  srcs=[
    'greet.rs',
  ],
  deps=[
    ':greeting',
  ],
)

rust_library(
  name='greeting',
  srcs=[
    'greeting.rs',
  ],
  deps=[
    ':join',
  ],
)

rust_library(
  name='join',
  srcs=[
    'join.rs',
  ],
)

rust_library​

def rust_library(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    _cxx_toolchain: str = ...,
    _exec_os_type: str = ...,
    _rust_toolchain: str = ...,
    _target_os_type: str = ...,
    _workspaces: list[str] = ...,
    clippy_configuration: None | str = ...,
    contacts: list[str] = ...,
    coverage: bool = ...,
    crate: None | str = ...,
    crate_dynamic: None | str = ...,
    crate_root: None | str = ...,
    default_host_platform: None | str = ...,
    default_platform: None | str = ...,
    deps: list[str] = ...,
    doc_deps: list[str] = ...,
    doc_env: dict[str, str] = ...,
    doc_link_style: None | str = ...,
    doc_linker_flags: list[str] = ...,
    doc_named_deps: list[(str, str)] | dict[str, str] = ...,
    doctests: None | bool = ...,
    edition: None | str = ...,
    env: dict[str, str] = ...,
    exported_linker_flags: list[str] = ...,
    exported_post_linker_flags: list[str] = ...,
    features: list[str] = ...,
    flagged_deps: list[(str, list[str])] = ...,
    incremental_build_mode: None | str = ...,
    incremental_enabled: bool = ...,
    labels: list[str] = ...,
    licenses: list[str] = ...,
    link_style: None | str = ...,
    linker_flags: list[str] = ...,
    mapped_srcs: dict[str, str] = ...,
    named_deps: list[(str, str)] | dict[str, str] = ...,
    preferred_linkage: str = ...,
    proc_macro: bool = ...,
    resources: list[str] | dict[str, str] = ...,
    rustc_flags: list[str] = ...,
    rustdoc_flags: list[str] = ...,
    separate_debug_info: bool = ...,
    soname: None | str = ...,
    srcs: list[str] = ...,
    supports_python_dlopen: None | bool = ...,
) -> None

A rust_library() rule builds a native library from the supplied set of Rust source files and dependencies.

Parameters​

  • name: name of the target

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

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

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

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

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

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

  • metadata: a key-value map of metadata associated with this target

  • tests: a list of targets that provide tests for this one

  • modifiers: an array of modifiers associated with this target

  • _workspaces: Internal implementation detail of Rust workspaces. This should not be set manually and will be replaced in favor of metadata in a future version of buck2.

  • crate_root: Set the name of the top-level source file for the crate, which can be used to override the default (see srcs).

  • deps: The set of dependencies of this rule. Currently, this supports rust_library and prebuilt_rust_library rules.

  • doc_deps: The set of dependencies of this rule. Currently, this supports rust_library and prebuilt_rust_library rules.

  • doc_env: Set environment variables for this rule's invocations of rustc. The environment variable values may include macros which are expanded.

  • doc_link_style: Determines whether to build and link this rule's dependencies statically or dynamically. Can be either static, static_pic or shared.

  • doc_linker_flags: The set of additional flags to pass to the linker.

  • doc_named_deps: Add crate dependencies and define a local name by which to use that dependency by. This allows a crate to have multiple dependencies with the same crate name. For example: named_deps = {"local_name", ":some_rust_crate" }. The dependencies may also be non-Rust, but the alias is ignored. It has no effect on the symbols provided by a C/C++ library.

  • edition: Set the language edition to be used for this rule. Can be set to any edition the compiler supports (2018 right now). If unset it uses the compiler's default (2015).

  • env: Set environment variables for this rule's invocations of rustc. The environment variable values may include macros which are expanded.

  • exported_linker_flags: A set of additional flag to pass before this item on the link line, even if this items is compiled to a DSO.

  • exported_post_linker_flags: A set of additional flag to pass after this item on the link line, even if this items is compiled to a DSO.

  • features: The set of features to be enabled for this rule.

    These are passed to rustc with --cfg feature="{feature}", and can be used in the code with #[cfg(feature = "{feature}")].

  • link_style: Determines whether to build and link this rule's dependencies statically or dynamically. Can be either static, static_pic or shared.

  • linker_flags: The set of additional flags to pass to the linker.

  • mapped_srcs: Add source files along with a local path mapping. Rust is sensitive to the layout of source files, as the directory structure follows the module structure. However this is awkward if the source file is, for example, generated by another rule. In this case, you can set up a mapping from the actual source path to something that makes sense locally. For example mapped_srcs = {":generate-module", "src/generated.rs" }. These are added to the regular srcs, so a file should not be listed in both.

  • named_deps: Add crate dependencies and define a local name by which to use that dependency by. This allows a crate to have multiple dependencies with the same crate name. For example: named_deps = {"local_name", ":some_rust_crate" }. The dependencies may also be non-Rust, but the alias is ignored. It has no effect on the symbols provided by a C/C++ library.

  • rustc_flags: The set of additional compiler flags to pass to rustc.

  • soname: Sets the soname ("shared object name") of any shared library produced from this rule. The default value is based on the full rule name. The macro $(ext) will be replaced with a platform-appropriate extension. An argument can be provided, which is a library version. For example soname = 'libfoo.$(ext 2.3)' will be libfoo.2.3.dylib on Mac and libfoo.so.2.3 on Linux.

  • srcs: The set of Rust source files to be compiled by this rule.

    One of the source files is the root module of the crate. By default this is lib.rs for libraries, main.rs for executables, or the crate's name with .rs appended. This can be overridden with the crate_root rule parameter.

Details​

If you invoke a build with the check flavor, then Buck will invoke rustc to check the code (typecheck, produce warnings, etc), but won't generate an executable code. When applied to binaries it produces no output; for libraries it produces metadata for consumers of the library.

Note: Buck is currently tested with (and therefore supports) version 1.32.0 of Rust.

Examples:

For more examples, check out our integration tests.


rust_library(
  name='greeting',
  srcs=[
    'greeting.rs',
  ],
  deps=[
    ':join',
  ],
)

rust_test​

def rust_test(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    _cxx_toolchain: str = ...,
    _exec_os_type: str = ...,
    _inject_test_env: str = ...,
    _remote_test_execution_toolchain: str = ...,
    _rust_toolchain: str = ...,
    _target_os_type: str = ...,
    _test_toolchain: str = ...,
    _workspaces: list[str] = ...,
    anonymous_link_groups: bool = ...,
    auto_link_groups: bool = ...,
    clippy_configuration: None | str = ...,
    contacts: list[str] = ...,
    coverage: bool = ...,
    crate: None | str = ...,
    crate_root: None | str = ...,
    default_host_platform: None | str = ...,
    default_platform: None | str = ...,
    default_roots: None | list[str] = ...,
    deps: list[str] = ...,
    edition: None | str = ...,
    enable_distributed_thinlto: bool = ...,
    env: dict[str, str] = ...,
    features: list[str] = ...,
    flagged_deps: list[(str, list[str])] = ...,
    framework: bool = ...,
    incremental_build_mode: None | str = ...,
    incremental_enabled: bool = ...,
    labels: list[str] = ...,
    licenses: list[str] = ...,
    link_group: None | str = ...,
    link_group_map: None | str | list[(str, list[(None | str | list[None | str], str, None | str | list[str], None | str)], None | dict[str, typing.Any])] = ...,
    link_group_min_binary_node_count: None | int = ...,
    link_style: None | str = ...,
    linker_flags: list[str] = ...,
    mapped_srcs: dict[str, str] = ...,
    named_deps: list[(str, str)] | dict[str, str] = ...,
    remote_execution: None | str | dict[str, None | bool | int | str | list[dict[str, str]] | dict[str, str]] = ...,
    remote_execution_action_key_providers: None | str = ...,
    resources: list[str] | dict[str, str] = ...,
    rpath: bool = ...,
    run_env: dict[str, str] = ...,
    rustc_flags: list[str] = ...,
    rustdoc_flags: list[str] = ...,
    separate_debug_info: bool = ...,
    srcs: list[str] = ...,
) -> None

A rust_test() rule builds a Rust test native executable from the supplied set of Rust source files and dependencies and runs this test.

Parameters​

  • name: name of the target

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

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

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

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

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

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

  • metadata: a key-value map of metadata associated with this target

  • tests: a list of targets that provide tests for this one

  • modifiers: an array of modifiers associated with this target

  • _workspaces: Internal implementation detail of Rust workspaces. This should not be set manually and will be replaced in favor of metadata in a future version of buck2.

  • crate_root: Set the name of the top-level source file for the crate, which can be used to override the default (see srcs).

  • default_roots: Set the candidate source names to consider for crate root. Typically used to disambiguate between lib.rs or main.rs for rust_test, which may be declare a test suite for either library or binary rules. Has no effect if an explicit crate_root is provided.

  • deps: The set of dependencies of this rule. Currently, this supports rust_library and prebuilt_rust_library rules.

  • edition: Set the language edition to be used for this rule. Can be set to any edition the compiler supports (2018 right now). If unset it uses the compiler's default (2015).

  • env: Set environment variables for this rule's invocations of rustc and during execution of the tests. The environment variable values may include macros which are expanded.

  • features: The set of features to be enabled for this rule.

    These are passed to rustc with --cfg feature="{feature}", and can be used in the code with #[cfg(feature = "{feature}")].

  • framework: Use the standard test framework. If this is set to false, then the result is a normal executable which requires a main(), etc. It is still expected to accept the same command-line parameters and produce the same output as the test framework.

  • link_style: Determines whether to build and link this rule's dependencies statically or dynamically. Can be either static, static_pic or shared.

  • linker_flags: The set of additional flags to pass to the linker.

  • mapped_srcs: Add source files along with a local path mapping. Rust is sensitive to the layout of source files, as the directory structure follows the module structure. However this is awkward if the source file is, for example, generated by another rule. In this case, you can set up a mapping from the actual source path to something that makes sense locally. For example mapped_srcs = {":generate-module", "src/generated.rs" }. These are added to the regular srcs, so a file should not be listed in both.

  • named_deps: Add crate dependencies and define a local name by which to use that dependency by. This allows a crate to have multiple dependencies with the same crate name. For example: named_deps = {"local_name", ":some_rust_crate" }. The dependencies may also be non-Rust, but the alias is ignored. It has no effect on the symbols provided by a C/C++ library.

  • rpath: Set the "rpath" in the executable when using a shared link style.

  • run_env: Set environment variables during test execution. The environment variable values may include macros which are expanded.

  • rustc_flags: The set of additional compiler flags to pass to rustc.

  • srcs: The set of Rust source files to be compiled by this rule.

    One of the source files is the root module of the crate. By default this is lib.rs for libraries, main.rs for executables, or the crate's name with .rs appended. This can be overridden with the crate_root rule parameter.

Details​

Note: Buck is currently tested with (and therefore supports) version 1.32.0 of Rust.

Examples:

For more examples, check out our integration tests.


rust_test(
  name='greet',
  srcs=[
    'greet.rs',
  ],
  deps=[
    ':greeting',
  ],
)

rust_library(
  name='greeting',
  srcs=[
    'greeting.rs',
  ],
  deps=[
    ':join',
  ],
)

rust_library(
  name='join',
  srcs=[
    'join.rs',
  ],
)

scala_library​

def scala_library(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    abi_generation_mode: 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] = ...,
    exported_deps: list[str] = ...,
    exported_provided_deps: list[str] = ...,
    extra_arguments: list[str] = ...,
    java_version: None | str = ...,
    javac: None | str = ...,
    labels: list[str] = ...,
    licenses: list[str] = ...,
    manifest_file: None | str = ...,
    maven_coords: None | str = ...,
    never_mark_as_unused_dependency: None | bool = ...,
    on_unused_dependencies: None | str = ...,
    plugins: list[str | (str, list[str])] = ...,
    proguard_config: None | str = ...,
    provided_deps: list[str] = ...,
    remove_classes: list[str] = ...,
    required_for_source_only_abi: bool = ...,
    resources: list[str] = ...,
    resources_root: None | str = ...,
    runtime_deps: list[str] = ...,
    source: None | str = ...,
    source_abi_verification_mode: None | str = ...,
    source_only_abi_deps: list[str] = ...,
    srcs: list[str] = ...,
    target: None | str = ...,
) -> None

Parameters​

  • name: name of the target
  • default_target_platform: specifies the default target platform, used when no platforms are specified on the command line
  • target_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • exec_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with an execution platform
  • visibility: a list of visibility patterns restricting what targets can depend on this one
  • within_view: a list of visibility patterns restricting what this target can depend on
  • metadata: a key-value map of metadata associated with this target
  • tests: a list of targets that provide tests for this one
  • modifiers: an array of modifiers associated with this target
  • javac: Specifies the Java compiler program to use for this rule. The value is a source path or an execution dep (e.g., //foo/bar:bar). Overrides the value in "javac" in the "tools" section of .buckconfig.

scala_test​

def scala_test(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    abi_generation_mode: None | str = ...,
    annotation_processor_deps: list[str] = ...,
    annotation_processor_params: list[str] = ...,
    annotation_processors: list[str] = ...,
    contacts: list[str] = ...,
    cxx_library_whitelist: list[str] = ...,
    default_cxx_platform: None | str = ...,
    default_host_platform: None | str = ...,
    deps: list[str] = ...,
    deps_query: None | str = ...,
    env: dict[str, str] = ...,
    exported_deps: list[str] = ...,
    exported_provided_deps: list[str] = ...,
    extra_arguments: list[str] = ...,
    fork_mode: str = ...,
    java_version: None | str = ...,
    javac: None | str = ...,
    labels: list[str] = ...,
    licenses: list[str] = ...,
    manifest_file: None | str = ...,
    maven_coords: None | str = ...,
    never_mark_as_unused_dependency: None | bool = ...,
    on_unused_dependencies: None | str = ...,
    plugins: list[str | (str, list[str])] = ...,
    proguard_config: None | str = ...,
    provided_deps: list[str] = ...,
    remove_classes: list[str] = ...,
    required_for_source_only_abi: bool = ...,
    resources: list[str] = ...,
    resources_root: None | str = ...,
    run_test_separately: bool = ...,
    runtime_deps: list[str] = ...,
    source: None | str = ...,
    source_abi_verification_mode: None | str = ...,
    source_only_abi_deps: list[str] = ...,
    srcs: list[str] = ...,
    std_err_log_level: None | int | str = ...,
    std_out_log_level: None | int | str = ...,
    target: None | str = ...,
    test_case_timeout_ms: None | int = ...,
    test_rule_timeout_ms: None | int = ...,
    test_type: None | str = ...,
    use_cxx_libraries: None | bool = ...,
    use_dependency_order_classpath: None | bool = ...,
    vm_args: list[str] = ...,
) -> None

Parameters​

  • name: name of the target
  • default_target_platform: specifies the default target platform, used when no platforms are specified on the command line
  • target_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • exec_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with an execution platform
  • visibility: a list of visibility patterns restricting what targets can depend on this one
  • within_view: a list of visibility patterns restricting what this target can depend on
  • metadata: a key-value map of metadata associated with this target
  • tests: a list of targets that provide tests for this one
  • modifiers: an array of modifiers associated with this target
  • javac: Specifies the Java compiler program to use for this rule. The value is a source path or an execution dep (e.g., //foo/bar:bar). Overrides the value in "javac" in the "tools" section of .buckconfig.

scene_kit_assets​

def scene_kit_assets(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    contacts: list[str] = ...,
    default_host_platform: None | str = ...,
    labels: list[str] = ...,
    licenses: list[str] = ...,
    path: str,
) -> None

Parameters​

  • name: name of the target
  • default_target_platform: specifies the default target platform, used when no platforms are specified on the command line
  • target_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • exec_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with an execution platform
  • visibility: a list of visibility patterns restricting what targets can depend on this one
  • within_view: a list of visibility patterns restricting what this target can depend on
  • metadata: a key-value map of metadata associated with this target
  • tests: a list of targets that provide tests for this one
  • modifiers: an array of modifiers associated with this target

sh_binary​

def sh_binary(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    _target_os_type: str = ...,
    append_script_extension: bool = ...,
    contacts: list[str] = ...,
    default_host_platform: None | str = ...,
    deps: list[str] = ...,
    labels: list[str] = ...,
    licenses: list[str] = ...,
    main: str,
    resources: list[str] = ...,
) -> None

An sh_binary() is used to execute a shell script.

Parameters​

  • name: name of the target

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

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

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

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

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

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

  • metadata: a key-value map of metadata associated with this target

  • tests: a list of targets that provide tests for this one

  • modifiers: an array of modifiers associated with this target

  • append_script_extension: By default, sh_binary ensures that the script has an appropriate extension (e.g. .sh or .bat), appending one itself if necessary. Setting this to False prevents that behavior and makes the caller responsible for ensuring an existing appropriate extension.

  • main: Either the path to the script (relative to the build file), or a build target. This file must be executable in order to be run.

  • resources: A list of files or build rules that this rule requires in order to run. These could be things such as random data files.

    When the script runs, the $BUCK_DEFAULT_RUNTIME_RESOURCES environment variable specifies the directory that contains these resources. This directory's location is determined entirely by Buck; the script should not assume the directory's location.

    The resources are also made available in a tree structure that mirrors their locations in the source and buck-out trees. The environment variable $BUCK_PROJECT_ROOT specifies a directory that contains all the resources, laid out in their locations relative to the original buck project root.

Details​

Examples:

This sh_binary() just cats a sample data file back at the user.


# $REPO/BUCK
sh_binary(
    name = "script",
    main = "script.sh",
    resources = [
        "data.dat",
    ],
)


# Sample data file with data we need at runtime
$ echo "I'm a datafile" > data.dat

# Create a simple script that prints out the resource
$ cat > script.sh
#!/bin/sh
cat $BUCK_DEFAULT_RUNTIME_RESOURCES/data.dat

# Make sure the script is executable
$ chmod u+x script.sh

# Run the script, and see that it prints out the resource we provided
$ buck run //:script
Jobs completed: 4. Time elapsed: 0.2s.
BUILD SUCCEEDED
I'm a datafile

sh_test​

def sh_test(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    _inject_test_env: str = ...,
    _remote_test_execution_toolchain: str = ...,
    _test_toolchain: str = ...,
    args: list[str] = ...,
    constraint_overrides: list[str] = ...,
    contacts: list[str] = ...,
    default_host_platform: None | str = ...,
    deps: list[str] = ...,
    env: dict[str, str] = ...,
    labels: list[str] = ...,
    licenses: list[str] = ...,
    list_args: None | list[str] = ...,
    list_env: None | dict[str, str] = ...,
    platform_override: None | str = ...,
    remote_execution: None | str | dict[str, None | bool | int | str | list[dict[str, str]] | dict[str, str]] = ...,
    remote_execution_action_key_providers: None | str = ...,
    resources: list[str] = ...,
    run_args: list[str] = ...,
    run_env: dict[str, str] = ...,
    run_test_separately: bool = ...,
    test: None | str = ...,
    test_rule_timeout_ms: None | int = ...,
    type: None | str = ...,
) -> None

A sh_test() is a test rule that can pass results to the test runner by invoking a shell script.

Parameters​

  • name: name of the target

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

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

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

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

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

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

  • metadata: a key-value map of metadata associated with this target

  • tests: a list of targets that provide tests for this one

  • modifiers: an array of modifiers associated with this target

  • args: The list of arguments to invoke this script with. These are literal values, and no shell interpolation is done.

    These can contain string parameter macros , for example, to give the location of a generated binary to the test script.

  • env: Environment variable overrides that should be used when running the script. The key is the variable name, and the value is its value.

    The values can contain string parameter macros such as the location of a generated binary to be used by the test script.

  • test: Either the path to the script (relative to the build file), or a build target. This file must be executable in order to be run.

  • type: If provided, this will be sent to any configured .buckconfig

Details​

NOTE: This rule is not currently supported on Windows.

Examples:

This sh_test() fails if a string does not match a value.


# $REPO/BUCK
sh_test(
    name = "script_pass",
    test = "script.sh",
    args = ["--pass"],
)

sh_test(
    name = "script_fail",
    test = "script.sh",
    args = ["--fail"],
)



# Create a simple script that prints out the resource
$ cat > script.sh
#!/bin/sh
for arg in $@; do
  if [ "$arg" == "--pass" ]; then
    echo "Passed"
    exit 0;
  fi
done
echo "Failed"
exit 1

# Make sure the script is executable
$ chmod u+x script.sh

# Run the script, and see that one test passes, one fails
$ buck test //:script_pass //:script_fail
FAILURE script.sh sh_test
Building: finished in 0.0 sec (100%) 2/2 jobs, 0 updated
  Total time: 0.0 sec
Testing: finished in 0.0 sec (1 PASS/1 FAIL)
RESULTS FOR //:script_fail //:script_pass
FAIL    <100ms  0 Passed   0 Skipped   1 Failed   //:script_fail
FAILURE script.sh sh_test
====STANDARD OUT====
Failed

PASS    <100ms  1 Passed   0 Skipped   0 Failed   //:script_pass
TESTS FAILED: 1 FAILURE
Failed target: //:script_fail
FAIL //:script_fail

supermodule_target_graph​

def supermodule_target_graph(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    contacts: list[str] = ...,
    default_host_platform: None | str = ...,
    deps: list[str] = ...,
    label_pattern: None | str = ...,
    labels: list[str] = ...,
    licenses: list[str] = ...,
    on_duplicate_entry: str = ...,
    out: str = ...,
) -> None

Parameters​

  • name: name of the target
  • default_target_platform: specifies the default target platform, used when no platforms are specified on the command line
  • target_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • exec_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with an execution platform
  • visibility: a list of visibility patterns restricting what targets can depend on this one
  • within_view: a list of visibility patterns restricting what this target can depend on
  • metadata: a key-value map of metadata associated with this target
  • tests: a list of targets that provide tests for this one
  • modifiers: an array of modifiers associated with this target

swift_library​

def swift_library(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    bridging_header: None | str = ...,
    compiler_flags: list[str] = ...,
    contacts: list[str] = ...,
    default_host_platform: None | str = ...,
    deps: list[str] = ...,
    enable_cxx_interop: bool = ...,
    frameworks: list[str] = ...,
    labels: list[str] = ...,
    libraries: list[str] = ...,
    licenses: list[str] = ...,
    module_name: None | str = ...,
    preferred_linkage: str = ...,
    sdk_modules: list[str] = ...,
    serialize_debugging_options: None | bool = ...,
    soname: None | str = ...,
    srcs: list[str] = ...,
    supported_platforms_regex: None | str = ...,
    target_sdk_version: None | str = ...,
    uses_explicit_modules: bool = ...,
    version: None | str = ...,
) -> None

Parameters​

  • name: name of the target
  • default_target_platform: specifies the default target platform, used when no platforms are specified on the command line
  • target_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • exec_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with an execution platform
  • visibility: a list of visibility patterns restricting what targets can depend on this one
  • within_view: a list of visibility patterns restricting what this target can depend on
  • metadata: a key-value map of metadata associated with this target
  • tests: a list of targets that provide tests for this one
  • modifiers: an array of modifiers associated with this target

swift_toolchain​

def swift_toolchain(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    _internal_platform_path: None | str = ...,
    _internal_sdk_path: None | str = ...,
    _library_interface_uses_swiftinterface: bool = ...,
    _swiftc_wrapper: str = ...,
    architecture: None | str = ...,
    contacts: list[str] = ...,
    default_host_platform: None | str = ...,
    labels: list[str] = ...,
    licenses: list[str] = ...,
    make_swift_comp_db: str = ...,
    make_swift_interface: str = ...,
    object_format: str = ...,
    placeholder_tool: None | str = ...,
    platform_path: None | str = ...,
    prefix_serialized_debug_info: bool = ...,
    resource_dir: None | str = ...,
    runtime_paths_for_bundling: list[str] = ...,
    runtime_paths_for_linking: list[str] = ...,
    runtime_run_paths: list[str] = ...,
    sdk_modules: list[str] = ...,
    sdk_path: None | str = ...,
    static_runtime_paths: list[str] = ...,
    supports_relative_resource_dir: bool = ...,
    swift_experimental_features: dict[str, list[str]] = ...,
    swift_ide_test_tool: None | str = ...,
    swift_stdlib_tool: str,
    swift_stdlib_tool_flags: list[str] = ...,
    swift_upcoming_features: dict[str, list[str]] = ...,
    swiftc: str,
    swiftc_flags: list[str] = ...,
) -> None

Parameters​

  • name: name of the target
  • default_target_platform: specifies the default target platform, used when no platforms are specified on the command line
  • target_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • exec_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with an execution platform
  • visibility: a list of visibility patterns restricting what targets can depend on this one
  • within_view: a list of visibility patterns restricting what this target can depend on
  • metadata: a key-value map of metadata associated with this target
  • tests: a list of targets that provide tests for this one
  • modifiers: an array of modifiers associated with this target

test_suite​

def test_suite(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    contacts: list[str] = ...,
    default_host_platform: None | str = ...,
    labels: list[str] = ...,
    licenses: list[str] = ...,
    test_deps: list[str] = ...,
) -> None

A test_suite() is used to create a grouping of tests that should all be run by just testing this rule.

Parameters​

  • name: name of the target
  • default_target_platform: specifies the default target platform, used when no platforms are specified on the command line
  • target_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • exec_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with an execution platform
  • visibility: a list of visibility patterns restricting what targets can depend on this one
  • within_view: a list of visibility patterns restricting what this target can depend on
  • metadata: a key-value map of metadata associated with this target
  • tests: a list of targets that provide tests for this one
  • modifiers: an array of modifiers associated with this target

Details​

This rule can then be given to buck test, and all tests that it depends on will be invoked. Note that the test_suite() target is not tested itself, it just tells buck to run other tests. It will not show up in calls to the external runner nor in the normal test output.

Examples:

This test_suite() sets up two different sets of tests to run, 'all' tests and 'slow' tests. Note that all_tests can depend on slow_tests, and all three tests are run.


# instrumentation_tests/BUCK:
sh_test(
    name = "instrumentation_tests",
    test = "instrumentation_tests.sh",
    visibility = ["PUBLIC"],
)

# integration_tests/BUCK:
sh_test(
    name = "integration_tests",
    test = "integration_tests.sh",
    visibility = ["PUBLIC"],
)

# unit_tests/BUCK:
sh_test(
    name = "unit_tests",
    test = "unit_tests.sh",
    visibility = ["PUBLIC"],
)

# BUCK:
test_suite(
    name = "slow_tests",
    tests = [
        "//instrumentation_tests:instrumentation_tests",
        "//integration_tests:integration_tests",
    ],
)

test_suite(
    name = "all_tests",
    tests = [
        ":slow_tests",
        "//unit_tests:unit_tests",
    ],
)

Yields output like this when run:


$ buck test //:slow_tests
...
RESULTS FOR //instrumentation_tests:instrumentation_tests //integration_tests:integration_tests
PASS    <100ms  1 Passed   0 Skipped   0 Failed   //instrumentation_tests:instrumentation_tests
PASS    <100ms  1 Passed   0 Skipped   0 Failed   //integration_tests:integration_tests
TESTS PASSED
...

$ buck test //:all_tests
RESULTS FOR //instrumentation_tests:instrumentation_tests //integration_tests:integration_tests //unit_tests:unit_tests
PASS    <100ms  1 Passed   0 Skipped   0 Failed   //instrumentation_tests:instrumentation_tests
PASS    <100ms  1 Passed   0 Skipped   0 Failed   //integration_tests:integration_tests
PASS    <100ms  1 Passed   0 Skipped   0 Failed   //unit_tests:unit_tests
TESTS PASSED

toolchain_alias​

def toolchain_alias(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    actual: str,
) -> None

toolchain_alias acts like alias but for toolchain rules.

Parameters​

  • name: name of the target
  • default_target_platform: specifies the default target platform, used when no platforms are specified on the command line
  • target_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • exec_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with an execution platform
  • visibility: a list of visibility patterns restricting what targets can depend on this one
  • within_view: a list of visibility patterns restricting what this target can depend on
  • metadata: a key-value map of metadata associated with this target
  • tests: a list of targets that provide tests for this one
  • modifiers: an array of modifiers associated with this target
  • actual: The actual toolchain that is being aliased. This should be a toolchain rule.

Details​

The toolchain_alias itself is a toolchain rule and the actual argument is expected to be a toolchain_rule as well.

versioned_alias​

def versioned_alias(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    contacts: list[str] = ...,
    default_host_platform: None | str = ...,
    labels: list[str] = ...,
    licenses: list[str] = ...,
    versions: dict[str, str] = ...,
) -> None

Parameters​

  • name: name of the target
  • default_target_platform: specifies the default target platform, used when no platforms are specified on the command line
  • target_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • exec_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with an execution platform
  • visibility: a list of visibility patterns restricting what targets can depend on this one
  • within_view: a list of visibility patterns restricting what this target can depend on
  • metadata: a key-value map of metadata associated with this target
  • tests: a list of targets that provide tests for this one
  • modifiers: an array of modifiers associated with this target

windows_resource​

def windows_resource(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    _cxx_toolchain: str = ...,
    header_namespace: None | str = ...,
    headers: list[str] | dict[str, str] = ...,
    include_directories: list[str] = ...,
    labels: list[str] = ...,
    platform_headers: list[(str, list[str] | dict[str, str])] = ...,
    raw_headers: list[str] = ...,
    srcs: list[str | (str, list[str])] = ...,
) -> None

A windows_resource() rule specifies a set of Window's Resource File (.rc) that are compiled into object files.

Parameters​

  • name: name of the target
  • default_target_platform: specifies the default target platform, used when no platforms are specified on the command line
  • target_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • exec_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with an execution platform
  • visibility: a list of visibility patterns restricting what targets can depend on this one
  • within_view: a list of visibility patterns restricting what this target can depend on
  • metadata: a key-value map of metadata associated with this target
  • tests: a list of targets that provide tests for this one
  • modifiers: an array of modifiers associated with this target
  • 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. 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 name can contain forward slashes (/). The headers can be included with #include "$HEADER_NAMESPACE/$HEADER_NAME" or #include <$HEADER_NAMESPACE/$HEADER_NAME> , where $HEADER_NAMESPACE is the value of the target's header_namespace attribute, and $HEADER_NAME is the header name if specified, and the filename of the header file otherwise. See header_namespace for more information.
  • include_directories: A list of include directories (with raw_headers) to be added to the compile command for compiling this target (via -I). An include directory is relative to the current package.
  • platform_headers: Platform specific header files. These should be specified as a list of pairs where the first element is an un-anchored regex (in java.util.regex.Pattern syntax) against which the platform name is matched, and the second element is either a list of header files or a dictionary of header names to header files that will be made available for inclusion to the source files in the target if the platform matches the regex. See headers for more information.
  • raw_headers: The set of header files that can be used for inclusion to the source files in the target and all targets that transitively depend on it. Buck doesn't add raw headers to the search path of a compiler/preprocessor automatically. include_directories and public_include_directories are the recommended way to add raw headers to the search path (they will be added via -I). compiler_flags, preprocessor_flags and exported_preprocessor_flags can also be used to add such raw headers to the search path if inclusion via -isystem or -iquote is needed. raw_headers cannot be used together with headers or exported_headers in the same target.
  • srcs: The set of C, C++, Objective-C, Objective-C++, or assembly source files to be preprocessed, compiled, and assembled by this rule. We determine which stages to run on each input source based on its file extension. See the GCC documentation for more detail on how file extensions are interpreted. Each element can be either a string specifying a source file (e.g. '') or a tuple of a string specifying a source file and a list of compilation flags (e.g. ('', ['-Wall', '-Werror']) ). In the latter case the specified flags will be used in addition to the rule's other flags when preprocessing and compiling that file (if applicable).

Details​

The files are compiled into .res files using rc.exe and then compiled into object files using cvtres.exe. They are not part of cxx_library because Microsoft's linker ignores the resources unless they are specified as an object file, meaning including them in a possibly static library is unintuitive.

Examples:


# A rule that includes a single .rc file and compiles it into an object file.
windows_resource(
  name = "resources",
  srcs = [
    "resources.rc",
  ],
)

# A rule that links against the above windows_resource rule.
cxx_binary(
  name = "app",
  srcs = [
    "main.cpp",
  ],
  deps = [
    ":resources"
  ],
)

worker_tool​

def worker_tool(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    _worker_tool_runner: str = ...,
    args: str | list[str] = ...,
    contacts: list[str] = ...,
    default_host_platform: None | str = ...,
    env: dict[str, str] = ...,
    exe: None | str = ...,
    labels: list[str] = ...,
    licenses: list[str] = ...,
    max_workers: None | int = ...,
    max_workers_per_thread_percent: None | int = ...,
    persistent: None | bool = ...,
) -> None

Some external tools have high startup costs. To amortize those costs over the whole build rather than paying them for each rule invocation, use the worker_tool() rule in conjunction with genrule(). Buck then starts the external tool once and reuses it by communicating with it over stdin and stdout using a simple JSON protocol.

Parameters​

  • name: name of the target
  • default_target_platform: specifies the default target platform, used when no platforms are specified on the command line
  • target_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration
  • exec_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with an execution platform
  • visibility: a list of visibility patterns restricting what targets can depend on this one
  • within_view: a list of visibility patterns restricting what this target can depend on
  • metadata: a key-value map of metadata associated with this target
  • tests: a list of targets that provide tests for this one
  • modifiers: an array of modifiers associated with this target
  • args: A string of args that is passed to the executable represented by exe on initial startup.
  • env: A map of environment variables that is passed to the executable represented by exe on initial startup.
  • exe: A build target for a rule that outputs an executable, such as an sh_binary(). Buck runs this executable only once per build.
  • max_workers: The maximum number of workers of this type that Buck starts. Use -1 to allow the creation of as many workers as necessary.
  • max_workers_per_thread_percent: The maximum ratio of workers of this type that Buck starts per thread, specified as a positive integer percentage (1-100). Must be greater than or equal to 1 and less than or equal to 100. Only one of max_workers and max_workers_per_thread_percent may be specified.
  • persistent: If set to true, Buck does not restart the tool unless the tool itself changes. This means the tool persists across multiple Buck commands without being shut down and may see the same rule being built more than once. Be careful not to use this setting with tools that don't expect to process the same input—with different contents—twice!

Details​

A worker_tool rule can be referenced in the cmd parameter of a genrule by using the macro:



$(exe //path/to:target)

Examples:

Consider the following build rules:


#
# Buck
#
worker_tool(
  name = 'ExternalToolWorker',
  exe = ':ExternalTool',
  args = '--arg1 --arg2'
)

sh_binary(
  name = 'ExternalTool',
  main = 'external_tool.sh',
)

genrule(
  name = 'TransformA',
  out = 'OutputA.txt',
  cmd = '$(exe :ExternalToolWorker) argA',
)

genrule(
  name = 'TransformB',
  out = 'OutputB.txt',
  cmd = '$(exe :ExternalToolWorker) argB',
)

genrule(
  name = 'TransformC',
  out = 'OutputC.txt',
  cmd = '$(exe :ExternalToolWorker) argC',
)

When doing a buck build on all three of the above genrules, Buck first creates the worker process by invoking:



./external_tool.sh --arg1 --arg2

Buck then communicates with this process using JSON over stdin, starting with a handshake:


[
  {
    "id": 0,
    "type": "handshake",
    "protocol_version": "0",
    "capabilities": []
  }

Buck then waits for the tool to reply on stdout:


[
  {
    "id": 0,
    "type": "handshake",
    "protocol_version": "0",
    "capabilities": []
  }

Then, when building the first genrule, Buck writes to stdin:


  ,{
    "id": 1,
    "type": "command",
    "args_path": "/tmp/1.args",
    "stdout_path": "/tmp/1.out",
    "stderr_path": "/tmp/1.err"
  }

The file /tmp/1.args contains argA. The tool should perform the necessary work for this job and then write the job's output to the files supplied by Buck—in this case, /tmp/1.out and /tmp/1.err. Once the job is done, the tool should reply to Buck on stdout with:


  ,{
    "id": 1,
    "type": "result",
    "exit_code": 0
  }

Once Buck hears back from the first genrule's job, it submits the second genrule's job in the same fashion and awaits the response. When the build is all finished, Buck closes the JSON by writing to stdin:


]

which signals the tool that it should exit after replying on stdout with:


]

In this example, Buck is guaranteed to invoke



./external_tool.sh --arg1 --arg2

only once during the build. The three jobs corresponding to the three genrules are submitted synchronously to the single worker process.

Note that the id values in the messages are not necessarily increasing or sequential, but they do have to match between the request message and the response message of a given job as well as in the initial handshake.

If the tool receives a message type it cannot interpret it should answer with:


{
  "id": &ltn>,
  "type": "error",
  "exit_code": 1
}

If the tool receives a message type it can interpret, but the other attributes of the message are in an inconsistent state, it should answer with:


{
  "id": &ltn>,
  "type": "error",
  "exit_code": 2
}

zip_file​

def zip_file(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    _zip_file_toolchain: str = ...,
    contacts: list[str] = ...,
    default_host_platform: None | str = ...,
    entries_to_exclude: list[str] = ...,
    hardcode_permissions_for_deterministic_output: None | bool = ...,
    labels: list[str] = ...,
    licenses: list[str] = ...,
    on_duplicate_entry: str = ...,
    out: str = ...,
    srcs: list[str] = ...,
    zip_srcs: list[str] = ...,
) -> None

A zip_file() allows builds to create basic zip files in a platform-agnostic way.

Parameters​

  • name: name of the target

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

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

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

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

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

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

  • metadata: a key-value map of metadata associated with this target

  • tests: a list of targets that provide tests for this one

  • modifiers: an array of modifiers associated with this target

  • entries_to_exclude: List of regex expressions that describe entries that should not be included in the output zip file.

    The regexes must be defined using java.util.regex.Pattern syntax.

  • hardcode_permissions_for_deterministic_output: If set to true, Buck hardcodes the permissions in order to ensures that all files have the same permissions regardless of the platform on which the zip was generated.

  • on_duplicate_entry: Action performed when Buck detects that zip_file input contains multiple entries with the same name.

    The valid values are:

    • overwrite (default): the last entry overwrites all previous entries with the same name.
    • append: all entries are added to the output file.
    • fail: fail the build when duplicate entries are present.

  • out: The name of the zip file that should be generated. This allows builds to use a meaningful target name coupled with a meaningful zip file name. The default value takes the rule's name and appends .zip.

  • srcs: The set of files to include in the zip.

    Each src will be added to the zip as follows:

    • If the src is the output of another rule, the output will be included using just the output's file name.
    • If the src is a file relative to the rule's declaration, it will be included in the zip with its relative file name.

  • zip_srcs: The set of zip files whose content to include in the output zip file.

    Note that the order of files in zip_srcs matters because the same zip entry can be included from multiple files. See the on_duplicate_entry argument to learn how to control the behavior when there are multiple entries with the same name.

    The entries from zip_srcs are added before files from srcs.

Details​

Examples:

This example will create a simple zip file.


zip_file(
  # The output will be "example.zip"
  name = 'example',
  srcs =
    # These files will be found in the zip under "dir/"
    glob(['dir/**/*']) +
    [
      # Imagine this generates the output
      # "buck-out/gen/foo/hello.txt". This output will
      # be found in the zip at "hello.txt"
      '//some/other:target',

    ],
  zip_srcs = [
     # The contents of this zip will be added to the generated zip.
    'amazing-library-1.0-sources.zip',
  ],
  entries_to_exclude = [
    "com/example/amazinglibrary/Source1.java",
  ],
)

If you were to examine the generated zip, the contents would look something like (assuming the output of "//some/other:target" was a file who's path ended with hello.txt, the "dir" glob found two files, and "amazing-library-1.0-sources.zip" contained two Java source files):


dir/file1.txt
dir/subdir/file2.txt
hello.txt
com/example/amazinglibrary/Source2.java