Skip to content

codex: pin LIBCLANG_PATH to the default llvm, fail closed on any other libclang - #1391

Merged
bryan-minimal merged 1 commit into
mainfrom
codex-libclang-pin
Nov 10, 2026
Merged

bryan-minimal merged 1 commit into
mainfrom
codex-libclang-pin

Conversation

@bryan-minimal

@bryan-minimal bryan-minimal commented Nov 8, 2026 •

Copy link
Copy Markdown
Member

What

packages/codex/build.sh found its libclang with

export LIBCLANG_PATH="$(dirname $(find /usr/lib -name 'libclang*.so' | head -1))"

That picks by directory order. Once #1339 lands (LLVM 21 frozen as llvm-21 under /usr/lib/llvm-21, default llvm at 23 in /usr/lib), any closure that holds both has two candidates (/usr/lib/libclang.so and /usr/lib/llvm-21/lib/libclang.so), and which one bindgen gets depends on filesystem order. That hurts reproducibility, and it can also build against the wrong LLVM.

Change

  • LIBCLANG_PATH=/usr/lib is now set explicitly, pointing at the unprefixed default llvm build dep. When LIBCLANG_PATH is set, clang-sys searches only that directory.
  • The build fails if /usr/bin/llvm-config (the default llvm) or libclang.so in /usr/lib is missing, or if any /usr/lib/libclang.so*, after resolving symlinks, has a different major than llvm-config --version reports.

This is correct before #1339 too, because it pins whatever the default llvm is (21 today, 23 after). It should merge after #1339 so the first bot build covers the 23 layout, but the order doesn't matter for correctness.

Verification

No local build: build-bot / CI will build it. I ran the new block by itself against fake /usr trees, with paths substituted:

tree result
default 23 in /usr/lib + llvm-21 in /usr/lib/llvm-21 OK, /usr/lib
default 21 only (today) OK
llvm-config 23 but /usr/lib libclang 21 ERROR (fails closed)
extra libclang.so.21.1.8 in /usr/lib next to 23 ERROR
no libclang.so ERROR
no llvm-config exits (set -e / pipefail)
negative control: the old find on the first tree returns both /usr/lib/libclang.so and /usr/lib/llvm-21/lib/libclang.so, so the result depends on order

Other find | head / ls | head picks on main

