Skip to content

[vcpkg.cmake] Add VCPKG_PREFER_HOST_TOOLS, on by default - #54781

Merged
Billy O'Neal (BillyONeal) merged 1 commit into
microsoft:masterfrom
rkitover:toolchain-prefer-host-tools
Nov 4, 2026
Merged

Billy O'Neal (BillyONeal) merged 1 commit into
microsoft:masterfrom
rkitover:toolchain-prefer-host-tools

Conversation

@rkitover

Copy link
Copy Markdown
Contributor

VCPKG_USE_HOST_TOOLS puts only the host triplet's tools in CMAKE_PROGRAM_PATH. That breaks build tools that come with a target port and are not available as host tools, such as wxrc from wxwidgets.

Add VCPKG_PREFER_HOST_TOOLS, which searches the host triplet's tools first and then the target triplet's. It is on by default when VCPKG_HOST_TRIPLET is set, in place of VCPKG_USE_HOST_TOOLS, which is now off by default and still takes precedence when set. Unless it is already set, CMAKE_FIND_ROOT_PATH_MODE_PROGRAM becomes NEVER for cross builds, so find_program() does not find a target tool first because it is under the find root.

Tools found for the target triplet, such as wxrc, may not run on the build machine when cross compiling.

Assisted-By: Claude Opus 5.5 noreply@anthropic.com

VCPKG_USE_HOST_TOOLS puts only the host triplet's tools in
CMAKE_PROGRAM_PATH. That breaks build tools that come with a target port
and are not available as host tools, such as wxrc from wxwidgets.

Add VCPKG_PREFER_HOST_TOOLS, which searches the host triplet's tools
first and then the target triplet's. It is on by default when
VCPKG_HOST_TRIPLET is set, in place of VCPKG_USE_HOST_TOOLS, which is now
off by default and still takes precedence when set. Unless it is already
set, CMAKE_FIND_ROOT_PATH_MODE_PROGRAM becomes NEVER for cross builds, so
find_program() does not find a target tool first because it is under
the find root.

Tools found for the target triplet, such as wxrc, may not run on the
build machine when cross compiling.

Assisted-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Rafael Kitover <rkitover@gmail.com>
Copilot AI balanced review requested due to automatic review settings October 30, 2026 21:27
@rkitover

Copy link
Copy Markdown
Contributor Author

If this is merged, I have a doc update as well:

MicrosoftDocs/vcpkg-docs@2925dea

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 Needs a closer look

Changes to default tool discovery and global find_program root handling require cross-platform CMake validation of host/target precedence and chainloaded-toolchain interactions unavailable in this review environment.

No open issues 🎉

What changed in this PR

Updates vcpkg’s CMake integration to prefer host tools while allowing fallback to target-triplet tools, such as wxwidgets’ wxrc.

Changes:

  • Adds VCPKG_PREFER_HOST_TOOLS, enabled by default when a host triplet is available.
  • Makes VCPKG_USE_HOST_TOOLS opt-in while preserving its precedence and host-only behavior.
  • Defaults program root-path searching to NEVER when preferring tools across different triplets, unless explicitly configured.
File Description
scripts/​buildsystems/​vcpkg.cmake Adds host-first tool discovery with target fallback and adjusts program search defaults.

Review effort: Balanced

@vicroms Victor Romero (vicroms) added the requires:vcpkg-team-review This PR or issue requires someone on the vcpkg team to take a further look. label Nov 2, 2026
@BillyONeal Billy O'Neal (BillyONeal) removed the requires:vcpkg-team-review This PR or issue requires someone on the vcpkg team to take a further look. label Nov 4, 2026

@BillyONeal Billy O'Neal (BillyONeal) left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you! Can you submit that to the docs repo?

@BillyONeal
Billy O'Neal (BillyONeal) merged commit a2f369a into microsoft:master Nov 4, 2026
16 checks passed
@dg0yt

Copy link
Copy Markdown
Contributor

Do we really want to make searching both paths the default when vcpkg didn't do it in the past?

