Introduction

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

• Autotools to CMake Transition Guide: If you have previously built MySQL using the GNU autotools, this guide shows how to map common autotools/configure options to CMake.
• CMake documentation at cmake.org
• CMake Useful Variables

Prerequisites

---

• Usual MySQL build prerequisites:
  • Unix: compiler and make utility, curses dev package on Linux
  • Windows: Visual Studio (Express version okay)
  • Mac OS X: Xcode tools
  • Everywhere: bison, unless you're building from source package where bison output is already packed. On OpenSolaris/Solaris Express you would need to install m4 in addition to bison. NOTE: On Windows install bison into path without spaces, not into default location. Reason : this bug in bison 2.4.1
• CMake version 2.6.3 or later installed on your system.

How to install CMake

• Debian/Ubuntu Linux:

 sudo apt-get install cmake cmake-gui

• Fedora Linux

 sudo yum install cmake cmake-gui

• openSUSE Linux

 sudo zypper install cmake cmake-gui

• Gentoo Linux

 sudo emerge cmake

• OpenSolaris:

 pfexec pkgadd install SUNWcmake

• Windows:

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

• Mac OS X:

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

• Other Unixes:

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.

Very quick how-to-build

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

• Unix (Makefiles)

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

• Windows (Visual Studio, from command line)

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

- Build Debug configuration

• Unix (Makefiles)

 mkdir bld_debug
 cd bld_debug
 cmake .. -DCMAKE_BUILD_TYPE=Debug

• Visual Studio (using command line)

 devenv mysql.sln /build debug

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

• Unix (Makefiles)

 make

• Visual Studio (using command line)

 devenv mysql.sln /build relwithdebinfo

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

• RedHat/Fedora

 sudo yum install libaio-devel

• Debian/Ubuntu

 sudo apt-get install libaio-dev

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.

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

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.

Listing configuration parameters

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 .

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.

• 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

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

Build

• 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

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.

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

How to control compiler flags

To specify your own compiler flags, 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.

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.

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)

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"

• "make test" runs unit tests (uses CTest for it)
• "make test-force" runs mysql-test-run.pl tests with --test-force parameter

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.

• 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

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

• -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 plugns have direct dependency (use symbols) exported by MySQL server.

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

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:

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

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

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.

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.

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

Tips for developers

• How to find out which compiler/linker 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/link.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.

MySQL specific CMake macros

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

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:

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

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

FAQ / Miscellany

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.

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:

• 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>

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

Compiling for different hardware architectures

• 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 -D "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. Sex Shop Sex Shop Atacado Sex Shop