Categories: MySQLDevelopment | Development

CMake


How to Build MySQL server with CMake

Contents

[edit] Introduction

This page describes how to build MySQL distributions with CMake. Other resources that you might find useful:

[edit] Prerequisites

[edit] How to install CMake

 sudo apt-get install cmake cmake-gui

 sudo yum install cmake cmake-gui

 sudo zypper install cmake cmake-gui

 sudo emerge cmake

 pfexec pkgadd install SUNWcmake

Download and install the latest distribution from http://www.cmake.org/cmake/resources/software.html. Download the installer .exe file and run it.

Download and install the latest distribution from http://www.cmake.org/cmake/resources/software.html. Download the .dmg image and open it. Alternatively, if you have Darwinports installed, you can install the CMake port. The +gui variant causes cmake-gui to be installed as well. Omit +gui if you do not want to install cmake-gui. 

 port install cmake +gui

Precompiled packages for other Unix flavors (HPUX, AIX) are available from http://www.cmake.org/cmake/resources/software.html

Alternatively, you can build from source. A source package is also available from the CMake download page.

[edit] Very quick how-to-build

This section describes how to build MySQL in release mode (with debug info)

To control which compiler is chosen, set the CC and CXX environment variables to point to C and C++ compilers. (This is optional, but if you have different versions of the compilers, it gives better control.) 

mkdir bld
cd bld
cmake ..
make

mkdir bld
cd bld
cmake .. 
devenv mysql.sln /build relwithdebinfo


- Build Debug configuration 

 mkdir bld_debug
 cd bld_debug
 cmake .. -DCMAKE_BUILD_TYPE=Debug

 devenv mysql.sln /build debug

[edit] Build using the same options as in MySQL official release

Official MySQL releases add some compiler options. Also, some storage engines are linked statically into mysqld (for example, ARCHIVE). These build options for official releases are stored in cmake/build_configurations/mysql_release.cmake. To use the options, use the -DBUILD_CONFIG=mysql_release cmake parameter. 

 mkdir bld
 cd bld
 cmake -DBUILD_CONFIG=mysql_release ..

 make

 devenv mysql.sln /build relwithdebinfo

Note that on Linux, the offical release requires libaio to be installed on the build machine. For example: 

 sudo yum install libaio-devel

 sudo apt-get install libaio-dev

[edit] Long description of how-to build

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.

[edit] Create the build 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 (e.g., 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

[edit] Configuration step

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.

[edit] Listing configuration parameters

After the initial configuration step completes you can use 

 cmake . -L

 cmake . -LH

 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 .

[edit] Changing configuration parameters

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. 


 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)

From the build directory, issue 

cmake-gui .

[edit] How do build debug configurations

Using Makefiles, debug build is done with -DCMAKE_BUILD_TYPE=Debug (shortcut for it 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

[edit] Build

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. 

devenv MySQL.sln /build RelWithDebInfo

(alternatively, open MySQL.sln and build using the IDE) 

xcodebuild -configuration RelWithDebInfo

(alternatively, open MySQL.xcodeproj and build using the IDE)

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

[edit] Build types

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.

[edit] How to control compiler flags

To specify your own compiler flags, you can

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.

[edit] Predefined sets of options and compiler flags

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.

[edit] Creating binary package

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)

[edit] make install, make test

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"


[edit] Fine-tuning installation paths

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.

--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".

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

[edit] Packager-friendly build options (Unix)

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

[edit] ./configure emulation

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

[edit] For Developers: how to write platform checks

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:

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()

[edit] Debug-only options

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()

[edit] Adding platform checks/compiler flags for a specific OS

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.


[edit] Troubleshooting platform checks or configure errors

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.

[edit] Troubleshooting CMake code

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

[edit] Tips for developers

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/link.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.

[edit] MySQL specific CMake macros

[edit] MYSQL_ADD_EXECUTABLE

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

[edit] MYSQL_ADD_PLUGIN - build mysql plugin 

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:

Define for storage engine. Causes shared library be built with ha_ prefix.

Define for mandatory plugins (like myisam). Causes plugin to be always built

Default plugin. Built unless WITHOUT_<plugin_name> option is defined. Note: innobase storage engine has this option starting with MySQL 5.5.5

Can be only built as static library

Can be only built as shared module

Defines plugin library name when it is built as shared module.

Defines library name when it is built as static library.

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.

Libraries to link with plugin

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

[edit] Interface to Third-Party Tools

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

[edit] FAQ / Miscellany

[edit] Running mysql-test-run.pl in out-of-source build

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.

[edit] Running mysql-test-run.pl with Visual Studio or Xcode projects

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: 

 cd builddir/mysql-test
 MTR_VS_CONFIG=Debug  perl mysql-test-run.pl <parameters>

 cd builddir\mysql-test
 set MTR_VS_CONFIG=Debug
 perl mysql-test-run.pl <parameters>

[edit] make distclean

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".

[edit] Compiling for different hardware architectures

Use compile option -m32 (force 32-bit build), -m64 (force 64-bit build)

Use cmake -G "Visual Studio 9 2008 Win64" <path_to_source_dir> to compile 64-bit (x64)

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.

Retrieved from "http://forge.mysql.com/wiki/CMake"

This page has been accessed 27,508 times. This page was last modified 20:52, 19 March 2011.

Find

Browse
MySQLForge
Main Page
Current events
Recent changes
Random page
Help
Edit
Edit this page
Editing help
This page
Discuss this page
Post a comment
Printable version
Context
Page history
What links here
Related changes
My pages
Special pages
New pages
File list
Statistics
Bug reports
More...