rust/settings/settings.bzl

"""# Rust settings

Definitions for all `@rules_rust//rust` settings
"""

load(
    "@bazel_skylib//rules:common_settings.bzl",
    "bool_flag",
    "int_flag",
    "string_flag",
)
load(
    "//rust/private:clippy.bzl",
    _capture_clippy_output = "capture_clippy_output",
    _clippy_flag = "clippy_flag",
    _clippy_flags = "clippy_flags",
)
load("//rust/private:lto.bzl", "rust_lto_flag")
load(
    "//rust/private:rustc.bzl",
    _error_format = "error_format",
    _extra_exec_rustc_flag = "extra_exec_rustc_flag",
    _extra_exec_rustc_flags = "extra_exec_rustc_flags",
    _extra_rustc_flag = "extra_rustc_flag",
    _extra_rustc_flags = "extra_rustc_flags",
    _no_std = "no_std",
    _per_crate_rustc_flag = "per_crate_rustc_flag",
    _rustc_output_diagnostics = "rustc_output_diagnostics",
)
load("//rust/private:unpretty.bzl", "UNPRETTY_MODES", "rust_unpretty_flag")
load(":incompatible.bzl", "incompatible_flag")

# buildifier: disable=unnamed-macro
def unpretty():
    """A build setting to control the output of `RustUnpretty*` actions

    Supported values are:
    - `ast-tree,expanded`
    - `ast-tree`
    - `expanded,hygiene`
    - `expanded,identified`
    - `expanded`
    - `hir-tree`
    - `hir,identified`
    - `hir,typed`
    - `hir`
    - `identified`
    - `mir-cfg`
    - `mir`
    - `normal`
    """
    rust_unpretty_flag(
        name = "unpretty",
        build_setting_default = UNPRETTY_MODES,
    )

# buildifier: disable=unnamed-macro
def lto():
    """A build setting which specifies the link time optimization mode used when building Rust code."""
    rust_lto_flag(
        name = "lto",
        build_setting_default = "unspecified",
    )

def rename_first_party_crates():
    """A flag controlling whether to rename first-party crates such that their names \
    encode the Bazel package and target name, instead of just the target name.

    First-party vs. third-party crates are identified using the value of
    `@rules_rust//settings:third_party_dir`.
    """
    bool_flag(
        name = "rename_first_party_crates",
        build_setting_default = False,
    )

def third_party_dir():
    """A flag specifying the location of vendored third-party rust crates within this \
    repository that must not be renamed when `rename_first_party_crates` is enabled.

    Must be specified as a Bazel package, e.g. "//some/location/in/repo".
    """
    string_flag(
        name = "third_party_dir",
        build_setting_default = str(Label("//third_party/rust")),
    )

def use_real_import_macro():
    """A flag to control whether rust_library and rust_binary targets should \
    implicitly depend on the *real* import macro, or on a no-op target.
    """
    bool_flag(
        name = "use_real_import_macro",
        build_setting_default = False,
    )

def pipelined_compilation():
    """When set, this flag causes rustc to emit `*.rmeta` files and use them for `rlib -> rlib` dependencies.

    While this involves one extra (short) rustc invocation to build the rmeta file,
    it allows library dependencies to be unlocked much sooner, increasing parallelism during compilation.
    """
    bool_flag(
        name = "pipelined_compilation",
        build_setting_default = False,
    )

def experimental_use_cc_common_link():
    """A flag to control whether to link rust_binary and rust_test targets using \
    cc_common.link instead of rustc.
    """
    bool_flag(
        name = "experimental_use_cc_common_link",
        build_setting_default = False,
    )

def experimental_use_global_allocator():
    """A flag to indicate that a global allocator is in use when using `--@rules_rust//rust/settings:experimental_use_cc_common_link`

    Users need to specify this flag because rustc generates different set of symbols at link time when a global allocator is in use.
    When the linking is not done by rustc, the `rust_toolchain` itself provides the appropriate set of symbols.
    """
    bool_flag(
        name = "experimental_use_global_allocator",
        build_setting_default = False,
    )