I grepped packages/ and stacks/ for find|ls ... | head|tail near clang / llvm / lld / libLLVM. codex was the only toolchain-library pick. The remaining hits don't involve LLVM, so I left them alone:

  • packages/llvm/versioned-build.sh:56: find ... | head -20 lists stray files for an error message. Not a pick.
  • packages/cocoalib/build.sh:35: ls /usr/lib/libgmp.so /usr/lib64/libgmp.so | head -1 chooses between two fixed paths of one library.
  • packages/{glibc-bedrock-2.42,stage0-gcc-15.2.0,stage0-gcc-10.4.0,gcc-15.2.0-glibc}/build.sh: ls /usr/include/c++/*/<tgt>/bits/c++config.h | head -n1. This is the same hazard for GCC: if two libstdc++ header trees ever share a closure, the pick is order-dependent. It isn't affected by llvm: freeze LLVM 21 as llvm-21, switch default llvm to 23.1.5 (LLVM plan steps 6+7) #1339, so it's out of scope here, but it's worth a follow-up.

🤖 Generated with Claude Code

Summary by CodeRabbit

  • Chores
    • Improved build-time checks for LLVM and libclang compatibility. Builds now stop with an error if the expected libclang library is missing or its version doesn’t match the default LLVM version.

…r libclang

`find /usr/lib -name 'libclang*.so' | head -1` picks by directory order. Once a
prefixed llvm-<N> (e.g. llvm-21 under /usr/lib/llvm-21, pkgs#1339) shares the
closure, that pick can land on the wrong LLVM. Point clang-sys at /usr/lib (the
unprefixed default llvm build dep) and fail unless every libclang.so* there is
the major /usr/bin/llvm-config reports.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@bryan-minimal
bryan-minimal requested a review from a team as a code owner November 8, 2026 02:28
@coderabbitai

coderabbitai Bot commented Nov 8, 2026 •

Copy link
Copy Markdown
Contributor

Explain Change →

No actionable comments were generated in the recent review.

Walkthrough

The Codex build script sets LIBCLANG_PATH to /usr/lib, reads the default LLVM major version, and checks that discovered libclang.so* filenames match it.

Changes: Codex libclang build validation

Layer / File(s) Summary
Discover and validate libclang libraries
packages/codex/build.sh
The script sets LIBCLANG_PATH to /usr/lib, reads the default LLVM major version, and exits with an error if the version or libraries are missing, or if any library filename does not match that major.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related issues

  • gominimal/pkgs#996 — The issue proposes another LLVM version, while this change validates libclang against the default LLVM major when versions coexist.

Possibly related PRs

  • gominimal/pkgs#1339 — This PR changes the default and versioned LLVM package layout that the build script’s version check handles.
  • gominimal/pkgs#1061 — This PR adds versioned LLVM packages, which can coexist with the default LLVM libraries.

Suggested reviewers: norrietaylor, mitodrummer

Merge Risk: Minimal · up to 12675

No actionable merge-blocking issue was established. The package build remains to be confirmed by CI.

Pre-merge checks: Passed 5

Check name Status Explanation
Description Check Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check Passed The title names the main change: LIBCLANG_PATH is pinned to the default llvm, and the script fails when any other libclang is present. The raw summary confirms the script now pins LIBCLANG_PATH to /us…
Docstring Coverage Passed No eligible functions found in the changed files. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff with cyclomatic complexity of at least 2. Documentat…
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.
Full details: Title check

Explanation

The title names the main change: LIBCLANG_PATH is pinned to the default llvm, and the script fails when any other libclang is present. The raw summary confirms the script now pins LIBCLANG_PATH to /usr/lib, reads the default LLVM major from /usr/bin/llvm-config, and exits with an error when a libclang filename has a different major. The title is specific and matches the changeset.

Full details: Docstring Coverage

Explanation

No eligible functions found in the changed files. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff with cyclomatic complexity of at least 2. Documentation-only edits and deletions within surviving functions are included; unchanged diff context and fully deleted functions are excluded. Analyzed 0 functions across 1 files.

Finishing Touches

Generate docstrings

  • Commit to this branch
  • Create a new PR
Generate unit tests (beta)

  • Commit to this branch
  • Create a new PR
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts
Recent review info

Run configuration

Commits

Reviewing files that changed from the base of the PR and between 23dd58c and 126754a.

Files selected for processing: 1

  • packages/codex/build.sh

Included review availability: This review used your included allowance. 0 included reviews remain after this review. Your included PR review attempts over the past 7 days set your current allowance at 1 review per hour.

@agent-137 agent-137 left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Review on Karl's behalf. This is a comment, not an approval. Nothing was built for it. The findings come from reading the declarations and fetching upstream sources, and each one says how it was checked. The CI rollup on this head is now SUCCESS.

CI: all green, including minimal build. codex built and its tests passed on amd64 and arm64, so the guard accepts the real llvm 21.1.8 layout.

Should-fix: none.

Nit:

  • packages/codex/build.sh:22-25: if /usr/bin/llvm-config is missing, the build stops at the assignment on line 22 (set -euo pipefail; status 127) and prints only bash's "No such file" line. The ERROR: no default llvm (/usr/bin/llvm-config) message on line 25 never prints for that case. The build still fails closed, which the PR body says, but the message is dead code for the cause it names. An explicit [ -x /usr/bin/llvm-config ] || { echo …; exit 1; } before line 22 would make it print.
  • packages/codex/build.sh:23: the guard checks only libclang.so*. On Linux, clang-sys also globs libclang-*.so* in LIBCLANG_PATH. The default llvm ships libclang-cpp.so* in /usr/lib (the libclang output glob is usr/lib/libclang*.{so*,a}), and the guard never checks it. It is the same major today, and llvm-21 installs under /usr/lib/llvm-21, so nothing goes wrong now. But "every libclang in it" in the comment is broader than what the code checks. Unverified: the clang-sys glob list is from my knowledge of its source, not checked against the vendored version.

Checked:

  • The llvm package installs with CMAKE_INSTALL_PREFIX=/usr (packages/llvm/build.sh:40). Its outputs ship usr/bin/* (llvm-config) and usr/lib/libclang*.so*, so /usr/lib and /usr/bin/llvm-config are the right paths.
  • The libclang SOVERSION is the major (libclang.so → .so.21 → .so.21.1.8). readlink -f plus sort -u reduces these to one file, and the case accepts it.
  • The "libclang.so.$llvm_major".* pattern needs a literal dot after the major, so a major of 21 cannot match .so.210.
  • The guard fails when:
    • two different majors are present (the loop exits on the first mismatch),
    • there is no match (-exec never runs, the variable is empty, and line 24 exits),
    • the libclang file is unversioned (no pattern matches).
  • codex depends only on the default llvm, and rust's runtime llvm is the same package.

@agent-137 agent-137 left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Approving at 126754a. No should-fix findings; the nits in the earlier comment review are optional.

@bryan-minimal
bryan-minimal added this pull request to the merge queue Nov 9, 2026
Merged via the queue into main with commit d133ca6 Nov 10, 2026
15 checks passed
@bryan-minimal
bryan-minimal deleted the codex-libclang-pin branch November 10, 2026 03:23
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants