README.CMake.txt

   1 README.CMake.txt - 2010-12-20 - Building and using FLTK with CMake
   2 ------------------------------------------------------------------
   3
   4
   5
   6  CONTENTS
   7 ==========
   8
   9   1   INTRODUCTION TO CMAKE
  10   2   USING CMAKE TO BUILD FLTK
  11     2.1   Prerequisites
  12     2.2   Options
  13     2.3   Building under Linux with Unix Makefiles
  14     2.4   Crosscompiling
  15   3   USING CMAKE WITH FLTK
  16     3.1   Library names
  17     3.2   Using Fluid files
  18   4   DOCUMENT HISTORY
  19
  20
  21  INTRODUCTION TO CMAKE
  22 =======================
  23
  24 CMake was designed to let you create build files for a project once and
  25 then compile the project on multiple platforms.
  26
  27 Using it on any platform consists of the same steps.  Create the
  28 CMakeLists.txt build file(s).  Run one of the CMake executables, picking
  29 your source directory, build directory, and build target.  The "cmake"
  30 executable is a one-step process with everything specified on the command
  31 line.  The others let you select options interactively, then configure
  32 and generate your platform-specific target.  You then run the resulting
  33 Makefile / project file / solution file as you normally would.
  34
  35 CMake can be run in up to three ways, depending on your platform.  "cmake"
  36 is the basic command line tool.  "ccmake" is the curses based interactive
  37 tool.  "cmake-gui" is the gui-based interactive tool.  Each of these will
  38 take command line options in the form of -DOPTION=VALUE.  ccmake and
  39 cmake-gui will also let you change options interactively.
  40
  41 CMake not only supports, but works best with out-of-tree builds.  This means
  42 that your build directory is not the same as your source directory or with a
  43 complex project, not the same as your source root directory.  Note that the
  44 build directory is where, in this case, FLTK will be built, not its final
  45 installation point.  If you want to build for multiple targets, such as
  46 VC++ and MinGW on Windows, or do some cross-compiling you must use out-of-tree
  47 builds exclusively.  In-tree builds will gum up the works by putting a
  48 CMakeCache.txt file in the source root.
  49
  50 More information on CMake can be found on its web site http://www.cmake.org.
  51
  52
  53
  54  USING CMAKE TO BUILD FLTK
  55 ===========================
  56
  57
  58  PREREQUISITES
  59 ---------------
  60
  61 The prerequisites for building FLTK with CMake are staightforward:
  62 CMake 2.6 or later and a recent FLTK 1.3 snapshot.  Installation of
  63 CMake is covered on its web site.
  64
  65 This howto will cover building FLTK with the default options using cmake
  66 under Linux with both the default Unix Makefiles and a MinGW cross compiling
  67 toolchain.  Other platforms are just as easy to use.
  68
  69
  70  OPTIONS
  71 ---------
  72
  73 All options have sensible defaults so you won't usually need to touch these.
  74 There are only two CMake options that you may want to specify.
  75
  76 CMAKE_BUILD_TYPE
  77    This specifies what kind of build this is i.e. Release, Debug...
  78 Platform specific compile/link flags/options are automatically selected
  79 by CMake depending on this value.
  80
  81 CMAKE_INSTALL_PREFIX
  82    Where everything will go on install.  Defaults are /usr/local for unix
  83 and C:\Program Files\FLTK for Windows.
  84
  85 These are the FLTK specific options.  Platform specific options are ignored
  86 on other platforms.
  87
  88 OPTION_OPTIM
  89    Extra optimization flags.
  90 OPTION_ARCHFLAGS
  91    Extra architecture flags.
  92
  93    The OPTION_PREFIX_* flags are for fine-tuning where everything goes
  94 on the install.
  95 OPTION_PREFIX_BIN
  96 OPTION_PREFIX_LIB
  97 OPTION_PREFIX_INCLUDE
  98 OPTION_PREFIX_DATA
  99 OPTION_PREFIX_DOC
 100 OPTION_PREFIX_CONFIG
 101 OPTION_PREFIX_MAN
 102
 103 OPTION_APPLE_X11 - default OFF
 104    In case you want to use X11 on OSX.  Not currently supported.
 105 OPTION_USE_POLL - default OFF
 106    Don't use this one either.
 107
 108 OPTION_BUILD_SHARED_LIBS - default OFF
 109    Normally FLTK is built as static libraries which makes more portable
 110 binaries.  If you want to use shared libraries, this will build them too.
 111 OPTION_BUILD_EXAMPLES - default ON
 112    Builds the many fine example programs.
 113
 114 OPTION_CAIRO - default OFF
 115    Enables libcairo support
 116 OPTION_CAIROEXT - default OFF
 117    Enables extended libcairo support
 118
 119 OPTION_USE_GL - default ON
 120    Enables OpenGL support
 121
 122 OPTION_USE_THREADS - default ON
 123    Enables multithreaded support
 124
 125 OPTION_LARGE_FILE - default ON
 126    Enables large file (>2G) support
 127
 128    FLTK has built in jpeg zlib and png libraries.  These let you use
 129 system libraries instead, unless CMake can't find them.
 130 OPTION_USE_SYSTEM_LIBJPEG - default ON
 131 OPTION_USE_SYSTEM_ZLIB - default ON
 132 OPTION_USE_SYSTEM_LIBPNG - default ON
 133
 134    X11 extended libraries.
 135 OPTION_USE_XINERAMA - default ON
 136 OPTION_USE_XFT - default ON
 137 OPTION_USE_XDBE - default ON
 138
 139
 140  BUILDING UNDER LINUX WITH UNIX MAKEFILES
 141 ------------------------------------------
 142
 143 After untaring the FLTK source, go to the root of the FLTK tree and type
 144 the following.
 145
 146 mkdir build
 147 cd build
 148 cmake ..
 149 make
 150 sudo make install
 151
 152 This will build and install a default configuration FLTK.
 153
 154
 155  CROSSCOMPILING
 156 ----------------
 157
 158 Once you have a crosscompiler going, to use CMAke to build FLTK you need
 159 two more things.  You need a toolchain file which tells CMake where your
 160 build tools are.  The CMake website is a good source of information on
 161 this file.  Here's mine for MinGW under Linux.
 162 ----
 163
 164 # the name of the target operating system
 165 set(CMAKE_SYSTEM_NAME Windows)
 166
 167 # which tools to use
 168 set(CMAKE_C_COMPILER   /usr/bin/i486-mingw32-gcc)
 169 set(CMAKE_CXX_COMPILER /usr/bin/i486-mingw32-g++)
 170
 171 # here is where the target environment located
 172 set(CMAKE_FIND_ROOT_PATH  /usr/i486-mingw32)
 173
 174 # adjust the default behaviour of the FIND_XXX() commands:
 175 # search programs in the host environment
 176 set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER)
 177 # search headers and libraries in the target environment,
 178 set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY)
 179 set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)
 180
 181 set(CMAKE_INSTALL_PREFIX ${CMAKE_FIND_ROOT_PATH}/usr CACHE FILEPATH
 182    "install path prefix")
 183
 184 ----
 185
 186 Not too tough.  The other thing you need is a native installation of FLTK
 187 on your build platform.  This is to supply the fluid executable which will
 188 compile the *.fl into C++ source and header files.
 189
 190 So, again from the FLTK tree root.
 191
 192 mkdir mingw
 193 cd mingw
 194 cmake -DCMAKE_TOOLCHAIN_FILE=~/projects/toolchain/Toolchain-mingw32.cmake ..
 195 make
 196 sudo make install
 197
 198 This will create a default configuration FLTK suitable for mingw/msys and
 199 install it in the /usr/i486-mingw32/usr tree.
 200
 201
 202
 203  USING CMAKE WITH FLTK
 204 =======================
 205
 206 This howto assumes that you have FLTK libraries which were built using
 207 CMake, installed.  Building them with CMake generates some CMake helper
 208 files which are installed in standard locations, making FLTK easy to find
 209 and use.
 210
 211 Here is a basic CMakeLists.txt file using FLTK.
 212
 213 ------
 214
 215 cmake_minimum_required(VERSION 2.6)
 216
 217 project(hello)
 218
 219 find_package(FLTK REQUIRED NO_MODULE)
 220 include(${FLTK_USE_FILE})
 221
 222 add_executable(hello WIN32 hello.cxx)
 223
 224 target_link_libraries(hello fltk)
 225
 226 ------
 227
 228 The find_package command tells CMake to find the package FLTK, REQUIRED
 229 means that it is an error if it's not found.  NO_MODULE tells it to search
 230 only for the FLTKConfig file, not using the FindFLTK.cmake supplied with
 231 CMake, which doesn't work with this version of FLTK.
 232
 233 Once the package is found we include the ${FLTK_USE_FILE} which adds the
 234 FLTK include directories and library link information to its knowledge
 235 base.  After that your programs will be able to find FLTK headers and
 236 when you link the fltk library, it automatically links the libraries
 237 fltk depends on.
 238
 239 The WIN32 in the add_executable tells your Windows compiler that this is
 240 a gui app.  It is ignored on other platforms.
 241
 242
 243  LIBRARY NAMES
 244 ---------------
 245
 246 When you use the target_link_libraries command, CMake uses it's own
 247 internal names for libraries.  The fltk library names are:
 248
 249 fltk     fltk_forms     fltk_images    fltk_gl
 250
 251 and for the shared libraries (if built):
 252
 253 fltk_SHARED     fltk_forms_SHARED     fltk_images_SHARED    fltk_gl_SHARED
 254
 255 The built-in libraries (if built):
 256
 257 fltk_jpeg      fltk_png    fltk_z
 258
 259
 260  USING FLUID FILES
 261 -------------------
 262
 263 CMake has a command named fltk_wrap_ui which helps deal with fluid *.fl
 264 files.  An example of its use is in test/CMakeLists.txt.  Here is a short
 265 summary on its use.
 266
 267 Set a variable to list your C++ files, say CPPFILES.
 268 Set another variable to list your *.fl files, say FLFILES.
 269 Say your executable will be called exec.
 270
 271 Then this is what you do...
 272
 273 fltk_wrap_ui(exec ${FLFILES})
 274 add_executable(exec WIN32 ${CPPFILES} ${exec_FLTK_UI_SRCS})
 275
 276 fltk_wrap_ui calls fluid and generates the required C++ files from the *.fl
 277 files.  It sets the variable, in this case exec_FLTK_UI_SRCS, to the
 278 list of generated files for inclusion in the add_executable command.
 279
 280 The variable FLTK_FLUID_EXECUTABLE which is needed by fltk_wrap_ui is set
 281 when find_package(FLTK REQUIRED NO_MODULE) succeeds.
 282
 283
 284  DOCUMENT HISTORY
 285 ==================
 286
 287 Dec 20 2010 - matt: merged and restructures