[DRAFT] Support linking against a prebuilt AWS-LC installation

.github/workflows/tests.yml

@@ -274,6 +274,46 @@ jobs:
         # See: https://github.com/rust-lang/cargo/issues/8531
         run: cargo test -p aws-lc-rs --tests
 
+  prebuilt-install-test:
+    if: github.repository_owner == 'aws'
+    name: aws-lc-rs prebuilt install (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    # Windows is omitted: the prebuilt code paths are Windows-aware
+    # (find_static_lib/find_dynamic_lib handle .lib/.dll/.dll.a), but the
+    # integration script is bash-only and a Windows AWS-LC install would
+    # also require NASM setup. Add as a follow-up.
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ ubuntu-latest, macos-15-intel, macos-latest ]
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          submodules: 'recursive'
+      - uses: dtolnay/rust-toolchain@stable
+      - name: Build and install AWS-LC (static)
+        run: |
+          cmake -S aws-lc-sys/aws-lc -B aws-lc-build \
+            -DCMAKE_BUILD_TYPE=Release \
+            -DBUILD_TESTING=OFF \
+            -DBUILD_TOOL=OFF \
+            -DDISABLE_GO=ON \
+            -DBUILD_SHARED_LIBS=OFF \
+            -DCMAKE_INSTALL_PREFIX="${PWD}/aws-lc-install"
+          cmake --build aws-lc-build --target install -j
+      - name: Build and install AWS-LC (shared)
+        run: |
+          cmake -S aws-lc-sys/aws-lc -B aws-lc-shared-build \
+            -DCMAKE_BUILD_TYPE=Release \
+            -DBUILD_TESTING=OFF \
+            -DBUILD_TOOL=OFF \
+            -DDISABLE_GO=ON \
+            -DBUILD_SHARED_LIBS=ON \
+            -DCMAKE_INSTALL_PREFIX="${PWD}/aws-lc-install"
+          cmake --build aws-lc-shared-build --target install -j
+      - name: Run prebuilt integration tests
+        run: ./scripts/tests/test_prebuilt.sh "${PWD}/aws-lc-install"
+
   build-prebuild-nasm-test:
     if: github.repository_owner == 'aws'
     name: prebuilt-nasm usage

Cargo.toml

@@ -37,6 +37,7 @@ openssl = "0.10.73"
 paste = "1.0.15"
 ring = "0.17.14"
 toml_edit = "0.25.0"
+tempfile = "3"
 
 [profile.bench]
 lto = true

aws-lc-sys/README.md

@@ -63,6 +63,57 @@ For each PR submitted,
 [CI verifies](https://github.com/aws/aws-lc-rs/blob/main/.github/workflows/tests.yml)
 that the NASM objects newly built from source match the NASM objects currently in the repository.
 
+## Linking against a prebuilt AWS-LC
+
+If you have an existing AWS-LC installation (built and installed via CMake),
+you can link against it instead of building AWS-LC from the bundled source.
+Set `AWS_LC_SYS_PREBUILT_INSTALL_DIR` to the install prefix:
+
+```shell
+AWS_LC_SYS_PREBUILT_INSTALL_DIR=/path/to/aws-lc-install cargo build
+```
+
+The install directory must contain:
+
+* `include/openssl/base.h` — used to detect the `OPENSSL_IS_AWSLC` marker and
+  the AWS-LC version (`AWSLC_VERSION_NUMBER_STRING`).
+* `lib/` (or `lib64/` for 64-bit targets, when present) containing `libcrypto`.
+  When the `ssl` feature is enabled, `libssl` is also required.
+
+Static vs. dynamic linking honors `AWS_LC_SYS_STATIC` (the same variable used
+when building from source). When both static and dynamic libraries are present
+the preferred form is selected; if only one is present it is used regardless
+of the preference, with a warning.
+
+If a prefixed AWS-LC build is detected (via `include/openssl/boringssl_prefix_symbols.h`),
+the prefix is extracted and applied automatically to library names and bindings.
+
+### Bindings for prebuilt installations
+
+When the prebuilt path is taken, bindings are resolved in this order:
+
+1. **`AWS_LC_SYS_PREBUILT_BINDINGS`** — explicit path to a pre-generated
+   `bindings.rs`. A misconfigured path is a hard error.
+2. **`<install_dir>/share/rust/aws_lc_bindings.rs`** — populated by AWS-LC's
+   CMake install (AWS-LC v1.68.0+). See [aws-lc#2999](https://github.com/aws/aws-lc/pull/2999).
+3. **Internal `bindgen`** — when the `bindgen` feature is enabled.
+4. **External `bindgen-cli`** — when the `bindgen` binary is on `PATH`.
+
+If none of these are available the build fails with guidance on how to proceed.
+
+### Version compatibility
+
+The version embedded in the prebuilt headers must be greater than or equal to
+the AWS-LC version bundled with this crate. To bypass this check (not
+recommended), set `AWS_LC_SYS_PREBUILT_SKIP_VERSION_CHECK=1`.
+
+### Limitations
+
+Prebuilt linking is not supported for FIPS builds (`aws-lc-fips-sys`).
+Validating that a prebuilt installation actually meets FIPS requirements is
+non-trivial, so the build refuses rather than silently linking a non-FIPS
+build into a FIPS crate.
+
 ## Build Prerequisites
 
 Since this crate builds AWS-LC as a native library, most build tools needed to build AWS-LC are applicable

builder-test/Cargo.toml

@@ -5,15 +5,13 @@ edition = "2021"
 publish = false
 description = "Test harness for aws-lc-sys builder modules - does not duplicate code"
 
-# Silence warnings that are expected when compiling builder code as a library.
-# The builder code is designed to run as a build script, so many functions
-# appear "unused" when compiled as a library for testing purposes.
+# This crate exists solely to run unit tests defined in builder/main.rs and its
+# modules. The builder code normally compiles only as a build script, so many
+# functions appear "unused" when compiled as a library here.
 [lints.rust]
 dead_code = "allow"
 unused = "allow"
 
-# Point to the actual builder/main.rs as the library source
-# The #[cfg(test)] module in main.rs will be compiled and run
 [lib]
 name = "builder"
 path = "../builder/main.rs"
@@ -26,6 +24,9 @@ dunce = { workspace = true }
 fs_extra = { workspace = true }
 bindgen = { workspace = true, optional = true }
 
+[dev-dependencies]
+tempfile = { workspace = true }
+
 [features]
 default = []
 # Mirror the features from aws-lc-sys that affect builder compilation