INSTALL

MySQL Connector/C++

This is a release of MySQL Connector/C++, Oracle's
dual-license C++ API for connecting client applications
to MySQL.

Copyright (c) 2008, 2016, Oracle and/or its affiliates. All rights reserved.

--------------------------------------------------------------------------------

CONTENTS

 * Contact
 * Installation
 * Prerequisites for building Connector/C++
 * Building on Unix
   * Run CMake to build a Makefile
   * Use make to build the libraries
   * CMake options: MySQL installation path, debug version and more
 * Building on Solaris
 * Building on Windows
 * Source layout
 * (if binary package) Further Platform Notes on Building


CONTACT

 For general discussion of the MySQL Connector/C++ please use the C/C++
 community forum at http://forums.mysql.com/list.php?167 or join the MySQL
 Connector/C++ mailing list at http://lists.mysql.com .

 Bugs can be reported at http://bugs.mysql.com .

 See also https://wikis.oracle.com/pages/viewpage.action?pageId=27394600


INSTALLATION

  The MySQL Driver for C++ is distributed in source and binary form.

  The binary distributions are available as TAR.GZ archives for all
  supported platforms but Windows. On Windows you either use a MSI Installer
  or unpack a ZIP archive to an appropriate place.

  Please check the Reference Manual for further information at:

    http://dev.mysql.com/doc/refman/5.5/en/connector-cpp.html

  Notes on building the driver from source can be found in the Reference
  Manual and below. At the end of this file you may find settings
  we have used to build a binary package for your platform.


PREREQUISITES FOR BUILDING CONNECTOR/C++

  The MySQL Connector/C++ is based on the MySQL client libary (MySQL C API).
  Connector C/C++ is linked against the MySQL client library. You need to have
  the MySQL client library installed in order to compile the Connector/C++.

  Typically the MySQL client library gets installed by installing
  the MySQL Server. However, check your operating system documentation for
  other installation options.

  Alternatively you can install the new MySQL Connector/C. The MySQL Connector/C
  is a standalone version of the MySQL client library.

  You need to have CMake 2.6.2 (http://www.cmake.org).
  NOTE: cmake binaries are available for most systems. You do not need to build
  cmake yourself.

  As of version 1.1.0 Connector/C++ makes use of Boost (http://www.boost.org).
  You need to have Boost 1.34.0 or newer installed on your build system.
  The MySQL driver for C++ makes use of Boost variant, any and some pointers.
  All of those are "headers only". When installing Boost on your system,
  you can disable all components that require building any kind
  of binaries. Connector/C++ source version 1.1.5 must use Boost 1.54.0. Also 
  applications using Connector/C++ 1.1.5 should use Boost 1.54.0.

BUILDING ON UNIX

  The MySQL Connector/C++ is using the cross platform make CMake. CMake
  creates classical Makefiles. Please visit http://www.cmake.org for
  further information and documentation.

  1. Run CMake to build a Makefile

    me@host:/path/to/mysql-connector-cpp> cmake .
    -- Check for working C compiler: /usr/local/bin/gcc
    -- Check for working C compiler: /usr/local/bin/gcc -- works
    -- Check size of void*
    -- Check size of void* - done
    -- Check for working CXX compiler: /usr/bin/c++
    -- Check for working CXX compiler: /usr/bin/c++ -- works
    -- mysql_config was found /usr/bin/mysql_config
    -- MySQL Include dir: /usr/include/mysql
    -- MySQL Library    :
    -- MySQL Library dir: /usr/lib64/mysql;/usr/lib64
    [...]
    -- Configuring done
    -- Generating done
    -- Build files have been written to: /path/to/mysql-connector-cpp


  Read on at point 3) in case of configure problems.

  2. Use make to build the libraries

    me@host:/path/to/mysql-connector-cpp> make clean
    me@host:/path/to/mysql-connector-cpp> make
    Scanning dependencies of target mysqlcppconn
    [  0%] Building CXX object driver/CMakeFiles/mysqlcppconn.dir/mysql_art_resultset.cpp.o
    [  1%] Building CXX object driver/CMakeFiles/mysqlcppconn.dir/mysql_art_rset_metadata.cpp.o
    [  2%] Building CXX object driver/CMakeFiles/mysqlcppconn.dir/mysql_connection.cpp.o
    [...]
    [100%] Building CXX object test/unit/template_bug_group/CMakeFiles/bug456.dir/bug456.o
    Linking CXX executable bug456

  If all goes well, you will find the Connector/C++ library in
  /path/to/driver/libcppmysqlcppconn.so . In case of problems read on below
  before you ask for assistance.

  If you want to install the libraries on your system proceed with make install.

  me@host:/path/to/mysql-connector-cpp> make install

  3. CMake options: MySQL installation path, debug version and more

  In case of configure and/or compile problems check the list of CMake options:

    me@host:/path/to/mysql-connector-cpp> cmake -L
    [...]
    CMAKE_BUILD_TYPE:STRING=
    CMAKE_INSTALL_PREFIX:PATH=/usr/local
    MYSQLCLIENT_STATIC_BINDING:BOOL=1
    MYSQLCPPCONN_BUILD_EXAMPLES:BOOL=1
    MYSQLCPPCONN_DT_RPATH:STRING=
    MYSQLCPPCONN_DYNLOAD_MYSQL_LIB:FILEPATH=/usr/lib64/libmysqlclient_r.so
    MYSQLCPPCONN_GCOV_ENABLE:BOOL=0
    MYSQLCPPCONN_ICU_ENABLE:BOOL=0
    MYSQLCPPCONN_STLPORT_ENABLE:BOOL=0
    MYSQLCPPCONN_TEST_NOT_IMPLEMENTED:BOOL=0
    MYSQLCPPCONN_TRACE_ENABLE:BOOL=0
    MYSQL_CONFIG_EXECUTABLE:FILEPATH=/usr/bin/mysql_config

  You may also try cmake -LA to get a list of all options including
  the advanced options.

  For example, if your MySQL Server installation path is not /usr/local/mysql
  and you want to build a debug version of the MySQL Connector/C++ use:

    me@host:/path/to/mysql-connector-cpp>
     cmake -DCMAKE_BUILD_TYPE:STRING=Debug -DMYSQL_CONFIG_EXECUTABLE:FILEPATH=/path/to/my/mysql/server/bin/mysql_config .

  Verify your settings with cmake -L:

    me@host:/path/to/mysql-connector-cpp> cmake -L
    [...]
    CMAKE_BUILD_TYPE:STRING=
    CMAKE_INSTALL_PREFIX:PATH=/usr/local
    MYSQLCLIENT_STATIC_BINDING:BOOL=1
    MYSQLCPPCONN_BUILD_EXAMPLES:BOOL=1
    MYSQLCPPCONN_DT_RPATH:STRING=
    MYSQLCPPCONN_DYNLOAD_MYSQL_LIB:FILEPATH=/usr/lib64/libmysqlclient_r.so
    MYSQLCPPCONN_GCOV_ENABLE:BOOL=0
    MYSQLCPPCONN_ICU_ENABLE:BOOL=0
    MYSQLCPPCONN_STLPORT_ENABLE:BOOL=0
    MYSQLCPPCONN_TEST_NOT_IMPLEMENTED:BOOL=0
    MYSQLCPPCONN_TRACE_ENABLE:BOOL=0
    MYSQL_CONFIG_EXECUTABLE:FILEPATH=/path/to/my/mysql/server/bin/mysql_config

  Proceed with make clean; make as described at point 2.)

  NOTE: cmake does cache settings in the file CMakeCache.txt.
  Make sure that cmake does not use old and unwanted settings from
  CMakeCache.txt. This may cause compile problems. If so, delete CMakeCache.txt,
  configure custom settings with cmake -D, if any and try compiling again.


