Update BUILD.md

Remove references to VS 2015, as it is no longer supported.
Update the build instructions to include UPDATE_DEPS more prominently.
Move mentions of tests to the very end, and to use `ctest`.
Mention Cross Compilation caveats.

1 files changed, 126 insertions, 138 deletions

diff --git a/BUILD.md b/BUILD.md
index 420373a96..d2133cbd8 100644
--- a/BUILD.md
+++ b/BUILD.md
@@ -4,33 +4,64 @@ Instructions for building this repository on Linux, Windows, and MacOS.
 
 ## Table Of Contents
 
-- [Contributing to the Repository](#contributing-to-the-repository)
-- [Repository Content](#repository-content)
-  - [Installed Files](#installed-files)
-- [Repository Set-Up](#repository-set-up)
-  - [Display Drivers](#display-drivers)
-  - [Download the Repository](#download-the-repository)
-  - [Repository Dependencies](#repository-dependencies)
-  - [Build and Install Directories](#build-and-install-directories)
-  - [Building Dependent Repositories with Known-Good Revisions](#building-dependent-repositories-with-known-good-revisions)
-  - [Generated source code](#generated-source-code)
-  - [Build Options](#build-options)
-- [Building On Windows](#building-on-windows)
-  - [Windows Development Environment Requirements](#windows-development-environment-requirements)
-  - [Windows Build - Microsoft Visual Studio](#windows-build---microsoft-visual-studio)
-  - [Windows Notes](#windows-notes)
-    - [CMake Visual Studio Generators](#cmake-visual-studio-generators)
-    - [Using The Vulkan Loader Library in this Repository on Windows](#using-the-vulkan-loader-library-in-this-repository-on-windows)
-- [Building On Linux](#building-on-linux)
-  - [Linux Development Environment Requirements](#linux-development-environment-requirements)
-  - [Linux Build](#linux-build)
-- [Building on MacOS](#building-on-macos)
-  - [MacOS Development Environment Requirements](#macos-development-environment-requirements)
-  - [Clone the Repository](#clone-the-repository)
-  - [MacOS build](#macos-build)
-- [Building on Fuchsia](#building-on-fuchsia)
-- [Building on QNX](#building-on-qnx)
-  - [SDK Symbols](#sdk-symbols)
+- [Build Instructions](#build-instructions)
+  - [Table Of Contents](#table-of-contents)
+  - [Contributing to the Repository](#contributing-to-the-repository)
+  - [Repository Content](#repository-content)
+    - [Installed Files](#installed-files)
+  - [Repository Set-Up](#repository-set-up)
+    - [Display Drivers](#display-drivers)
+    - [Download the Repository](#download-the-repository)
+    - [Repository Dependencies](#repository-dependencies)
+      - [Vulkan-Headers](#vulkan-headers)
+      - [Test Dependencies](#test-dependencies)
+    - [Build and Install Directories](#build-and-install-directories)
+    - [Building Dependent Repositories with Known-Good Revisions](#building-dependent-repositories-with-known-good-revisions)
+      - [Manually](#manually)
+        - [Notes About the Manual Option](#notes-about-the-manual-option)
+      - [Automatically](#automatically)
+        - [Notes About the Automatic Option](#notes-about-the-automatic-option)
+    - [Generated source code](#generated-source-code)
+    - [Build Options](#build-options)
+  - [Building On Windows](#building-on-windows)
+    - [Windows Development Environment Requirements](#windows-development-environment-requirements)
+    - [Windows Build - Microsoft Visual Studio](#windows-build---microsoft-visual-studio)
+      - [Windows Quick Start](#windows-quick-start)
+      - [Use `CMake` to Create the Visual Studio Project Files](#use-cmake-to-create-the-visual-studio-project-files)
+      - [Build the Solution From the Command Line](#build-the-solution-from-the-command-line)
+      - [Build the Solution With Visual Studio](#build-the-solution-with-visual-studio)
+      - [Windows Install Target](#windows-install-target)
+    - [Windows Notes](#windows-notes)
+      - [Using The Vulkan Loader Library in this Repository on Windows](#using-the-vulkan-loader-library-in-this-repository-on-windows)
+  - [Building On Linux](#building-on-linux)
+    - [Linux Development Environment Requirements](#linux-development-environment-requirements)
+      - [Required Package List](#required-package-list)
+    - [Linux Build](#linux-build)
+      - [Linux Quick Start](#linux-quick-start)
+      - [Use CMake to Create the Make Files](#use-cmake-to-create-the-make-files)
+      - [Build the Project](#build-the-project)
+    - [Linux Notes](#linux-notes)
+      - [Using The Vulkan Loader Library in this Repository on Linux](#using-the-vulkan-loader-library-in-this-repository-on-linux)
+      - [WSI Support Build Options](#wsi-support-build-options)
+      - [Linux Install to System Directories](#linux-install-to-system-directories)
+      - [Linux Uninstall](#linux-uninstall)
+      - [Linux 32-bit support](#linux-32-bit-support)
+  - [Building on MacOS](#building-on-macos)
+    - [MacOS Development Environment Requirements](#macos-development-environment-requirements)
+    - [Clone the Repository](#clone-the-repository)
+    - [MacOS build](#macos-build)
+      - [CMake Generators](#cmake-generators)
+      - [Building with the Unix Makefiles Generator](#building-with-the-unix-makefiles-generator)
+      - [Building with the Xcode Generator](#building-with-the-xcode-generator)
+    - [Using the new macOS loader](#using-the-new-macos-loader)
+  - [Building on Fuchsia](#building-on-fuchsia)
+  - [Building on QNX](#building-on-qnx)
+    - [SDK Symbols](#sdk-symbols)
+  - [Cross Compilation](#cross-compilation)
+    - [Unknown function handling which requires explicit assembly implementations](#unknown-function-handling-which-requires-explicit-assembly-implementations)
+      - [Platforms which fully support unknown function handling](#platforms-which-fully-support-unknown-function-handling)
+    - [Link Time Optimization](#link-time-optimization)
+  - [Tests](#tests)
 
 
 ## Contributing to the Repository
@@ -226,11 +257,11 @@ on/off options currently supported by this repository:
 | BUILD_STATIC_LOADER          | macOS    | `OFF`   | This allows the loader to be built as a static library on macOS. Not tested, use at your own risk.                                                                                |
 The following is a table of all string options currently supported by this repository:
 
-| Option                      | Platform    | Default                       | Description                                                                                                                                          |
-| --------------------------- | ----------- | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
-| 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. |
-| 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.   |
-| BUILD_DLL_VERSIONINFO       | Windows     | `""` (empty string)           | Allows setting the Windows specific version information for the Loader DLL. Format is "major.minor.patch.build".                                     |
+| Option                | Platform    | Default                       | Description                                                                                                                                          |
+| --------------------- | ----------- | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 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. |
+| 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.   |
+| BUILD_DLL_VERSIONINFO | Windows     | `""` (empty string)           | Allows setting the Windows specific version information for the Loader DLL. Format is "major.minor.patch.build".                                     |
 
 These variables should be set using the `-D` option when invoking CMake to generate the native platform files.
 
@@ -242,9 +273,8 @@ These variables should be set using the `-D` option when invoking CMake to gener
   - Any Personal Computer version supported by Microsoft
 - Microsoft [Visual Studio](https://www.visualstudio.com/)
   - Versions
-    - [2015](https://www.visualstudio.com/vs/older-downloads/)
-    - [2017](https://www.visualstudio.com/vs/older-downloads/)
-    - [2019](https://www.visualstudio.com/vs/downloads/)
+    - [2022](https://www.visualstudio.com/vs/downloads/)
+    - [2017 & 2019](https://www.visualstudio.com/vs/older-downloads/)
   - The Community Edition of each of the above versions is sufficient, as
     well as any more capable edition.
 - [CMake 3.10.2](https://cmake.org/files/v3.10/cmake-3.10.2-win64-x64.zip) is recommended.
@@ -270,7 +300,7 @@ Open a developer command prompt and enter:
     cd Vulkan-Loader
     mkdir build
     cd build
-    cmake -A x64 -DVULKAN_HEADERS_INSTALL_DIR=absolute_path_to_install_dir ..
+    cmake -A x64 -DUPDATE_DEPS=ON ..
     cmake --build .
 
 The above commands instruct CMake to find and use the default Visual Studio
@@ -278,10 +308,6 @@ installation to generate a Visual Studio solution and projects for the x64
 architecture. The second CMake command builds the Debug (default)
 configuration of the solution.
 
-Note that if you do not wish to use a developer command prompt, you may either
-run either `vcvars64.bat` or `vcvars32.bat` to set the required environment
-variables.
-
 #### Use `CMake` to Create the Visual Studio Project Files
 
 Change your current directory to the top of the cloned repository directory,
@@ -290,26 +316,25 @@ create a build directory and generate the Visual Studio project files:
     cd Vulkan-Loader
     mkdir build
     cd build
-    cmake -A x64 -DVULKAN_HEADERS_INSTALL_DIR=absolute_path_to_install_dir ..
+    cmake -DUPDATE_DEPS=ON -G "Visual Studio 16 2019" -A x64 ..
 
 > Note: The `..` parameter tells `cmake` the location of the top of the
 > repository. If you place your build directory someplace else, you'll need to
-> specify the location of the repository top differently.
-
-The `-A` option is used to select either the "Win32" or "x64" architecture.
+> specify the location of the repository differently.
 
-If a generator for a specific version of Visual Studio is required, you can
-specify it for Visual Studio 2015, for example, with:
+The `-G` option is used to select the generator
 
-    64-bit: -G "Visual Studio 14 2015 Win64"
-    32-bit: -G "Visual Studio 14 2015"
+Supported Visual Studio generators:
+* `Visual Studio 17 2022`
+* `Visual Studio 16 2019`
+* `Visual Studio 15 2017`
 
-See this [list](#cmake-visual-studio-generators) of other possible generators
-for Visual Studio.
+The `-A` option is used to select either the "Win32", "x64", or "ARM64 architecture.
 
 When generating the project files, the absolute path to a Vulkan-Headers
-install directory must be provided. This can be done by setting the
-`VULKAN_HEADERS_INSTALL_DIR` environment variable or by setting the
+install directory must be provided. This can be done automatically by the
+`-DUPDATE_DEPS=ON` option, by directly setting the
+`VULKAN_HEADERS_INSTALL_DIR` environment variable, or by setting the
 `VULKAN_HEADERS_INSTALL_DIR` CMake variable with the `-D` CMake option. In
 either case, the variable should point to the installation directory of a
 Vulkan-Headers repository built with the install target.
@@ -356,48 +381,9 @@ You can build the install target from the command line with:
 
 or build the `INSTALL` target from the Visual Studio solution explorer.
 
-### Windows Tests
-
-The Vulkan-Loader repository contains some simple unit tests for the loader
-but no other test clients.
-
-To run the loader test script, open a Powershell Console, change to the
-`build\tests` directory, and run:
-
-For Release builds:
-
-    .\run_all_tests.ps1
-
-For Debug builds:
-
-    .\run_all_tests.ps1 -Debug
-
-This script will run the following tests:
-
-- `vk_loader_validation_tests`:
-  Vulkan loader handle wrapping, allocation callback, and loader/layer interface tests
-
-You can also change to either `build\tests\Debug` or `build\tests\Release`
-(depending on which one you built) and run the executable tests (`*.exe`)
-files from there.
 
 ### Windows Notes
 
-#### CMake Visual Studio Generators
-
-The chosen generator should match one of the Visual Studio versions that you
-have installed. Generator strings that correspond to versions of Visual Studio
-include:
-
-| Build Platform               | 64-bit Generator              | 32-bit Generator        |
-| ---------------------------- | ----------------------------- | ----------------------- |
-| Microsoft Visual Studio 2015 | "Visual Studio 14 2015 Win64" | "Visual Studio 14 2015" |
-| Microsoft Visual Studio 2017 | "Visual Studio 15 2017 Win64" | "Visual Studio 15 2017" |
-| Microsoft Visual Studio 2019 | "Visual Studio 16 2019"       | "Visual Studio 16 2019" |
-
-Note that with Visual Studio 2019, the architecture will need to be specified with the `-A`
-flag for 64-bit builds.
-
 #### Using The Vulkan Loader Library in this Repository on Windows
 
 Vulkan programs must be able to find and use the Vulkan loader
@@ -407,14 +393,13 @@ directory as the program. The projects in this solution copy the Vulkan loader
 library and the "googletest" libraries to the `build\tests\Debug` or the
 `build\tests\Release` directory, which is where the
 `vk_loader_validation_test.exe` executable is found, depending on what
-configuration you built. (The loader validation tests use the "googletest"
-testing framework.)
+configuration you built.
 
 Other techniques include placing the library in a system folder
 (C:\Windows\System32) or in a directory that appears in the `PATH` environment
 variable.
 
-See the `LoaderAndLayerInterface` document in the `loader` folder in this
+See the documentation in the `docs` folder in this
 repository for more information on how the loader finds driver libraries and
 layer libraries. The document also describes both how ICDs and layers should
 be packaged, and how developers can point to ICDs and layers within their
@@ -425,7 +410,7 @@ builds.
 ### Linux Development Environment Requirements
 
 This repository has been built and tested on the two most recent Ubuntu LTS
-versions. Currently, the oldest supported version is Ubuntu 16.04, meaning
+versions. Currently, the oldest supported version is Ubuntu 18.04, meaning
 that the minimum officially supported C++11 compiler version is GCC 5.4.0,
 although earlier versions may work. It should be straightforward to adapt this
 repository to other Linux distributions.
@@ -447,7 +432,7 @@ CMake with the `--build` option or `make` to build from the command line.
     cd Vulkan-Loader
     mkdir build
     cd build
-    cmake -DVULKAN_HEADERS_INSTALL_DIR=absolute_path_to_install_dir ..
+    cmake -DUPDATE_DEPS=ON ..
     make
 
 See below for the details.
@@ -471,8 +456,9 @@ create a build directory and generate the make files.
 Use `-DCMAKE_BUILD_TYPE` to specify a Debug or Release build.
 
 When generating the project files, the absolute path to a Vulkan-Headers
-install directory must be provided. This can be done by setting the
-`VULKAN_HEADERS_INSTALL_DIR` environment variable or by setting the
+install directory must be provided. This can be done automatically by the
+`-DUPDATE_DEPS=ON` option, by directly setting the
+`VULKAN_HEADERS_INSTALL_DIR` environment variable, or by setting the
 `VULKAN_HEADERS_INSTALL_DIR` CMake variable with the `-D` CMake option. In
 either case, the variable should point to the installation directory of a
 Vulkan-Headers repository built with the install target.
@@ -502,13 +488,7 @@ If your build system supports ccache, you can enable that via CMake option
 
 #### Using The Vulkan Loader Library in this Repository on Linux
 
-The `vk_loader_validation_tests` executable is linked with an RPATH setting to
-allow it to find the Vulkan loader library in the repository's build
-directory. This allows the test executable to run and find this Vulkan loader
-library without installing the loader library to a directory searched by the
-system loader or in the `LD_LIBRARY_PATH`.
-
-If you want to test a Vulkan application that is not built within this
+If you want to run a Vulkan application that is not built within this
 repository with the loader you just built from this repository, you can direct
 the application to load it from your build directory:
 
@@ -587,19 +567,6 @@ To uninstall the files from the system directories, you can execute:
 
     sudo make uninstall
 
-#### Linux Tests
-
-The Vulkan-Loader repository contains some simple unit tests for the loader
-but no other test clients.
-
-To run the loader test script, change to the `build/tests` directory, and run:
-
-    ./run_all_tests.sh
-
-This script will run the following tests:
-
-- `vk_loader_validation_tests`: Vulkan loader handle wrapping, allocation
-  callback, and loader/layer interface tests
 
 #### Linux 32-bit support
 
@@ -676,15 +643,16 @@ this repository are:
 This generator is the default generator.
 
 When generating the project files, the absolute path to a Vulkan-Headers
-install directory must be provided. This can be done by setting the
-`VULKAN_HEADERS_INSTALL_DIR` environment variable or by setting the
+install directory must be provided. This can be done automatically by the
+`-DUPDATE_DEPS=ON` option, by directly setting the
+`VULKAN_HEADERS_INSTALL_DIR` environment variable, or by setting the
 `VULKAN_HEADERS_INSTALL_DIR` CMake variable with the `-D` CMake option. In
 either case, the variable should point to the installation directory of a
 Vulkan-Headers repository built with the install target.
 
     mkdir build
     cd build
-    cmake -DVULKAN_HEADERS_INSTALL_DIR=absolute_path_to_install_dir -DCMAKE_BUILD_TYPE=Debug ..
+    cmake -DUPDATE_DEPS=ON -DVULKAN_HEADERS_INSTALL_DIR=absolute_path_to_install_dir -DCMAKE_BUILD_TYPE=Debug ..
     make
 
 To speed up the build on a multi-core machine, use the `-j` option for `make`
@@ -711,23 +679,6 @@ can direct the application to load it from your build directory:
 
     export DYLD_LIBRARY_PATH=<path to your repository>/build/loader
 
-### MacOS Tests
-
-The Vulkan-Loader repository contains some simple unit tests for the loader
-but no other test clients.
-
-Before you run these tests, you will need to clone and build the
-[MoltenVK](https://github.com/KhronosGroup/MoltenVK) repository.
-
-You will also need to direct your new loader to the MoltenVK ICD:
-
-    export VK_DRIVER_FILES=<path to MoltenVK repository>/Package/Latest/MoltenVK/macOS/MoltenVK_icd.json
-
-To run the loader test script, change to the `build/tests` directory in your
-Vulkan-Loader repository, and run:
-
-    ./vk_loader_validation_tests
-
 ## Building on Fuchsia
 
 Fuchsia uses the project's GN build system to integrate with the Fuchsia platform build.
@@ -745,3 +696,40 @@ It will build the ICD loader for all CPU targets supported by QNX.
 
 The Vulkan Loader is a component of the Fuchsia SDK, so it must explicitly declare its exported symbols in
 the file vulkan.symbols.api; see [SDK](https://fuchsia.dev/fuchsia-src/development/sdk).
+
+## Cross Compilation
+
+While this repo is capable of cross compilation, there are a handful of caveats.
+
+### Unknown function handling which requires explicit assembly implementations
+
+Unknown function handling is only fully supported on select platforms due to the
+need for assembly in the implementation. Other platforms will need to disable
+assembly by setting `USE_GAS` or `USE_MASM` to `OFF`.
+#### Platforms which fully support unknown function handling
+
+* 64 bit Windows (x64)
+* 32 bit Windows (x86)
+* 64 bit Linux (x64)
+* 32 bit Linux (x86)
+* 64 bit Arm (aarch64)
+
+Platforms not listed will use a fallback C Code path that relies on tail-call optimization to work.
+No guarantees are made about the use of the fallback code paths.
+
+### Link Time Optimization
+
+When cross compiling, the use of Link Time Optimization (LTO) and unknown function handling
+is not supported. Either LTO needs to be turned off, or the assembly should be disabled.
+
+## Tests
+
+To build tests, make sure that the `BUILD_TESTS` option is set to true. Using
+the command line, this looks like `-DBUILD_TESTS=ON`.
+
+This project is configured to run with `ctest`, which makes it easy to run the
+tests. To run the tests, change the directory to that of the build direction, and
+execute `ctest`.
+
+More details can be found in the [README.md](./tests/README.md) for the tests
+directory of this project.