BUILD.md

   1 # Build Instructions
   2 This project fully supports Linux today.
   3 Support for Windows is for the loader, layers, and the VkTrace trace/replay tools.
   4 Support for Android is TBD.
   5
   6 ## Git the Bits
   7
   8 Make sure you have access to the Khronos GitLab repository at gitlab.khronos.org.  Once you do, the
   9 preferred work flow is to clone the repo, create a branch, push branch to gitlab and then
  10 issue a merge request to integrate that work back into the repo.
  11
  12 Note: If you are doing ICD (driver) development, please make sure to look at documentation in the [ICD Loader](loader/README.md) and the [Sample Driver](icd).
  13
  14 ## Linux System Requirements
  15 Ubuntu 14.10 needed for DRI 3
  16
  17 ```
  18 sudo apt-get install git subversion cmake libgl1-mesa-dev freeglut3-dev libglm-dev libpng12-dev libmagickwand-dev qt5-default libpciaccess-dev libpthread-stubs0-dev libudev-dev
  19 sudo apt-get build-dep mesa
  20 ```
  21 Warning: Recent versions of 14.10 have **REMOVED** DRI 3.
  22 Version: 2:2.99.914-1~exp1ubuntu4.1 is known to work.
  23 To see status of this package:
  24 ```
  25 dpkg -s xserver-xorg-video-intel
  26 ```
  27
  28 Note:
  29 Version 2:2.99.914-1~exp1ubuntu4.2 does not work anymore.
  30 To install the working driver from launchpadlibrarian.net:
  31 - Remove the current driver:
  32 ```
  33 sudo apt-get purge xserver-xorg-video-intel
  34 ```
  35 - Download the old driver:
  36 ```
  37 wget http://launchpadlibrarian.net/189418339/xserver-xorg-video-intel_2.99.914-1%7Eexp1ubuntu4.1_amd64.deb
  38 ```
  39 - Install the driver:
  40 ```
  41 sudo dpkg -i xserver-xorg-video-intel_2.99.914-1~exp1ubuntu4.1_amd64.deb
  42 ```
  43 - Pin the package to prevent updates
  44 ```
  45 sudo bash -c "echo $'Package: xserver-xorg-video-intel\nPin: version 2:2.99.914-1~exp1ubuntu4.1\nPin-Priority: 1001' > /etc/apt/preferences.d/xserver-xorg-video-intel"
  46 ```
  47
  48 - Either restart Ubuntu or just X11.
  49
  50 ## Clone the repository
  51
  52 To create your local git repository:
  53 ```
  54 mkdir YOUR_DEV_DIRECTORY  # it's called GL-Next on Github, but the name doesn't matter
  55 cd YOUR_DEV_DIRECTORY
  56 git clone -o khronos git@gitlab.khronos.org:vulkan/LoaderAndTools.git .
  57 # Or substitute the URL from your forked repo for git@gitlab.khronos.org:vulkan/LoaderAndTools.git above.
  58 ```
  59
  60 ## Linux Build
  61
  62 The sample driver uses cmake and should work with the usual cmake options and utilities.
  63 The standard build process builds the icd, the icd loader and all the tests.
  64
  65 Example debug build:
  66 ```
  67 cd YOUR_DEV_DIRECTORY  # cd to the root of the vk git repository
  68 export KHRONOS_ACCOUNT_NAME= <subversion login name for svn checkout of BIL>
  69 ./update_external_sources.sh  # fetches and builds glslang, llvm, LunarGLASS, and BIL
  70 cmake -H. -Bdbuild -DCMAKE_BUILD_TYPE=Debug
  71 cd dbuild
  72 make
  73 ```
  74
  75 To run VK programs you must tell the icd loader where to find the libraries.
  76 This is described in a specification in the Khronos documentation Git
  77 repository.  See the file:
  78 https://gitlab.khronos.org/vulkan/vulkan/blob/master/ecosystem/LinuxICDs.txt
  79
  80 This specification describes both how ICDs and layers should be properly
  81 packaged, and how developers can point to ICDs and layers within their builds.
  82
  83
  84 ## Linux Test
  85
  86 The test executibles can be found in the dbuild/tests directory. The tests use the Google
  87 gtest infrastructure. Tests available so far:
  88 - vkbase: Test basic entry points
  89 - vk_blit_tests: Test VK Blits (copy, clear, and resolve)
  90 - vk_image_tests: Test VK image related calls needed by render_test
  91 - vk_render_tests: Render a single triangle with VK. Triangle will be in a .ppm in
  92 the current directory at the end of the test.
  93 - vk_layer_validation_tests: Test Vulkan layers.
  94
  95 There are also a few shell and Python scripts that run test collections (eg,
  96 `run_all_tests.sh`).
  97
  98 ## Linux Demos
  99
 100 The demos executables can be found in the dbuild/demos directory. The demos use DRI 3
 101 to render directly onto window surfaces.
 102 - vulkaninfo: report GPU properties
 103 - tri: a textured triangle
 104 - cube: a textured spinning cube
 105
 106 ## Linux Render Nodes
 107
 108 The render tests depend on access to DRM render nodes.
 109 To make that available, a couple of config files need to be created to set a module option
 110 and make accessible device files.
 111 The system will need to be rebooted with these files in place to complete initialization.
 112 These commands will create the config files.
 113
 114 ```
 115 sudo tee /etc/modprobe.d/drm.conf << EOF
 116 # Enable render nodes
 117 options drm rnodes=1
 118 EOF
 119 # this will add the rnodes=1 option into the boot environment
 120 sudo update-initramfs -k all -u
 121 ```
 122 ```
 123 sudo tee /etc/udev/rules.d/drm.rules << EOF
 124 # Add permissions to render nodes
 125 SUBSYSTEM=="drm", ACTION=="add", DEVPATH=="/devices/*/renderD*", MODE="020666"
 126 EOF
 127 ```
 128
 129 ## Windows System Requirements
 130
 131 Windows 7+ with additional required software packages:
 132
 133 - Microsoft Visual Studio 2013 Professional.  Note: it is possible that lesser/older versions may work, but that has not been tested.
 134 - CMake (from http://www.cmake.org/download/).  Notes:
 135   - In order to build the VkTrace tools, you need at least version 3.0.
 136   - Tell the installer to "Add CMake to the system PATH" environment variable.
 137 - Python 3 (from https://www.python.org/downloads).  Notes:
 138   - Select to install the optional sub-package to add Python to the system PATH environment variable.
 139   - Need python3.3 or later to get the Windows py.exe launcher that is used to get python3 rather than python2 if both are installed on Windows
 140 - Git (from http://git-scm.com/download/win).
 141   - Note: If you use Cygwin, you can normally use Cygwin's "git.exe".  However, in order to use the "update_external_sources.bat" script, you must have this version.
 142   - Tell the installer to allow it to be used for "Developer Prompt" as well as "Git Bash".
 143   - Tell the installer to treat line endings "as is" (i.e. both DOS and Unix-style line endings).
 144 - Image Magick is used by the tests to compare images (from http://www.imagemagick.org/script/binary-releases.php)
 145   - Be sure to check box to "Install development headers and libraries"
 146 - glslang is required for demos and tests.
 147   - You can download and configure it (in a peer directory) here: https://github.com/KhronosGroup/glslang/blob/master/README.md
 148   - A windows batch file has been included that will pull and build the correct version.  Run it from Developer Command Prompt for VS2013 like so:
 149     - update_external_sources.bat --build-glslang
 150
 151 Optional software packages:
 152
 153 - Cygwin (from https://www.cygwin.com/).  Notes:
 154   - Cygwin provides some Linux-like tools, which are valuable for obtaining the source code, and running CMake.
 155     Especially valuable are the BASH shell and git packages.
 156   - If you don't want to use Cygwin, there are other shells and environments that can be used.
 157     You can also use a Git package that doesn't come from Cygwin.
 158
 159 ## Windows Build
 160
 161 Cygwin is used in order to obtain a local copy of the Git repository, and to run the CMake command that creates Visual Studio files.  Visual Studio is used to build the software, and will re-run CMake as appropriate.
 162
 163 Example debug build (e.g. in a "Developer Command Prompt for VS2013" window):
 164 ```
 165 cd LoaderAndTools  # cd to the root of the Vulkan git repository
 166 update_external_sources.bat --build-glslang
 167 mkdir _out64
 168 cd _out64
 169 cmake -G "Visual Studio 12 Win64" -DCMAKE_BUILD_TYPE=Debug ..
 170 ```
 171
 172 At this point, you can use Windows Explorer to launch Visual Studio by double-clicking on the "VULKAN.sln" file in the \_out64 folder.  Once Visual Studio comes up, you can select "Debug" or "Release" from a drop-down list.  You can start a build with either the menu (Build->Build Solution), or a keyboard shortcut (Ctrl+Shift+B).  As part of the build process, Python scripts will create additional Visual Studio files and projects, along with additional source files.  All of these auto-generated files are under the "_out64" folder.
 173
 174 VK programs must be able to find and use the VK.dll libary. Make sure it is either installed in the C:\Windows\System32 folder, or the PATH enviroment variable includes the folder that it is located in.
 175
 176 To run VK programs you must tell the icd loader where to find the libraries.
 177 This is described in a specification in the Khronos documentation Git
 178 repository.  See the file:
 179 https://gitlab.khronos.org/vulkan/vulkan/blob/master/ecosystem/WindowsICDs.txt
 180
 181 This specification describes both how ICDs and layers should be properly
 182 packaged, and how developers can point to ICDs and layers within their builds.