Windows: local-build script update

[thomthehound]

As this PR is a follow-up to #9541 (and additionally related to #9618), I would appreciate review by @stsoe.

Problem solved by the commit

The existing build scripts for Windows are CI-focused and not friendly for external users who may want/need to install XRT on their local machine. Additionally, the existing dependency installation scripts are outdated and do not function as expected for end-users. As more Ryzen AI NPU projects come online, these barriers to entry become more pronounced.

This patch aims to fill that gap by providing Windows desktop users a more turn-key path that "just works", while also being CI-compatible and without disrupting existing workflows.

Usage instructions (from repo root):

# Install deps into <repo>\build\ext.vcpkg
src\runtime_src\tools\scripts\xrtdeps-vcpkg.bat

# Install XRT into C:\Xilinx\XRT and stage minimal runtime DLLs
build\build26.bat -opt -npu -install -stage

How problem was solved

This patch adds two new scripts (both support -help) and patches two CMakeLists.txt files:

src/runtime_src/tools/scripts/xrtdeps-vcpkg.bat

• This script acts as a wrapper for vcpkg, removing ambiguity for end-users who may not have intimate knowledge of vcpkg. It will not run unless called directly.
• Uses manifest-mode vcpkg (without need for a standalone clone) to install dependencies into <repo>\build\ext.vcpkg (or other directory specified by -extroot).
• Default ports are pulled directly from src/vcpkg.json, but may be optionally extended with the -port flag to include, e.g., protobuf so that xbtracer can be built.
• Pins the vcpkg registry to a specific commit hash (user-alterable with the -baseline flag) to avoid breakages from upstream changes. This was chosen to ease long-term maintenance.
• Installs pybind11 via pip for pyxrt.

build/build26.bat:

• Prefers VS 18 2026, falls back to VS 17 2022 if needed, thereby justifying the script name reservation while remaining testable on currently available Windows runners.
• Externally behaves as a superset of build/build22.bat. Accepts the same arguments, plus:
  -ext <path>: dependency prefix root (e.g. a vcpkg_installed<triplet> directory generated from src/runtime_src/tools/scripts/xrtdeps-vcpkg.bat)
  -install [<prefix>] : install to a specified location (default C:\Xilinx\XRT; if omitted, installs to the build tree, identically to build22.bat)
  -stage: copy the minimal subset of necessary runtime DLL's into <install_prefix>\ext\bin (currently Boost filesystem/program_options and optional protobuf DLLs)
  -rwd: build RelWithDebInfo configuration.
  -arm64: build for ARM64 architecture (requires first setting -triplet arm64-windows for vcpkg dependencies in xrtdeps-vcpkg.bat)

Minimally modifies src/runtime_src/tools/xclbinutil/CMakeLists.txt to no longer force gtest to be installed in a hardcoded directory.

Minimally modifies src/python/pybind11/CMakeLists.txt to enable debug/relwithdebinfo builds to find and link the correct Python libraries on Windows.

Alternatives considered / rejected

• Fix old (or add new) src/runtime_src/tools/scripts/xrtdeps-win*.py
  • Rejected by codeowner request.
• Overwrite build/build.bat
  • Would have been preferred due to the existing script's age, but may have had unforeseen consequences for existing workflows.
• Not reserving the build26.bat filename
  • This PR is intentionally forward-looking and compatibility-minded. If it does not deserve such a name, it does not deserve presence in the repo.

Risks (if any) associated with the changes in the commit

Very low:

• New behavior is additive (build26.bat / xrtdeps-vcpkg.bat); changes to existing scripts only fix (Windows-gated) bugs and do not add/remove features.
• The external behavior of build26.bat differs from build22.bat only in that it does not automatically generate a zip file (-sdk should still create one).
• It is possible, but highly unlikely, that the pinned vcpkg registry commit may not be compatible with older toolsets (but it functions flawlessly against the current repo baseline).

What has been tested and how, request additional testing if necessary

