diff --git a/README.cmake b/README.cmake deleted file mode 100644 index 13b86b02..00000000 --- a/README.cmake +++ /dev/null @@ -1,188 +0,0 @@ -What is CMake? -============== - -CMake is a cross platform build system, that can be used to replace the old -auto-tools, providing a nice building environment and advanced features. - -Some of these features are: -* Out of sources build: CMake allows you to build your software into a directory - different to the source tree. You can safely delete the build directory and - all its contents once you are done. -* Multiple generators: classic makefiles can be generated for Unix and MinGW, - but also Visual Studio, XCode and Eclipse CDT projects among other types. -* Graphic front-ends for configuration and build options. - -More information and documentation is available at the CMake project site: - http://www.cmake.org - -CMake is free software. You can get the sources and pre-compiled packages for -Linux and other systems at: - http://www.cmake.org/cmake/resources/software.html - -How to use it? -============== - -1. You need CMake 3.0.2 or later to build FluidSynth - -2. Unpack the FluidSynth sources somewhere, or checkout the repository, - and create a build directory. For instance, using a command line shell: - -$ tar -xvzf Downloads/fluidsynth-x.y.z.tar.gz -$ cd fluidsynth-x.y.z -$ mkdir build - -2. Execute CMake from the build directory, providing the source directory - location and optionally, the build options. There are several ways. - -* From a command line shell: - -$ pwd -fluidsynth-x.y.z -$ cd build -$ cmake .. -DCMAKE_INSTALL_PREFIX=/usr -Denable-ladspa=1 - -Valid values for boolean (enable-xxxx) options: 1, 0, yes, no, on, off. - -* There are also several alternative CMake front-ends, if you don't want to use - the command line interface: - * ncurses based program, for Linux and Unix: ccmake - * GUI, Qt4 based program, multiplatform: cmake-gui - * GUI, Windows native program: CMakeSetup.exe - -3. Execute the build command. If you used the Makefiles generator (the default - in Linux and other Unix systems) then execute make, gmake or mingw32-make. - If you generated a project file, use your IDE to build it. - -You may find more up-to-date information in the project Wiki: - https://github.com/FluidSynth/fluidsynth/wiki/BuildingWithCMake - -Compiling with make -=================== - -There are many targets available. To see a complete list of them, type: - -$ make help - -The build process usually hides the compiler command lines, to show them: - -$ make VERBOSE=1 - -There is a "clean" target, but not a "distclean" one. You should use a build -directory different to the source tree. In this case, the "distclean" target -would be equivalent to simply removing the build directory. - -To compile the developer documentation, install Doxygen (http://www.doxygen.org) -and use this command from the root build directory: - -$ make doxygen - -If something fails -================== - -If there is an error message while executing CMake, this probably means that a -required package is missing in your system. You should install the missing -component and run CMake again. - -If there is an error executing the build process, after running a flawless CMake -configuration process, this means that there may be an error in the source code, -or in the build system, or something incompatible in 3rd party libraries. - -The CMake build system for FluidSynth is experimental. It will take a while -until it becomes stable and fully tested. You can help providing feedback, -please send a report containing your problems to the FluidSynth development -mailing list: http://lists.nongnu.org/mailman/listinfo/fluid-dev - - -For developers - how to add a new feature to the CMake build system -=================================================================== - -Let's explain this issue with an example. We are adding D-Bus support to -FluidSynth as an optional feature, conditionally adding source files that -require this feature. The first step is to add a macro "option()" to the main -CMakeLists.txt file, the one that is located at the fluidsynth root directory. - -file CMakeLists.txt, line 64: - - option ( enable-dbus "compile DBUS support (if it is available)" on ) - -Now, let's check if the dbus-1 library and headers are installed, using -pkg-config: - -file CMakeLists.txt, lines 371-377: - - unset ( DBUS_SUPPORT CACHE ) - if ( enable-dbus ) - pkg_check_modules ( DBUS dbus-1>=1.0.0 ) - set ( DBUS_SUPPORT ${DBUS_FOUND} ) - else ( enable-dbus ) - unset_pkg_config ( DBUS ) - endif ( enable-dbus ) - -The first line clears the value of the CMake variable DBUS_SUPPORT. If the -value of the option "enable-dbus" is true, then the macro pkg_check_modules() -is used to test a package named "dbus-1" with version 1.0.0 or later. This macro -automatically defines the variables DBUS_LIBRARIES, DBUS_INCLUDEDIR, DBUS_FOUND -and others. The value of the last one is assigned to our variable DBUS_SUPPORT -for later use. - -There is a report to summarize the performed checks and the enabled features -after the configuration steps, so let's add a line in this report regarding -the D-Bus support. - -file cmake_admin/report.cmake, lines 14-18: - - if ( DBUS_SUPPORT ) - message ( "D-Bus: yes" ) - else ( DBUS_SUPPORT ) - message ( "D-Bus: no" ) - endif ( DBUS_SUPPORT ) - -The variable DBUS_SUPPORT is available for the CMake files, but we want to make -it available to the compilers as well, to conditionally build code using -"#ifdef DBUS_SUPPORT". This can be done adding a line to the config.cmake file: - -file src/config.cmake, lines 22-23: - - /* Define if D-Bus support is enabled */ - #cmakedefine DBUS_SUPPORT @DBUS_SUPPORT@ - -The file config.cmake will be processed at configure time, producing a header -file "config.h" in the build directory with this content, if the dbus support -has been enabled and found: - - /* Define if D-Bus support is enabled */ - #define DBUS_SUPPORT 1 - -Finally, we can add the new source files to the build system for the compiler -target with the macro add_library(), and the libraries for the linker target -with the macros link_directories() and target_link_libraries(). - -file src/CMakeLists.txt, lines 57-60 - - if ( DBUS_SUPPORT ) - set ( fluid_dbus_SOURCES fluid_rtkit.c fluid_rtkit.h ) - include_directories ( ${DBUS_INCLUDEDIR} ${DBUS_INCLUDE_DIRS} ) - endif ( DBUS_SUPPORT ) - -file src/CMakeLists.txt, lines 163-197 - - link_directories ( - ... - ${DBUS_LIBDIR} - ${DBUS_LIBRARY_DIRS} - ) - - add_library ( libfluidsynth - ... - ${fluid_dbus_SOURCES} - ... - ) - -file src/CMakeLists.txt, lines 163-197 - - target_link_libraries ( libfluidsynth - ... - ${DBUS_LIBRARIES} - ... - ) - diff --git a/README.cmake.md b/README.cmake.md new file mode 100644 index 00000000..57a5893f --- /dev/null +++ b/README.cmake.md @@ -0,0 +1,115 @@ +## For users - how to compile FluidSynth + +The latest information on how to compile FluidSynth using the cmake build system can be found in our wiki: + +https://github.com/FluidSynth/fluidsynth/wiki/BuildingWithCMake + + +## For developers - how to add a new feature to the CMake build system + +Let's explain this issue with an example. We are adding D-Bus support to +FluidSynth as an optional feature, conditionally adding source files that +require this feature. The first step is to add a macro "option()" to the main +CMakeLists.txt file, the one that is located at the fluidsynth root directory. + +file CMakeLists.txt, line 64: + +```cmake +option ( enable-dbus "compile DBUS support (if it is available)" on ) +``` + +Now, let's check if the dbus-1 library and headers are installed, using +pkg-config: + +file CMakeLists.txt, lines 371-377: + +```cmake +unset ( DBUS_SUPPORT CACHE ) +if ( enable-dbus ) + pkg_check_modules ( DBUS dbus-1>=1.0.0 ) + set ( DBUS_SUPPORT ${DBUS_FOUND} ) +else ( enable-dbus ) + unset_pkg_config ( DBUS ) +endif ( enable-dbus ) +``` + +The first line clears the value of the CMake variable DBUS_SUPPORT. If the +value of the option "enable-dbus" is true, then the macro pkg_check_modules() +is used to test a package named "dbus-1" with version 1.0.0 or later. This macro +automatically defines the variables DBUS_LIBRARIES, DBUS_INCLUDEDIR, DBUS_FOUND +and others. The value of the last one is assigned to our variable DBUS_SUPPORT +for later use. + +There is a report to summarize the performed checks and the enabled features +after the configuration steps, so let's add a line in this report regarding +the D-Bus support. + +file cmake_admin/report.cmake, lines 14-18: + +```cmake +if ( DBUS_SUPPORT ) + message ( "D-Bus: yes" ) +else ( DBUS_SUPPORT ) + message ( "D-Bus: no" ) +endif ( DBUS_SUPPORT ) +``` + +The variable DBUS_SUPPORT is available for the CMake files, but we want to make +it available to the compilers as well, to conditionally build code using +"#ifdef DBUS_SUPPORT". This can be done adding a line to the config.cmake file: + +file src/config.cmake, lines 22-23: + +```c +/* Define if D-Bus support is enabled */ +#cmakedefine DBUS_SUPPORT @DBUS_SUPPORT@ +``` + +The file config.cmake will be processed at configure time, producing a header +file "config.h" in the build directory with this content, if the dbus support +has been enabled and found: + +```c +/* Define if D-Bus support is enabled */ +#define DBUS_SUPPORT 1 +``` + +Finally, we can add the new source files to the build system for the compiler +target with the macro add_library(), and the libraries for the linker target +with the macros link_directories() and target_link_libraries(). + +file src/CMakeLists.txt, lines 57-60 + +```cmake +if ( DBUS_SUPPORT ) + set ( fluid_dbus_SOURCES fluid_rtkit.c fluid_rtkit.h ) + include_directories ( ${DBUS_INCLUDEDIR} ${DBUS_INCLUDE_DIRS} ) +endif ( DBUS_SUPPORT ) +``` + +file src/CMakeLists.txt, lines 163-197 + +```cmake +link_directories ( + ... + ${DBUS_LIBDIR} + ${DBUS_LIBRARY_DIRS} +) + +add_library ( libfluidsynth + ... + ${fluid_dbus_SOURCES} + ... +) +``` + +file src/CMakeLists.txt, lines 163-197 + +```cmake +target_link_libraries ( libfluidsynth + ... + ${DBUS_LIBRARIES} + ... +) +``` +