5.2 Building Connector/C++ Applications on Windows with Microsoft Visual Studio

This section describes how to build Connector/C++ applications for Windows using Microsoft Visual Studio. For general application-building information, see Section 5.1, “Building Connector/C++ Applications: General Considerations”.

Developers using Microsoft Windows must satisfy the following requirements:

• Microsoft Visual Studio 2015 is required to build Connector/C++ applications.

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

Linking Connector/C++ to Applications

Connector/C++ is available as a dynamic or static library to use with your application. This section describes how to link the library to your application.

Linking the Dynamic Library

To use a dynamic library file (.dll extension), link your application with a .lib import library. At runtime, the application must have access to the .dll library.

The following table indicates which import library and dynamic library files to use for Connector/C++. LIB denotes the Connector/C++ installation library path name.

Table 5.1 Connector/C++ Import Library and Dynamic Library Names

Import Library	Dynamic Library
LIB/mysqlcppconn.lib	LIB/mysqlcppconn.dll

Linking the Static Library

To use a static library file (.lib extension), link your application with the library.

The static library name is LIB/mysqlcppconn-static.lib, where LIB denotes the Connector/C++ installation library path name.

Building Connector/C++ Applications with Microsoft Visual Studio

The initial steps for building an application to use either the dynamic or static library are the same. Some additional steps vary, depend on whether you are building your application to 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 will not be 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, add the include/ directory of Connector/C++ (it should be located within the Connector/C++ installation directory). Also add the Boost library's root directory, if Boost is required to build the application (see Section 5.1, “Building Connector/C++ Applications: General Considerations”).

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 (it should be located within the Connector/C++ installation directory). The library 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.

Dynamic Build

If you are building 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 (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 following these rules:

   • For version 1.1.9 and later: 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. The required version is VC++ Redistributable 2015 for Connector/C++ 1.1.11 and higher (Commercial and Community builds), VC++ Redistributable 2013 for Connector/C++ versions prior to 1.1.11 (Community builds only).

   • For version 1.1.8 and before: Link to the dynamic version of the C++ Runtime Library by selecting the /MD compiler option.

   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.

Static Build

If you are building your application to use the 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 (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: 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 following these rules:

   • For version 1.1.9 and later: 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. The required version is VC++ Redistributable 2015 for Connector/C++ 1.1.11 and higher (Commercial and Community builds), VC++ Redistributable 2013 for Connector/C++ versions prior to 1.1.11 (Community builds only).

   • For version 1.1.8 and before: Link to the dynamic version of the C++ Runtime Library by selecting the /MD compiler option.

   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.