• Tested across two separate mixed-use desktop machines with Windows 10/11, VS 18 2026, CMake 4.2.3, and CPython 3.12
• Verified that dependencies install and compilation completes successfully when passing:

build\build26.bat -dbg -npu -stage -install

build\build26.bat -opt -npu -stage -install

build\build26.bat -rwd -npu -stage -install

build\build26.bat -arm64 -npu -stage

build\build26.bat -ext "build\ext.vcpkg\vcpkg_installed\x64-windows" -opt -npu -stage

And several other variations of the above, with and without -stage, -ext, and -install (and accompanying optional directory prefix) to verify that the flags are working as expected and without order dependencies. Additionally tested with and without protobuf ports to verify that the optional port extension is working as expected.

• Verified xclbintest passes via: build\WRelease\runtime_src\tools\xclbinutil\Release\xclbintest.exe --resource-dir src\runtime_src\tools\xclbinutil\unittests\test_data. All tests are green:

[----------] Global test environment tear-down
[==========] 12 tests from 5 test suites ran. (363 ms total)
[  PASSED  ] 12 tests.

• CPack dev zip creation (-sdk flag) was tested, but WiX packaging has not been validated. It was, however, directly carried over from build22.bat.
• Testing in both public and private CI environments should be possible, but was not performed in this PR.
• Fallback to VS 17 2022 was not thoroughly tested.
• Compiled ARM64 target was not tested on actual hardware, but compilation completed successfully with the appropriate flags and dependencies.

Documentation impact (if any)

None in this PR. The new scripts provide some self-documentation via -help. However, additional documentation can be added if desired/required.

[xrt-pr-bot]

⚠️ Authorization Failed

@thomthehound is not a repository collaborator.

To proceed:

• XRT Admins: Add the build label to authorize this PR build
• OR Add @thomthehound as a repository collaborator

[stsoe]

Thank you for making windows build more user friendly. These are really great enhancements.

I was experimenting with this myself, I wanted to create a separate repo that managed and built the vcpkg dependencies, but I actually like what you are doing here.

Few comments though.

I think you are building vcpkg dynamic dependencies by default?One requirement is that XRT links statically with all external dependencies. I believe this would eliminate the stage option. If someone insists in building with dynamic dependencies, then sure we could accommodate that, but the default build has to link statically with vcpkg dependencies (minus OpenCL.dll of course). Now, I am fully aware that the CI scripts I added yesterday also use dynamic dependencies, and I need to fix that at some point.

Secondly, default building vcpkg dependencies as part of the build is going to drive novice developers crazy. They will forget to supply the -ext argument pointing to a pre-built area and instead incur excessive long build times. I'd much rather reverse the logic, and stick with a fixed pre-populated ext-dir by default. I would prefer special explicit switch for invoking the vcpkg part of the script.

I like how you pin the vcpkg hash XRT. It has long bothered me that ext.new doesn't reflect the sources used to build the external dependencies, so if we reverse the logic to point at a pre-popuated ext-dir backed into build26.bat. then maybe this directory should carry the hash of vcpkg in its name ext.vcpkg.<hash>?

[thomthehound]

Thank you for making windows build more user friendly. These are really great enhancements.

I was experimenting with this myself, I wanted to create a separate repo that managed and built the vcpkg dependencies, but I actually like what you are doing here.

Few comments though.

I think you are building vcpkg dynamic dependencies by default?One requirement is that XRT links statically with all external dependencies. I believe this would eliminate the stage option. If someone insists in building with dynamic dependencies, then sure we could accommodate that, but the default build has to link statically with vcpkg dependencies (minus OpenCL.dll of course). Now, I am fully aware that the CI scripts I added yesterday also use dynamic dependencies, and I need to fix that at some point.

Thank you for your kind words and for taking the time to look at this, Soren. It is always my pleasure.

