libpng 1.6.58.5 → 1.6.58.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e9edc7cf7190ff782780b914a63bc3a26cd3c1dd71199c26ec144e3e3f72619f
-  data.tar.gz: bed30533f0f5b33e4064213aa6bacecb8e815ca56234a8991ae8af70627cb40f
+  metadata.gz: fda67e6ac3b6280ed407565fc08a8166668093554afd534e33cf041d47900ecd
+  data.tar.gz: 060045bc45e2dc049d5957063a2dd045283b01f821666247b6a789638d35b277
 SHA512:
-  metadata.gz: e94cbd6af3fbc2accb177d8f3adc9565582d1853e9f998ff314934b6b5f2816f058164b40a32ee7661b55ea5c58e920c03d600d30e49e7f1d51d5f71e280f3f7
-  data.tar.gz: 88fca2579a17b68e184b381483687e43eef88d5a104ac74deb12056bd376e494db7e3b795312fad2042219979a0c9119b2daef8cd4dd2e47c6cf49925a2f5274
+  metadata.gz: 253211e3494d116f6cf13e78b5688cf171b0c4f85817b2f818fb3d69cffaa4e025687c7e086885b27ea57c2083555097a99732f188464f786676224987e4a08c
+  data.tar.gz: adc29322d89eb94d2f978f57e82be6f59d2a9691c233cefc09552d0c021e11f3f438fe1a8aebb6da2df56db5acbc9b7e8c0a1ff9697815489505f80b2ddc592b

data/.github/workflows/build.yml

@@ -143,12 +143,6 @@ jobs:
             platform: x86_64-linux-musl
           - os: ubuntu-24.04-arm
             platform: aarch64-linux-musl
-          # OHOS (OpenHarmony / Huawei HarmonyOS PC) is musl-based arm64.
-          # Built inside the same Alpine container as aarch64-linux-musl;
-          # the resulting binary is byte-compatible. Only the gem's
-          # platform label differs so RubyGems on OHOS selects it.
-          - os: ubuntu-24.04-arm
-            platform: aarch64-linux-ohos
 
     steps:
     - uses: actions/checkout@v4
@@ -174,27 +168,12 @@ jobs:
         git config --global --add safe.directory /work
         bundle install --jobs 4
         bundle exec rake "gem:native:${PLATFORM}"
-        case "${PLATFORM}" in
-          *-ohos)
-            # OHOS gem is labeled aarch64-linux-ohos so RubyGems on OHOS
-            # selects it, but Alpine Ruby reports *-linux-musl -- a
-            # platform mismatch. The .so inside is musl-compatible, so
-            # unpack the gem and load it via -Ilib directly to verify
-            # the binary works without going through RubyGems install.
-            mkdir -p /tmp/ohos-smoke
-            gem unpack pkg/libpng-*.gem --target /tmp/ohos-smoke
-            (cd /tmp/ohos-smoke/libpng-* && \
-              ruby -Ilib -e 'require "libpng"; png = Libpng.encode(2, 2, "\xff" * 16, pixel_format: "RGBA"); puts Libpng.decode(png, pixel_format: "RGBA").inspect')
-            ;;
-          *)
-            gem install -b pkg/libpng-*.gem
-            # Smoke test from /tmp so bundler's source-tree LOAD_PATH doesn't
-            # shadow the installed gem. Activate via `gem` so RubyGems resolves
-            # the platform-specific binary gem (Alpine Ruby's platform string
-            # is *-linux-musl, which must match the gem's platform suffix).
-            (cd /tmp && ruby -e 'gem "libpng"; require "libpng"; png = Libpng.encode(2, 2, "\xff" * 16, pixel_format: "RGBA"); File.binwrite("test.png", png); puts Libpng.decode(png, pixel_format: "RGBA").inspect')
-            ;;
-        esac
+        gem install -b pkg/libpng-*.gem
+        # Smoke test from /tmp so bundler's source-tree LOAD_PATH doesn't
+        # shadow the installed gem. Activate via `gem` so RubyGems resolves
+        # the platform-specific binary gem (Alpine Ruby's platform string
+        # is *-linux-musl, which must match the gem's platform suffix).
+        (cd /tmp && ruby -e 'gem "libpng"; require "libpng"; png = Libpng.encode(2, 2, "\xff" * 16, pixel_format: "RGBA"); File.binwrite("test.png", png); puts Libpng.decode(png, pixel_format: "RGBA").inspect')
         BUILD_EOF
         chmod +x /tmp/alpine-build.sh
         docker run --rm \
@@ -208,4 +187,90 @@ jobs:
     - uses: actions/upload-artifact@v4
       with:
         name: pkg-${{ matrix.platform }}
