5.2.1 Windows Notes

This section describes aspects of building Connector/C++ applications that are specific to Microsoft Windows. For general application-building information, see Section 5.1, “Building Connector/C++ Applications: General Considerations”.

On Windows, applications can be built in different build configurations, which determine the type of the C++ runtime library that is used by the final executable:

• An application can be built in 32-bit or 64-bit mode.

• An application can be built in release or debug mode.

• You can choose between the dynamic runtime library (/MD linker option) or static runtime library (/MT linker option). Different versions of the MSVC compiler also use different versions of the runtime library.

To build Connector/C++ applications, developers using Windows must satisfy these conditions:

• An acceptable version of Microsoft Visual Studio is required.

• Applications should use the same build configuration as that used to build Connector/C++. Build configuration includes the build mode (release mode or debug mode) and the linker option (for example, /MD or /MDd).

• Target hosts running client applications must have an acceptable version of the Visual C++ Redistributable for Visual Studio installed.

For information about acceptable versions of Visual Studio and VC++ Redistributable, see Platform Support and Prerequisites.

The following sections provide additional detail about several aspects of building Connector/C++ applications:

• Application Build Configuration Must Match Connector/C++

• Linking Connector/C++ to Applications

• Building Connector/C++ Applications with Microsoft Visual Studio

Application Build Configuration Must Match Connector/C++

It is important to use a compatible compiler version to build applications and Connector/C++. It is also important to build applications using the same build configuration as that used to build Connector/C++. That is, applications should use the same build mode and linker option, to ensure that the connector and the application use the same runtime library.

The following table shows the linker option appropriate for each combination of build mode and runtime library. It also shows for each combination whether a Connector/C++ binary package is available from Oracle. (If not, you must build Connector/C++ from source yourself.)

Table 5.1 Connector/C++ Linker Option Per Build Mode and Runtime Library

Build Mode	Runtime Library	Linker Option	Binary Package Available
Release	Dynamic	/MD	Yes
Debug	Dynamic	/MDd	Yes
Release	Static	/MT	No (build from source)
Debug	Static	/MTd	No (build from source)

Standard Connector/C++ binary packages available from Oracle are built in release mode. If you install such a package, build applications in release mode to match. Oracle packages built in debug mode are available as well. To build applications in debug mode, you must either install an Oracle-built Connector/C++ package that was built in debug mode, or build Connector/C++ from source yourself using debug mode.

Linking Connector/C++ to Applications

Connector/C++ binary distributions are available as 64-bit or 32-bit packages, which store libraries under a directory named lib64 or lib, respectively. Package names and certain library file and directory names also include vsNN. The vsNN value in these names depends on the MSVC toolchain version used to build the libraries. This convention enables using libraries built with different versions of MSVC on the same system.

Note

The vsNN value represents the major version of the MSVC toolchain used to build the libraries. Currently it is vs14, which is the toolchain used by MSVC 2015 through 2019.

Connector/C++ binary packages include libraries built using the dynamic runtime library in either release mode (/MD) or debug mode (/MDd). The Connector/C++ libraries are compatible with MSVC 2019 and 2017, and code that uses these libraries can be built with either MSVC 2019 or 2017 using the appropriate linker option (that is, /MD for release mode or /MDd for debug mode). To build code with a different linker option (/MT or /MTd), first build Connector/C++ from source with that option (see Section 4.3, “Installing Connector/C++ from Source”), then build applications using the same option.

Note

One exception for compiler version compatibility is that to build applications using the static JDBC legacy connector, MSVC 2019 is required; 2017 does not work.

Connector/C++ is available as a dynamic or static library to use with your application. Which library you choose determines the library files needed, and the location of those files within a Connector/C++ package depends on whether the package was built in release or debug mode. Library files are located under the library directory, which, as previously mentioned, is lib64 for 64-bit packages or lib for 32-bit packages. Denote this directory as LIB. The following table shows the directory in which to find library files for each type of library (including import libraries, which are used in conjunction with dynamic libraries).

Table 5.2 Connector/C++ Library File Directories

Library Type	Library File Directory (Release Build)	Library File Directory (Debug Build)
Dynamic Library	LIB	LIB/debug
Import Library	LIB/vs14	LIB/vs14/debug
Static Library	LIB/vs14	LIB/vs14/debug

For dynamic linking, the following table indicates which dynamic and import library files to use.

Table 5.3 Connector/C++ Dynamic and Import Library Files Per Connector

Connector	Dynamic Library File	Import Library File
X DevAPI, X DevAPI for C	mysqlcppconn8-2-vs14.dll	mysqlcppconn8.lib
JDBC	mysqlcppconn-7-vs14.dll	mysqlcppconn.lib

For the X DevAPI or X DevAPI for C connector, use the dynamic library file named mysqlcppconn8-2-vs14.dll, together with with the import library file named mysqlcppconn8.lib from the import library directory. The 2 in the dynamic library name is the major ABI version number. (This helps when using compatibility libraries with an old ABI together with new libraries having a different ABI.) The libraries installed on your system may have a different ABI version in their file names.

For the legacy JDBC connector, use the dynamic library file named mysqlcppconn-7-vs14.dll, together with the import library file named mysqlcppconn.lib from the import library directory.

