| name | port-upgrade |
| description | Upgrade cmake-toolset ports to newer upstream versions. Use when: checking releases, resolving dependency pins, validating patches, handling cross-compiling host tools, or reviewing CI impact. |
| argument-hint | ports=<names|all>; mode=analyze|update; validate=patch|build|ci|full |
Port Upgrade Workflow
Use this skill to upgrade one or more ports while
preserving dependency compatibility, patch behavior,
and repository-specific guards.
Workflow
Phase 0: Preflight Classification
- Classify the entry file as a standard port,
aggregator, orchestrator, complex port, or
cross-compiling host port.
- Read the truth sources:
- upstream repo at the target tag
ports/Configure.cmaketest/CMakeLists.txt.github/workflows/build.yaml and ci/do_ci.*
- Record compiler/version fallbacks, hosted tools,
RTTI/visibility logic, cross-compiling support, and
backend exclusions.
Phase 1: Version Survey
- Find all current version declarations and related
tag or compiler fallback logic.
- Fetch the latest stable upstream releases.
- Build a table of current vs target versions.
Phase 2: Dependency Analysis
- Query upstream build metadata such as
MODULE.bazel, WORKSPACE, bazel/*_deps.bzl,
CMakeLists.txt, and cmake/*.cmake.
- Use
test/CMakeLists.txt for repository include
order and local compatibility guards.
- When multiple ports pin the same dependency
differently, use the highest commonly supported
version or report the conflict.
- See dependency-chains.md.
Phase 3: Special-Case Analysis
- Any
import.cmake under ports/ is an aggregator.
Known aggregators: compression/, algorithm/,
grpc/, ngtcp2/, telemetry/, test/, web/.
- Treat aggregators and orchestrators as grouped logic,
not template-only edits.
- Preserve compiler fallbacks, backend exclusions,
RTTI/visibility logic, and hosted-tool behavior unless
validated.
- For
crosscompiling-host/, hosted tools, or
.cross.patch, follow
cross-compilation.md.
- Treat
ssl/port.cmake, grpc/import.cmake, and
protobuf/protobuf.cmake as custom logic.
Phase 4: Version Updates
- Update all relevant version, tag, and conditional
references.
- Check tag-format changes and multiple version sites.
Phase 5: Patch Validation
- Reuse same-minor patch files when they still apply
cleanly.
- Create a new patch only when the content differs.
- Validate
.cross.patch separately when relevant.
- Use
--depth 1 for patch testing and clean up
test/third_party/packages/ afterward.
- See patch-workflow.md.
Phase 6: Deprecated Build Options
Phase 7: Integration and CI Verification
- Confirm versions, tags, build options, and patch names.
- Review
test/CMakeLists.txt,
.github/workflows/build.yaml, and ci/do_ci.* for
impacted combinations.
- Summarize changes, validation, and remaining risks.
Important Rules
- Pre-commit formatting is mandatory. Before
committing, run
cmake-format -i on every modified
.cmake, .cmake.in, and CMakeLists.txt file
(excluding test/third_party/ and
test/build_jobs_*/). Alternatively run
bash ci/format.sh to format the entire tree.
CI will reject unformatted files.
- Never update a dependency without checking its
dependents. Always query upstream repos for actual
version pins rather than assuming from memory.
- Repository include order comes from
test/CMakeLists.txt.
- Patch files are matched by minor version prefix.
A patch for
v1.9.4 will match v1.9.5
automatically. Only create a new patch if the content
actually differs.
- Ports with
crosscompiling-host/ assets or hosted
tools require host-side validation.
- Preserve repository-specific guards. Existing
no-exception, no-rtti, compiler-version, and backend
exclusions are compatibility knowledge, not dead code.
- Cross-compilation patches (
.cross.patch) are
separate from regular patches and must be tested
independently.
Known Issues
- c-ares: Some versions have Windows build
failures. Check CI notes before updating.
