MySQL :: MySQL Connector/C++ Developer Guide :: 4.3 Installing Connector/C++ from Source

Configuring Connector/C++

Use CMake to configure and build Connector/C++. Only out-of-source-builds are supported, so create a directory to use for the build and change location into it. Then configure the build using this command, where concpp_source is the directory containing the Connector/C++ source code:

cmake concpp_source

It may be necessary to specify other options on the configuration command. Some examples:

By default, these installation locations are used:
- /usr/local/mysql/connector-c++-8.0 (Unix and Unix-like systems)
- User_home/MySQL/"MySQL Connector C++ 8.0" (Windows)
To specify the installation location explicitly, use the CMAKE_INSTALL_PREFIX option:
```
-DCMAKE_INSTALL_PREFIX=path_name
```
On Windows, you can use the -G and -A options to select a particular generator:
- -G "Visual Studio 16" -A x64 (64-bit builds)
- -G "Visual Studio 16" -A Win32 (32-bit builds)
Consult the CMake manual or check cmake --help to find out which generators are supported by your CMake version. (However, it may be that your version of CMake supports more generators than can actually be used to build Connector/C++.)
If the Boost C++ libraries are needed, use the WITH_BOOST option to specify their location:
```
-DWITH_BOOST=path_name
```
By default, the build creates dynamic (shared) libraries. To build static libraries, enable the BUILD_STATIC option:
```
-DBUILD_STATIC=ON
```
By default, the legacy JDBC connector is not built. To include the JDBC connector in the build, enable the WITH_JDBC option:
```
-DWITH_JDBC=ON
```

Note

If you configure and build the test programs later, use the same CMake options to configure them as the ones you use to configure Connector/C++ (-G, WITH_BOOST, BUILD_STATIC, and so forth). Exceptions: Path name arguments will differ, and you need not specify CMAKE_INSTALL_PREFIX.

For information about CMake configuration options, see Section 4.4, “Connector/C++ Source-Configuration Options”.

Specifying External Dependencies

Use CMake options to configure and build Connector/C++ with external sources that you can substitute for the required third-party dependencies currently bundled with the connector. If the dependency is an external library, then the library is linked dynamically to the connector. In contrast, bundled third-party libraries used by connector are linked statically to it.

Note

Using an external third-party library that cannot be linked to the connector dynamically causes the build to fail, even when the static library is available.

The supported options are:

For example, to use an external installation of Protobuf, instead of building it from bundled sources, specify the WITH_PROTOBUF option and provide the path name to the location where CMake can find the alternative dependency.

Note

If an external dependency cannot be found (or is unusable), then the build fails. No attempt is made to locate the bundled source.

cmake [other_options] -DWITH_PROTOBUF=path_name_to_protobuf_install

To configure the standard system-wide location for an external dependency, use the literal value system rather than providing a path name. For example:

-DWITH_SSL=system

For information about CMake configuration options, see Section 4.4, “Connector/C++ Source-Configuration Options”.

External dependencies make it possible to use shared third-party libraries that are linked dynamically to the connector. This can be an advantage because, for example, you cannot use the connector static library with an application that also links to a Protobuf library.

When running an application that is linked to the connector dynamic library, the third-party libraries on which the connector depends should be correctly found if they are placed in the file system next to the connector library. The application should also work when the libraries are installed at the standard system-wide locations. This assumes that the external third-party dependency version is expected by Connector/C++.

Except for Windows, it should be possible to run an application linked to the connector dynamic library when the connector library and the third-party libraries are placed in a nonstandard location, provided that these locations were stored as runtime paths when building the application (gcc -rpath option).

For Windows, an application that is linked to the connector shared library can be run only if the connector library and the libraries are stored either:

In the Windows system folder
In the same folder as the application
In a folder listed in the PATH environment variable

If the application is linked to the connector static library, it remains true that the required libraries must be found in one of the preceding locations.

Building Connector/C++

After configuring the Connector/C++ distribution, build it using this command:

cmake --build . --config build_type

The --config option is optional. It specifies the build configuration to use, such as Release or Debug. If you omit --config, the default is Debug.

Important

If you specify the --config option on the preceding command, specify the same --config option for later steps, such as the steps that install Connector/C++ or that build test programs.

If the build is successful, it creates the connector libraries in the build directory. (For Windows, look for the libraries in a subdirectory with the same name as the build_type value specified for the --config option.)

If you build dynamic libraries, they have these names:
- libmysqlcppconn8.so.1 (Unix)
- libmysqlcppconn8.3.dylib (macOS)
- mysqlcppconn8-1-vs14.dll (Windows)
If you build static libraries, they have these names:
- libmysqlcppconn8-static.a (Unix, macOS)
- mysqlcppconn8-static.lib (Windows)

If you enabled the WITH_JDBC option to include the legacy JDBC connector in the build, the following additional library files are created.

If you build legacy dynamic libraries, they have these names:
- libmysqlcppconn.so.7 (Unix)
- libmysqlcppconn.7.dylib (macOS)
- mysqlcppconn-7-vs14.dll (Windows)
If you build legacy static libraries, they have these names:
- libmysqlcppconn-static.a (Unix, macOS)
- mysqlcppconn-static.lib (Windows)

Installing Connector/C++

To install Connector/C++, use this command:

cmake --build . --target install --config build_type

Verifying Connector/C++ Functionality

To verify connector functionality, build and run one or more of the test programs included in the testapp directory of the source distribution. Create a directory to use and change location into it. Then issue the following commands:

cmake [other_options] -DWITH_CONCPP=concpp_install concpp_source/testapp
cmake --build . --config=build_type

WITH_CONCPP is an option used only to configure the test application. other_options consists of the options that you used to configure Connector/C++ itself (-G, WITH_BOOST, BUILD_STATIC, and so forth). concpp_source is the directory containing the Connector/C++ source code, and concpp_install is the directory where Connector/C++ is installed:

The preceding commands should create the devapi_test and xapi_test programs in the run directory of the build location. If you enable WITH_JDBC when configuring the test programs, the build also creates the jdbc_test program.

Before running test programs, ensure that a MySQL server instance is running with X Plugin enabled. The easiest way to arrange this is to use the mysql-test-run.pl script from the MySQL distribution. For MySQL 8.0, X Plugin is enabled by default, so invoke this command in the mysql-test directory of that distribution:

perl mysql-test-run.pl --start-and-exit

The command should start a test server instance with X Plugin enabled and listening on port 13009 instead of its standard port (33060).

Now you can run one of the test programs. They accept a connection-string argument, so if the server was started as just described, you can run them like this:

run/devapi_test mysqlx://root@127.0.0.1:13009
run/xapi_test mysqlx://root@127.0.0.1:13009

The connection string assumes availability of a root user account without any password and the programs assume that there is a test schema available (assumptions that hold for a server started using mysql-test-run.pl).

To test jdbc_test, you need a MySQL server, but X Plugin is not required. Also, the connection options must be in the form specified by the JDBC API. Pass the user name as the second argument. For example:

run/jdbc_test tcp://127.0.0.1:13009 root