README.md

   1 Waffle - a library for selecting an OpenGL API and window system at runtime
   2
   3 # Summary
   4
   5 Waffle is a cross-platform library that allows one to defer selection of an
   6 OpenGL API and of window system until runtime. For example, on Linux, Waffle
   7 enables an application to select X11/EGL with an OpenGL 3.3 core profile,
   8 Wayland with OpenGL ES2, and other window system / API combinations.
   9
  10 Waffle's immediate goal is to enable [Piglit] to test multiple OpenGL
  11 flavors in a cross-platform way, and to allow each Piglit test to choose its
  12 OpenGL API and window system at runtime. A future goal is to enable the
  13 ability to record (with another tool such [APITrace]) an application's
  14 OpenGL calls on one operating system or window system, and then replay
  15 that trace on a different system.
  16
  17 For more information, visit to Waffle's website.
  18
  19
  20 [Piglit]: https://piglit.freedesktop.org
  21 [APITrace]: https://github.com/apitrace/apitrace#readme
  22
  23
  24 # Links
  25
  26 - source:         https://gitlab.freedesktop.org/mesa/waffle.git
  27 - gitweb:         https://gitlab.freedesktop.org/mesa/waffle
  28 - issue-tracker:  https://gitlab.freedesktop.org/mesa/waffle/issues
  29 - website:        https://waffle.freedesktop.org/
  30 - mailing-list:   waffle@lists.freedesktop.org
  31 - license:        BSD [https://www.opensource.org/licenses/bsd-license.php]
  32 - maintainer:     Emil Velikov <emil.l.velikov@gmail.com>
  33
  34
  35 # Examples
  36
  37 For example code and makefiles that demonstrate how to use and build with
  38 Waffle, see the following:
  39
  40     - The 'examples' directory in the source repository:
  41       https://gitlab.freedesktop.org/mesa/waffle/tree/master/examples
  42
  43     - Installed examples at $PREFIX/share/doc/waffle-VERSION/examples, if
  44       Waffle is installed on your system.
  45
  46
  47 # Build Requirements
  48
  49 Waffle has two build systems, a mature cmake build system and an new meson
  50 build system. We recommend using meson, but if you run into problems you may
  51 want to try cmake.
  52
  53 ## Linux
  54
  55 On Linux it's recommended to install the cmake or meson package using your
  56 distribution package manager.
  57
  58     Archlinux: pacman -S cmake meson
  59     Fedora 17: yum install cmake meson
  60     Debian: apt-get install cmake meson
  61
  62 To build the manpages or html documentation, xsltproc and the Docbook XSL
  63 stylesheets are required.
  64
  65     Archlinux: pacman -S libxslt docbook-xsl
  66     Fedora 17: yum install libxslt docbook-style-xsl
  67     Debian: apt-get install xsltproc docbook-xsl
  68
  69 If you choose to enable support for a given platform (for example,
  70 -Dwaffle_has_glx=1), then CMake will complain if the necessary libraries are
  71 not installed. Listed below are the required packages for each platform.
  72
  73 If you install Mesa from source, then Mesa must be configured with option
  74 `-D platforms=PLATFORM_LIST`, where PLATFORM_LIST is
  75 a comma-separated list of any combination of "x11", "wayland", and "drm".
  76
  77     - GLX:
  78         - Archlinux: pacman -S libgl libxcb libx11
  79         - Fedora 17: yum install mesa-libGL-devel libxcb-devel libX11-devel
  80         - Debian: apt-get install libgl1-mesa-dev libxcb1-dev libx11-dev
  81
  82     - X11/EGL:
  83         - all: If you choose to install Mesa from source, use -D platforms=x11
  84         - Archlinux: pacman -S libegl libxcb libx11
  85         - Fedora 17: yum install mesa-libEGL-devel libxcb-devel libX11-devel
  86         - Debian: apt-get install libegl1-mesa-dev libxcb1-dev libx11-dev
  87
  88     - Wayland:
  89         - all: Install wayland>=1.0 from source.
  90         - all: Install Mesa from source. Use -D platforms=wayland
  91         - Debian: apt-get install libwayland-dev
  92
  93     - GBM:
  94         - all: Install Mesa from source. Use -D platforms=drm
  95         - Archlinux: pacman -S systemd
  96         - Fedora 17: yum install libdrm-devel
  97         - Debian: apt-get install libgbm-dev libdrm-dev
  98
  99
 100 ## Windows
 101
 102 ### cross-building under Linux
 103
 104 Make sure that CMake or meson is installed on your system.
 105
 106     Archlinux: pacman -S cmake meson
 107     Fedora 17: yum install cmake meson
 108     Debian: apt-get install cmake meson
 109
 110 The MinGW-W64 cross-build toolchain is recommended and its CMake wrapper.
 111
 112     Archlinux: aura -A mingw-w64-gcc mingw-w64-cmake (both are in the aur)
 113     Fedora 17: yum install FINISHME
 114     Debian: apt-get install FINISHME
 115
 116 For meson you will need a mingw cross file.
 117
 118
 119 ### native builds
 120
 121 Install Microsoft Visual Studio 2013 Update 4* or later.
 122 Install 'Visual C++' feature.
 123
 124 ### CMake
 125
 126 Download and install the latest version CMake from the official website:
 127
 128     https://cmake.org/
 129
 130 Download OpenGL Core API and Extension Header Files.
 131
 132     https://www.opengl.org/registry/#headers
 133
 134 Copy the header files to MSVC.
 135
 136     C:\Program Files\Microsoft Visual Studio 12.0\VC\include\GL
 137
 138 ### Meson
 139
 140 Download and install the latest meson from github:
 141
 142     https://github.com/mesonbuild/meson/releases
 143
 144 OR, install python 3.x (currently 3.5 or later is supported) and install meson using pip:
 145
 146     py -3 -m pip install meson
 147
 148 There is no need to copy header files, meson uses a bundled copy
 149
 150
 151 ### CYGWIN
 152 Waffle is not tested to build under CYGWIN and is likely to be broken.
 153 Patches addressing it are more than welcome.
 154
 155 For build requirements, build and installation instructions, refer to the
 156 Linux notes in the relevant sections.
 157
 158
 159 ## Build and Installation
 160
 161 ### Be in the correct directory
 162
 163     git clone https://gitlab.freedesktop.org/mesa/waffle.git
 164     cd waffle
 165
 166 or
 167
 168     tar xvf waffle-0.0.0.tar.xz
 169     cd waffle-0.0.0
 170
 171
 172 ### Configure pkg-config
 173
 174 Compiling for Windows does require any additional dependencies, as such
 175 this step can be omitted.
 176
 177 If any of Waffle's dependencies are installed in custom locations, you must
 178 set the PKG_CONFIG_PATH environment variable. For example, if you installed
 179 a dependeny into /usr/local, then:
 180
 181     export PKG_CONFIG_PATH=/usr/local/share/pkgconfig:/usr/local/$libdir/pkgconfig:$PKG_CONFIG_PATH
 182
 183
 184 ## Building with CMake
 185
 186 ### Configuring
 187
 188 #### Linux and Mac
 189
 190 On Linux and Mac, running CMake with no arguments as below will configure
 191 Waffle for a release build (optimized compiler flags and basic debug symbols)
 192 and will auto-enable support for features whose dependencies are installed:
 193
 194     cmake .
 195
 196 To manually control the configuration process, or to later modify the an
 197 already-configured source tree, run one of the following:
 198
 199     # An ncurses interface to CMake configuration.
 200     ccmake .
 201
 202     # A graphical Qt interface to CMake configuration.
 203     cmake-gui .
 204
 205     # Edit the raw configuration file.
 206     vim CMakeCache.txt
 207
 208 All configuration options can also be set on the command line during the
 209 *initial* invocation of cmake. For example, to configure Waffle for a debug
 210 build, require support for Wayland, and install into '/usr' instead of
 211 '/usr/local', run the following:
 212
 213     cmake -DCMAKE_BUILD_TYPE=Debug \
 214           -DCMAKE_INSTALL_PREFIX=/usr \
 215           -Dwaffle_has_wayland=1 \
 216           .
 217
 218 #### Windows - cross-building under Linux
 219
 220 The following sh snippet can be used to ease the configuration process.
 221
 222     _architectures="i686-w64-mingw32 x86_64-w64-mingw32"
 223     unset LDFLAGS
 224     for _arch in ${_architectures}; do
 225       _install_prefix=/usr/${_arch}
 226       mkdir -p build-${_arch} && pushd build-${_arch}
 227       ${_arch}-cmake .. \
 228         -DCMAKE_INSTALL_PREFIX=${_install_prefix} \
 229         -DCMAKE_INSTALL_LIBDIR=${_install_prefix}/lib \
 230         \
 231         -Dwaffle_build_tests=0 \
 232         -Dwaffle_build_examples=1
 233       make
 234       popd
 235     done
 236
 237 Make sure to adjust _install_prefix to "" if the resulting library will
 238 not be used for further cross-building.
 239
 240
 241 #### Windows - native builds
 242
 243 For native Windows builds, one must provide a generator argument and
 244 optionally a toolset if the resulting library must be compatible with
 245 Windows XP. When the resulting library is to be 64bit "Win64" needs to be
 246 appended to the generator argument.
 247
 248     @echo Configuring Waffle as Windows Vista compatible 32bit library
 249     cmake -G "Visual Studio 12" -H%CD% -B%CD%\build\msvc32 -DCMAKE_INSTALL_PREFIX=""
 250
 251     @echo Configuring Waffle as Windows Vista compatible 64bit library
 252     cmake -G "Visual Studio 12 Win64" -H%CD% -B%CD%\build\msvc64 -DCMAKE_INSTALL_PREFIX=""
 253
 254     @echo Configuring Waffle as Windows XP compatible 32bit library
 255     cmake -G "Visual Studio 12" -T "v120_xp" -H%CD% -B%CD%\build\msvc32 -DCMAKE_INSTALL_PREFIX=""
 256
 257 For alternative control of the configuration process, or to later modify an
 258 already-configured source tree, run the graphical Qt interface via:
 259
 260     cmake-gui
 261
 262 ### Build and Install
 263
 264 The following commands build Waffle, run its tests, installs the project and
 265 creates a binary archive in a platform agnostic way.
 266
 267 Note that not all steps may be required in your case and the configuration
 268 settings (cache) are located in the current directory as indicated by ".".
 269
 270     cmake --build .
 271     cmake --build . --target check
 272     cmake --build . --target check-func
 273     cmake --build . --target install
 274     cpack
 275
 276 Calling `cmake ... check` only runs unittests that do not access the native
 277 OpenGL platform. To run additional functional tests, which do access the
 278 native OpenGL platform, call `cmake ... check-func`.
 279
 280 #### Linux and Mac
 281
 282 On Linux and Mac the default CMake generator is Unix Makefiles, as such we
 283 can use an alternative version of the above commands:
 284
 285     make
 286     make check
 287     make check-func
 288     make install
 289     make package
 290
 291
 292 #### Windows - cross-building under Linux
 293
 294     _architectures="i686-w64-mingw32 x86_64-w64-mingw32"
 295     unset LDFLAGS
 296     for _arch in ${_architectures}; do
 297       pushd build-${_arch}
 298       make
 299       make install
 300       make package
 301       popd
 302     done
 303
 304 Note: Running the tests (`make check` and/or `make check-func`) is not tested
 305 but may work if the appropriate environment is setup via wine.
 306
 307 #### Windows - native builds
 308
 309 One can manage the build/install/package process via Visual Studio's GUI
 310 or via the command line.
 311
 312 When using the GUI open .\build\msvc*\waffle-VERSION.sln, where * can be
 313 either 32 or 64 depending on your requirements.
 314
 315 If building via the command line, navigate to the correct folder and invoke
 316 the desired command as outlined in `Section 3. Build and Install`
 317
 318 For example the following will build 32bit Waffle and will package/archive
 319 it into a file called waffle1-VERSION-win32.zip.
 320
 321     @echo Preparing to build 32 bit version of waffle
 322     cd .\build\msvc32
 323     cmake --build .
 324     cpack
 325
 326
 327 ## Building with Meson
 328
 329 Once meson is installed you can configure the build with meson:
 330
 331     meson builddir
 332
 333 The default buildtype for waffle is `debugoptimzed`, which has debugging
 334 symbols but is optimized. This is equivalent to the CMake builds `release`.
 335 Meson's release mode does not have debugging symbols. If you wish to pass your
 336 own flags via CFLAGS you should set buildtype to `plain`:
 337
 338     meson builddir -Dbuildtype=plain -Dc_args='-03 -march=native'
 339
 340 __NOTE__: meson only read CFLAGS (and CXXFLAGS, etc) at initial configuration
 341 time. If you wish to change these flags you'll need to use the meson command
 342 line option `-D${lang}_args=` (such as `-Dc_args=`). This can be used at
 343 configure time as well. It is _highly_ recommended that you use -Dc_args
 344 instead of CFLAGS.
 345
 346 You can check configuration options by:
 347
 348     meson configure builddir
 349
 350 Meson will be default try to find dependencies and enables targets that have
 351 dependencies met. This behavior can be controlled using configure flags.
 352
 353 Meson detects compilers from the environment, rather from a toolchain file like
 354 CMake does, the easiest way to set up MSVC is to launch a visual studio
 355 terminal prompt, and run meson from there. Meson supports using both ninja (the
 356 default) and msbuild on windows, to use msbuild add:
 357
 358     meson builddir -Dbackend=vs
 359
 360 On mac there is an xcode backend for meson, but it is not very mature and is
 361 not recommended.
 362
 363 To cross compile pass the location of a cross file, as described
 364 [here](https://mesonbuild.com/Cross-compilation.html).
 365
 366 If you want to build tests and don't have cmocka installed, meson will download
 367 and build cmocka for you while building the rest of waffle. This works on
 368 windows, but due to the way that .dll files work on windows it is only
 369 supported if you add:
 370
 371     -Ddefault_library=static
 372
 373 Which will also build libwaffle as a static library.