MySQL Connector/C++ Developer Guide  /  Building Connector/C++ Applications  /  Building Connector/C++ 8.0 Applications from the Command Line with make

5.2 Building Connector/C++ 8.0 Applications from the Command Line with make

This section discusses building Connector/C++ 8.0 applications from the command line using make. It applies to any platform that supports make and command-line build tools such as g++, cc, or clang. For information about building Connector/C++ 8.0 applications on Windows using a graphical interface, see Section 5.3, “Building Connector/C++ Applications on Windows with Microsoft Visual Studio”.

Connector/C++ Header Files

The API an application uses determines which Connector/C++ header files it should include. The following include directives work under the assumption that the include path contains $MYSQL_CPPCONN_DIR/include, where $MYSQL_CPPCONN_DIR is the Connector/C++ installation location. Pass an -I $MYSQL_CPPCONN_DIR/include option on the compiler invocation command to ensure this.

  • For applications that use X DevAPI:

    #include <mysqlx/xdevapi.h>
  • For applications that use X DevAPI for C:

    #include <mysqlx/xapi.h>
  • For applications that use the legacy JDBC API:

    #include <jdbc/mysql_driver.h>
    #include <jdbc/mysql_connection.h>
    #include <jdbc/cppconn/*.h>

    Legacy code that uses Connector/C++ 1.1 has #include directives of this form:

    #include <mysql_driver.h>
    #include <mysql_connection.h>
    #include <cppconn/*.h>

    To build such code with Connector/C++ 8.0 without modifying it, add $MYSQL_CPPCONN_DIR/include/jdbc to the include path.

To compile code that you intend to link statically against Connector/C++, define a macro that adjusts API declarations in the header files for usage with the static library. For details, see Using the Connector/C++ Static Library.

Using the Connector/C++ Dynamic Library

The Connector/C++ dynamic library name depends on the platform. These libraries implement X DevAPI and X DevAPI for C:

  • libmysqlcppconn8.so (Unix)

  • libmysqlcppconn8.1.dylib (macOS)

  • mysqlcppconn8-1-vsNN.dll, with import library vsNN/mysqlcppconn8.lib (Windows)

For the legacy JDBC API, the dynamic libraries are named as follows:

  • libmysqlcppconn.so.7 (Unix)

  • libmysqlcppconn.7.dylib (macOS)

  • mysqlcppconn-7-vsNN.dll, with import library vsNN/mysqlcppconn-static.lib (Windows)

On Windows, the vsNN value in library names depends on the MSVC compiler version used to build the libraries (for example, vs14 for MSVC 2015). This convention enables using libraries built with different versions of MSVC on the same system. For details, see Windows Notes.

To build code that uses X DevAPI or X DevAPI for C, add -lmysqlcppconn8 to the linker options. To build code that uses the legacy JDBC API, add -lmysqlcppconn. You must also indicate whether to use the 64-bit or 32-bit libraries by specifying the appropriate library directory. Use an -L linker option to specify $MYSQL_CONCPP_DIR/lib64 (64-bit libraries) or $MYSQL_CONCPP_DIR/lib (32-bit libraries), where $MYSQL_CPPCONN_DIR is the Connector/C++ installation location.

To build a Connector/C++ application that uses X DevAPI, has sources in app.cc, and links dynamically to the connector library, the Makefile might look like this:

MYSQL_CONCPP_DIR= Connector/C++ installation location
CPPFLAGS = -I $(MYSQL_CONCPP_DIR)/include -L $(MYSQL_CONCPP_DIR)/lib64
LDLIBS = -lmysqlcppconn8
CXXFLAGS = -std=c++11
app : app.cc

With that Makefile, the command make app generates the following compiler invocation:

g++ -std=c++11 -I .../include -L .../lib64 app.cc -lmysqlcppconn8 -o app

To build a plain C application that uses X DevAPI for C, has sources in app.c, and links dynamically to the connector library, the Makefile might look like this:

