BUILD.md

   1 # Build Instructions
   2 This project fully supports Linux and Windows today.
   3 Support for Android is TBD.
   4
   5 ## Git the Bits
   6
   7 Make sure you have access to the Khronos GitLab repository at gitlab.khronos.org.  Once you do, the
   8 preferred work flow is to clone the repo, create a branch, push branch to gitlab and then
   9 issue a merge request to integrate that work back into the repo.
  10
  11 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).
  12
  13 ## Linux System Requirements
  14 Ubuntu 14.04.3 LTS, 14.10, 15.04 and 15.10 have been used with the sample driver.
  15
  16 These packages are used for building and running the samples.
  17 ```
  18 sudo apt-get install git subversion cmake libgl1-mesa-dev freeglut3-dev libglm-dev qt5-default libpciaccess-dev libpthread-stubs0-dev libudev-dev bison graphviz libpng-dev
  19 sudo apt-get build-dep mesa
  20 ```
  21
  22 The sample driver uses DRI3 for its window system interface.
  23 That requires extra configuration of Ubuntu systems.
  24
  25 ### Ubuntu 14.04.3 LTS support of DRI 3
  26
  27 Ubuntu 14.04.3 LTS does not ship a xserver-xorg-video-intel package with supported DRI 3 on intel graphics.
  28 The xserver-xorg-video-intel package can be built from source with DRI 3 enabled.
  29 Use the following commands to enable DRI3 on ubuntu 14.04.3 LTS.
  30
  31 - Install packages used to build:
  32 ```
  33 sudo apt-get update
  34 sudo apt-get dist-upgrade
  35 sudo apt-get install devscripts
  36 sudo apt-get build-dep xserver-xorg-video-intel-lts-vivid
  37 ```
  38
  39 - Get the source code for xserver-xorg-video-intel-lts-vivid
  40 ```
  41 mkdir xserver-xorg-video-intel-lts-vivid_source
  42 cd xserver-xorg-video-intel-lts-vivid_source
  43 apt-get source xserver-xorg-video-intel-lts-vivid
  44 cd xserver-xorg-video-intel-lts-vivid-2.99.917
  45 debian/rules patch
  46 quilt new 'enable-DRI3'
  47 quilt edit configure.ac
  48 ```
  49
  50 - Use the editor to make these changes.
  51 ```
  52 --- a/configure.ac
  53 +++ b/configure.ac
  54 @@ -340,9 +340,9 @@
  55               [DRI2=yes])
  56  AC_ARG_ENABLE(dri3,
  57               AS_HELP_STRING([--enable-dri3],
  58 -                            [Enable DRI3 support [[default=no]]]),
  59 +                            [Enable DRI3 support [[default=yes]]]),
  60               [DRI3=$enableval],
  61 -             [DRI3=no])
  62 +             [DRI3=yes])
  63  AC_ARG_ENABLE(xvmc, AS_HELP_STRING([--disable-xvmc],
  64                                    [Disable XvMC support [[default=yes]]]),
  65 ```
  66 - Build and install xserver-xorg-video-intel-lts-vivid
  67 ```
  68 quilt refresh
  69 debian/rules clean
  70 debuild -us -uc
  71 sudo dpkg -i ../xserver-xorg-video-intel-lts-vivid_2.99.917-1~exp1ubuntu2.2~trusty1_amd64.deb
  72 ```
  73 - Prevent updates from replacing this version of the package.
  74 ```
  75 sudo bash -c 'echo xserver-xorg-video-intel-lts-vivid hold | dpkg --set-selections'
  76 ```
  77 - save your work then restart the X server with the next command.
  78 ```
  79 sudo service lightdm restart
  80 ```
  81 - After logging in again, check for success with this command and look for DRI3.
  82 ```
  83 xdpyinfo | grep DRI
  84 ```
  85
  86 ### Ubuntu 14.10 support of DRI 3
  87
  88 Warning: Recent versions of 14.10 have **REMOVED** DRI 3.
  89 Version: 2:2.99.914-1~exp1ubuntu4.1 is known to work.
  90 To see status of this package:
  91 ```
  92 dpkg -s xserver-xorg-video-intel
  93 ```
  94
  95 Note:
  96 Version 2:2.99.914-1~exp1ubuntu4.2 does not work anymore.
  97 To install the working driver from launchpadlibrarian.net:
  98 - Remove the current driver:
  99 ```
 100 sudo apt-get purge xserver-xorg-video-intel
 101 ```
 102 - Download the old driver:
 103 ```
 104 wget http://launchpadlibrarian.net/189418339/xserver-xorg-video-intel_2.99.914-1%7Eexp1ubuntu4.1_amd64.deb
 105 ```
 106 - Install the driver:
 107 ```
 108 sudo dpkg -i xserver-xorg-video-intel_2.99.914-1~exp1ubuntu4.1_amd64.deb
 109 ```
 110 - Pin the package to prevent updates
 111 ```
 112 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"
 113 ```
 114
 115 - Either restart Ubuntu or just X11.
 116
 117
 118 ### Ubuntu 15.04 support of DRI 3
 119
 120 Ubuntu 15.04 has never shipped a xserver-xorg-video-intel package with supported DRI 3 on intel graphics.
 121 The xserver-xorg-video-intel package can be built from source with DRI 3 enabled.
 122 Use the following commands to enable DRI3 on ubuntu 15.04.
 123
 124 - Install packages used to build:
 125 ```
 126 sudo apt-get update
 127 sudo apt-get dist-upgrade
 128 sudo apt-get install devscripts
 129 sudo apt-get build-dep xserver-xorg-video-intel
 130 ```
 131
 132 - Get the source code for xserver-xorg-video-intel
 133 ```
 134 mkdir xserver-xorg-video-intel_source
 135 cd xserver-xorg-video-intel_source
 136 apt-get source xserver-xorg-video-intel
 137 cd xserver-xorg-video-intel-2.99.917
 138 debian/rules patch
 139 quilt new 'enable-DRI3'
 140 quilt edit configure.ac
 141 ```
 142
 143 - Use the editor to make these changes.
 144 ```
 145 --- a/configure.ac
 146 +++ b/configure.ac
 147 @@ -340,9 +340,9 @@
 148               [DRI2=yes])
 149  AC_ARG_ENABLE(dri3,
 150               AS_HELP_STRING([--enable-dri3],
 151 -                            [Enable DRI3 support [[default=no]]]),
 152 +                            [Enable DRI3 support [[default=yes]]]),
 153               [DRI3=$enableval],
 154 -             [DRI3=no])
 155 +             [DRI3=yes])
 156  AC_ARG_ENABLE(xvmc, AS_HELP_STRING([--disable-xvmc],
 157                                    [Disable XvMC support [[default=yes]]]),
 158 ```
 159 - Build and install xserver-xorg-video-intel
 160 ```
 161 quilt refresh
 162 debian/rules clean
 163 debuild -us -uc
 164 sudo dpkg -i ../xserver-xorg-video-intel_2.99.917-1~exp1ubuntu2.2_amd64.deb
 165 ```
 166 - Prevent updates from replacing this version of the package.
 167 ```
 168 sudo bash -c 'echo xserver-xorg-video-intel hold | dpkg --set-selections'
 169 ```
 170 - save your work then restart the X server with the next command.
 171 ```
 172 sudo service lightdm restart
 173 ```
 174 - After logging in again, check for success with this command and look for DRI3.
 175 ```
 176 xdpyinfo | grep DRI
 177 ```
 178 ### Ubuntu 15.10 support of DRI 3
 179
 180 Ubuntu 15.10 has never shipped a xserver-xorg-video-intel package with supported DRI 3 on intel graphics.
 181 The xserver-xorg-video-intel package can be built from source with DRI 3 enabled.
 182 Use the following commands to enable DRI3 on ubuntu 15.10.
 183
 184 - Install packages used to build:
 185 ```
 186 sudo apt-get update
 187 sudo apt-get dist-upgrade
 188 sudo apt-get install devscripts
 189 sudo apt-get build-dep xserver-xorg-video-intel
 190 ```
 191
 192 - Get the source code for xserver-xorg-video-intel
 193 ```
 194 mkdir xserver-xorg-video-intel_source
 195 cd xserver-xorg-video-intel_source
 196 apt-get source xserver-xorg-video-intel
 197 cd xserver-xorg-video-intel-2.99.917+git20150808
 198 debian/rules patch
 199 quilt new 'enable-DRI3'
 200 quilt edit configure.ac
 201 ```
 202
 203 - Use the editor to make these changes.
 204 ```
 205 Index: xserver-xorg-video-intel-2.99.917+git20150808/configure.ac
 206 ===================================================================
 207 --- xserver-xorg-video-intel-2.99.917+git20150808.orig/configure.ac
 208 +++ xserver-xorg-video-intel-2.99.917+git20150808/configure.ac
 209 @@ -356,7 +356,7 @@ AC_ARG_WITH(default-dri,
 210             AS_HELP_STRING([--with-default-dri],
 211                            [Select the default maximum DRI level [default 2]]),
 212               [DRI_DEFAULT=$withval],
 213 -             [DRI_DEFAULT=2])
 214 +             [DRI_DEFAULT=3])
 215  if test "x$DRI_DEFAULT" = "x0"; then
 216         AC_DEFINE(DEFAULT_DRI_LEVEL, 0,[Default DRI level])
 217  else
 218 ```
 219 - Build and install xserver-xorg-video-intel
 220 ```
 221 quilt refresh
 222 debian/rules clean
 223 debuild -us -uc
 224 sudo dpkg -i ../xserver-xorg-video-intel_2.99.917+git20150808-0ubuntu4_amd64.deb
 225 ```
 226 - Prevent updates from replacing this version of the package.
 227 ```
 228 sudo bash -c 'echo xserver-xorg-video-intel hold | dpkg --set-selections'
 229 ```
 230 - save your work then restart the X server with the next command.
 231 ```
 232 sudo service lightdm restart
 233 ```
 234 - After logging in again, check for success with this command and look for DRI3.
 235 ```
 236 xdpyinfo | grep DRI
 237 ```
 238
 239
 240 ## Clone the repository
 241
 242 To create your local git repository:
 243 ```
 244 mkdir YOUR_DEV_DIRECTORY  # it's called GL-Next on Github, but the name doesn't matter
 245 cd YOUR_DEV_DIRECTORY
 246 git clone -o khronos git@gitlab.khronos.org:vulkan/LoaderAndTools.git .
 247 # Or substitute the URL from your forked repo for git@gitlab.khronos.org:vulkan/LoaderAndTools.git above.
 248 ```
 249
 250 ## Linux Build
 251
 252 The sample driver uses cmake and should work with the usual cmake options and utilities.
 253 The standard build process builds the icd, the icd loader and all the tests.
 254
 255 Example debug build:
 256 ```
 257 cd YOUR_DEV_DIRECTORY  # cd to the root of the vk git repository
 258 export KHRONOS_ACCOUNT_NAME= <subversion login name for svn checkout of BIL>
 259 ./update_external_sources.sh  # fetches and builds glslang, llvm, LunarGLASS, and BIL
 260 cmake -H. -Bdbuild -DCMAKE_BUILD_TYPE=Debug
 261 cd dbuild
 262 make
 263 ```
 264
 265 To run VK programs you must tell the icd loader where to find the libraries.
 266 This is described in a specification in the Khronos documentation Git
 267 repository.  See the file:
 268 https://gitlab.khronos.org/vulkan/vulkan/blob/master/ecosystem/LinuxICDs.txt
 269
 270 This specification describes both how ICDs and layers should be properly
 271 packaged, and how developers can point to ICDs and layers within their builds.
 272
 273
 274 ## Validation Test
 275
 276 The test executibles can be found in the dbuild/tests directory. The tests use the Google
 277 gtest infrastructure. Tests available so far:
 278 - vk_layer_validation_tests: Test Vulkan layers.
 279
 280 There are also a few shell and Python scripts that run test collections (eg,
 281 `run_all_tests.sh`).
 282
 283 ## Linux Demos
 284
 285 The demos executables can be found in the dbuild/demos directory. The demos use DRI 3
 286 to render directly onto window surfaces.
 287 - vulkaninfo: report GPU properties
 288 - tri: a textured triangle
 289 - cube: a textured spinning cube
 290
 291 ## Windows System Requirements
 292
 293 Windows 7+ with additional required software packages:
 294
 295 - Microsoft Visual Studio 2013 Professional.  Note: it is possible that lesser/older versions may work, but that has not been tested.
 296 - CMake (from http://www.cmake.org/download/).  Notes:
 297   - Tell the installer to "Add CMake to the system PATH" environment variable.
 298 - Python 3 (from https://www.python.org/downloads).  Notes:
 299   - Select to install the optional sub-package to add Python to the system PATH environment variable.
 300   - 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
 301 - Git (from http://git-scm.com/download/win).
 302   - 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.
 303   - Tell the installer to allow it to be used for "Developer Prompt" as well as "Git Bash".
 304   - Tell the installer to treat line endings "as is" (i.e. both DOS and Unix-style line endings).
 305   - Install each a 32-bit and a 64-bit version, as the 64-bit installer does not install the 32-bit libraries and tools.
 306 - glslang is required for demos and tests.
 307   - You can download and configure it (in a peer directory) here: https://github.com/KhronosGroup/glslang/blob/master/README.md
 308   - 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:
 309     - update_external_sources.bat --build-glslang
 310
 311 Optional software packages:
 312
 313 - Cygwin (from https://www.cygwin.com/).  Notes:
 314   - Cygwin provides some Linux-like tools, which are valuable for obtaining the source code, and running CMake.
 315     Especially valuable are the BASH shell and git packages.
 316   - If you don't want to use Cygwin, there are other shells and environments that can be used.
 317     You can also use a Git package that doesn't come from Cygwin.
 318
 319 ## Windows Build
 320
 321 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.
 322
 323 Example debug x64 build (e.g. in a "Developer Command Prompt for VS2013" window):
 324 ```
 325 cd LoaderAndTools  # cd to the root of the Vulkan git repository
 326 update_external_sources.bat --all
 327 mkdir build
 328 cd build
 329 cmake -G "Visual Studio 12 Win64" ..
 330 ```
 331
 332 At this point, you can use Windows Explorer to launch Visual Studio by double-clicking on the "VULKAN.sln" file in the \build 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 "build" folder.
 333
 334 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.
 335
 336 To run VK programs you must tell the icd loader where to find the libraries.
 337 This is described in a specification in the Khronos documentation Git
 338 repository.  See the file:
 339 https://gitlab.khronos.org/vulkan/vulkan/blob/master/ecosystem/WindowsICDs.txt
 340
 341 This specification describes both how ICDs and layers should be properly
 342 packaged, and how developers can point to ICDs and layers within their builds.
 343
 344 ### Windows 64-bit Installation Notes
 345 If you plan on creating a Windows Install file (done in the windowsRuntimeInstaller sub-directory) you will need to build for both 32-bit and 64-bit Windows since both versions of EXEs and DLLs exist simultaneously on Windows 64.
 346
 347 To do this, simply create and build the release versions of each target:
 348 ```
 349 cd LoaderAndTools  # cd to the root of the Vulkan git repository
 350 update_external_sources.bat --all
 351 mkdir build
 352 cd build
 353 cmake -G "Visual Studio 12 Win64" ..
 354 msbuild ALL_BUILD.vcxproj /p:Platform=x64 /p:Configuration=Release
 355 mkdir build32
 356 cd build32
 357 cmake -G "Visual Studio 12" ..
 358 msbuild ALL_BUILD.vcxproj /p:Platform=x86 /p:Configuration=Release
 359 ```
 360