libs/fluidsynth_lite/README.cmake

   1 What is CMake?
   2 ==============
   3
   4 CMake is a cross platform build system, that can be used to replace the old
   5 auto-tools, providing a nice building environment and advanced features.
   6
   7 Some of these features are:
   8 * Out of sources build: CMake allows you to build your software into a directory
   9   different to the source tree. You can safely delete the build directory and
  10   all its contents once you are done.
  11 * Multiple generators: classic makefiles can be generated for Unix and MinGW,
  12   but also Visual Studio, XCode and Eclipse CDT projects among other types.
  13 * Graphic front-ends for configuration and build options.
  14
  15 More information and documentation is available at the CMake project site:
  16     http://www.cmake.org
  17
  18 CMake is free software. You can get the sources and pre-compiled packages for
  19 Linux and other systems at:
  20      http://www.cmake.org/cmake/resources/software.html
  21
  22 How to use it?
  23 ==============
  24
  25 1. You need CMake 2.6.3 or later to build FluidSynth
  26
  27 2. Unpack the FluidSynth sources somewhere, or checkout the repository,
  28    and create a build directory. For instance, using a command line shell:
  29
  30 $ tar -xvzf Downloads/fluidsynth-x.y.z.tar.gz
  31 $ cd fluidsynth-x.y.z
  32 $ mkdir build
  33
  34 2. Execute CMake from the build directory, providing the source directory
  35    location and optionally, the build options. There are several ways.
  36
  37 * From a command line shell:
  38
  39 $ pwd
  40 fluidsynth-x.y.z
  41 $ cd build
  42 $ cmake .. -DCMAKE_INSTALL_PREFIX=/usr -Denable-ladspa=1
  43
  44 Valid values for boolean (enable-xxxx) options: 1, 0, yes, no, on, off.
  45
  46 * There are also several alternative CMake front-ends, if you don't want to use
  47   the command line interface:
  48   * ncurses based program, for Linux and Unix: ccmake
  49   * GUI, Qt4 based program, multiplatform: cmake-gui
  50   * GUI, Windows native program: CMakeSetup.exe
  51
  52 3. Execute the build command. If you used the Makefiles generator (the default
  53    in Linux and other Unix systems) then execute make, gmake or mingw32-make.
  54    If you generated a project file, use your IDE to build it.
  55
  56 You may find more information in the project Wiki:
  57     http://sourceforge.net/apps/trac/fluidsynth/wiki/BuildingWithCMake
  58
  59 Compiling with make
  60 ===================
  61
  62 There are many targets available. To see a complete list of them, type:
  63
  64 $ make help
  65
  66 The build process usually hides the compiler command lines, to show them:
  67
  68 $ make VERBOSE=1
  69
  70 There is a "clean" target, but not a "distclean" one. You should use a build
  71 directory different to the source tree. In this case, the "distclean" target
  72 would be equivalent to simply removing the build directory.
  73
  74 To compile the developer documentation, install Doxygen (http://www.doxygen.org)
  75 and use this command from the root build directory:
  76
  77 $ make doxygen
  78
  79 If something fails
  80 ==================
  81
  82 If there is an error message while executing CMake, this probably means that a
  83 required package is missing in your system. You should install the missing
  84 component and run CMake again.
  85
  86 If there is an error executing the build process, after running a flawless CMake
  87 configuration process, this means that there may be an error in the source code,
  88 or in the build system, or something incompatible in 3rd party libraries.
  89
  90 The CMake build system for FluidSynth is experimental. It will take a while
  91 until it becomes stable and fully tested. You can help providing feedback,
  92 please send a report containing your problems to the FluidSynth development
  93 mailing list: http://lists.nongnu.org/mailman/listinfo/fluid-dev
  94
  95
  96 For developers - how to add a new feature to the CMake build system
  97 ===================================================================
  98
  99 Let's explain this issue with an example. We are adding D-Bus support to
 100 FluidSynth as an optional feature, conditionally adding source files that
 101 require this feature. The first step is to add a macro "option()" to the main
 102 CMakeLists.txt file, the one that is located at the fluidsynth root directory.
 103
 104 file CMakeLists.txt, line 64:
 105
 106         option ( enable-dbus "compile DBUS support (if it is available)" on )
 107
 108 Now, let's check if the dbus-1 library and headers are installed, using
 109 pkg-config:
 110
 111 file CMakeLists.txt, lines 371-377:
 112
 113         unset ( DBUS_SUPPORT CACHE )
 114         if ( enable-dbus )
 115                 pkg_check_modules ( DBUS dbus-1>=1.0.0 )
 116                 set ( DBUS_SUPPORT ${DBUS_FOUND} )
 117     else ( enable-dbus )
 118         unset_pkg_config ( DBUS )
 119         endif ( enable-dbus )
 120
 121 The first line clears the value of the CMake variable DBUS_SUPPORT. If the
 122 value of the option "enable-dbus" is true, then the macro  pkg_check_modules()
 123 is used to test a package named "dbus-1" with version 1.0.0 or later. This macro
 124 automatically defines the variables DBUS_LIBRARIES, DBUS_INCLUDEDIR, DBUS_FOUND
 125 and others. The value of the last one is assigned to our variable DBUS_SUPPORT
 126 for later use.
 127
 128 There is a report to summarize the performed checks and the enabled features
 129 after the configuration steps, so let's add a line in this report regarding
 130 the D-Bus support.
 131
 132 file cmake_admin/report.cmake, lines 14-18:
 133
 134         if ( DBUS_SUPPORT )
 135                 message ( "D-Bus:                 yes" )
 136         else ( DBUS_SUPPORT )
 137                 message ( "D-Bus:                 no" )
 138         endif ( DBUS_SUPPORT )
 139
 140 The variable DBUS_SUPPORT is available for the CMake files, but we want to make
 141 it available to the compilers as well, to conditionally build code using
 142 "#ifdef DBUS_SUPPORT". This can be done adding a line to the config.cmake file:
 143
 144 file src/config.cmake, lines 22-23:
 145
 146         /* Define if D-Bus support is enabled */
 147         #cmakedefine DBUS_SUPPORT @DBUS_SUPPORT@
 148
 149 The file config.cmake will be processed at configure time, producing a header
 150 file "config.h" in the build directory with this content, if the dbus support
 151 has been enabled and found:
 152
 153         /* Define if D-Bus support is enabled */
 154         #define DBUS_SUPPORT  1
 155
 156 Finally, we can add the new source files to the build system for the compiler
 157 target with the macro add_library(), and the libraries for the linker target
 158 with the macros link_directories() and target_link_libraries().
 159
 160 file src/CMakeLists.txt, lines 57-60
 161
 162         if ( DBUS_SUPPORT )
 163                 set ( fluid_dbus_SOURCES fluid_rtkit.c fluid_rtkit.h )
 164                 include_directories ( ${DBUS_INCLUDEDIR} ${DBUS_INCLUDE_DIRS} )
 165         endif ( DBUS_SUPPORT )
 166
 167 file src/CMakeLists.txt, lines 163-197
 168
 169     link_directories (
 170                 ...
 171                 ${DBUS_LIBDIR}
 172                 ${DBUS_LIBRARY_DIRS}
 173         )
 174
 175         add_library ( libfluidsynth
 176                 ...
 177                 ${fluid_dbus_SOURCES}
 178                 ...
 179         )
 180
 181 file src/CMakeLists.txt, lines 163-197
 182
 183         target_link_libraries ( libfluidsynth
 184                 ...
 185                 ${DBUS_LIBRARIES}
 186                 ...
 187         )
 188