mirror of
https://gitlab.freedesktop.org/monado/monado.git
synced 2024-12-28 18:46:18 +00:00
doc: Add docs about building on Windows.
This commit is contained in:
Ryan Pavlik
Jakob Bornecrantz
parent
e791f3ea2f
commit
d5768ead81
145
doc/building-on-windows.md
Normal file
145
doc/building-on-windows.md
Normal file
|
|
@ -0,0 +1,145 @@
|
|||
# Building on Windows {#winbuild}
|
||||
|
||||
<!--
|
||||
Copyright 2022, Collabora, Ltd. and the Monado contributors
|
||||
SPDX-License-Identifier: BSL-1.0
|
||||
-->
|
||||
|
||||
Monado has a work-in-progress port to Windows. While it's not ready for
|
||||
widespread usage due to some rough edges and lack of drivers, it does build and
|
||||
can serve as a base for further development.
|
||||
|
||||
## System Dependencies
|
||||
|
||||
Most dependencies for the Windows build on Monado are handled by [vcpkg][].
|
||||
However, some are not installable or usable (in the way we want) through there,
|
||||
so they require separate installation. For each, the command line to install
|
||||
with "winget" (built in to at least Windows 11, and possibly newer builds of
|
||||
Windows 10) and/or [scoop][] are provided below. Use whichever one you are more
|
||||
comfortable with. (Scoop commands may require adding the "extras" bucket.)
|
||||
|
||||
[vcpkg]: https://vcpkg.io
|
||||
[scoop]: https://github.com/ScoopInstaller/Scoop
|
||||
|
||||
- CMake
|
||||
- `winget install Kitware.CMake`
|
||||
- `scoop install cmake`
|
||||
- Recently, bundled with Visual Studio in a path like
|
||||
`C:\Program Files\Microsoft Visual Studio\2022\Community\Common7\IDE\CommonExtensions\Microsoft\CMake\CMake\bin\cmake.exe`
|
||||
which gets added to your PATH in a Visual Studio command prompt/PowerShell.
|
||||
- Python 3.x
|
||||
- `winget install Python.Python.3`
|
||||
- `scoop install python`
|
||||
- Vulkan SDK
|
||||
- `winget install KhronosGroup.VulkanSDK`
|
||||
- `scoop install vulkan`
|
||||
- Ninja (build tool, recommended but not strictly required)
|
||||
- Not available from winget
|
||||
- `scoop install ninja`
|
||||
- Recently, bundled with Visual Studio in a path like
|
||||
`C:\Program Files\Microsoft Visual Studio\2022\Community\Common7\IDE\CommonExtensions\Microsoft\CMake\Ninja\ninja.exe`
|
||||
which gets added to your PATH in a Visual Studio command prompt/PowerShell.
|
||||
|
||||
You will also need Visual Studio. Most current development is happening with
|
||||
2022, though it should also build with 2019. (Work on Monado might meet the
|
||||
requirements for Microsoft's no-charge
|
||||
[Visual Studio Community](https://visualstudio.microsoft.com/vs/community/)
|
||||
license - see the
|
||||
[VS Community License Terms](https://visualstudio.microsoft.com/license-terms/vs2022-ga-community/)
|
||||
and talk to your lawyer if unsure, this is not legal advice.)
|
||||
|
||||
We should be able to build using LLVM/Clang using libc++ instead of the MSVC
|
||||
standard library, but this hasn't been widely tested.
|
||||
|
||||
## Configuring the build tree
|
||||
|
||||
The main points to note are that:
|
||||
|
||||
- If building against a normal clone/checkout of [vcpkg][], make sure that
|
||||
`CMAKE_TOOLCHAIN_FILE` is set to
|
||||
`yourVcpkgDir\scripts\buildsystems\vcpkg.cmake` (substituting `yourVcpkgDir`
|
||||
as appropriate). This will put vcpkg in "manifest mode", and it will build and
|
||||
install the dependencies in `vcpkg.json` (in the source tree) into a directory
|
||||
in the build tree automatically.
|
||||
- If you have run `.\vcpkg integrate install` in your vcpkg directory, this
|
||||
toolchain is added automatically when you "Open Folder" in Visual Studio for
|
||||
a folder containing CMake build scripts. So, in this case, just open the
|
||||
Monado source directory and everything will be set up automatically for you.
|
||||
- On the CMake command line, this means passing something like
|
||||
`"-DCMAKE_TOOLCHAIN_FILE=yourVcpkgDir\scripts\buildsystems\vcpkg.cmake"`
|
||||
(quotation marks possibly required depending on your shell).
|
||||
- If building against "exported" dependencies from a vcpkg install (which can be
|
||||
used to share a build environment easily and reduce build times), you will
|
||||
also need to set `CMAKE_TOOLCHAIN_FILE` is set to
|
||||
`yourVcpkgDir\scripts\buildsystems\vcpkg.cmake` (where `yourVcpkgDir` here is
|
||||
the exported directory you extract), **and also** set `VCPKG_MANIFEST_MODE` to
|
||||
`OFF`. Because exported dependencies from vcpkg do not include the vcpkg tool
|
||||
binary itself (or the port files, etc), we can't use manifest mode and must
|
||||
disable it. Instead, Monado will build against the dependencies installed in
|
||||
your exported tree. Open a Visual Studio Developer PowerShell terminal to your
|
||||
source dir before following one of the following two sections to generate your
|
||||
build tree.
|
||||
- Without the vcpkg command-line tool, there's no "integrate" to let VS
|
||||
automatically know to take these steps, so you'll have to manually set the
|
||||
CMake variables in `CMakeSettings.json`. (VS has a GUI editor for it.)
|
||||
- On the CMake command line, this means passing something like
|
||||
`"-DCMAKE_TOOLCHAIN_FILE=yourVcpkgDir\scripts\buildsystems\vcpkg.cmake" -DVCPKG_MANIFEST_MODE=OFF`
|
||||
(quotation marks possibly required depending on your shell).
|
||||
|
||||
For either of them, you may choose to add
|
||||
`"-DCMAKE_INSTALL_PREFIX=w:\someplace\else"` (with a path of your choice) to set
|
||||
where to "install" to, if you don't want to run out of the build tree.
|
||||
|
||||
### Sample batch file for build
|
||||
|
||||
This assumes that you have a full clone of vcpkg in `w:\vcpkg` and want to build
|
||||
on the command line, using the Visual Studio 2019 build tools.
|
||||
|
||||
```bat
|
||||
@setlocal
|
||||
|
||||
@rem Set up environment for build
|
||||
call "C:\Program Files (x86)\Microsoft Visual Studio\2019\BuildTools\VC\Auxiliary\Build\vcvars64.bat"
|
||||
|
||||
@rem Change current directory
|
||||
w:
|
||||
cd "w:\src\monado"
|
||||
|
||||
cmake -S . ^
|
||||
-b build
|
||||
-G Ninja ^
|
||||
-DCMAKE_BUILD_TYPE="Release" ^
|
||||
-DCMAKE_TOOLCHAIN_FILE="w:\vcpkg\scripts\buildsystems\vcpkg.cmake"
|
||||
|
||||
ninja -C build
|
||||
```
|
||||
|
||||
## Using
|
||||
|
||||
Proper install of a runtime in Windows involves registry modifications. However,
|
||||
the easiest way to test is just to set the `XR_RUNTIME_JSON` environment
|
||||
variable (in a command prompt/powershell where you will launch the app) to the
|
||||
generated JSON manifest file. Assuming you have a terminal open to the directory
|
||||
where `hello_xr.exe` is, you can run the following in `cmd.exe` command prompt,
|
||||
changing path as required:
|
||||
|
||||
```bat
|
||||
@rem May have the build type as an additional directory if using a multi-config generator
|
||||
set XR_RUNTIME_JSON=w:\src\monado\build\openxr_monado-dev.json
|
||||
hello_xr.exe -G Vulkan
|
||||
```
|
||||
|
||||
or the following in PowerShell:
|
||||
|
||||
```pwsh
|
||||
$env:XR_RUNTIME_JSON="w:\src\monado\build\openxr_monado-dev.json"
|
||||
.\hello_xr.exe -G Vulkan
|
||||
|
||||
```
|
||||
|
||||
## Limitations
|
||||
|
||||
Note that there are current limitations in the Windows build. The main one
|
||||
currently is that IPC/service mode is not (yet) supported. There are also no
|
||||
actual headset drivers yet, partially because some USB stuff needs porting, and
|
||||
partially because direct mode on Windows is more complicated.
|
||||
Loading…
Reference in a new issue