The client library — libmysqlclient — is part of the same source code repository as the server. It comes both as a dynamic link library (.so), also called a shared library, and as a static link library (.a). During the 5.7 development cycle, we’ve made several improvements to the library, which has resulted in a bump from ABI version 18 to version 20. This is the fourth and final part in a series of blog posts focusing on the client library. If you want to read the whole series, go back to the first post, called The API, the whole API and nothing but the API.

In my previous post, I covered a few changes we’ve made to the build process. This time, we’re going to use some of that to build a simple example application using modern tools.

Hello, MySQL World

We’re going to write a simple application in C that connects to a MySQL server and executes queries. The entire source code of this project can be downloaded from http://github.com/nryeng/hello-mysql-world.

Prerequisites

We’re going to use the following tools:

• CMake
• pkg-config
• libmysqlclient version 20 (comes with MySQL 5.7)
• GCC

The installation details are different for every OS, so it would take a whole new series of blog posts to explain how to install all these. I’m simply going to assume that they are installed.

The source code

The application itself is very simple: It asks for host name, port number, user name, password and database name. It then connects to the server and lets you execute queries. The full source code is in the file hello.c in the GitHub repo.

Our simple application will be dynamically linked with the client library.

Using CMake to build our application

CMake is a cross-platform build system. The goal of this blog post is to demonstrate how simple it is to add a libmysqlclient dependency to CMake projects using pkg-config, not to teach CMake basics, but I’ll explain a little about each line anyways.

Our CMake script looks like this:

Line 3 tells you which CMake version is required to run this script. I have 3.0.2, so I put 3.0 there. It might also work with older versions if you lower that number.

Line 4 says that this project is called hello-mysql-world and that it’s written in C. And since I’m using C99, I’ve added the C flag for that in line 5.

The next few lines is where the pkg-config magic happens. In line 7, we include the FindPkgConfig module, a CMake module that uses pkg-config to find libraries. Then, in line 8, we use the pkg_check_modules command provided by that module to find the libmysqlclient library. Let’s go through the parameters one by one.

The result of the pkg_check_modules command is that a number of variables will be set, and the first parameter to the command is the prefix for those variables. I’ve chosen LIBMYSQLCLIENT so that my variables will be called LIBMYSQLCLIENT_FOUND (which is set to 1 if the library is found), LIBMYSQLCLIENT_LIBRARIES (which is the list of libraries to link with), etc. A full list of variables can be found in the FindPkgConfig documentation.

The second parameter, REQUIRED, says that CMake should fail if the library isn’t found. Our application won’t build without the library, so I’ve chosen to fail fast if pkg-config can’t locate the library.

Third and last is the name of the library, or module, as it is called in pkg-config terms. Typically, this is the same as what you specify in the -l option on the linker command line, i.e., the name of the library without the “lib” prefix. In our case, that means “mysqlclient”.

The FindPkgConfig module will call pkg-config to find out everything it can about the library and set CMake variables for everything.

Lines 10–12 loop through the LIBMYSQLCLIENT_CFLAGS_OTHER list and append each flag to CMAKE_C_FLAGS. The list is created by pkg_check_modules and contains all the C flags that are needed to compile, except the flags for include directories and linking, which we will specify in a different way.

Line 14 tells CMake to tell the linker to look for libraries in the directory where pkg_check_modules found the libmysqlclient library.

Lines 16–18 specifies that hello.c will be compiled to make an executable called “hello”, and to build it we need to include header files from LIBMYSQLCLIENT_INCLUDE_DIR and link with the libraries listed in LIBMYSQLCLIENT_LIBRARIES. Both these variables are set by the pkg_check_modules command.

Building and running

Now that we have both the source code and the build script, we can try to build the application:

As we can see in line 18, CMake finds libmysqlclient version 20.0.9 and is able to build the application. Let’s try it out!

That’s it! We wrote a simple MySQL client and used CMake and pkg-config to build it.

In part 2 of this series, we talked about what the version number means and how the linker uses it to find the right library. Let’s look at the library dependencies for our hello application:

In line 3 we see that the application depends on libmysqlclient.so.20, which is the 5.7 client library. This means that we’ve linked this applications with version 20 of the client library, and we only know that version 20 will work. In this case I happen to know that version 18, and maybe even older version, works, but the linker can’t take the chance on that. If I want to use another version, I have to recompile.

Summary

This concludes our four-part series of libmysqlclient blog posts. We’ve covered several topics relating to shared libraries in general and the MySQL client library in particular:

• The API
• The version number
• How to build MySQL clients

And in the end, we summed it all up in this final example. I hope you’ve learned something!

If you have any questions or comments, please use the comment field below.