mirror of https://github.com/fltk/fltk
333 lines
11 KiB
Plaintext
333 lines
11 KiB
Plaintext
README.CMake.txt - Building and using FLTK with CMake
|
|
-----------------------------------------------------
|
|
|
|
|
|
CONTENTS
|
|
==========
|
|
|
|
1 INTRODUCTION TO CMAKE
|
|
2 USING CMAKE TO BUILD FLTK
|
|
2.1 Prerequisites
|
|
2.2 Options
|
|
2.3 Building under Linux with Unix Makefiles
|
|
2.4 Crosscompiling
|
|
3 USING CMAKE WITH FLTK
|
|
3.1 Library names
|
|
3.2 Using Fluid files
|
|
4 DOCUMENT HISTORY
|
|
|
|
|
|
INTRODUCTION TO CMAKE
|
|
=======================
|
|
|
|
CMake was designed to let you create build files for a project once and
|
|
then compile the project on multiple platforms.
|
|
|
|
Using it on any platform consists of the same steps. Create the
|
|
CMakeLists.txt build file(s). Run one of the CMake executables, picking
|
|
your source directory, build directory, and build target. The "cmake"
|
|
executable is a one-step process with everything specified on the command
|
|
line. The others let you select options interactively, then configure
|
|
and generate your platform-specific target. You then run the resulting
|
|
Makefile / project file / solution file as you normally would.
|
|
|
|
CMake can be run in up to three ways, depending on your platform. "cmake"
|
|
is the basic command line tool. "ccmake" is the curses based interactive
|
|
tool. "cmake-gui" is the gui-based interactive tool. Each of these will
|
|
take command line options in the form of -DOPTION=VALUE. ccmake and
|
|
cmake-gui will also let you change options interactively.
|
|
|
|
CMake not only supports, but works best with out-of-tree builds. This means
|
|
that your build directory is not the same as your source directory or with a
|
|
complex project, not the same as your source root directory. Note that the
|
|
build directory is where, in this case, FLTK will be built, not its final
|
|
installation point. If you want to build for multiple targets, such as
|
|
VC++ and MinGW on Windows, or do some cross-compiling you must use out-of-tree
|
|
builds exclusively. In-tree builds will gum up the works by putting a
|
|
CMakeCache.txt file in the source root.
|
|
|
|
More information on CMake can be found on its web site http://www.cmake.org.
|
|
|
|
|
|
|
|
USING CMAKE TO BUILD FLTK
|
|
===========================
|
|
|
|
|
|
PREREQUISITES
|
|
---------------
|
|
|
|
The prerequisites for building FLTK with CMake are staightforward:
|
|
CMake 2.6 or later and a recent FLTK 1.3 release, snapshot, or subversion
|
|
download (working copy). Installation of CMake is covered on its web site.
|
|
|
|
This howto will cover building FLTK with the default options using cmake
|
|
under Linux with both the default Unix Makefiles and a MinGW cross compiling
|
|
toolchain. Other platforms are just as easy to use.
|
|
|
|
|
|
OPTIONS
|
|
---------
|
|
Options can be specified to cmake with the -D flag:
|
|
|
|
cmake -D <OPTION_NAME>=<OPTION_VALUE>
|
|
|
|
Example:
|
|
|
|
cmake -D CMAKE_BUILD_TYPE=Debug
|
|
|
|
All options have sensible defaults so you won't usually need to touch these.
|
|
There are only two CMake options that you may want to specify:
|
|
|
|
CMAKE_BUILD_TYPE
|
|
This specifies what kind of build this is i.e. Release, Debug...
|
|
Platform specific compile/link flags/options are automatically selected
|
|
by CMake depending on this value.
|
|
|
|
CMAKE_INSTALL_PREFIX
|
|
Where everything will go on install. Defaults are /usr/local for unix
|
|
and C:\Program Files\FLTK for Windows.
|
|
|
|
The following are the FLTK specific options. Platform specific options
|
|
are ignored on other platforms.
|
|
|
|
OPTION_OPTIM
|
|
Extra optimization flags.
|
|
|
|
OPTION_ARCHFLAGS
|
|
Extra architecture flags.
|
|
|
|
OPTION_APPLE_X11 - default OFF
|
|
In case you want to use X11 on OSX.
|
|
Use this only if you know what you do, and if you have installed X11.
|
|
|
|
OPTION_USE_POLL - default OFF
|
|
Don't use this one either.
|
|
|
|
OPTION_BUILD_SHARED_LIBS - default OFF
|
|
Normally FLTK is built as static libraries which makes more portable
|
|
binaries. If you want to use shared libraries, this will build them too.
|
|
|
|
OPTION_BUILD_EXAMPLES - default ON
|
|
Builds the many fine example programs.
|
|
|
|
OPTION_CAIRO - default OFF
|
|
Enables libcairo support
|
|
|
|
OPTION_CAIROEXT - default OFF
|
|
Enables extended libcairo support
|
|
|
|
OPTION_USE_GL - default ON
|
|
Enables OpenGL support
|
|
|
|
OPTION_USE_THREADS - default ON
|
|
Enables multithreaded support
|
|
|
|
OPTION_LARGE_FILE - default ON
|
|
Enables large file (>2G) support
|
|
|
|
OPTION_USE_SYSTEM_LIBJPEG - default ON
|
|
OPTION_USE_SYSTEM_ZLIB - default ON
|
|
OPTION_USE_SYSTEM_LIBPNG - default ON
|
|
FLTK has built in jpeg, zlib, and png libraries. These let you use
|
|
system libraries instead, unless CMake can't find them. If you set
|
|
any of these options to OFF, then the built in library will be used.
|
|
|
|
OPTION_USE_XINERAMA - default ON
|
|
OPTION_USE_XFT - default ON
|
|
OPTION_USE_XDBE - default ON
|
|
These are X11 extended libraries.
|
|
OPTION_PRINT_SUPPORT - default ON
|
|
When turned off, the Fl_Printer class does nothing and the
|
|
Fl_PostScript_File_Device class cannot be used, but the FLTK library
|
|
is somewhat smaller. This option makes sense only on the Unix/Linux
|
|
platform or when OPTION_APPLE_X11 is ON.
|
|
|
|
BUILDING UNDER LINUX WITH UNIX MAKEFILES
|
|
------------------------------------------
|
|
|
|
After untaring the FLTK source, go to the root of the FLTK tree and type
|
|
the following.
|
|
|
|
mkdir build
|
|
cd build
|
|
cmake ..
|
|
make
|
|
sudo make install
|
|
|
|
This will build and install a default configuration FLTK.
|
|
|
|
Some flags can be changed during the 'make' command, such as:
|
|
|
|
make VERBOSE=on
|
|
|
|
..which builds in verbose mode, so you can see all the compile/link commands.
|
|
|
|
|
|
CROSSCOMPILING
|
|
----------------
|
|
|
|
Once you have a crosscompiler going, to use CMake to build FLTK you need
|
|
two more things. You need a toolchain file which tells CMake where your
|
|
build tools are. The CMake website is a good source of information on
|
|
this file. Here's mine for MinGW under Linux.
|
|
|
|
----
|
|
# the name of the target operating system
|
|
set(CMAKE_SYSTEM_NAME Windows)
|
|
|
|
# which tools to use
|
|
set(CMAKE_C_COMPILER /usr/bin/i486-mingw32-gcc)
|
|
set(CMAKE_CXX_COMPILER /usr/bin/i486-mingw32-g++)
|
|
|
|
# here is where the target environment located
|
|
set(CMAKE_FIND_ROOT_PATH /usr/i486-mingw32)
|
|
|
|
# adjust the default behaviour of the FIND_XXX() commands:
|
|
# search programs in the host environment
|
|
set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER)
|
|
# search headers and libraries in the target environment,
|
|
set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY)
|
|
set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)
|
|
|
|
set(CMAKE_INSTALL_PREFIX ${CMAKE_FIND_ROOT_PATH}/usr CACHE FILEPATH
|
|
"install path prefix")
|
|
----
|
|
|
|
Not too tough. The other thing you need is a native installation of FLTK
|
|
on your build platform. This is to supply the fluid executable which will
|
|
compile the *.fl into C++ source and header files.
|
|
|
|
So, again from the FLTK tree root.
|
|
|
|
mkdir mingw
|
|
cd mingw
|
|
cmake -DCMAKE_TOOLCHAIN_FILE=~/projects/toolchain/Toolchain-mingw32.cmake ..
|
|
make
|
|
sudo make install
|
|
|
|
This will create a default configuration FLTK suitable for mingw/msys and
|
|
install it in the /usr/i486-mingw32/usr tree.
|
|
|
|
|
|
|
|
USING CMAKE WITH FLTK
|
|
=======================
|
|
|
|
The CMake Export/Import facility can be thought of as an automated
|
|
fltk-config. For example, if you link your program to the fltk
|
|
library, it will automatically link in all of its dependencies. This
|
|
includes any special flags. ie on Linux it includes the -lpthread flag.
|
|
|
|
This howto assumes that you have FLTK libraries which were built using
|
|
CMake, installed. Building them with CMake generates some CMake helper
|
|
files which are installed in standard locations, making FLTK easy to find
|
|
and use.
|
|
|
|
Here is a basic CMakeLists.txt file using FLTK.
|
|
|
|
------
|
|
|
|
cmake_minimum_required(VERSION 2.6)
|
|
|
|
project(hello)
|
|
|
|
# The following line is required only if (a) you didn't install FLTK
|
|
# or if (b) find_package can't find your installation directory because
|
|
# you installed FLTK in a non-standard location. It points to
|
|
# (a) the base folder of the build directory, or
|
|
# (b) <fltk-install-prefix>/share/fltk
|
|
# resp., where <fltk-install-prefix> is the installation prefix you
|
|
# used to install FLTK.
|
|
# (The file FLTKConfig.cmake and others must be found in that path.)
|
|
|
|
set(FLTK_DIR /path/to/fltk)
|
|
|
|
find_package(FLTK REQUIRED NO_MODULE)
|
|
include(${FLTK_USE_FILE})
|
|
|
|
add_executable(hello WIN32 hello.cxx)
|
|
|
|
target_link_libraries(hello fltk)
|
|
|
|
------
|
|
|
|
The set(FLTK_DIR ...) command is a superhint to the find_package command.
|
|
This is very useful if you don't install or have a non-standard install.
|
|
The find_package command tells CMake to find the package FLTK, REQUIRED
|
|
means that it is an error if it's not found. NO_MODULE tells it to search
|
|
only for the FLTKConfig file, not using the FindFLTK.cmake supplied with
|
|
CMake, which doesn't work with this version of FLTK.
|
|
|
|
Once the package is found we include the ${FLTK_USE_FILE} which adds the
|
|
FLTK include directories to its knowledge base. After that your programs
|
|
will be able to find FLTK headers.
|
|
|
|
The WIN32 in the add_executable tells your Windows compiler that this is
|
|
a gui app. It is ignored on other platforms.
|
|
|
|
LIBRARY NAMES
|
|
---------------
|
|
|
|
When you use the target_link_libraries command, CMake uses it's own
|
|
internal names for libraries. The fltk library names are:
|
|
|
|
fltk fltk_forms fltk_images fltk_gl
|
|
|
|
and for the shared libraries (if built):
|
|
|
|
fltk_SHARED fltk_forms_SHARED fltk_images_SHARED fltk_gl_SHARED
|
|
|
|
The built-in libraries (if built):
|
|
|
|
fltk_jpeg fltk_png fltk_z
|
|
|
|
|
|
USING FLUID FILES
|
|
-------------------
|
|
|
|
CMake has a command named fltk_wrap_ui which helps deal with fluid *.fl
|
|
files. Unfortunately it is broken in CMake 3.4.x. You can however use
|
|
add_custom_command to achieve the same result.
|
|
This is a more basic approach and should work for all CMake versions.
|
|
|
|
Here is a sample CMakeLists.txt which compiles the CubeView example from
|
|
a directory you've copied the test/Cube* files to.
|
|
|
|
---
|
|
cmake_minimum_required(VERSION 2.6)
|
|
|
|
project(CubeView)
|
|
|
|
# change this to your fltk buid directory
|
|
set(FLTK_DIR /home/msurette/build/fltk-release/)
|
|
|
|
find_package(FLTK REQUIRED NO_MODULE)
|
|
include(${FLTK_USE_FILE})
|
|
|
|
#run fluid -c to generate CubeViewUI.cxx and CubeViewUI.h files
|
|
add_custom_command(
|
|
OUTPUT "CubeViewUI.cxx" "CubeViewUI.h"
|
|
COMMAND fluid -c ${CMAKE_CURRENT_SOURCE_DIR}/CubeViewUI.fl
|
|
)
|
|
|
|
include_directories(${CMAKE_BINARY_DIR})
|
|
include_directories(${CMAKE_SOURCE_DIR})
|
|
add_executable(CubeView WIN32 CubeMain.cxx CubeView.cxx CubeViewUI.cxx)
|
|
|
|
target_link_libraries(CubeView fltk fltk_gl)
|
|
---
|
|
|
|
You can repeat the add_custom_command for each fluid file or if you have
|
|
a large number of them see the CMake/macros.cmake function FLTK_RUN_FLUID
|
|
for an example of how to run it in a loop.
|
|
|
|
DOCUMENT HISTORY
|
|
==================
|
|
|
|
Dec 20 2010 - matt: merged and restructures
|
|
May 15 2013 - erco: small formatting tweaks, added some examples
|
|
Feb 23 2014 - msurette: updated to reflect changes to the CMake files
|
|
Apr 07 2015 - AlbrechtS: update use example and more docs
|
|
Jan 31 2016 - msurette: custom command instead of fltk_wrap_ui
|