BUILD.md

   1 # Build Instructions
   2
   3 1. [Requirements](#requirements)
   4 1. [Building Overview](#building-overview)
   5 1. [Generated source code](#generated-source-code)
   6 1. [Dependencies](#dependencies)
   7 1. [Linux Build](#building-on-linux)
   8 1. [Windows Build](#building-on-windows)
   9 1. [MacOS build](#building-on-macos)
  10 1. [Android Build](#building-for-android)
  11 1. [Installed Files](#installed-files)
  12
  13 ## Requirements
  14
  15 1. CMake >= 3.17.2
  16 1. C++17 compatible toolchain
  17 1. Git
  18 1. Python >= 3.10
  19
  20 NOTE: Python is needed for working on generated code, and helping grab dependencies.
  21 While it's not technically required, it's practically required for most users.
  22
  23 ### Generated source code
  24
  25 This repository contains generated source code which is not intended to be modified directly.
  26
  27 A helper CMake target `tools_codegen` is also provided to simplify the invocation of `scripts/generate_source.py` from the build directory:
  28
  29 ```bash
  30 cmake -S . -B build -D TOOLS_CODEGEN=ON
  31 cmake --build build --target tools_codegen
  32 ```
  33
  34 NOTE: `TOOLS_CODEGEN` is `OFF` by default.
  35
  36 ## Building Overview
  37
  38 The following will be enough for most people, for more detailed instructions, see below.
  39
  40 ```bash
  41 git clone https://github.com/KhronosGroup/Vulkan-Tools.git
  42 cd Vulkan-Tools
  43
  44 cmake -S . -B build -D UPDATE_DEPS=ON -D BUILD_WERROR=ON -D BUILD_TESTS=ON -D CMAKE_BUILD_TYPE=Debug
  45 cmake --build build --config Debug
  46 ```
  47
  48 ### Warnings as errors off by default!
  49
  50 By default `BUILD_WERROR` is `OFF`. The idiom for open source projects is to NOT enable warnings as errors.
  51
  52 System/language package managers have to build on multiple different platforms and compilers.
  53
  54 By defaulting to `ON` we cause issues for package managers since there is no standard way to disable warnings until CMake 3.24
  55
  56 Add `-D BUILD_WERROR=ON` to your workflow. Or use the `dev` preset shown below which will also enabling warnings as errors.
  57
  58 ## Dependencies
  59
  60 Currently this repo has a custom process for grabbing C/C++ dependencies.
  61
  62 Keep in mind this repo predates tools like `vcpkg`, `conan`, etc. Our process is most similar to `vcpkg`.
  63
  64 By specifying `-D UPDATE_DEPS=ON` when configuring CMake we grab dependencies listed in [known_good.json](scripts/known_good.json).
  65
  66 All we are doing is streamlining `building`/`installing` the `known good` dependencies and helping CMake `find` the dependencies.
  67
  68 This is done via a combination of `Python` and `CMake` scripting.
  69
  70 Misc Useful Information:
  71
  72 - By default `UPDATE_DEPS` is `OFF`. The intent is to be friendly by default to system/language package managers.
  73 - You can run `update_deps.py` manually but it isn't recommended for most users.
  74
  75 ### How to test new dependency versions
  76
  77 Typically most developers alter `known_good.json` with the commit/branch they are testing.
  78
  79 Alternatively you can modify `CMAKE_PREFIX_PATH` as follows.
  80
  81 ```sh
  82 # Delete the CMakeCache.txt which will cache find_* results
  83 rm  -rf build/
  84 cmake -S . -B build/ ... -D CMAKE_PREFIX_PATH=~/foobar/vulkan_headers_install/ ...
  85 ```
  86
  87 ## Building On Linux
  88
  89 ### Linux Build Requirements
  90
  91 This repository is regularly built and tested on the two most recent Ubuntu LTS versions.
  92
  93 ```bash
  94 sudo apt-get install git build-essential python3 cmake
  95
  96 # Linux WSI system libraries
  97 sudo apt-get install libwayland-dev xorg-dev
  98 ```
  99
 100 ### WSI Support Build Options
 101
 102 By default, the repository components are built with support for the
 103 Vulkan-defined WSI display servers: Xcb, Xlib, and Wayland. It is recommended
 104 to build the repository components with support for these display servers to
 105 maximize their usability across Linux platforms. If it is necessary to build
 106 these modules without support for one of the display servers, the appropriate
 107 CMake option of the form `BUILD_WSI_xxx_SUPPORT` can be set to `OFF`.
 108
 109 ### Linux 32-bit support
 110
 111 Usage of this repository's contents in 32-bit Linux environments is not
 112 officially supported. However, since this repository is supported on 32-bit
 113 Windows, these modules should generally work on 32-bit Linux.
 114
 115 Here are some notes for building 32-bit targets on a 64-bit Ubuntu "reference"
 116 platform:
 117
 118 ```bash
 119 # 32-bit libs
 120 # your PKG_CONFIG configuration may be different, depending on your distribution
 121 sudo apt-get install gcc-multilib g++-multilib libx11-dev:i386
 122 ```
 123
 124 Set up your environment for building 32-bit targets:
 125
 126 ```bash
 127 export ASFLAGS=--32
 128 export CFLAGS=-m32
 129 export CXXFLAGS=-m32
 130 export PKG_CONFIG_LIBDIR=/usr/lib/i386-linux-gnu
 131 ```
 132
 133 ## Building On Windows
 134
 135 ### Windows Development Environment Requirements
 136
 137 - Windows 10+
 138 - Visual Studio
 139
 140 Note: Anything less than `Visual Studio 2019` is not guaranteed to compile/work.
 141
 142 ### Visual Studio Generator
 143
 144 Run CMake to generate [Visual Studio project files](https://cmake.org/cmake/help/latest/guide/user-interaction/index.html#command-line-g-option).
 145
 146 ```bash
 147 # NOTE: By default CMake picks the latest version of Visual Studio as the default generator.
 148 cmake -S . -B build
 149
 150 # Open the Visual Studio solution
 151 cmake --open build
 152 ```
 153
 154 See the [CMake documentation](https://cmake.org/cmake/help/latest/manual/cmake-generators.7.html#visual-studio-generators) for further information on Visual Studio generators.
 155
 156 NOTE: Windows developers don't have to develop in Visual Studio. Visual Studio just helps streamlining the needed C++ toolchain requirements (compilers, linker, etc).
 157
 158 ## Building on MacOS
 159
 160 ### MacOS Development Environment Requirements
 161
 162 - Xcode
 163
 164 NOTE: MacOS developers don't have to develop in Xcode. Xcode just helps streamlining the needed C++ toolchain requirements (compilers, linker, etc). Similar to Visual Studio on Windows.
 165
 166 ### Xcode Generator
 167
 168 To create and open an Xcode project:
 169
 170 ```bash
 171 # Create the Xcode project
 172 cmake -S . -B build -G Xcode
 173
 174 # Open the Xcode project
 175 cmake --open build
 176 ```
 177
 178 See the [CMake documentation](https://cmake.org/cmake/help/latest/generator/Xcode.html) for further information on the Xcode generator.
 179
 180 ## Building For Android
 181
 182 - CMake 3.21+
 183 - NDK r25+
 184 - Ninja 1.10+
 185 - Android SDK Build-Tools 34.0.0+
 186
 187 ### Android Build Requirements
 188
 189 - Download [Android Studio](https://developer.android.com/studio)
 190 - Install (https://developer.android.com/studio/install)
 191 - From the `Welcome to Android Studio` splash screen, add the following components using the SDK Manager:
 192   - SDK Platforms > Android 8.0 and newer (API Level 26 or higher)
 193   - SDK Tools > Android SDK Build-Tools
 194   - SDK Tools > Android SDK Platform-Tools
 195   - SDK Tools > Android SDK Tools
 196   - SDK Tools > NDK
 197   - SDK Tools > CMake
 198
 199 #### Add Android specifics to environment
 200
 201 NOTE: The following commands are streamlined for Linux but easily transferable to other platforms.
 202 The main intent is setting 2 environment variables and ensuring the NDK and build tools are in the `PATH`.
 203
 204 ```sh
 205 # Set environment variables
 206 # https://github.com/actions/runner-images/blob/main/images/linux/Ubuntu2204-Readme.md#environment-variables-2
 207 export ANDROID_SDK_ROOT=$HOME/Android/Sdk
 208 export ANDROID_NDK_HOME=$ANDROID_SDK_ROOT/ndk/X.Y.Z
 209
 210 # Modify path
 211 export PATH=$ANDROID_SDK_ROOT/build-tools/X.Y.Z:$PATH
 212
 213 # (Optional if you have new enough version of CMake + Ninja)
 214 export PATH=$ANDROID_SDK_ROOT/cmake/3.22.1/bin:$PATH
 215
 216 # Verify SDK build-tools is set correctly
 217 which aapt
 218
 219 # Verify CMake/Ninja are in the path
 220 which cmake
 221 which ninja
 222
 223 # Check apksigner
 224 apksigner --help
 225 ```
 226
 227 Note: If `apksigner` gives a `java: not found` error you do not have Java in your path.
 228
 229 ```bash
 230 # A common way to install on the system
 231 sudo apt install default-jre
 232 ```
 233
 234 ### Android Build
 235
 236 1. Building the binaries (No APK)
 237
 238 Invoking CMake directly to build the binary is relatively simple.
 239
 240 See https://developer.android.com/ndk/guides/cmake#command-line for CMake NDK documentation.
 241
 242 ```sh
 243 # Build release binary for arm64-v8a
 244 cmake -S . -B build \
 245   -D CMAKE_TOOLCHAIN_FILE=$ANDROID_NDK_HOME/build/cmake/android.toolchain.cmake \
 246   -D ANDROID_PLATFORM=26 \
 247   -D CMAKE_ANDROID_ARCH_ABI=arm64-v8a \
 248   -D CMAKE_ANDROID_STL_TYPE=c++_static \
 249   -D ANDROID_USE_LEGACY_TOOLCHAIN_FILE=NO \
 250   -D CMAKE_BUILD_TYPE=Release \
 251   -D UPDATE_DEPS=ON \
 252   -G Ninja
 253
 254 cmake --build build
 255
 256 cmake --install build --prefix build/install
 257 ```
 258
 259 Alternatively users can also use `scripts/android.py` to build the binaries.
 260
 261 ```sh
 262 # Build release binaries for arm64-v8a
 263 python3 scripts/android.py --config Release --app-abi arm64-v8a --app-stl c++_static
 264 ```
 265
 266 `android.py` can also streamline building for multiple ABIs:
 267
 268 ```sh
 269 # Build release binaries for all ABIs
 270 python3 scripts/android.py --config Release --app-abi 'armeabi-v7a arm64-v8a x86 x86_64' --app-stl c++_static
 271 ```
 272
 273 NOTE: The above methods will only build the `vulkaninfo` and `libVkCube`. It won't create an APK.
 274
 275 Furthermore `vulkaninfo` is intended to run as an executable (No APK).
 276
 277 2. Building the VkCube APK
 278
 279 Creating the `VkCube.apk` is a bit of an involved process since it requires running multiple CLI tools after the CMake build has finished.
 280
 281 As a result users are enouraged to use `scripts/android.py` to build the APK.
 282
 283 This script handles wrapping CMake and various Android CLI tools to create the APK for you.
 284
 285 ```sh
 286 # Build a complete APK with debug binaries for all ABIS
 287 python3 scripts/android.py --config Debug --app-abi 'armeabi-v7a arm64-v8a x86 x86_64' --app-stl c++_shared --apk
 288
 289 # Build a clean APK with release binaries for arm64-v8a
 290 python3 scripts/android.py --config Release --app-abi arm64-v8a --app-stl c++_shared --apk --clean
 291 ```
 292
 293 Note: `scripts/android.py` will place the APK in the `build-android/bin` directory.
 294
 295 See [tests/README.md](tests/README.md) for running `VkCube.apk` / `vulkaninfo` on Android.
 296
 297 ### Installed Files
 298
 299 - *install_dir*`/bin` : The `vulkaninfo`, `vkcube` and `vkcubepp` executables
 300
 301 If `INSTALL_ICD` is configured then MockICD will be installed as follows:
 302
 303 For Unix operating systems:
 304
 305 - *install_dir*`/bin` : The Mock ICD
 306 - *install_dir*`/share/vulkan/icd.d` : Mock ICD JSON
 307
 308 For WIN32:
 309
 310 - *install_dir*`/bin` : The Mock ICD and JSON
 311
 312 ### Software Installation
 313
 314 After you have built your project you can install using CMake's install functionality.
 315
 316 CMake Docs:
 317 - [Software Installation Guide](https://cmake.org/cmake/help/latest/guide/user-interaction/index.html#software-installation)
 318 - [CLI for installing a project](https://cmake.org/cmake/help/latest/manual/cmake.1.html#install-a-project)
 319
 320 ```sh
 321 # EX: Installs Release artifacts into `build/install` directory.
 322 # NOTE: --config is only needed for multi-config generators (Visual Studio, Xcode, etc)
 323 cmake --install build/ --config Release --prefix build/install
 324 ```