zdoom/fluidsynth
0
0
Fork 0
mirror of https://github.com/ZDoom/fluidsynth.git synced 2024-11-26 22:21:31 +00:00
Code Issues Projects Releases Packages Wiki Activity

Update and rename README.cmake to README.cmake.md

Browse source 
remove duplicate docs and point to the wiki
This commit is contained in:
Tom M 2018-06-15 17:47:12 +02:00 committed by GitHub
parent a1bc872754
commit 876af08d2f
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
2 changed files with 115 additions and 188 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

188
README.cmake
View file

@ -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}
...
)

115
README.cmake.md Normal file
View file

@ -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}
...
)
```