5.2.1 Windows Notes

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

Developers using Microsoft Windows must satisfy these conditions to build Connector/C++ applications:

  • An acceptable version of Microsoft Visual Studio is required.

  • Your applications should use the same linker configuration as Connector/C++. For example, use one of /MD, /MDd, /MT, or /MTd.

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

For information about which Visual Studio and VC++ Restributable versions are acceptable, see Platform Support and Prerequisites.

On Windows, applications can be built in different modes (also called build configurations), which determine the type of the 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 debug or release mode.

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

Binary distributions of Connector/C++ 8.0 are available as 64-bit and 32-bit packages, which store libraries in directories named lib64 and 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.

It is important to ensure that the compiler version and the build mode of an application match the corresponding parameters used to build the connector library, to ensure that the connector and the application use the same runtime library.

Binary distributions of Connector/C++ 8.0 ship libraries built in release mode using the dynamic runtime (/MD). The libraries are compatible with MSVC 2019 and 2017, and code that uses these libraries can be built with either MSVC 2019 or 2017 in /MD mode. To build code in a different mode, first build Connector/C++ from source in that mode (see Section 4.3, “Installing Connector/C++ from Source”), then build your applications using the same mode.

Note

When linking dynamically, it is possible to build your code in debug mode even if the connector libraries are built in release mode. However, in that case, it is not possible to step inside connector code during a debug session. To be able to do that, or to build in debug mode while linking statically to the connector, you must first build Connector/C++ in debug mode

Linking Connector/C++ to Applications

Connector/C++ is available as a dynamic or static library to use with your application.

A dynamic connector library name has a .dll extension and is used with an import library that has a .lib extension in the vsNN subdirectory. Thus, a connector dynamic library named mysqlcppconn8-2-vs14.dll is used with an import library named vs14/mysqlcppconn8.lib. 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. The corresponding static library is named vs14/mysqlcppconn8-static.lib.

A legacy JDBC connector dynamic library named mysqlcppconn-7-vs14.dll is used with an import library named vs14/mysqlcppconn.lib. The corresponding static library is named vs14/mysqlcppconn-static.lib.

The following tables indicate which dynamic and import library files to use for dynamic linking, and which static library files to use for static linking. LIB denotes the Connector/C++ installation library path name. The name of the last path component is lib64 (for 64-bit packages) or lib (for 32-bit packages).

Table 5.1 Connector/C++ Dynamic and Import Libraries

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

Table 5.2 Connector/C++ Static Libraries

Connector Type Static Library File Name
X DevAPI, X DevAPI for C LIB/vs14/mysqlcppconn8-static.lib
JDBC LIB/vs14/mysqlcppconn-static.lib

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 $MYSQL_CONCPP_DIR/lib64 (for 64-bit libraries) or $MYSQL_CONCPP_DIR/lib (for 32-bit libraries).

  • To use a dynamic library file (.dll extension), link your application with a .lib import library: add vs14/mysqlcppconn8.lib to the linker options, or vs14/mysqlcppconn.lib for legacy code. At runtime, the application must have access to the .dll library.

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

If linking statically, the linker must find the link libraries (with .lib extension) for the required OpenSSL libraries. If the connector was installed from a binary package provided by Oracle, they 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, next to the connector .dll libraries.

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 put the required DLLs in the same location as the executable.

Building Connector/C++ Applications with Microsoft Visual Studio

The initial steps for building an application are the same whether you use the dynamic or static library. Some additional steps vary, depending on whether you use the dynamic or static library.

Initial Application-Building Steps

These steps are the same whether you use the dynamic or static library:

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

  2. In the drop-down list for build configuration on the toolbar, change the configuration from the default option of Debug to Release.

    Connector/C++ and Application Build Configuration Must Match

    Because the application build configuration must match that of the Connector/C++ it uses, Release is required when using an Oracle-built Connector/C++, which is built in the release configuration. When linking dynamically, it is possible to build your code in debug mode even if the connector libraries are built in release mode. However, in that case, it is not possible to step inside connector code during a debug session. To be able to do that, or to build in debug mode while linking statically to the connector, you must build Connector/C++ from source yourself using the Debug configuration.

  3. From the main menu select Project, Properties. This can also be accessed using the hot key ALT + F7.

  4. Under Configuration Properties, open the tree view.

  5. Select C/C++, General in the tree view.

  6. In the Additional Include Directories text field:

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

  8. In the Additional Library Directories text field, add the Connector/C++ library directory. This directory should be located within the Connector/C++ installation directory. The directory name ends with lib64 (for 64-bit builds) or lib (for 32-bit builds).

The remaining steps depend on whether you are building an application to use the Connector/C++ dynamic or static library.

Building with the Dynamic Library

To build an application to use the Connector/C++ dynamic library, follow these steps:

  1. Open Linker, Input in the Property Pages dialog.

  2. Add the appropriate import library name into the Additional Dependencies text field. For example, use vs14/mysqlcppconn8.lib, or vs14/mysqlcppconn.lib for legacy applications; see Linking Connector/C++ to Applications.

  3. Choose the C++ Runtime Library to link to. In the Property Pages dialog, open C++, Code Generation in the tree view, and then select the appropriate option for Runtime Library.

    Link to the dynamic version of the C++ Runtime Library by selecting the /MD compiler option. Also, target hosts running the client application must have the Visual C++ Redistributable for Visual Studio installed. For information about which VC++ Restributable versions are acceptable, see Platform Support and Prerequisites.

    Do not use the /MTd or /MDd option if you are using an Oracle-built Connector/C++. For an explanation, see this discussion: Connector/C++ and Application Build Configuration Must Match.

  4. Copy the appropriate 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.

    The dynamic library must be in the same directory as the application executable, or somewhere on the system's path, so that the application can access the Connector/C++ dynamic library at runtime.

Building with the Static Library

To build an application to use the Connector/C++ static library, follow these steps:

  1. Open Linker, Input in the Property Pages dialog.

  2. Add the appropriate static library name into the Additional Dependencies text field. For example, use vs14/mysqlcppconn8-static.lib, or vs14/mysqlcppconn-static.lib for legacy applications; see Linking Connector/C++ to Applications.

  3. To compile code that is linked statically with the connector library, define a macro that adjusts API declarations in the header files for usage with the static library. By default, the macro is defined 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.

  4. Choose the C++ Runtime Library to link to. In the Property Pages dialog, open C++, Code Generation in the tree view, and then select the appropriate option for Runtime Library.

    Link to the dynamic version of the C++ Runtime Library by selecting the /MD compiler option. Also, target hosts running the client application must have the Visual C++ Redistributable for Visual Studio installed. For information about which VC++ Restributable versions are acceptable, see Platform Support and Prerequisites.

    Do not use the /MTd or /MDd option if you are using an Oracle-built Connector/C++. For an explanation, see this discussion: Connector/C++ and Application Build Configuration Must Match.