def experimental_use_coverage_metadata_files():
    """A flag to have coverage tooling added as `coverage_common.instrumented_files_info.metadata_files` instead of \
    reporting tools like `llvm-cov` and `llvm-profdata` as runfiles to each test.
    """
    bool_flag(
        name = "experimental_use_coverage_metadata_files",
        build_setting_default = True,
    )

def toolchain_generated_sysroot():
    """A flag to set rustc --sysroot flag to the sysroot generated by rust_toolchain."""
    bool_flag(
        name = "toolchain_generated_sysroot",
        build_setting_default = True,
        visibility = ["//visibility:public"],
    )

# buildifier: disable=unnamed-macro
def incompatible_change_rust_test_compilation_output_directory():
    """A flag to put rust_test compilation outputs in the same directory as the rust_library compilation outputs.
    """
    incompatible_flag(
        name = "incompatible_change_rust_test_compilation_output_directory",
        build_setting_default = False,
        issue = "https://github.com/bazelbuild/rules_rust/issues/2827",
    )

def experimental_link_std_dylib():
    """A flag to control whether to link libstd dynamically."""
    bool_flag(
        name = "experimental_link_std_dylib",
        build_setting_default = False,
    )

def experimental_use_sh_toolchain_for_bootstrap_process_wrapper():
    """A flag to control whether the shell path from a shell toolchain (`@bazel_tools//tools/sh:toolchain_type`) \
    is embedded into the bootstrap process wrapper for the `.sh` file.
    """
    bool_flag(
        name = "experimental_use_sh_toolchain_for_bootstrap_process_wrapper",
        build_setting_default = False,
    )

# buildifier: disable=unnamed-macro
def clippy_toml():
    """This setting is used by the clippy rules. See https://bazelbuild.github.io/rules_rust/rust_clippy.html

    Note that this setting is actually called `clippy.toml`.
    """
    native.label_flag(
        name = "clippy.toml",
        build_setting_default = ".clippy.toml",
    )

# buildifier: disable=unnamed-macro
def rustfmt_toml():
    """This setting is used by the rustfmt rules. See https://bazelbuild.github.io/rules_rust/rust_fmt.html

    Note that this setting is actually called `rustfmt.toml`.
    """
    native.label_flag(
        name = "rustfmt.toml",
        build_setting_default = ".rustfmt.toml",
    )

# buildifier: disable=unnamed-macro
def capture_clippy_output():
    """Control whether to print clippy output or store it to a file, using the configured error_format."""
    _capture_clippy_output(
        name = "capture_clippy_output",
        build_setting_default = False,
    )

# buildifier: disable=unnamed-macro
def no_std():
    """This setting may be used to enable builds without the standard library.

    Currently only no_std + alloc is supported, which can be enabled with setting the value to "alloc".
    In the future we could add support for additional modes, e.g "core", "alloc,collections".
    """
    string_flag(
        name = "no_std",
        build_setting_default = "off",
        values = [
            "alloc",
            "off",
        ],
    )

    # A hack target to allow as to only apply the no_std mode in target config.
    _no_std(
        name = "build_target_in_no_std",
        visibility = ["//visibility:private"],
    )

    # A config setting for setting conditional `cargo_features`, `deps`, based on the `:no_std` value.
    native.config_setting(
        name = "is_no_std",
        flag_values = {
            ":build_target_in_no_std": "alloc",
        },
    )

# buildifier: disable=unnamed-macro
def error_format():
    """This setting may be changed from the command line to generate machine readable errors.
    """
    _error_format(
        name = "error_format",
        build_setting_default = "human",
    )

