README.md 11.9 KB
Newer Older
1
Waffle - a library for selecting an OpenGL API and window system at runtime
Chad Versace's avatar
Chad Versace committed
2

3
# Summary
Chad Versace's avatar
Chad Versace committed
4

5 6 7 8
Waffle is a cross-platform library that allows one to defer selection of an
OpenGL API and of window system until runtime. For example, on Linux, Waffle
enables an application to select X11/EGL with an OpenGL 3.3 core profile,
Wayland with OpenGL ES2, and other window system / API combinations.
Chad Versace's avatar
Chad Versace committed
9

10
Waffle's immediate goal is to enable [Piglit] to test multiple OpenGL
11 12
flavors in a cross-platform way, and to allow each Piglit test to choose its
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 15
OpenGL calls on one operating system or window system, and then replay
that trace on a different system.
Chad Versace's avatar
Chad Versace committed
16

17
For more information, visit to Waffle's website.
18

Chad Versace's avatar
Chad Versace committed
19

20 21
[Piglit]: http://piglit.freedesktop.org
[APITrace]: http://github.com/apitrace/apitrace#readme
Chad Versace's avatar
Chad Versace committed
22 23


24
# Links
25

Eric Engestrom's avatar
Eric Engestrom committed
26 27 28 29 30 31 32
- source:         https://gitlab.freedesktop.org/mesa/waffle.git
- gitweb:         https://gitlab.freedesktop.org/mesa/waffle
- issue-tracker:  https://gitlab.freedesktop.org/mesa/waffle/issues
- website:        http://www.waffle-gl.org
- mailing-list:   waffle@lists.freedesktop.org
- license:        BSD [http://www.opensource.org/licenses/bsd-license.php]
- maintainer:     Chad Versace <chad.versace@linux.intel.com>
33 34


35
# Examples
36 37 38 39

For example code and makefiles that demonstrate how to use and build with
Waffle, see the following:

40
    - The 'examples' directory in the source repository:
41
      https://gitlab.freedesktop.org/mesa/waffle/tree/master/examples
42 43 44 45 46

    - Installed examples at $PREFIX/share/doc/waffle-VERSION/examples, if
      Waffle is installed on your system.


47
# Build Requirements
48

Dylan Baker's avatar
Dylan Baker committed
49 50 51
Waffle has two build systems, a mature cmake build system and an new meson
build system. We recommend using meson, but if you run into problems you may
want to try cmake.
52

53 54
## Linux

Dylan Baker's avatar
Dylan Baker committed
55
On Linux it's recommended to install the cmake or meson package using your
56
distribution package manager.
57

Dylan Baker's avatar
Dylan Baker committed
58 59 60
    Archlinux: pacman -S cmake meson
    Fedora 17: yum install cmake meson
    Debian: apt-get install cmake meson
61

62 63
To build the manpages or html documentation, xsltproc and the Docbook XSL
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 70 71 72 73
If you choose to enable support for a given platform (for example,
-Dwaffle_has_glx=1), then CMake will complain if the necessary libraries are
not installed. Listed below are the required packages for each platform.

If you install Mesa from source, then Mesa must be configured with option
74 75
`-D platforms=PLATFORM_LIST`, where PLATFORM_LIST is
a comma-separated list of any combination of "x11", "wayland", and "drm".
76 77 78

    - GLX:
        - 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 89

    - Wayland:
        - 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 libudev-devel
97
        - Debian: apt-get install libgbm-dev libudev-dev
98 99


100 101 102 103
## Windows 

### cross-building under Linux

Dylan Baker's avatar
Dylan Baker committed
104
Make sure that CMake or meson is installed on your system.
105

Dylan Baker's avatar
Dylan Baker committed
106 107 108
    Archlinux: pacman -S cmake meson
    Fedora 17: yum install cmake meson
    Debian: apt-get install cmake meson
109 110 111

The MinGW-W64 cross-build toolchain is recommended and its CMake wrapper.

Dylan Baker's avatar
Dylan Baker committed
112
    Archlinux: aura -A mingw-w64-gcc mingw-w64-cmake (both are in the aur)
113 114 115
    Fedora 17: yum install FINISHME
    Debian: apt-get install FINISHME

Dylan Baker's avatar
Dylan Baker committed
116 117
For meson you will need a mingw cross file.

118

119 120
### native builds

Dylan Baker's avatar
Dylan Baker committed
121 122 123 124 125
Install Microsoft Visual Studio 2013 Update 4* or later.
Install 'Visual C++' feature.

### CMake

126 127 128 129 130 131 132 133 134 135 136 137
Download and install the latest version CMake from the official website:

    http://cmake.org/

Download OpenGL Core API and Extension Header Files.

    http://www.opengl.org/registry/#headers

Copy the header files to MSVC.

    C:\Program Files\Microsoft Visual Studio 12.0\VC\include\GL

Dylan Baker's avatar
Dylan Baker committed
138 139 140 141 142 143 144 145 146 147 148
### Meson

Download and install the latest meson from github:

    https://github.com/mesonbuild/meson/releases

OR, install python 3.x (currently 3.5 or later is supported) and install meson using pip:

    py -3 -m pip install meson

There is no need to copy header files, meson uses a bundled copy
149 150


151
### CYGWIN
152 153 154 155 156 157 158
Waffle is not tested to build under CYGWIN and is likely to be broken.
Patches addressing it are more than welcome.

For build requirements, build and installation instructions, refer to the
Linux notes in the relevant sections.


159
## Build and Installation
160

161
### Be in the correct directory
162

163
    git clone https://gitlab.freedesktop.org/mesa/waffle.git
164 165 166 167 168 169 170
    cd waffle

or

    tar xvf waffle-0.0.0.tar.xz
    cd waffle-0.0.0

Chad Versace's avatar
Chad Versace committed
171

172
### Configure pkg-config
173

174 175 176
Compiling for Windows does require any additional dependencies, as such
this step can be omitted.

177 178 179 180 181 182
If any of Waffle's dependencies are installed in custom locations, you must
set the PKG_CONFIG_PATH environment variable. For example, if you installed
a dependeny into /usr/local, then:

    export PKG_CONFIG_PATH=/usr/local/share/pkgconfig:/usr/local/$libdir/pkgconfig:$PKG_CONFIG_PATH

183

Dylan Baker's avatar
Dylan Baker committed
184 185 186
## Building with CMake

### Configuring
187

188
#### Linux and Mac
189

190 191 192 193 194
On Linux and Mac, running CMake with no arguments as below will configure
Waffle for a release build (optimized compiler flags and basic debug symbols)
and will auto-enable support for features whose dependencies are installed:

    cmake .
195

196 197
To manually control the configuration process, or to later modify the an
already-configured source tree, run one of the following:
Chad Versace's avatar
Chad Versace committed
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 209 210 211
All configuration options can also be set on the command line during the
*initial* invocation of cmake. For example, to configure Waffle for a debug
build, require support for Wayland, and install into '/usr' instead of
'/usr/local', run the following:
212

213
    cmake -DCMAKE_BUILD_TYPE=Debug \
214
          -DCMAKE_INSTALL_PREFIX=/usr \
215 216
          -Dwaffle_has_wayland=1 \
          .
217

218
#### Windows - cross-building under Linux
219

220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240
The following sh snippet can be used to ease the configuration process.

    _architectures="i686-w64-mingw32 x86_64-w64-mingw32"
    unset LDFLAGS
    for _arch in ${_architectures}; do
      _install_prefix=/usr/${_arch}
      mkdir -p build-${_arch} && pushd build-${_arch}
      ${_arch}-cmake .. \
        -DCMAKE_INSTALL_PREFIX=${_install_prefix} \
        -DCMAKE_INSTALL_LIBDIR=${_install_prefix}/lib \
        \
        -Dwaffle_build_tests=0 \
        -Dwaffle_build_examples=1
      make
      popd
    done

Make sure to adjust _install_prefix to "" if the resulting library will
not be used for further cross-building.


241
#### Windows - native builds
242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261

For native Windows builds, one must provide a generator argument and
optionally a toolset if the resulting library must be compatible with
Windows XP. When the resulting library is to be 64bit "Win64" needs to be
appended to the generator argument.

    @echo Configuring Waffle as Windows Vista compatible 32bit library
    cmake -G "Visual Studio 12" -H%CD% -B%CD%\build\msvc32 -DCMAKE_INSTALL_PREFIX=""

    @echo Configuring Waffle as Windows Vista compatible 64bit library
    cmake -G "Visual Studio 12 Win64" -H%CD% -B%CD%\build\msvc64 -DCMAKE_INSTALL_PREFIX=""

    @echo Configuring Waffle as Windows XP compatible 32bit library
    cmake -G "Visual Studio 12" -T "v120_xp" -H%CD% -B%CD%\build\msvc32 -DCMAKE_INSTALL_PREFIX=""

For alternative control of the configuration process, or to later modify an
already-configured source tree, run the graphical Qt interface via:

    cmake-gui

262
### Build and Install
263

264 265 266 267
The following commands build Waffle, run its tests, installs the project and
creates a binary archive in a platform agnostic way.

Note that not all steps may be required in your case and the configuration
Emil Velikov's avatar
Emil Velikov committed
268
settings (cache) are located in the current directory as indicated by ".".
269 270 271 272 273 274 275 276 277 278 279

    cmake --build .
    cmake --build . --target check
    cmake --build . --target check-func
    cmake --build . --target install
    cpack

Calling `cmake ... check` only runs unittests that do not access the native
OpenGL platform. To run additional functional tests, which do access the
native OpenGL platform, call `cmake ... check-func`.

280
#### Linux and Mac
281

282 283
On Linux and Mac the default CMake generator is Unix Makefiles, as such we
can use an alternative version of the above commands:
284 285 286

    make
    make check
287
    make check-func
288
    make install
289 290 291
    make package


292
#### Windows - cross-building under Linux
293 294 295 296 297 298 299 300 301 302 303 304

    _architectures="i686-w64-mingw32 x86_64-w64-mingw32"
    unset LDFLAGS
    for _arch in ${_architectures}; do
      pushd build-${_arch}
      make
      make install
      make package
      popd
    done

Note: Running the tests (`make check` and/or `make check-func`) is not tested
Emil Velikov's avatar
Emil Velikov committed
305
but may work if the appropriate environment is setup via wine.
306

307
#### Windows - native builds
308

Emil Velikov's avatar
Emil Velikov committed
309
One can manage the build/install/package process via Visual Studio's GUI
310 311 312 313 314 315 316 317 318 319
or via the command line.

When using the GUI open .\build\msvc*\waffle-VERSION.sln, where * can be
either 32 or 64 depending on your requirements.

If building via the command line, navigate to the correct folder and invoke
the desired command as outlined in `Section 3. Build and Install`

For example the following will build 32bit Waffle and will package/archive
it into a file called waffle1-VERSION-win32.zip.
320

321 322 323 324
    @echo Preparing to build 32 bit version of waffle
    cd .\build\msvc32
    cmake --build .
    cpack
Dylan Baker's avatar
Dylan Baker committed
325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373


## Building with Meson

Once meson is installed you can configure the build with meson:

    meson builddir

The default buildtype for waffle is `debugoptimzed`, which has debugging
symbols but is optimized. This is equivalent to the CMake builds `release`.
Meson's release mode does not have debugging symbols. If you wish to pass your
own flags via CFLAGS you should set buildtype to `plain`:

    meson builddir -Dbuildtype=plain -Dc_args='-03 -march=native'

__NOTE__: meson only read CFLAGS (and CXXFLAGS, etc) at initial configuration
time. If you wish to change these flags you'll need to use the meson command
line option `-D${lang}_args=` (such as `-Dc_args=`). This can be used at
configure time as well. It is _highly_ recommended that you use -Dc_args
instead of CFLAGS.

You can check configuration options by:

    meson configure builddir

Meson will be default try to find dependencies and enables targets that have
dependencies met. This behavior can be controlled using configure flags.

Meson detects compilers from the environment, rather from a toolchain file like
CMake does, the easiest way to set up MSVC is to launch a visual studio
terminal prompt, and run meson from there. Meson supports using both ninja (the
default) and msbuild on windows, to use msbuild add:

    meson builddir -Dbackend=vs

On mac there is an xcode backend for meson, but it is not very mature and is
not recommended.

To cross compile pass the location of a cross file, as described
[here](http://mesonbuild.com/Cross-compilation.html).

If you want to build tests and don't have cmocka installed, meson will download
and build cmocka for you while building the rest of waffle. This works on
windows, but due to the way that .dll files work on windows it is only
supported if you add:

    -Ddefault_library=static

Which will also build libwaffle as a static library.