matrixfurry.com
The open source OpenXR runtime
1# Building on Windows {#winbuild}
2
3<!--
4Copyright 2022, Collabora, Ltd. and the Monado contributors
5SPDX-License-Identifier: BSL-1.0
6-->
7
8[TOC]
9
10Monado has a work-in-progress port to Windows. While it's not ready for
11widespread usage due to some rough edges and lack of drivers, it does build and
12can serve as a base for further development.
13
14## System Dependencies
15
16Most dependencies for the Windows build on Monado are handled by [vcpkg][].
17However, some are not installable or usable (in the way we want) through there,
18so they require separate installation. For each, the command line to install
19with "winget" (built in to at least Windows 11, and possibly newer builds of
20Windows 10) and/or [scoop][] are provided below. Use whichever one you are more
21comfortable with. (Scoop commands may require adding the "extras" bucket.)
22
23[vcpkg]: https://vcpkg.io
24[scoop]: https://github.com/ScoopInstaller/Scoop
25
26- CMake
27 - `winget install Kitware.CMake`
28 - `scoop install cmake`
29 - Recently, bundled with Visual Studio in a path like
30 `C:\Program Files\Microsoft Visual Studio\2022\Community\Common7\IDE\CommonExtensions\Microsoft\CMake\CMake\bin\cmake.exe`
31 which gets added to your PATH in a Visual Studio command prompt/PowerShell.
32- Python 3.x
33 - `winget install Python.Python.3.x` (replace x with the latest Python version).
34 - `scoop install python`
35- Vulkan SDK
36 - `winget install KhronosGroup.VulkanSDK`
37 - `scoop install vulkan`
38- Ninja (build tool, recommended but not strictly required)
39 - `winget install Ninja-build.Ninja`
40 - `scoop install ninja`
41 - Recently, bundled with Visual Studio in a path like
42 `C:\Program Files\Microsoft Visual Studio\2022\Community\Common7\IDE\CommonExtensions\Microsoft\CMake\Ninja\ninja.exe`
43 which gets added to your PATH in a Visual Studio command prompt/PowerShell.
44
45You will also need Visual Studio. Most current development is happening with
462022, though it should also build with 2019. (Work on Monado might meet the
47requirements for Microsoft's no-charge
48[Visual Studio Community](https://visualstudio.microsoft.com/vs/community/)
49license - see the
50[VS Community License Terms](https://visualstudio.microsoft.com/license-terms/vs2022-ga-community/)
51and talk to your lawyer if unsure, this is not legal advice.)
52
53We should be able to build using LLVM/Clang using libc++ instead of the MSVC
54standard library, but this hasn't been widely tested.
55
56## Configuring the build tree
57
58The main points to note are that:
59
60- If building against a normal clone/checkout of [vcpkg][], make sure that
61 `CMAKE_TOOLCHAIN_FILE` is set to
62 `yourVcpkgDir\scripts\buildsystems\vcpkg.cmake` (substituting `yourVcpkgDir`
63 as appropriate). This will put vcpkg in "manifest mode", and it will build and
64 install the dependencies in `vcpkg.json` (in the source tree) into a directory
65 in the build tree automatically.
66 - If you have run `.\vcpkg integrate install` in your vcpkg directory, this
67 toolchain is added automatically when you "Open Folder" in Visual Studio for
68 a folder containing CMake build scripts. So, in this case, just open the
69 Monado source directory and everything will be set up automatically for you.
70 - On the CMake command line, this means passing something like
71 `"-DCMAKE_TOOLCHAIN_FILE=yourVcpkgDir\scripts\buildsystems\vcpkg.cmake"`
72 (quotation marks possibly required depending on your shell).
73- If building against "exported" dependencies from a vcpkg install (which can be
74 used to share a build environment easily and reduce build times), you will
75 also need to set `CMAKE_TOOLCHAIN_FILE` is set to
76 `yourVcpkgDir\scripts\buildsystems\vcpkg.cmake` (where `yourVcpkgDir` here is
77 the exported directory you extract), **and also** set `VCPKG_MANIFEST_MODE` to
78 `OFF`. Because exported dependencies from vcpkg do not include the vcpkg tool
79 binary itself (or the port files, etc), we can't use manifest mode and must
80 disable it. Instead, Monado will build against the dependencies installed in
81 your exported tree. Open a Visual Studio Developer PowerShell terminal to your
82 source dir before following one of the following two sections to generate your
83 build tree.
84 - Without the vcpkg command-line tool, there's no "integrate" to let VS
85 automatically know to take these steps, so you'll have to manually set the
86 CMake variables in `CMakeSettings.json`. (VS has a GUI editor for it.)
87 - On the CMake command line, this means passing something like
88 `"-DCMAKE_TOOLCHAIN_FILE=yourVcpkgDir\scripts\buildsystems\vcpkg.cmake" -DVCPKG_MANIFEST_MODE=OFF`
89 (quotation marks possibly required depending on your shell).
90
91For either of them, you may choose to add
92`"-DCMAKE_INSTALL_PREFIX=w:\someplace\else"` (with a path of your choice) to set
93where to "install" to, if you don't want to run out of the build tree.
94
95### Sample batch file for build
96
97This assumes that you have a full clone of vcpkg in `w:\vcpkg` and want to build
98on the command line, using the Visual Studio 2019 build tools.
99
100```bat
101@setlocal
102
103@rem Set up environment for build
104call "C:\Program Files (x86)\Microsoft Visual Studio\2019\BuildTools\VC\Auxiliary\Build\vcvars64.bat"
105
106@rem Change current directory
107w:
108cd "w:\src\monado"
109
110cmake -S . ^
111 -B build
112 -G Ninja ^
113 -DCMAKE_BUILD_TYPE="Release" ^
114 -DCMAKE_TOOLCHAIN_FILE="w:\vcpkg\scripts\buildsystems\vcpkg.cmake"
115
116ninja -C build
117```
118
119If you want to build the `outOfProcess` version of Monado, please add extra
120build parameter `-DXRT_FEATURE_SERVICE=ON`.
121
122## Using
123
124### Run Monado service
125
126If you build the `outOfProcess` version of Monado, you need to start
127the `monado-service.exe` first with the following command in `cmd.exe`
128command prompt before running OpenXR clients:
129
130```bat
131monado-service.exe
132```
133
134or the following in PowerShell:
135
136```pwsh
137.\monado-service.exe
138```
139
140If you build the `inProcess` version of Monado, you don't need the above
141steps, and you can jump to the next section to run OpenXR clients directly.
142
143### Run hello_xr
144
145Proper install of a runtime in Windows involves registry modifications. However,
146the easiest way to test is just to set the `XR_RUNTIME_JSON` environment
147variable (in a command prompt/powershell where you will launch the app) to the
148generated JSON manifest file. Assuming you have a terminal open to the directory
149where `hello_xr.exe` is, you can run the following in `cmd.exe` command prompt,
150changing path as required:
151
152```bat
153@rem May have the build type as an additional directory if using a multi-config generator
154set XR_RUNTIME_JSON=w:\src\monado\build\openxr_monado-dev.json
155hello_xr.exe -G Vulkan
156```
157
158or the following in PowerShell:
159
160```pwsh
161$env:XR_RUNTIME_JSON="w:\src\monado\build\openxr_monado-dev.json"
162.\hello_xr.exe -G Vulkan
163```
164
165## Limitations
166
167Note that there are current limitations in the Windows build.
168The main one currently is no actual headset drivers yet, partially because
169some USB stuff needs porting, and partially because direct mode on Windows
170is more complicated.