README.txt

   1 Waffle - a library for selecting an OpenGL API and window system at runtime
   2
   3 Summary
   4 =======
   5
   6 Waffle is a cross-platform library that allows one to defer selection of an
   7 OpenGL API and of window system until runtime. For example, on Linux, Waffle
   8 enables an application to select X11/EGL with an OpenGL 3.3 core profile,
   9 Wayland with OpenGL ES2, and other window system / API combinations.
  10
  11 Waffle's immediate goal is to enable Piglit [1] to test multiple OpenGL
  12 flavors in a cross-platform way, and to allow each Piglit test to choose its
  13 OpenGL API and window system at runtime. A future goal is to enable the
  14 ability to record (with another tool such APITrace [2]) an application's
  15 OpenGL calls on one operating system or window system, and then replay
  16 that trace on a different system.
  17
  18 For more information, visit to Waffle's website.
  19
  20
  21 [1] http://piglit.freedesktop.org
  22 [2] http://github.com/apitrace/apitrace#readme
  23
  24
  25 Links
  26 =====
  27
  28 source:         git://github.com/waffle-gl/waffle
  29 gitweb:         https://github.com/waffle-gl/waffle
  30 issue-tracker:  https://github.com/waffle-gl/waffle/issues
  31 website:        http://www.waffle-gl.org
  32 mailing-list:   waffle@lists.freedesktop.org
  33 license:        BSD [http://www.opensource.org/licenses/bsd-license.php]
  34 maintainer:     Chad Versace <chad.versace@linux.intel.com>
  35
  36
  37 Examples
  38 ========
  39
  40 For example code and makefiles that demonstrate how to use and build with
  41 Waffle, see the following:
  42
  43     - The 'examples' directory in the source repository:
  44       https://github.com/waffle-gl/waffle/tree/master/examples
  45
  46     - Installed examples at $PREFIX/share/doc/waffle-VERSION/examples, if
  47       Waffle is installed on your system.
  48
  49
  50 Build Requirements
  51 ==================
  52
  53 Waffle uses CMake for its build system.
  54
  55 Linux
  56 -----
  57 On Linux it's recommended to install the cmake package using your
  58 distribution package manager.
  59
  60     Archlinux: pacman -S cmake
  61     Fedora 17: yum install cmake
  62     Debian: apt-get install cmake
  63
  64 To build the manpages or html documentation, xsltproc and the Docbook XSL
  65 stylesheets are required.
  66
  67     Archlinux: pacman -S libxslt docbook-xsl
  68     Fedora 17: yum install libxslt docbook-style-xsl
  69     Debian: apt-get install xsltproc docbook-xsl
  70
  71 If you choose to enable support for a given platform (for example,
  72 -Dwaffle_has_glx=1), then CMake will complain if the necessary libraries are
  73 not installed. Listed below are the required packages for each platform.
  74
  75 If you install Mesa from source, then Mesa must be configured with option
  76 `--with-egl-platforms=PLATFORM_LIST`, where PLATFORM_LIST is
  77 a comman-separated list of any combination of "x11", "wayland", and "drm".
  78
  79     - GLX:
  80         - Archlinux: pacman -S libgl libxcb libx11
  81         - Fedora 17: yum install mesa-libGL-devel libxcb-devel libX11-devel
  82         - Debian: apt-get install libgl1-mesa-dev libxcb1-dev libx11-dev
  83
  84     - X11/EGL:
  85         - all: If you choose to install Mesa from source, use --with-egl-platforms=x11.
  86         - Archlinux: pacman -S libegl libxcb libx11
  87         - Fedora 17: yum install mesa-libEGL-devel libxcb-devel libX11-devel
  88         - Debian: apt-get install libegl1-mesa-dev libxcb1-dev libx11-dev
  89
  90     - Wayland:
  91         - all: Install wayland>=1.0 from source.
  92         - all: Install mesa-9.1-devel from source. Use --with-egl-platforms=wayland.
  93         - Debian: apt-get install libwayland-dev
  94
  95     - GBM:
  96         - all: Install mesa-9.1-devel from source. Use --with-egl-platforms=drm.
  97         - Archlinux: pacman -S systemd
  98         - Fedora 17: yum install libudev-devel
  99         - Debian: apt-get install libgbm-dev libudev-dev
 100
 101
 102 Windows - cross-building under Linux
 103 ------------------------------------
 104 Make sure that CMake is installed on your system.
 105
 106     Archlinux: pacman -S cmake
 107     Fedora 17: yum install cmake
 108     Debian: apt-get install cmake
 109
 110 The MinGW-W64 cross-build toolchain is recommended and its CMake wrapper.
 111
 112     Archlinux: pacman -S mingw-w64-gcc mingw-w64-cmake (latter is in AUR)
 113     Fedora 17: yum install FINISHME
 114     Debian: apt-get install FINISHME
 115
 116
 117 Windows - native builds
 118 -----------------------
 119 Download and install the latest version CMake from the official website:
 120
 121     http://cmake.org/
 122
 123 Install Microsoft Visual Studio 2013 Update 4* or later.
 124 Install 'Visual C++' feature.
 125
 126 Download OpenGL Core API and Extension Header Files.
 127
 128     http://www.opengl.org/registry/#headers
 129
 130 Copy the header files to MSVC.
 131
 132     C:\Program Files\Microsoft Visual Studio 12.0\VC\include\GL
 133
 134
 135 [*] Waffle heavily requires on features introduced by the C99 standard. As
 136 such only reasonable compiler (at the time of writing) from the Microsoft
 137 Visual Compiler series is MSVC 2013. Building with older versions is likely
 138 to be broken.
 139
 140 Windows - CYGWIN
 141 ----------------
 142 Waffle is not tested to build under CYGWIN and is likely to be broken.
 143 Patches addressing it are more than welcome.
 144
 145 For build requirements, build and installation instructions, refer to the
 146 Linux notes in the relevant sections.
 147
 148
 149 Build and Installation
 150 ======================
 151
 152 0. Be in the correct directory
 153 ------------------------------
 154
 155     git clone git://github.com/waffle-gl/waffle
 156     cd waffle
 157
 158 or
 159
 160     tar xvf waffle-0.0.0.tar.xz
 161     cd waffle-0.0.0
 162
 163
 164 1. Configure pkg-config
 165 -----------------------
 166 Compiling for Windows does require any additional dependencies, as such
 167 this step can be omitted.
 168
 169 If any of Waffle's dependencies are installed in custom locations, you must
 170 set the PKG_CONFIG_PATH environment variable. For example, if you installed
 171 a dependeny into /usr/local, then:
 172
 173     export PKG_CONFIG_PATH=/usr/local/share/pkgconfig:/usr/local/$libdir/pkgconfig:$PKG_CONFIG_PATH
 174
 175
 176 2. Configure CMake
 177 ------------------
 178
 179 2.1 Linux and Mac
 180 -----------------
 181 On Linux and Mac, running CMake with no arguments as below will configure
 182 Waffle for a release build (optimized compiler flags and basic debug symbols)
 183 and will auto-enable support for features whose dependencies are installed:
 184
 185     cmake .
 186
 187 To manually control the configuration process, or to later modify the an
 188 already-configured source tree, run one of the following:
 189
 190     # An ncurses interface to CMake configuration.
 191     ccmake .
 192
 193     # A graphical Qt interface to CMake configuration.
 194     cmake-gui .
 195
 196     # Edit the raw configuration file.
 197     vim CMakeCache.txt
 198
 199 All configuration options can also be set on the command line during the
 200 *initial* invocation of cmake. For example, to configure Waffle for a debug
 201 build, require support for Wayland, and install into '/usr' instead of
 202 '/usr/local', run the following:
 203
 204     cmake -DCMAKE_BUILD_TYPE=Debug \
 205           -DCMAKE_INSTALL_PREFIX=/usr \
 206           -Dwaffle_has_wayland=1 \
 207           .
 208
 209 2.2 Windows - cross-building under Linux
 210 ----------------------------------------
 211 The following sh snippet can be used to ease the configuration process.
 212
 213     _architectures="i686-w64-mingw32 x86_64-w64-mingw32"
 214     unset LDFLAGS
 215     for _arch in ${_architectures}; do
 216       _install_prefix=/usr/${_arch}
 217       mkdir -p build-${_arch} && pushd build-${_arch}
 218       ${_arch}-cmake .. \
 219         -DCMAKE_INSTALL_PREFIX=${_install_prefix} \
 220         -DCMAKE_INSTALL_LIBDIR=${_install_prefix}/lib \
 221         \
 222         -Dwaffle_build_tests=0 \
 223         -Dwaffle_build_examples=1
 224       make
 225       popd
 226     done
 227
 228 Make sure to adjust _install_prefix to "" if the resulting library will
 229 not be used for further cross-building.
 230
 231
 232 2.3 Windows - native builds
 233 ---------------------------
 234
 235 For native Windows builds, one must provide a generator argument and
 236 optionally a toolset if the resulting library must be compatible with
 237 Windows XP. When the resulting library is to be 64bit "Win64" needs to be
 238 appended to the generator argument.
 239
 240     @echo Configuring Waffle as Windows Vista compatible 32bit library
 241     cmake -G "Visual Studio 12" -H%CD% -B%CD%\build\msvc32 -DCMAKE_INSTALL_PREFIX=""
 242
 243     @echo Configuring Waffle as Windows Vista compatible 64bit library
 244     cmake -G "Visual Studio 12 Win64" -H%CD% -B%CD%\build\msvc64 -DCMAKE_INSTALL_PREFIX=""
 245
 246     @echo Configuring Waffle as Windows XP compatible 32bit library
 247     cmake -G "Visual Studio 12" -T "v120_xp" -H%CD% -B%CD%\build\msvc32 -DCMAKE_INSTALL_PREFIX=""
 248
 249 For alternative control of the configuration process, or to later modify an
 250 already-configured source tree, run the graphical Qt interface via:
 251
 252     cmake-gui
 253
 254 3. Build and Install
 255 --------------------
 256 The following commands build Waffle, run its tests, installs the project and
 257 creates a binary archive in a platform agnostic way.
 258
 259 Note that not all steps may be required in your case and the configuration
 260 settings (cache) are located in the current directory as indicated by ".".
 261
 262     cmake --build .
 263     cmake --build . --target check
 264     cmake --build . --target check-func
 265     cmake --build . --target install
 266     cpack
 267
 268 Calling `cmake ... check` only runs unittests that do not access the native
 269 OpenGL platform. To run additional functional tests, which do access the
 270 native OpenGL platform, call `cmake ... check-func`.
 271
 272 3.1 Linux and Mac
 273 -----------------
 274 On Linux and Mac the default CMake generator is Unix Makefiles, as such we
 275 can use an alternative version of the above commands:
 276
 277     make
 278     make check
 279     make check-func
 280     make install
 281     make package
 282
 283
 284 3.2 Windows - cross-building under Linux
 285 ----------------------------------------
 286
 287     _architectures="i686-w64-mingw32 x86_64-w64-mingw32"
 288     unset LDFLAGS
 289     for _arch in ${_architectures}; do
 290       pushd build-${_arch}
 291       make
 292       make install
 293       make package
 294       popd
 295     done
 296
 297 Note: Running the tests (`make check` and/or `make check-func`) is not tested
 298 but may work if the appropriate environment is setup via wine.
 299
 300
 301 3.3 Windows - native builds
 302 ---------------------------
 303 One can manage the build/install/package process via Visual Studio's GUI
 304 or via the command line.
 305
 306 When using the GUI open .\build\msvc*\waffle-VERSION.sln, where * can be
 307 either 32 or 64 depending on your requirements.
 308
 309 If building via the command line, navigate to the correct folder and invoke
 310 the desired command as outlined in `Section 3. Build and Install`
 311
 312 For example the following will build 32bit Waffle and will package/archive
 313 it into a file called waffle1-VERSION-win32.zip.
 314
 315     @echo Preparing to build 32 bit version of waffle
 316     cd .\build\msvc32
 317     cmake --build .
 318     cpack