I agree with what you are saying about static vs. dynamic linking. I actually wasn't doing that to mimic you: this was a habit of mine due to an old bug I ran into while working on the Windows bring-up for mlir-aie. I'll try to track down again where the specific problem was so I can jog my memory, but I believe it had something to do with pyxrt not functioning properly on end-user systems due to a need for the signed (driver-supplied) version of xrt_coreutil.dll. Surprisingly, linking dynamically never appeared to break anything that wasn't already unavailable due to that signed driver, so the habit stuck. Regardless, I will refactor to make dynamic builds optional and static builds default. I may simply replace the -stage flag with -dynamic in this case, which should be clean.

Secondly, default building vcpkg dependencies as part of the build is going to drive novice developers crazy. They will forget to supply the -ext argument pointing to a pre-built area and instead incur excessive long build times. I'd much rather reverse the logic, and stick with a fixed pre-populated ext-dir by default. I would prefer special explicit switch for invoking the vcpkg part of the script.

I think I see what you are driving at with preferring pre-packaged dependencies, so I can arrange to reverse the logic. In fact, I had anticipated you might say something like that. It just did not seem reasonable for me to act on that assumption in the initial PR. Would expecting the packages to be in C:\Xilinix\XRT\ext.new be acceptable, or do you have somewhere else in mind?

I like how you pin the vcpkg hash XRT. It has long bothered me that ext.new doesn't reflect the sources used to build the external dependencies, so if we reverse the logic to point at a pre-popuated ext-dir backed into build26.bat. then maybe this directory should carry the hash of vcpkg in its name ext.vcpkg.<hash>?

I'm glad you like the hash. I was worried I was going too far with that, but I was also bothered by the same thing. I think I might need to change the location of the dependency staging directory if we include the hash in the name, though. From my experimentation, it appears I've already started to approach the maximum safe path length on Windows, and the hash is long. Perhaps I can see what happens if I include only the first ~7 hex digits, as they appear on GitHub.

I'll try to get this done as quickly as possible, but it is likely to take me at least a couple of days to draft the requested changes.

[xrt-pr-bot]

⚠️ Authorization Failed

@thomthehound is not a repository collaborator.

To proceed:

• XRT Admins: Add the build label to authorize this PR build
• OR Add @thomthehound as a repository collaborator

[thomthehound]

@stsoe, sorry about the wait on this. Some things came up.

I believe I have implemented the changes you requested:

(1) Dependencies and the build script use the static triplet by default

• Custom -triplet <triplet> can still be passed in xrtdeps-vcpkg.bat
• Users can force dynamic builds by passing the -dynamic switch in build26.bat, which also automatically stages the needed DLLs.

(2) build26.bat looks for dependency candidate directories in the following order:

• build\ext.vcpkg\vcpkg_installed<triplet>
• C:\Xilinx\XRT\ext.new\vcpkg_installed<triplet>
• C:\Xilinx\XRT\ext.new<triplet>
• C:\Xilinx\XRT\ext.new

This was chosen because (A) it can be reasonably expected that the user would not run xrtdeps-vcpkg.bat unless they intended to use it, and xrtdeps-vcpkg.bat never runs without direct user intervention (meaning they would have to have hunted through the dir tree to even find it, inherently gating its use) and (B) It was little extra work to provide flexibility on exactly what directory tree your dependency packaging scheme might produce, so we have options.

(3) In the interest of keeping things tidy and not overly complicating the scripts, xrtdeps-vcpkg.bat writes a 40-byte .vcpkg-baseline into the directory containing the SHA hash of the used vcpkg baseline instead of writing the hash directly into the directory name. Being a single line, the .vcpkg-baseline file can be parsed easily by a .bat file (or anything else). This file acts as a stamp for the triplet. Additionally, a -pkg switch was added to xrtdeps-vcpkg.bat that writes into build\pkg a zip file containing vcpkg_installed\<triplet> and stamps it with the first seven hex digits of the SHA hash (e.g.: ext.vcpkg.66c0373.x64-windows-static.zip).

If you want the directories themselves named, I can still do that, but I think this is the cleaner option.

Usage remains the same:

# Build deps:
src\runtime_src\tools\scripts\xrtdeps-vcpkg.bat

# Build and install XRT
build\build26.bat -opt -npu -install