BUILDING ON SOLARIS

  Use the Sun compiler to build the MySQL Connector/C++.

  Ensure that your environment points cmake to the appropriate compiler
  binaries. The binary distributions of the MySQL Server are build using Sun
  compilers. The MySQL tool mysql_config returns compiler flags suitable for
  Sun compilers but possibly not suitable for GCC.

  If you plan to use GCC on Solaris to compile MySQL Connector/C++,
  you might need to insert

  SET(MYSQL_CXXFLAGS "")

  at the end of the file /path/to/mysql-connector-cpp/FindMySQL.cm.
  However, its recommended to use Sun Studio on Solaris.
  No changes are required when using the Sun compilers!

  Make sure that you do not mix Sun compilers with GNU compilers when building
  the MySQL Connector/C++. For example, do not use GCC as a C compiler and
  Sun CC as a C++ compiler. The linker might fail to link the results
  from both compilers to one binary.


BUILDING ON WINDOWS

  The MySQL Connector/C++ is using the cross platform make CMake. CMake
  creates classical Makefiles. Please visit http://www.cmake.org for
  further information and documentation.

  You need to have the environment variables set for the Visual Studio
  toolchain. Visual Studio includes a batch file to set these for you,
  and installs a shortcut into the Start menu to open a command prompt
  with these variables set.

  You need to set MYSQL_DIR to point to where the MySQL server is
  installed, using the short-style filenames:

   set MYSQL_DIR=C:\PROGRA~1\MySQL\MYSQLS~1.0

  Build Connector/C++ using the "cmake" command-line tool by doing the
  following from the source root directory (in a command prompt window);

    cmake -G "Visual Studio 8 2005"

  This produces a project file that you can open with Visual Studio or
  build from the command line with either of:

   devenv.com MySQLCPPCONN.sln /build Release
   devenv.com MySQLCPPCONN.sln /build RelWithDebInfo

  To compile the "Debug" build, you must run set the cmake build type so
  the correct version of the MySQL client libraries are used:

    cmake -G "Visual Studio 8 2005" -DCMAKE_BUILD_TYPE=Debug
    devenv.com MySQLCPPCONN.sln /build Debug

  Upon completion; you will find the executables in the subdirectories of the
  "bin" and "lib" directories.

  Different versions of CMake come with different "generators". A generator
  is the component of CMake that is responsible for writing the build files.
  If, for example, cmake --help does not list a generator for
  Visual Studio 9 2008, try a more recent version of CMake.

  Connector C/C++ supports only Microsoft Visual Studio 2003 and above
  on Windows.


SOURCE LAYOUT

  The MySQL Connector/C++ distribution contains the following directories:

  |-- cppconn              <-- Header files of the public interface
  |-- driver               <-- Connector/C++ source code
  |-- examples             <-- Basic examples
  |-- test                 <-- Tests, so to say: more examples
  |-- thread               <-- Thread abstraction, unused
  --- win                  <-- Windows MSI Installer


FURTHER PLATFORM NOTES ON BUILDING

If this INSTALL file is contained in a binary package, you will see below
what settings we have used to create the binary.

If this INSTALL file is contained in a source package and, you have build
issues, please download a binary package for your platform and check
the platform specific settings found in its INSTALL file. It may help 
to check the settings used by us for building.