rust_python_extension

A rust_python_extension() rule builds a Python extension module from Rust source code (typically using PyO3), producing a .so or a Windows .pyd.

Details

The module is importable under base_module and module_name (the rule name by default). link_style defaults to shared; static and static_pic both use position-independent dependency archives. Toolchains without advanced unstable linking always bundle Rust dependencies, while still honoring link_style for native dependencies.

Extensions may be statically embedded into a native Python binary unless allow_embedding is false. Rust initialization symbols are not renamed, so embedded modules must have distinct module_name values.

The rule is a rust crate as far as developer tooling is concerned: it exposes the same check, clippy.json, diag.json, expand, doc and sources sub-targets as rust_library, and the same rust-analyzer and diagnostics providers.

Function Signature

def rust_python_extension(
    *,
    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 | target_name_glob] = [],
    within_view: list[str | target_name_glob] = ["PUBLIC"],
    metadata: OpaqueMetadata = {},
    tests: list[str] = [],
    modifiers: OpaqueMetadata = [],
    incoming_transition: None | str = None,
    _create_third_party_build_root: str = "prelude//third-party/tools:create_build",
    _cxx_toolchain: str = select({"prelude//:none": "gh_facebook_buck2_shims_meta//:cxx_no_default_deps", "DEFAULT": "gh_facebook_buck2_shims_meta//:cxx"}),
    _exec_os_type: str = "prelude//os_lookup/targets:os_lookup",
    _rust_analyzer_target_kind: str = "lib",
    _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",
    _workspaces: list[str] = [],
    allow_embedding: bool = True,
    base_module: None | str = None,
    clippy_configuration: None | str = None,
    clippy_flags: list[str] = [],
    contacts: list[str] = [],
    coverage: bool = False,
    crate: None | str = None,
    crate_dynamic: None | str = None,
    crate_root: None | str = None,
    default_deps: str = "deps",
    default_platform: None | str = None,
    deps: list[str] = [],
    doctests: bool = False,
    edition: None | str = None,
    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_enabled: bool = False,
    labels: list[str] = [],
    licenses: list[str] = [],
    link_style: None | str = None,
    linker_flags: list[str] = [],
    mapped_srcs: dict[str, str] = {},
    module_name: None | str = None,
    named_deps: list[(str, str)] | dict[str, str] = {},
    proc_macro: bool = False,
    resources: list[str] | dict[str, str] = [],
    rustc_flags: list[str] = [],
    rustdoc_flags: list[str] = [],
    separate_debug_info: bool = False,
    srcs: list[str] = [],
    srcs_filegroup: None | str = None,
    type_stub: None | str = None,
    use_content_based_paths: bool = True,
    uses_restricted_rustc_flags: bool = False,
) -> 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

• _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.

• allow_embedding: (defaults to: True)

  Whether the extension may be statically embedded into a native python binary (linked directly into the executable) rather than shipped as a separate .so. Set to False for extensions that must remain dynamically loaded.

• base_module: (defaults to: None)

  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.

• clippy_flags: (defaults to: [])

  Flags passed to clippy but not rustc, ahead of rustc_flags so those can override them.

• contacts: (defaults to: [])

  A list of organizational contacts for this rule. These could be individuals who you would contact in the event of a failure or other issue with the rule.

  contacts = [ 'Joe Sixpack', 'Erika Mustermann' ]

• 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_deps: (defaults to: "deps")

  Whether to include the default deps from the toolchain, and where to include them (deps, exported_deps, etc).

• 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. The environment variable values may include macros which are expanded.

• exported_linker_flags: (defaults to: [])

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

  A set of additional flag to pass after this item on the link line, even if this items is compiled to a DSO.

• 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}")].

• labels: (defaults to: [])

  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().

• licenses: (defaults to: [])

  Set of license files for this library. To get the list of license files for a given build rule and all of its dependencies, you can use buck query

• 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.

• module_name: (defaults to: None)

  Override the imported module's name (defaults to the rule name).

• 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.

• 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 target.

  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 attribute.

• srcs_filegroup: (defaults to: None)

  Directory of sources already combined together from srcs + mapped_srcs. This allows sources to be located in a different Buck package than the one containing the rust_library target which compiles those sources.

  When using srcs_filegroup, the attributes srcs and mapped_srcs cannot also be passed, and crate_root must be passed.

• type_stub: (defaults to: None)

  Optional .pyi type stub file for the extension.

Examples

# A Python extension implemented as a pyo3 #[pymodule] in Rust.
rust_python_extension(
    name = "mymodule",
    base_module = "foo.bar",
    srcs = glob(["src/**/*.rs"]),
    crate_root = "src/lib.rs",
    deps = [
        "//third-party/rust:pyo3",
    ],
)

python_binary(
    name = "main",
    main_module = "foo.bar.mymodule",
    deps = [":mymodule"],
)