Skip to content

[boring] Document and check the glibc requirement of the prebuilt Linux libraries - #2896

Draft
mosuem wants to merge 3 commits into
boring-build-optionsfrom
boring-linux-libc-check
Draft

mosuem wants to merge 3 commits into
boring-build-optionsfrom
boring-linux-libc-check

Conversation

@mosuem

@mosuem mosuem commented Nov 17, 2026

Copy link
Copy Markdown
Member

Note

This PR was generated by an AI coding agent (Jetski) on behalf of @mosuem.

Important

Stacked on #2893, which is its base branch. CI runs once #2893 lands and GitHub retargets this PR. This replaces #2894, which built the libraries in containers.

Third of a stack of package:boring fixes:

  1. [boring] Bind BN_ULONG as UintPtr #2892: bind BN_ULONG as UintPtr
  2. [boring] Compile with OPENSSL_SMALL and the sanitizer of the Dart runtime #2893: compile with OPENSSL_SMALL and the sanitizer of the Dart runtime
  3. This PR: document and check the glibc requirement of the prebuilt Linux libraries

The prebuilt Linux libraries are built on Ubuntu 22.04, the oldest Ubuntu runner GitHub Actions has. objdump -T shows that both the x64 and the arm64 library require glibc 2.34, because pthread functions such as pthread_key_create moved into libc in that version. The README didn't say so, and the prebuilt library is picked by OS and architecture only. So on older distributions (Debian 11, Ubuntu 20.04, RHEL 8) and on other C libraries (musl on Alpine Linux), fetch bundled a library that failed to load at run time. package:webcrypto used to compile BoringSSL on the user's machine, so it worked on all of these.

This PR doesn't change how the libraries are built. It makes the requirement explicit:

  • README: the prebuilt Linux libraries require glibc 2.34 or later, for example Ubuntu 22.04, Debian 12, RHEL 9, Fedora 35, or Amazon Linux 2023. Elsewhere, use buildMode: checkout.
  • Build-time check: in the fetch build mode, when building for the Linux machine the hook runs on (dart run, dart test), the hook calls gnu_get_libc_version() through DynamicLibrary.process(). On musl, or on glibc older than 2.34, it fails with a BuildError and the buildMode: checkout hint, like for other targets without prebuilt libraries. When cross-compiling, the target's C library isn't known, so the hook doesn't check it.
  • CI guard: the ABI check in boring_binaries.yaml goes from 2.35 to 2.34, what the libraries need today, so a runner or toolchain change can't silently raise the requirement. prebuiltLinuxGlibc in lib/src/hook_helpers/libc.dart and the README must stay in sync with it.

test/hook_helpers_test.dart covers parsing, the version floor, musl, and the C library of the test machine. Locally on Linux x64, dart test passes (38 passed, 5 skipped).

BoringSSL's BN_ULONG is uint64_t on 64-bit targets and uint32_t on 32-bit
targets (openssl/base.h). ffigen runs on a 64-bit host, so the bindings used
Uint64, which passes and returns the wrong values for the BN_*_word functions
on 32-bit targets such as Android arm. For example, BN_set_word(bn, 65537)
set the wrong RSA public exponent in package:webcrypto (fixed there in
google/webcrypto.dart#432 before it moved to package:boring).

Map BN_ULONG to the pointer-sized UintPtr in tool/ffigen.dart, and keep the
BN_ULONG and DartBN_ULONG typedefs in bindings.dart, because ffigen no longer
generates them.
…time

- Compile BoringSSL with OPENSSL_SMALL. Its smaller precomputed tables, mainly
  for P-256, are used by every application that uses ECDSA or ECDH, so
  tree-shaking can't remove them. For package:webcrypto, this makes the
  tree-shaken library on Linux x64 19% smaller (1.12 MB -> 0.91 MB), and P-256
  signing about 2x slower (26 -> 54 us). AES-GCM is unaffected.
- When the build config has a sanitizer, for example in
  `dart test -p vm-asan`, compile BoringSSL with it and Clang, like
  package:webcrypto's build hook did. The prebuilt libraries aren't
  instrumented, so the `fetch` build mode builds from source in that case.
  Add an `asan` CI job.
- List BoringSSL's `.inc` files as dependencies of the `checkout` build, like
  google/webcrypto.dart#429.
…ux libraries

The prebuilt Linux libraries are built on Ubuntu 22.04, the oldest Ubuntu
that GitHub Actions has, so they require glibc 2.34, for the pthread functions
that moved into libc in 2.34. The README didn't say so, and the libraries are
picked by OS and architecture only, so they failed to load on older
distributions and on other C libraries, such as musl on Alpine Linux.

- List the requirement in the README.
- In the `fetch` build mode, when building for the Linux machine the hook runs
  on, check its C library with gnu_get_libc_version(), and fail with a hint to
  use `buildMode: checkout` on musl or glibc older than 2.34, instead of
  bundling a library that fails to load.
- Tighten the ABI check of the binaries workflow from 2.35 to 2.34, what the
  libraries need today, so the requirement can't silently grow.
@mosuem
mosuem requested a review from a team as a code owner November 17, 2026 15:35
@github-actions github-actions Bot added type-infra A repository infrastructure change or enhancement package:boring labels Nov 17, 2026

@gemini-code-assist gemini-code-assist Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Code Review

This pull request introduces a check on Linux to ensure the host system has glibc 2.34 or later before using prebuilt libraries in fetch build mode, falling back to a build error with a hint to use buildMode: checkout on unsupported systems (such as Alpine Linux with musl). Feedback on the tests suggests making the glibc detection test more robust, as it currently assumes the host environment running the tests will always have a compatible glibc version, which may cause failures on Alpine Linux or older distributions.

Comment on lines +165 to +171
if (Platform.isLinux) {
// The CI runners use glibc.
expect(version, isNotNull);
expect(unsupportedLinuxLibcReason(version), isNull);
} else {
expect(version, isNull);
}

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

medium

The test assumes that any Linux environment running the tests will have a glibc version of at least 2.34. However, this package is designed to support other Linux environments (like Alpine Linux with musl, or older Ubuntu distributions with glibc < 2.34) by falling back to compiling from source. Running dart test on those platforms will cause this test to fail. We should make the test robust to these environments by only asserting the version structure if glibc is detected, without assuming its presence or a specific minimum version.

      if (Platform.isLinux) {
        // On Linux, the host may use glibc (which might be older than 2.34) or another libc like musl.
        if (version != null) {
          final (major, minor) = version;
          expect(major, greaterThan(0));
          expect(minor, greaterThanOrEqualTo(0));
        }
      } else {
        expect(version, isNull);
      }

@mosuem
mosuem force-pushed the boring-build-options branch from 56ca107 to a000c1c Compare November 18, 2026 08:38
@mosuem
mosuem marked this pull request as draft November 18, 2026 15:59

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

package:boring type-infra A repository infrastructure change or enhancement

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant