docs(registry): add musl vs glibc section to registry style guide

[suzuki-shunsuke]

Summary

This PR adds a "musl vs glibc" section to the registry style guide (website/docs/develop-registry/registry-style-guide.md), describing how to choose between musl and glibc pre-built binaries when both are available for a package.

What the section covers

• The decision is driven by whether the musl build is static or dynamic. Static musl binaries depend on no host libc and are portable; dynamic musl binaries require the host libc to be musl.
• How to detect static vs dynamic: file, with ldd, readelf -d, or objdump -p | grep NEEDED as fallbacks. readelf -d and objdump are noted as safer than ldd because they don't execute the binary.
• Worked example using claude code v2.1.126 (linux-arm64-musl), showing the output of all four commands. The interpreter is /lib/ld-musl-aarch64.so.1 and the NEEDED entry is libc.musl-aarch64.so.1, demonstrating that this build is dynamically linked to musl.
• Rule 1 — when the musl build is static: always use the musl build. The rationale: it works fine, it's simpler than juggling variants, the glibc build can break depending on host glibc version, aqua does not currently check glibc version, and the size benefit of glibc is not worth the complexity.
• Rule 2 — when the musl build is dynamic: default to the glibc build and use the musl build via variants only on environments where it works (e.g. Alpine). Keeping glibc as the default preserves backward compatibility with aqua versions before variants was supported (variants requires aqua >= v2.58.0).
• A pointer to the variants reference at the end.

Test plan

• Confirm the new section renders correctly in the docs site (npm run start under website/).
• Confirm there is no remaining Japanese in the file: rg '[\p{Hiragana}\p{Katakana}\p{Han}]' website/docs/develop-registry/registry-style-guide.md should return no matches.
• Spot-check that the example commands (file, ldd, readelf -d, objdump -p | grep NEEDED) produce equivalent musl/dynamic indications on a real musl binary.

🤖 Generated with Claude Code

[coderabbitai]

📝 Walkthrough

Walkthrough

A new "musl vs glibc" section was added to the registry style guide, providing guidance on determining whether a musl binary is statically or dynamically linked and prescribing which variant to use based on the binary type.

Changes

Registry Style Guide Documentation

Layer / File(s)	Summary
Documentation website/docs/develop-registry/registry-style-guide.md	New "musl vs glibc" section added, covering inspection methods (file, ldd, readelf -d, objdump -p), decision rules for static vs. dynamic binaries, concrete example output, and guidance to default to glibc when musl is dynamically linked.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Possibly related PRs

• feat(registry)!: rename libc variant value gnu to glibc #4755: Modifies registry documentation around musl vs. glibc variant selection guidance.

Poem

🐰 A binary mystery, now made clear,
musl or glibc? Which one, dear?
With file and ldd as your trusty tool,
The registry guide now makes it cool!
Static or dynamic, the choice is bright,
Your dependencies linked just right! ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description check	✅ Passed	The PR description is comprehensive, detailed, and well-structured. It explains the changes, covers all relevant aspects of the musl vs glibc section, provides context for decision-making rules, and includes a concrete test plan.
Title check	✅ Passed	The pull request title accurately describes the main change: adding a musl vs glibc section to the registry style guide.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/musl-glibc-style-guide

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@website/docs/develop-registry/registry-style-guide.md`:
- Around line 193-197: The doc text currently claims variants require aqua >=
v2.58.0; change this to the correct minimum version v1.12.0. Update the sentence
that reads "this requires aqua >= v2.58.0, which supports variants" to instead
reference "this requires aqua >= v1.12.0, which supports variants" and ensure
any other occurrences in registry-style-guide.md that mention the variants
version requirement are updated consistently; keep the existing links to
[variants] unchanged.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: dc65e796-f89e-459d-bf9a-8e4e3a9ae641

📥 Commits

Reviewing files that changed from the base of the PR and between 52873a4 and ccb35f9.

📒 Files selected for processing (1)

• website/docs/develop-registry/registry-style-guide.md

[coderabbitai]

⚠️ Potential issue | 🟠 Major

🧩 Analysis chain

🌐 Web query:

When was variantssupport added toaqua (minimum version)? Is it v2.58.0?

💡 Result:

Variants support in aqua was added with the supported_envs feature (variants of OS/arch). The original implementation landed in v1.12.0 (merged June 18, 2022). Therefore, it is not tied to v2.58.0; v2.58.0 is far later than the version where variants/OS-arch environment support was introduced. Answer to your specific question: No, variants support was not first added in v2.58.0. It dates back to v1.12.0.

Citations:

• 1: feat: add supported_envs #884
• 2: f09935e

---

Update version requirement for variants support.

Line 195 incorrectly states that variants requires aqua >= v2.58.0. Variants support was actually added in v1.12.0 (June 18, 2022). Update the version requirement to reflect the actual minimum version where this feature was introduced.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@website/docs/develop-registry/registry-style-guide.md` around lines 193 -
197, The doc text currently claims variants require aqua >= v2.58.0; change this
to the correct minimum version v1.12.0. Update the sentence that reads "this
requires aqua >= v2.58.0, which supports variants" to instead reference "this
requires aqua >= v1.12.0, which supports variants" and ensure any other
occurrences in registry-style-guide.md that mention the variants version
requirement are updated consistently; keep the existing links to [variants]
unchanged.

[suzuki-shunsuke]

Variants support was actually added in v1.12.0 (June 18, 2022).

This is completely wrong. I'm not sure why you're misunderstanding.

[coderabbitai]

@suzuki-shunsuke, I apologize for the incorrect review comment. My web search conflated the general OS/arch variant support (via supported_envs, added in v1.12.0) with the specific variants field in overrides registry config, which is indeed a distinct, newer feature planned for v2.58.0. You are correct, and the version requirement in the documentation is accurate.

(╯°□°）╯ (dropping my wrong conclusion)

---

✏️ Learnings added

Learnt from: suzuki-shunsuke
Repo: aquaproj/aqua PR: 4756
File: website/docs/develop-registry/registry-style-guide.md:193-197
Timestamp: 2026-05-03T01:58:08.826Z
Learning: In the aquaproj/aqua project, the specific `variants` field in registry `overrides` (referenced at `/docs/reference/registry-config/overrides#variants`) is a distinct feature introduced in aqua v2.58.0. Do not confuse it with the general OS/arch variant support (`supported_envs`) which was added much earlier in v1.12.0. The registry style guide correctly states `aqua >= v2.58.0` as the minimum version requirement for the `variants` feature in overrides.

Note: Learnings are effective only in the context of similar code segments. To apply general coding guidelines, please configure review instructions. You can manage existing learnings in the app.