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