Merged the CMake documenation and adapted the format to the one used in the other README fiels (mainly adding a TOC).

git-svn-id: file:///fltk/svn/fltk/branches/branch-1.3@8082 ea41ed52-d2ee-0310-a9c1-e6b18d33e121

3 files changed, 287 insertions, 242 deletions

diff --git a/README.CMake.txt b/README.CMake.txt
new file mode 100644
index 000000000..780ad755b
--- /dev/null
+++ b/README.CMake.txt
@@ -0,0 +1,287 @@
+README.CMake.txt - 2010-12-20 - 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 snapshot.  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
+---------
+
+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.
+
+These are the FLTK specific options.  Platform specific options are ignored
+on other platforms.
+
+OPTION_OPTIM
+   Extra optimization flags.
+OPTION_ARCHFLAGS
+   Extra architecture flags.
+
+   The OPTION_PREFIX_* flags are for fine-tuning where everything goes
+on the install.
+OPTION_PREFIX_BIN
+OPTION_PREFIX_LIB
+OPTION_PREFIX_INCLUDE
+OPTION_PREFIX_DATA
+OPTION_PREFIX_DOC
+OPTION_PREFIX_CONFIG
+OPTION_PREFIX_MAN
+
+OPTION_APPLE_X11 - default OFF
+   In case you want to use X11 on OSX.  Not currently supported.
+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
+
+   FLTK has built in jpeg zlib and png libraries.  These let you use
+system libraries instead, unless CMake can't find them.
+OPTION_USE_SYSTEM_LIBJPEG - default ON
+OPTION_USE_SYSTEM_ZLIB - default ON
+OPTION_USE_SYSTEM_LIBPNG - default ON
+
+   X11 extended libraries.
+OPTION_USE_XINERAMA - default ON
+OPTION_USE_XFT - default ON
+OPTION_USE_XDBE - default 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.
+
+
+ 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
+=======================
+
+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)
+
+find_package(FLTK REQUIRED NO_MODULE)
+include(${FLTK_USE_FILE})
+
+add_executable(hello WIN32 hello.cxx)
+
+target_link_libraries(hello fltk)
+
+------
+
+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 and library link information to its knowledge
+base.  After that your programs will be able to find FLTK headers and
+when you link the fltk library, it automatically links the libraries
+fltk depends on.
+
+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.  An example of its use is in test/CMakeLists.txt.  Here is a short
+summary on its use.
+
+Set a variable to list your C++ files, say CPPFILES.
+Set another variable to list your *.fl files, say FLFILES.
+Say your executable will be called exec.
+
+Then this is what you do...
+
+fltk_wrap_ui(exec ${FLFILES})
+add_executable(exec WIN32 ${CPPFILES} ${exec_FLTK_UI_SRCS})
+
+fltk_wrap_ui calls fluid and generates the required C++ files from the *.fl
+files.  It sets the variable, in this case exec_FLTK_UI_SRCS, to the
+list of generated files for inclusion in the add_executable command.
+
+The variable FLTK_FLUID_EXECUTABLE which is needed by fltk_wrap_ui is set
+when find_package(FLTK REQUIRED NO_MODULE) succeeds.
+
+
+ DOCUMENT HISTORY
+==================
+
+Dec 20 2010 - matt: merged and restructures
diff --git a/README.CMake_build b/README.CMake_build
deleted file mode 100644
index d68fc60c6..000000000
--- a/README.CMake_build
+++ /dev/null
@@ -1,137 +0,0 @@
-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 snapshot.  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
-
-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.
-
-These are the FLTK specific options.  Platform specific options are ignored
-on other platforms.
-
-OPTION_OPTIM
-   Extra optimization flags.
-OPTION_ARCHFLAGS
-   Extra architecture flags.
-
-   The OPTION_PREFIX_* flags are for fine-tuning where everything goes
-on the install.
-OPTION_PREFIX_BIN
-OPTION_PREFIX_LIB
-OPTION_PREFIX_INCLUDE
-OPTION_PREFIX_DATA
-OPTION_PREFIX_DOC
-OPTION_PREFIX_CONFIG
-OPTION_PREFIX_MAN
-
-OPTION_APPLE_X11 - default OFF
-   In case you want to use X11 on OSX.  Not currently supported.
-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
-
-   FLTK has built in jpeg zlib and png libraries.  These let you use
-system libraries instead, unless CMake can't find them.
-OPTION_USE_SYSTEM_LIBJPEG - default ON
-OPTION_USE_SYSTEM_ZLIB - default ON
-OPTION_USE_SYSTEM_LIBPNG - default ON
-
-   X11 extended libraries.
-OPTION_USE_XINERAMA - default ON
-OPTION_USE_XFT - default ON
-OPTION_USE_XDBE - default 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.
-
-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.
diff --git a/README.CMake_use b/README.CMake_use
deleted file mode 100644
index 92f9e7a27..000000000
--- a/README.CMake_use
+++ /dev/null
@@ -1,105 +0,0 @@
-
-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 WITH FLTK
-
-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)
-
-find_package(FLTK REQUIRED NO_MODULE)
-include(${FLTK_USE_FILE})
-
-add_executable(hello WIN32 hello.cxx)
-
-target_link_libraries(hello fltk)
-
-------
-
-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 and library link information to its knowledge
-base.  After that your programs will be able to find FLTK headers and
-when you link the fltk library, it automatically links the libraries
-fltk depends on.
-
-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.  An example of its use is in test/CMakeLists.txt.  Here is a short
-summary on its use.
-
-Set a variable to list your C++ files, say CPPFILES.
-Set another variable to list your *.fl files, say FLFILES.
-Say your executable will be called exec.
-
-Then this is what you do...
-
-fltk_wrap_ui(exec ${FLFILES})
-add_executable(exec WIN32 ${CPPFILES} ${exec_FLTK_UI_SRCS})
-
-fltk_wrap_ui calls fluid and generates the required C++ files from the *.fl
-files.  It sets the variable, in this case exec_FLTK_UI_SRCS, to the
-list of generated files for inclusion in the add_executable command.
-
-The variable FLTK_FLUID_EXECUTABLE which is needed by fltk_wrap_ui is set
-when find_package(FLTK REQUIRED NO_MODULE) succeeds.