Skip to content

feat(toolkit-macros): compile-time gear dependency linking via re-exports #4146

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
MikeFalcon77 merged 15 commits into from
Jul 17, 2026
Merged

feat(toolkit-macros): compile-time gear dependency linking via re-exports #4146

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
15 commits
Select commit Hold shift + click to select a range
cfbf41f
Add reexports for gears deps generation to gears macro
Jun 26, 2026
bbb03d4
Add system gears decls to Cargo.toml
Jun 26, 2026
f86aae8
Add full crates for deps exporting
Jun 26, 2026
1b147f7
Fix: Don't add reexports on tests
Jun 26, 2026
d60ea06
Anchor re-export path with leading :: to avoid module-scope shadowing
Jun 26, 2026
11f5903
Add full crates for deps exporting to new modules as well
Jul 13, 2026
d9427fe
Update exported versions
Jul 13, 2026
71456e8
Add the new "unused" crates to shear ignored list
Jul 14, 2026
b5fdbb6
Update lock file
Jul 16, 2026
eef3dc0
Change gears macro to use idents in deps
Jul 16, 2026
9b0501d
Adapt docs / examples / tests
Jul 16, 2026
cec1f7f
Adapt gears macro invocations to new format
Jul 16, 2026
65ff21e
Fix: deps_not_array test
Jul 16, 2026
0cd439e
Free up some disk space before llvm-cov and shear CI jobs
Jul 16, 2026
ea5f581
docs: document cargo-shear ignore list requirement for gear deps
Jul 16, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 20 additions & 0 deletions .github/workflows/ci.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -348,6 +348,16 @@ jobs:
env:
RUSTUP_TOOLCHAIN: nightly-2026-04-16
steps:
- name: Free disk space
uses: jlumbroso/free-disk-space@54081f138730dfa15788a46383842cd2f914a1be # v1.3.1
with:
tool-cache: false
android: true
dotnet: true
haskell: true
large-packages: true
swap-storage: true

- name: Checkout
uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2

Expand Down Expand Up @@ -437,6 +447,16 @@ jobs:
env:
RUSTUP_TOOLCHAIN: nightly-2026-04-16
steps:
- name: Free disk space
uses: jlumbroso/free-disk-space@54081f138730dfa15788a46383842cd2f914a1be # v1.3.1
with:
tool-cache: false
android: true
dotnet: true
haskell: true
large-packages: true
swap-storage: true

- name: Checkout
uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
with:
Expand Down
17 changes: 17 additions & 0 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -89,6 +89,23 @@ Follow the coding standards and guidelines:

Gear directories under `gears/` must use kebab-case (validated by `tools/scripts/validate_gear_names.py` and enforced in CI).

#### Gear dependencies and `cargo-shear`

When a gear declares dependencies via `#[gear(deps = [...])]`, the dep entries are

@coderabbitai coderabbitai Bot Jul 17, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Use the actual toolkit::gear attribute in the example.

The documented syntax omits the toolkit:: namespace, while this feature is exposed as #[toolkit::gear(deps = [...])]. As written, contributors may copy an attribute that does not resolve.

Proposed fix 
-When a gear declares dependencies via `#[gear(deps = [...])]`, the dep entries are
+When a gear declares dependencies via `#[toolkit::gear(deps = [...])]`, the dep entries are
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
When a gear declares dependencies via `#[gear(deps = [...])]`, the dep entries are
When a gear declares dependencies via `#[toolkit::gear(deps = [...])]`, the dep entries are
🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@CONTRIBUTING.md` at line 94, Update the dependency-attribute example in
CONTRIBUTING.md to use the fully qualified toolkit::gear syntax, including the
namespace in the attribute declaration. Preserve the existing deps example and
surrounding documentation.

**crate identifiers** (snake_case). The runtime gear name is derived by replacing
underscores with hyphens (`authn_resolver` → `"authn-resolver"`), matching the
convention that `lib-name == gear-name` across the workspace.

The macro generates hidden `pub use` re-exports that force the linker to keep each
dependency's `inventory::submit!` registration alive. Because these re-exports only
exist in macro-expanded code, `cargo-shear` cannot see them and will flag the
dependency crates as unused.

**When adding a new gear dependency**, add the crate name to the
`[workspace.metadata.cargo-shear] ignored` list in the workspace `Cargo.toml`.
Forgetting this will cause the `shear` CI job to fail with an error unrelated to
your actual change.

Always include unit tests when introducing new code.

### 2.4. Run Code Quality Checks
Expand Down
42 changes: 42 additions & 0 deletions Cargo.lock
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

22 changes: 22 additions & 0 deletions Cargo.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -279,6 +279,14 @@ cf-gears-system-sdk-directory = { version = "0.1.37", path = "libs/system-sdks/s

# System gears
types-registry = { package = "cf-gears-types-registry", version = "0.1.23", path = "gears/system/types-registry/types-registry" }
authn-resolver = { package = "cf-gears-authn-resolver", version = "0.2.17", path = "gears/system/authn-resolver/authn-resolver" }
authz-resolver = { package = "cf-gears-authz-resolver", version = "0.1.24", path = "gears/system/authz-resolver/authz-resolver" }
tenant-resolver = { package = "cf-gears-tenant-resolver", version = "0.1.22", path = "gears/system/tenant-resolver/tenant-resolver" }
resource-group = { package = "cf-gears-resource-group", version = "0.1.4", path = "gears/system/resource-group/resource-group" }
credstore = { package = "cf-gears-credstore", version = "0.1.23", path = "gears/credstore/credstore" }
oagw = { package = "cf-gears-oagw", version = "0.2.26", path = "gears/system/oagw/oagw" }
account-management = { package = "cf-gears-account-management", version = "0.2.0", path = "gears/system/account-management/account-management" }
usage-collector = { package = "cf-gears-usage-collector", version = "0.1.0", path = "gears/system/usage-collector/usage-collector" }
Comment thread
maurolacy marked this conversation as resolved.

cf-gears-cluster-sdk = { version = "0.1.0", path = "gears/system/cluster/cluster-sdk" }
cf-gears-cluster-conformance = { version = "0.1.0", path = "gears/system/cluster/cluster-conformance" }
Expand Down Expand Up @@ -592,3 +600,17 @@ gts-macros = "0.11.0"

[workspace.metadata.cargo-shear]
ignored-paths = ["**/tests/ui/**"]
# Gear crate deps only consumed by macro-generated re-exports in #[toolkit::gear(deps = [...])].
# cargo-shear cannot trace usage through proc-macro expansion, so these appear unused.
ignored = [
"account-management",
"authn-resolver",
"authz-resolver",
"credstore",
"grpc_hub",
"oagw",
"resource-group",
"tenant-resolver",
"types-registry",
"usage-collector",
]
5 changes: 5 additions & 0 deletions examples/oop-gears/calculator-gateway/calculator-gateway/Cargo.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@ description = "Calculator gateway module - example in-process REST service"
[dependencies]
# External SDKs (dependencies on other modules)
calculator-sdk = { path = "../../calculator/calculator-sdk" }
calculator = { path = "../../calculator/calculator" }

# ToolKit
toolkit = { workspace = true }
Expand All @@ -35,3 +36,7 @@ thiserror = { workspace = true }
anyhow = { workspace = true }
tracing = { workspace = true }
inventory = { workspace = true }

[package.metadata.cargo-shear]
# Gear dep only consumed by macro-generated re-export in #[toolkit::gear(deps = [...])].
ignored = ["calculator"]
Comment thread
maurolacy marked this conversation as resolved.
Loading
Loading