Needing target triplet tools in cross builds might be an indication of a port bug in most cases. It can be opt-in for cases where it is really needed. (I'm skeptical about it being needed for wxrc, but I know the limitations of gobject-introspection.)

Also, searching the host path first (which is right), which is the scenario where there is no host wxrc being found before the target wxrc?

@rkitover

Copy link
Copy Markdown
Contributor Author

I would assume we want to use host tools for all builds, not just cross builds.

This is currently not happening automatically without VCPKG_HOST_TRIPLET being set, which I have started to work on fixing here:

microsoft/vcpkg-tool#2126

, which I pinged you guys on.

Ideally we want host tools to be available for all build tools. But sometimes that is not the case, for example for wxwidgets wxrc, which is essential for compiling wxWidgets GUI XML definitions, for example for dialogs.

In the case of wxrc I will also work on fixing this and try to add a wxwidgets-wxrc host port.

So in this particular case, as things stand now, defining VCPKG_HOST_TRIPLET, which may be needed for tools like pkgconf is not enough to also have the target triplet tools like wxrc, which would not be found by the toolchain without adding the target triplet tools to the search path manually.

I'm guessing there are other build tools in this situation and there will be because ports are often imperfect.

So the overall intent here, once these parts are done, is that in a normal non-cross-build host tools like pkgconf are found automatically as well as target tools which do not yet have host tools like wxrc, as opposed to your build breaking, with little cost.

@dg0yt

Kai Pastor (dg0yt) commented Nov 4, 2026 •

Copy link
Copy Markdown
Contributor

which I pinged you guys on.

I'm notified anyways, but I'm only a community member, and I am not willing to be the first human to review AI assisted PRs. Microsoft must have a look.

Back to this PR. Correct me if I am wrong:

  • This PR did not trigger a full CI rebuild.
  • This PR changes nothing for port builds now because we still do not (in general) pass the host triplet to ports builds (because we do not have the integration with vcpkg tool yet).
  • This PR changes the program search path for top-level CMake projects and for ports which do set the host triplet (and thus only used host path before the change).
    IMO this behavior must be opt-in - there is no need to generally add the target tool path. It fact it might find incompatible tools from vcpkg when the user expects to use compatible tools from the system.

@BillyONeal

Copy link
Copy Markdown
Member

Kai Pastor (@dg0yt)

Do we really want to make searching both paths the default when vcpkg didn't do it in the past?
Needing target triplet tools in cross builds might be an indication of a port bug in most cases. It can be opt-in for cases where it is really needed.

It would be better to search only the host one, but I assumed that would be too backcompat breaking.

This PR did not trigger a full CI rebuild.

I was under the impression that it did but I didn't verify. :/

Rafael Kitover (@rkitover)

I would assume we want to use host tools for all builds, not just cross builds.
This is currently not happening automatically without VCPKG_HOST_TRIPLET being set, which I have started to work on fixing here:
microsoft/vcpkg-tool#2126

I'm not sure I understand; in a non-cross build, host and target tools are the same.

@rkitover

Rafael Kitover (rkitover) commented Nov 4, 2026 •

Copy link
Copy Markdown
Contributor Author
  • This PR did not trigger a full CI rebuild.

Correct, scripts/buildsystems/vcpkg.cmake isn't part of the package ABI, so nothing is rebuilt.

  • This PR changes nothing for port builds now because we still do not (in general) pass the host triplet to ports builds (because we do not have the integration with vcpkg tool yet).

Correct, vcpkg_cmake_configure doesn't pass VCPKG_HOST_TRIPLET, a few ports pass it themselves (gdal, vtk, hpx, ...), and only when cross compiling, to find host tools. For those ports, there is no behavior change because the host tools precede the target tools in CMAKE_PROGRAM_PATH.

  • This PR changes the program search path for top-level CMake projects and for ports which do set the host triplet (and thus only used host path before the change).

Right.

IMO this behavior must be opt-in - there is no need to generally add the target tool path. It fact it might find incompatible tools from vcpkg when the user expects to use compatible tools from the system.

The target tools are already in CMAKE_PROGRAM_PATH by default when VCPKG_HOST_TRIPLET is not set, because VCPKG_SETUP_CMAKE_PROGRAM_PATH defaults to ON. Without VCPKG_HOST_TRIPLET, the cmake_dependent_option forces VCPKG_USE_HOST_TOOLS to OFF, so the toolchain adds installed/<target triplet>/tools and its subdirectories to CMAKE_PROGRAM_PATH.

Even if that were the case, I would expect the user's preference to be for vcpkg tools for their ports rather than something from PATH.

@rkitover

Copy link
Copy Markdown
Contributor Author

It would be better to search only the host one, but I assumed that would be too backcompat breaking.

It would in-fact be more correct.

The issue is the situations where there is no host tool but there is a target tool, such as wxrc.

The change being default handles this situation at a slight cost of correctness with zero configuration, once all of the pieces are in place.

I'm not sure I understand; in a non-cross build, host and target tools are the same.

Suppose you are building for x64-windows-static. In that case, some tools are host-only such as pkgconf and would be installed in x64-windows, which is the host triplet in that case. There is no target tool because pkgconf is not installed for x64-windows-static.

@BillyONeal

Copy link
Copy Markdown
Member

The issue is the situations where there is no host tool but there is a target tool, such as wxrc.

If it's not a backcompat issue I'm happy to tell people who have created those situations that they need to fix it in their portfile.cmake rather than globally.

@rkitover

Copy link
Copy Markdown
Contributor Author

If it's not a backcompat issue I'm happy to tell people who have created those situations that they need to fix it in their portfile.cmake rather than globally.

It is also a backcompat issue, because once VCPKG_HOST_TRIPLET will be automatically defined by the toolchain, the target tools will no longer be in CMAKE_PROGRAM_PATH as they are now in the most common case when VCPKG_HOST_TRIPLET is not set.

@rkitover

Copy link
Copy Markdown
Contributor Author

The doc PR is here:

MicrosoftDocs/vcpkg-docs#623

@rkitover
Rafael Kitover (rkitover) deleted the toolchain-prefer-host-tools branch November 5, 2026 05:17
@dg0yt

Copy link
Copy Markdown
Contributor

FTR I'm not opposed to eventually moving to correct use of the host tools path (even if it is disruptive).

I'm opposed to a partial behavioral change now and another partial behavioral change when proper host triplet passing landed.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants