diff --git a/.github/workflows/boring.yaml b/.github/workflows/boring.yaml index b8166f7325..6e4b863077 100644 --- a/.github/workflows/boring.yaml +++ b/.github/workflows/boring.yaml @@ -50,19 +50,11 @@ jobs: - name: Analyze code run: dart analyze --fatal-infos if: always() && steps.install.outcome == 'success' - # The `fetch` build mode downloads the libraries pinned in hashes.dart, - # which boring_binaries.yaml builds from the native sources on main. A - # release of package:boring mustn't ship libraries built from other - # sources than the ones it vendors, so this fails once the version is no - # longer a -wip one. - - name: Check that the prebuilt libraries match the native sources - run: ./tool/check_prebuilt_binaries.sh - if: always() && steps.install.outcome == 'success' # Build BoringSSL from source with the build hook and run the tests on each # desktop OS (Linux, macOS, and Windows each use different linker flags in - # hook/link.dart), including cross-compiling to linux-arm64 with and without - # a cross-toolchain. + # hook/link.dart). test/prebuilt_test.dart, which needs the prebuilt + # libraries, runs in boring_binaries.yaml. test: needs: analyze runs-on: ${{ matrix.os }} @@ -81,58 +73,6 @@ jobs: - name: Setup NASM if: runner.os == 'Windows' uses: ./.github/actions/setup-nasm - - name: Install Linux cross toolchain (Linux) - if: runner.os == 'Linux' - run: sudo apt-get update && sudo apt-get install -y gcc-aarch64-linux-gnu g++-aarch64-linux-gnu - # The release of messense/homebrew-macos-cross-toolchains that its - # Homebrew tap installs, downloaded directly to pin its SHA-256, like the - # Windows download below. - - name: Install Linux cross toolchain (macOS) - if: runner.os == 'macOS' - shell: bash - run: | - case "$(uname -m)" in - arm64) - url="https://github.com/messense/homebrew-macos-cross-toolchains/releases/download/v15.2.0/aarch64-unknown-linux-gnu-aarch64-darwin.tar.gz" - expected="0f224db36d8572489f09ed5bce39f189eee998f9ab4f8ea07f510d6c7078caa3" - ;; - x86_64) - url="https://github.com/messense/homebrew-macos-cross-toolchains/releases/download/v15.2.0/aarch64-unknown-linux-gnu-x86_64-darwin.tar.gz" - expected="7fa485313b7049d57c5de56bf876d5c4648ebfd736f86a8f4739596218523127" - ;; - *) - echo "::error::Unsupported macOS architecture: $(uname -m)" - exit 1 - ;; - esac - curl -fSL -o "$RUNNER_TEMP/aarch64-linux-gnu.tar.gz" "$url" - actual="$(shasum -a 256 < "$RUNNER_TEMP/aarch64-linux-gnu.tar.gz" | cut -d' ' -f1)" - if [ "$actual" != "$expected" ]; then - echo "::error::Expected SHA-256 $expected for $url, got $actual." - exit 1 - fi - tar -xzf "$RUNNER_TEMP/aarch64-linux-gnu.tar.gz" -C "$RUNNER_TEMP" - echo "$RUNNER_TEMP/aarch64-unknown-linux-gnu/bin" >> "$GITHUB_PATH" - - name: Install Linux cross toolchain (Windows) - if: runner.os == 'Windows' - shell: bash - env: - TOOLCHAIN_URL: https://developer.arm.com/-/media/Files/downloads/gnu/14.2.rel1/binrel/arm-gnu-toolchain-14.2.rel1-mingw-w64-x86_64-aarch64-none-linux-gnu.zip - # From the .sha256asc file published next to the zip. - TOOLCHAIN_SHA256: 9428b2039923916418ec7037025be8cec3202926d65db9452519977834ad2a89 - run: | - curl -fSL -o "$RUNNER_TEMP/arm-gnu-toolchain.zip" "$TOOLCHAIN_URL" - actual="$(sha256sum < "$RUNNER_TEMP/arm-gnu-toolchain.zip" | cut -d' ' -f1)" - if [ "$actual" != "$TOOLCHAIN_SHA256" ]; then - echo "::error::Expected SHA-256 $TOOLCHAIN_SHA256 for $TOOLCHAIN_URL, got $actual." - exit 1 - fi - 7z x "$RUNNER_TEMP/arm-gnu-toolchain.zip" -o"$RUNNER_TEMP/arm-gnu-toolchain" -y >/dev/null - BIN_DIR="$RUNNER_TEMP/arm-gnu-toolchain/bin" - for f in "$BIN_DIR"/aarch64-none-linux-gnu-*.exe; do - cp "$f" "${f/aarch64-none-linux-gnu-/aarch64-linux-gnu-}" - done - cygpath -w "$BIN_DIR" >> "$GITHUB_PATH" - id: install name: Install dependencies run: dart pub get @@ -194,15 +134,11 @@ jobs: sdk: dev - name: Regenerate at tool/REVISION run: ./tool/bump-boringssl-revision.sh "$(cat tool/REVISION)" - # Also checks that every prebuilt target's asset exists in the pinned - # release, since `fetch` fails for a target without a hash. - - name: Regenerate the hashes of the pinned release - run: dart run tool/regenerate_hashes.dart - name: Check for changes run: | if [ -n "$(git status --porcelain -- .)" ]; then git status --short -- . - echo "::error::Generated files are out of date. Run ./tool/bump-boringssl-revision.sh \"\$(cat tool/REVISION)\" and dart run tool/regenerate_hashes.dart in pkgs/boring and commit the result." + echo "::error::Generated files are out of date. Run ./tool/bump-boringssl-revision.sh \"\$(cat tool/REVISION)\" in pkgs/boring and commit the result." exit 1 fi diff --git a/.github/workflows/boring_binaries.yaml b/.github/workflows/boring_binaries.yaml index d0fce6d3d4..880b84669e 100644 --- a/.github/workflows/boring_binaries.yaml +++ b/.github/workflows/boring_binaries.yaml @@ -1,17 +1,19 @@ -# Builds the prebuilt libraries that hook/build.dart downloads in the `fetch` -# build mode, attaches them to a `boring-binaries--` GitHub -# pre-release, and opens a pull request that pins their SHA-256 hashes in -# lib/src/hook_helpers/hashes.dart. +# Builds the prebuilt libraries that hook/build.dart uses in the `fetch` build +# mode, adds them to the prebuilt/ directory of package:boring, and tests the +# package archive with them. On a `boring-v` tag, it then calls +# `dart-lang/setup-dart/.github/workflows/publish.yml` (`bundled-files`, +# `attest: true`) to stage the libraries into an isolated checkout, attest the +# package archive's SLSA Build L3 provenance, and publish it to pub.dev, so the +# libraries come with the package instead of being downloaded. publish.yaml +# skips these tags, as it would publish the package without them. # -# Runs when a change to the native sources (src/, the vendored BoringSSL, or -# this pipeline) lands on main, for example the weekly BoringSSL update, and on -# `workflow_dispatch` on main. The `analyze` job of boring.yaml checks that the -# pinned libraries were built from the current native sources, so a release of -# package:boring can't ship stale ones: merge the pin pull request first. +# The libraries are built from the tagged commit, so they match the vendored +# BoringSSL that the `checkout` build mode compiles. # -# Pull requests that change the pipeline or the native build only run the -# `precompile` job, as does `workflow_dispatch` on other branches, and upload -# workflow artifacts without creating a release. +# Also runs, without publishing, on pull requests that change the native build, +# the hooks, or this pipeline, when a change to the native sources (src/, the +# vendored BoringSSL, or this pipeline) lands on main, for example the weekly +# BoringSSL update, and on `workflow_dispatch`. name: package:boring binaries permissions: contents: read @@ -19,6 +21,8 @@ permissions: on: push: branches: [ main ] + # Path filters don't apply to tags. + tags: [ 'boring-v[0-9]+.[0-9]+.[0-9]+*' ] paths: - '.github/actions/setup-nasm/**' - '.github/workflows/boring_binaries.yaml' @@ -31,19 +35,23 @@ on: paths: - '.github/actions/setup-nasm/**' - '.github/workflows/boring_binaries.yaml' + - 'pkgs/boring/.pubignore' + - 'pkgs/boring/hook/**' + - 'pkgs/boring/lib/src/hook_helpers/**' + - 'pkgs/boring/pubspec.yaml' - 'pkgs/boring/src/**' + - 'pkgs/boring/test/prebuilt_test.dart' - 'pkgs/boring/tool/precompile_binaries.dart' workflow_dispatch: -# Releases are named after the commit, so builds of the same ref run one after -# the other instead of racing for the release. +# Cancels the superseded runs of a pull request, but never a publishing run. concurrency: group: ${{ github.workflow }}-${{ github.ref }} cancel-in-progress: ${{ github.event_name == 'pull_request' }} jobs: # Runs compilers and other build tools, so it only gets `contents: read` and - # cannot mint OIDC tokens. The `attest` job attests the libraries. + # cannot mint OIDC tokens. precompile: name: Precompile (${{ matrix.target-os }}-${{ matrix.target-arch }}${{ matrix.ios-sdk && format('-{0}', matrix.ios-sdk) || '' }}) runs-on: ${{ matrix.os }} @@ -123,7 +131,8 @@ jobs: run: dart pub get # Builds the dynamic library, which is bundled when linking is disabled, # and the static library, which hook/link.dart links into a dynamic - # library with only the functions an application uses. + # library with only the functions an application uses, in + # prebuilt//. - name: Precompile the libraries env: TARGET_OS: ${{ matrix.target-os }} @@ -134,7 +143,7 @@ jobs: ${IOS_SDK:+--ios-sdk="$IOS_SDK"} \ ${ANDROID_NDK_LATEST_HOME:+--android-ndk="$ANDROID_NDK_LATEST_HOME"} - name: List the libraries - run: ls -l bin + run: ls -lR prebuilt # The dynamic library is bundled as is, so it must run on every OS version # that Dart and Flutter support, not only on the build machine's. - name: Check the ABI floor of the dynamic library (Linux) @@ -142,7 +151,7 @@ jobs: env: MAX_GLIBC: ${{ matrix.max-glibc }} run: | - glibc="$(objdump -T bin/*.so | grep -oE 'GLIBC_[0-9.]+' | sed 's/GLIBC_//' | sort -Vu | tail -1)" + glibc="$(objdump -T prebuilt/*/*.so | grep -oE 'GLIBC_[0-9.]+' | sed 's/GLIBC_//' | sort -Vu | tail -1)" echo "Newest glibc symbol version: $glibc (allowed: $MAX_GLIBC)" if [ "$(printf '%s\n%s\n' "$glibc" "$MAX_GLIBC" | sort -V | tail -1)" != "$MAX_GLIBC" ]; then echo "::error::The library requires glibc $glibc, newer than $MAX_GLIBC. Build on an older runner." @@ -154,7 +163,7 @@ jobs: MIN_OS: ${{ matrix.min-os }} TARGET_OS: ${{ matrix.target-os }} run: | - minos="$(otool -l bin/*.dylib | awk '/minos/ {print $2}' | sort -u)" + minos="$(otool -l prebuilt/*/*.dylib | awk '/minos/ {print $2}' | sort -u)" echo "Minimum $TARGET_OS version: $minos (expected: $MIN_OS)" if [ "$minos" != "$MIN_OS" ]; then echo "::error::The library requires $TARGET_OS '$minos' instead of $MIN_OS. Check the deployment targets in tool/precompile_binaries.dart." @@ -172,11 +181,11 @@ jobs: arm|ia32) expected_alignment=0x1000 ;; *) expected_alignment=0x4000 ;; esac - alignments="$(readelf -lW bin/*.so | awk '$1 == "LOAD" {print $NF}' | sort -u)" - needed="$(readelf -d bin/*.so | awk '/NEEDED/ {print $NF}' | tr -d '[]' | sort -u | tr '\n' ' ')" + alignments="$(readelf -lW prebuilt/*/*.so | awk '$1 == "LOAD" {print $NF}' | sort -u)" + needed="$(readelf -d prebuilt/*/*.so | awk '/NEEDED/ {print $NF}' | tr -d '[]' | sort -u | tr '\n' ' ')" echo "LOAD segment alignment: $alignments (expected: $expected_alignment)" echo "Needed libraries: $needed" - readelf -n bin/*.so | grep -A2 'Android' || true + readelf -n prebuilt/*/*.so | grep -A2 'Android' || true if [ "$alignments" != "$expected_alignment" ]; then echo "::error::The LOAD segments are aligned to $alignments instead of $expected_alignment. Use NDK r28 or newer, or ANDROID_SUPPORT_FLEXIBLE_PAGE_SIZES." exit 1 @@ -192,163 +201,196 @@ jobs: run: | # The C runtime is linked statically (see src/CMakeLists.txt), so the # DLL must not import the Visual C++ Redistributable's DLLs. - imports="$(grep -a -o -i -E '(vcruntime|msvcp|msvcr)[0-9_]*\.dll|api-ms-win-crt-[a-z0-9-]*\.dll' bin/*.dll | sort -u || true)" + imports="$(grep -a -o -i -E '(vcruntime|msvcp|msvcr)[0-9_]*\.dll|api-ms-win-crt-[a-z0-9-]*\.dll' prebuilt/*/*.dll | sort -u || true)" if [ -n "$imports" ]; then echo "$imports" echo "::error::The DLL imports the C runtime dynamically. Check CMAKE_MSVC_RUNTIME_LIBRARY in src/CMakeLists.txt." exit 1 fi echo "The DLL doesn't import the C runtime dynamically." + - name: Stage prebuilt libraries + run: | + mkdir -p "$RUNNER_TEMP/bundled-files" + cp -r prebuilt "$RUNNER_TEMP/bundled-files/" - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 with: - name: binaries-${{ matrix.target-os }}-${{ matrix.target-arch }}${{ matrix.ios-sdk && format('-{0}', matrix.ios-sdk) || '' }} - path: pkgs/boring/bin/* + name: bundled-files-${{ matrix.target-os }}-${{ matrix.target-arch }}${{ matrix.ios-sdk && format('-{0}', matrix.ios-sdk) || '' }} + path: ${{ runner.temp }}/bundled-files/ if-no-files-found: error - # Attests the provenance of the libraries that `precompile` built. Only - # downloads and attests them, so no build tool runs with `id-token: write`. - attest: - name: Attest the provenance of the release libraries + # Adds the libraries of all targets to prebuilt/, where hook/build.dart looks + # for them, and creates a package archive for `test` (including on fork PRs, + # where `publish` cannot run because OIDC tokens are unavailable). + # pkgs/boring/.pubignore, unlike .gitignore, doesn't ignore prebuilt/. + package: + name: Create the test package archive needs: precompile - if: github.event_name != 'pull_request' && github.ref == 'refs/heads/main' runs-on: ubuntu-latest - permissions: - id-token: write # To sign the provenance attestations of the libraries. - attestations: write # To store the attestations with the repository. + defaults: + run: + working-directory: pkgs/boring/ steps: - - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 with: - pattern: binaries-* - path: release-assets - merge-multiple: true - # Verify with `gh attestation verify --repo dart-lang/tools`. - - name: Attest the provenance of the release libraries - uses: actions/attest-build-provenance@4d101475d8b20a2381f78447822ac1eab6504dd8 + persist-credentials: false + - uses: dart-lang/setup-dart@6afc89df92d6eb3834022f73cd65adc8cdfcb92d with: - subject-path: release-assets/* - - release: - name: Attach the binaries to a GitHub release - needs: attest - if: github.event_name != 'pull_request' && github.ref == 'refs/heads/main' - runs-on: ubuntu-latest - permissions: - contents: write # To create the release and upload its assets. - outputs: - tag: ${{ steps.release.outputs.tag }} - id: ${{ steps.release.outputs.id }} - steps: + sdk: stable - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 with: - path: release-assets + pattern: bundled-files-* + path: pkgs/boring merge-multiple: true - - name: Create the GitHub release - id: release - env: - GH_TOKEN: ${{ github.token }} - GH_REPO: ${{ github.repository }} - COMMIT: ${{ github.sha }} - run: | - id="$(date -u +%Y%m%d)-${COMMIT::12}" - tag="boring-binaries-$id" - echo "id=$id" >> "$GITHUB_OUTPUT" - echo "tag=$tag" >> "$GITHUB_OUTPUT" - if ! gh release view "$tag" > /dev/null 2>&1; then - gh release create "$tag" --prerelease --target "$COMMIT" \ - --title "package:boring binaries $tag" \ - --notes "The prebuilt BoringSSL libraries for package:boring, built from $GITHUB_SERVER_URL/$GITHUB_REPOSITORY/commit/$COMMIT by $GITHUB_SERVER_URL/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_ID. Verify a library with \`gh attestation verify --repo $GITHUB_REPOSITORY\`." - fi - # lib/src/hook_helpers/hashes.dart pins the hashes of the assets, so - # never replace them. Delete a failed release to rebuild a commit. - if [ "$(gh release view "$tag" --json assets --jq '.assets | length')" -ne 0 ]; then - echo "::error::Release $tag already has assets. Delete the release to upload new ones." - exit 1 - fi - gh release upload "$tag" release-assets/* - echo "Created $GITHUB_SERVER_URL/$GITHUB_REPOSITORY/releases/tag/$tag" + - name: Install dependencies + run: dart pub get + - name: Validate the package + run: dart pub publish --dry-run + - name: Create the package archive + run: dart pub publish --to-archive="$RUNNER_TEMP/package.tar.gz" + - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 + with: + name: test-package-archive + path: ${{ runner.temp }}/package.tar.gz + if-no-files-found: error - # Pins the hashes of the release in hashes.dart, like the refresh job of - # boring.yaml updates BoringSSL. The Dart Bot token is needed so that the - # PR's CI runs: its `generated` job re-hashes the release assets, and the - # tree-shaking tests download them in the `fetch` build mode. - pin: - name: Open the pull request that pins the binaries - needs: release - if: github.repository_owner == 'dart-lang' - runs-on: ubuntu-latest - permissions: - contents: write # To push the branch of the pull request. - pull-requests: write # To open the pull request. + # Builds the example against the package archive like an app that depends on + # package:boring from pub.dev, in the default `fetch` build mode, see + # test/prebuilt_test.dart. On each desktop OS, cross-compiles to Linux with + # and without a cross-toolchain (hook/link.dart uses different linker flags + # on each). + test: + name: Test the package archive (${{ matrix.os }}) + needs: package + runs-on: ${{ matrix.os }} + defaults: + run: + working-directory: pkgs/boring/ + strategy: + fail-fast: false + matrix: + os: [ubuntu-latest, macos-latest, windows-latest] steps: - - name: Generate Dart Bot token - id: generate-token - uses: actions/create-github-app-token@64ab729a6294000f5aa4a4bc0b73d1f32bc45510 - with: - client-id: ${{ vars.ECOSYSTEM_BOT_CLIENT_ID }} - private-key: ${{ secrets.ECOSYSTEM_BOT_PRIVATE_KEY }} - permission-contents: write - permission-pull-requests: write - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 with: - ref: main - token: ${{ steps.generate-token.outputs.token }} persist-credentials: false - uses: dart-lang/setup-dart@6afc89df92d6eb3834022f73cd65adc8cdfcb92d with: sdk: stable + # `dart test` builds this package from source, see pubspec.yaml. + - name: Setup NASM + if: runner.os == 'Windows' + uses: ./.github/actions/setup-nasm + - name: Install Linux cross toolchain (Linux) + if: runner.os == 'Linux' + run: sudo apt-get update && sudo apt-get install -y gcc-aarch64-linux-gnu g++-aarch64-linux-gnu + - name: Install Linux cross toolchain (macOS) + if: runner.os == 'macOS' + shell: bash + run: | + case "$(uname -m)" in + arm64) + url="https://github.com/messense/homebrew-macos-cross-toolchains/releases/download/v15.2.0/aarch64-unknown-linux-gnu-aarch64-darwin.tar.gz" + expected="0f224db36d8572489f09ed5bce39f189eee998f9ab4f8ea07f510d6c7078caa3" + ;; + x86_64) + url="https://github.com/messense/homebrew-macos-cross-toolchains/releases/download/v15.2.0/aarch64-unknown-linux-gnu-x86_64-darwin.tar.gz" + expected="7fa485313b7049d57c5de56bf876d5c4648ebfd736f86a8f4739596218523127" + ;; + *) + echo "::error::Unsupported macOS architecture: $(uname -m)" + exit 1 + ;; + esac + curl -fSL -o "$RUNNER_TEMP/aarch64-linux-gnu.tar.gz" "$url" + actual="$(shasum -a 256 < "$RUNNER_TEMP/aarch64-linux-gnu.tar.gz" | cut -d' ' -f1)" + if [ "$actual" != "$expected" ]; then + echo "::error::Expected SHA-256 $expected for $url, got $actual." + exit 1 + fi + tar -xzf "$RUNNER_TEMP/aarch64-linux-gnu.tar.gz" -C "$RUNNER_TEMP" + echo "$RUNNER_TEMP/aarch64-unknown-linux-gnu/bin" >> "$GITHUB_PATH" + - name: Install Linux cross toolchain (Windows) + if: runner.os == 'Windows' + shell: bash + env: + TOOLCHAIN_URL: https://developer.arm.com/-/media/Files/downloads/gnu/14.2.rel1/binrel/arm-gnu-toolchain-14.2.rel1-mingw-w64-x86_64-aarch64-none-linux-gnu.zip + # From the .sha256asc file published next to the zip. + TOOLCHAIN_SHA256: 9428b2039923916418ec7037025be8cec3202926d65db9452519977834ad2a89 + run: | + curl -fSL -o "$RUNNER_TEMP/arm-gnu-toolchain.zip" "$TOOLCHAIN_URL" + actual="$(sha256sum < "$RUNNER_TEMP/arm-gnu-toolchain.zip" | cut -d' ' -f1)" + if [ "$actual" != "$TOOLCHAIN_SHA256" ]; then + echo "::error::Expected SHA-256 $TOOLCHAIN_SHA256 for $TOOLCHAIN_URL, got $actual." + exit 1 + fi + 7z x "$RUNNER_TEMP/arm-gnu-toolchain.zip" -o"$RUNNER_TEMP/arm-gnu-toolchain" -y >/dev/null + BIN_DIR="$RUNNER_TEMP/arm-gnu-toolchain/bin" + for f in "$BIN_DIR"/aarch64-none-linux-gnu-*.exe; do + cp "$f" "${f/aarch64-none-linux-gnu-/aarch64-linux-gnu-}" + done + cygpath -w "$BIN_DIR" >> "$GITHUB_PATH" - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 with: - path: release-assets - merge-multiple: true + name: test-package-archive + path: ${{ runner.temp }} + - name: Extract the package archive + shell: bash + working-directory: ${{ runner.temp }} + run: mkdir boring && tar -xzf package.tar.gz -C boring - name: Install dependencies - working-directory: pkgs/boring/ run: dart pub get - - name: Pin the hashes - working-directory: pkgs/boring/ + - name: Run tests env: - TAG: ${{ needs.release.outputs.tag }} - COMMIT: ${{ github.sha }} - GH_REPO: ${{ github.repository }} - run: dart run tool/regenerate_hashes.dart --repository "$GH_REPO" --source-commit "$COMMIT" --assets "$GITHUB_WORKSPACE/release-assets" "$TAG" - - name: Create pull request - id: create-pr - uses: peter-evans/create-pull-request@86c87cfdd87dd582eb8b8f226cfec4e09d825326 - with: - token: ${{ steps.generate-token.outputs.token }} - committer: dart-ecosystem-bot - author: dart-ecosystem-bot - base: main - add-paths: pkgs/boring/lib/src/hook_helpers/hashes.dart - commit-message: "[boring] Pin the prebuilt binaries of ${{ needs.release.outputs.tag }}" - branch: "boring-pin-binaries-${{ needs.release.outputs.id }}" - title: "[boring] Pin the prebuilt binaries of ${{ needs.release.outputs.tag }}" - body: >- - Pins the SHA-256 hashes of the prebuilt libraries of - [`${{ needs.release.outputs.tag }}`](${{ github.server_url }}/${{ github.repository }}/releases/tag/${{ needs.release.outputs.tag }}), - built from ${{ github.sha }} by - [this run](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}) - of `boring_binaries.yaml`. - + BORING_PACKAGE_DIR: ${{ runner.temp }}/boring + run: dart test test/prebuilt_test.dart - The `generated` job re-hashes the release assets, and the - tree-shaking tests download them in the `fetch` build mode. - labels: skip-changelog-check - delete-branch: true - # Each run supersedes the bot's earlier pull requests of this kind, so - # close them instead of leaving them for someone to clean up. - - name: Close superseded pull requests - if: steps.create-pr.outputs.pull-request-number != '' - env: - GH_TOKEN: ${{ steps.generate-token.outputs.token }} - GH_REPO: ${{ github.repository }} - NEW_PR: ${{ steps.create-pr.outputs.pull-request-number }} - BRANCH_PREFIX: boring-pin-binaries- - run: | - gh pr list --state open --limit 100 --json number,headRefName,author | - jq -r --arg prefix "$BRANCH_PREFIX" --argjson new "$NEW_PR" \ - '.[] | select(.author.login == "app/dart-ecosystem-bot") - | select(.headRefName | startswith($prefix)) - | select(.number != $new) | .number' | - while read -r pr; do - gh pr close "$pr" --delete-branch --comment "Superseded by #$NEW_PR." - done + # Stages `bundled-files-*` into an isolated checkout via setup-dart's reusable + # publishing workflow, generates SLSA Build L3 provenance (`attest: true`), + # and publishes on `boring-v` tags (running in `test-run` mode on + # non-tag runs from this repository). + publish: + name: Publish to pub.dev + needs: [precompile, test] + if: >- + !cancelled() && + github.repository_owner == 'dart-lang' && + needs.precompile.result == 'success' && + ( + (github.event_name == 'push' && github.ref_type == 'tag' && needs.test.result == 'success') || + (github.ref_type != 'tag' && (github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository)) + ) + permissions: + id-token: write # To authenticate with pub.dev and sign the attestation. + attestations: write # To store the package attestation. + # TODO(mosuem): Repin to `main` / `@v1` once dart-lang/setup-dart#210, #212, + # and #213 land. + uses: dart-lang/setup-dart/.github/workflows/publish.yml@05f6f8a1c44c614ffa21021a13d34089858e5e8e # publish-bundled-files + with: + working-directory: pkgs/boring + use-flutter: false + attest: true + test-run: ${{ github.event_name != 'push' || github.ref_type != 'tag' }} + # Keep in sync with `prebuiltTargets` in lib/src/hook_helpers/targets.dart. + bundled-files: | + prebuilt/android-arm/libbssl_dart.so + prebuilt/android-arm/libbssl_dart_static.a + prebuilt/android-arm64/libbssl_dart.so + prebuilt/android-arm64/libbssl_dart_static.a + prebuilt/android-x64/libbssl_dart.so + prebuilt/android-x64/libbssl_dart_static.a + prebuilt/ios-arm64-iphoneos/libbssl_dart.dylib + prebuilt/ios-arm64-iphoneos/libbssl_dart_static.a + prebuilt/ios-arm64-iphonesimulator/libbssl_dart.dylib + prebuilt/ios-arm64-iphonesimulator/libbssl_dart_static.a + prebuilt/ios-x64-iphonesimulator/libbssl_dart.dylib + prebuilt/ios-x64-iphonesimulator/libbssl_dart_static.a + prebuilt/linux-arm64/libbssl_dart.so + prebuilt/linux-arm64/libbssl_dart_static.a + prebuilt/linux-x64/libbssl_dart.so + prebuilt/linux-x64/libbssl_dart_static.a + prebuilt/macos-arm64/libbssl_dart.dylib + prebuilt/macos-arm64/libbssl_dart_static.a + prebuilt/macos-x64/libbssl_dart.dylib + prebuilt/macos-x64/libbssl_dart_static.a + prebuilt/windows-x64/bssl_dart.dll + prebuilt/windows-x64/bssl_dart_static.lib diff --git a/.github/workflows/publish.yaml b/.github/workflows/publish.yaml index e78ac8ca83..5e35c6ad6f 100644 --- a/.github/workflows/publish.yaml +++ b/.github/workflows/publish.yaml @@ -8,8 +8,11 @@ on: pull_request: branches: [ main ] push: - # Match -v publish tags - tags: [ '[A-z0-9]+-v[0-9]+.[0-9]+.[0-9]+' ] + # Match -v publish tags, except package:boring's, + # which boring_binaries.yaml publishes with its prebuilt libraries. + tags: + - '[A-z0-9]+-v[0-9]+.[0-9]+.[0-9]+' + - '!boring-v*' jobs: publish: diff --git a/pkgs/boring/.gitignore b/pkgs/boring/.gitignore index ea42c5b6e3..01c4a7e6dc 100644 --- a/pkgs/boring/.gitignore +++ b/pkgs/boring/.gitignore @@ -1,7 +1,10 @@ .dart_tool/ .packages build/ -bin/ +# The prebuilt libraries, which .github/workflows/boring_binaries.yaml adds to +# the published package, and tool/precompile_binaries.dart writes. .pubignore +# includes them in the package. +prebuilt/ *.dylib *.so *.dll diff --git a/pkgs/boring/.pubignore b/pkgs/boring/.pubignore new file mode 100644 index 0000000000..ae07055d9f --- /dev/null +++ b/pkgs/boring/.pubignore @@ -0,0 +1,12 @@ +# pub reads this file instead of .gitignore in this directory. It ignores the +# same files, except the prebuilt libraries in prebuilt/, which +# .github/workflows/boring_binaries.yaml adds to the package it publishes. +.dart_tool/ +.packages +build/ +*.dylib +*.so +*.dll +*.a +!/prebuilt/** +pubspec.lock diff --git a/pkgs/boring/CHANGELOG.md b/pkgs/boring/CHANGELOG.md index 6930333a13..5019ecb2ff 100644 --- a/pkgs/boring/CHANGELOG.md +++ b/pkgs/boring/CHANGELOG.md @@ -3,6 +3,10 @@ Android arm. `BN_ULONG` is now `UintPtr` instead of `Uint64`, because it is `uint32_t` on 32-bit targets. - Update BoringSSL to [8f2554dc](https://boringssl.googlesource.com/boringssl/+/8f2554dc344d403fd6d628773d39637c323eb801). +- The prebuilt libraries come with the published package instead of being + downloaded from GitHub Releases during the build, so the default `fetch` + build mode no longer needs network access. A git or path dependency on the + repository has no prebuilt libraries and requires `buildMode: checkout`. ## 0.4.2 diff --git a/pkgs/boring/CONTRIBUTING.md b/pkgs/boring/CONTRIBUTING.md index 8f6e9e9e1e..e32d807e40 100644 --- a/pkgs/boring/CONTRIBUTING.md +++ b/pkgs/boring/CONTRIBUTING.md @@ -10,21 +10,39 @@ In the `fetch` and `checkout` build modes, `hook/build.dart` provides: profile and release builds), which `hook/link.dart` links into a tree-shaken dynamic library containing only the functions recorded via `@RecordUse()`. -Every GitHub Release contains both the dynamic and the static library for each -prebuilt target in [`lib/src/hook_helpers/targets.dart`](lib/src/hook_helpers/targets.dart). +The package published on pub.dev contains both the dynamic and the static +library for each prebuilt target in +[`lib/src/hook_helpers/targets.dart`](lib/src/hook_helpers/targets.dart), in +`prebuilt//`, where the `fetch` build mode uses them. They are not +checked in: `.gitignore` ignores `prebuilt/`, but [`.pubignore`](.pubignore), +which pub reads instead, doesn't. The [`package:boring binaries`](../../.github/workflows/boring_binaries.yaml) workflow builds the prebuilt libraries (`tool/precompile_binaries.dart`) from -the vendored BoringSSL whenever a change to the native sources (`src/`, -`third_party/boringssl/`, or `tool/REVISION`) lands on `main`, attaches them to -a `boring-binaries--` pre-release with a provenance attestation -(`gh attestation verify --repo dart-lang/tools`), and opens a pull -request (`tool/regenerate_hashes.dart`) that pins their SHA-256 hashes in -[`lib/src/hook_helpers/hashes.dart`](lib/src/hook_helpers/hashes.dart). +the vendored BoringSSL, adds them to `prebuilt/`, creates the package archive, +and builds the example against it on each desktop OS +([`test/prebuilt_test.dart`](test/prebuilt_test.dart)). It does so for pull +requests that change the native build, the hooks, or the workflow, and when a +change to the native sources (`src/`, `third_party/boringssl/`, or +`tool/REVISION`) lands on `main`. -CI (`tool/check_prebuilt_binaries.sh`) checks that a release of this package -pins libraries built from the sources it vendors, so `fetch` and `checkout` -produce the same BoringSSL. +To release, push a `boring-v` tag, for example by creating a GitHub +release with it. The workflow then builds the libraries from the tagged commit, +tests the archive across Linux, macOS, and Windows, and calls +`dart-lang/setup-dart/.github/workflows/publish.yml` (`bundled-files`, +`attest: true`) to stage the libraries into an isolated checkout, attest the +package archive's SLSA Build L3 provenance, and publish it to pub.dev. +[`publish.yaml`](../../.github/workflows/publish.yaml), which publishes the +other packages of this repository, skips these tags. As the libraries are built +from the tagged commit, the `fetch` and `checkout` build modes produce the same +BoringSSL. + +`dart run tool/precompile_binaries.dart` writes the libraries for the current +OS to `prebuilt/`, so that a path dependency on a checkout can use the `fetch` +build mode. To run `test/prebuilt_test.dart` locally, download the +`test-package-archive` (or `package-archive`) artifact of a workflow run, +extract the `package.tar.gz` in it, and set `BORING_PACKAGE_DIR` to the +extracted directory. ## Updating BoringSSL and Regenerating Bindings @@ -32,8 +50,7 @@ Run `./tool/bump-boringssl-revision.sh [revision]` to update the vendored BoringSSL under `third_party/boringssl/`, record the commit in `tool/REVISION`, and regenerate the FFI bindings (`tool/ffigen.dart`). The `generated` job in [`boring.yaml`](../../.github/workflows/boring.yaml) runs on `ubuntu-24.04` and -verifies that all generated files and [`hashes.dart`](lib/src/hook_helpers/hashes.dart) -are up to date. +verifies that all generated files are up to date. The `refresh` job in the same workflow runs the script weekly against the latest BoringSSL revision and opens a pull request with the result. diff --git a/pkgs/boring/README.md b/pkgs/boring/README.md index 6b1ac96a42..7def4847e3 100644 --- a/pkgs/boring/README.md +++ b/pkgs/boring/README.md @@ -52,9 +52,10 @@ hooks: buildMode: fetch # 'fetch', 'checkout', or 'local' ``` -- **`fetch`** *(default)*: Downloads the prebuilt library of the pinned - release from GitHub Releases and verifies it against the SHA-256 hash pinned - in the package. A hash mismatch is an error. +- **`fetch`** *(default)*: Uses the prebuilt library that comes with the + package published on pub.dev, so the build doesn't download anything. A git + or path dependency on the repository has no prebuilt libraries and requires + `checkout`. - **`checkout`**: Compiles BoringSSL locally from bundled sources via CMake and Ninja. - **`local`**: Uses a custom prebuilt dynamic library at `localPath`, which is diff --git a/pkgs/boring/hook/build.dart b/pkgs/boring/hook/build.dart index 3ef944e508..5bd7f7e427 100644 --- a/pkgs/boring/hook/build.dart +++ b/pkgs/boring/hook/build.dart @@ -6,7 +6,7 @@ import 'dart:io'; import 'package:boring/src/hook_helpers/build_options.dart' show BuildModeEnum, BuildOptions; -import 'package:boring/src/hook_helpers/fetch.dart' show fetchPrebuiltLibrary; +import 'package:boring/src/hook_helpers/prebuilt.dart' show prebuiltLibrary; import 'package:boring/src/hook_helpers/targets.dart' show libraryFileName; import 'package:code_assets/code_assets.dart'; import 'package:hooks/hooks.dart'; @@ -33,15 +33,16 @@ Future main(List args) async { switch (buildOptions.buildMode) { case BuildModeEnum.fetch: - final library = await fetchPrebuiltLibrary(input, static: static); + final library = prebuiltLibrary(input, static: static); _addLibrary(input, output, library, static: static); + output.dependencies.add(library); case BuildModeEnum.checkout: await _buildLocalCMake(input, output, static: static); case BuildModeEnum.local: await _useLocalBinary(input, output, buildOptions.localPath); } - // The hooks runner reruns the hook when any of its Dart sources change, - // including hashes.dart, so only non-Dart inputs are listed. + // The hooks runner reruns the hook when any of its Dart sources change, so + // only non-Dart inputs are listed. output.dependencies.add(input.packageRoot.resolve('pubspec.yaml')); }); } diff --git a/pkgs/boring/hook/link.dart b/pkgs/boring/hook/link.dart index 6becbff162..4f47637cf9 100644 --- a/pkgs/boring/hook/link.dart +++ b/pkgs/boring/hook/link.dart @@ -8,8 +8,7 @@ import 'dart:typed_data'; import 'package:boring/src/bindings/record_use_mapping.g.dart'; import 'package:boring/src/hook_helpers/build_options.dart' show BuildModeEnum, BuildOptions; -import 'package:boring/src/hook_helpers/fetch.dart' show fetchPrebuiltLibrary; -import 'package:boring/src/hook_helpers/hashes.dart' show releaseTag; +import 'package:boring/src/hook_helpers/prebuilt.dart' show prebuiltLibrary; import 'package:code_assets/code_assets.dart'; import 'package:hooks/hooks.dart'; import 'package:logging/logging.dart'; @@ -86,7 +85,7 @@ Future main(List args) async { // throws a `ToolError`, which extends `Error` and is not exported, if it // finds no toolchain. stdout.writeln('boring: linking failed: $e\n$s'); - if (!await _fallBackToPrebuiltLibrary(input, output, e)) rethrow; + if (!_fallBackToPrebuiltLibrary(input, output, e)) rethrow; } }); } @@ -96,17 +95,18 @@ Future main(List args) async { /// /// Returns `false` if there is no equivalent pre-built library to fall back /// to. -Future _fallBackToPrebuiltLibrary( +bool _fallBackToPrebuiltLibrary( LinkInput input, LinkOutputBuilder output, Object linkError, -) async { +) { final code = input.config.code; final target = '${code.targetOS}_${code.targetArchitecture}'; final buildMode = BuildOptions.fromDefines(input.userDefines).buildMode; if (buildMode != BuildModeEnum.fetch) { - // The static library was not fetched, but for example built from a local - // checkout. Falling back would silently swap in different BoringSSL code. + // The static library is not the pre-built one, but for example built from + // a local checkout. Falling back would silently swap in different + // BoringSSL code. stderr.writeln( 'package:boring could not link the static library built in the ' '`${buildMode.name}` build mode for $target. Install a C toolchain ' @@ -116,7 +116,7 @@ Future _fallBackToPrebuiltLibrary( ); return false; } - final library = await fetchPrebuiltLibrary(input, static: false); + final library = prebuiltLibrary(input, static: false); final reason = switch (linkError) { // native_toolchain_c puts the whole linker command, which has an argument // for each used symbol, into the message. @@ -127,10 +127,10 @@ Future _fallBackToPrebuiltLibrary( }; stderr.writeln( 'Warning: package:boring could not tree-shake its native library for ' - '$target, so it bundles the pre-built dynamic library of release ' - '$releaseTag instead, which is not tree-shaken and therefore ' - 'larger. To enable tree-shaking, install a C toolchain (compiler and ' - 'linker) for $target. Linking failed with: $reason', + '$target, so it bundles the pre-built dynamic library instead, which is ' + 'not tree-shaken and therefore larger. To enable tree-shaking, install a ' + 'C toolchain (compiler and linker) for $target. Linking failed with: ' + '$reason', ); output.assets.code.add( CodeAsset( @@ -140,6 +140,7 @@ Future _fallBackToPrebuiltLibrary( file: library, ), ); + output.dependencies.add(library); return true; } diff --git a/pkgs/boring/lib/src/hook_helpers/build_options.dart b/pkgs/boring/lib/src/hook_helpers/build_options.dart index eb0b08ccdb..70601b6d51 100644 --- a/pkgs/boring/lib/src/hook_helpers/build_options.dart +++ b/pkgs/boring/lib/src/hook_helpers/build_options.dart @@ -6,7 +6,8 @@ import 'package:hooks/hooks.dart' show BuildError, HookInputUserDefines; /// How `hook/build.dart` obtains the BoringSSL library, see the README. enum BuildModeEnum { - /// Downloads the prebuilt library of the pinned release. + /// Uses the prebuilt library that comes with the package published on + /// pub.dev. fetch, /// Compiles BoringSSL from the vendored source with CMake. @@ -25,7 +26,7 @@ class BuildOptions { BuildOptions({required this.buildMode, this.localPath}); /// Throws a [BuildError] if `buildMode` is not one of [BuildModeEnum], so a - /// typo doesn't silently download prebuilt binaries instead of building from + /// typo doesn't silently use the prebuilt libraries instead of building from /// source. factory BuildOptions.fromDefines(HookInputUserDefines defines) => BuildOptions( diff --git a/pkgs/boring/lib/src/hook_helpers/fetch.dart b/pkgs/boring/lib/src/hook_helpers/fetch.dart deleted file mode 100644 index 85c4407e47..0000000000 --- a/pkgs/boring/lib/src/hook_helpers/fetch.dart +++ /dev/null @@ -1,144 +0,0 @@ -// Copyright (c) 2026, the Dart project authors. Please see the AUTHORS file -// for details. All rights reserved. Use of this source code is governed by a -// BSD-style license that can be found in the LICENSE file. - -import 'dart:async' show TimeoutException; -import 'dart:io'; -import 'dart:typed_data' show BytesBuilder; - -import 'package:code_assets/code_assets.dart'; -import 'package:crypto/crypto.dart' show sha256; -import 'package:hooks/hooks.dart'; - -import 'hashes.dart' show fileHashes, releaseRepository, releaseTag; -import 'targets.dart' - show libraryFileName, releaseAssetName, releaseAssetUrl, targetTripleFor; - -/// How long to wait for the connection and for each response. -const _connectionTimeout = Duration(seconds: 30); - -/// How long to wait for the whole library to download. -const _downloadTimeout = Duration(minutes: 5); - -const _checkoutHint = - 'To build boring locally from source instead, set ' - '`buildMode: checkout` in your pubspec.yaml under ' - '`hooks.user_defines.boring`.'; - -/// Downloads and verifies the pre-built library for the target of [input] from -/// the GitHub release [releaseTag] of [releaseRepository], caching it in -/// [HookInput.outputDirectoryShared]. -/// -/// Throws a [BuildError] if no hash is registered in [fileHashes] for the -/// target, if downloading fails, or if the downloaded file's SHA-256 checksum -/// does not match [fileHashes]. -Future fetchPrebuiltLibrary( - HookInput input, { - required bool static, -}) async { - final targetOS = input.config.code.targetOS; - final targetArch = input.config.code.targetArchitecture; - final iosSdk = targetOS == OS.iOS ? input.config.code.iOS.targetSdk : null; - - final assetRemoteName = releaseAssetName( - targetOS, - targetArch, - iosSdk: iosSdk, - static: static, - ); - final expectedHash = fileHashes[assetRemoteName]; - - if (expectedHash == null || expectedHash.isEmpty) { - final target = targetTripleFor(targetOS, targetArch, iosSdk: iosSdk); - throw BuildError( - message: - 'No prebuilt boring binary is available for $target ' - '($assetRemoteName) in release $releaseTag of $releaseRepository.\n' - '$_checkoutHint', - ); - } - - final fileName = libraryFileName(targetOS, static: static); - final cachedFile = File.fromUri( - input.outputDirectoryShared - .resolve('$releaseTag/$assetRemoteName/') - .resolve(fileName), - ); - if (await cachedFile.exists()) { - final cachedHash = sha256 - .convert(await cachedFile.readAsBytes()) - .toString(); - if (cachedHash == expectedHash) { - stdout.writeln( - 'boring: using cached prebuilt binary ($assetRemoteName).', - ); - return cachedFile.uri; - } - } - - final binaryUrl = releaseAssetUrl( - repository: releaseRepository, - tag: releaseTag, - assetName: assetRemoteName, - ); - stdout.writeln('boring: fetching prebuilt binary from $binaryUrl...'); - - final bytes = await _download(binaryUrl); - final actualHash = sha256.convert(bytes).toString(); - - if (actualHash != expectedHash) { - throw BuildError( - message: - 'SHA256 hash mismatch for prebuilt binary $assetRemoteName.\n' - 'Expected: $expectedHash\n' - 'Actual: $actualHash\n' - '$_checkoutHint', - ); - } - - stdout.writeln('boring: verified SHA256 checksum ($actualHash).'); - - await cachedFile.parent.create(recursive: true); - await cachedFile.writeAsBytes(bytes); - return cachedFile.uri; -} - -/// Downloads [url], or throws a [BuildError] if the download fails. -/// -/// Honors the `HTTPS_PROXY` family of environment variables, which the hooks -/// runner passes through to hooks, and gives up on a connection that hangs. -Future> _download(Uri url) async { - final client = HttpClient() - ..connectionTimeout = _connectionTimeout - ..findProxy = HttpClient.findProxyFromEnvironment; - try { - final request = await client.getUrl(url).timeout(_connectionTimeout); - final response = await request.close().timeout(_connectionTimeout); - if (response.statusCode != HttpStatus.ok) { - await response.drain(); - throw BuildError( - message: - 'Failed to download prebuilt boring binary from $url ' - '(HTTP ${response.statusCode}).\n' - '$_checkoutHint', - ); - } - final builder = BytesBuilder(copy: false); - await response.forEach(builder.add).timeout(_downloadTimeout); - return builder.takeBytes(); - } on IOException catch (e) { - throw BuildError( - message: - 'Network error downloading prebuilt boring binary from $url: $e\n' - '$_checkoutHint', - ); - } on TimeoutException catch (e) { - throw BuildError( - message: - 'Timed out downloading prebuilt boring binary from $url: $e\n' - '$_checkoutHint', - ); - } finally { - client.close(force: true); - } -} diff --git a/pkgs/boring/lib/src/hook_helpers/hashes.dart b/pkgs/boring/lib/src/hook_helpers/hashes.dart deleted file mode 100644 index 1d53ecf64c..0000000000 --- a/pkgs/boring/lib/src/hook_helpers/hashes.dart +++ /dev/null @@ -1,67 +0,0 @@ -// Copyright (c) 2026, the Dart project authors. Please see the AUTHORS file -// for details. All rights reserved. Use of this source code is governed by a -// BSD-style license that can be found in the LICENSE file. - -// coverage:ignore-file -// THIS FILE IS GENERATED BY `tool/regenerate_hashes.dart`. - -/// The GitHub repository of the release with the prebuilt libraries. -const releaseRepository = 'dart-lang/tools'; - -/// The tag of the release with the prebuilt libraries. -const releaseTag = 'boring-binaries-20261117-a385c332fa79'; - -/// The commit of this repository that the libraries were built from, or empty -/// if they were built elsewhere. The `analyze` job of -/// .github/workflows/boring.yaml checks that the native sources haven't -/// changed since. -const sourceCommit = 'a385c332fa797229cf8da0c464606a026c33e3ff'; - -/// Mapping from release asset name (see `releaseAssetName`) to -/// SHA-256 hash. -const fileHashes = { - 'boring-android-arm-libbssl_dart.so': - 'a9763314d4ee19663dda3032d7466bea96bdb8f1ca57880ce2e532e932d68b06', - 'boring-android-arm-libbssl_dart_static.a': - 'd2561e33fb55dd41ca50e345d1361dc188ef681e30230da1d0d7549026bf0dc0', - 'boring-android-arm64-libbssl_dart.so': - 'f8e542aceb0e75d430d75585a629c45df46b88a6dac8da5021c0e9dffec408e1', - 'boring-android-arm64-libbssl_dart_static.a': - 'c9439ce2c2c161a2709362e23bf34e261416b0f54345f6c7b8851a66e93d752b', - 'boring-android-x64-libbssl_dart.so': - '001a1f8a02606cfaf1c1c021df297029977281f5af3f6b270e3c58af6fc649e1', - 'boring-android-x64-libbssl_dart_static.a': - '3150c75843b5622d1b6d45883157c0b1a123c939a682ecf9500e48e381856e9a', - 'boring-ios-arm64-iphoneos-libbssl_dart.dylib': - 'd05f1875963538dd062840fa14979ce43f1e4994e191a3b379e9064b8503e042', - 'boring-ios-arm64-iphoneos-libbssl_dart_static.a': - 'f5b73ecf3d5beb3eb4fd53763a6d2217e4954fedc222f954fb93246e57ac5eff', - 'boring-ios-arm64-iphonesimulator-libbssl_dart.dylib': - 'a36d4bff9284ca7607a5678b2b936b4afec7a06fdd15eceefe18ef84a75ec41a', - 'boring-ios-arm64-iphonesimulator-libbssl_dart_static.a': - '409c216f8c0b77a893591baaa8c0b673dbdb7bbb5fa33c484806918443dee449', - 'boring-ios-x64-iphonesimulator-libbssl_dart.dylib': - '5429154af47ab0ba255403a974b2e19acb4bc228654053b057f203cc7667b522', - 'boring-ios-x64-iphonesimulator-libbssl_dart_static.a': - 'f31d6e62588d2b7414cfcb51016d61729fe024a14893ace099c4682a39810395', - 'boring-linux-arm64-libbssl_dart.so': - 'e6680fa8b82951687c1262aaa5d6b725543d678c8613bea5141106b8d84a0427', - 'boring-linux-arm64-libbssl_dart_static.a': - '23c50a3cba918d4fb70bd9cc433b376ef9b76a7eb59481732ad5a0a9aeac87a2', - 'boring-linux-x64-libbssl_dart.so': - 'd94b441b5951654d0230b80cab3b7c4393387d4a9d49aac4bbc7428a34c9a668', - 'boring-linux-x64-libbssl_dart_static.a': - '021d46b97b0930630b7a14d199c4ce8d933901758d614b7bb232f2f9ea879407', - 'boring-macos-arm64-libbssl_dart.dylib': - '5e7c5a1d6240eacf59c10bfddf73deabb2e5c13434a8982d8ca93b3e308a5cf2', - 'boring-macos-arm64-libbssl_dart_static.a': - 'bf8404629863a93f2ecde28ee6748ea949f0c4d9328f48e20d400d272c584f43', - 'boring-macos-x64-libbssl_dart.dylib': - '46604ff4378520aa4fbf4548e1612608c21fbfe653a481efee1ff0bbb989e01d', - 'boring-macos-x64-libbssl_dart_static.a': - 'e0d7b3fe73521a03da800f0da96f8d01793ca29c94e4296ac95ae6befbba6681', - 'boring-windows-x64-bssl_dart.dll': - '7deaa2978c6187390fd2ba7112395416de7c469efc5cd4d7a206daea93fab567', - 'boring-windows-x64-bssl_dart_static.lib': - '43e9c08041f0d620432157b0bd91336933b7897916b03b64c7cfb6720690fcf6', -}; diff --git a/pkgs/boring/lib/src/hook_helpers/prebuilt.dart b/pkgs/boring/lib/src/hook_helpers/prebuilt.dart new file mode 100644 index 0000000000..6b2ae274e2 --- /dev/null +++ b/pkgs/boring/lib/src/hook_helpers/prebuilt.dart @@ -0,0 +1,66 @@ +// Copyright (c) 2026, the Dart project authors. Please see the AUTHORS file +// for details. All rights reserved. Use of this source code is governed by a +// BSD-style license that can be found in the LICENSE file. + +import 'dart:io'; + +import 'package:code_assets/code_assets.dart'; +import 'package:hooks/hooks.dart'; + +import 'targets.dart' + show + prebuiltDirectory, + prebuiltLibraryPath, + prebuiltTargets, + targetTripleFor; + +const _checkoutHint = + 'To build boring locally from source instead, set ' + '`buildMode: checkout` in your pubspec.yaml under ' + '`hooks.user_defines.boring`.'; + +/// The prebuilt library for the target of [input] in the [prebuiltDirectory] +/// of the package. +/// +/// `.github/workflows/boring_binaries.yaml` adds the prebuilt libraries to the +/// package that it publishes to pub.dev, so they come with the package instead +/// of being downloaded. +/// +/// Throws a [BuildError] if there is no prebuilt library for the target, or if +/// the package doesn't have it, as for a git or path dependency on the +/// repository. +Uri prebuiltLibrary(HookInput input, {required bool static}) { + final targetOS = input.config.code.targetOS; + final targetArch = input.config.code.targetArchitecture; + final iosSdk = targetOS == OS.iOS ? input.config.code.iOS.targetSdk : null; + final target = targetTripleFor(targetOS, targetArch, iosSdk: iosSdk); + + if (!prebuiltTargets.contains((targetOS, targetArch, iosSdk))) { + throw BuildError( + message: + 'No prebuilt boring library is available for $target.\n' + '$_checkoutHint', + ); + } + + final path = prebuiltLibraryPath( + targetOS, + targetArch, + iosSdk: iosSdk, + static: static, + ); + final library = input.packageRoot.resolve('$prebuiltDirectory/$path'); + if (!File.fromUri(library).existsSync()) { + throw BuildError( + message: + 'The prebuilt boring library for $target is missing: ' + '${library.toFilePath()} does not exist. Only the package published ' + 'on pub.dev has the prebuilt libraries, a git or path dependency on ' + 'its repository does not.\n' + '$_checkoutHint', + ); + } + + stdout.writeln('boring: using the prebuilt library ${library.toFilePath()}.'); + return library; +} diff --git a/pkgs/boring/lib/src/hook_helpers/targets.dart b/pkgs/boring/lib/src/hook_helpers/targets.dart index 6ce3a73d10..2b3c38cfb3 100644 --- a/pkgs/boring/lib/src/hook_helpers/targets.dart +++ b/pkgs/boring/lib/src/hook_helpers/targets.dart @@ -23,17 +23,13 @@ const prebuiltTargets = <(OS, Architecture, IOSSdk?)>[ (OS.windows, Architecture.x64, null), ]; -/// The URL of the release asset [assetName] of the GitHub release [tag] of -/// [repository] (`owner/name`). +/// The directory of the package with the prebuilt libraries, relative to the +/// package root. /// -/// hashes.dart has the repository and the tag of the pinned release. -Uri releaseAssetUrl({ - required String repository, - required String tag, - required String assetName, -}) => Uri.parse( - 'https://github.com/$repository/releases/download/$tag/$assetName', -); +/// It is not checked in. `.github/workflows/boring_binaries.yaml` adds the +/// libraries to the package that it publishes, and +/// `tool/precompile_binaries.dart` writes them here by default. +const prebuiltDirectory = 'prebuilt'; /// Formats a canonical target identifier, including [iosSdk] when targeting iOS /// so device (`iphoneos`) and simulator (`iphonesimulator`) binaries do not @@ -53,13 +49,16 @@ String libraryFileName(OS os, {required bool static}) => static ? os.staticlibFileName('bssl_dart_static') : os.dylibFileName('bssl_dart'); -/// The name of the GitHub release asset with the prebuilt library for [os] and -/// [arch]. -String releaseAssetName( +/// The path of the prebuilt library for [os] and [arch] relative to +/// [prebuiltDirectory]. +/// +/// Each target has its own directory, so that the libraries keep the file +/// names that `src/CMakeLists.txt` gives them. +String prebuiltLibraryPath( OS os, Architecture arch, { IOSSdk? iosSdk, required bool static, }) => - 'boring-${targetTripleFor(os, arch, iosSdk: iosSdk)}-' + '${targetTripleFor(os, arch, iosSdk: iosSdk)}/' '${libraryFileName(os, static: static)}'; diff --git a/pkgs/boring/pubspec.yaml b/pkgs/boring/pubspec.yaml index 14738110ce..ea92a65ca9 100644 --- a/pkgs/boring/pubspec.yaml +++ b/pkgs/boring/pubspec.yaml @@ -13,7 +13,6 @@ environment: dependencies: code_assets: ^2.1.0 - crypto: ^3.0.6 hooks: ^2.2.0 logging: ^1.3.0 meta: ^1.19.0 @@ -29,9 +28,9 @@ dev_dependencies: test: ^1.32.0 # User-defines only apply from the root package, so this makes the tests and -# the example of this package build the vendored BoringSSL from source instead -# of downloading the prebuilt libraries. It has no effect on packages that -# depend on boring. +# the example of this package build the vendored BoringSSL from source, as only +# the published package has the prebuilt libraries. It has no effect on packages +# that depend on boring. hooks: user_defines: boring: diff --git a/pkgs/boring/test/hook_helpers_test.dart b/pkgs/boring/test/hook_helpers_test.dart index f9064829c5..c3e8fc1c1a 100644 --- a/pkgs/boring/test/hook_helpers_test.dart +++ b/pkgs/boring/test/hook_helpers_test.dart @@ -5,89 +5,57 @@ import 'dart:io'; import 'package:boring/src/hook_helpers/build_options.dart'; -import 'package:boring/src/hook_helpers/fetch.dart'; -import 'package:boring/src/hook_helpers/hashes.dart'; +import 'package:boring/src/hook_helpers/prebuilt.dart'; import 'package:boring/src/hook_helpers/targets.dart'; import 'package:code_assets/code_assets.dart'; import 'package:hooks/hooks.dart'; import 'package:test/test.dart'; void main() { - group('hashes.dart', () { - // If the asset naming and the hashes file drift apart, `fetch` finds no - // hash and fails for every user. - test('pins exactly the assets of the prebuilt targets', () { - final expected = { - for (final (os, arch, iosSdk) in prebuiltTargets) - for (final static in [false, true]) - releaseAssetName(os, arch, iosSdk: iosSdk, static: static), - }; - if (sourceCommit.isEmpty) { - // A release built elsewhere may predate some of the prebuilt targets. - expect(fileHashes, isNotEmpty); - expect(expected, containsAll(fileHashes.keys)); - } else { - expect(fileHashes.keys, unorderedEquals(expected)); - } - }); - - test('has SHA-256 hashes', () { - for (final MapEntry(key: asset, value: hash) in fileHashes.entries) { - expect(hash, matches(RegExp(r'^[0-9a-f]{64}$')), reason: asset); - } - }); - - test('pins a release', () { - expect(releaseRepository, matches(RegExp(r'^[\w.-]+/[\w.-]+$'))); - expect(releaseTag, isNotEmpty); - expect(sourceCommit, anyOf(isEmpty, matches(RegExp(r'^[0-9a-f]{40}$')))); - expect( - releaseAssetUrl( - repository: releaseRepository, - tag: releaseTag, - assetName: 'boring-linux-x64-libbssl_dart.so', - ).toString(), - 'https://github.com/$releaseRepository/releases/download/$releaseTag/' - 'boring-linux-x64-libbssl_dart.so', - ); - }); - }); - - group('releaseAssetName', () { + group('prebuiltLibraryPath', () { test('uses the platform library names', () { expect( - releaseAssetName(OS.linux, Architecture.x64, static: false), - 'boring-linux-x64-libbssl_dart.so', + prebuiltLibraryPath(OS.linux, Architecture.x64, static: false), + 'linux-x64/libbssl_dart.so', ); expect( - releaseAssetName(OS.linux, Architecture.arm64, static: true), - 'boring-linux-arm64-libbssl_dart_static.a', + prebuiltLibraryPath(OS.linux, Architecture.arm64, static: true), + 'linux-arm64/libbssl_dart_static.a', ); expect( - releaseAssetName(OS.macOS, Architecture.arm64, static: false), - 'boring-macos-arm64-libbssl_dart.dylib', + prebuiltLibraryPath(OS.macOS, Architecture.arm64, static: false), + 'macos-arm64/libbssl_dart.dylib', ); expect( - releaseAssetName(OS.windows, Architecture.x64, static: false), - 'boring-windows-x64-bssl_dart.dll', + prebuiltLibraryPath(OS.windows, Architecture.x64, static: false), + 'windows-x64/bssl_dart.dll', ); expect( - releaseAssetName(OS.windows, Architecture.x64, static: true), - 'boring-windows-x64-bssl_dart_static.lib', + prebuiltLibraryPath(OS.windows, Architecture.x64, static: true), + 'windows-x64/bssl_dart_static.lib', ); }); test('distinguishes the iOS SDKs', () { expect( - releaseAssetName( + prebuiltLibraryPath( OS.iOS, Architecture.arm64, iosSdk: IOSSdk.iPhoneSimulator, static: true, ), - 'boring-ios-arm64-iphonesimulator-libbssl_dart_static.a', + 'ios-arm64-iphonesimulator/libbssl_dart_static.a', ); }); + + test('gives every prebuilt library its own path', () { + final paths = [ + for (final (os, arch, iosSdk) in prebuiltTargets) + for (final static in [false, true]) + prebuiltLibraryPath(os, arch, iosSdk: iosSdk, static: static), + ]; + expect(paths.toSet(), hasLength(paths.length)); + }); }); group('BuildOptions.fromDefines', () { @@ -136,25 +104,57 @@ void main() { }); }); - group('fetchPrebuiltLibrary', () { - test('throws a BuildError when no prebuilt binary exists for target', () { - final builder = BuildInputBuilder() - ..setupShared( - packageRoot: _basePath, - packageName: 'boring', - outputDirectoryShared: _basePath.resolve('.dart_tool/shared/'), - outputFile: _basePath.resolve('.dart_tool/output.json'), - ) - ..config.setupBuild(linkingEnabled: false) - ..addExtension( - CodeAssetExtension( - targetOS: OS.linux, - targetArchitecture: Architecture.riscv64, - linkModePreference: LinkModePreference.dynamic, + group('prebuiltLibrary', () { + late Directory packageRoot; + + setUp(() async { + packageRoot = await Directory.systemTemp.createTemp('boring_package_'); + addTearDown(() => packageRoot.delete(recursive: true)); + }); + + test('returns the library in the prebuilt directory', () async { + final library = File.fromUri( + packageRoot.uri.resolve('prebuilt/linux-x64/libbssl_dart_static.a'), + ); + await library.create(recursive: true); + expect( + prebuiltLibrary( + _buildInput(packageRoot.uri, OS.linux, Architecture.x64), + static: true, + ), + library.uri, + ); + }); + + test('throws a BuildError if the package has no prebuilt libraries', () { + final library = packageRoot.uri.resolve( + 'prebuilt/linux-x64/libbssl_dart.so', + ); + expect( + () => prebuiltLibrary( + _buildInput(packageRoot.uri, OS.linux, Architecture.x64), + static: false, + ), + throwsA( + isA().having( + (e) => e.message, + 'message', + allOf( + contains(library.toFilePath()), + contains('git or path dependency'), + contains('buildMode: checkout'), + ), ), - ); + ), + ); + }); + + test('throws a BuildError when no prebuilt binary exists for target', () { expect( - () => fetchPrebuiltLibrary(builder.build(), static: false), + () => prebuiltLibrary( + _buildInput(packageRoot.uri, OS.linux, Architecture.riscv64), + static: false, + ), throwsA( isA().having( (e) => e.message, @@ -172,6 +172,27 @@ void main() { final _basePath = Directory.current.uri; +/// The input of hook/build.dart for [os] and [arch] in a package at +/// [packageRoot]. +BuildInput _buildInput(Uri packageRoot, OS os, Architecture arch) { + final builder = BuildInputBuilder() + ..setupShared( + packageRoot: packageRoot, + packageName: 'boring', + outputDirectoryShared: packageRoot.resolve('.dart_tool/shared/'), + outputFile: packageRoot.resolve('.dart_tool/output.json'), + ) + ..config.setupBuild(linkingEnabled: false) + ..addExtension( + CodeAssetExtension( + targetOS: os, + targetArchitecture: arch, + linkModePreference: LinkModePreference.dynamic, + ), + ); + return builder.build(); +} + /// The user-defines of a root package whose pubspec.yaml has [defines] under /// `hooks.user_defines.boring`. HookInputUserDefines _userDefines(Map defines) { diff --git a/pkgs/boring/test/prebuilt_test.dart b/pkgs/boring/test/prebuilt_test.dart new file mode 100644 index 0000000000..3486439bd0 --- /dev/null +++ b/pkgs/boring/test/prebuilt_test.dart @@ -0,0 +1,301 @@ +// Copyright (c) 2026, the Dart project authors. Please see the AUTHORS file +// for details. All rights reserved. Use of this source code is governed by a +// BSD-style license that can be found in the LICENSE file. + +// Checks the prebuilt libraries of the package at BORING_PACKAGE_DIR, such as +// the extracted archive that .github/workflows/boring_binaries.yaml publishes: +// that it has those of every prebuilt target, and that the example builds with +// `dart build cli` in an app that depends on it in the default `fetch` build +// mode. Cross-compiles to Linux with a cross-toolchain, which tree-shakes the +// prebuilt static library, and without one, which falls back to the prebuilt +// dynamic library. +// +// Skipped without BORING_PACKAGE_DIR, as a checkout of this package has no +// prebuilt libraries. +@TestOn('linux || mac-os || windows') +@Timeout(Duration(minutes: 15)) +library; + +import 'dart:io'; +import 'dart:typed_data'; + +import 'package:boring/src/hook_helpers/targets.dart' + show prebuiltDirectory, prebuiltLibraryPath, prebuiltTargets; +import 'package:code_assets/code_assets.dart'; +import 'package:test/test.dart'; + +const _usedFunctions = ['EVP_sha256', 'EVP_DigestFinal', 'OPENSSL_free']; +const _unusedFunctions = ['EVP_sha512', 'EVP_AEAD_CTX_seal', 'X509_verify']; + +/// The package with the prebuilt libraries to build the example against. +final _packageDir = Platform.environment['BORING_PACKAGE_DIR']; + +final _skipWithoutPackage = _packageDir == null + ? 'Set BORING_PACKAGE_DIR to a package with the prebuilt libraries, such ' + 'as the package-archive artifact of ' + '.github/workflows/boring_binaries.yaml.' + : null; + +Uri get _package => Directory(_packageDir!).absolute.uri; + +void main() { + test( + 'the package has the prebuilt libraries of every prebuilt target', + () { + for (final (os, arch, iosSdk) in prebuiltTargets) { + for (final static in [false, true]) { + final path = prebuiltLibraryPath( + os, + arch, + iosSdk: iosSdk, + static: static, + ); + final library = File.fromUri( + _package.resolve('$prebuiltDirectory/$path'), + ); + expect(library.existsSync(), isTrue, reason: library.path); + } + } + }, + skip: _skipWithoutPackage, + ); + + group( + 'cross-compilation with toolchain (linux-arm64)', + () { + late Uri bundle; + late File executable; + late File library; + + setUpAll(() async { + final appDir = await _createConsumerExamplePackage(); + final output = await Directory.systemTemp.createTemp( + 'boring_example_linux_arm64_', + ); + addTearDown(() => output.delete(recursive: true)); + + final build = await Process.run( + Platform.resolvedExecutable, + [ + 'build', + 'cli', + '--target', + 'bin/boring_example.dart', + '--target-os=linux', + '--target-arch=arm64', + '--output', + output.path, + ], + workingDirectory: appDir.path, + ); + expect(build.exitCode, 0, reason: '${build.stdout}\n${build.stderr}'); + + bundle = output.uri.resolve('bundle/'); + executable = File.fromUri(bundle.resolve('bin/boring_example')); + library = File.fromUri( + bundle.resolve('lib/${OS.linux.dylibFileName('bssl_dart')}'), + ); + }); + + test('builds a linux-arm64 executable and dynamic library', () { + // EM_AARCH64 = 183. + expect(_elfMachine(executable.readAsBytesSync()), 183); + expect(_elfMachine(library.readAsBytesSync()), 183); + }); + + test('the library only exports the functions the example uses', () { + final symbols = _elfDefinedDynamicSymbols(library.readAsBytesSync()); + for (final used in _usedFunctions) { + expect(symbols, contains('bssl_dart_$used'), reason: used); + } + for (final unused in _unusedFunctions) { + expect(symbols, isNot(contains('bssl_dart_$unused')), reason: unused); + } + }); + + test('the library is tree-shaken', () { + // With all functions, the library is about 3 MB. + expect(library.lengthSync(), lessThan(1024 * 1024)); + }); + }, + skip: + _skipWithoutPackage ?? + (Platform.environment['CI'] != 'true' && !_hasAarch64LinuxToolchain() + ? 'aarch64-linux-gnu-gcc is not installed' + : null), + ); + + group('cross-compilation without toolchain', () { + // On macOS and Windows, `x86_64-linux-gnu-gcc` is not installed, so + // targeting `linux-x64` exercises the linker-less fallback naturally. + // On Linux (`x64`), we target `linux-arm64` with a stub on PATH that masks + // `aarch64-linux-gnu-gcc` if installed. + final targetArch = Platform.isLinux ? 'arm64' : 'x64'; + // EM_AARCH64 = 183, EM_X86_64 = 62. + final expectedElfMachine = Platform.isLinux ? 183 : 62; + + late Uri bundle; + late File executable; + late File library; + + setUpAll(() async { + final appDir = await _createConsumerExamplePackage(); + final output = await Directory.systemTemp.createTemp( + 'boring_example_no_linker_', + ); + addTearDown(() => output.delete(recursive: true)); + + Map? environment; + if (Platform.isLinux) { + final maskDir = await Directory.systemTemp.createTemp( + 'boring_no_aarch64_gcc_', + ); + addTearDown(() => maskDir.delete(recursive: true)); + final fakeGcc = File.fromUri( + maskDir.uri.resolve('aarch64-linux-gnu-gcc'), + ); + await fakeGcc.writeAsString('#!/bin/sh\nexit 1\n'); + await Process.run('chmod', ['+x', fakeGcc.path]); + final currentPath = Platform.environment['PATH'] ?? ''; + environment = {'PATH': '${maskDir.path}:$currentPath'}; + } + + final build = await Process.run( + Platform.resolvedExecutable, + [ + 'build', + 'cli', + '--target', + 'bin/boring_example.dart', + '--target-os=linux', + '--target-arch=$targetArch', + '--output', + output.path, + ], + workingDirectory: appDir.path, + environment: environment, + ); + expect(build.exitCode, 0, reason: '${build.stdout}\n${build.stderr}'); + + bundle = output.uri.resolve('bundle/'); + executable = File.fromUri(bundle.resolve('bin/boring_example')); + library = File.fromUri( + bundle.resolve('lib/${OS.linux.dylibFileName('bssl_dart')}'), + ); + }); + + test('builds a linux-$targetArch executable and dynamic library', () { + expect(_elfMachine(executable.readAsBytesSync()), expectedElfMachine); + expect(_elfMachine(library.readAsBytesSync()), expectedElfMachine); + }); + + test( + 'falls back to bundling the pre-built dynamic library without ' + 'tree-shaking', + () { + final symbols = _elfDefinedDynamicSymbols(library.readAsBytesSync()); + for (final used in _usedFunctions) { + expect(symbols, contains('bssl_dart_$used'), reason: used); + } + for (final unused in _unusedFunctions) { + expect(symbols, contains('bssl_dart_$unused'), reason: unused); + } + expect(library.lengthSync(), greaterThan(1024 * 1024)); + }, + ); + }, skip: _skipWithoutPackage); +} + +/// Creates a temporary app that depends on the package at BORING_PACKAGE_DIR +/// in the default `fetch` build mode, so that cross-compilation uses its +/// prebuilt libraries rather than compiling BoringSSL from source with CMake. +Future _createConsumerExamplePackage() async { + final appDir = await Directory.systemTemp.createTemp( + 'boring_example_cross_app_', + ); + addTearDown(() => appDir.delete(recursive: true)); + + await File.fromUri(appDir.uri.resolve('pubspec.yaml')).writeAsString(''' +name: boring_cross_example +publish_to: none +environment: + sdk: ^3.10.0 +dependencies: + boring: + path: ${_package.toFilePath()} +'''); + + final binDir = Directory.fromUri(appDir.uri.resolve('bin/')); + await binDir.create(recursive: true); + await File.fromUri( + _package.resolve('example/boring_example.dart'), + ).copy(binDir.uri.resolve('boring_example.dart').toFilePath()); + + final pubGet = await Process.run( + Platform.resolvedExecutable, + ['pub', 'get'], + workingDirectory: appDir.path, + ); + expect( + pubGet.exitCode, + 0, + reason: '${pubGet.stdout}\n${pubGet.stderr}', + ); + return appDir; +} + +bool _hasAarch64LinuxToolchain() { + final which = Platform.isWindows ? 'where' : 'which'; + if (Process.runSync(which, ['aarch64-linux-gnu-gcc']).exitCode == 0) { + return true; + } + return Platform.isMacOS && + (File('/opt/homebrew/bin/aarch64-linux-gnu-gcc').existsSync() || + File('/usr/local/bin/aarch64-linux-gnu-gcc').existsSync()); +} + +/// Returns the ELF `e_machine` field of [bytes]. +int _elfMachine(Uint8List bytes) { + expect(bytes.length, greaterThanOrEqualTo(64)); + // 0x7f 'E' 'L' 'F', 64-bit (2), little-endian (1). + expect(bytes.sublist(0, 6), [0x7f, 0x45, 0x4c, 0x46, 2, 1]); + return ByteData.sublistView(bytes).getUint16(18, Endian.little); +} + +/// Returns the names of all defined symbols in the `.dynsym` section of a +/// 64-bit little-endian ELF binary. +Set _elfDefinedDynamicSymbols(Uint8List bytes) { + final data = ByteData.sublistView(bytes); + final shoff = data.getUint64(40, Endian.little); + final shentsize = data.getUint16(58, Endian.little); + final shnum = data.getUint16(60, Endian.little); + + const shtDynsym = 11; + for (var i = 0; i < shnum; i++) { + final shdr = shoff + i * shentsize; + final shType = data.getUint32(shdr + 4, Endian.little); + if (shType != shtDynsym) continue; + + final symOffset = data.getUint64(shdr + 24, Endian.little); + final symSize = data.getUint64(shdr + 32, Endian.little); + final strTabIndex = data.getUint32(shdr + 40, Endian.little); + final symEntSize = data.getUint64(shdr + 56, Endian.little); + + final strShdr = shoff + strTabIndex * shentsize; + final strOffset = data.getUint64(strShdr + 24, Endian.little); + + final symbols = {}; + final count = symSize ~/ symEntSize; + for (var j = 0; j < count; j++) { + final sym = symOffset + j * symEntSize; + final stName = data.getUint32(sym, Endian.little); + final stShndx = data.getUint16(sym + 6, Endian.little); + if (stName == 0 || stShndx == 0) continue; + final start = strOffset + stName; + final end = bytes.indexOf(0, start); + symbols.add(String.fromCharCodes(bytes, start, end)); + } + return symbols; + } + throw StateError('No .dynsym section found in ELF binary.'); +} diff --git a/pkgs/boring/test/tree_shaking_test.dart b/pkgs/boring/test/tree_shaking_test.dart index 4f851143e4..0be15623aa 100644 --- a/pkgs/boring/test/tree_shaking_test.dart +++ b/pkgs/boring/test/tree_shaking_test.dart @@ -2,16 +2,16 @@ // for details. All rights reserved. Use of this source code is governed by a // BSD-style license that can be found in the LICENSE file. -// Builds the example with `dart build cli` (both native and cross-compiled), -// which runs hook/link.dart with the recorded uses of the bindings, and checks -// that the bundled library only has the functions the example uses. +// Builds the example with `dart build cli`, which runs hook/link.dart with the +// recorded uses of the bindings, and checks that the bundled library only has +// the functions the example uses. test/prebuilt_test.dart checks the same for +// the prebuilt libraries, cross-compiled. @TestOn('linux || mac-os || windows') @Timeout(Duration(minutes: 15)) library; import 'dart:ffi'; import 'dart:io'; -import 'dart:typed_data'; import 'package:code_assets/code_assets.dart'; import 'package:test/test.dart'; @@ -78,242 +78,4 @@ void main() { expect(library.lengthSync(), lessThan(1024 * 1024)); }); }); - - group( - 'cross-compilation with toolchain (linux-arm64)', - () { - late Uri bundle; - late File executable; - late File library; - - setUpAll(() async { - final appDir = await _createConsumerExamplePackage(); - final output = await Directory.systemTemp.createTemp( - 'boring_example_linux_arm64_', - ); - addTearDown(() => output.delete(recursive: true)); - - final build = await Process.run( - Platform.resolvedExecutable, - [ - 'build', - 'cli', - '--target', - 'bin/boring_example.dart', - '--target-os=linux', - '--target-arch=arm64', - '--output', - output.path, - ], - workingDirectory: appDir.path, - ); - expect(build.exitCode, 0, reason: '${build.stdout}\n${build.stderr}'); - - bundle = output.uri.resolve('bundle/'); - executable = File.fromUri(bundle.resolve('bin/boring_example')); - library = File.fromUri( - bundle.resolve('lib/${OS.linux.dylibFileName('bssl_dart')}'), - ); - }); - - test('builds a linux-arm64 executable and dynamic library', () { - // EM_AARCH64 = 183. - expect(_elfMachine(executable.readAsBytesSync()), 183); - expect(_elfMachine(library.readAsBytesSync()), 183); - }); - - test('the library only exports the functions the example uses', () { - final symbols = _elfDefinedDynamicSymbols(library.readAsBytesSync()); - for (final used in _usedFunctions) { - expect(symbols, contains('bssl_dart_$used'), reason: used); - } - for (final unused in _unusedFunctions) { - expect(symbols, isNot(contains('bssl_dart_$unused')), reason: unused); - } - }); - - test('the library is tree-shaken', () { - // With all functions, the library is about 3 MB. - expect(library.lengthSync(), lessThan(1024 * 1024)); - }); - }, - skip: Platform.environment['CI'] != 'true' && !_hasAarch64LinuxToolchain() - ? 'aarch64-linux-gnu-gcc is not installed' - : null, - ); - - group('cross-compilation without toolchain', () { - // On macOS and Windows, `x86_64-linux-gnu-gcc` is not installed, so - // targeting `linux-x64` exercises the linker-less fallback naturally. - // On Linux (`x64`), we target `linux-arm64` with a stub on PATH that masks - // `aarch64-linux-gnu-gcc` if installed. - final targetArch = Platform.isLinux ? 'arm64' : 'x64'; - // EM_AARCH64 = 183, EM_X86_64 = 62. - final expectedElfMachine = Platform.isLinux ? 183 : 62; - - late Uri bundle; - late File executable; - late File library; - - setUpAll(() async { - final appDir = await _createConsumerExamplePackage(); - final output = await Directory.systemTemp.createTemp( - 'boring_example_no_linker_', - ); - addTearDown(() => output.delete(recursive: true)); - - Map? environment; - if (Platform.isLinux) { - final maskDir = await Directory.systemTemp.createTemp( - 'boring_no_aarch64_gcc_', - ); - addTearDown(() => maskDir.delete(recursive: true)); - final fakeGcc = File.fromUri( - maskDir.uri.resolve('aarch64-linux-gnu-gcc'), - ); - await fakeGcc.writeAsString('#!/bin/sh\nexit 1\n'); - await Process.run('chmod', ['+x', fakeGcc.path]); - final currentPath = Platform.environment['PATH'] ?? ''; - environment = {'PATH': '${maskDir.path}:$currentPath'}; - } - - final build = await Process.run( - Platform.resolvedExecutable, - [ - 'build', - 'cli', - '--target', - 'bin/boring_example.dart', - '--target-os=linux', - '--target-arch=$targetArch', - '--output', - output.path, - ], - workingDirectory: appDir.path, - environment: environment, - ); - expect(build.exitCode, 0, reason: '${build.stdout}\n${build.stderr}'); - - bundle = output.uri.resolve('bundle/'); - executable = File.fromUri(bundle.resolve('bin/boring_example')); - library = File.fromUri( - bundle.resolve('lib/${OS.linux.dylibFileName('bssl_dart')}'), - ); - }); - - test('builds a linux-$targetArch executable and dynamic library', () { - expect(_elfMachine(executable.readAsBytesSync()), expectedElfMachine); - expect(_elfMachine(library.readAsBytesSync()), expectedElfMachine); - }); - - test( - 'falls back to bundling the pre-built dynamic library without ' - 'tree-shaking', - () { - final symbols = _elfDefinedDynamicSymbols(library.readAsBytesSync()); - for (final used in _usedFunctions) { - expect(symbols, contains('bssl_dart_$used'), reason: used); - } - for (final unused in _unusedFunctions) { - expect(symbols, contains('bssl_dart_$unused'), reason: unused); - } - expect(library.lengthSync(), greaterThan(1024 * 1024)); - }, - ); - }); -} - -/// Creates a temporary consumer package (using the default `fetch` build mode) -/// so cross-compilation uses the pre-built release binaries rather than -/// compiling BoringSSL from source with CMake. -Future _createConsumerExamplePackage() async { - final appDir = await Directory.systemTemp.createTemp( - 'boring_example_cross_app_', - ); - addTearDown(() => appDir.delete(recursive: true)); - - final repoRoot = Directory.current.uri; - await File.fromUri(appDir.uri.resolve('pubspec.yaml')).writeAsString(''' -name: boring_cross_example -publish_to: none -environment: - sdk: ^3.10.0 -dependencies: - boring: - path: ${repoRoot.toFilePath()} -'''); - - final binDir = Directory.fromUri(appDir.uri.resolve('bin/')); - await binDir.create(recursive: true); - await File( - 'example/boring_example.dart', - ).copy(binDir.uri.resolve('boring_example.dart').toFilePath()); - - final pubGet = await Process.run( - Platform.resolvedExecutable, - ['pub', 'get'], - workingDirectory: appDir.path, - ); - expect( - pubGet.exitCode, - 0, - reason: '${pubGet.stdout}\n${pubGet.stderr}', - ); - return appDir; -} - -bool _hasAarch64LinuxToolchain() { - final which = Platform.isWindows ? 'where' : 'which'; - if (Process.runSync(which, ['aarch64-linux-gnu-gcc']).exitCode == 0) { - return true; - } - return Platform.isMacOS && - (File('/opt/homebrew/bin/aarch64-linux-gnu-gcc').existsSync() || - File('/usr/local/bin/aarch64-linux-gnu-gcc').existsSync()); -} - -/// Returns the ELF `e_machine` field of [bytes]. -int _elfMachine(Uint8List bytes) { - expect(bytes.length, greaterThanOrEqualTo(64)); - // 0x7f 'E' 'L' 'F', 64-bit (2), little-endian (1). - expect(bytes.sublist(0, 6), [0x7f, 0x45, 0x4c, 0x46, 2, 1]); - return ByteData.sublistView(bytes).getUint16(18, Endian.little); -} - -/// Returns the names of all defined symbols in the `.dynsym` section of a -/// 64-bit little-endian ELF binary. -Set _elfDefinedDynamicSymbols(Uint8List bytes) { - final data = ByteData.sublistView(bytes); - final shoff = data.getUint64(40, Endian.little); - final shentsize = data.getUint16(58, Endian.little); - final shnum = data.getUint16(60, Endian.little); - - const shtDynsym = 11; - for (var i = 0; i < shnum; i++) { - final shdr = shoff + i * shentsize; - final shType = data.getUint32(shdr + 4, Endian.little); - if (shType != shtDynsym) continue; - - final symOffset = data.getUint64(shdr + 24, Endian.little); - final symSize = data.getUint64(shdr + 32, Endian.little); - final strTabIndex = data.getUint32(shdr + 40, Endian.little); - final symEntSize = data.getUint64(shdr + 56, Endian.little); - - final strShdr = shoff + strTabIndex * shentsize; - final strOffset = data.getUint64(strShdr + 24, Endian.little); - - final symbols = {}; - final count = symSize ~/ symEntSize; - for (var j = 0; j < count; j++) { - final sym = symOffset + j * symEntSize; - final stName = data.getUint32(sym, Endian.little); - final stShndx = data.getUint16(sym + 6, Endian.little); - if (stName == 0 || stShndx == 0) continue; - final start = strOffset + stName; - final end = bytes.indexOf(0, start); - symbols.add(String.fromCharCodes(bytes, start, end)); - } - return symbols; - } - throw StateError('No .dynsym section found in ELF binary.'); } diff --git a/pkgs/boring/tool/check_prebuilt_binaries.sh b/pkgs/boring/tool/check_prebuilt_binaries.sh deleted file mode 100755 index 4c5c57323e..0000000000 --- a/pkgs/boring/tool/check_prebuilt_binaries.sh +++ /dev/null @@ -1,41 +0,0 @@ -#!/usr/bin/env bash -# Copyright (c) 2026, the Dart project authors. Please see the AUTHORS file -# for details. All rights reserved. Use of this source code is governed by a -# BSD-style license that can be found in the LICENSE file. - -# Checks that the prebuilt libraries pinned in lib/src/hook_helpers/hashes.dart -# were built from the current native sources (src/, third_party/boringssl/, and -# tool/REVISION). -# -# Warns if the package version in pubspec.yaml is a -wip version, and fails -# otherwise, so a release of package:boring can't ship stale prebuilt libraries. - -set -euo pipefail - -DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" -cd "$DIR" - -source_commit="$(sed -n "s/^const sourceCommit = '\([0-9a-f]*\)';$/\1/p" lib/src/hook_helpers/hashes.dart)" -stale=false -if [ -z "$source_commit" ]; then - stale=true - message="The prebuilt libraries pinned in lib/src/hook_helpers/hashes.dart weren't built from this repository." -else - git fetch --quiet --depth=1 origin "$source_commit" - if ! git diff --quiet "$source_commit" HEAD -- src third_party/boringssl tool/REVISION; then - stale=true - message="src/, third_party/boringssl/ or tool/REVISION changed since the prebuilt libraries pinned in lib/src/hook_helpers/hashes.dart were built at $source_commit." - fi -fi - -if [ "$stale" = true ]; then - message="$message The 'package:boring binaries' workflow builds and pins new ones when such a change lands on main; merge its pull request before releasing." - if grep -Eq '^version: .*-wip$' pubspec.yaml; then - echo "::warning::$message" - else - echo "::error::$message" - exit 1 - fi -else - echo "The prebuilt libraries were built from the current native sources ($source_commit)." -fi diff --git a/pkgs/boring/tool/precompile_binaries.dart b/pkgs/boring/tool/precompile_binaries.dart index 40d9a0317f..4cfc0e8fcf 100644 --- a/pkgs/boring/tool/precompile_binaries.dart +++ b/pkgs/boring/tool/precompile_binaries.dart @@ -10,7 +10,8 @@ import 'package:args/args.dart'; import 'package:boring/src/hook_helpers/targets.dart'; import 'package:code_assets/code_assets.dart'; -/// Builds the dynamic and the static library for a release. +/// Builds the dynamic and the static library that the published package +/// bundles in `prebuilt/`. /// /// hook/build.dart bundles the dynamic library when linking is disabled, and /// hook/link.dart links the static library into a dynamic library with only @@ -20,6 +21,10 @@ import 'package:code_assets/code_assets.dart'; /// and Android (with the NDK). The `precompile` job of /// .github/workflows/boring_binaries.yaml builds every target in /// `prebuiltTargets`. +/// +/// Writes the libraries to `prebuilt//` by default, where the `fetch` +/// build mode of hook/build.dart finds them, also in a checkout of the +/// repository. void main(List args) async { final parser = ArgParser() ..addOption( @@ -52,8 +57,9 @@ void main(List args) async { ..addOption( 'out-dir', abbr: 'd', - defaultsTo: 'bin', - help: 'Output directory for built release binaries.', + defaultsTo: prebuiltDirectory, + help: + 'Output directory for the libraries, written to //.', ); ArgResults results; @@ -165,13 +171,19 @@ void main(List args) async { builtLibrary.path, ]); } - final releaseAsset = File.fromUri( + final prebuiltFile = File.fromUri( outDir.uri.resolve( - releaseAssetName(targetOS, targetArch, iosSdk: iosSdk, static: static), + prebuiltLibraryPath( + targetOS, + targetArch, + iosSdk: iosSdk, + static: static, + ), ), ); - await builtLibrary.copy(releaseAsset.path); - stdout.writeln('==> Created release binary: ${releaseAsset.path}'); + await prebuiltFile.parent.create(recursive: true); + await builtLibrary.copy(prebuiltFile.path); + stdout.writeln('==> Created prebuilt library: ${prebuiltFile.path}'); } } diff --git a/pkgs/boring/tool/regenerate_hashes.dart b/pkgs/boring/tool/regenerate_hashes.dart deleted file mode 100644 index 1a085a47cc..0000000000 --- a/pkgs/boring/tool/regenerate_hashes.dart +++ /dev/null @@ -1,303 +0,0 @@ -// Copyright (c) 2026, the Dart project authors. Please see the AUTHORS file -// for details. All rights reserved. Use of this source code is governed by a -// BSD-style license that can be found in the LICENSE file. - -// coverage:ignore-file - -import 'dart:io'; -import 'dart:typed_data' show BytesBuilder; - -import 'package:args/args.dart'; -import 'package:boring/src/hook_helpers/hashes.dart' as current; -import 'package:boring/src/hook_helpers/targets.dart'; -import 'package:crypto/crypto.dart' show sha256; - -const _hashesFile = 'lib/src/hook_helpers/hashes.dart'; - -/// Pins the prebuilt libraries of a GitHub release in -/// lib/src/hook_helpers/hashes.dart: the repository, the tag, the commit they -/// were built from, and the SHA-256 hashes of the release assets built by -/// tool/precompile_binaries.dart. -/// -/// Usage: `dart run tool/regenerate_hashes.dart [options] [tag]` -/// -/// Without arguments, re-pins the current release, which the `generated` job -/// of .github/workflows/boring.yaml uses to check hashes.dart. The `pin` job -/// of .github/workflows/boring_binaries.yaml passes the new release's tag, -/// `--source-commit`, and `--assets` with the libraries it just built. -/// -/// Fails without writing anything if an asset of a prebuilt target is missing -/// from a release built by that workflow, so that a failed or partial release -/// can't break the `fetch` build mode for that target. Releases built elsewhere -/// (`sourceCommit` is empty) may predate some targets. -Future main(List args) async { - final parser = ArgParser() - ..addOption( - 'repository', - help: 'The GitHub repository (owner/name) of the release.', - defaultsTo: current.releaseRepository, - ) - ..addOption( - 'source-commit', - help: - 'The commit of this repository that the libraries were built from. ' - 'Defaults to the commit of the tag, looked up with git ls-remote.', - ) - ..addOption( - 'assets', - help: - 'A directory with the release assets to hash instead of downloading ' - 'them.', - ) - ..addFlag('help', abbr: 'h', negatable: false); - final ArgResults options; - try { - options = parser.parse(args); - if (options.rest.length > 1) { - throw FormatException('Expected at most one tag, got ${options.rest}.'); - } - } on FormatException catch (e) { - stderr.writeln('${e.message}\n\n${_usage(parser)}'); - exit(64); - } - if (options.flag('help')) { - stdout.writeln(_usage(parser)); - return; - } - - final repository = options.option('repository')!; - final tag = options.rest.isNotEmpty - ? options.rest.single - : current.releaseTag; - final assetsDir = options.option('assets'); - final sourceCommit = - options.option('source-commit') ?? - await _sourceCommit(repository: repository, tag: tag); - - stdout.writeln( - assetsDir == null - ? 'Hashing the assets of release $tag of $repository...' - : 'Hashing the assets of release $tag of $repository in $assetsDir...', - ); - - final fileHashes = {}; - final missing = []; - final httpClient = HttpClient() - ..findProxy = HttpClient.findProxyFromEnvironment; - try { - for (final (os, arch, iosSdk) in prebuiltTargets) { - for (final static in [false, true]) { - final assetName = releaseAssetName( - os, - arch, - iosSdk: iosSdk, - static: static, - ); - final List? bytes; - try { - bytes = assetsDir != null - ? await _readLocal(Directory(assetsDir), assetName) - : await _fetch( - httpClient, - releaseAssetUrl( - repository: repository, - tag: tag, - assetName: assetName, - ), - ); - } on _DownloadException catch (e) { - stderr.writeln('Not updating $_hashesFile: $e'); - exit(1); - } - if (bytes == null) { - missing.add(assetName); - continue; - } - final hash = sha256.convert(bytes).toString(); - fileHashes[assetName] = hash; - stdout.writeln(' $assetName: $hash'); - } - } - } finally { - httpClient.close(force: true); - } - - if (missing.isNotEmpty) { - final summary = - '${missing.length} of the ${fileHashes.length + missing.length} ' - 'assets of the prebuilt targets are missing from release $tag of ' - '$repository:\n ${missing.join('\n ')}'; - if (sourceCommit.isNotEmpty) { - stderr.writeln('Not updating $_hashesFile: $summary'); - exit(1); - } - stdout.writeln( - 'Warning: $summary\nThe release wasn\'t built by this repository.', - ); - } - - final buffer = StringBuffer() - ..write(await _licenseHeader()) - ..writeln() - ..writeln('// coverage:ignore-file') - ..writeln('// THIS FILE IS GENERATED BY `tool/regenerate_hashes.dart`.') - ..writeln() - ..writeln( - '/// The GitHub repository of the release with the prebuilt ' - 'libraries.', - ) - ..writeln("const releaseRepository = '$repository';") - ..writeln() - ..writeln('/// The tag of the release with the prebuilt libraries.') - ..writeln("const releaseTag = '$tag';") - ..writeln() - ..writeln( - '/// The commit of this repository that the libraries were built ' - 'from, or empty', - ) - ..writeln('/// if they were built elsewhere. The `analyze` job of') - ..writeln( - '/// .github/workflows/boring.yaml checks that the native sources ' - "haven't", - ) - ..writeln('/// changed since.') - ..writeln("const sourceCommit = '$sourceCommit';") - ..writeln() - ..writeln('/// Mapping from release asset name (see `releaseAssetName`) to') - ..writeln('/// SHA-256 hash.') - ..writeln('const fileHashes = {'); - for (final entry in fileHashes.entries) { - buffer - ..writeln(" '${entry.key}':") - ..writeln(" '${entry.value}',"); - } - buffer.writeln('};'); - - await File(_hashesFile).writeAsString(buffer.toString()); - final format = await Process.run(Platform.resolvedExecutable, [ - 'format', - _hashesFile, - ]); - if (format.exitCode != 0) { - stderr.writeln('dart format failed:\n${format.stdout}\n${format.stderr}'); - exit(format.exitCode); - } - stdout.writeln( - 'Updated $_hashesFile with the ${fileHashes.length} hashes of release ' - '$tag of $repository' - '${sourceCommit.isEmpty ? '' : ', built from $sourceCommit'}.', - ); -} - -/// The license header of the existing hashes.dart, whose copyright year is the -/// year the file was created, or a new one for the current year. -Future _licenseHeader() async { - final file = File(_hashesFile); - if (await file.exists()) { - final header = (await file.readAsLines()) - .takeWhile((line) => line.startsWith('//')) - .toList(); - if (header.length == 3 && header.first.startsWith('// Copyright (c) ')) { - return '${header.join('\n')}\n'; - } - } - return '// Copyright (c) ${DateTime.now().year}, the Dart project authors. ' - 'Please see the AUTHORS file\n' - '// for details. All rights reserved. Use of this source code is ' - 'governed by a\n' - '// BSD-style license that can be found in the LICENSE file.\n'; -} - -String _usage(ArgParser parser) => - 'Usage: dart run tool/regenerate_hashes.dart [options] [tag]\n\n' - 'Pins the prebuilt libraries of the GitHub release [tag] (default: ' - '${current.releaseTag}).\n\n' - '${parser.usage}'; - -/// The commit that the libraries of release [tag] were built from. -/// -/// Keeps the current one if the release is unchanged. Otherwise looks up the -/// tag's commit with `git ls-remote`, which unlike the GitHub API isn't rate -/// limited, if the release is in this repository, that is, if it was built by -/// .github/workflows/boring_binaries.yaml. -Future _sourceCommit({ - required String repository, - required String tag, -}) async { - if (repository == current.releaseRepository && tag == current.releaseTag) { - return current.sourceCommit; - } - if (!tag.startsWith('boring-binaries-')) { - // A release of another repository, such as mosuem/boring. - return ''; - } - final result = await Process.run('git', [ - 'ls-remote', - 'https://github.com/$repository.git', - 'refs/tags/$tag', - 'refs/tags/$tag^{}', - ]); - if (result.exitCode != 0) { - stderr.writeln( - 'Failed to look up the commit of tag $tag with git ls-remote:\n' - '${result.stderr}\n' - 'Pass it with --source-commit.', - ); - exit(1); - } - final lines = (result.stdout as String).trim().split('\n'); - // The peeled commit of an annotated tag comes last; a lightweight tag only - // has the one line. - final commit = lines.last.split(RegExp(r'\s+')).first; - if (!RegExp(r'^[0-9a-f]{40}$').hasMatch(commit)) { - stderr.writeln( - 'Tag $tag not found in $repository. Pass the commit the libraries were ' - 'built from with --source-commit.', - ); - exit(1); - } - return commit; -} - -Future?> _readLocal(Directory directory, String assetName) async { - final file = File.fromUri(directory.uri.resolve(assetName)); - if (!await file.exists()) { - stdout.writeln(' Missing: ${file.path}'); - return null; - } - return file.readAsBytes(); -} - -/// Downloads [url], or returns `null` if there is no such asset. -/// -/// Throws a [_DownloadException] for any other failure, which must not be -/// mistaken for a missing asset. -Future?> _fetch(HttpClient client, Uri url) async { - try { - final request = await client.getUrl(url); - final response = await request.close(); - if (response.statusCode == HttpStatus.notFound) { - stdout.writeln(' Missing: $url'); - await response.drain(); - return null; - } - if (response.statusCode != HttpStatus.ok) { - await response.drain(); - throw _DownloadException('$url returned status ${response.statusCode}.'); - } - final builder = BytesBuilder(copy: false); - await response.forEach(builder.add); - return builder.takeBytes(); - } on IOException catch (e) { - throw _DownloadException('Failed to download $url: $e'); - } -} - -class _DownloadException implements Exception { - final String message; - - _DownloadException(this.message); - - @override - String toString() => message; -}