windows: fix native MSVC/Vulkan build portability

[ElderOrb]

Removes POSIX-only constructs from the test and loader paths that MSVC cannot
compile, behind one small internal shim, so the Windows target list can widen
past the seven binaries scripts/build-windows-release.ps1:372-382 builds today.

src/vllm/support/platform_compat.h (63 lines) carries five inline helpers with
Windows and POSIX arms: HostPageSize, CurrentProcessId,
FileDescriptorFromFile, TruncateFile and SetEnvVar. HostPageSize is the
one with a production caller — safetensors_reader.cpp:285 now delegates to it,
byte-for-byte behaviour-preserving inside the pre-existing #if !defined(_WIN32).
The other four are reached from tests only; they are recorded as such rather than
claimed as shipped capability.

SetEnvVar is deliberately NOT normalised on an empty value: _putenv_s(name, "")
removes the variable where POSIX setenv(name, "", 1) defines it empty. No caller
passes an empty value, so normalising would be unexercised code. The header records
the contract, matching the rule tests/support/test_env.h already states for the
test-side seam.

Seven test suites lose their POSIX-isms: ::mkdir becomes
std::filesystem::create_directories, ::rmdir becomes fs::remove, ::getpid
becomes CurrentProcessId, and test_minimax_h3_video_fold.cpp replaces a
std::system("rm -rf '" + root + "'") — a shell-injection-shaped construct on a
path — with fs::remove_all. tests/capi/test_capi.cpp routes its ::unsetenv
through the existing tests/support/test_env.h seam rather than a new one.

tests/capi/test_dlopen.cpp gains a LoadLibraryA/GetProcAddress abstraction
alongside dlopen/dlsym, and fixes a latent bug on the path we run every day:
the old INFO("dlopen error: ", (dlerror() != nullptr ? dlerror() : "")) called
dlerror() twice, and the first call consumes and clears the error, so on a real
failure the ternary streamed the second call's nullptr as a const char*.
LastSharedLibraryError() reads it once.

CMakeLists.txt gives vllm_shared an ARCHIVE_OUTPUT_NAME. Without it,
install(TARGETS vllm vllm_shared ARCHIVE DESTINATION ...) installs the shared
target's MSVC import library and the static archive both as vllm.lib, and one
overwrites the other. No-op on ELF and Mach-O, where a SHARED target has no
ARCHIVE artifact. This is the one piece here that fixes a defect rather than
preparing for one.

Scope, stated plainly

None of these files is built by either Windows CI lane today, so this does not
move #584 and does not turn windows-msvc-* green — that lane now compiles,
links vllm-server.exe and runs its tests, and dies at #584's 0xC0000409
runtime crash. What lands here is the prerequisite removal of POSIX-isms, plus
the vllm.lib collision fix and the dlerror() repair.

Maintainer changes on top

Three, applied while landing, none altering behaviour:

• examples/laguna_gen is reverted to main's version and loses a private
  -I ${CMAKE_SOURCE_DIR}/src. Reaching platform_compat.h would have made it
  the first example to include a header existing only under src/; every prior
  entry on its scripts/example-abi-allowlist.txt row is an include/ header,
  and check-surface-coverage.py parses #include lines and is blind to -I
  flags, so no gate would have caught it. laguna-gen is not built on Windows,
  so it bought nothing there.
• vllm_cpp_add_test no longer grants ${CMAKE_SOURCE_DIR}/src to every test.
  The file already carries 123 explicit per-target grants; the five suites that
  actually reach the shim get it by name.
• SetEnvVar's empty-value divergence is documented in the header.

Issue: #503

FOLLOWING_AGENTS_PROTOCOL

Following-Agents-Protocol: true
AI-Assisted: true
Assisted-by: ClaudeCode:claude-opus-5 [ClaudeCode]

[localai-org-maint-bot]

This portability PR is not reviewable as a merge candidate while its own portability and build gates are red. The current head fails windows-msvc-cpu, windows-msvc-vulkan, both Linux build-test jobs, Vulkan verification, both sanitizer jobs, commit-protocol-tag, agent-record, device-leakage, and documentation-checkpoint. Please rebase onto current main, add the required FOLLOWING_AGENTS_PROTOCOL trailer to every PR commit, and push a head where the intended MSVC/Vulkan fixes pass their target jobs. After that, the large mechanical compatibility diff can be reviewed against a meaningful green signal.

[localai-bot]

