1# Build Instructions 2 3Instructions for building this repository on Linux, Windows, and MacOS. 4 5## Table Of Contents 6 7- [Build Instructions](#build-instructions) 8 - [Table Of Contents](#table-of-contents) 9 - [Contributing to the Repository](#contributing-to-the-repository) 10 - [Repository Content](#repository-content) 11 - [Installed Files](#installed-files) 12 - [Build Requirements](#build-requirements) 13 - [Test Requirements](#test-requirements) 14 - [Repository Set-Up](#repository-set-up) 15 - [Display Drivers](#display-drivers) 16 - [Repository Dependencies](#repository-dependencies) 17 - [Vulkan-Headers](#vulkan-headers) 18 - [Test Dependencies](#test-dependencies) 19 - [Build and Install Directory Locations](#build-and-install-directory-locations) 20 - [Building Dependent Repositories with Known-Good Revisions](#building-dependent-repositories-with-known-good-revisions) 21 - [Automatically](#automatically) 22 - [Manually](#manually) 23 - [Notes About the Manual Option](#notes-about-the-manual-option) 24 - [Generated source code](#generated-source-code) 25 - [Build Options](#build-options) 26 - [Building On Windows](#building-on-windows) 27 - [Windows Development Environment Requirements](#windows-development-environment-requirements) 28 - [Windows Build - Microsoft Visual Studio](#windows-build---microsoft-visual-studio) 29 - [Windows Quick Start](#windows-quick-start) 30 - [Use `CMake` to Create the Visual Studio Project Files](#use-cmake-to-create-the-visual-studio-project-files) 31 - [Build the Solution From the Command Line](#build-the-solution-from-the-command-line) 32 - [Build the Solution With Visual Studio](#build-the-solution-with-visual-studio) 33 - [Windows Install Target](#windows-install-target) 34 - [Building On Linux](#building-on-linux) 35 - [Linux Development Environment Requirements](#linux-development-environment-requirements) 36 - [Required Package List](#required-package-list) 37 - [Linux Build](#linux-build) 38 - [Linux Quick Start](#linux-quick-start) 39 - [Use CMake to Create the Make Files](#use-cmake-to-create-the-make-files) 40 - [Build the Project](#build-the-project) 41 - [Linux Notes](#linux-notes) 42 - [WSI Support Build Options](#wsi-support-build-options) 43 - [Linux Install to System Directories](#linux-install-to-system-directories) 44 - [Linux 32-bit support](#linux-32-bit-support) 45 - [Building on MacOS](#building-on-macos) 46 - [MacOS Development Environment Requirements](#macos-development-environment-requirements) 47 - [Clone the Repository](#clone-the-repository) 48 - [MacOS build](#macos-build) 49 - [Building with the Unix Makefiles Generator](#building-with-the-unix-makefiles-generator) 50 - [Building with the Xcode Generator](#building-with-the-xcode-generator) 51 - [Building on Fuchsia](#building-on-fuchsia) 52 - [SDK Symbols](#sdk-symbols) 53 - [Building on QNX](#building-on-qnx) 54 - [Cross Compilation](#cross-compilation) 55 - [Unknown function handling which requires explicit assembly implementations](#unknown-function-handling-which-requires-explicit-assembly-implementations) 56 - [Platforms which fully support unknown function handling](#platforms-which-fully-support-unknown-function-handling) 57 - [Link Time Optimization](#link-time-optimization) 58 - [Tests](#tests) 59 60 61## Contributing to the Repository 62 63If you intend to contribute, the preferred work flow is for you to develop 64your contribution in a fork of this repository in your GitHub account and then 65submit a pull request. Please see the [CONTRIBUTING.md](CONTRIBUTING.md) file 66in this repository for more details. 67 68## Repository Content 69 70This repository contains the source code necessary to build the desktop Vulkan 71loader and its tests. 72 73### Installed Files 74 75The `install` target installs the following files under the directory 76indicated by *install_dir*: 77 78- *install_dir*`/lib` : The Vulkan loader library 79- *install_dir*`/bin` : The Vulkan loader library DLL (Windows) 80 81## Build Requirements 82 831. `C99` capable compiler 842. `CMake` version 3.17.2 or greater 853. `Git` 86 87### Test Requirements 88 891. `C++17` capable compiler 90 91## Repository Set-Up 92 93### Display Drivers 94 95This repository does not contain a Vulkan-capable driver. You will need to 96obtain and install a Vulkan driver from your graphics hardware vendor or from 97some other suitable source if you intend to run Vulkan applications. 98 99 100### Repository Dependencies 101 102This repository attempts to resolve some of its dependencies by using 103components found from the following places, in this order: 104 1051. CMake or Environment variable overrides (e.g., -D VULKAN_HEADERS_INSTALL_DIR) 1062. System-installed packages, mostly applicable on Linux 107 108Dependencies that cannot be resolved by the SDK or installed packages must be 109resolved with the "install directory" override and are listed below. The 110"install directory" override can also be used to force the use of a specific 111version of that dependency. 112 113#### Vulkan-Headers 114 115This repository has a required dependency on the [Vulkan Headers repository](https://github.com/KhronosGroup/Vulkan-Headers). 116The Vulkan-Headers repository contains the Vulkan API definition files that are 117required to build the loader. 118 119#### Test Dependencies 120 121The loader tests depend on the [Google Test](https://github.com/google/googletest) library and 122on Windows platforms depends on the [Microsoft Detours](https://github.com/microsoft/Detours) library. 123 124To build the tests, pass both `-D UPDATE_DEPS=ON` and `-D BUILD_TESTS=ON` options when generating the project: 125```bash 126cmake ... -D UPDATE_DEPS=ON -D BUILD_TESTS=ON ... 127``` 128This will ensure googletest and detours is downloaded and the appropriate version is used. 129 130### Warnings as errors off by default! 131 132By default `BUILD_WERROR` is `OFF`. The idiom for open source projects is to NOT enable warnings as errors. 133 134System/language package managers have to build on multiple different platforms and compilers. 135 136By defaulting to `ON` we cause issues for package managers since there is no standard way to disable warnings. 137 138Add `-D BUILD_WERROR=ON` to your workflow 139 140### Build and Install Directory Locations 141 142A common convention is to place the `build` directory in the top directory of 143the repository and place the `install` directory as a child of the `build` 144directory. The remainder of these instructions follow this convention, 145although you can place these directories in any location. 146 147### Building Dependent Repositories with Known-Good Revisions 148 149There is a Python utility script, `scripts/update_deps.py`, that you can use 150to gather and build the dependent repositories mentioned above. 151This program uses information stored in the `scripts/known-good.json` file 152to checkout dependent repository revisions that are known to be compatible with 153the revision of this repository that you currently have checked out. 154 155You can choose to do this automatically or manually. 156The first step to either is cloning the Vulkan-Loader repo and stepping into 157that newly cloned folder: 158 159``` 160 git clone git@github.com:KhronosGroup/Vulkan-Loader.git 161 cd Vulkan-Loader 162``` 163 164#### Automatically 165 166On the other hand, if you choose to let the CMake scripts do all the 167heavy-lifting, you may just trigger the following CMake commands: 168 169``` 170 cmake -S . -B build -D UPDATE_DEPS=On 171 cmake --build build 172``` 173 174#### Manually 175 176To manually update the dependencies you now must create the build folder, and 177run the update deps script followed by the necessary CMake build commands: 178 179``` 180 mkdir build 181 cd build 182 python ../scripts/update_deps.py 183 cmake -C helper.cmake .. 184 cmake --build . 185``` 186 187##### Notes About the Manual Option 188 189- You may need to adjust some of the CMake options based on your platform. See 190 the platform-specific sections later in this document. 191- The `update_deps.py` script fetches and builds the dependent repositories in 192 the current directory when it is invoked. 193- The `--dir` option for `update_deps.py` can be used to relocate the 194 dependent repositories to another arbitrary directory using an absolute or 195 relative path. 196- The `update_deps.py` script generates a file named `helper.cmake` and places 197 it in the same directory as the dependent repositories. 198 This file contains CMake commands to set the CMake `*_INSTALL_DIR` variables 199 that are used to point to the install artifacts of the dependent repositories. 200 The `-C helper.cmake` option is used to set these variables when you generate 201 the build files. 202- If using "MINGW" (Git For Windows), you may wish to run 203 `winpty update_deps.py` in order to avoid buffering all of the script's 204 "print" output until the end and to retain the ability to interrupt script 205 execution. 206- Please use `update_deps.py --help` to list additional options and read the 207 internal documentation in `update_deps.py` for further information. 208 209### Generated source code 210 211This repository contains generated source code in the `loader/generated` 212directory which is not intended to be modified directly. 213Instead, changes should be made to the corresponding generator in the `scripts` directory. 214The source files can then be regenerated using `scripts/generate_source.py`. 215 216Run `python scripts/generate_source.py --help` to see how to invoke it. 217 218A helper CMake target `loader_codegen` is also provided to simplify the invocation of `scripts/generate_source.py`. 219 220Note: By default this helper target is disabled. To enable it, add `-D LOADER_CODEGEN=ON` 221to CMake, as shown below. 222 223``` 224cmake -S . -B build -D LOADER_CODEGEN=ON 225cmake --build . --target loader_codegen 226``` 227 228### Build Options 229 230When generating build files through CMake, several options can be specified to 231customize the build. 232The following is a table of all on/off options currently supported by this repository: 233 234| Option | Platform | Default | Description | 235| ------------------------------- | ------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | 236| BUILD_TESTS | All | `OFF` | Controls whether or not the loader tests are built. | 237| BUILD_WSI_XCB_SUPPORT | Linux | `ON` | Build the loader with the XCB entry points enabled. Without this, the XCB headers should not be needed, but the extension `VK_KHR_xcb_surface` won't be available. | 238| BUILD_WSI_XLIB_SUPPORT | Linux | `ON` | Build the loader with the Xlib entry points enabled. Without this, the X11 headers should not be needed, but the extension `VK_KHR_xlib_surface` won't be available. | 239| BUILD_WSI_WAYLAND_SUPPORT | Linux | `ON` | Build the loader with the Wayland entry points enabled. Without this, the Wayland headers should not be needed, but the extension `VK_KHR_wayland_surface` won't be available. | 240| BUILD_WSI_DIRECTFB_SUPPORT | Linux | `OFF` | Build the loader with the DirectFB entry points enabled. Without this, the DirectFB headers should not be needed, but the extension `VK_EXT_directfb_surface` won't be available. | 241| BUILD_WSI_SCREEN_QNX_SUPPORT | QNX | `OFF` | Build the loader with the QNX Screen entry points enabled. Without this the extension `VK_QNX_screen_surface` won't be available. | 242| ENABLE_WIN10_ONECORE | Windows | `OFF` | Link the loader to the [OneCore](https://msdn.microsoft.com/en-us/library/windows/desktop/mt654039.aspx) umbrella library, instead of the standard Win32 ones. | 243| USE_GAS | Linux | `ON` | Controls whether to build assembly files with the GNU assembler, else fallback to C code. | 244| USE_MASM | Windows | `ON` | Controls whether to build assembly files with MS assembler, else fallback to C code | 245| LOADER_ENABLE_ADDRESS_SANITIZER | Linux & macOS | `OFF` | Enables Address Sanitizer in the loader and tests. | 246| LOADER_ENABLE_THREAD_SANITIZER | Linux & macOS | `OFF` | Enables Thread Sanitizer in the loader and tests. | 247| LOADER_USE_UNSAFE_FILE_SEARCH | All | `OFF` | Disables security policies that prevent unsecure locations from being used when running with elevated permissions. | 248| LOADER_CODEGEN | All | `OFF` | Creates a helper CMake target to generate code. | 249 250NOTE: `LOADER_USE_UNSAFE_FILE_SEARCH` should NOT be enabled except in very specific contexts (like isolated test environments)! 251 252The following is a table of all string options currently supported by this repository: 253 254| Option | Platform | Default | Description | 255| --------------------- | ----------- | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | 256| FALLBACK_CONFIG_DIRS | Linux/MacOS | `/etc/xdg` | Configuration path(s) to use instead of `XDG_CONFIG_DIRS` if that environment variable is unavailable. The default setting is freedesktop compliant. | 257| FALLBACK_DATA_DIRS | Linux/MacOS | `/usr/local/share:/usr/share` | Configuration path(s) to use instead of `XDG_DATA_DIRS` if that environment variable is unavailable. The default setting is freedesktop compliant. | 258| BUILD_DLL_VERSIONINFO | Windows | `""` (empty string) | Allows setting the Windows specific version information for the Loader DLL. Format is "major.minor.patch.build". | 259 260These variables should be set using the `-D` option when invoking CMake to generate the native platform files. 261 262## Building On Windows 263 264### Windows Development Environment Requirements 265 266- Windows 267 - Any Personal Computer version supported by Microsoft 268- Microsoft [Visual Studio](https://www.visualstudio.com/) 269 - Versions 270 - [2022](https://www.visualstudio.com/vs/downloads/) 271 - [2019](https://www.visualstudio.com/vs/older-downloads/) 272 - The Community Edition of each of the above versions is sufficient, as 273 well as any more capable edition. 274- [CMake 3.17.2](https://cmake.org/files/v3.17/cmake-3.17.2-win64-x64.zip) is recommended. 275 - Use the installer option to add CMake to the system PATH 276- Git Client Support 277 - [Git for Windows](http://git-scm.com/download/win) is a popular solution 278 for Windows 279 - Some IDEs (e.g., [Visual Studio](https://www.visualstudio.com/), 280 [GitHub Desktop](https://desktop.github.com/)) have integrated 281 Git client support 282 283### Windows Build - Microsoft Visual Studio 284 285The general approach is to run CMake to generate the Visual Studio project 286files. Then either run CMake with the `--build` option to build from the 287command line or use the Visual Studio IDE to open the generated solution and 288work with the solution interactively. 289 290#### Windows Quick Start 291 292Open a developer command prompt and enter: 293 294 cd Vulkan-Loader 295 mkdir build 296 cd build 297 cmake -A x64 -D UPDATE_DEPS=ON .. 298 cmake --build . 299 300The above commands instruct CMake to find and use the default Visual Studio 301installation to generate a Visual Studio solution and projects for the x64 302architecture. The second CMake command builds the Debug (default) 303configuration of the solution. 304 305#### Use `CMake` to Create the Visual Studio Project Files 306 307Change your current directory to the top of the cloned repository directory, 308create a build directory and generate the Visual Studio project files: 309 310 cd Vulkan-Loader 311 mkdir build 312 cd build 313 cmake -D UPDATE_DEPS=ON -G "Visual Studio 16 2019" -A x64 .. 314 315> Note: The `..` parameter tells `cmake` the location of the top of the 316> repository. If you place your build directory someplace else, you'll need to 317> specify the location of the repository differently. 318 319The `-G` option is used to select the generator 320 321Supported Visual Studio generators: 322* `Visual Studio 17 2022` 323* `Visual Studio 16 2019` 324 325The `-A` option is used to select either the "Win32", "x64", or "ARM64 architecture. 326 327When generating the project files, the absolute path to a Vulkan-Headers 328install directory must be provided. This can be done automatically by the 329`-D UPDATE_DEPS=ON` option, by directly setting the 330`VULKAN_HEADERS_INSTALL_DIR` environment variable, or by setting the 331`VULKAN_HEADERS_INSTALL_DIR` CMake variable with the `-D` CMake option. In 332either case, the variable should point to the installation directory of a 333Vulkan-Headers repository built with the install target. 334 335The above steps create a Windows solution file named `Vulkan-Loader.sln` in 336the build directory. 337 338At this point, you can build the solution from the command line or open the 339generated solution with Visual Studio. 340 341#### Build the Solution From the Command Line 342 343While still in the build directory: 344 345 cmake --build . 346 347to build the Debug configuration (the default), or: 348 349 cmake --build . --config Release 350 351to make a Release build. 352 353#### Build the Solution With Visual Studio 354 355Launch Visual Studio and open the "Vulkan-Loader.sln" solution file in the 356build folder. You may select "Debug" or "Release" from the Solution 357Configurations drop-down list. Start a build by selecting the Build->Build 358Solution menu item. 359 360#### Windows Install Target 361 362The CMake project also generates an "install" target that you can use to copy 363the primary build artifacts to a specific location using a "bin, include, lib" 364style directory structure. This may be useful for collecting the artifacts and 365providing them to another project that is dependent on them. 366 367The default location is `$CMAKE_CURRENT_BINARY_DIR\install`, but can be changed 368with the `CMAKE_INSTALL_PREFIX` variable when first generating the project build 369files with CMake. 370 371You can build the install target from the command line with: 372 373 cmake --build . --config Release --target install 374 375or build the `INSTALL` target from the Visual Studio solution explorer. 376 377## Building On Linux 378 379### Linux Development Environment Requirements 380 381This repository has been built and tested on the two most recent Ubuntu LTS 382versions, although earlier versions may work. 383It is be straightforward to adapt this repository to other Linux distributions. 384 385[CMake 3.17.2](https://cmake.org/files/v3.17/cmake-3.17.2-Linux-x86_64.tar.gz) is recommended. 386 387#### Required Package List 388 389 sudo apt-get install git build-essential libx11-xcb-dev \ 390 libxkbcommon-dev libwayland-dev libxrandr-dev 391 392### Linux Build 393 394The general approach is to run CMake to generate make files. Then either run 395CMake with the `--build` option or `make` to build from the command line. 396 397#### Linux Quick Start 398 399 cd Vulkan-Loader 400 mkdir build 401 cd build 402 cmake -D UPDATE_DEPS=ON .. 403 make 404 405See below for the details. 406 407#### Use CMake to Create the Make Files 408 409Change your current directory to the top of the cloned repository directory, 410create a build directory and generate the make files. 411 412 cd Vulkan-Loader 413 mkdir build 414 cd build 415 cmake -D CMAKE_BUILD_TYPE=Debug \ 416 -D VULKAN_HEADERS_INSTALL_DIR=absolute_path_to_install_dir \ 417 -D CMAKE_INSTALL_PREFIX=install .. 418 419> Note: The `..` parameter tells `cmake` the location of the top of the 420> repository. If you place your `build` directory someplace else, you'll need 421> to specify the location of the repository top differently. 422 423Use `-D CMAKE_BUILD_TYPE` to specify a Debug or Release build. 424 425When generating the project files, the absolute path to a Vulkan-Headers 426install directory must be provided. This can be done automatically by the 427`-D UPDATE_DEPS=ON` option, by directly setting the `VULKAN_HEADERS_INSTALL_DIR` 428environment variable, or by setting the `VULKAN_HEADERS_INSTALL_DIR` CMake 429variable with the `-D` CMake option. 430In either case, the variable should point to the installation directory of a 431Vulkan-Headers repository built with the install target. 432 433> Note: For Linux, the default value for `CMAKE_INSTALL_PREFIX` is 434> `/usr/local`, which would be used if you do not specify 435> `CMAKE_INSTALL_PREFIX`. In this case, you may need to use `sudo` to install 436> to system directories later when you run `make install`. 437 438#### Build the Project 439 440You can just run `make` to begin the build. 441 442To speed up the build on a multi-core machine, use the `-j` option for `make` 443to specify the number of cores to use for the build. For example: 444 445 make -j4 446 447You can also use 448 449 cmake --build . 450 451### Linux Notes 452 453#### WSI Support Build Options 454 455By default, the Vulkan Loader is built with support for the Vulkan-defined WSI 456display servers: Xcb, Xlib, and Wayland. It is recommended to build the 457repository components with support for these display servers to maximize their 458usability across Linux platforms. If it is necessary to build these modules 459without support for one of the display servers, the appropriate CMake option 460of the form `BUILD_WSI_xxx_SUPPORT` can be set to `OFF`. 461 462#### Linux Install to System Directories 463 464Installing the files resulting from your build to the systems directories is 465optional since environment variables can usually be used instead to locate the 466binaries. There are also risks with interfering with binaries installed by 467packages. If you are certain that you would like to install your binaries to 468system directories, you can proceed with these instructions. 469 470Assuming that you've built the code as described above and the current 471directory is still `build`, you can execute: 472 473 sudo make install 474 475This command installs files to `/usr/local` if no `CMAKE_INSTALL_PREFIX` is 476specified when creating the build files with CMake: 477 478- `/usr/local/lib`: Vulkan loader library and package config files 479 480You may need to run `ldconfig` in order to refresh the system loader search 481cache on some Linux systems. 482 483You can further customize the installation location by setting additional 484CMake variables to override their defaults. For example, if you would like to 485install to `/tmp/build` instead of `/usr/local`, on your CMake command line 486specify: 487 488 -D CMAKE_INSTALL_PREFIX=/tmp/build 489 490Then run `make install` as before. The install step places the files in 491`/tmp/build`. This may be useful for collecting the artifacts and providing 492them to another project that is dependent on them. 493 494Using the `CMAKE_INSTALL_PREFIX` to customize the install location also 495modifies the loader search paths to include searching for layers in the 496specified install location. In this example, setting `CMAKE_INSTALL_PREFIX` to 497`/tmp/build` causes the loader to search 498`/tmp/build/etc/vulkan/explicit_layer.d` and 499`/tmp/build/share/vulkan/explicit_layer.d` for the layer JSON files. The 500loader also searches the "standard" system locations of 501`/etc/vulkan/explicit_layer.d` and `/usr/share/vulkan/explicit_layer.d` after 502searching the two locations under `/tmp/build`. 503 504You can further customize the installation directories by using the CMake 505variables `CMAKE_INSTALL_SYSCONFDIR` to rename the `etc` directory and 506`CMAKE_INSTALL_DATADIR` to rename the `share` directory. 507 508See the CMake documentation for more details on using these variables to 509further customize your installation. 510 511Also see the `LoaderInterfaceArchitecture.md` document in the `docs` folder in this 512repository for more information about loader operation. 513 514#### Linux 32-bit support 515 516The loader supports building in 32-bit Linux environments. 517However, it is not nearly as straightforward as it is for Windows. 518Here are some notes for building this repo as 32-bit on a 64-bit Ubuntu 519"reference" platform: 520 521If not already installed, install the following 32-bit development libraries: 522 523`gcc-multilib gcc-multilib g++-multilib libc6:i386 libc6-dev-i386 libgcc-s1:i386 libwayland-dev:i386 libxrandr-dev:i386` 524 525This list may vary depending on your distribution and which windowing systems 526you are building for. 527 528Set up your environment for building 32-bit targets: 529 530 export CFLAGS=-m32 531 export CXXFLAGS=-m32 532 export LDFLAGS=-m32 533 export ASFLAGS=--32 534 535Your PKG_CONFIG configuration may be different, depending on your distribution. 536 537Finally, build the repository normally as explained above. 538 539These notes are taken from the Github Actions workflow `linux-32` which is run 540regularly as a part of CI. 541 542## Building on MacOS 543 544### MacOS Development Environment Requirements 545 546Setup Homebrew and components 547 548- Ensure Homebrew is at the beginning of your PATH: 549 550 export PATH=/usr/local/bin:$PATH 551 552- Add packages with the following (may need refinement) 553 554 brew install python python3 git 555 556### Clone the Repository 557 558Clone the Vulkan-Loader repository: 559 560 git clone https://github.com/KhronosGroup/Vulkan-Loader.git 561 562### MacOS build 563 564[CMake 3.17.2](https://cmake.org/files/v3.17/cmake-3.17.2-Darwin-x86_64.tar.gz) is recommended. 565 566#### Building with the Unix Makefiles Generator 567 568This generator is the default generator. 569 570When generating the project files, the absolute path to a Vulkan-Headers 571install directory must be provided. This can be done automatically by the 572`-D UPDATE_DEPS=ON` option, by directly setting the 573`VULKAN_HEADERS_INSTALL_DIR` environment variable, or by setting the 574`VULKAN_HEADERS_INSTALL_DIR` CMake variable with the `-D` CMake option. In 575either case, the variable should point to the installation directory of a 576Vulkan-Headers repository built with the install target. 577 578 mkdir build 579 cd build 580 cmake -D UPDATE_DEPS=ON -D VULKAN_HEADERS_INSTALL_DIR=absolute_path_to_install_dir -D CMAKE_BUILD_TYPE=Debug .. 581 make 582 583To speed up the build on a multi-core machine, use the `-j` option for `make` 584to specify the number of cores to use for the build. For example: 585 586 make -j4 587 588#### Building with the Xcode Generator 589 590To create and open an Xcode project: 591 592 mkdir build-xcode 593 cd build-xcode 594 cmake -GXcode .. 595 open Vulkan-Loader.xcodeproj 596 597Within Xcode, you can select Debug or Release builds in the project's Build 598Settings. 599 600## Building on Fuchsia 601 602Fuchsia uses the project's GN build system to integrate with the Fuchsia platform build. 603 604### SDK Symbols 605 606The Vulkan Loader is a component of the Fuchsia SDK, so it must explicitly declare its exported symbols in 607the file vulkan.symbols.api; see [SDK](https://fuchsia.dev/fuchsia-src/development/sdk). 608 609## Building on QNX 610 611QNX is using its own build system. The proper build environment must be set 612under the QNX host development system (Linux, Win64, MacOS) by invoking 613the shell/batch script provided with QNX installation. 614 615Then change working directory to the "scripts/qnx" in this project and type "make". 616It will build the ICD loader for all CPU targets supported by QNX. 617 618## Cross Compilation 619 620While this repo is capable of cross compilation, there are a handful of caveats. 621 622### Unknown function handling which requires explicit assembly implementations 623 624Unknown function handling is only fully supported on select platforms due to the 625need for assembly in the implementation. 626Platforms not fully supported will have assembly disabled automatically, or 627can be manually disabled by setting `USE_GAS` or `USE_MASM` to `OFF`. 628 629#### Platforms which fully support unknown function handling 630 631* 64 bit Windows (x64) 632* 32 bit Windows (x86) 633* 64 bit Linux (x64) 634* 32 bit Linux (x86) 635* 64 bit Arm (aarch64) 636 637Platforms not listed will use a fallback C Code path that relies on tail-call optimization to work. 638No guarantees are made about the use of the fallback code paths. 639 640### Link Time Optimization 641 642When cross compiling, the use of Link Time Optimization (LTO) and unknown function handling 643is not supported. Either LTO needs to be turned off, or the assembly should be disabled. 644 645## Tests 646 647To build tests, make sure that the `BUILD_TESTS` option is set to true. Using 648the command line, this looks like `-D BUILD_TESTS=ON`. 649 650This project is configured to run with `ctest`, which makes it easy to run the 651tests. To run the tests, change the directory to that of the build direction, and 652execute `ctest`. 653 654More details can be found in the [README.md](./tests/README.md) for the tests 655directory of this project. 656