# XRT is installed to C:\Xilinx\XRT by default

Of course, we can always just tell users to "Install the dependency package into C:\Xilinx\ext.new and then run build\build26.bat -opt -npu -install". That will work just fine now.

Note: I think I have found a bug when building xbtracer with static dependencies on Windows. I am going to look into this further.

[stsoe]

Thank you @thomthehound . This looks really good. I will take it for a spin to familiarize myself with the scripts and options you have added.

[thomthehound]

Thank you @thomthehound . This looks really good. I will take it for a spin to familiarize myself with the scripts and options you have added.

I'm glad to hear it! If you have any other requests of me, please do not hesitate to ask.

While you are testing, just be aware that, right now, it only builds xbtracer without error if dynamic protobuf is used. Obviously, it will not even try to build xbtracer if you don't pass -port protobuf, so this should not be an issue in the vast majority of cases. I've figured out the problem (the xbtracer CMakeLists was never build to take vcpkg config-mode into account) and should have a patch for that ready in another PR later tonight or tomorrow. I'll be leaving the old, shimmed abseil code in the CMakeLists in case it is needed for anything, but I suspect it will be safe to remove at a later date.

[stsoe]

Hi @thomthehound . Do you mind rebasing this PR against latest master to pull in #9633 along with other changes?

[xrt-pr-bot]

⚠️ Authorization Failed

@thomthehound is not a repository collaborator.

To proceed:

• XRT Admins: Add the build label to authorize this PR build
• OR Add @thomthehound as a repository collaborator

[thomthehound]

@stsoe Should be good to go now.

[xrt-pr-bot]

⚠️ Authorization Failed

@thomthehound is not a repository collaborator.

To proceed:

• XRT Admins: Add the build label to authorize this PR build
• OR Add @thomthehound as a repository collaborator

[thomthehound]

How interesting. Accepting a suggested change causes the DCO to fail. I would have thought that me being signed in would count as signing the commit.

[stsoe]

How interesting. Accepting a suggested change causes the DCO to fail. I would have thought that me being signed in would count as signing the commit.

Hmm, yes, but all commits have to be individually signed off. This is a little painful.

[xrt-pr-bot]

⚠️ Authorization Failed

@thomthehound is not a repository collaborator.

To proceed:

• XRT Admins: Add the build label to authorize this PR build
• OR Add @thomthehound as a repository collaborator

[stsoe]

Hi @thomthehound . I've not been successful with xrtdeps-vcpkg.bat. Right now I forget what error I got, but it was somewhere deep on vcpkg. Does it run from a clean state for you?

There are few additional complications. We need OpenCL dependency created as x64-windows dynamic, copied to same install area as all the static libraries. Also, we need protobuf, which I can't get vcpkg to build.

I am worried about the vcpkg automation in build26.bat. I don't really want to support this when our developers run into problems, or decides to build their own dependencies, which then maybe don't work. For our developers, I much prefer a central area managed by our DevOps. To that extend, I am leaning towards a separate repo, that builds dependencies with vcpkg as much as possible, then maybe special cases whatever vcpkg can't build. For external folks, this could be documented as they way to build XRT dependencies. My WIP is here: https://github.com/stsoe/xrtdeps-vcpkg.

[thomthehound]

Hi @thomthehound . I've not been successful with xrtdeps-vcpkg.bat. Right now I forget what error I got, but it was somewhere deep on vcpkg. Does it run from a clean state for you?

There are few additional complications. We need OpenCL dependency created as x64-windows dynamic, copied to same install area as all the static libraries. Also, we need protobuf, which I can't get vcpkg to build.

I am worried about the vcpkg automation in build26.bat. I don't really want to support this when our developers run into problems, or decides to build their own dependencies, which then maybe don't work. For our developers, I much prefer a central area managed by our DevOps. To that extend, I am leaning towards a separate repo, that builds dependencies with vcpkg as much as possible, then maybe special cases whatever vcpkg can't build. For external folks, this could be documented as they way to build XRT dependencies. My WIP is here: https://github.com/stsoe/xrtdeps-vcpkg.