MYSQL_CONCPP_DIR= Connector/C++ installation location
CPPFLAGS = -I $(MYSQL_CONCPP_DIR)/include -L $(MYSQL_CONCPP_DIR)/lib64
LDLIBS = -lmysqlcppconn8
app : app.c

With that Makefile, the command make app generates the following compiler invocation:

cc -I .../include -L .../lib64 app.c -lmysqlcppconn8 -o app

Typically, X DevAPI for C applications are written in plain C. However, if application code does use C++11, the Makefile should also specify the -std=c++11 option:

CXXFLAGS = -std=c++11
Note

The resulting code, even though it is compiled as plain C, depends on the C++ runtime (typically libstdc++, though this may differ depending on platform or build tools; see Runtime Libraries).

To build a plain C++ application that uses the legacy JDBC API, has sources in app.c, and links dynamically to the connector library, the Makefile might look like this:

MYSQL_CONCPP_DIR= Connector/C++ installation location
CPPFLAGS = -I $(MYSQL_CONCPP_DIR)/include -L $(MYSQL_CONCPP_DIR)/lib64
LDLIBS = -lmysqlcppconn
app : app.c

The library option in this case is -lmysqlcppcon, rather than -lmysqlcppcon8 as for an X DevAPI or X DevAPI for C application.

With that Makefile, the command make app generates the following compiler invocation:

cc -I .../include -L .../lib64 app.c -lmysqlcppconn -o app

Typically, applications that use the legacy JDBC API are written in plain C++. However, if application code does use C++11, the Makefile should also specify the -std=c++11 option:

CXXFLAGS = -std=c++11
Note

When running an application that uses the Connector/C++ dynamic library, the library and its runtime dependencies must be found by the dynamic linker. See Runtime Libraries.

Using the Connector/C++ Static Library

It is possible to link your application with the Connector/C++ static library. This way there is no runtime dependency on the connector, and the resulting binary can run on systems where Connector/C++ is not installed.

Note

Even when linking statically, the resulting code still depends on all runtime dependencies of the Connector/C++ library. For example, if Connector/C++ is built using OpenSSL, the code has a runtime dependency on the OpenSSL libraries. See Runtime Libraries.

The Connector/C++ static library name depends on the platform. These libraries implement X DevAPI and X DevAPI for C:

  • libmysqlcppconn8-static.a (Unix, macOS)

  • vsNN/mysqlcppconn8-static.lib (Windows)

For the legacy JDBC API, the static libraries are named as follows:

  • libmysqlcppconn-static.a (Unix, macOS)

  • vsNN/mysqlcppconn-static.lib (Windows)

On Windows, the vsNN value in library names depends on the MSVC compiler version used to build the libraries (for example, vs14 for MSVC 2015). This convention enables using libraries built with different versions of MSVC on the same system. For details, see Windows Notes.

To compile code that you intend to link statically against Connector/C++, define a macro that adjusts API declarations in the header files for usage with the static library. One way to define the macro is by passing a -D option on the compiler invocation command:

  • For applications that use X DevAPI or X DevAPI for C, define the STATIC_CONCPP macro. All that matters is that you define it; the value does not matter. For example: -DSTATIC_CONCPP

  • 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. For example: -DCPPCONN_PUBLIC_FUNC=

To build a Connector/C++ application that uses X DevAPI, has sources in app.cc, and links statically to the connector library, the Makefile might look like this:

MYSQL_CONCPP_DIR= Connector/C++ installation location
CPPFLAGS = -DSTATIC_CONCPP -I $(MYSQL_CONCPP_DIR)/include
LDLIBS = $(MYSQL_CONCPP_DIR)/lib64/libmysqlcppconn8-static.a -lssl -lcrypto -lpthread
CXXFLAGS = -std=c++11
app : app.cc

With that Makefile, the command make app generates the following compiler invocation:

