Using Connector/C++ 2.0  {#usage}
=======================

Connector/C++ 2.0 can be used as either a static or a shared library.
If used as a shared library, the library must be installed on the target
machine in order for the application to run. The shared library name is:

- `libmysqlcppconn2.so` on Unix platforms (the soname is
  `libmysqlcppconn2.so.1`)
- `libmysqlcppconn2.dylib` on the OSX platform (the soname is
  `libmysqlcppconn2.1.dylib`)
- `mysqlcppconn2-vsXX.dll` on Windows platforms (see
   [Windows Notes](@ref usage_win) for explanation of `-vsXX` suffixes)

The static library name is:

- `libmysqlcppconn2-static.a` on OSX and Unix platforms.
- `mysqlcppconn2-static.lib` on Windows platforms,

In what follows we assume that Connector/C++ 2.0 is installed to the location
given by `$MYSQL_CONCPP_DIR`.


Using the shared library
------------------------

When compiling code which uses the connector, add `$MYSQL_CONCPP_DIR/include`
to project's include path and `$MYSQL_CONCPP_DIR/lib` or
`$MYSQL_CONCPP_DIR/lib64` to the library path (the latter on a 64-bit platform).
Then add `-lmysqlcppconn2` to the linker options (on Unix systems also add
`-lpthread` required by Connector/C++ on these platforms).

If code uses X DevAPI, enable C++11 support in the compiler as it is required
by the X DevAPI headers. For `gcc` and `clang` compilers this can be done
using `-std=c++11` option. Connector/C++ requires gcc version 4.8 or later.

An example `Makefile` to build an application which uses Connector/C++ X DevAPI,
with sources in `app.cc` is shown below:

~~~~~~~
MYSQL_CONCPP_DIR= ...
CPPFLAGS = -I $(MYSQL_CONCPP_DIR)/include -L $(MYSQL_CONCPP_DIR)/lib64
LDLIBS = -lmysqlcppconn2 -lpthread
CXXFLAGS = -std=c++11

app : app.cc
~~~~~~~

It generates the following compiler invocation:

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


The connector can be also used with plain C code written against XAPI.
An example `Makefile` to build a plain C application from sources in `app.c`
might look like this:

~~~~~~~
MYSQL_CONCPP_DIR= ...
CPPFLAGS = -I $(MYSQL_CONCPP_DIR)/include -L $(MYSQL_CONCPP_DIR)/lib64
LDLIBS = -lmysqlcppconn2 -lpthread

app : app.c
~~~~~~~

which generates the following compiler invocation:

~~~~~~~
cc  -I .../include -L .../lib64  app.c  -lmysqlcppconn2 -lpthread -o app
~~~~~~~

Note that the resulting code, even though it is compiled as plain C, will
depend on the C++ runtime (`libstdc++`).

@note When running an application which uses the shared Connector/C++ library,
the library must be found by the dynamic linker. Either the connector library
must be installed in a system-wide location known to the dynamic linker, or
one can set the LD_LIBRARY_PATH environment variable to indicate the location
where connector libraries can be found.

@note Because Connector/C++ exports C++ classes in its X DevAPI, code which
uses it should be built using the same compiler that was used to build the
connector. If using the binary distribution of the connector, then compile with
`clang` on OSX and with `gcc` on other Unix systems. See also [Window Notes]
(@ref usage_win) for details about compiling code on Windows.


Using the static library
------------------------

It is possible to link your application with the static connector 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.

When compiling code which is linked with the connector library statically,
it is important to define the `STATIC_CONCPP` macro. This macro is used
to adjust API declarations in connector's public headers for usage with
the static library.

An example `Makefile` to build a C++ application that links to the connector
library statically is shown below:

~~~~~~~
MYSQL_CONCPP_DIR= ...
CPPFLAGS = -DSTATIC_CONCPP -I $(MYSQL_CONCPP_DIR)/include
LDLIBS = $(MYSQL_CONCPP_DIR)/lib64/libmysqlcppconn2-static.a -lpthread
CXXFLAGS = -std=c++11

app : app.cc
~~~~~~~

It generates the following compiler invocation:

~~~~~~~
g++ -std=c++11 -DSTATIC_CONCPP -I .../include  app.cc  .../lib64/libmysqlcppconn2-static.a -lpthread -o app
~~~~~~~


When building plain C code it is important to take care of connector's
dependency on the C++ runtime. Best way is to ensure that a C++ linker is used
to build the final code. This approach is taken in the example `Makefile` below:

~~~~~~~
MYSQL_CONCPP_DIR= ...
CPPFLAGS = -DSTATIC_CONCPP -I $(MYSQL_CONCPP_DIR)/include
LDLIBS = $(MYSQL_CONCPP_DIR)/lib64/libmysqlcppconn2-static.a -lpthread
LINK.o = $(LINK.cc) # use C++ linker

app : app.o
~~~~~~~

With this `Makefile` the build process has two steps: first the application
source in `app.c` is compiled using plain C compiler, then the final executable
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  .../libmysqlcppconn2-static.a -lpthread -o app
~~~~~~~


Another approach is to use plain C compiler and linker, but add the C++ runtime
library `libstdc++` as an explicit input to the linker:

~~~~~~~
MYSQL_CONCPP_DIR= ...
CPPFLAGS = -I $(MYSQL_CONCPP_DIR)/include
LDLIBS = $(MYSQL_CONCPP_DIR)/lib64/libmysqlcppconn2-static.a -lpthread -lstdc++

app : app.c
~~~~~~~

With this `Makefile` the compiler is invoked as follows:

~~~~~~~
cc  -DSTATIC_CONCPP -I .../include  app.c  .../libmysqlcppconn2-static.a -lpthread -lstdc++ -o app
~~~~~~~

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


OS X Notes
----------

The binary distribution of Connector/C++ for OS X is compiled using the OS X
native `clang` compiler. For that reason an application that uses the connector
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.

An example `Makefile` for OS X build is shown below. Note that there is no
dependency on `pthread` library on OS X.

~~~~~~~
MYSQL_CONCPP_DIR= ...
CPPFLAGS = -I $(MYSQL_CONCPP_DIR)/include -L $(MYSQL_CONCPP_DIR)/lib64
LDLIBS = -lmysqlcppconn2
CXX = clang++ -stdlib=libc++
CXXFLAGS = -std=c++11

app : app.cc
~~~~~~~


Windows Notes                                            @anchor usage_win
-------------

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 a debug or
a release mode. Then it can be built in a 32-bit or a 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 matches the same parameters used when building the connector
library. This is to ensure that the runtime library used by the connector
and the application is the same. For that reason the binary distribution
of Connector/C++ for Windows includes several variants of the library built
with different parameters.

@note Only release mode builds are supported by the current binary
distribution of Connector/C++ 2.0. Debug variants of the connector
libraries, if required, must be built from sources.

There are separate 32-bit and 64-bit packages, each keeping libraries in
`lib/` and `lib64/` folder, respectively. The library folder contains two
versions of the shared library:

- `mysqlcppconn2-vs12.dll` - built with MSVC 2013, compiler version 18.00
- `mysqlcppconn2-vs14.dll` - built with MSVC 2015, compiler version 19.00

The corresponding import libraries are in `vs12/` or `vs14/` subfolder
of the library folder:

- `vs12/mysqlcppconn2.lib` - import library for `mysqlcppconn2-vs12.dll`
- `vs14/mysqlcppconn2.lib` - import library for `mysqlcppconn2-vs14.dll`

A project which uses the shared connector library must be configured to link
with the import library `mysqlcppconn2.lib`. The library path should be
set to `.../vs12` or `.../vs14`, as appropriate for the MSVC version being
used.

@note An application which uses the shared connector library must be able
to locate it at the runtime. The common way of arranging this is to put
the connector DLL in the same location as the executable.


The static library comes in two more flavors, giving the user a choice
to build his code either with the static (`/MT`) or the dynamic runtime (`/MD`).
If building code in the `/MT` mode, the `mysqlconcpp2-static-mt.lib` connector
library should be used. For `/MD` builds the `mysqlconcpp2-static.lib` should
be used. These libraries are found in either `vs12/` or `vs14/` subfolder, as
appropriate for the MSVC version being used.

@note The shared library uses dynamic runtime (`/MD`) and the code which uses
the shared library should be built in the same `/MD` mode. There is
no possibility to use shared connector library from code built in `/MT` mode.
Attempt to do it can lead to undefined behavior.


@todo Building applications in 'Debug' mode using binary distribution
      of Connector/C++.
@todo How to build on OSX with XCode.
@todo Dynamic linking with other connector dependencies.


<!--
  Copyright (c) 2015, 2017, Oracle and/or its affiliates. All rights reserved.

  The MySQL Connector/C++ is licensed under the terms of the GPLv2
  <http://www.gnu.org/licenses/old-licenses/gpl-2.0.html>, like most
  MySQL Connectors. There are special exceptions to the terms and
  conditions of the GPLv2 as it is applied to this software, see the
  FLOSS License Exception
  <http://www.mysql.com/about/legal/licensing/foss-exception.html>.

  This program is free software; you can redistribute it and/or modify
  it under the terms of the GNU General Public License as published
  by the Free Software Foundation; version 2 of the License.

  This program is distributed in the hope that it will be useful, but
  WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
  for more details.

  You should have received a copy of the GNU General Public License along
  with this program; if not, write to the Free Software Foundation, Inc.,
  51 Franklin St, Fifth Floor, Boston, MA 02110-1301  USA
-->
