Get the code, build it, test it

MariaDB Server is hosted on GitHub. The official repository can be found at https://github.com/MariaDB/server.

Prerequisites

For getting started as a developer and to make your debugging process easier, make sure that your hardware has at least 2GB RAM, 2GB HD and at least 4 cores. We are working with git and cmake, so you will need to have git installed and cmake.

Get the source code

The current development version of MariaDB is 10.6.  It is recommended that everything you do with development you do as a regular user, not as a super user.

The recommended way to get the source is to fork it and clone it.

git clone https://github.com/YOUR-USERNAME/server

Build the server

Before you can build the server, you must install build dependencies. Windows users should follow the link How to build MariaDB on Windows.

On a Debian based distribution:

apt-get build-dep mariadb-server-10.X

where X is the suffix of the major version.

apt-get install build-essential libncurses5-dev gnutls-dev bison zlib1g-dev ccache

A few extra packages may be required to build other components.

Configure the build

MariaDB uses cmake to generate Makefiles (or Ninja build files) used to compile the server.

To check if cmake is installed run cmake --version. Cmake has a CMAKE_BUILD_TYPE option for predefined build types, which affects optimization and whether the result of the build can be debugged. One of them is a Debug type, for which optimizations are off and debug info is generated. This option is used for creating the trace files which are useful if mysqld is crashing. Running without specifying CMAKE_BUILD_TYPE uses default the C and C++ compilers described with CMAKE_C_FLAGS and CMAKE_CXX_FLAGS. All cmake configuration options for MariaDB can be displayed with:

cmake . -LH

where L stands for short form, LH short form plus description, LA lists internal and advanced ones options. For more options see cmake documentation.

Recommend always doing an out-of-tree build so that your source code doesn’t get build artifacts mixed with the source files. This also allow different build directories with different cmake options at the same time. If you have accidentally built an in-tree build, make sure to clean out old object files and cached information before reconfiguring and rebuilding:

make clean

rm CMakeCache.txt

or (preferred):

git clean -dffx

git reset --hard HEAD

git submodule update --init --recursive

The last command is needed because fresh git clone doesn’t automatically clone everything (examples are modules libmariadb and storage/rocksdb/rocksdb folder which is upstream submodule). After git submodule update run again git status. To configure a Debug build, useful for development, create a build directory beside the source tree and change to this directory:

mkdir build-mariadb-server-debug
cd build-mariadb-server-debug

Then configure MariaDB by running:

cmake ../server -DCMAKE_BUILD_TYPE=Debug

Debugging builds provide additional tests.

CMake will now check to see which libraries are available, which compiler is installed and if everything checks out, it will finish with a “Configure successful” message. If there are failures, check to see which libraries you need to install. You probably need to install the development versions of them.

Configuration with CMake produces files under the CMakeFiles directory:
CMakeFiles/CMakeError.log and CMakeFiles/CMakeOutput.log.

After the initial configuration has been performed you can add more options to cmake. Options are remembered in the CMake cache (the CMakeCache.txt file in the build directory (build-mariadb-server-debug)).


If the configuring or building doesn’t succeed, you can install the required packages and re-run cmake. Alternately if the error is confined to a plugin, those can be disabled with a cmake option like -DPLUGIN_MROONGA=NO.

Build with embedded server is not set by default in the build since it increase the compilation time. In order to use it, compile the server with cmake . DWITH_EMBEDDED_SERVER=1. Note the . here is the current build directory and not the source directory.

As an alternative you can also use ninja build system in order to run builds faster. To do so make sure you have installed ninja.

apt-get install ninja-build

If you have successfully installed build system with ninja --version you will obtain installed version.

Make sure that you cleaned old object files and run again cmake but this time with Ninja flag and with prefix -G.

cmake ../server -DCMAKE_BUILD_TYPE=Debug -G Ninja

Now you are ready to compile server (with make or ninja), invoke cmake --build . inside the build directory.

