Skip to content

Commit

Permalink
Added documentation for all rules_rust settings (#3114)
Browse files Browse the repository at this point in the history
There is no way to document symbols in a BUILD file or anything that is
not a rule, macro, aspect, or provider. So to be able to generate
documentation for settings, I've added `settings.bzl` files which
contain macros with docstrings to do the trick.
  • Loading branch information
UebelAndre authored Dec 17, 2024
1 parent 7a1f037 commit eb1fe7d
Show file tree
Hide file tree
Showing 39 changed files with 1,575 additions and 2,689 deletions.
10 changes: 7 additions & 3 deletions cargo/BUILD.bazel
Original file line number Diff line number Diff line change
@@ -1,9 +1,13 @@
load("@bazel_skylib//:bzl_library.bzl", "bzl_library")

package(default_visibility = ["//visibility:public"])
exports_files(["defs.bzl"])

bzl_library(
name = "bzl_lib",
srcs = glob(["**/*.bzl"]),
deps = ["//cargo/private:bzl_lib"],
srcs = glob(["*.bzl"]),
visibility = ["//visibility:public"],
deps = [
"//cargo/private:bzl_lib",
"//cargo/settings:bzl_lib",
],
)
5 changes: 4 additions & 1 deletion cargo/defs.bzl
Original file line number Diff line number Diff line change
@@ -1,4 +1,7 @@
"""Common definitions for the `@rules_rust//cargo` package"""
"""# Cargo
Common definitions for the `@rules_rust//cargo` package
"""

load(
"//cargo/private:cargo_bootstrap.bzl",
Expand Down
59 changes: 24 additions & 35 deletions cargo/settings/BUILD.bazel
Original file line number Diff line number Diff line change
@@ -1,43 +1,32 @@
load("@bazel_skylib//rules:common_settings.bzl", "bool_flag", "string_list_flag")
load("@bazel_skylib//:bzl_library.bzl", "bzl_library")
load(
":settings.bzl",
"cargo_manifest_dir_filename_suffixes_to_retain",
"debug_std_streams_output_group",
"experimental_symlink_execroot",
"incompatible_runfiles_cargo_manifest_dir",
"use_default_shell_env",
)

package(default_visibility = ["//visibility:public"])

# A flag for which causes `cargo_build_script` to symlink the execroot of the action to
# the `CARGO_MANIFEST_DIR` where the scripts are run.
bool_flag(
name = "experimental_symlink_execroot",
build_setting_default = False,
)
exports_files(["settings.bzl"])

# A flag which causes `cargo_build_script` to write an explicit `CARGO_MANFIEST_DIR`
# directory from an action instead of using runfiles directories which cannot be
# passed to downstream actions.
# https://github.com/bazelbuild/bazel/issues/15486
bool_flag(
name = "incompatible_runfiles_cargo_manifest_dir",
build_setting_default = True,
)

# A flag which determines what files are retained in `CARGO_MANIFEST_DIR` directories
# that are created in `CargoBuildScriptRun` actions.
string_list_flag(
name = "cargo_manifest_dir_filename_suffixes_to_retain",
build_setting_default = [
".lib",
".so",
bzl_library(
name = "bzl_lib",
srcs = glob(["*.bzl"]),
visibility = ["//cargo:__pkg__"],
deps = [
"@bazel_skylib//rules:common_settings",
],
)

# A flag which adds a `streams` output group to `cargo_build_script` targets that contain
# the raw `stderr` and `stdout` streams from the build script.
bool_flag(
name = "debug_std_streams_output_group",
build_setting_default = False,
)
cargo_manifest_dir_filename_suffixes_to_retain()

# A flag which controls the global default of `ctx.actions.run.use_default_shell_env`
# for `cargo_build_script` targets.
bool_flag(
name = "use_default_shell_env",
build_setting_default = True,
)
debug_std_streams_output_group()

experimental_symlink_execroot()

incompatible_runfiles_cargo_manifest_dir()

use_default_shell_env()
56 changes: 56 additions & 0 deletions cargo/settings/settings.bzl
Original file line number Diff line number Diff line change
@@ -0,0 +1,56 @@
"""# Cargo settings
Definitions for all `@rules_rust//cargo` settings
"""

load("@bazel_skylib//rules:common_settings.bzl", "bool_flag", "string_list_flag")

def experimental_symlink_execroot():
"""A flag for which causes `cargo_build_script` to symlink the execroot of the action to \
the `CARGO_MANIFEST_DIR` where the scripts are run.
"""
bool_flag(
name = "experimental_symlink_execroot",
build_setting_default = False,
)

def incompatible_runfiles_cargo_manifest_dir():
"""A flag which causes `cargo_build_script` to write an explicit `CARGO_MANFIEST_DIR` \
directory from an action instead of using runfiles directories which cannot be \
passed to downstream actions.
https://github.com/bazelbuild/bazel/issues/15486
"""
bool_flag(
name = "incompatible_runfiles_cargo_manifest_dir",
build_setting_default = True,
)

def cargo_manifest_dir_filename_suffixes_to_retain():
"""A flag which determines what files are retained in `CARGO_MANIFEST_DIR` directories \
that are created in `CargoBuildScriptRun` actions.
"""
string_list_flag(
name = "cargo_manifest_dir_filename_suffixes_to_retain",
build_setting_default = [
".lib",
".so",
],
)

def debug_std_streams_output_group():
"""A flag which adds a `streams` output group to `cargo_build_script` targets that contain \
the raw `stderr` and `stdout` streams from the build script.
"""
bool_flag(
name = "debug_std_streams_output_group",
build_setting_default = False,
)

def use_default_shell_env():
"""A flag which controls the global default of `ctx.actions.run.use_default_shell_env` for `cargo_build_script` targets.
"""
bool_flag(
name = "use_default_shell_env",
build_setting_default = True,
)
Loading

0 comments on commit eb1fe7d

Please sign in to comment.