internationalcolorconsortium/iccdev/vcpkg-export-consumer-debug

vcpkg Export Consumer Debug

Use this skill when a review or workflow log mentions ci-vcpkg-ports, ci-pr-action, examples/hello-iccdev, install manifests, uninstall, or packaged CMake consumers.

Port Pin Check

For source refreshes without an upstream version bump, update the port as version#port-version: increment ports/iccdev/vcpkg.json port-version, and refresh ports/iccdev/portfile.cmake REF plus SHA512 together. CI should use local source mode (VCPKG_ICCDEV_SOURCE and VCPKG_KEEP_ENV_VARS) so it tests the checked-out branch, not the GitHub archive fallback.

When refreshing the source pin, also test the non-local path on Windows with VCPKG_ICCDEV_SOURCE unset. Use a fresh --x-install-root and disable binary cache restoration for the iccdev package, or remove the prior iccdev install before repeating it; changing this environment variable alone does not replace an already installed package. Install iccdev[tools,xml,json] using the overlay and a full, bootstrapped vcpkg checkout, then build and run examples/hello-iccdev against the installed package. A local-source build does not verify the new archive hash or the pinned source's packaging. The overlay is static-only and deliberately disables ENABLE_CMM_TOOLS; its tools feature does not install the Windows ICM IccDEVCmm.dll.

For Windows source/consumer smoke tests, the immutable <https://github.com/InternationalColorConsortium/iccDEV/releases/tag/vcpkg-win-23241-libheif-deps> export supplies prebuilt dependencies. Verify its published SHA256 before extraction and disable manifest mode when using its toolchain. The export is not a full vcpkg registry; it does not replace the overlay install above.

Prebuilt Export Refresh

_build-test-windows.yml, ci-pr-win.yml, ci-matlab.yml, and the optional pinned-release-bundle path in ci-latest-release.yml pin the same export asset by URL and SHA256. Change all four together and update the assertions in .github/tests/test_wasm_workflow.py. The release workflow defaults to windows_vcpkg_source=manifest; selecting pinned-release-bundle verifies the archive checksum and configures with VCPKG_MANIFEST_MODE=OFF. The asset suffix is only a label and does not identify the vcpkg registry baseline, and the export does not set the manifest builtin-baseline; refresh that separately as described in Dependency Manifest Sync.

gh release view <tag> --repo InternationalColorConsortium/iccDEV `
  --json assets --jq '.assets[] | [.name, .digest, .size] | @tsv'
git grep -n -E 'vcpkg-win-[0-9]+-libheif-deps|iccdev-windows-vcpkg-classic' -- .github docs
python -m pytest --rootdir . --import-mode=importlib .github/tests/test_wasm_workflow.py -q

Dependency Manifest Sync

For direct build dependencies, compare and synchronize:

• vcpkg.json
• Build/Cmake/vcpkg.json
• ports/iccdev/vcpkg.json

Keep dependency-specific CMake options explicit in ports/iccdev/portfile.cmake. For zlib, all three manifests declare zlib, the portfile passes -DICC_USE_ZLIB=ON, and the overlay port-version is incremented. Do not add zlib directly to examples/hello-iccdev/vcpkg.json; that consumer receives it through the iccdev port.

For a registry baseline update, synchronize the root and Build/Cmake manifests, examples/hello-iccdev/vcpkg-configuration.json, the explicit checkouts in ci-vcpkg-ports.yml, and VCPKG_BASELINE in ci.yml. The overlay port manifest intentionally has no registry baseline.

Staleness Check

1. Compare the tested ref with the current PR head:

gh pr view <PR> --repo InternationalColorConsortium/iccDEV \
  --json headRefOid,headRefName,baseRefName,statusCheckRollup
git rev-parse HEAD

1. If the review SHA is not current, do not discard the finding. Re-check the

current head for the exact source pattern or failing workflow path.

1. Treat the review as still actionable when the same source pattern remains

present on the current head.

Common Windows Failures

Static vcpkg Consumer Uses the Wrong CRT

Signal:

MT_StaticRelease from Icc*2-static.lib conflicts with MD_DynamicRelease
LNK1169

Cause: the x64-windows-static packaged libraries were built with /MT, but the consumer executable used the default /MD runtime.

Fix: when configuring the packaged Windows static consumer, pass the matching runtime explicitly:

cmake -S "examples\hello-iccdev" -B $exampleBuild `
  -G "Visual Studio 17 2022" `
  -A x64 `
  -DCMAKE_BUILD_TYPE=Release `
  -DCMAKE_TOOLCHAIN_FILE="$env:VCPKG_ROOT\scripts\buildsystems\vcpkg.cmake" `
  -DVCPKG_MANIFEST_MODE=OFF `
  -DVCPKG_TARGET_TRIPLET=x64-windows-static `
  -DCMAKE_MSVC_RUNTIME_LIBRARY=MultiThreaded

Installed-Package Consumer Cannot Find Parent Dependencies

Signal:

Could NOT find ZLIB (missing: ZLIB_LIBRARY ZLIB_INCLUDE_DIR)

Cause: iccdev.installed-package-consumer disables manifest mode for its nested projects. If the driver does not also forward the parent build's VCPKG_INSTALLED_DIR, the vcpkg toolchain searches its global classic tree instead of the manifest tree already populated for the parent build.

Fix contract: pass the parent installed tree into the CTest driver and forward it to each nested configure together with CMAKE_TOOLCHAIN_FILE, VCPKG_MANIFEST_MODE=OFF, and VCPKG_TARGET_TRIPLET. Keep build-test-binaries dependent on every shared and static library artifact the test stages.

Focused Windows validation:

cmake --build out\vs2022-x64 --config Release --target build-test-binaries
ctest --test-dir out\vs2022-x64 -C Release `
  -R '^iccdev\.installed-package-consumer$' --output-on-failure --no-tests=error

Source Uninstall Breaks on CMake Path Spaces

Signal:

cmake --build ... --target uninstall --config Release
C:/Program Files/CMake/bin/cmake.exe is split at the space

Cause: generated uninstall scripts used unquoted @CMAKE_COMMAND@.

Fix:

execute_process(
    COMMAND "@CMAKE_COMMAND@" -E remove "$ENV{DESTDIR}${file}"
)

Validation

Run local checks on Windows before pushing:

git diff --check
python -c "import json; [json.load(open(p)) for p in ['vcpkg.json', 'Build/Cmake/vcpkg.json', 'ports/iccdev/vcpkg.json', 'examples/hello-iccdev/vcpkg.json']]; print('vcpkg JSON OK')"
python -c "import yaml; yaml.safe_load(open('.github/workflows/ci-vcpkg-ports.yml')); print('YAML parse OK')"
actionlint -no-color .github/workflows/ci-vcpkg-ports.yml
actionlint -no-color .github/workflows/vcpkg-packages.yml

Final proof for these failures requires a GitHub-hosted Windows runner. Monitor the source install/uninstall job and the packaged hello-iccdev consumer job after pushing.

References

• ../../workflows/ci-vcpkg-ports.yml
• ../../../Build/Cmake/RefIccMAXUninstall.cmake.in
• ../../../examples/hello-iccdev/CMakeLists.txt
• ../../../ports/iccdev/portfile.cmake