Windows Workflow
================

Build inside the Windows container, which synchronizes the artifacts back to the repository,
then run the built application and tests on the Windows host with PowerShell.

Build In The Container
----------------------

.. code-block:: powershell

   .\scripts\windows\Invoke-ContainerBuild.ps1

The wrapper delegates to ANTfrastructure's ``Invoke-ContainerBuild``
(``WindowsContainerBuild.Reuse``), which runs ``scripts/windows/Build-Windows.ps1`` inside a
reusable container:

- **Transport:** the sources travel by tar-pipe to the family workspace path ``C:\ws``. Bind
  mounting is the measured-slower opt-in (``-UseBindMount``); ``-FreshContainer`` discards the
  reused build tree.
- **Resources:** ``--isolation process`` gives the container every host CPU;
  ``-CpuCount``/``-MemoryGb`` apply only under ``-Isolation hyperv``.
- **Targets:** ``clangcl-debug``, ``clangcl-profile`` and ``clangcl-release``.
- **Delivery:** ``build-<target>`` (verified per lane), ``logs`` and ``dist`` come back to the
  host (`Artifact Locations`_).

Run The Build Script Directly
-----------------------------

Inside the image, the same script CI runs:

.. code-block:: powershell

   pwsh -NoProfile -File .\scripts\windows\Build-Windows.ps1
   pwsh -NoProfile -File .\scripts\windows\Build-Windows.ps1 -BuildTargets clangcl-debug -LogDir logs\debug

Build directories and presets are rows in
``scripts/windows/Build-Windows.config.psd1``, not parameters; each row also names
an environment variable that overrides it. ``-LogDir`` is relative to the
workspace. The script expects the family Windows image (its toolchain, its
GStreamer and its chain ONNX Runtime); from a host,
``.\scripts\windows\Invoke-ContainerBuild.ps1`` runs it inside that image.

Artifact Locations
------------------

The container build syncs its output back into the workspace, where the host-side scripts run
it directly:

- ``build-clangcl-debug``
- ``build-clangcl-profile``
- ``build-clangcl-release``
- ``dist\windows-x64`` for the release configuration's products: the portable
  ``bundle`` (the install tree with the engine's whole DLL closure), the MSI,
  ZIP and NSIS installers in ``packages``, and the MSIX in ``msix``
- ``logs`` for container build logs and analysis artifacts

Host-Side Execution
-------------------

``Start-Windows.ps1`` runs a configuration's executables outside the container. A missing or
unstartable binary fails the run; for one that exists but will not start, the script first walks
its imports and names every DLL the loader cannot find.

Debug Run
^^^^^^^^^

.. code-block:: powershell

   .\scripts\windows\Start-Windows.ps1 -Config Debug

Starts the CLI from ``build-clangcl-debug\bin\AccelerANTgine.exe`` for a stable local version
check, then runs ``commitTestSuite.exe``, ``compileTestSuite.exe`` and ``fuzzTestSuite.exe`` (in
FuzzTest's unit mode, about a second per property).

With a signalling server already running on the host, opt into the network-dependent WebRTC
smoke test:

.. code-block:: powershell

   .\scripts\windows\Start-Windows.ps1 -Config Debug -RunWebRtcSmoke -ServerUri ws://localhost:8443

Profile Run
^^^^^^^^^^^

.. code-block:: powershell

   .\scripts\windows\Start-Windows.ps1 -Config Profile

Runs the profile build executable, then ``perfTestSuite.exe``; a missing suite fails the run.

Release Run
^^^^^^^^^^^

.. code-block:: powershell

   .\scripts\windows\Start-Windows.ps1 -Config Release

The CLI check, run from ``build-clangcl-release\bin`` (the build tree, not the ``dist``
bundle), then the Release suites ``Build-Windows.ps1 -StageTests`` staged in
``dist\windows-x64-tests``, through their ``Invoke-StagedTests.ps1``; a failed or an empty
verdict fails the run. Without staged suites it is the CLI check alone.

Build Script Responsibilities
-----------------------------

``scripts/windows/Build-Windows.ps1`` does more than compile:

- formats the CMake and C++ sources in place (``-SkipFormat`` skips both)
- configures preset-driven builds
- stages the image's GStreamer DLLs, the chain ONNX Runtime (proved by
  ANTfrastructure's G6 census) and the toolset's VC++ runtime beside each
  configuration's binaries
- runs debug tests with ``ctest``
- has an LLVM coverage step over ``Test\compile\default.profraw``, which finds
  nothing today: the ``x64-ClangCL-Windows-Debug`` preset leaves
  ``myproject_ENABLE_COVERAGE`` off
- runs ``clang-tidy``
- runs profile benchmarks
- builds release packages and the portable bundle in ``dist\windows-x64``
- optionally creates MSIX output (``-SkipMSIX`` skips it), signed with the first
  ``*.pfx`` at the repository root and ``MSIX_PFX_PASSWORD`` when there is one,
  and unsigned with a warning otherwise

CI Note
-------

CI runs the same script, but not through ``Invoke-ContainerBuild.ps1``: both Windows lanes call
ANTfrastructure's reusable ``container-ci-windows.yml``, which bind-mounts the checkout
(``D:\ws`` on the runner, ``C:\ws`` in the container) and runs ``Build-Windows.ps1`` there. The
x64 lane then runs ``Start-Windows.ps1 -Config Debug|Profile|Release`` on the runner host, which
has the desktop the container lacks; the arm64 cross build runs on GitHub's ``windows-11-arm``
runner. Both lanes, their targets, artifacts and side jobs: ``AGENTS.md`` § 5.