Thanks for tackling this, and welcome — the Windows arm being red on every PR is a real problem and the centralising instinct here is the right one. Four hand-rolled setenv shims scattered across the tree is a genuine smell and a shared platform_compat.h is where that should end up.

I have to be straight with you though: as it stands this PR does not turn the Windows jobs green, and it breaks the Linux build in two places. Details below so you can judge what to keep.

The Windows jobs go redder, not greener

Both die in scripts/check-windows-portability.py before the compiler ever runs. Conclusions read from the API, head 45550dc:

windows-msvc-cpu     conclusion=failure  (job 94566363611)
windows-msvc-vulkan  conclusion=failure  (job 94566363526)

ERROR: include/vllm/support/platform_compat.h:17: unguarded POSIX include/call reaches Windows
ERROR: include/vllm/support/platform_compat.h:21: unguarded POSIX include/call reaches Windows
ERROR: src/vllm/multimodal/video_engine.cpp:21/59/64: unguarded POSIX include/call reaches Windows
ERROR: cpu_matmul_elem.cpp: F16C must be isolated in a dedicated translation unit

The current baseline red is three errors, all video_engine.cpp (issue #664, already fixed by open PR #677). This PR leaves those three and adds three of its own.

The two new ones are your #include <fcntl.h> and #include <sys/stat.h> at platform_compat.h:17,21 — which sit inside #if defined(_WIN32) and are legitimate MSVC CRT headers. So the checker is arguably over-broad here (its pattern matches the spelling regardless of branch). That's a fair thing to argue for changing, but changing a checker's semantics needs a spec plus red-before/green-after evidence under AGENTS.md, and this PR neither changes the checker nor makes the case.

Important, and not your fault: the reason your native Windows validation passed while CI fails is that your host build never runs this gate. And separately — even a perfect version of this PR could not have turned windows-msvc-cpu green, because #584 (test_openai_api_server crashing with STATUS_STACK_BUFFER_OVERRUN 0xC0000409) is still open and independent of everything here.

Two Linux breaks, both reproduced locally

1. -Werror=unused-function. vulkan_loader.cpp adds three helpers to an anonymous namespace and calls one:

$ g++ -std=c++20 -Wall -Wextra -Werror ... -c src/vt/vulkan/vulkan_loader.cpp
error: 'void ...CloseSharedLibrary(void*)' defined but not used
error: 'void* ...LoadSharedSymbol(void*, const char*)' defined but not used
# same command on base: compiles clean

2. Missing include. tests/vllm/v1/test_kv_offload_tiering.cpp:43 calls vllm::support::CurrentProcessId() but never includes platform_compat.h → 'vllm::support' has not been declared. This one is instructive: your /FI force-include in tests/CMakeLists.txt is MSVC-only, so it silently supplies the header to every test on Windows and to none on Linux. That's why it built for you. I swept the whole tree for the same class and this is the only instance — contained.

Three hunks I'd drop

• cmake/CompilerWarnings.cmake: /WX → /WX- plus COMPILE_WARNING_AS_ERROR OFF and blanket /wd4324 /wd4458. AGENTS.md is explicit that you may not turn a red gate green by widening a scope. Worth knowing: check-windows-portability.py:1710 tests "/WX" in warnings, and "/WX" in "/WX-" is True — so the gate is blind to its own inversion. The only bare /WX left in your version is on COMPILE_LANGUAGE:OBJCXX, i.e. Metal, which never builds under MSVC. That checker gap is ours and I'm filing it regardless of what happens here.
• VT_CPU_F16C_TARGET is defined and used nowhere (git grep returns only its own two definition lines) and it trips the F16C-isolation contract. Pure cost.
• nvfp4_persistent_cache.cpp — this file is if(NOT WIN32) at CMakeLists.txt:1352 and is hard-coded as WINDOWS_EXCLUDED_SOURCE in the checker, so it never compiles on Windows at all. The rewrite replaces ::mkstemp (random name, O_EXCL) with a predictable .tmp.<pid>.<counter> opened trunc, and drops ::fsync — flush() only drains the C++ stream buffer, so the write-then-rename durability guarantee is gone. The project's contract for exactly this operation lives one directory over in fs_io.cpp (CREATE_NEW, FlushFileBuffers, ::fsync, MOVEFILE_WRITE_THROUGH). Linux/CUDA regression for no Windows benefit.

Also inert: the elseif(MSVC) at CMakeLists.txt:1228 is unreachable — if(MSVC) at 1224 already matched — so the /WHOLEARCHIVE fix the body describes can't execute.

What I'd keep

The ARCHIVE_OUTPUT_NAME / blake3_vendored link fixes look like real repairs (I can't verify them from Linux). #undef CreateEvent correctly identifies the Win32 A/W macro collision, though the tree's idiom is #pragma push_macro/pop_macro rather than a bare #undef in a public header, which permanently unmaps the name for every downstream TU. And the shared-helper direction is right.

Sequencing

There are four other Windows PRs in flight and this collides with them. #524 hard-conflicts — you both edit tests/CMakeLists.txt and insert at the top of test_api_server.cpp, and #524 duplicates your M_PI and POSIX-stat work by other means. #578 is a third spelling of the same setenv shim. #677 fixes the three video_engine.cpp errors that are the actual current baseline red, so it's the shortest path to green and worth landing first.

My suggestion: let #677 and #584 land, then bring this back split into (a) the shared platform_compat.h with the two Linux breaks fixed and the /FI made cross-platform, and (b) the packaging/link fixes — dropping the /WX- downgrade, the dead F16C macro, the dead elseif, and the nvfp4 rewrite. That version is genuinely valuable and much easier to review.

One housekeeping note, and a normal thing for a first contribution: commits need a bare FOLLOWING_AGENTS_PROTOCOL line plus Following-Agents-Protocol: true, AI-Assisted: true and Assisted-by: trailers — that's what commit-protocol-tag and agent-record are flagging. See AGENTS.md § "Landing work". A tracking issue linked in the PR body is wanted too; ENG-RELEASE-WINDOWS is the row this belongs to.

[localai-bot]

Re-reviewed against current main, and the substantive work is now sound — thank you for turning it round. I verified by building rather than reading:

• /WX- and COMPILE_WARNING_AS_ERROR OFF are gone.
• Both Linux breaks are fixed. vulkan_loader.cpp compiles clean under -Wall -Wextra -Werror (the unused-function error is gone — CloseSharedLibrary is now actually called), and test_kv_offload_tiering.cpp no longer errors on vllm::support.
• The nvfp4_persistent_cache.cpp rewrite is dropped, and ::fsync is back — the write-then-rename durability guarantee is intact.
• Rebased onto current main, scripts/check-windows-portability.py reports Windows portability contract OK, under the stricter checker that landed in fix(GATE-WINDOWS-WARNING-POLICY): /WX- is not /WX, and OBJCXX is not the C++ compile (#774) #795.

Two things are left, and they are packaging rather than code.

1. platform_compat.h needs to live under src/, not include/

check-doc-checkpoint classifies any include/vllm/ edit as landing_page, user_usage and demands a docs/USAGE.md entry:

ERROR: commit 74ba3823f: changed feature_surface, landing_page, user_usage
       but did not update docs/FEATURES.md, docs/USAGE.md
ERROR: commit 15aa963a6: changed landing_page, user_usage
       but did not update docs/USAGE.md

There is nothing user-facing to say about it — it is a loader/test portability shim, not public ABI — so the right answer is to move it out of the public header tree rather than invent a USAGE entry. That is the same conclusion another change reached independently this week (#815 put voxtral_loader_internal.h under src/ for exactly this reason), and the house has the precedent already: qwen3_5_internal.h, voxtral_loader_internal.h, capi/engine_handle.h.

I tried to do this for you and stopped, because it is bigger than it looks. CMakeLists.txt:1283 is target_include_directories(vllm PRIVATE src) — PRIVATE, so src does not propagate to test targets. Ten of the eighteen includers are tests:

tests/capi/test_capi.cpp                    tests/parity/test_op_parity.cpp
tests/vllm/gguf_builder.h                   tests/vllm/test_qwen36_weights.cpp
tests/vllm/test_safetensors.cpp             tests/vllm/v1/test_kv_offload_connector.cpp
tests/vllm/v1/test_kv_offload_tiering.cpp   tests/vllm/models/test_minimax_h3_video_fold.cpp
tests/vt/test_nvfp4_persistent_cache.cpp
tests/vllm/model_executor/layers/attention/test_mla_attention_block.cpp

so each needs target_include_directories(<t> PRIVATE ${CMAKE_SOURCE_DIR}/src), which is the established per-target idiom (tests/CMakeLists.txt:1158 does exactly that for test_capi). I did not want to reshape ~60 files of your PR on your behalf without asking.

2. Commit trailers

74ba3823f8e6: [trailers] FOLLOWING_AGENTS_PROTOCOL must appear exactly once
              as a separate paragraph before the trailer paragraph
15aa963a6e1d: [same]

Every commit needs a bare FOLLOWING_AGENTS_PROTOCOL line as its own paragraph, then:

Following-Agents-Protocol: true
AI-Assisted: true
Assisted-by: <AGENT:MODEL [TOOL]>

No Signed-off-by, and no AI Co-Authored-By. See AGENTS.md § "Landing work". This needs an amend/rebase of your two commits — it is per-commit, so a new commit on top will not clear it. Entirely normal for a first contribution; nothing else in the protocol is outstanding.

Worth knowing before you spend more time

The original goal is already met. check-windows-portability passes on plain main today — the three video_engine.cpp errors were fixed by another change, and I closed #677 as already-landed after confirming its diff against main is empty. The remaining Windows red is windows-msvc-cpu / windows-msvc-vulkan, which are PR-only jobs with no main baseline (#584) and fail on every PR in the repo for unrelated reasons — this PR could never have turned them green.

So what is left here is the cleanup half, and it is still genuinely worth having: four hand-rolled setenv shims across the tree is a real smell and a shared platform_compat.h is where that should end up. Two things to sequence against, though: #524 conflicts hard with this (both edit tests/CMakeLists.txt and insert at the top of test_api_server.cpp, and it duplicates your M_PI and POSIX-stat work by other means), and #578 is a third spelling of the same setenv shim. Landing #524 first and rebasing would make this much smaller and easier to review.

Happy to look again once the header moves and the trailers land.

[localai-bot]

Thank you for this, and sorry it has sat so long — the delay is on us, and it
has cost the PR: main has since fixed every compile blocker this branch was
written to remove.

What changed underneath it. Verified on main at 281e6a120:

• main does not compile under MSVC, and main-baseline.py reports GREEN because windows-msvc-* are PR-only jobs it never runs #503's named instance, tests/vt/test_cpu_isa_x86.cpp missing <ostream>,
  is already repaired. This branch adds <string_view> there — harmless, but
  no longer needed.
• windows-msvc CI is RED on main: test_backend_cross_device.cpp uses POSIX setenv/unsetenv, which MSVC does not provide #603's instance, tests/vt/test_backend_cross_device.cpp, already routes
  through tests/support/test_env.h (vllm_test::SetEnv/UnsetEnv), which was
  added for exactly that purpose. This branch does not touch that file and
  builds a competing shim instead.
• windows-msvc red: video_engine.cpp has three unguarded POSIX sites (an instance of #503, sibling of #603) #729 is closed; video_engine.cpp's POSIX sites are gone. This branch's
  entire change to that file is now the deletion of one blank line.
• windows-msvc-cpu/vulkan red on every PR based on c7cb59fbb: C4244 double->float in ltx2_video.cpp's StreamState<->Ltx2LatentState positions copy (#964) #968, the last compile blocker, landed two hours ago as fix(ltx2): cast positions double/float to avoid MSVC C4244 (#968) #983, and main does not compile under MSVC: #1054 removed a lambda capture that was not redundant #1068 (a
  regression from fix(qwen3.5): drop redundant AppleClang capture #1054) as fix(qwen3.5): the capture #1054 dropped was not redundant, and MSVC says so #1069. The MSVC lane now compiles, links
  vllm-server.exe and runs its tests — it fails only at test_openai_api_server crashes on Windows with STATUS_STACK_BUFFER_OVERRUN (0xC0000409), unmasked by the #512 fix #584's
  0xC0000409 runtime crash.

So the portability value this PR was carrying has largely been paid elsewhere,
and what remains is a 53-file diff whose costs now dominate.

The blocking findings, in order of weight

1. A second env seam beside the one that exists.
   src/vllm/support/test_platform_compat.h:598-631 adds
   SetEnvOrThrow / UnsetEnvOrThrow / ScopedEnvVar, duplicating
   tests/support/test_env.h, whose header comment says "New env-flipping tests
   include this header". AGENTS.md: extend a shared seam when it cannot
   represent the behavior; otherwise record one tracked exception; never write a
   parallel path by hand.

2. The duplicate seam gets that seam's one documented divergence wrong.
   tests/support/test_env.h normalises the empty value — _putenv_s(name,"")
   deletes on Windows while setenv(name,"",1) defines-empty on POSIX — and
   says a test needing defined-but-empty must say so at the call site.
   vllm::support::SetEnvVar does not normalise, and this PR uses it at a site
   that depends on it: tests/vllm/test_gguf_keep_quant.cpp,
   for (const char* off : {"0","false","off",""}) SetEnvOrThrow("VT_GGUF_KEEP_QUANT", off);
   On Windows the "" arm silently becomes unset rather than empty, which
   changes what that arm proves. Latent today because the file is not built on
   Windows; real the day it is.

3. Roughly 100 lines of platform_compat.h have no call site — kPi,
   both OpenFile overloads, CloseFile, ReadFile, WriteFile,
   MapReadOnlyFile, UnmapFile, AlignedAlloc, AlignedFree. Under Nothing
   lands dead that needs a ## Owed entry, an owning row and an issue, or it
   should not ship. It also carries #define O_CLOEXEC 0 and
   #define O_NOFOLLOW 0, which leak into every including TU and silently drop
   no-follow semantics, reachable only through the dead OpenFile.

4. Six unused includes drag <windows.h> into model TUs —
   mla_attention.cpp:12, deepseek_v4.cpp:70, minimax_h3_audio_vae.cpp:47,
   minimax_h3_video_vae.cpp:33, gguf_reader.cpp:17, tests/vllm/gguf_builder.h:17,
   none with a corresponding use. The new #pragma push_macro("CreateEvent")
   block in include/vt/backend.h is direct evidence of the resulting macro
   pollution — and it only fires if <windows.h> came first, while pop_macro
   restores the macro afterwards, so call sites later in the same TU are still
   rewritten to CreateEventA. It fixes the declaration, not the uses.

5. docs/USAGE.md overclaims. The inserted paragraph says the native-MSVC
   contract "now covers the supporting example and test binaries".
   scripts/build-windows-release.ps1:372-382 still builds the same seven
   focused targets, and nothing here changes that.

What is genuinely good and worth keeping. Your commit trailers are the only
ones of the three external Windows PRs that pass check-commit-trailers.py --filled cleanly, and the issue linkage is correct (Issue: #503, indexed at
.agents/issue-index.md:52). The vllm_shared ARCHIVE_OUTPUT_NAME plus
explicit blake3_vendored link, the test_dlopen.cpp
LoadLibraryA/GetProcAddress abstraction, and the mkdir/rm -rf/mkdtemp
→ std::filesystem conversions are all solid.

What we would merge today. Roughly a 15-file PR: the CMake packaging/link
fix, test_dlopen.cpp, the std::filesystem conversions, and a minimal
platform_compat.h carrying only the six helpers that have call sites — with
every env-var site routed through the existing tests/support/test_env.h, and
ScopedEnvVar added to that header if you want the scope guard (we would take
that gladly). If you would rather not carry the rebase, say so and we will split
it out with your authorship preserved.

Also worth knowing: five test cases here become TEST_CASEs containing only a
MESSAGE and zero assertions on Windows (test_capi.cpp:393-397,
test_load_direct_upload.cpp:19-24, test_none_hash_determinism.cpp:17-22,
test_lmcache_connector.cpp:32-37,1670-1674). You are honest about it in the
body, but a case with zero assertions reads as a pass in every summary we grep,
so each needs a named owning issue.

[ElderOrb]

Rebased onto current main and reduced this branch to the reviewed Windows/MSVC portability subset at bcf1df0b.

What changed since the earlier review:

• moved platform_compat.h under src/vllm/support/
• kept only the minimal helper set with live call sites
• removed the parallel env seam and routed the relevant env handling through the existing tests/support/test_env.h path
• dropped the Windows MESSAGE-only fake-pass cases
• kept the vllm_shared packaging/link fix and the LoadLibraryA / GetProcAddress shared-library smoke test
• narrowed the remaining portability changes to the temp-path / sparse-file call sites that still need them
• replaced the earlier overclaim in docs/USAGE.md with a minimal note only about the Windows shared-library packaging behavior this PR changes

The branch now locally passes the targeted gates:

• python scripts/check-commit-trailers.py --range upstream/main..HEAD
• python scripts/check-commit-style.py --range upstream/main..HEAD
• python scripts/check-doc-checkpoint.py --base upstream/main --head HEAD
• python scripts/check-windows-portability.py --root .

Would appreciate a re-review when convenient.