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, 10GB 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 (as of March 2024) is 11.5. 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
apt-get install build-essential libncurses5-dev gnutls-dev bison zlib1g-dev ccache

On RedHat based distributions:

dnf builddep mariadb

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

Please note that on some MacOS systems, the default bison version is a bit older than what we need to build MariaDB. Please try to install bison from Homebrew if you encounter grammar errors during the build process.

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 mariadbd 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_UNIT_TESTS=OFF -DCMAKE_BUILD_TYPE=Debug -DWITHOUT_DYNAMIC_PLUGIN=ON -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. Option --parallel works for cmake version 3.20+, alternatively pass options to native tool like cmake --build . -- -j5.

Testing the server

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

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

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 (not working in MacOS).
--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 mariadbd after build

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

If you are running MariaDB for first time you will need to run mariadb-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 ~/mariadb.cnf file.

Note: if you are using macOS you will need to use the path to your home directory instead of ~ for all the subsequent steps in this document.

# 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 mariadbd configuration files and groups.

Now that you have created your own config file you can call it with flag `--defaults-file` while installing the system tables. To install the system tables call following from the build folder:

./scripts/mariadb-install-db --srcdir=../server --defaults-file=~/mariadb.cnf

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

sql/mariadbd --defaults-file=~/mariadb.cnf

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

sudo client/mariadb -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.