Thank you again for taking the time to review this, Soren, and also for sharing your WIP repo. That makes the direction you want much clearer.

I have tested xrtdeps-vcpkg.bat from fresh clones on two separate systems, from both x64 Native Tools and PowerShell, using both the VS 2026 bundled vcpkg and a standalone clone from GitHub. In all cases I was able to build protobuf locally with -port protobuf, so I have not yet been able to reproduce the failure(s) you are seeing. I am going to do some additional testing against VS 2022 as well, since that is one possible source of the difference.

For OpenCL, I can replicate in xrtdeps-vcpkg.bat what your repo appears to be doing. That should be straightforward, just a bit of time.

I think I better understand your concern now about build26.bat referencing xrtdeps-vcpkg. My patch was written from a user-convenience perspective, but I agree that the main build script should not make locally built dependency trees look like the default supported path for developers. I will modify build26.bat so that it makes no reference to xrtdeps-vcpkg and instead stays aligned with a centrally managed dependency area by default.

Part of why I ended up splitting the difference here is that I have previously had patches held up because codeowners wanted scripts I'd written for the CI to also be convenient for end-users on desktop systems. But I understand the maintenance concern (and I agree with you). Now that Windows is going to get distribution support, there is much less need for users to build everything locally. I will revise the patch accordingly.

This may take me a few days to rework and retest.

[xrt-pr-bot]

⚠️ Authorization Failed

@thomthehound is not a repository collaborator.

To proceed:

• XRT Admins: Add the build label to authorize this PR build
• OR Add @thomthehound as a repository collaborator

[xrt-pr-bot]

⚠️ Authorization Failed

@thomthehound is not a repository collaborator.

To proceed:

• XRT Admins: Add the build label to authorize this PR build
• OR Add @thomthehound as a repository collaborator

[thomthehound]

• build26.bat no longer mentions/suggests the use of xrtdeps-vckpg.bat; it now assumes a centrally managed dependency area unless -ext is explicitly provided.

• Split OpenCL out in xrtdeps-vcpkg.bat so it is built as x64-windows dynamic and then copied back into the main dependency prefix.

I have still not been able to replicate an error in building protobuf. In addition to my other tests, I have removed all development tools from my secondary machine, nuked all caches, completely removed any instance of vcpkg anywhere, and re-installed with the bare minimum VS 2022 Build Tools, and it has still worked for me.

However, I just tried an absurdly long path length for the build, and that did fail in the x64 Native Tools Command Prompt (not exactly at protobuf, but that could simply be a function of the exact number of characters), so perhaps it is a path length issue?

[thomthehound]

@stsoe one other possibility, if you are saying you've never been able to build protobuf specifically from the Windows CI runner is that you might be getting bitten by the Ninja 1.13.0 response file parsing bug. The best way around that is to use the windows-2025 runner (which is still on VS 2022 but slated to switch to VS 2026 in May, I believe) or use windows-2025-vs2026 (I think that might permanently be an Insiders VS, though).

[thomthehound]

It appears that deprecation warnings issued after #9651 may be breaking Windows builds in pyxrt:

Build FAILED.

"F:\tst\XRT\build\WRelease\ALL_BUILD.vcxproj" (default target) (1) ->
"F:\tst\XRT\build\WRelease\python\pybind11\pyxrt.vcxproj" (default target) (32) ->
(ClCompile target) ->
  F:\tst\XRT\src\python\pybind11\src\pyxrt.cpp(138,42): error C4996: 'xrt::device::load_xclbin': deprecated, please use hw_context() instead [F:\tst\XRT\build\WRelease\python\pybind11\pyxrt.vcxproj]
  F:\tst\XRT\src\python\pybind11\src\pyxrt.cpp(142,42): error C4996: 'xrt::device::load_xclbin': deprecated, please use hw_context() instead [F:\tst\XRT\build\WRelease\python\pybind11\pyxrt.vcxproj]

