BUILD.md

   1 # Build Instructions
   2 This project fully supports Linux today.
   3 Support for Windows is for the loader, layers, and the Glave debugger (additional info below).  Additional Windows support will be coming in Q1'15.
   4 Support for Android is TBD.
   5
   6 ##Git the Bits
   7
   8 Make sure you have access to the Khronos Github repository. If not, send an email to
   9 jens@lunarg.com or courtney@lunarg.com and we can add you if you have a Khronos account.
  10 Also need to be sure that your Github account name is in your Khronos profile or the
  11 system will disable Github access. Once you have access to the Khronos Github repository,
  12 the preferred work flow is to fork that repo, commit work on to your fork and then issue a
  13 pull request to integrate that work into the Khronos repo. If that's too much, it's okay
  14 to clone the Khronos repository directly.
  15
  16 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).
  17
  18 ##Linux System Requirements
  19 Ubuntu 14.10 needed for DRI 3
  20
  21 ```
  22 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
  23 sudo apt-get build-dep mesa
  24 ```
  25 Warning: Recent versions of 14.10 have **REMOVED** DRI 3.
  26 Version: 2:2.99.914-1~exp1ubuntu4.1 is known to work.
  27 To see status of this package:
  28 ```
  29 dpkg -s xserver-xorg-video-intel
  30 ```
  31
  32 Note:
  33 Version 2:2.99.914-1~exp1ubuntu4.2 does not work anymore.
  34 To install the working driver from launchpadlibrarian.net:
  35 - Remove the current driver:
  36 ```
  37 sudo apt-get purge xserver-xorg-video-intel
  38 ```
  39 - Download the old driver:
  40 ```
  41 wget http://launchpadlibrarian.net/189418339/xserver-xorg-video-intel_2.99.914-1%7Eexp1ubuntu4.1_amd64.deb
  42 ```
  43 - Install the driver:
  44 ```
  45 sudo dpkg -i xserver-xorg-video-intel_2.99.914-1~exp1ubuntu4.1_amd64.deb
  46 ```
  47 - Either restart Ubuntu or just X11.
  48
  49 ## Clone the repository
  50
  51 To create your local git repository:
  52 ```
  53 mkdir YOUR_DEV_DIRECTORY  # it's called GL-Next on Github, but the name doesn't matter
  54 cd YOUR_DEV_DIRECTORY
  55 git clone -o khronos git@github.com:KhronosGroup/GL-Next.git .
  56 # Or substitute the URL from your forked repo for git@github.com:KhronosGroup above.
  57 ```
  58
  59 ##Linux Build
  60
  61 The sample driver uses cmake and should work with the usual cmake options and utilities.
  62 The standard build process builds the icd, the icd loader and all the tests.
  63
  64 Example debug build:
  65 ```
  66 cd YOUR_DEV_DIRECTORY  # cd to the root of the xgl git repository
  67 export KHRONOS_ACCOUNT_NAME= <subversion login name for svn checkout of BIL>
  68 ./update_external_sources.sh  # fetches and builds glslang, llvm, LunarGLASS, and BIL
  69 cmake -H. -Bdbuild -DCMAKE_BUILD_TYPE=Debug
  70 cd dbuild
  71 make
  72 ```
  73
  74 To run XGL programs you must tell the icd loader where to find the libraries. Set the
  75 environment variable LIBXGL_DRIVERS_PATH to the driver path. For example:
  76 ```
  77 export LIBXGL_DRIVERS_PATH=$PWD/icd/intel
  78 ```
  79
  80 To enable debug and validation layers with your XGL programs you must tell the icd loader
  81 where to find the layer libraries. Set the environment variable LIBXGL_LAYERS_PATH to
  82 the layer folder and indicate the layers you want loaded via LIBXGL_LAYER_NAMES.
  83 For example, to enable the APIDump and DrawState layers, do:
  84 ```
  85 export LIBXGL_LAYERS_PATH=$PWD/layers
  86 export LIBXGL_LAYER_NAMES=APIDump:DrawState
  87 ```
  88
  89 ##Linux Test
  90
  91 The test executibles can be found in the dbuild/tests directory. The tests use the Google
  92 gtest infrastructure. Tests available so far:
  93 - xglinfo: Report GPU properties
  94 - xglbase: Test basic entry points
  95 - xgl_blit_tests: Test XGL Blits (copy, clear, and resolve)
  96 - xgl_image_tests: Test XGL image related calls needed by render_test
  97 - xgl_render_tests: Render a single triangle with XGL. Triangle will be in a .ppm in
  98 the current directory at the end of the test.
  99
 100 ##Linux Demos
 101
 102 The demos executables can be found in the dbuild/demos directory. The demos use DRI 3
 103 to render directly onto window surfaces.
 104 - tri: a textured triangle
 105 - cube: a textured spinning cube
 106
 107 ##Linux Render Nodes
 108
 109 The render tests depend on access to DRM render nodes.
 110 To make that available, a couple of config files need to be created to set a module option
 111 and make accessible device files.
 112 The system will need to be rebooted with these files in place to complete initialization.
 113 These commands will create the config files.
 114
 115 ```
 116 sudo tee /etc/modprobe.d/drm.conf << EOF
 117 # Enable render nodes
 118 options drm rnodes=1
 119 EOF
 120 # this will add the rnodes=1 option into the boot environment
 121 sudo update-initramfs -k all -u
 122 ```
 123 ```
 124 sudo tee /etc/udev/rules.d/drm.rules << EOF
 125 # Add permissions to render nodes
 126 SUBSYSTEM=="drm", ACTION=="add", DEVPATH=="/devices/*/renderD*", MODE="020666"
 127 EOF
 128 ```
 129
 130 ##Windows System Requirements
 131
 132 Windows 7+ with additional, software:
 133
 134 - Microsoft Visual Studio 2013 Professional.  Note: it is possible that lesser/older versions may work, but that has not been tested.
 135 - CMake (from http://www.cmake.org/download/).  Notes:
 136   - In order to build the Glave debugger, you need at least version 3.0.
 137   - Tell the installer to "Add CMake to the system PATH" environment variable.
 138 - Python 3 (from https://www.python.org/downloads).  Notes:
 139   - Select to install the optional sub-package to add Python to the system PATH environment variable.
 140   - Need python3.3 or later to get the Windows py.exe launcher that is used to get pyhton3 rather than python2 if both are installed on Windows
 141 - Optional Packages:
 142   - Qt 5.3 (from http://www.qt.io/download/).  Notes:
 143     - Qt 5.3 is required in order to build the Glave debugger (GUI).  The Glave trace and replay tools can be built without Qt, but the debugger/GUI is built on top of Qt 5.3.  Various dependencies, from the Qt package are copied to the directory where the Glave debugger and its libraries are built.  In order to copy and run the debugger in another directory, these libraries must also be copied.  Other notes:
 144     - While there are commercial licenses, you can also use the "Community" (free) license.
 145     - By default, the installer will select the latest version (e.g. Qt 5.4) as well as some other components.  You must select "Qt 5.3"!  You can have multiple versions installed (e.g. Qt 5.2.1, 5.3, and 5.4).
 146     - Installing Qt takes a long time.
 147   - Cygwin (from https://www.cygwin.com/).  Notes:
 148     - Cygwin provides some Linux-like tools, which are valuable for obtaining the source code, and running CMake.
 149       Especially valuable are the BASH shell and git packages.
 150     - If you don't want to use Cygwin, there are other shells and environments that can be used.
 151       You can also use a Git package that doesn't come from Cygwin.
 152   - Git (from http://git-scm.com/download/win).
 153
 154 ##Windows Build
 155
 156 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.
 157
 158 Example debug build:
 159 ```
 160 cd GL-Next  # cd to the root of the xgl git repository
 161 mkdir _out64
 162 cd _out64
 163 cmake -G "Visual Studio 12 Win64" -DCMAKE_BUILD_TYPE=Debug ..
 164 ```
 165
 166 At this point, you can use Windows Explorer to launch Visual Studio by double-clicking on the "XGL.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.
 167
 168 XGL programs must be able to find and use the XGL.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.
 169
 170 To run XGL programs you must have an appropriate ICD (installable client driver) that is either installed in the C:\Windows\System32 folder, or pointed to by the registry and/or an environment variable:
 171
 172 - Registry:
 173   - Root Key: HKEY_LOCAL_MACHINE
 174   - Key: "SOFTWARE\XGL"
 175   - Value: "XGL_DRIVERS_PATH" (semi-colon-delimited set of folders to look for ICDs)
 176 - Environment Variable: "XGL_DRIVERS_PATH" (semi-colon-delimited set of folders to look for ICDs)
 177
 178 Note: If both the registry value and environment variable are used, they are concatenated into a new semi-colon-delimited list of folders.
 179
 180 Note: Environment variables on Windows cannot be set with Cygwin, but must be set via the Windows Control Panel, and generally require a system restart in order to take effect.  Here is how to set this environment variable on a Windows 7 system:
 181
 182 - Launch Control Panel (e.g. Start->Control Panel)
 183 - Within the search box, type "environment variable" and click on "Edit the system environment variables" (or navigate there via "System and Security->System->Advanced system settings").
 184 - This will launch a window with several tabs, one of which is "Advanced".  Click on the "Environment Variables..." button.
 185 - For either "User variables" or "System variables" click "New...".
 186 - Enter "XGL_DRIVERS_PATH" as the variable name, and an appropriate Windows path to where your driver DLL is (e.g. C:\Users\username\GL-Next\_out64\icd\drivername\Debug).
 187
 188 It is possible to specify multiple icd folders.  Simply use a semi-colon (i.e. ";") to separate folders in the environment variable.
 189
 190 The icd loader searches in all of the folders for files that are named "XGL_*.dll" (e.g. "XGL_foo.dll").  It attempts to dynamically load these files, and look for appropriate functions.
 191
 192 To enable debug and validation layers with your XGL programs you must tell the icd loader
 193 where to find the layer libraries, and which ones you desire to use.  The default folder for layers is C:\Windows\System32. Again, this can be pointed to by the registry and/or an environment variable:
 194
 195 - Registry:
 196   - Root Key: HKEY_LOCAL_MACHINE
 197   - Key: "System\XGL"
 198   - Value: "XGL_LAYERS_PATH" (semi-colon-delimited set of folders to look for layers)
 199   - Value: "XGL_LAYER_NAMES" (semi-colon-delimited list of layer names)
 200 - Environment Variables:
 201   - "XGL_LAYERS_PATH" (semi-colon-delimited set of folders to look for layers)
 202   - "XGL_LAYER_NAMES" (semi-colon-delimited list of layer names)
 203
 204 Note: If both the registry value and environment variable are used, they are concatenated into a new semi-colon-delimited list.
 205
 206 The icd loader searches in all of the folders for files that are named "XGLLayer*.dll" (e.g. "XGLLayerParamChecker.dll").  It attempts to dynamically load these files, and look for appropriate functions.