g++ -std=c++11 -DSTATIC_CONCPP -I .../include app.cc
  .../lib64/libmysqlcppconn8-static.a -lssl -lcrypto -lpthread -o app
Note

To avoid having the linker report unresolved symbols, the compile line must include the OpenSSL libraries and the pthread library on which Connector/C++ code depends.

OpenSSL libraries are not needed if Connector/C++ is built without them, but Connector/C++ as built and distributed by Oracle does depend on OpenSSL.

The exact list of libraries required by Connector/C++ library depends on the platform. For example, on Solaris, the socket, rt, and nsl libraries might be needed.

To build a plain C application that uses X DevAPI for C, has sources in app.c, and links statically to the connector library, the Makefile might look like this:

MYSQL_CONCPP_DIR= Connector/C++ installation location
CPPFLAGS = -DSTATIC_CONCPP -I $(MYSQL_CONCPP_DIR)/include
LDLIBS = $(MYSQL_CONCPP_DIR)/lib64/libmysqlcppconn8-static.a -lssl -lcrypto -lpthread
app : app.c

With that Makefile, the command make app generates the following compiler invocation:

cc -DSTATIC_CONCPP -I .../include app.c
  .../lib64/libmysqlcppconn8-static.a -lssl -lcrypto -lpthread -o app

If the application code uses C++11, the Makefile should also specify the -std=c++11 option:

CXXFLAGS = -std=c++11

To build a plain C application that uses the legacy JDBC API, has sources in app.c, and links statically to the connector library, the Makefile might look like this:

MYSQL_CONCPP_DIR= Connector/C++ installation location
CPPFLAGS = -DCPPCONN_PUBLIC_FUNC= -I $(MYSQL_CONCPP_DIR)/include
LDLIBS = $(MYSQL_CONCPP_DIR)/lib64/libmysqlcppconn-static.a -lssl -lcrypto -lpthread
app : app.c

The library option in this case names libmysqlcppcon-static.a, rather than libmysqlcppcon8-static.a as for an X DevAPI or X DevAPI for C application.

With that Makefile, the command make app generates the following compiler invocation:

cc -std=c++11 --DCPPCONN_PUBLIC_FUNC= -I .../include app.c
  .../lib64/libmysqlcppconn-static.a -lssl -lcrypto -lpthread -o app

If the application code uses C++11, the Makefile should also specify the -std=c++11 option:

CXXFLAGS = -std=c++11

When building plain C code, it is important to take care of connector's dependency on the C++ runtime, which is introduced by the connector library even though the code that uses it is plain C:

  • One approach is to ensure that a C++ linker is used to build the final code. This approach is taken by the Makefile shown here:

    MYSQL_CONCPP_DIR= Connector/C++ installation location
    CPPFLAGS = -DSTATIC_CONCPP -I $(MYSQL_CONCPP_DIR)/include
    LDLIBS = $(MYSQL_CONCPP_DIR)/lib64/libmysqlcppconn8-static.a -lssl -lcrypto -lpthread
    LINK.o = $(LINK.cc) # use C++ linker
    app : app.o

    With that Makefile, the build process has two steps: first the application source in app.c is compiled using a plain C compiler to produce app.o, then the final executable (app) is linked using the C++ linker, which takes care of the dependency on the C++ runtime:

    cc -DSTATIC_CONCPP -I .../include -c -o app.o app.c
    g++ -DSTATIC_CONCPP -I .../include app.o
      .../libmysqlcppconn8-static.a -lssl -lcrypto -lpthread -o app
  • Another approach is to use a plain C compiler and linker, but add the libstdc++ C++ runtime library as an explicit option to the linker. This approach is taken by the Makefile shown here:

    MYSQL_CONCPP_DIR= Connector/C++ installation location
    CPPFLAGS = -DSTATIC_CONCPP -I $(MYSQL_CONCPP_DIR)/include
    LDLIBS = $(MYSQL_CONCPP_DIR)/lib64/libmysqlcppconn8-static.a -lssl -lcrypto -lpthread -lstdc++
    app : app.c

    With that Makefile, the compiler is invoked as follows:

    cc -DSTATIC_CONCPP -I .../include app.c
      .../libmysqlcppconn8-static.a -lssl -lcrypto -lpthread -lstdc++ -o app
