| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 0 | 6 | 4 | 0% |
| Commands | 0 | 0 | 0 | — |
| Section tags | 0 | 0 | 3 | 0% |
What each file covers
Sections
0 shared · 6 only in A · 4 only in B- − gRPC Core Configuration
- − Overarching Purpose
- − Core Concepts
- − Files
- − Major Classes
- − Notes
- + gRPC C++ Agents Collaboration Guide
- + Preferred Tools & Libraries
- + Code Style & Conventions
- + About gRPC
Commands
neither file has anySection tags
0 shared · 0 only in A · 3 only in B- + code-style
- + dependencies
- + do-not
Line diff
grpc/grpc · src/core/config/AGENTS.md
@@ −1 @@
1# gRPC Core Configuration
2
3This directory contains the fundamental building blocks for configuring the gRPC core library.
4
5See also: [gRPC Core overview](../AGENTS.md)
6
7## Overarching Purpose
8
9This directory manages both static configuration (via config variables) and dynamic configuration (via pluggable components). It provides a centralized and extensible way to configure the behavior of the gRPC core library.
10
11## Core Concepts
12
13* **`ConfigVars`**: `ConfigVars` is a singleton that holds configuration properties for gRPC. These properties are loaded from environment variables, Abseil flags, and can be programmatically overridden. This provides a unified way to access configuration values throughout the library. The values are automatically generated from `config_vars.yaml`.
14* **`CoreConfiguration`**: `CoreConfiguration` is a singleton that acts as a central registry for all pluggable components in gRPC. It uses a builder pattern (`CoreConfiguration::Builder`) to allow different parts of the system to register factories for things like resolvers, load balancing policies, handshakers, and channel filters. This is the primary mechanism for extending gRPC's functionality.
15
16## Files
17
18* **`config_vars.h`, `config_vars.cc`**: These files define the `ConfigVars` class.
19* **`config_vars.yaml`**: This file contains the definitions of all of the configuration variables that are available in gRPC. The `config_vars.h` and `config_vars.cc` files are generated from this file.
20* **`core_configuration.h`, `core_configuration.cc`**: These files define the `CoreConfiguration` class and its builder.
21* **`load_config.h`, `load_config.cc`**: These files provide helper functions to load configuration values from various sources (flags, environment variables, and programmatic overrides) with a defined order of precedence.
22
23## Major Classes
24
25* **`grpc_core::ConfigVars`**: A singleton class that provides access to gRPC's core configuration variables. It's initialized once and can be accessed via `ConfigVars::Get()`.
26* **`grpc_core::CoreConfiguration`**: A singleton that holds registries for various pluggable components. It's constructed via a `Builder` pattern, and is the main extension point for adding functionality to gRPC.
27* **`grpc_core::CoreConfiguration::Builder`**: A builder class that is used to construct the `CoreConfiguration` singleton. It provides methods for registering factories for the different types of pluggable components.
28
29## Notes
30
31* The configuration system is designed to be highly extensible. The `CoreConfiguration` class and its builder pattern are key to this design, allowing for a la carte inclusion of features.
32* The `ConfigVars` are a good example of how gRPC uses code generation to ensure a single source of truth for configuration variables.
33* The `CoreConfiguration` is initialized at startup, and it can be customized by registering new factories with the builder. This is the primary mechanism for extending gRPC's functionality. For example, to add a new load balancing policy, you would implement the `LoadBalancingPolicyFactory` interface and then register your factory with the `CoreConfiguration::Builder`.
34
grpc/grpc · AGENTS.md
@@ +1 @@
1# gRPC C++ Agents Collaboration Guide
2
3This document outlines conventions and best practices for AI-assisted development in the gRPC C++ codebase.
4
5## Preferred Tools & Libraries
6* Prefer gRPC types before absl.
7* Prefer std types when available, use absl types when not
8* Prefer `std::optional` over `absl::optional`
9* gRPC uses C++17, so we can't use C++20 onwards types.
10* The Python implementation cannot depend on the protobuf library, so any shared libraries must expose a C-style API that does not rely on C++ protobuf types.
11
12## Code Style & Conventions
13* `#include <grpc/support/port_platform.h>` is not required unless its macros are needed for compilation.
14* Only include headers that are actively used.
15* Abseil headers are sorted before gRPC headers.
16* For public api headers (in `include/grpc`) we use `<grpc/...>`.
17 * Example: `#include <grpc/grpc.h>`
18* Prefer explicit types over `std::pair` or `std::tuple` for return types.
19* Use `LOG(ERROR)` from `absl/log/log.h` for logging errors, never use `std::cerr` or `gpr_log`.
20* The `fuzztest.h` header is located at `fuzztest/fuzztest.h`.
21
22## About gRPC
23* gRPC uses its own macros for Bazel libraries, tests, etc. Each directory should have a `grpc_package` declaration. For libraries use `grpc_cc_library`, for tests `grpc_cc_test`.
24* Dependencies on non-gRPC libraries (like gtest or absl) are listed in the `external_deps` attribute.
25* The `:grpc` BUILD target is not allowed to depend on the C++ protobuf library, either directly or transitively.
26* Build files for implementation code are typically located in `src/core/BUILD` and `BUILD`. Do not add new `BUILD` files under the `src/` tree without explicit instruction.
27* Tests are located in `test/core` and `test/cpp` (corresponding to the `src` directories). These test directories contain their own `BUILD` files.
28* Fuzz tests use `fuzztest_main` instead of `gtest_main`.
29* When depending on a `grpc_proto_library`, the name of the `cc_library` target is the same as the `name` of the `grpc_proto_library` rule itself, not `[name]_cc_proto` as one might expect from standard Bazel `cc_proto_library` rules. The build system error messages can be misleading in this case.
30* The 'gtest' external_dep also includes 'gmock'.
31* All `upb` related build rules (`grpc_upb_proto_library`, `grpc_upb_proto_reflection_library`) for protos defined anywhere in the repository must be defined in the root `BUILD` file. They should not be placed in the `BUILD` file of the subdirectory where the proto is located.
32* Core end-to-end tests are defined in `test/core/end2end/BUILD` using the `grpc_core_end2end_test_suite` macro. This macro generates multiple `grpc_cc_test` targets by combining a configuration file (like `end2end_http2_config.cc`) with individual test implementation files located in `test/core/end2end/tests/`. The final test target name is created by appending `_test` to the `name` attribute of the macro. For example, `grpc_core_end2end_test_suite(name = "end2end_http2", ...)` generates the test target `//test/core/end2end:end2end_http2_test`.
33* Unused named parameters is a compilation failure.
34
@@ −1 +1 @@
1−# gRPC Core Configuration
1+# gRPC C++ Agents Collaboration Guide
22
3−This directory contains the fundamental building blocks for configuring the gRPC core library.
3+This document outlines conventions and best practices for AI-assisted development in the gRPC C++ codebase.
44
5−See also: [gRPC Core overview](../AGENTS.md)
5+## Preferred Tools & Libraries
6+* Prefer gRPC types before absl.
7+* Prefer std types when available, use absl types when not
8+* Prefer `std::optional` over `absl::optional`
9+* gRPC uses C++17, so we can't use C++20 onwards types.
10+* The Python implementation cannot depend on the protobuf library, so any shared libraries must expose a C-style API that does not rely on C++ protobuf types.
611
7−## Overarching Purpose
12+## Code Style & Conventions
13+* `#include <grpc/support/port_platform.h>` is not required unless its macros are needed for compilation.
14+* Only include headers that are actively used.
15+* Abseil headers are sorted before gRPC headers.
16+* For public api headers (in `include/grpc`) we use `<grpc/...>`.
17+ * Example: `#include <grpc/grpc.h>`
18+* Prefer explicit types over `std::pair` or `std::tuple` for return types.
19+* Use `LOG(ERROR)` from `absl/log/log.h` for logging errors, never use `std::cerr` or `gpr_log`.
20+* The `fuzztest.h` header is located at `fuzztest/fuzztest.h`.
821
9−This directory manages both static configuration (via config variables) and dynamic configuration (via pluggable components). It provides a centralized and extensible way to configure the behavior of the gRPC core library.
10−
11−## Core Concepts
12−
13−* **`ConfigVars`**: `ConfigVars` is a singleton that holds configuration properties for gRPC. These properties are loaded from environment variables, Abseil flags, and can be programmatically overridden. This provides a unified way to access configuration values throughout the library. The values are automatically generated from `config_vars.yaml`.
14−* **`CoreConfiguration`**: `CoreConfiguration` is a singleton that acts as a central registry for all pluggable components in gRPC. It uses a builder pattern (`CoreConfiguration::Builder`) to allow different parts of the system to register factories for things like resolvers, load balancing policies, handshakers, and channel filters. This is the primary mechanism for extending gRPC's functionality.
15−
16−## Files
17−
18−* **`config_vars.h`, `config_vars.cc`**: These files define the `ConfigVars` class.
19−* **`config_vars.yaml`**: This file contains the definitions of all of the configuration variables that are available in gRPC. The `config_vars.h` and `config_vars.cc` files are generated from this file.
20−* **`core_configuration.h`, `core_configuration.cc`**: These files define the `CoreConfiguration` class and its builder.
21−* **`load_config.h`, `load_config.cc`**: These files provide helper functions to load configuration values from various sources (flags, environment variables, and programmatic overrides) with a defined order of precedence.
22−
23−## Major Classes
24−
25−* **`grpc_core::ConfigVars`**: A singleton class that provides access to gRPC's core configuration variables. It's initialized once and can be accessed via `ConfigVars::Get()`.
26−* **`grpc_core::CoreConfiguration`**: A singleton that holds registries for various pluggable components. It's constructed via a `Builder` pattern, and is the main extension point for adding functionality to gRPC.
27−* **`grpc_core::CoreConfiguration::Builder`**: A builder class that is used to construct the `CoreConfiguration` singleton. It provides methods for registering factories for the different types of pluggable components.
28−
29−## Notes
30−
31−* The configuration system is designed to be highly extensible. The `CoreConfiguration` class and its builder pattern are key to this design, allowing for a la carte inclusion of features.
32−* The `ConfigVars` are a good example of how gRPC uses code generation to ensure a single source of truth for configuration variables.
33−* The `CoreConfiguration` is initialized at startup, and it can be customized by registering new factories with the builder. This is the primary mechanism for extending gRPC's functionality. For example, to add a new load balancing policy, you would implement the `LoadBalancingPolicyFactory` interface and then register your factory with the `CoreConfiguration::Builder`.
22+## About gRPC
23+* gRPC uses its own macros for Bazel libraries, tests, etc. Each directory should have a `grpc_package` declaration. For libraries use `grpc_cc_library`, for tests `grpc_cc_test`.
24+* Dependencies on non-gRPC libraries (like gtest or absl) are listed in the `external_deps` attribute.
25+* The `:grpc` BUILD target is not allowed to depend on the C++ protobuf library, either directly or transitively.
26+* Build files for implementation code are typically located in `src/core/BUILD` and `BUILD`. Do not add new `BUILD` files under the `src/` tree without explicit instruction.
27+* Tests are located in `test/core` and `test/cpp` (corresponding to the `src` directories). These test directories contain their own `BUILD` files.
28+* Fuzz tests use `fuzztest_main` instead of `gtest_main`.
29+* When depending on a `grpc_proto_library`, the name of the `cc_library` target is the same as the `name` of the `grpc_proto_library` rule itself, not `[name]_cc_proto` as one might expect from standard Bazel `cc_proto_library` rules. The build system error messages can be misleading in this case.
30+* The 'gtest' external_dep also includes 'gmock'.
31+* All `upb` related build rules (`grpc_upb_proto_library`, `grpc_upb_proto_reflection_library`) for protos defined anywhere in the repository must be defined in the root `BUILD` file. They should not be placed in the `BUILD` file of the subdirectory where the proto is located.
32+* Core end-to-end tests are defined in `test/core/end2end/BUILD` using the `grpc_core_end2end_test_suite` macro. This macro generates multiple `grpc_cc_test` targets by combining a configuration file (like `end2end_http2_config.cc`) with individual test implementation files located in `test/core/end2end/tests/`. The final test target name is created by appending `_test` to the `name` attribute of the macro. For example, `grpc_core_end2end_test_suite(name = "end2end_http2", ...)` generates the test target `//test/core/end2end:end2end_http2_test`.
33+* Unused named parameters is a compilation failure.
3434
