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

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

Jordan Justen's avatar
Jordan Justen committed
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
Jordan Justen's avatar
Jordan Justen committed
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
Jordan Justen's avatar
Jordan Justen committed
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


Dylan Baker's avatar
Dylan Baker committed
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


Dylan Baker's avatar
Dylan Baker committed
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.


Dylan Baker's avatar
Dylan Baker committed
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

Dylan Baker's avatar
Dylan Baker committed
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


Dylan Baker's avatar
Dylan Baker committed
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

Dylan Baker's avatar
Dylan Baker committed
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


Dylan Baker's avatar
Dylan Baker committed
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.


Dylan Baker's avatar
Dylan Baker committed
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
Dylan Baker's avatar
Dylan Baker committed
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
Dylan Baker's avatar
Dylan Baker committed
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
Dylan Baker's avatar
Dylan Baker committed
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
Dylan Baker's avatar
Dylan Baker committed
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
Dylan Baker's avatar
Dylan Baker committed
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.