[waffle] [PATCHv2 03/19] README: Add notes when building Waffle for Windows.
Emil Velikov
emil.l.velikov at gmail.com
Mon Aug 4 09:27:27 PDT 2014
Update the existing document to reflect the areas where the existing
instructions are not applicable for Windows. Split some of the sections
at "per platform/build time" basis when needed.
- Fix couple of trivial typos and drop the BUILD_DIR variable.
- Disable waffle tests for now.
- Minimised duplication, don't execute vcvarsall.bat and correctly
append Win64 in the generator string. Spotted by Jose.
Signed-off-by: Emil Velikov <emil.l.velikov at gmail.com>
---
README.txt | 177 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++----
1 file changed, 166 insertions(+), 11 deletions(-)
diff --git a/README.txt b/README.txt
index 1695347..e18da31 100644
--- a/README.txt
+++ b/README.txt
@@ -50,10 +50,12 @@ Waffle, see the following:
Build Requirements
==================
+Waffle uses CMake for its build system.
+
Linux
-----
-
-Waffle uses CMake for it build system.
+On Linux it's recommended to install the cmake package using your
+distribution package manager.
Archlinux: pacman -S cmake
Fedora 17: yum install cmake
@@ -97,6 +99,53 @@ a comman-separated list of any combination of "x11", "wayland", and "drm".
- Debian: apt-get install libgbm-dev libudev-dev
+Windows - cross-building under Linux
+------------------------------------
+Make sure that CMake is installed on your system.
+
+ Archlinux: pacman -S cmake
+ Fedora 17: yum install cmake
+ Debian: apt-get install cmake
+
+The MinGW-W64 cross-build toolchain is recommended and its CMake wrapper.
+
+ Archlinux: pacman -S mingw-w64-gcc mingw-w64-cmake (latter is in AUR)
+ Fedora 17: yum install FINISHME
+ Debian: apt-get install FINISHME
+
+
+Windows - native builds
+-----------------------
+Download and install the latest version CMake from the official website:
+
+ http://cmake.org/
+
+Install Microsoft Visual Studio 2013* or later.
+Install 'Visual C++' feature.
+
+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
+
+
+[*] Waffle heavily requires on features introduced by the C99 standard. As
+such only reasonable compiler (at the time of writing) from the Microsoft
+Visual Compiler series is MSVC 2013. Building with older versions is likely
+to be broken.
+
+Windows - CYGWIN
+----------------
+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.
+
+
Build and Installation
======================
@@ -114,6 +163,9 @@ or
1. Configure pkg-config
-----------------------
+Compiling for Windows does require any additional dependencies, as such
+this step can be omitted.
+
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:
@@ -123,23 +175,26 @@ a dependeny into /usr/local, then:
2. Configure CMake
------------------
+
+2.1 Linux and Mac
+-----------------
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 .
-To manually control the configuration process, or to later modify the an already-configured source tree,
-run one of the following:
+To manually control the configuration process, or to later modify the an
+already-configured source tree, run one of the following:
# An ncurses interface to CMake configuration.
- ccamke $BUILD_DIR
+ ccmake .
# A graphical Qt interface to CMake configuration.
- cmake-gui $BUILD_DIR
+ cmake-gui .
# Edit the raw configuration file.
- vim $BUILD_DIR/CMakeCache.txt
+ vim CMakeCache.txt
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
@@ -147,17 +202,117 @@ build, require support for Wayland, and install into '/usr' instead of
'/usr/local', run the following:
cmake -DCMAKE_BUILD_TYPE=Debug \
- -DCMAKE_INSTALL_PREFIX=/usr/local \
+ -DCMAKE_INSTALL_PREFIX=/usr \
-Dwaffle_has_wayland=1 \
.
+2.2 Windows - cross-building under Linux
+----------------------------------------
+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.
+
+
+2.3 Windows - native builds
+---------------------------
+
+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
+
3. Build and Install
--------------------
+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
+settings (cache) are localed in the current directory as indicated by ".".
+
+ 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`.
+
+3.1 Linux and Mac
+-----------------
+On Linux and Mac the default CMake generator is Unix Makefiles, as such we
+can use an alternative version of the above commands:
make
make check
+ make check-func
make install
+ make package
+
+
+3.2 Windows - cross-building under Linux
+----------------------------------------
+
+ _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
+but may work if the approapriate environment is setup via wine.
+
+
+3.3 Windows - native builds
+---------------------------
+Once can manage the build/install/package process via Visual Studio's GUI
+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.
-Calling `make 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 `make check-func`.
+ @echo Preparing to build 32 bit version of waffle
+ cd .\build\msvc32
+ cmake --build .
+ cpack
--
2.0.2
More information about the waffle
mailing list