[+/-]
Ensure that your compiler and cmake are in your PATH setting. The following description assumes that the current working directory is the top-level source directory.
One of the nice CMake features is "out-of-source" build support, which means not building in the source directory, but in a dedicated build directory. This keeps the source directory clean and allows for more than a single build tree from the same source tree (for example, debug and release, 32-bit and 64-bit, etc.). We'll create a subdirectory "bld" in the source directory for this purpose.
mkdir bld cd bld
On Unix machine, configure the build with
cmake ..
On Windows machine, to build with VS2008 and x64
cmake .. -G "Visual Studio 9 2008 Win64"
On OS X, if you want to use the Xcode IDE
cmake .. -G Xcode
You can add configuration parameters (see next section for description), e.g
cmake .. -DWITH_EMBEDDED_SERVER=1
Now, CMake runs system checks and generates Makefiles. CMake allows the configuration process to be iterative, so you can add more parameters after initial config has run. For example, running the following command after the initial preceding configuration step would add ARCHIVE to the list of statically compiled storage engines:
cmake .. -DWITH_ARCHIVE_STORAGE_ENGINE=1
System checks do not rerun after the initial configuration completes.
After the initial configuration step completes you can use
short form
cmake . -L
short form plus description
cmake . -LH
long form (lists lots of parameters, including internal and advanced ones)
cmake . -LA
Better even, if you have cmake-gui installed, you can do
cmake-gui .
and see or change parameters here. On Unix, some people like to use ccmake (Curses based GUI for cmake):
ccmake .
The procedure above will build with default configuration. This configuration is likely not the most perfect for your needs: For example, the embedded library is not produced. Assume that you you want to change the configuration parameters and compile embedded.
You can provide parameters on the command line, like
cmake . -DWITH_EMBEDDED_SERVER=1
This can be done during the initial configuration or any time later. Note, that parameters are "sticky", that is they are remembered in the CMake cache (CMakeCache.txt file in the build directory)
Configuration using cmake-gui (Windows, OS X, or Linux with cmake-gui installed)
From the build directory, issue
cmake-gui .
Check the WITH_EMBEDDED_SERVER checkbox
Click the "Configure" button
Click the "Generate" button
Close cmake-gui
[+/-]
Using Makefiles, debug build is done with -DCMAKE_BUILD_TYPE=Debug (an alias for this is -DWITH_DEBUG=1). this would include DBUG instrumentation, plus wrapper around pthread mutexes known as SAFE_MUTEX on Unixes.
If Visual Studio or XCode generators are used (you called cmake with -G "Visual Studio ..." or -G Xcode), then switching to release or debug configuration is done within IDE, or at the build time using command line switches, e.g
devenv MySQL.sln /build debug
Unix
make
Note: by default, cmake build is less verbose than automake build. Use
make VERBOSE=1
if you want to see how compiler is invoked.
Windows (using "Visual Studio 9 2008" generator)
devenv MySQL.sln /build RelWithDebInfo
(alternatively, open MySQL.sln and build using the IDE)
Mac OS X build with Xcode
xcodebuild -configuration RelWithDebInfo
(alternatively, open MySQL.xcodeproj and build using the IDE)
Command line build with CMake 2.8
After creating project with cmake as above, issue
cmake --build .
this works with any CMake generator.
For Visual Studio and Xcode, you might want to add extra configuration parameters, to avoid building all configurations.
cmake --build . --config RelWithDebInfo
CMake has CMAKE_BUILD_TYPE variable for predefined build types. A build type affects optimization and whether the result of the build is debuggable.
The ones used by MySQL are RelWithDebInfo or Debug.
RelWithDebInfo (optimizations are on, debug info is generated) is used in MySQL by default.
Debug (optimizations are off, debug info is generated) is used if WITH_DEBUG variable is set.
CMAKE_BUILD_TYPE is not set when custom compile flags are used (see next section)
To specify your own compiler flags, in case compiler flags do not affect optimization you can
Set environment variables: CFLAGS, CXXFLAGS
Use CMake options: cmake . -DCMAKE_C_FLAGS=
your_c_flags-DCMAKE_CXX_FLAGS=your_c++_flags
When providing your own compiler flags, you might want to specify CMAKE_BUILD_TYPE as well.
For example, to create a 32-bit release build on a 64-bit Linux machine , you do:
cmake -DCMAKE_C_FLAGS=-m32 --DCMAKE_CXX_FLAGS=-m32 \ -DCMAKE_BUILD_TYPE=RelWithDebInfo.
If flags you set that affect optimization
(-Onumber), then to specify a
different optimization for default build (Relwithdebinfo), you
need to set CMAKE_C_FLAGS_RELWITHDEBINDO and/or
CMAKE_CXX_RELWITHDEBINFO. For example, to compile on Linux
with -O3 and with debug symbols, do :
cmake "-DCMAKE_C_FLAGS_RELWITHDEBINFO=-O3 \ -g" "-DCMAKE_CXX_FLAGS_RELWITHDEBINFO=-O3 -g"
It might be handy to specify a predefined set of options and
do some compiler flag adjustments by passing just a single
parameter to cmake. For MYSQL ,this can be done using cmake
-DBUILD_CONFIG=some_config. When
set, cmake will execute script in
cmake/build_configurations/some_config.cmake.
Assuming we want to include embedded and exclude archive
storage engine from build, this script could look like
SET(WITH_EMBEDDED_SERVER 1 CACHE BOOL "") SET(WITHOUT_ARCHIVE_STORAGE_ENGINE 1 CACHE BOOL "")
Currently, there is just a single predefined configuration mysql_release, it reflects configuration parameters and compiler flags used by MySQL releases.
Packaging in form of tar.gz archives or .zip on Windows
1)If you're using "generic" Unix build with makefiles
make package
2)On Windows, using "Visual Studio" generator
devenv mysql.sln /build relwithdebinfo /project package
On Windows, current versions of CMake (2.8 and later) do not need any external tools to generate ZIP, with CMake 2.6 however 7Zip or Winzip must be installed and 7z.exe rsp winzip.exe need to be in the PATH.
Another way to build packages is calling cpack executable directly like
cpack -G TGZ --config CPackConfig.cmake
(-G TGZ is for tar.gz generator, there is also -GZIP)
install target also provided for Makefile based generators. Installation directory can be controlled using configure-time parameter CMAKE_INSTALL_PREFIX (default is /usr. It is also possible to install to non-configured directory, using
make install DESTDIR="/some/absolute/path"
"make test" runs unit tests (uses CTest for it)
"make test-force" runs mysql-test-run.pl tests with --test-force parameter
IF you come from autotools background, you will be familiar with --bindir, --libdir, --sbindir etc parameters passed to configure script that allow for fine tuning the installation layout. A similar functionality is available with CMake build too.
CMAKE_INSTALL_PREFIX: specifies the "root" directory of the installation, same as autotools --prefix
INSTALL_BINDIR, INSTALL_SBINDIR, INSTALL_LIBDIR: correspond to autotols
--bindir, --sbindir, --libdir parameters. A subtle difference is that INSTALL_XXXDIR should be paths relative to CMAKE_INSTALL_PREFIX, e.g INSTALL_BINDIR should be "bin" rather than "/usr/bin".
-
there is INSTALL_LAYOUT parameter that allows to choose one of several predefined installation layouts
STANDALONE with layout is the same as in tar.gz/zip packages
RPM with layout similar to RPM packages - for example mysqld is in sbin subdirectory.
SVR4 - Solaris package layout
DEB (experimental)- Layout as in DEB package
Default layout is STANDALONE.
Here is an example on how to modify STANDLONE layout slightly and install libraries into "lib64" subdirectory instead of default "lib"
cmake . -DINSTALL_LAYOUT=STANDALONE -DINSTALL_LIBDIR=lib64
MySQL source distribution contains sources for zlib (compression library), YaSSL (ssl library), readline and libedit. MySQL can be compiled using either libraries available on the system or, to minimize external dependencies, with bundled sources. For Unix/Linux packagers, using system libraries is a more natural option and CMake build has support for it, using options below
-DWITH_ZLIB=system (link with system libz.so)
-DWITH_SSL=system (link with system libssl.so, libcrypto.so)
-DWITH_READLINE=system (link with system libreadline.so)
On Linux, --Wl,--as-needed link option can also be used to remove unused dependencies. While CMake build tries to avoid unneeded dependencies, --as-needed brings better results, for example it removes unused dependency on libgcc_s.so
--Wl,--no-undefined can *not* be used at the moment if plugins are built, because plugins have direct dependency (use symbols) exported by MySQL server.
The legacy way to build MySQL on Unix was to run
BUILD/autorun.sh;./configure lots of parameters; make
This will still work, however ./configure created by ./BUILD/autorun.sh is just a wrapper that translates old-style autotools parameters to new style cmake parameters. Beware that the script is neither perfect nor supported. It is meant to be a temporary solution for those who need time to rewrite ./configure based scripts to native CMake.
Instead of running BUILD/autorun.sh, one can directly invoke ./cmake/configure.pl
[+/-]
If you modify MySQL source and want to add a new platform check, please read http://www.vtk.org/Wiki/CMake_HowToDoPlatformChecks first. In MySQL, most of the platform tests are implemented in configure.cmake and the template header file is config.h.cmake
Bigger chunks of functionality, for example, non-trivial macros,
are implemented in files
src-root/cmake subdirectory.
For people with autotools background, it is important to remember CMake does not provide autoheader functionality. That is, when you add a check
CHECK_FUNCTION_EXISTS(foo HAVE_FOO)
to config.cmake, then you will also need to add
#cmakedefine HAVE_FOO 1
to config.h.cmake
Useful bits:
Check for existence of C/C++ compiler flags with CHECK_{C,CXX}_COMPILER_FLAG.
Here is an example of checking for (theoretical) -foo flag support in C compiler, and adding it to C flags, if the flag is supported.
INCLUDE(CheckCCompilerFlag)
CHECK_C_COMPILER_FLAG("-foo" HAVE_C_COMPILER_FOO)
IF(HAVE_COMPILER_FOO)
SET(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -foo")
ENDIF()
Sometimes, it is handy to add an option that is active only in Debug builds. When doing this one should keep in mind, that tests like IF(WITH_DEBUG) or IF(CMAKE_BUILD_TYPE MATCHES "Debug") do not work as expected. First, while WITH_DEBUG is an alias for CMAKE_BUILD_TYPE=Debug, the converse is not true.
Second, checking for CMAKE_BUILD_TYPE will not work everywhere, more precisely , it will *not* work with multi-configuration CMake generators, i.e neither on Windows with Visual Studio and nor on OSX with Xcode.
So, when adding debug-only option consider extending CMAKE_{C,CXX}_FLAGS_DEBUG like for example:
# Works always
SET(CMAKE_C_FLAGS_DEBUG "${CMAKE_C_FLAGS_DEBUG} -DUNIV_DEBUG")
and do NOT do it like:
IF(WITH_DEBUG)
# Does NOT work with CMAKE_BUILD_TYPE=Debug, Visual Studio or Xcode
ADD_DEFINITIONS(-DUNIV_DEBUG)
ENDIF()
If you add a platform check for specific OS or want to modify
compiler flags, rather then introducing IF(CMAKE_SYSTEM_NAME
MATCHES...)in configure.cmake, add them to the apropriate
section in
cmake/os/my_platform.cmake. For
example, Solaris specific adjustments are made in
cmake/os/SunOS.cmake. This file will be included when you
compile on Solaris.
If you suspect that a platform check returned wrong result,
examine
build-root/CMakeFiles/CMakeError.log
and
build-root/CMakeFiles/CMakeOutput.log
These files they contain compiler command line, and exact
error messages.
While there are advanced flags for cmake like -debug-trycompile and --trace, a simple and efficient way to debug to add MESSAGE("interesting variable=${some_invariable}") to the interesting places in CMakeLists.txt
How to find out which compiler/ulinker flags are used
When using Makefile generator it is easy to examine which
compiler flags are used to build. For example, compiler flags
for mysqld are in
build-root/sql/CMakeFiles/mysqld.dir/flags.make
and the linker command line is in
build-root/sql/CMakeFiles/mysqld.dir/ulink.txt
What is CMakeCache.txt?
CMake caches results of platform checks in CMakeCache.txt. It is a nice feature because tests do not rerun when reconfiguring (e.g when a new test was added).The downside of caching is that when a platform test was wrong and was later corrected, the cached result is still used. If you encounter this situation, which should be a rare occation, you need either to remove the offending entry from CMakeCache.txt (if test was for HAVE_FOO, remove lines containing HAVE_FOO from CMakeCache.txt) or just remove the cache file.
Almost the same as ADD_EXECUTABLE. Supports optional DESTINATION parameter which tells where to install the exe (if not specified, it goes to ${INSTALL_BINDIR} directory). For executables not indented to be installed, use ADD_EXECUTABLE instead. On Windows, signs the executable if SIGNCODE option is set to TRUE.
Example usage
MYSQL_ADD_EXECUTABLE(mysqld ${MYSQLD_SOURCE} \
DESTINATION ${INSTALL_SBINDIR})
MYSQL_ADD_PLUGIN(plugin_name source1...sourceN [STORAGE_ENGINE] [MANDATORY|DEFAULT] [STATIC_ONLY|MODULE_ONLY] [MODULE_OUTPUT_NAME module_name] [STATIC_OUTPUT_NAME static_name] [RECOMPILE_FOR_EMBEDDED] [LINK_LIBRARIES lib1...libN] [DEPENDENCIES target1...targetN])
Parameters:
STORAGE_ENGINE
Define for storage engine. Causes shared library be built with ha_ prefix.
MANDATORY
Define for mandatory plugins (like myisam). Causes plugin to be always built
DEFAULT
Default plugin. Built unless
WITHOUT_plugin_name option is
defined. Note: innobase storage engine has this option
starting with MySQL 5.5.5
STATIC_ONLY
Can be only built as static library
MODULE_ONLY
Can be only built as shared module
MODULE_OUTPUT_NAME module_name
Defines plugin library name when it is built as shared module.
STATIC_OUTPUT_NAME
Defines library name when it is built as static library.
RECOMPILE_FOR_EMBEDDED
Needs to be recompiled with -DEMBEDDED_SERVER preprocessor flag for use with embedded server. Only few plugins need this - typically mandatory storage engines that depend on internal structures and on EMBEDDED_SERVER flag.
LINK_LIBRARIES
Libraries to link with plugin
DEPENDENCIES
Plugin dependencies
Example 1 - Simple plugin that is only built as shared module
MYSQL_ADD_PLUGIN(daemon_example daemon_example.cc MODULE_ONLY)
Example 2 - Innobase plugin. Storage engine, redefines output name of shared library to be ha_innodb rather than ha_innobase, depedends on zlib library.
MYSQL_ADD_PLUGIN(innobase ${INNOBASE_SOURCES} STORAGE_ENGINE MODULE_OUTPUT_NAME ha_innodb LINK_LIBRARIES ${ZLIB_LIBRARY})
Third-party tools that need to determine the MySQL version from the MySQL source can read the VERSION file in the top-level source directory. The file lists the pieces of the version separately. For example, if the version is 5.5.8, the file looks like this:
MYSQL_VERSION_MAJOR=5 MYSQL_VERSION_MINOR=5 MYSQL_VERSION_PATCH=8 MYSQL_VERSION_EXTRA=
If the source is not for a General Availablility (GA) release, the MYSQL_VERSION_EXTRA value will be nonempty. For example, the value for a Release Candidate release would look like this:
MYSQL_VERSION_EXTRA=rc
To construct a five-digit number from the version components, use this formula:
MYSQL_VERSION_MAJOR*10000 + MYSQL_VERSION_MINOR*100 + MYSQL_VERSION_PATCH
[+/-]
When using out-of-source build, use mysql-test-run.pl in the
builddir/mysql-test. It is a
wrapper script that calls mysql-test-run.pl in the source
directory and tells it where to look for the binaries, via
environment MTR_BINDIR variable. Attempts to run
mysql-test-run.pl from the source directory will fail.
If you build with Xcode, and you build more than a single
configuration (e.g Debug and RelWithDebInfo), set environment
variable
MTR_VS_CONFIG=cmake_configuration_name
to run tests for a specific configuration. The name of the
variable, specifially "VS" part in it just reflects
the fact it was implemented for Visual Studio originally. When
many configurations are build, MTR will prefer Release or
RelWithDebInfo. To run debug configuration:
On Mac OS X
cd builddir/mysql-test
MTR_VS_CONFIG=Debug perl mysql-test-run.pl parameters
On Windows
cd builddir\mysql-test
set MTR_VS_CONFIG=Debug
perl mysql-test-run.pl parameters
Unlike autotools, CMake does not provide "distclean" target natively, nor there should be a need to use it, if you build out-of-source. But if you built in-source, use "bzr clean-tree" with --unknown and/or --ignored arguments. If you want to add new files to the tree, be sure to "bzr add" prior to "bzr clean-tree".
GCC (on Linux) or Sun Studio
Use compile option -m32 (force 32-bit build), -m64 (force 64-bit build)
Windows, Visual Studio generator
Use cmake -G "Visual Studio 9 2008 Win64"
path_to_source_dir to compile
64-bit (x64)
Mac OS X
Use CMAKE_OSX_ARCHITECTURES CMake variable. You can set more than a single architecture to create universal binary, e.g
cmake "-DCMAKE_OSX_ARCHITECTURES=i386;pcc" path_to_source
will build universal binary with 32-bit intel / 32-bit powerpc.
cmake "-DCMAKE_OSX_ARCHITECTURES=x86_64" path_to_source
will create x86_64 binary.