For static linking, the following table indicates which static library file to use.

Table 5.4 Connector/C++ Static Library File Per Connector

Connector	Static Library File
X DevAPI, X DevAPI for C	mysqlcppconn8-static.lib
JDBC	mysqlcppconn-static.lib

For the X DevAPI or X DevAPI for C connector, use the static library file named mysqlcppconn8-static.lib from the static library directory.

For the legacy JDBC connector, use the static library file named mysqlcppconn-static.lib from the static library directory.

When building code that uses Connector/C++ libraries, use these guidelines for setting build options in the project configuration:

• As an additional include directory, specify $MYSQL_CPPCONN_DIR/include.

• As an additional library directory, specify the directory containing the libraries the application must link to, as indicated in Table 5.2, “Connector/C++ Library File Directories”. For example, to specify the import or static library directory for building in release mode, use $MYSQL_CONCPP_DIR/lib64/vs14 (for 64-bit libraries) or $MYSQL_CONCPP_DIR/lib/vs14 (for 32-bit libraries). For building in debug mode, change vs14 to vs14/debug.

• To use a dynamic library file (.dll extension), link your application with a .lib import library: mysqlcppconn8.lib to the linker options, or mysqlcppconn.lib for legacy code.

• To use a static library file (.lib extension), link your application with the library: mysqlcppconn8-static.lib, or mysqlcppconn-static.lib for legacy code.

For static linking, the application must also be linked with import libraries for the required OpenSSL libraries. If the connector was installed from a binary package provided by Oracle, these are present in the vs14 subdirectory under the main library directory ($MYSQL_CONCPP_DIR/lib64 or $MYSQL_CONCPP_DIR/lib), and the corresponding OpenSSL .dll libraries are present in the main library directory.

Note

A Windows application that uses the connector dynamic library must be able to locate it at runtime, as well as its dependencies such as OpenSSL. The common way of arranging this is to copy all the required DLLs to the same location as the application executable.

Building Connector/C++ Applications with Microsoft Visual Studio

To build a Connector/C++ application with Microsoft Visual Studio, follow this procedure:

1. Start a new Visual C++ project in Visual Studio.

2. Set the required include paths.

   From the main menu, select Project, Properties. This can also be accessed using the hot key ALT + F7. Under Configuration Properties, open the tree view. Select C/C++, General in the tree view.

   In the Additional Include Directories text field:

   • Add the include/ directory of Connector/C++. This directory should be located within the Connector/C++ installation directory.

   • If Boost is required to build the application, also add the Boost library root directory. (See Section 5.1, “Building Connector/C++ Applications: General Considerations”.)

3. Set the library locations.

   In the tree view, open Linker, General, Additional Library Directories.

   In the Additional Library Directories text field, add the Connector/C++ import or static library directory as specified in Table 5.2, “Connector/C++ Library File Directories”. Set appropriate paths for release and debug builds.

   Note

   For building in debug mode, the Connector/C++ debug package must be installed.

4. Set the connector library to use.

   Open Linker, Input in the Property Pages dialog.

   For building with the Connector/C++ dynamic library, enter the import library name: mysqlcppconn8.lib, or mysqlcppconn.lib for legacy applications.

   For building with the Connector/C++ static library, enter the static library name: mysqlcppconn8-static.lib, or mysqlcppconn-static.lib for legacy applications.

   Note

   Generic Linux packages do not contain Connector/C++ static libraries.

5. Define macros for static linking.

   To compile code that is linked statically with the connector library, you must define a macro that adjusts API declarations in the header files for usage with the static library. By default, the macro is undefined to declare functions to be compatible with an application that calls a DLL.

   In the Project, Properties tree view, under C++, Preprocessor, enter the appropriate macro into the Preprocessor Definitions text field:

   • For applications that use X DevAPI, X DevAPI for C, or (as of Connector/C++ 8.0.16) the legacy JDBC API, define the STATIC_CONCPP macro. All that matters is that you define it; the value does not matter. For example: -DSTATIC_CONCPP

   • Prior to Connector/C++ 8.0.16, for applications that use the legacy JDBC API, define the CPPCONN_PUBLIC_FUNC macro as an empty string. To ensure this, define the macro as CPPCONN_PUBLIC_FUNC=, not as CPPCONN_PUBLIC_FUNC.

Notes

• Target hosts running the client application must have the Visual C++ Redistributable for Visual Studio installed. For information about which VC++ Redistributable versions are acceptable, see Platform Support and Prerequisites.

• If your code uses the Connector/C++ dynamic library, it must be present on the target host where the application is run. Copy the appropriate Connector/C++ dynamic library to the same directory as the application executable (see Linking Connector/C++ to Applications). Alternatively, extend the PATH environment variable using SET PATH=%PATH%;C:\path\to\cpp, or copy the dynamic library to the Windows installation directory, typically C:\windows.

• If your code uses the Connector/C++ static library, the required OpenSSL libraries must be found on the target host where the application is run. For Connector/C++ binary distributions, the OpenSSL .dll libraries are present in the main library directory ($MYSQL_CONCPP_DIR/lib64 or $MYSQL_CONCPP_DIR/lib). Copy them to the same location as the application executable or to some directory listed in the system PATH.