WL#5161: CMake-based unified build system

Currently, there are 2 build do different toolsets used to build MySQL Server
- GNU (autoconf, automake, libtool)  is used on Unixes.
- CMake  is used on Windows.

The purpose of this worklog is to unify the build system .After evaluation 
period, switch from using 2 different systems to a  single one CMake

The main reasons for choosing CMake is that it is obviously simpler to maintain 
a unified build system than two disparate systems.

Here are some pro-CMake arguments:

- It works on Window. GNU buildsystem does not appear to be enough  “cross-
platform”,  that is it does not work and likely never will work natively on 
Windows.

- Traditionally, new MySQL features that required changes in build (plugin 
yystem,  unit tests,  most recently  googletest integration) were always 
implemented on Unixes first, leaving Windows behind, sometimes for years. This 
would not happen with unified build system.

- We already use CMake since 2006 on Windows, so we do not need to start from 
scratch, only port what we have to Unix.

- CMake runs on every OS and compiler we support.

- It is simple to  get. It is available  in all major Linux  repositories 
(checked Ubuntu, Fedora, OpenSUSE). It is also in OpenSolaris repository, known 
as SUNWCmake. It in FreeBSD ports. The It is also very simple to compile it 
from source, the single prerequisite is a working C++ compiler and make utility.

- CMake has support features we need and might need:  system checks, cross-
compiling.

- CMake  provides integrated support for packaging. It can handle both simple 
packages (tar.gz or zip archives) and more complex things like DEB and RPM 
without much extra coding.

- Good integration with the popular IDEs (Visual Studio, Xcode, Eclipse CDT, 
KDevelop). Developing in IDE makes development process more enjoyable, and 
potentially it lowers the barrier for external contributors. Of course, cmake 
can generate traditional Unix Makefiles, which appear to be are superior to 
autotools generated ones (for example they have progress indicators, color and 
working dependencies).

- Scripting language used by CMake is simpler m4 used by autotools.

- CMake is a single small tool, not a bunch of different tools as in GNU system
(autoconf,autoheader,automake,libtool)

=====Quick start====

Using cmake for developer is simple, to compile and test MySQL server, the 
minimalistic instructions to compile  on Unix are

bzr  branch  
cd repo
cmake .
make
make test-force

Of course we will support build options, so the above cmake command could look 
a bit more complicated with
cmake . –DWITH_INNOBASE_STORAGE_ENGINE=1 –DWITH_SSL=bundled –
DWITH_EXTRA_CHARSETS=all

========Which build options are supported========

We will support all  important options and platform specialities (like 
DTrace) .  We’ll cut support for some obsolete things (like  –with-named-thread-
library). Likely there won’t be support for  non-thread safe client libraries, 
but we’ll generate symlinks  such that  user’s build does not break.
Translation from the currently known autotools configure script options will 
work like this : leading – is omitted, option name is translated to upper case, 
dash is replaced with underscore.-
-	“boolean” options (on/off),  are translated like this
./configure --with-innobase-storage-engine  =>  cmake  -
DWITH_INNOBASE_STORAGE_ENGINE=1
-	“textual” options will are translated like this
./configure –with-ssl=bundled => cmake –DWITH_SSL=bundled
This is compatible with what we use on Windows currently, at least KDE folks 
and other CMake users seem to follow the same schema.
cmake –LH will list the really important options, cmake –LAH will list all 
options, including exotic ones.
cmake –LH or cmake-gui  can be seen as replacement for ./configure –help

======How to compile for debugging===============

By default,  unless explicit options are given in CFLAGS or CXXFLAGS 
environment variables, we will use Relwithdebinfo configuration (release with 
debug information)  which typically equates to –O2  -g compile flags. We also 
add –DDBUG_OFF in all but Dbug configurations.
To compile debug, one can use following options

cmake –DCMAKE_BUILD_TYPE=Debug (native cmake syntax)
cmake –DWITH_DEBUG (added for compatibity with autotools)
cmake –DWITH_DEBUG_FULL (uses safemalloc, slow)


