mewin/vulkan-headers
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

doc: Update BUILD.md [skip ci]

Browse Source
This commit is contained in:
Karl Schultz 2018-06-15 19:11:06 -06:00
parent b1577d5fbd
commit 06a71b203e
1 changed files with 165 additions and 79 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

244
BUILD.md
View File

@ -2,27 +2,49 @@
Instructions for building this repository on Windows, Linux, and MacOS. Instructions for building this repository on Windows, Linux, and MacOS.
Since this repository doesn't contain any build targets for libraries
or executables, there usually isn't any need to "build" this repository.
However, `install` and `uninstall` targets are provided if you have a need to
install the Vulkan headers and registry files to system directories
or other location for use by other repositories.
## Index ## Index
1. [Contributing](#contributing-to-the-repository) 1. [Contributing](#contributing-to-the-repository)
2. [Repository Set-Up](#repository-set-up) 1. [Repository Content](#repository-content)
3. [Installed Files](#installed-files) 1. [Repository Set-up](#repository-set-up)
4. [Windows Build](#building-on-windows) 1. [Windows Build](#building-on-windows)
5. [Linux Build](#building-on-linux) 1. [Linux Build](#building-on-linux)
6. [MacOS build](#building-on-macos) 1. [MacOS Build](#building-on-macos)
## Contributing to the Repository ## Contributing to the Repository
The contents of this repository are sourced primarily from the The contents of this repository are sourced primarily from the Khronos Vulkan
[Khronos Vulkan API specification repository](https://github.com/KhronosGroup/Vulkan-Docs). API specification [repository](https://github.com/KhronosGroup/Vulkan-Docs).
Please visit that repository for information on contributing. Please visit that repository for information on contributing.
## Repository Content
This repository contains the Vulkan header files and the Vulkan API definition
(registry) with its related files. This repository does not create libraries
or executables.
However, this repository contains CMake build configuration files to "install"
the files from this repository to a specific install directory. For example,
you can install the files to a system directory such as `/usr/local` on Linux.
If you are building other Vulkan-related repositories such as
[Vulkan-Loader](https://github.com/KhronosGroup/Vulkan-Loader),
you need to build the install target of this repository and provide the
resulting install directory to those repositories.
### Installed Files
The `install` target installs the following files under the directory
indicated by *install_dir*:
- *install_dir*`/include/vulkan` : The header files found in the
`include/vulkan` directory of this repository
- *install_dir*`/share/vulkan/registry` : The registry files found in the
`registry` directory of this repository
The `uninstall` target can be used to remove the above files from the install
directory.
## Repository Set-Up ## Repository Set-Up
### Download the Repository ### Download the Repository
@ -31,63 +53,86 @@ To create your local git repository:
git clone https://github.com/KhronosGroup/Vulkan-Headers.git git clone https://github.com/KhronosGroup/Vulkan-Headers.git
## Installed Files ### Repository Dependencies
The `install` target installs the following files under the directory This repository does not depend on any other repositories.
indicated by "install_dir":
- `install_dir/include/vulkan` : The header files found in the ### Build and Install Directories
`include/vulkan` directory of this repository
- `install_dir/share/vulkan/registry` : The registry files found in the A common convention is to place the build directory in the top directory of
`registry` directory of this repository the repository with a name of `build` and place the install directory as a
child of the build directory with the name `install`. The remainder of these
instructions follow this convention, although you can use any name for these
directories and place them in any location.
## Building On Windows ## Building On Windows
### Windows Build Requirements ### Windows Development Environment Requirements
Windows 7+ with the following software packages: - Windows
- Any Personal Computer version supported by Microsoft
- Microsoft Visual Studio 2013 Update 4 Professional, VS2015 (any version), or VS2017 (any version). - Microsoft [Visual Studio](https://www.visualstudio.com/)
- [CMake](http://www.cmake.org/download/) - Versions
- Tell the installer to "Add CMake to the system PATH" environment variable. - [2013 (update 4)](https://www.visualstudio.com/vs/older-downloads/)
- [Git](http://git-scm.com/download/win) - [2015](https://www.visualstudio.com/vs/older-downloads/)
- Tell the installer to allow it to be used for "Developer Prompt" as well as "Git Bash". - [2017](https://www.visualstudio.com/vs/downloads/)
- Tell the installer to treat line endings "as is" (i.e. both DOS and Unix-style line endings). - The Community Edition of each of the above versions is sufficient, as
- Install both the 32-bit and 64-bit versions, as the 64-bit installer does not install the well as any more capable edition.
32-bit libraries and tools. - [CMake](http://www.cmake.org/download/) (Version 2.8.11 or better)
- Use the installer option to add CMake to the system PATH
- Git Client Support
- [Git for Windows](http://git-scm.com/download/win) is a popular solution
for Windows
- Some IDEs (e.g., [Visual Studio](https://www.visualstudio.com/),
[GitHub Desktop](https://desktop.github.com/)) have integrated
Git client support
### Windows Build - Microsoft Visual Studio ### Windows Build - Microsoft Visual Studio
The general approach is to run `cmake` to generate the VS project files. The general approach is to run CMake to generate the Visual Studio project
Then either run `cmake` again to build from the command line or use the files. Then either run CMake with the `--build` option to build from the
Visual Studio IDE to open the generated solution and work with the solution command line or use the Visual Studio IDE to open the generated solution and
interactively. work with the solution interactively.
It should be possible to perform these `cmake` invocations from any one of the Windows #### Windows Quick Start
"terminal programs", including the standard Windows Command Prompt, MSBuild Command Prompt,
PowerShell, MINGW, CygWin, etc.
#### Use `cmake` to create the VS project files cd Vulkan-Headers
mkdir build
cd build
cmake ..
cmake --build . --target install
Switch to the top of the cloned repository directory, See below for the details.
create a build directory and generate the VS project files:
#### Use `CMake` to Create the Visual Studio Project Files
Change your current directory to the top of the cloned repository directory,
create a build directory and generate the Visual Studio project files:
cd Vulkan-Headers cd Vulkan-Headers
mkdir build mkdir build
cd build cd build
cmake .. cmake ..
The default install directory location is `$CMAKE_BINARY_DIR\install`, > Note: The `..` parameter tells `cmake` the location of the top of the
which is your `Vulkan-Headers\build\install` directory. > repository. If you place your build directory someplace else, you'll need to
> specify the location of the repository top differently.
This default setting sets the install destination to The CMake configuration files set the default install directory location to
`Vulkan-Headers\build\install` `$CMAKE_BINARY_DIR\install`, which is a child of your build directory. In this
and causes the header files to be installed to example, the install directory becomes the `Vulkan-Headers\build\install`
`Vulkan-Headers\build\install\include/vulkan` directory.
and the registry files to be installed to
`Vulkan-Headers\build\install\share\vulkan\registry`.
The install location can be changed with the `CMAKE_INSTALL_PREFIX` variable. The project installs the header files to
Vulkan-Headers\build\install\include\vulkan
and installs the registry files to
Vulkan-Headers\build\install\share\vulkan\registry
You can change the install directory with the `CMAKE_INSTALL_PREFIX` CMake
variable.
For example: For example:
@ -96,23 +141,24 @@ For example:
cd build cd build
cmake -DCMAKE_INSTALL_PREFIX=/c/Users/dev/install .. # MINGW64 shell cmake -DCMAKE_INSTALL_PREFIX=/c/Users/dev/install .. # MINGW64 shell
As it starts generating the project files, `cmake` responds with something like: As it starts generating the project files, `cmake` responds with something
like:
-- Building for: Visual Studio 14 2015 -- Building for: Visual Studio 14 2015
which is a 32-bit generator. which is a 32-bit generator.
Since this repository does not compile anything, there is no need Since this repository does not compile anything, there is no need to specify a
to specify a specific generator such as "Visual Studio 14 2015 Win64", specific generator such as "Visual Studio 14 2015 Win64", so the default
so the default generator should suffice. generator should suffice.
This creates a Windows solution file named `Vulkan-Headers.sln` The above steps create a Windows solution file named `Vulkan-Headers.sln` in
in the build directory. the build directory.
At this point, you can build the solution from the command line or open the At this point, you can build the solution from the command line or open the
generated solution with Visual Studio. generated solution with Visual Studio.
#### Build the solution from the command line #### Build the Solution From the Command Line
While still in the build directory: While still in the build directory:
@ -120,29 +166,50 @@ While still in the build directory:
to build the install target. to build the install target.
Build the `uninstall` target to remove the files from the install location. Build the `uninstall` target to remove the files from the install directory.
cmake --build . --target uninstall cmake --build . --target uninstall
#### Build the solution with Visual Studio #### Build the Solution With Visual Studio
Launch Visual Studio and open the "Vulkan-Headers.sln" solution file in the build folder. Launch Visual Studio and open the "Vulkan-Headers.sln" solution file in the
Build the `INSTALL` target from the Visual Studio solution explorer. build directory. Build the `INSTALL` target from the Visual Studio solution
explorer.
Build the `uninstall` target to remove the files from the install location. Build the `uninstall` target to remove the files from the install directory.
cmake --build . --target uninstall > Note: Since there are only the `INSTALL` and `uninstall` projects in the
> solution, building the solution from the command line may be more efficient
> than starting Visual Studio for these simple operations.
## Building On Linux ## Building On Linux
### Linux Build Requirements ### Linux Development Environment Requirements
There are no specific Linux distribution or compiler There are no specific Linux distribution or compiler version requirements for
verison requirements for building this repository. building this repository. The required tools are
- cmake (Version 2.8.11 or better)
- git
### Linux Build ### Linux Build
Switch to the top of the cloned repository directory, The general approach is to run CMake to generate make files. Then either run
CMake with the `--build` option or `make` to build from the command line.
#### Linux Quick Start
cd Vulkan-Headers
mkdir build
cd build
cmake -DCMAKE_INSTALL_PREFIX=install ..
make install
See below for the details.
#### Use CMake to Create the Make Files
Change your current directory to the top of the cloned repository directory,
create a build directory and generate the make files: create a build directory and generate the make files:
cd Vulkan-Headers cd Vulkan-Headers
@ -150,19 +217,30 @@ create a build directory and generate the make files:
cd build cd build
cmake -DCMAKE_INSTALL_PREFIX=install .. cmake -DCMAKE_INSTALL_PREFIX=install ..
> 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.
Set the `CMAKE_INSTALL_PREFIX` variable to the directory to serve as the Set the `CMAKE_INSTALL_PREFIX` variable to the directory to serve as the
destination directory for the `install` target. destination directory for the `install` target.
The above setting sets the install destination to
`Vulkan-Headers/build/install`
which causes the header files to be installed to
`Vulkan-Headers/build/install/include/vulkan`
and the registry files to be installed to
`Vulkan-Headers/build/install/share/vulkan/registry`
For Linux, the default value for `CMAKE_INSTALL_PREFIX` is `/usr/local`, The above `cmake` command sets the install directory to
which would be used if you do not specify `CMAKE_INSTALL_PREFIX`. `$CMAKE_BINARY_DIR/install`, which is a child of your `build` directory. In
In this case, you may need to use `sudo` to install to system directories this example, the install directory becomes the `Vulkan-Headers/build/install`
later when you run `make install`. directory.
The make file install target installs the header files to
Vulkan-Headers/build/install/include/vulkan
and installs the registry files to
Vulkan-Headers/build/install/share/vulkan/registry
> Note: For Linux, the default value for `CMAKE_INSTALL_PREFIX` is
> `/usr/local`, which would be used if you do not specify
> `CMAKE_INSTALL_PREFIX`. In this case, you may need to use `sudo` to install
> to system directories later when you run `make install`.
Note that after generating the make files, running `make`: Note that after generating the make files, running `make`:
@ -174,11 +252,19 @@ To install the header files:
make install make install
or
cmake --build . --target install
To uninstall the files from the install directories, you can execute: To uninstall the files from the install directories, you can execute:
make uninstall make uninstall
or
cmake --build . --target uninstall
## Building on MacOS ## Building on MacOS
The instructions for installing the headers for MacOS are the The instructions for building this repository on MacOS are the same as those
same as those for Linux. for Linux.