+        path: pkg/*.gem
+
+  # OHOS (OpenHarmony / Huawei HarmonyOS PC) requires the official OHOS
+  # NDK to cross-compile. The NDK's clang and binary-sign-tool are x86_64
+  # ELF binaries; on this arm64 runner they run transparently via
+  # binfmt_misc + qemu-user-static. Verification (dockerharmony) runs
+  # natively because the arm64 rootfs matches the host architecture.
+  build_ohos:
+    name: build aarch64-linux-ohos (NDK)
+    runs-on: ubuntu-24.04-arm
+    needs: prepare
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Install host-side tools
+      # These are used for: NDK setup (curl/jq/unzip), artifact prep
+      # (file), and dockerharmony verification (docker is preinstalled).
+      run: |
+        sudo apt-get update
+        sudo apt-get install -y curl jq unzip file
+
+    - name: Register binfmt for amd64 docker emulation
+      # The OHOS NDK is x86_64-only. We run the entire build inside an
+      # amd64 docker container on this arm64 host -- docker's binfmt_misc
+      # registration handles the emulation transparently inside the
+      # container, with no library juggling on the host side.
+      run: docker run --privileged --rm tonistiigi/binfmt --install amd64
+
+    - name: Cache OHOS NDK
+      id: cache-ndk
+      uses: actions/cache@v4
+      with:
+        path: ext/ohos/ndk
+        key: ohos-ndk-${{ hashFiles('ext/ohos/setup-ndk.sh') }}
+
+    - name: Setup OHOS NDK (host-side; only curl/jq/unzip needed)
+      if: steps.cache-ndk.outputs.cache-hit != 'true'
+      run: sh ext/ohos/setup-ndk.sh --prefix ext/ohos/ndk
+
+    - name: Build OHOS gem in amd64 container
+      # The entire build (libpng + static zlib + signing) runs inside an
+      # amd64 docker container so the NDK's x86_64 clang + binary-sign-tool
+      # run natively (no qemu at the process level; docker's binfmt handles
+      # the container emulation as a whole).
+      run: |
+        docker run --rm --platform linux/amd64 \
+          -v "$PWD:/work" -w /work \
+          -e target_platform=aarch64-linux-ohos \
+          ruby:3.3 \
+          sh -c '
+            set -e
+            apt-get update
+            apt-get install -y --no-install-recommends cmake ninja-build zlib1g-dev
+            bundle install --jobs 4
+            bundle exec rake gem:native:aarch64-linux-ohos
+            # Confirm the .so was produced and is arm64 ELF (sanity).
+            file lib/libpng/libpng16.so
+          '
+
+    - name: Prepare dockerharmony artifacts (host-side)
+      # verify-prepare.sh cross-compiles smoke-test.c using the NDK clang.
+      # We run it inside the same amd64 container for the same reason.
+      run: |
+        docker run --rm --platform linux/amd64 \
+          -v "$PWD:/work" -w /work \
+          -e NDK_ROOT=/work/ext/ohos/ndk \
+          ruby:3.3 \
+          sh -c '
+            set -e
+            apt-get update
+            apt-get install -y --no-install-recommends file
+            sh ext/ohos/verify-prepare.sh
+          '
+
+    - name: Verify in dockerharmony (real OHOS userland, arm64-native)
+      run: |
+        docker pull ghcr.io/hqzing/dockerharmony:latest
+        docker run --rm \
+          -v "$PWD/ohos-verify:/work" \
+          -w /work \
+          ghcr.io/hqzing/dockerharmony:latest \
+          sh -c 'LD_LIBRARY_PATH=. ./smoke-test'
+
+    - uses: actions/upload-artifact@v4
+      with:
+        name: pkg-aarch64-linux-ohos
         path: pkg/*.gem

data/.github/workflows/release.yml

@@ -201,10 +201,6 @@ jobs:
             platform: x86_64-linux-musl
           - os: ubuntu-24.04-arm
             platform: aarch64-linux-musl
-          # OHOS: same Alpine-built musl arm64 binary as aarch64-linux-musl,
-          # packaged under a distinct platform label.
-          - os: ubuntu-24.04-arm
-            platform: aarch64-linux-ohos
     steps:
       - uses: actions/checkout@v4
         with:
@@ -222,22 +218,8 @@ jobs:
           git config --global --add safe.directory /work
           bundle install --jobs 4
           bundle exec rake "gem:native:${PLATFORM}"
-          case "${PLATFORM}" in
-            *-ohos)
-              # OHOS gem is labeled aarch64-linux-ohos so RubyGems on OHOS
-              # selects it, but Alpine Ruby reports *-linux-musl. The .so
-              # inside is musl-compatible -- unpack and load via -Ilib to
-              # verify the binary without going through RubyGems install.
-              mkdir -p /tmp/ohos-smoke
-              gem unpack pkg/libpng-*.gem --target /tmp/ohos-smoke
-              (cd /tmp/ohos-smoke/libpng-* && \
-                ruby -Ilib -e 'require "libpng"; png = Libpng.encode(2, 2, "\xff" * 16, pixel_format: "RGBA"); puts Libpng.decode(png, pixel_format: "RGBA").inspect')
-              ;;
-            *)
-              gem install -b pkg/libpng-*.gem
-              (cd /tmp && ruby -e 'gem "libpng"; require "libpng"; png = Libpng.encode(2, 2, "\xff" * 16, pixel_format: "RGBA"); puts Libpng.decode(png, pixel_format: "RGBA").inspect')
-              ;;
-          esac
+          gem install -b pkg/libpng-*.gem
+          (cd /tmp && ruby -e 'gem "libpng"; require "libpng"; png = Libpng.encode(2, 2, "\xff" * 16, pixel_format: "RGBA"); puts Libpng.decode(png, pixel_format: "RGBA").inspect')
           BUILD_EOF
           chmod +x /tmp/alpine-build.sh
           docker run --rm \
@@ -253,8 +235,79 @@ jobs:
           name: pkg-${{ matrix.platform }}
           path: pkg/*.gem
 
+  # OHOS NDK cross-compile. See build.yml's build_ohos job for full notes.
+  build_ohos:
+    needs: bump
+    if: always() && !cancelled() && !failure() && (needs.bump.result == 'success' || needs.bump.result == 'skipped')
+    runs-on: ubuntu-24.04-arm
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ needs.bump.outputs.sha || github.ref }}
+
+      - name: Install host-side tools
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y curl jq unzip file
+
+      - name: Register binfmt for amd64 docker emulation
+        run: docker run --privileged --rm tonistiigi/binfmt --install amd64
+
+      - name: Cache OHOS NDK
+        id: cache-ndk
+        uses: actions/cache@v4
+        with:
+          path: ext/ohos/ndk
+          key: ohos-ndk-${{ hashFiles('ext/ohos/setup-ndk.sh') }}
+
+      - name: Setup OHOS NDK
+        if: steps.cache-ndk.outputs.cache-hit != 'true'
+        run: sh ext/ohos/setup-ndk.sh --prefix ext/ohos/ndk
+
+      - name: Build OHOS gem in amd64 container
+        run: |
+          docker run --rm --platform linux/amd64 \
+            -v "$PWD:/work" -w /work \
+            -e target_platform=aarch64-linux-ohos \
+            ruby:3.3 \
+            sh -c '
+              set -e
+              apt-get update
+              apt-get install -y --no-install-recommends cmake ninja-build zlib1g-dev
+              bundle install --jobs 4
+              bundle exec rake gem:native:aarch64-linux-ohos
+              file lib/libpng/libpng16.so
+            '
+
+      - name: Prepare dockerharmony artifacts
+        run: |
+          docker run --rm --platform linux/amd64 \
+            -v "$PWD:/work" -w /work \
+            -e NDK_ROOT=/work/ext/ohos/ndk \
+            ruby:3.3 \
+            sh -c '
+              set -e
+              apt-get update
+              apt-get install -y --no-install-recommends file
+              sh ext/ohos/verify-prepare.sh
+            '
+
+      - name: Verify in dockerharmony (real OHOS userland)
+        run: |
+          docker pull ghcr.io/hqzing/dockerharmony:latest
+          docker run --rm \
+            -v "$PWD/ohos-verify:/work" \
+            -w /work \
+            ghcr.io/hqzing/dockerharmony:latest \
+            sh -c 'LD_LIBRARY_PATH=. ./smoke-test'
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: pkg-aarch64-linux-ohos
+          path: pkg/*.gem
+
   publish:
-    needs: [ bump, build, build_musl ]
+    needs: [ bump, build, build_musl, build_ohos ]
     if: always() && !cancelled() && !failure()
     runs-on: ubuntu-latest
     steps:

data/CHANGELOG.md

@@ -7,6 +7,56 @@ This gem follows a `{LIBPNG_VERSION}.{LIBPNG_RUBY_ITERATION}` version
 scheme. `LIBPNG_VERSION` is the upstream libpng release; `ITERATION`
 bumps for Ruby-side changes and resets to 0 when LIBPNG_VERSION bumps.
 
+## [1.6.58.6] - 2026-07-26
+
+### Changed
+- **OHOS (`aarch64-linux-ohos`) is now cross-compiled with the official OHOS
+  NDK** (Huawei's `ohos.toolchain.cmake` + LLVM-19 clang), replacing the
+  1.6.58.4/.5 approach of shipping Alpine-built musl bytes labeled as OHOS.
+
+  The build runs on `ubuntu-24.04-arm`. The OHOS NDK clang is an x86_64
+  binary and runs transparently via `binfmt_misc` + `qemu-user-static`.
+  zlib is built statically with the same toolchain and linked into
+  `libpng16.so` (avoids the OHOS non-standard zlib SONAME
+  `libshared_libz.z.so`). The freshly built `.so` is code-signed with
+  `binary-sign-tool sign -selfSign 1` (mandatory for runtime loading on
+  production OHOS devices).
+
+  Verification: the signed `.so` is loaded by a smoke-test binary inside
+  real OHOS userland (the `dockerharmony` container running natively on
+  the same arm64 host -- no qemu). Build fails if the smoke test fails.
+
+### Added
+- `lib/libpng/ohos.rb`, `lib/libpng/ohos/{ndk,zlib_builder,code_signer,recipe}.rb`
+  -- OHOS cross-compile support. Lazy-loaded only when building for OHOS.
+  - `Libpng::OHOS::NDK` -- pure-data class for NDK path discovery.
+  - `Libpng::OHOS::ZlibBuilder < MiniPortileCMake` -- static zlib build.
+  - `Libpng::OHOS::CodeSigner` -- wraps `binary-sign-tool`.
+  - `Libpng::OHOS::Recipe < Libpng::Recipe` -- orchestrates the OHOS build.
+- `lib/libpng/recipe.rb`: `Recipe.for_target(platform)` factory -- OCP seam
+  that returns `OHOS::Recipe` for `*-ohos` targets, base `Recipe` otherwise.
+- `ext/ohos/setup-ndk.sh` -- downloads OHOS SDK + LLVM-19 via daily_build API
+  (adapted from ohos-node's `build.sh`).
+- `ext/ohos/smoke-test.c` -- minimal libpng round-trip test for dockerharmony.
+- `ext/ohos/verify-prepare.sh` -- cross-compiles smoke-test with NDK clang,
+  bundles signed `.so` + SONAME symlinks (fixes PR #12's symlink bug).
+- 49 new specs under `spec/ohos/` + `spec/recipe_factory_spec.rb`.
+
+### Caveats
+- The 1.6.58.4/.5 OHOS gems shipped Alpine-built bytes without NDK
+  verification. This version is the first with proper OHOS NDK
+  cross-compilation + signing.
+- Code signing uses `-selfSign 1` (self-signed). Sufficient for OHOS
+  userland load. Production deployment on Huawei-managed hardware may
+  require re-signing with an enrolled cert.
+
+### Superseded
+- PR #11 (closed) -- hand-written `toolchain.cmake` + system CMake. Replaced
+  by NDK's bundled `ohos.toolchain.cmake`.
+- PR #12 (closed) -- dockerharmony verification of Alpine bytes. The
+  verification step is reused here; the Alpine-built `.so` is replaced
+  with the NDK-built, signed one.
+
 ## [1.6.58.5] - 2026-07-26
 
 ### Added

data/CLAUDE.md

@@ -29,8 +29,16 @@ loaded via `autoload` from `lib/libpng.rb`. **Never use `require_relative`
 | `lib/libpng/standard_decoder.rb` | `Libpng::StandardDecoder` (libpng standard read API; explicit transform control) |
 | `lib/libpng/metadata_writer.rb` | `Libpng::MetadataWriter` (validates + writes text/gAMA/sRGB/cHRM/iCCP/pHYs onto a png_ptr/info_ptr pair) |
 | `lib/libpng/text_writer.rb` | `Libpng::TextWriter` + `Libpng::TextEntry` (builds png_text struct array, calls `png_set_text`) |
-| `lib/libpng/recipe.rb` | `Libpng::Recipe < MiniPortileCMake` (builds libpng from source for the source gem) |
-| `ext/extconf.rb` | Gem extension entry. Triggers `Libpng::Recipe` autoload via `require 'libpng'`, then emits a dummy Makefile |
+| `lib/libpng/recipe.rb` | `Libpng::Recipe < MiniPortileCMake` (builds libpng from source for the source gem). Has `.for_target(platform)` factory -- OCP seam that returns `OHOS::Recipe` for `*-ohos`, base `Recipe` otherwise |
+| `lib/libpng/ohos.rb` | `Libpng::OHOS` namespace + autoloads. Lazy-loaded only when `Recipe.for_target` is called with an OHOS target |
+| `lib/libpng/ohos/ndk.rb` | `OHOS::NDK` -- pure-data class for NDK path discovery (toolchain/sysroot/clang/sign-tool). Idempotent `#download` via `setup-ndk.sh` |
+| `lib/libpng/ohos/zlib_builder.rb` | `OHOS::ZlibBuilder < MiniPortileCMake` -- builds `libz.a` statically with the OHOS toolchain |
+| `lib/libpng/ohos/code_signer.rb` | `OHOS::CodeSigner` -- wraps `binary-sign-tool sign -selfSign 1`. Pure-data `#sign_command` is testable without invoking the tool |
+| `lib/libpng/ohos/recipe.rb` | `OHOS::Recipe < Libpng::Recipe` -- orchestrates NDK setup, zlib build, libpng cross-compile with `ohos.toolchain.cmake`, and post-install signing |
+| `ext/extconf.rb` | Gem extension entry. Calls `Libpng::Recipe.for_target(ENV['target_platform']).new`, then emits a dummy Makefile |
+| `ext/ohos/setup-ndk.sh` | Downloads OHOS SDK + LLVM-19 via OpenHarmony daily_build API (adapted from ohos-node/build.sh). Idempotent |
+| `ext/ohos/smoke-test.c` | Minimal libpng round-trip test, cross-compiled with NDK clang and run inside dockerharmony |
+| `ext/ohos/verify-prepare.sh` | Cross-compiles smoke-test, bundles signed `.so` + SONAME symlinks for dockerharmony |
 
 ### Public API
 
@@ -74,6 +82,25 @@ bundle exec rake gem:native:any             # source gem (compiles on install)
 
 Platform gem tasks: `x64-mingw32`, `x64-mingw-ucrt`, `aarch64-mingw-ucrt`, `x86_64-linux`, `x86_64-linux-musl`, `aarch64-linux`, `aarch64-linux-musl`, `aarch64-linux-ohos`, `x86_64-darwin`, `arm64-darwin`.
 
+### OHOS (`aarch64-linux-ohos`) build notes
+
+OHOS uses a dedicated `build_ohos` CI job (see `.github/workflows/build.yml`)
+that runs on `ubuntu-24.04-arm`. The NDK's clang and `binary-sign-tool` are
+x86_64 ELF and run via `binfmt_misc` + `qemu-user-static`. The job:
+
+1. Downloads OHOS SDK + LLVM-19 via `ext/ohos/setup-ndk.sh` (~1.5 GB, cached
+   across runs by `actions/cache@v4`).
+2. Runs `rake gem:native:aarch64-linux-ohos`, which delegates to
+   `Libpng::OHOS::Recipe` (sets up NDK, builds static zlib, cross-compiles
+   libpng with `ohos.toolchain.cmake`, signs the `.so`).
+3. Cross-compiles `ext/ohos/smoke-test.c` with NDK clang via
+   `verify-prepare.sh`, then runs it inside the `dockerharmony` container
+   (real OHOS userland) — build fails if smoke-test doesn't output `OK`.
+
+Local dev: `target_platform=aarch64-linux-ohos bundle exec rake compile`
+will only succeed on an arm64 host with `qemu-user-static` registered,
+because the NDK clang is x86_64 ELF. CI handles this automatically.
+
 ## Release process
 
 Releases are tag-triggered via `.github/workflows/release.yml`. Trigger with:

data/README.adoc

@@ -44,7 +44,7 @@ for the current set):
 | `x86_64-linux-musl` | x86_64 Linux (musl, e.g. Alpine) | `ruby:<ver>-alpine` on x86_64
 | `aarch64-linux` | ARM64 Linux (glibc) | `ubuntu-24.04-arm` (native)
 | `aarch64-linux-musl` | ARM64 Linux (musl) | `ruby:<ver>-alpine` on arm64
-| `aarch64-linux-ohos` | ARM64 OpenHarmony / Huawei HarmonyOS PC | `ruby:<ver>-alpine` on arm64 (byte-compatible with `aarch64-linux-musl`)
+| `aarch64-linux-ohos` | ARM64 OpenHarmony / Huawei HarmonyOS PC | `ubuntu-24.04-arm` + OHOS NDK (cross-compiled, signed, **verified in dockerharmony**)
 | `x64-mingw32` | x64 Windows, RubyInstaller < 3.0 (MSVCRT) | `windows-latest`
 | `x64-mingw-ucrt` | x64 Windows, RubyInstaller >= 3.0 (UCRT) | `windows-latest`
 | `aarch64-mingw-ucrt` | ARM64 Windows (Ruby >= 3.4) | `windows-11-arm` (native)

data/TODO.ohos/01-architecture.md

@@ -0,0 +1,105 @@
+# 01 - Architecture
+
+## Goal
+
+Cross-compile `libpng16.so` for `aarch64-linux-ohos` using the official OHOS
+NDK (Huawei-blessed toolchain), code-sign it, and empirically verify it in
+real OHOS userland (dockerharmony). Replace the 1.6.58.4/.5/.6 approach of
+"Alpine-built bytes labeled as OHOS".
+
+## Why this design (vs PR #11 / PR #12)
+
+| Approach | Status | Why rejected |
+|---|---|---|
+| Alpine bytes labeled OHOS (1.6.58.4/.5) | shipped | unverified assumption; user flagged musl symbol visibility, TLS, pthread layout risks |
+| PR #11: hand-written `toolchain.cmake` + system CMake | closed | 5 CI iterations failed (sysroot path, missing zlib in sysroot, try_compile couldn't find crt objects) — root cause: NOT using NDK's bundled `ohos.toolchain.cmake` |
+| PR #12: Alpine bytes + dockerharmony verification | closed | still ships Alpine bytes labeled OHOS; user wants proper NDK bytes |
+| **PR #13 (this plan)** | current | NDK-bundled `ohos.toolchain.cmake` + static zlib + `binary-sign-tool` + dockerharmony verify |
+
+## Key insights from references
+
+- **OHOS CMake doc** (`openharmony-6.0-app-dev-docs/napi/build-with-ndk-cmake.md`):
+  - NDK ships own CMake at `${SDK_PATH}/native/build-tools/cmake/bin/cmake`
+  - Toolchain file at `${SDK_PATH}/native/build/cmake/ohos.toolchain.cmake`
+  - Invoke: `cmake -DOHOS_ARCH=arm64-v8a -DOHOS_PLATFORM=OHOS -DCMAKE_TOOLCHAIN_FILE=...`
+  - Toolchain handles sysroot + `--target=arm-linux-ohos` + try_compile compatibility
+
+- **ohos-node** (`~/src/external/ohos-node/build.sh`):
+  - NDK download via `https://dcp.openharmony.cn/api/daily_build/build/list/component`
+  - Two components needed: `ohos-sdk-public` (SDK + `binary-sign-tool`) + `LLVM-19` (clang + sysroot)
+  - `binary-sign-tool sign -selfSign 1` is mandatory post-build
+  - Output runs on OHOS via dockerharmony (real OHOS rootfs)
+
+- **dockerharmony** (`~/src/external/dockerharmony/`):
+  - OHOS rootfs (musl + toybox + mksh) in Docker, runs aarch64-linux-musl binaries natively on arm64 hosts
+  - OHOS ships zlib as `libshared_libz.z.so` (NOT `libz.so`) — patchelf needed if linking dynamically
+
+- **NDK architecture reality** (verified):
+  - `LLVM-19` tarball contains `llvm-linux-x86_64.tar.gz` (x86_64-build clang) + `ohos-sysroot.tar.gz` (architecture-independent sysroot files)
+  - There is **no arm64 build of the NDK clang** in the daily_build output
+  - `ohos.toolchain.cmake` is a CMake script (architecture-independent)
+  - `binary-sign-tool` is in the x86_64-build ohos-sdk
+
+## CI topology (corrected: native arm64 + transparent qemu for NDK binaries)
+
+Single job on `ubuntu-24.04-arm` (native arm64 runner):
+
+1. Install `qemu-user-static` + `binfmt-support` — registers binfmt_misc so
+   x86_64 ELF binaries run transparently via `qemu-x86_64`.
+2. Run `ext/ohos/setup-ndk.sh` → NDK + LLVM-19 in `ext/ohos/ndk/`
+3. `bundle exec rake gem:native:aarch64-linux-ohos` →
+   - `OHOS::Recipe#cook` runs:
+     - Downloads libpng source (MiniPortile)
+     - Builds static zlib via `OHOS::ZlibBuilder` (NDK clang under binfmt)
+     - CMake-configures libpng with `ohos.toolchain.cmake` + static zlib (NDK cmake/clang under binfmt)
+     - Builds + installs `libpng16.so`
+     - Signs `.so` via `OHOS::CodeSigner` (`binary-sign-tool` under binfmt)
+4. Run `ext/ohos/verify-prepare.sh` → `ohos-verify/` artifacts (cross-compile smoke-test with NDK clang)
+5. Run dockerharmony natively: `docker run --rm -v ...:/work ghcr.io/hqzing/dockerharmony:latest sh -c 'LD_LIBRARY_PATH=. ./smoke-test'`
+
+### Why this is the right topology
+
+| Aspect | x86_64 runner (original plan) | arm64 runner + qemu (revised) |
+|---|---|---|
+| NDK clang / binary-sign-tool | native speed | ~5x slower (qemu emulation) |
+| dockerharmony verification | ~5x slower (qemu binfmt for arm64) | **native speed** |
+| CI complexity | needs binfmt setup, multi-arch docker pull | standard docker pull |
+| Total CI time | dominated by slow dockerharmony emulation | dominated by slow NDK compile (smaller) |
+
+Compilation is ~1 min native → ~5 min under qemu (acceptable).
+dockerharmony smoke-test is ~50ms native → ~250ms under qemu — small absolute number,
+but the binfmt setup for arm64 emulation on x86_64 is finicky and has been flaky
+in CI historically. Native arm64 docker is rock-solid.
+
+**Net**: arm64 + qemu is simpler AND faster overall.
+
+## MECE file layout
+
+```
+ext/ohos/
+├── setup-ndk.sh           # Downloads SDK + LLVM-19 (idempotent, shell)
+├── smoke-test.c           # Round-trip test (kept from PR #12)
+├── verify-prepare.sh      # Cross-compiles smoke-test, bundles for dockerharmony
+└── (no toolchain.cmake — we use NDK's bundled ohos.toolchain.cmake)
+
+lib/libpng/
+├── recipe.rb              # Add Recipe.for_target factory (OCP seam)
+├── ohos.rb                # Module Libpng::OHOS + autoloads
+└── ohos/
+    ├── ndk.rb             # OHOS::NDK: pure-data path discovery + download
+    ├── zlib_builder.rb    # OHOS::ZlibBuilder < MiniPortileCMake (static zlib)
+    ├── code_signer.rb     # OHOS::CodeSigner: wraps binary-sign-tool
+    └── recipe.rb          # OHOS::Recipe < Libpng::Recipe
+
+lib/libpng.rb              # Add autoload :OHOS, 'libpng/ohos'
+ext/extconf.rb             # Use Recipe.for_target(...) factory
+```
+
+## OCP compliance
+
+Adding a new cross-compile platform = adding `lib/libpng/<platform>/` with a
+`<Platform>::Recipe < Libpng::Recipe` subclass and registering it in
+`Recipe.for_target`. No modification of `Libpng::Recipe` needed.
+
+The existing `Libpng::Recipe` is unchanged (except adding the factory class
+method). All OHOS logic is in `lib/libpng/ohos/`.

data/TODO.ohos/02-close-pr-12-and-branch.md

@@ -0,0 +1,30 @@
+# 02 - Close PR #12, branch off main
+
+## Steps
+
+1. Close PR #12 with a comment explaining the pivot:
+
+   > Closing in favor of a proper OHOS NDK cross-compile approach (PR #13).
+   > The dockerharmony verification step is reused; the build approach changes
+   > from "Alpine-built bytes labeled OHOS" to "NDK-built bytes signed with
+   > binary-sign-tool". The smoke-test.c file is carried over.
+
+2. From `main`, create `fix/ohos-ndk-cmake`:
+   ```sh
+   git checkout main
+   git pull origin main
+   git checkout -b fix/ohos-ndk-cmake
+   ```
+
+3. Cherry-pick reusable files from `fix/ohos-dockerharmony`:
+   - `ext/ohos/smoke-test.c` — keep as-is
+   - `lib/libpng/version.rb` — keep iteration = 6 (it's already at 6 on PR #12 branch)
+
+   `verify-prepare.sh` will be rewritten (was Alpine-gcc-based; new version
+   uses NDK clang for cross-compile from x86_64 host).
+
+## Why branch off main (not off fix/ohos-dockerharmony)
+
+PR #12's CI changes (build.yml, release.yml) are incompatible with the NDK
+approach — they assume Alpine container build. Cleaner to start fresh and
+re-introduce only what's needed.

data/TODO.ohos/03-setup-ndk-sh.md

@@ -0,0 +1,54 @@
+# 03 - ext/ohos/setup-ndk.sh
+
+## Purpose
+
+Download and extract the OHOS NDK (SDK + LLVM-19) into `ext/ohos/ndk/`.
+Idempotent — skips if the destination already looks complete.
+
+## Source pattern
+
+Adapted from `~/src/external/ohos-node/build.sh` (lines 14-49). Key pieces:
+
+```sh
+query_component() {
+  component=$1
+  curl -fsSL 'https://dcp.openharmony.cn/api/daily_build/build/list/component' \
+    -H 'Accept: application/json, text/plain, */*' \
+    -H 'Content-Type: application/json' \
+    --data-raw '{"projectName":"openharmony","branch":"master","pageNum":1,"pageSize":10,"deviceLevel":"","component":"'${component}'","type":1,"startTime":"2025080100000000","endTime":"20990101235959","sortType":"","sortField":"","hardwareBoard":"","buildStatus":"success","buildFailReason":"","withDomain":1}'
+}
+```
+
+Two components needed:
+- `ohos-sdk-public` → contains `toolchains/lib/binary-sign-tool` + `build/cmake/ohos.toolchain.cmake`
+- `LLVM-19` → contains `llvm/bin/aarch64-unknown-linux-ohos-clang` + `ohos-sysroot.tar.gz`
+
+## Script contract
+
+```
+Usage: setup-ndk.sh [--prefix <dir>]
+Default prefix: $PWD/ext/ohos/ndk
+
+Outputs:
+  $PREFIX/ohos-sdk/linux/        # SDK
+  $PREFIX/llvm-19/llvm/          # Clang
+  $PREFIX/llvm-19/sysroot/       # OHOS sysroot (extracted from ohos-sysroot.tar.gz)
+
+Exits 0 if setup is complete (or was already complete).
+```
+
+## Idempotency
+
+Skip download if `$PREFIX/ohos-sdk/linux/toolchains/lib/binary-sign-tool` exists
+AND `$PREFIX/llvm-19/sysroot/usr/lib/aarch64-linux-ohos/` exists. This lets
+CI cache the directory across runs.
+
+## Dependencies (CI-side)
+
+- `curl`, `tar`, `unzip`, `jq` — apt-installed in workflow before script runs.
+
+## Why shell (not Ruby)
+
+- curl + jq + tar pipeline is 5 lines of shell vs 50+ lines of Ruby (Net::HTTP + JSON parsing).
+- Pattern is proven by ohos-node; we follow it verbatim.
+- Ruby's role is orchestration (deciding *when* to invoke); the script does the heavy lifting.

data/TODO.ohos/04-ohos-module-and-ndk.md

@@ -0,0 +1,65 @@
+# 04 - lib/libpng/ohos.rb + lib/libpng/ohos/ndk.rb
+
+## lib/libpng.rb modification
+
+Add one autoload entry (follows existing convention):
+
+```ruby
+# OHOS cross-compile support. Only loaded when building for aarch64-linux-ohos.
+autoload :OHOS, 'libpng/ohos'
+```
+
+## lib/libpng/ohos.rb
+
+Module namespace + sub-autoloads. Loaded lazily only when OHOS is referenced
+(i.e., when `Recipe.for_target('aarch64-linux-ohos')` is called).
+
+```ruby
+# frozen_string_literal: true
+
+module Libpng
+  module OHOS
+    autoload :NDK, 'libpng/ohos/ndk'
+    autoload :Recipe, 'libpng/ohos/recipe'
+    autoload :ZlibBuilder, 'libpng/ohos/zlib_builder'
+    autoload :CodeSigner, 'libpng/ohos/code_signer'
+
+    TARGET_TRIPLE = 'aarch64-linux-ohos'
+    OHOS_ARCH = 'arm64-v8a'
+  end
+end
+```
+
+## lib/libpng/ohos/ndk.rb
+
+Pure-data class — discovers and validates NDK paths. No shell calls except
+via explicit `#download` (which invokes `setup-ndk.sh`).
+
+### Public API
+
+```ruby
+class NDK
+  def initialize(root:)                 # root = Pathname to NDK install dir
+  def exist?                            # true if all expected paths present
+  def toolchain_path                    # Pathname to ohos.toolchain.cmake
+  def clang_path                        # Pathname to aarch64-unknown-linux-ohos-clang
+  def sysroot_path                      # Pathname to OHOS sysroot root
+  def sign_tool_path                    # Pathname to binary-sign-tool
+  def cmake_path                        # Pathname to NDK's bundled cmake binary
+  def download                          # invoke setup-ndk.sh (no-op if exist?)
+end
+```
+
+### Design notes
+
+- All path accessors return `Pathname` (not String) for composability.
+- `#exist?` checks the four critical paths (toolchain, clang, sysroot, sign-tool).
+- `#download` invokes `ext/ohos/setup-ndk.sh` via `system()`. Idempotent.
+- No `instance_variable_get`/`set` — ivars are private, accessed via methods.
+- No `respond_to?` — type checks use `is_a?`.
+
+### Testability
+
+Spec constructs a fake NDK directory structure (just empty files at expected
+paths) and verifies accessors return correct Pathnames. No doubles, no real
+download.