======Platform checks=============

System checks in configure.in ( availabity of header files, functions etc)  
will be ported. Restricted subset of checks will also run on Windows, which 
means Windows will  config-win.h will be ditched and Windows will use the same 
mechanism for config.h generation as every other platform.  
Why not to run all checks on Windows, but just a restricted subset? Platform 
checks generally run slower on Windows , because cmake needs to generate a VS 
solution for every test and since  most  of the tests do not apply to Windows  
anyway (pthread_ is not known to exist on every current or future version of 
windows, nor there will ever be a posix_fallocate on Windows), we’ll restrict 
the number of tests to minimum – it is a pure performance tweak.


======Out-of-source (aka out-of-place) builds========

We will support both in-source builds, as it is how people are used to work.  
We will also support and encourage out-of-sourc e builds, which are recommended 
by CMake folks because it is cleaner build- the source tree is not polluted 
with binaries and objects. The main advantage of an out-of-source build is the 
possibility to have multiple build tree  of the same source. One can build 
example building with different options , or debug and release, or even put the 
source tree on the network share and build on different OSes with different 
compilers.
An out of source build is done with simple
cmake  
We’ll also support running tests in an out-of-source builds, which will require 
some modifications in MTR (as it currently assumes sources and binaries are 
under same directory)

======Packaging (binary) ===========

cmake-built projects will break existing scripts used for tarball packaging – 
existing scripts rely on build that is done with libtool, for example on 
existence of  .libs directories. Also, existing scripts will not work for Xcode 
projects – the paths used there are different from what make_bnary_distribution 
expects , they rather resemble structure that is used for Visual Studio 
projects (binaries are different Debug and Relwithdebinfo subdirectories).  
Therefore we’ll use builtin support for packaging via cmake’s INSTALL command 
(we need to use it anyway to generate “make install”) .  First, we’ll support 
tar.gz and zip packages  -   potentially  it can be expanded to DEBs and  RPMs  
with minimal overhead

Creating a binary package with CMake2.6  :

make package (Unix Makefiles generator)
devenv  mysql.sln /build relwithdebinfo /project package (VS generator)
xcodebuild  -target=package–config=Relwithdebinfo (Xcode generator)

======Packaging(source) ===========

This is different to autotools and “make dist” is not provided by default. 
CMake-generated Makefiles provide package_source target, but it just packs 
everything in source directory. In an in-source build, this will packs binaries 
as well.
We will implement “make dist” ourselves,  using  “bzr export” functionality or, 
if bzr is not  available, “make package_source” ( for in-source build we’ll need 
to issue “make clean” prior to avoid packing the binaries).  We’ll pack some 
extra files into the tarball, that are there traditionally packed – that is 
bison output files.  For some period of time (as long as we continue 
supporting  both autotools  in addition to  cmake)  we’ll  generate and package 
the traditional configure script too.
It is worth noting that  “make dist”  less important  for cmake and can possibly 
can be completely replaced with “bzr export” or out-of-source “make 
package_source”  in the future. 

=======Backward compatibility with autotools system=======

At least for the start and time required for transition, autotools build will 
be supported. Existing scripts (BUILD/autorun.sh && configure) will continue to 
work.  configure script will be changed to call  cmake with relevant 
parameters , if cmake is found on the machine, otherwise it will fall back to 
autotools build.  There will be a possibility to disable CMake build  and force 
autotools  via environment variable HAVE_CMAKE=no. Plugging cmake into existing 
systems like described above has the benefit that all scripts in the BUILD 
directory continue to work.

======Backward compatibility with existing cmake usage on Windows =======

For the time required for transition, configure.js and win\build-foo.bat 
scripts will continue to work. We should encourage users though to use cmake 
directly. New versions of CMake (2.8, currently release candidate)  will  find 
existing Visual Studio so there is no need to specify generator with a long 
commands like 
cmake  . –G “Visual Studio 9 2008”.
Instead, one could just use
cmake .
as on Unix.