I do not think these warnings should be suppressed. I am setting aside some time to migrate the remaining pyxrt.pyd paths over to hw_context. The file is not large and the work seems quite straightforward.

I'm considering leaving a small shim through the non-deprecated C bindings (with a deprecation warning issued through Python) so anything downstream still using load_xclbin has a little more time to adapt, because that really should the the point of a warning after all. On the other hand... I'm not sure if that would be time well spent. I know almost half a dozen tests are also going to need updating if pyxrt.pyd API-breaks.

[stsoe]

It appears that deprecation warnings issued after #9651 may be breaking Windows builds in pyxrt:

Build FAILED.

"F:\tst\XRT\build\WRelease\ALL_BUILD.vcxproj" (default target) (1) ->
"F:\tst\XRT\build\WRelease\python\pybind11\pyxrt.vcxproj" (default target) (32) ->
(ClCompile target) ->
  F:\tst\XRT\src\python\pybind11\src\pyxrt.cpp(138,42): error C4996: 'xrt::device::load_xclbin': deprecated, please use hw_context() instead [F:\tst\XRT\build\WRelease\python\pybind11\pyxrt.vcxproj]
  F:\tst\XRT\src\python\pybind11\src\pyxrt.cpp(142,42): error C4996: 'xrt::device::load_xclbin': deprecated, please use hw_context() instead [F:\tst\XRT\build\WRelease\python\pybind11\pyxrt.vcxproj]

I do not think these warnings should be suppressed. I am setting aside some time to migrate the remaining pyxrt.pyd paths over to hw_context. The file is not large and the work seems quite straightforward.

I'm considering leaving a small shim through the non-deprecated C bindings (with a deprecation warning issued through Python) so anything downstream still using load_xclbin has a little more time to adapt, because that really should the the point of a warning after all. On the other hand... I'm not sure if that would be time well spent. I know almost half a dozen tests are also going to need updating if pyxrt.pyd API-breaks.

@chvamshi-xilinx @karthdmg-xilinx FYI, I thought we have had fixed the deprecation warnings in our own code? It's premature to deprecate APIs we are using.

[chvamshi-xilinx]

It appears that deprecation warnings issued after #9651 may be breaking Windows builds in pyxrt:

Build FAILED.

"F:\tst\XRT\build\WRelease\ALL_BUILD.vcxproj" (default target) (1) ->
"F:\tst\XRT\build\WRelease\python\pybind11\pyxrt.vcxproj" (default target) (32) ->
(ClCompile target) ->
  F:\tst\XRT\src\python\pybind11\src\pyxrt.cpp(138,42): error C4996: 'xrt::device::load_xclbin': deprecated, please use hw_context() instead [F:\tst\XRT\build\WRelease\python\pybind11\pyxrt.vcxproj]
  F:\tst\XRT\src\python\pybind11\src\pyxrt.cpp(142,42): error C4996: 'xrt::device::load_xclbin': deprecated, please use hw_context() instead [F:\tst\XRT\build\WRelease\python\pybind11\pyxrt.vcxproj]

I do not think these warnings should be suppressed. I am setting aside some time to migrate the remaining pyxrt.pyd paths over to hw_context. The file is not large and the work seems quite straightforward.
I'm considering leaving a small shim through the non-deprecated C bindings (with a deprecation warning issued through Python) so anything downstream still using load_xclbin has a little more time to adapt, because that really should the the point of a warning after all. On the other hand... I'm not sure if that would be time well spent. I know almost half a dozen tests are also going to need updating if pyxrt.pyd API-breaks.

@chvamshi-xilinx @karthdmg-xilinx FYI, I thought we have had fixed the deprecation warnings in our own code? It's premature to deprecate APIs we are using.

Hi @stsoe ,
@karthdmg-xilinx changed from load_xclbin to hw_context in all the places, Looks like we need to deprecate pyxrt bindings for load_xclbin aswell.
I merged it after that PR build is passed, but somehow our PR build is not catching the pyxrt failures.
@karthdmg-xilinx , Can you please work on it.