# buildifier: disable=unnamed-macro
def rustc_output_diagnostics():
    """This setting may be changed from the command line to generate rustc diagnostics.
    """
    _rustc_output_diagnostics(
        name = "rustc_output_diagnostics",
        build_setting_default = False,
        visibility = ["//visibility:public"],
    )

# buildifier: disable=unnamed-macro
def clippy_flags():
    """This setting may be used to pass extra options to clippy from the command line.

    It applies across all targets.
    """
    _clippy_flags(
        name = "clippy_flags",
        build_setting_default = [],
    )

# buildifier: disable=unnamed-macro
def clippy_flag():
    """Add a custom clippy flag from the command line with `--@rules_rust//rust/settings:clippy_flag`.

    Multiple uses are accumulated and appended after the `extra_rustc_flags`.
    """
    _clippy_flag(
        name = "clippy_flag",
        build_setting_default = [],
    )

# buildifier: disable=unnamed-macro
def extra_rustc_flags():
    """This setting may be used to pass extra options to rustc from the command line in non-exec configuration.

    It applies across all targets whereas the rustc_flags option on targets applies only
    to that target. This can be useful for passing build-wide options such as LTO.
    """
    _extra_rustc_flags(
        name = "extra_rustc_flags",
        build_setting_default = [],
    )

# buildifier: disable=unnamed-macro
def extra_rustc_flag():
    """Add additional rustc_flag from the command line with `--@rules_rust//rust/settings:extra_rustc_flag`.

    Multiple uses are accumulated and appended after the `extra_rustc_flags`.
    """
    _extra_rustc_flag(
        name = "extra_rustc_flag",
        build_setting_default = [],
    )

# buildifier: disable=unnamed-macro
def extra_exec_rustc_flags():
    """This setting may be used to pass extra options to rustc from the command line in exec configuration.

    It applies across all targets whereas the rustc_flags option on targets applies only
    to that target. This can be useful for passing build-wide options such as LTO.
    """
    _extra_exec_rustc_flags(
        name = "extra_exec_rustc_flags",
        build_setting_default = [],
    )

# buildifier: disable=unnamed-macro
def extra_exec_rustc_flag():
    """Add additional rustc_flags in the exec configuration from the command line with `--@rules_rust//rust/settings:extra_exec_rustc_flag`.

    Multiple uses are accumulated and appended after the extra_exec_rustc_flags.
    """
    _extra_exec_rustc_flag(
        name = "extra_exec_rustc_flag",
        build_setting_default = [],
    )

# buildifier: disable=unnamed-macro
def experimental_per_crate_rustc_flag():
    """Add additional rustc_flag to matching crates from the command line with `--@rules_rust//rust/settings:experimental_per_crate_rustc_flag`.

    The expected flag format is prefix_filter@flag, where any crate with a label or execution path starting
    with the prefix filter will be built with the given flag. The label matching uses the canonical form of
    the label (i.e `//package:label_name`). The execution path is the relative path to your workspace directory
    including the base name (including extension) of the crate root. This flag is not applied to the exec
    configuration (proc-macros, cargo_build_script, etc). Multiple uses are accumulated.
    """
    _per_crate_rustc_flag(
        name = "experimental_per_crate_rustc_flag",
        build_setting_default = [],
    )

# buildifier: disable=unnamed-macro
def incompatible_do_not_include_data_in_compile_data():
    """A flag to control whether to include data files in compile_data.
    """
    incompatible_flag(
        name = "incompatible_do_not_include_data_in_compile_data",
        build_setting_default = True,
        issue = "https://github.com/bazelbuild/rules_rust/issues/2977",
    )

def codegen_units():
    """The default value for `--codegen-units` which also affects resource allocation for rustc actions.

    Note that any value 0 or less will prevent this flag from being passed by Bazel and allow rustc to
    perform it's default behavior.

    https://doc.rust-lang.org/rustc/codegen-options/index.html#codegen-units
    """
    int_flag(
        name = "codegen_units",
        build_setting_default = -1,
    )