For the faster build you can exclude storage engines that you don’t need in your development. Here is an example of excluding some of storage engines (uses shell expansion) plus other configuration options for a faster build:

cmake ../server -DCONC_WITH_{UNITTEST,SSL}=OFF -DWITH_EMBEDDED_SERVER=ON -DWITH_UNIT_TESTS=OFF -DCMAKE_BUILD_TYPE=Debug -DPLUGIN_{ARCHIVE,TOKUDB,MROONGA,OQGRAPH,ROCKSDB,CONNECT,PERFSCHEMA,SPIDER,SPHINX}=NO -DWITH_SAFEMALLOC=OFF -DWITH_SSL=bundled -DMYSQL_MAINTAINER_MODE=OFF -G Ninja

To see the full list of options used by cmake or to change them through GUI, from build folder run ccmake .(you will have to install cmake-curses-gui).

Compile

To build with cmake, regardless of if using make or ninja:

 cmake --build . --parallel 5

Substitute 5 with the number of cores you have available for faster builds.

Testing the server

Now that the server is built, we should test that everything is working properly.

To find out if your mysqld binary has debugging support, run from the build directory sql/mysqld -V on the command line. If the version number ends in -debug then your mysqld binary was compiled with debugging support. From MariaDB-10.5 the mysqld binary is called mariadbd.

MariaDB has a testing framework defined in mysql-test folder. To run all tests:

mysql-test/mtr --parallel=5 --mem --force --max-test-fail=40

Note: if you are using MacOS omit the --mem flag. To run only unit tests:

mysql-test/mtr --suite=unit --mem --parallel=5

Each of the above is run from build directory. mysql-test-run uses its own --defaults-file overriding any default one.

You can see logs for your test in

mysql-test/var/log

There are lots of useful flags for mtr.

  • --parallel=#number-of-parallel-tasks will run multiple tests in parallel, thus speeding up tests. The process can easily take over an hour, even if parallelization is used.
  • --mem is used to force the tests to be run on a virtual ramdisk. This will speed things up as long as RAM is sufficient.
  • --force is used to continue to run the suit after failure.
  • --max-test-fail is used to limit the number of test failures before aborting the current test run. Defaults to 10. Set it’s default with the environment variable MTR_MAX_TEST_FAIL. (requires --force)
  • --embedded is used to run with the embedded server.
  • --big-test(or just --big) is used to run the big tests (tests which can use lots of memory and/or disk. In tests these tests have --source include/big_test.inc. If you want only to run big test use the flag two times --big --big.
  • --help is used to show options to control what engine/variation to run.

Starting mysqld after build

You can run mysqld directly from the build directory (without executing sudo make install).

If you are running MariaDB for first time you will need to run mysql_install_db to install the needed system tables. But before that create a directory for your data (this directory will be used for the datadir system variable in the config file). Copy following in  ~/.my.cnf file.

# The MariaDB server group

[mariadb]
datadir           = path/to/your/data/dir
# path to source dir + sql/share
lc_messages_dir   = source/sql/share

If you need to change something, read more about setting mysqld configuration files and groups.

Now you can go to the build directory and execute the following:

./scripts/mysql_install_db  --srcdir=../server --datadir=/path/to/data/dir

You are to create your own config file and call it with flag `–defaults-file` while installing the system tables. Create a new file ~/my-config.cnf like above.

Now to install the system tables call following from the build folder:

./scripts/mysql_install_db --srcdir=../server --defaults-file=~/my-config.cnf

After that you can start mysqld, which by default looks for option file. If --defaults-file is given mysqld will read only from this file. Run like:

sql/mysqld --defaults-file=

After starting up mysqld you can launch the client as root:

client/mysql -u root

What is next?

As a new contributor we encourage you to look more in beginner friendly jira tasks where you can find appropriate task that you can work on. In order to work on this task just write a comment in the ticket, stating that you re interested in working on it.

Read more about generic build instructions,  running MariaDB from build directory, starting and stopping MariaDB automatically.

See also