From 7046e8ebcb01c91500066300bdeaaa41ca1ac0cb Mon Sep 17 00:00:00 2001 From: Matthias Melcher Date: Mon, 20 Dec 2010 20:00:44 +0000 Subject: [PATCH] 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 --- README.CMake.txt | 287 +++++++++++++++++++++++++++++++++++++++++++++ README.CMake_build | 137 ---------------------- README.CMake_use | 105 ----------------- 3 files changed, 287 insertions(+), 242 deletions(-) create mode 100644 README.CMake.txt delete mode 100644 README.CMake_build delete mode 100644 README.CMake_use 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.