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 (
/MDlinker option) or static runtime library (
/MTlinker 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,
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:
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|
||No (build from source)|
||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.
Connector/C++ binary packages available from Oracle, whether built in release or debug mode, are intended for use with the dynamic version of the C++ runtime library. To build applications using the static runtime library, you must build Connector/C++ yourself from source using the appropriate linker option for the intended build mode.
Connector/C++ binary distributions are available as 64-bit or 32-bit
packages, which store libraries under a directory named
respectively. Package names and certain library file and
directory names also include
vs 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.
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,
release mode or
/MDd for debug mode). To
build code with a different linker option
build Connector/C++ from source with that option (see
Section 4.3, “Installing Connector/C++ from Source”), then
build applications using the same option.
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
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)|
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||
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
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
For the legacy JDBC connector, use the dynamic library file
with the import library file named
mysqlcppconn.lib from the import library
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||
For the X DevAPI or X DevAPI for C connector, use the static
library file named
mysqlcppconn8-static.lib from the static
For the legacy JDBC connector, use the static library file
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
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
To use a dynamic library file (
.dllextension), link your application with a
mysqlcppconn8.libto the linker options, or
mysqlcppconn.libfor legacy code.
To use a static library file (
.libextension), link your application with the library:
mysqlcppconn-static.libfor 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
subdirectory under the main library directory
$MYSQL_CONCPP_DIR/lib), and the
.dll libraries are
present in the main library directory.
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.
To build a Connector/C++ application with Microsoft Visual Studio, follow this procedure:
Start a new Visual C++ project in Visual Studio.
Set the required include paths.
From the main menu, select Configuration Properties, open the tree view. Select , General in the tree view., . This can also be accessed using the hot key + . Under
In the Additional Include Directories text field:
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”.)
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.
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:
mysqlcppconn.libfor legacy applications.
For building with the Connector/C++ static library, enter the static library name:
mysqlcppconn-static.libfor legacy applications.
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 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_CONCPPmacro. All that matters is that you define it; the value does not matter. For example:
Prior to Connector/C++ 8.0.16, for applications that use the legacy JDBC API, define the
CPPCONN_PUBLIC_FUNCmacro as an empty string. To ensure this, define the macro as
CPPCONN_PUBLIC_FUNC=, not as
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
PATHenvironment variable using
SET PATH=%PATH%;C:\, or copy the dynamic library to the Windows installation directory, typically
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
.dlllibraries are present in the main library directory (
$MYSQL_CONCPP_DIR/lib). Copy them to the same location as the application executable or to some directory listed in the system