Skip to main content

rust_test

A rust_test() rule builds a Rust test native executable from the supplied set of Rust source files and dependencies and runs this test.

Details​

Note: Buck is currently tested with (and therefore supports) version 1.32.0 of Rust.

Function Signature​

def rust_test(
    *,
    name: str,
    default_target_platform: None | str = None,
    target_compatible_with: list[str] = [],
    compatible_with: list[str] = [],
    exec_compatible_with: list[str] = [],
    visibility: list[str] = [],
    within_view: list[str] = ["PUBLIC"],
    metadata: OpaqueMetadata = {},
    tests: list[str] = [],
    modifiers: OpaqueMetadata = [],
    incoming_transition: None | str = None,
    _apple_platforms: dict[str, str] = {},
    _build_info: dict[str, typing.Any] = {},
    _cxx_toolchain: str = "gh_facebook_buck2_shims_meta//:cxx",
    _exec_os_type: str = "prelude//os_lookup/targets:os_lookup",
    _inject_test_env: str = "prelude//test/tools:inject_test_env",
    _remote_test_execution_toolchain: str = "gh_facebook_buck2_shims_meta//:remote_test_execution",
    _rust_internal_tools_toolchain: str = "prelude//rust/tools:internal_tools_toolchain",
    _rust_toolchain: str = "gh_facebook_buck2_shims_meta//:rust",
    _target_os_type: str = "prelude//os_lookup/targets:os_lookup",
    _test_toolchain: str = "gh_facebook_buck2_shims_meta//:test",
    _workspaces: list[str] = [],
    anonymous_link_groups: bool = True,
    auto_link_groups: bool = True,
    clippy_configuration: None | str = None,
    contacts: list[str] = [],
    coverage: bool = False,
    crate: None | str = None,
    crate_root: None | str = None,
    default_host_platform: None | str = None,
    default_platform: None | str = None,
    default_roots: None | list[str] = None,
    deps: list[str] = [],
    edition: None | str = None,
    enable_distributed_thinlto: bool = False,
    env: dict[str, str] = {},
    extra_dwp_flags: list[str] = [],
    features: list[str] = [],
    flagged_deps: list[(str, list[str])] = [],
    framework: bool = True,
    incremental_enabled: bool = False,
    labels: list[str] = [],
    licenses: list[str] = [],
    link_group: None | str = None,
    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])] = None,
    link_group_min_binary_node_count: None | int = None,
    link_style: None | str = None,
    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 | list[str]]] = None,
    resources: list[str] | dict[str, str] = [],
    rpath: bool = False,
    run_env: dict[str, str] = {},
    rustc_flags: list[str] = [],
    rustdoc_flags: list[str] = [],
    separate_debug_info: bool = False,
    srcs: list[str] = [],
    transformation_spec: None | str = None,
) -> None

Parameters​

  • name: (required)

    name of the target

  • default_target_platform: (defaults to: None)

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

  • target_compatible_with: (defaults to: [])

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

  • compatible_with: (defaults to: [])

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

  • exec_compatible_with: (defaults to: [])

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

  • visibility: (defaults to: [])

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

  • within_view: (defaults to: ["PUBLIC"])

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

  • metadata: (defaults to: {})

    a key-value map of metadata associated with this target

  • tests: (defaults to: [])

    a list of targets that provide tests for this one

  • modifiers: (defaults to: [])

    an array of modifiers associated with this target

  • incoming_transition: (defaults to: None)

    specifies the incoming transition to apply to this target

  • _build_info: (defaults to: {})

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

  • _workspaces: (defaults to: [])

    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: (defaults to: None)

    Set the name of the top-level source file for the crate, which can be used to override the default (see srcs).

  • default_roots: (defaults to: None)

    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: (defaults to: [])

    The set of dependencies of this rule. Currently, this supports rust_library and prebuilt_rust_library rules.

  • edition: (defaults to: None)

    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: (defaults to: {})

    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: (defaults to: [])

    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: (defaults to: True)

    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: (defaults to: None)

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

  • linker_flags: (defaults to: [])

    The set of additional flags to pass to the linker.

  • mapped_srcs: (defaults to: {})

    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: (defaults to: {})

    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: (defaults to: False)

    Set the "rpath" in the executable when using a shared link style.

  • run_env: (defaults to: {})

    Set environment variables during test execution. The environment variable values may include macros which are expanded.

  • rustc_flags: (defaults to: [])

    The set of additional compiler flags to pass to rustc.

  • srcs: (defaults to: [])

    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.

  • transformation_spec: (defaults to: None)

    Dependency to a transformation spec that will selectively change parts of dependency graph

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',
  ],
)