Chapter 5 Building Connector/C++ Windows Applications with Microsoft Visual Studio

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

Notes
  • The Boost C++ libraries are required to build Connector/C++ applications on Windows (but not to use Connector/C++ on a target host). Boost 1.56.0 or newer must be installed. To obtain Boost and its installation instructions, visit the official site.

  • To avoid potential crashes, the build configuration of Connector/C++ should match the build configuration of the application using it. For example, do not use the release build of Connector/C++ with a debug build of the client application.

Static Library

The Connector/C++ static library file is mysqlcppconn-static.lib. You link this library statically with your application.

Dynamic Library

The Connector/C++ dynamic library file is mysqlcppconn.dll. To build your client application, link it with the file mysqlcppconn.lib. At runtime, the application will require access to the files mysqlcppconn.dll.

Building a Connector/C++ Application with Microsoft Visual Studio

The initial steps for building an application to use either the static or dynamic library are the same. Some additional steps vary, depend on whether you are building your application to use the static or dynamic 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.

    This is required when using the Oracle-built Connector/C++, which is built in the release configuration, and the build configuration for the application must match that of the Connector/C++ it uses. To build you application with the debug configuration, you will have to build Connector/C++ from source yourself with the debug options.

  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.

    Figure 5.1 Setting Properties

    Setting properties

  6. In the Additional Include Directories text field, add the include/ directory of Connector/C++ (it should be located right under the installation directory of Connector/C++), and add also the Boost library's root directory.

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

    Figure 5.2 Additional Library Directories

    Additional Library Directories

  8. In the Additional Library Directories text field, add the lib/ directory of Connector/C++ (it should be located right under the installation directory of Connector/C++).

Static Build

The remaining steps depend on whether you are building an application to use the Connector/C++ static or dynamic library. If you are building your application to use the dynamic library, see Dynamic Build. If you are building your application to use the static library, follow these steps:

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

    Figure 5.3 Additional Dependencies

    Additional Dependencies

  2. Add mysqlcppconn-static.lib into the Additional Dependencies text field.

  3. By default CPPCONN_PUBLIC_FUNC is defined to declare functions to be compatible with an application that calls a DLL. If you are building an application to call the static library, ensure that function prototypes are compatible with this. In this case, define CPPCONN_PUBLIC_FUNC to be an empty string, so that functions are declared with the correct prototype.

    In the Project, Properties tree view, under C++, Preprocessor, enter CPPCONN_PUBLIC_FUNC= into the Preprocessor Definitions text field.

    Figure 5.4 Setting the CPPCONN_PUBLIC_FUNC Define

    Setting the CPPCONN_PUBLIC_FUNC define

    Note

    Make sure you enter CPPCONN_PUBLIC_FUNC= and not CPPCONN_PUBLIC_FUNC, so that it is defined as an empty string.

  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 right option for Runtime Library following these rules:

    • For the Community version of Connector/C++:

      • For version 1.1.8 and before: Link to the static version of the C++ runtime by selecting the /MT compiler option.

      • For version 1.1.9 and later: Link to the dynamic version of the C++ runtime by selecting the /MD compiler option. Also, target hosts running the client application need to have the Visual C++ Redistributable for Visual Studio 2013 installed.

    • For the Commercial version of Connector/C++: Link to the static version of the C++ runtime by selecting the/MT compiler option.

    Do NOT use the /MTd or /MDd option if you are using the Oracle-built Connector/C++; see the discussion here for an explanation.

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 mysqlcppconn.lib into the Additional Dependencies text field.

  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 right option for Runtime Library following these rules:

    • For the Community version of Connector/C++:

      • For version 1.1.8 and before: You can link either to the static or dynamic version of the C++ runtime by selecting the /MT or the /MD compiler option, respectively.

      • For version 1.1.9 and later: Link to the dynamic version of the C++ runtime by selecting the /MD compiler option. Also, target hosts running the client application need to have the Visual C++ Redistributable for Visual Studio 2013 installed.

    • For the Commercial version of Connector/C++: You can link either to the static or dynamic version of the C++ runtime by selecting the /MT or the /MD compiler option, respectively.

    Do NOT use the /MTd or /MDd option if you are using the Oracle-built Connector/C++; see the discussion here for an explanation.

  4. Copy mysqlcppconn.dll to the same directory as the application executable. Alternatively, extend the PATH environment variable using SET PATH=%PATH%;C:\path\to\cpp. Alternatively, you can copy mysqlcppconn.dll to the Windows installation Directory, typically c:\windows.

    mysqlcppconn.dll 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.