Cédric Barreteau

This commit significantly **improves and restructures the documentation** for **Buck2's build configuration system**, making it more accessible for both end-users and rule authors. It introduces a **new conceptual page** at `docs/concepts/transitions.md` and expands `docs/concepts/configurations.md` to comprehensively cover platforms, modifiers, and transitions. Existing information was **refactored**, moving general build configuration concepts from `docs/rule_authors/` to `docs/concepts/` while the rule author documentation now focuses on implementation details. This **documentation enhancement** provides a clearer understanding of complex configuration topics and includes clarifications for `$(location_exec)` and `$(exe_target)` macros.

This commit performs a **documentation improvement** by moving existing configuration comments into formal documentation strings within the `prelude/decls/core_rules.bzl` file. It specifically **updates and adds documentation** for core Buck2 rules such as `config_setting`, `constraint_setting`, `constraint_value`, `constraint`, and `platform`. This change enhances the **clarity and discoverability** of how these fundamental configuration and constraint rules function. The primary impact is improved user experience through more comprehensive and accessible reference documentation for the **Buck2 build system's core configuration capabilities**.

This commit primarily **updates Pyrefly's documentation** to detail **integration with Buck2**, adding new sections to `website/docs/configuration.mdx` that cover `build-system` configuration and custom query options. It also **improves internal code clarity** by rephrasing a description for the `command` field within `CustomQueryArgs` in `crates/pyrefly_build/src/query/custom.rs`. This **documentation update** and **maintenance** work enhances user understanding of Pyrefly's build system setup and ensures consistent formatting. The changes provide clearer guidance for users adopting Buck2 with Pyrefly.

This commit **reformats** the **configuration documentation** located at `website/docs/configuration.mdx` to ensure consistency with the project's Prettier rules. It specifically updates bullet point styles from asterisks to hyphens and adjusts italicization within the document. This is a **maintenance** task that improves the readability and aesthetic consistency of the project's user-facing documentation. The change has no functional impact, only affecting the presentation of the configuration guide.

This commit introduces a **new capability** to the `compilation_database.bxl` script, enabling it to accept **configured target expressions** for its `targets` argument. This **enhancement** significantly improves the flexibility of the **compilation database generation** process within the C++ toolchain. Previously constrained by the absence of `cli_args.configured_target_expr()`, the script can now handle more precise target specifications, benefiting users who require fine-grained control over compilation database creation.

This commit delivers a **bug fix** for the `buck2_client_ctx` module, specifically within the `superconsole` subscriber. It modifies the `truncate` function in `app/buck2_client_ctx/src/subscribers/superconsole.rs` to correctly handle string slicing at character boundaries. By utilizing `ceil_char_boundary` and `floor_char_boundary`, this change prevents a panic that previously occurred when truncating messages containing multi-byte (non-ASCII) characters. This ensures the client context reliably displays truncated strings without crashing, improving the stability of the `superconsole` output.

This commit **fixes a minor output formatting bug** within the **`buck2 expand-external-cells` command** in the `buck2_client` application. Previously, the command's reminder text was missing a newline, which caused the shell prompt to render immediately after the output on the same line. By adding a missing newline character to the `REMINDER_TEXT` constant in `app/buck2_client/src/commands/expand_external_cell.rs`, this change ensures proper terminal output. This **improves the user experience** by providing a cleaner and more readable command-line interface.

This commit **reverts a previous change** to the `prelude/cxx/tools/compilation_database.bxl` script, specifically undoing the logic for using compile commands from source library targets. This **bug fix** addresses a critical regression that made **compilation database generation** "essentially unusable" for trivial targets. By restoring the prior, simpler logic within the `_make_entry` and `_impl` functions, it ensures the correct and reliable creation of compilation database entries for C++ projects. This **maintenance** action resolves a significant issue in the **developer tooling** by restoring functionality for C++ compilation database users.

This commit introduces a **new capability** for the **`buck2 test` command**, allowing users to explicitly build `DefaultInfo` and `RunInfo` providers during test execution. New command-line options, such as `--build-default-info` and `--build-run-info`, are added to the `buck2 test` client and communicated through an updated `TestRequest` in the **Buck2 daemon protocol**. The **test execution logic** within `buck2_test` is modified to conditionally construct these providers, providing greater control over the build artifacts generated during testing. This enhancement improves the flexibility of `buck2 test` for debugging and specific build scenarios, supported by updated help output and new test cases for build report generation.

This commit **updates the Nativelink example README** to improve the accuracy and reliability of its documentation and build instructions. It **fixes outdated links** to basic configuration, ensuring users can easily navigate to relevant information. Additionally, the commit **updates the build process** by specifying the use of locked versions when building Nativelink from source, which enhances reproducibility and stability for developers. This is a **documentation fix and maintenance update** that streamlines the onboarding and development experience for the Nativelink subsystem.

This commit **adds comprehensive documentation** for the `modifiers` feature, significantly improving user understanding and adoption of this configuration mechanism. It introduces new conceptual guides and detailed how-to articles covering `modifiers` setup, application via the command line, integration with `PACKAGE` files, and usage on individual targets. This **documentation enhancement** provides crucial information for users to effectively leverage `modifiers` within their projects. The new pages, including `docs/concepts/modifiers.md` and several `docs/users/how_tos/modifiers_*.md` files, are seamlessly integrated into the website's navigation via `website/sidebars.ts`.

This commit **enhances the compilation database BXL script** (`prelude/cxx/tools/compilation_database.bxl`) by **adding support for modifiers**. This **new capability** allows for more flexible and precise resolution of configured targets during the compilation database generation process. Users can now apply modifiers, such as C++ standard versions (e.g., `-m cxx26`), to influence how targets are processed, thereby improving the utility and configurability of the generated compilation database. This change primarily affects the **C++ toolchain integration** within Buck2, providing greater control over build configurations reflected in the database.

This commit **enhances the Buck2 documentation** by introducing new pages that comprehensively explain the concept of **toolchains** and provide practical guidance for **rule authors on writing custom toolchains**. It adds `docs/concepts/toolchain.md` to clarify this fundamental Buck2 feature and `docs/rule_authors/writing_toolchains.md` to assist developers in extending the system. The `website/sidebars.ts` configuration is also updated to ensure these new, critical resources are easily discoverable within the project's official website. This **documentation improvement** significantly aids both users in understanding Buck2's architecture and developers in implementing custom build logic.

This commit **adds new documentation** explaining the concept of **labels** within the **Buck2 build system**. A new page, `docs/concepts/labels.md`, is introduced to detail what labels are and how they are used. The `website/sidebars.ts` file is also updated to ensure this new conceptual documentation is accessible via the **Buck2 website's navigation**. This **documentation improvement** aims to enhance user understanding and adoption of Buck2's labeling capabilities.