diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 81c3d4e..02d8571 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -325,35 +325,50 @@ jobs: with: persist-credentials: false + # One build per minor version, thread safe or not, in the official images: an extension + # loads into any build of PHP with the same API version and thread safety. + # From 8.6, every official image is thread safe and the -zts tags are gone, their last one an + # older release candidate (docker-library/php#1686), but setup-php and the distributions + # still install NTS. So both 8.6 builds come from php:8.6-rc-cli, and + # build-tally-hooks-in-php-image.sh builds the NTS PHP from the source of the image. + - name: "Choose the images" + run: | + for version in 8.2 8.3 8.4 8.5 8.6; do + for thread_safety in nts zts; do + if [ "$version" = 8.6 ]; then + image="php:8.6-rc-cli" + elif [ "$thread_safety" = zts ]; then + image="php:$version-zts" + else + image="php:$version-cli" + fi + # the digest of the index, one request, where --format reads the manifest of every platform + digest="sha256:$(docker buildx imagetools inspect --raw "$image" | sha256sum | cut -d ' ' -f 1)" + echo "$version $thread_safety $image $digest" + done + done | tee tmp/tally-hooks-images.txt + + # keyed by the images too, so a new release of PHP, such as the next release candidate, is built - name: "Restore the builds" id: cache uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0 with: path: codspeed - key: tally-hooks-${{ runner.arch }}-8.2-8.6-${{ hashFiles('ext/tally_hooks/*', 'build/build-tally-hooks.sh') }} + key: tally-hooks-${{ runner.arch }}-${{ hashFiles('ext/tally_hooks/*', 'build/build-tally-hooks.sh', 'build/build-tally-hooks-in-php-image.sh', 'tmp/tally-hooks-images.txt') }} - # One build per minor version, thread safe or not, in the official images: an extension - # loads into any build of PHP with the same API version and thread safety. - name: "Build" if: steps.cache.outputs.cache-hit != 'true' run: | output="codspeed/linux-$(uname -m)" - for version in 8.2 8.3 8.4 8.5 8.6; do - for variant in cli zts; do - image="php:$version-$variant" - # PHP 8.6 has only release candidates so far - if [ "$version" = 8.6 ]; then - image="php:8.6-rc-$variant" - fi - suffix="" - if [ "$variant" = zts ]; then - suffix="-zts" - fi - docker run --rm -v "$PWD:/tally" -w /tally "$image" bash -c \ - 'apt-get update -qq && apt-get install -y -qq --no-install-recommends $PHPIZE_DEPS >/dev/null && build/build-tally-hooks.sh "$1" && chown "$2" "$1"' \ - _ "$output/tally_hooks-$version$suffix.so" "$(id -u):$(id -g)" - done - done + while read -r version thread_safety image digest; do + suffix="" + if [ "$thread_safety" = zts ]; then + suffix="-zts" + fi + docker run --rm -v "$PWD:/tally" -w /tally "$image@$digest" bash -c \ + 'build/build-tally-hooks-in-php-image.sh "$1" "$2" && chown "$3" "$2"' \ + _ "$thread_safety" "$output/tally_hooks-$version$suffix.so" "$(id -u):$(id -g)" + done < tmp/tally-hooks-images.txt ls -l "$output" - name: "Upload the builds" @@ -523,13 +538,14 @@ jobs: runner: - "ubuntu-24.04" - "ubuntu-24.04-arm" - # the oldest and the newest build of tally_hooks + # the oldest and the newest builds of tally_hooks, 8.6 being a release candidate php-version: - "8.2" - "8.5" + - "8.6" phpts: - "nts" - # and the thread safe build, which tally run picks by ZEND_THREAD_SAFE + # and the thread safe builds, which tally run picks by ZEND_THREAD_SAFE include: - runner: "ubuntu-24.04" php-version: "8.5" @@ -537,6 +553,12 @@ jobs: - runner: "ubuntu-24.04-arm" php-version: "8.5" phpts: "ts" + - runner: "ubuntu-24.04" + php-version: "8.6" + phpts: "ts" + - runner: "ubuntu-24.04-arm" + php-version: "8.6" + phpts: "ts" steps: - name: Harden the runner (Audit all outbound calls) diff --git a/CLAUDE.md b/CLAUDE.md index 0b5ea2a..77c3719 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -24,7 +24,7 @@ Tally benchmarks PHP code by counting instructions, cycles, and memory under Cod - `ext/tally_hooks` – the PHP extension the counted worker calls: functions in `Tally\Hooks` that make Callgrind's client requests through Valgrind's `valgrind.h` and `callgrind.h`. Built with `-DTALLY_HOOKS_RECORDING`, it records the calls instead, for the tests. Keep it to these few functions; the logic belongs in PHP. - `bench/` – Tally's benchmarks of itself, listed in `tally.php`. They cover the code whose cost grows with the suite, a benchmark file, or a profile, and that runs once per case or once per worker: locating and rewriting expectations, planning and diffing new expectations, expanding cases, sharding, reading profiles, and rendering reports. `SuiteSource` generates the code and cases of large benchmark classes as their input. Build inputs in data providers and before methods, which are not counted, and keep the counted call to the one method being measured. `#[Warmup(1)]` keeps autoloading out of the count. - `examples/` – short, artificial benchmarks for README.md, one feature each. `examples/Scripts` shows a data provider with its own `ExpectationSource`, which keeps the numbers in a comment at the top of each script. Keep them readable over realistic; real measurements of Tally belong in `bench/`. CI runs them under CodSpeed next to `bench/`, so they stay valid. -- `build/` – scripts for the build, such as the coverage check. `build-codspeed.sh` builds CodSpeed's Valgrind (Callgrind only, static launcher) at a pinned tag into `codspeed/linux-`, which `1.x` ignores, and `build-tally-hooks.sh` builds `ext/tally_hooks` with `phpize` next to it; `make codspeed` runs both for this machine and PHP, CI builds `tally_hooks` for PHP 8.2 to 8.6, NTS and ZTS, in the official `php` Docker images. `build-release.sh` turns `1.x` into the `release/1.x` tree by committing the builds of both platforms; CI pushes it on every push to `1.x`, and releases are tagged there with `tag-release.sh `, which checks that the generated commit sits on the `1.x` commit to release. `check-release.sh` installs a release tree into a new project with Composer and counts a benchmark, which CI runs on every pull request on x86_64 and aarch64, with PHP 8.2 and 8.5, and 8.5 ZTS. `build/PHPStan` holds Tally's own PHPStan rules and `BenchmarkUsageProvider`, which tells the dead code detector about the methods Tally calls through reflection. `build/stubs` holds the stubs for what PHPStan cannot see, such as the functions of `tally_hooks`. +- `build/` – scripts for the build, such as the coverage check. `build-codspeed.sh` builds CodSpeed's Valgrind (Callgrind only, static launcher) at a pinned tag into `codspeed/linux-`, which `1.x` ignores, and `build-tally-hooks.sh` builds `ext/tally_hooks` with `phpize` next to it; `make codspeed` runs both for this machine and PHP, CI builds `tally_hooks` for PHP 8.2 to 8.6, NTS and ZTS, in the official `php` Docker images with `build-tally-hooks-in-php-image.sh`, which builds PHP from the image's source when the image's PHP is not of the requested thread safety (the tag does not say), and fails unless the build loads into a PHP of that thread safety. `build-release.sh` turns `1.x` into the `release/1.x` tree by committing the builds of both platforms; CI pushes it on every push to `1.x`, and releases are tagged there with `tag-release.sh `, which checks that the generated commit sits on the `1.x` commit to release. `check-release.sh` installs a release tree into a new project with Composer and counts a benchmark, which CI runs on every pull request on x86_64 and aarch64, with PHP 8.2, 8.5, and 8.6, and 8.5 and 8.6 ZTS. `build/PHPStan` holds Tally's own PHPStan rules and `BenchmarkUsageProvider`, which tells the dead code detector about the methods Tally calls through reflection. `build/stubs` holds the stubs for what PHPStan cannot see, such as the functions of `tally_hooks`. - `e2e/` – end-to-end tests with [bashunit](https://bashunit.com), `/_test.sh`; `e2e/bootstrap.sh`, set in `.bashunitrc`, gives each test a directory of its own, which is also its `TMPDIR`. `stripped-extensions` counts a benchmark with CodSpeed's Valgrind while PHP loads the extensions in `E2E_EXTENSIONS` in several ways (its scan directory, another one, the php.ini in `PHPRC`, `-c`): the case must not see them and must count what it counts on a PHP without them. CI installs bashunit into `e2e/` and runs it once per PHP setup (Xdebug, PCOV, both); locally, with the extensions loaded and bashunit installed the same way: `E2E_EXTENSIONS='xdebug pcov' e2e/bashunit test e2e`. Like `tests/Fixtures`, their PHP files are only linted. - `skills/` – Agent Skills for projects that use Tally, shipped in the Composer package, where `extra.skills` declares them for `llm/skills`, and as the plugin `tally` of the marketplace in `.claude-plugin/`, which Claude Code and Codex both read. `tally-rewind` turns past performance fixes of a project into benchmarks, replays them over its history, and improves on the best numbers; its `scripts/measure.sh` measures bench files at commits of the history, each in a worktree, with the Tally version the project has installed. - `tests/Unit` – pure logic, no file system, processes, or network. `tests/Integration` – adapters and the CLI. `tests/Fixtures` – benchmark classes and configuration files the tests load; excluded from PHPStan and the coding standard because some are invalid on purpose. diff --git a/build/build-release.sh b/build/build-release.sh index d5fd256..aa49af5 100755 --- a/build/build-release.sh +++ b/build/build-release.sh @@ -1,7 +1,7 @@ #!/usr/bin/env bash # Turns the 1.x source tree into the release/1.x tree: the same code with the builds of CodSpeed's # Valgrind (build/build-codspeed.sh) and of the tally_hooks extension for PHP 8.2 to 8.6, NTS and -# ZTS (build/build-tally-hooks.sh) in codspeed/, made on each platform. +# ZTS (build/build-tally-hooks-in-php-image.sh) in codspeed/, made on each platform. # Releases are tagged on release/1.x, so a project that requires Tally needs no CodSpeed setup. # With --commit, the builds become a commit, as on the release branch. set -euo pipefail diff --git a/build/build-tally-hooks-in-php-image.sh b/build/build-tally-hooks-in-php-image.sh new file mode 100755 index 0000000..5ea9553 --- /dev/null +++ b/build/build-tally-hooks-in-php-image.sh @@ -0,0 +1,53 @@ +#!/usr/bin/env bash +# Builds tally_hooks for one thread safety inside an official php Docker image, as root, into the +# given file, and checks that the file loads into a PHP of that thread safety. +# From 8.6, every official image is thread safe (docker-library/php#1686), while setup-php and the +# distributions still install NTS. When the PHP of the image is not of the requested thread safety, this +# builds that PHP from the source the image ships (docker-php-source), so both builds come from the +# same, newest version. +# Usage: build/build-tally-hooks-in-php-image.sh +set -euo pipefail + +repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" +thread_safety="${1:?Usage: build/build-tally-hooks-in-php-image.sh }" +output="${2:?Usage: build/build-tally-hooks-in-php-image.sh }" +case "$thread_safety" in + nts) zts=0 ;; + zts) zts=1 ;; + *) + echo "Unknown thread safety $thread_safety, expected nts or zts." >&2 + exit 1 + ;; +esac + +apt-get update -qq +# shellcheck disable=SC2086 # PHPIZE_DEPS is a list of packages +apt-get install -y -qq --no-install-recommends $PHPIZE_DEPS >/dev/null + +if [ "$(php -r 'echo ZEND_THREAD_SAFE ? 1 : 0;')" != "$zts" ]; then + echo "The PHP $(php -r 'echo PHP_VERSION;') of the image is not $thread_safety, building it from its source." + configure_zts=--disable-zts + if [ "$zts" = 1 ]; then + configure_zts=--enable-zts + fi + docker-php-source extract + # an extension needs only the API version, the thread safety, and the debug flag to match + ( + cd /usr/src/php + ./configure --prefix=/opt/php --disable-all --disable-cgi --disable-phpdbg "$configure_zts" >/tmp/php-build.log 2>&1 \ + && make -j"$(nproc)" >>/tmp/php-build.log 2>&1 \ + && make install >>/tmp/php-build.log 2>&1 + ) || { + cat /tmp/php-build.log >&2 + exit 1 + } + export PATH="/opt/php/bin:$PATH" +fi + +"$repo_root/build/build-tally-hooks.sh" "$output" + +if ! php -n -d extension="$output" -r "exit(extension_loaded('tally_hooks') && (ZEND_THREAD_SAFE ? 1 : 0) === $zts ? 0 : 1);"; then + echo "$output does not load into the $thread_safety PHP it was built for." >&2 + exit 1 +fi +php -n -d extension="$output" -r 'echo "Checked that tally_hooks loads into PHP ", PHP_VERSION, ZEND_THREAD_SAFE ? " ZTS" : " NTS", " (", basename(PHP_EXTENSION_DIR), ")\n";'