1# Build Instructions 2 3Instructions for building this repository on Windows, Linux, and MacOS. 4 5## Index 6 71. [Contributing](#contributing-to-the-repository) 81. [Repository Content](#repository-content) 91. [Repository Set-up](#repository-set-up) 101. [Windows Build](#building-on-windows) 111. [Linux Build](#building-on-linux) 121. [MacOS Build](#building-on-macos) 13 14## Contributing to the Repository 15 16The contents of this repository are sourced primarily from the Khronos Vulkan 17API specification [repository](https://github.com/KhronosGroup/Vulkan-Docs). 18Please visit that repository for information on contributing. 19 20## Repository Content 21 22This repository contains the Vulkan header files and the Vulkan API definition 23(registry) with its related files. This repository does not create libraries 24or executables. 25 26However, this repository contains CMake build configuration files to "install" 27the files from this repository to a specific install directory. For example, 28you can install the files to a system directory such as `/usr/local` on Linux. 29 30If you are building other Vulkan-related repositories such as 31[Vulkan-Loader](https://github.com/KhronosGroup/Vulkan-Loader), 32you need to build the install target of this repository and provide the 33resulting install directory to those repositories. 34 35### Installed Files 36 37The `install` target installs the following files under the directory 38indicated by *install_dir*: 39 40- *install_dir*`/include/vulkan` : The header files found in the 41 `include/vulkan` directory of this repository 42- *install_dir*`/share/vulkan/registry` : The registry files found in the 43 `registry` directory of this repository 44 45The `uninstall` target can be used to remove the above files from the install 46directory. 47 48## Repository Set-Up 49 50### Download the Repository 51 52To create your local git repository: 53 54 git clone https://github.com/KhronosGroup/Vulkan-Headers.git 55 56### Repository Dependencies 57 58This repository does not depend on any other repositories. 59 60### Build and Install Directories 61 62A common convention is to place the build directory in the top directory of 63the repository with a name of `build` and place the install directory as a 64child of the build directory with the name `install`. The remainder of these 65instructions follow this convention, although you can use any name for these 66directories and place them in any location. 67 68## Building On Windows 69 70### Windows Development Environment Requirements 71 72- Windows 73 - Any Personal Computer version supported by Microsoft 74- Microsoft [Visual Studio](https://www.visualstudio.com/) 75 - Versions 76 - [2015](https://www.visualstudio.com/vs/older-downloads/) 77 - [2017](https://www.visualstudio.com/vs/older-downloads/) 78 - [2019](https://www.visualstudio.com/vs/downloads/) 79 - The Community Edition of each of the above versions is sufficient, as 80 well as any more capable edition. 81- [CMake 3.10.2](https://cmake.org/files/v3.10/cmake-3.10.2-win64-x64.zip) is recommended. 82 - Use the installer option to add CMake to the system PATH 83- Git Client Support 84 - [Git for Windows](http://git-scm.com/download/win) is a popular solution 85 for Windows 86 - Some IDEs (e.g., [Visual Studio](https://www.visualstudio.com/), 87 [GitHub Desktop](https://desktop.github.com/)) have integrated 88 Git client support 89 90### Windows Build - Microsoft Visual Studio 91 92The general approach is to run CMake to generate the Visual Studio project 93files. Then either run CMake with the `--build` option to build from the 94command line or use the Visual Studio IDE to open the generated solution and 95work with the solution interactively. 96 97#### Windows Quick Start 98 99From a "Developer Command Prompt for VS 201x" console: 100 101 cd Vulkan-Headers 102 mkdir build 103 cd build 104 cmake .. 105 cmake --build . --target install 106 107See below for the details. 108 109#### Use `CMake` to Create the Visual Studio Project Files 110 111From within a "Developer Command Prompt for VS 201x" console, change your 112current directory to the top of the cloned repository directory, create a 113build directory and generate the Visual Studio project files: 114 115 cd Vulkan-Headers 116 mkdir build 117 cd build 118 cmake .. 119 120> Note: The `..` parameter tells `cmake` the location of the top of the 121> repository. If you place your build directory someplace else, you'll need to 122> specify the location of the repository top differently. 123 124The CMake configuration files set the default install directory location to 125`$CMAKE_BINARY_DIR\install`, which is a child of your build directory. In this 126example, the install directory becomes the `Vulkan-Headers\build\install` 127directory. 128 129The project installs the header files to 130 131 Vulkan-Headers\build\install\include\vulkan 132 133and installs the registry files to 134 135 Vulkan-Headers\build\install\share\vulkan\registry 136 137You can change the install directory with the `CMAKE_INSTALL_PREFIX` CMake 138variable. 139 140For example: 141 142 cd Vulkan-Headers 143 mkdir build 144 cd build 145 cmake -DCMAKE_INSTALL_PREFIX=/c/Users/dev/install .. # MINGW64 shell 146 147As it starts generating the project files, `cmake` responds with something 148like: 149 150 -- Building for: Visual Studio 14 2015 151 152which is a 32-bit generator. 153 154Since this repository does not compile anything, there is no need to specify a 155specific generator such as "Visual Studio 14 2015 Win64", so the default 156generator should suffice. 157 158The above steps create a Windows solution file named `Vulkan-Headers.sln` in 159the build directory. 160 161At this point, you can build the solution from the command line or open the 162generated solution with Visual Studio. 163 164#### Build the Solution From the Command Line 165 166While still in the build directory: 167 168 cmake --build . --target install 169 170to build the install target. 171 172Build the `uninstall` target to remove the files from the install directory. 173 174 cmake --build . --target uninstall 175 176#### Build the Solution With Visual Studio 177 178Launch Visual Studio and open the "Vulkan-Headers.sln" solution file in the 179build directory. Build the `INSTALL` target from the Visual Studio solution 180explorer. 181 182Build the `uninstall` target to remove the files from the install directory. 183 184> Note: Since there are only the `INSTALL` and `uninstall` projects in the 185> solution, building the solution from the command line may be more efficient 186> than starting Visual Studio for these simple operations. 187 188## Building On Linux 189 190### Linux Development Environment Requirements 191 192There are no specific Linux distribution or compiler version requirements for 193building this repository. The required tools are 194 195- [CMake 3.10.2](https://cmake.org/files/v3.10/cmake-3.10.2-Linux-x86_64.tar.gz) is recommended. 196- git 197 198### Linux Build 199 200The general approach is to run CMake to generate make files. Then either run 201CMake with the `--build` option or `make` to build from the command line. 202 203#### Linux Quick Start 204 205 cd Vulkan-Headers 206 mkdir build 207 cd build 208 cmake -DCMAKE_INSTALL_PREFIX=install .. 209 make install 210 211See below for the details. 212 213#### Use CMake to Create the Make Files 214 215Change your current directory to the top of the cloned repository directory, 216create a build directory and generate the make files: 217 218 cd Vulkan-Headers 219 mkdir build 220 cd build 221 cmake -DCMAKE_INSTALL_PREFIX=install .. 222 223> Note: The `..` parameter tells `cmake` the location of the top of the 224> repository. If you place your `build` directory someplace else, you'll need 225> to specify the location of the repository top differently. 226 227Set the `CMAKE_INSTALL_PREFIX` variable to the directory to serve as the 228destination directory for the `install` target. 229 230The above `cmake` command sets the install directory to 231`$CMAKE_BINARY_DIR/install`, which is a child of your `build` directory. In 232this example, the install directory becomes the `Vulkan-Headers/build/install` 233directory. 234 235The make file install target installs the header files to 236 237 Vulkan-Headers/build/install/include/vulkan 238 239and installs the registry files to 240 241 Vulkan-Headers/build/install/share/vulkan/registry 242 243> Note: For Linux, the default value for `CMAKE_INSTALL_PREFIX` is 244> `/usr/local`, which would be used if you do not specify 245> `CMAKE_INSTALL_PREFIX`. In this case, you may need to use `sudo` to install 246> to system directories later when you run `make install`. 247 248Note that after generating the make files, running `make`: 249 250 make 251 252does nothing, since there are no libraries or executables to build. 253 254To install the header files: 255 256 make install 257 258or 259 260 cmake --build . --target install 261 262To uninstall the files from the install directories, you can execute: 263 264 make uninstall 265 266or 267 268 cmake --build . --target uninstall 269 270## Building on MacOS 271 272The instructions for building this repository on MacOS are similar to those for Linux. 273 274[CMake 3.10.2](https://cmake.org/files/v3.10/cmake-3.10.2-Darwin-x86_64.tar.gz) is recommended. 275