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. If you plan to build this connector, an additional git command is needed to perform submodule initialization (do this in the top-level source directory):
```
git submodule update --init
```
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”.

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.1.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

For MySQL 5.7, X Plugin must be enabled explicitly, so add an option to do that:

perl mysql-test-run.pl --start-and-exit --mysqld=--plugin-load=mysqlx

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