Note

Even if the application that uses Connector/C++ is written in plain C, the final executable depends on the C++ runtime which must be installed on the target computer on which the application will run.

macOS Notes

The binary distribution of Connector/C++ for macOS is compiled using the macOS native clang compiler. For that reason, an application that uses Connector/C++ should be built with the same clang compiler.

The clang compiler can use two different implementations of the C++ runtime library: either the native libc++ or the GNU libstdc++ library. It is important that an application uses the same runtime implementation as Connector/C++ that is, the native libc++. To ensure that, the -stdlib=libc++ option should be passed to the compiler and the linker invocations.

To build a Connector/C++ application that uses X DevAPI, has sources in app.cc, and links dynamically to the connector library, the Makefile for building on macOS might look like this:

MYSQL_CONCPP_DIR= Connector/C++ installation location
CPPFLAGS = -I $(MYSQL_CONCPP_DIR)/include -L $(MYSQL_CONCPP_DIR)/lib64
LDLIBS = -lmysqlcppconn8
CXX = clang++ -stdlib=libc++
CXXFLAGS = -std=c++11
app : app.cc

Binary packages for macOS include OpenSSL libraries that are required by code linked with the connector. These libraries are installed in the same location as the connector libraries and should be found there by the dynamic linker.

Windows Notes

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 debug or release mode. Then it can be built in 32-bit or 64-bit mode. Also, one can choose between the static (/MT) or the dynamic (/MD) runtime. Different versions of the MSVC compiler also use different versions of the runtime.

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

The binary distribution of Connector/C++ 8.0 ships libraries built in release mode using dynamic runtime (/MD). The libraries are built with MSVC 2015 (the exact compiler version can be found in the BUILDINFO.txt file included in the package). Consequently, the code that uses these libraries must be built with the same version of MSVC and 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 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++ in debug mode first.

There are separate 64-bit and 32-bit packages, each keeping libraries in the lib64 and lib directories, respectively. Package and library names also include vsNN. The vsNN value in these names depends on the MSVC compiler version used to build the libraries (for example, vs14 for MSVC 2015). This convention enables using libraries built with different versions of MSVC on the same system.

A dynamic connector library name has a .dll extension and is used with a import library that has a .lib extension in the vsNN subdirectory. Thus, a connector dynamic library named mysqlcppconn8-1-vs14.dll is used with the import library named vs14/mysqlcppconn8.lib. The 1 in the dynamic library name is the major ABI version number. (In the future, this will help using compatibility libraries with old ABI together with new libraries having a different ABI.) The vs14 subdirectory also contains a static version of the library named vs14/mysqlcppconn8-static.lib.

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

When building code that uses Connector/C++ libraries:

  • Add $MYSQL_CPPCONN_DIR/include as an additional include directory and $MYSQL_CONCPP_DIR/lib64/vs14 (64-bit libraries) or $MYSQL_CONCPP_DIR/lib/vs14 (32-bit libraries) as an additional library directory in the project configuration.

  • To use the dynamic library, add mysqlcppconn8.lib to the linker options (or mysqlcppconn.lib for legacy code).

  • For use the static library, add mysqlcppconn8-static.lib (or 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 the binary package provided by Oracle, they are present in the $MYSQL_CONCPP_DIR/lib64/vs14 or $MYSQL_CONCPP_DIR/lib/vs14 directory, and the corresponding OpenSSL .dll libraries are present in the main library directory, next to the connector .dll libraries.

Note

An 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.


User Comments
Sign Up Login You must be logged in to post a comment.