Up to now, this manual has only discussed MySQL++ in conjunction with the example programs that come with the library. This chapter covers the steps you need to take to incorporate MySQL++ into your own projects.
The first thing you have to do is include
  mysql++.h in each module
  that uses MySQL++. In modules that use SSQLS v1, you also need to include
  ssqls.h.[23]
At this point, your project probably still won’t compile, and it certainly won’t link. The remaining steps are dependent on the operating system and tools you are using. The rest of this chapter is broken up into several sections, one for each major platform type. You can skip over the sections for platforms you don’t use.
If you don’t already have a project set up, open Visual Studio, say File | New | Project, then choose Visual C++ | MFC | MFC Application. Go through the wizard setting up the project as you see fit.
Once you have your project open, right click on your top-level executable in the Solution Explorer, choose Properties, and make the following changes. (Where it doesn’t specify Debug or Release, make the same change to both configurations.)
Append the following to C/C++ | General |
        Additional Include Directories: C:\Program
        Files\MySQL\MySQL Connector C 6.1\include,
        C:\mysql++\include
Under C/C++ | Code Generation change “Runtime Library” to “Multi-threaded Debug DLL (/MDd)” for the Debug configuration. For the Release configuration, make it “Multi-threaded DLL (/MD)”.
For both Release and Debug builds, append the following
          to Linker | General | Additional Library Directories:
          C:\Program Files\MySQL\MySQL Connector C 6.1\lib,
          C:\mysql++\lib
Connector/C does include debug libraries, but you will probably not need to use them.
Under Linker | Input add the following to
          “Additional Dependencies” for the Debug
          configuration: libmysql.lib wsock32.lib
          mysqlpp_d.lib
...and then for the Release configuration:
          libmysql.lib wsock32.lib
          mysqlpp.lib
This difference is because MySQL++’s Debug
          DLL and import library have a _d
          suffix so you can have both in the same directory without
          conflicts.
You may want to study
      examples\vstudio\mfc\mfc.vcproj
      to see this in action. Note that some of the paths will
      be different, because it can use relative paths for
      mysqlpp.dll.
Before you start work on getting MySQL++ working with your
      own program, you need to make some changes to the MySQL++ build
      settings. Open mysqlpp.sln, then right-click
      on the mysqlpp target and select Properties. Make the following
      changes for both the Debug and Release configurations:
Under Configuration Properties | General, change “Common Language Runtime support” to the /clr setting.
Under C/C++ | Code Generation, change “Enable C++ Exceptions” from “Yes (/EHsc)” to “Yes With SEH Exceptions (/EHa)”
If you have already built MySQL++, be sure to perform a
      complete rebuild after changing these options.  The compiler
      will emit several C4835 warnings after making those changes,
      which are harmless when using the DLL with a C++/CLI
      program, but which warn of real problems when using it with
      unmanaged C++.  This is why MySQL++’s Windows installer
      (install.hta) offers the option to install
      the CLR version into a separate directory; use it if you need
      both managed and unmanaged versions installed!
For the same reason, you might give some thought about
      where you install mysqlpp.dll on your
      end user’s machines when distributing your program.
      My recommendation is to install it in the same directory as
      the .exe file that uses it, rather than
      installing into a system directory where it could conflict
      with a mysqlpp.dll built with different
      settings.
Once you have MySQL++ built with CLR support, open your program’s project. If you don’t already have a project set up, open Visual Studio, say File | New | Project, then choose Visual C++ | CLR | Windows Forms Application. Go through the wizard setting up the project as you see fit.
The configuration process isn’t much different from that for an MFC project, so go through the list above first. Then, make the following changes particular to .NET and C++/CLI:
Under Configuration Properties | General change the setting from /clr:pure to /clr. (You need mixed assembly support to allow a C++/CLI program to use a plain C++ library like MySQL++.)
For the Linker | Input settings, you
        don’t need wsock32.lib. The mere
        fact that you’re using .NET takes care of that dependency
        for you.
In the MFC instructions above, it said that you need to build it using the Multi-threaded DLL version of the C++ Runtime Library. That’s not strictly true for MFC, but it’s an absolute requirement for C++/CLI. See the Remarks in the MSDN article on the /clr switch for details.
You may want to study
      examples\vstudio\wforms\wforms.vcproj
      to see all this in action. Note that some of the
      paths will be different, because it can use relative
      paths for mysqlpp_d.dll and
      mysqlpp.dll.
There are lots of ways to build programs on Unixy
    platforms.  We’ll cover just the most generic way
    here, Makefiles. We’ll use a very
    simple example so it’s clear how to translate this
    to more sophisticated build systems such as GNU Autotools or
    Bakefile.
“Hello, world!” for MySQL++ might look something like this:
#include <mysql++.h>
int main()
{
    mysqlpp::String greeting("Hello, world!");
    std::cout << greeting << std::endl;
    return 0;
}
Here’s a Makefile for building
    that program:
CXXFLAGS := -I/usr/include/mysql -I/usr/local/include/mysql++
LDFLAGS := -L/usr/local/lib
LDLIBS := -lmysqlpp -lmysqlclient
EXECUTABLE := hello
all: $(EXECUTABLE)
clean: 
    rm -f $(EXECUTABLE) *.o
The *FLAGS lines are where all of the
    assumptions about file and path names are laid out. Probably at
    least one of these assumptions isn’t true for your system,
    and so will require changing.
The trickiest line is the LDLIBS
    one. MySQL++ programs need to get built against both the MySQL
    and MySQL++ libraries, because MySQL++ is built on top of the
    MySQL C API library[24]
    If you’re building a threaded program, use
    -lmysqlclient_r instead of
    -lmysqlclient here. (See Section 7, “Using MySQL++ in a Multithreaded Program” for more details on building thread-aware
    programs.)
On some systems, the order of libraries in the
    LDLIBS line is important: these linkers collect
    symbols from right to left, so the rightmost library needs to
    be the most generic. In this example, MySQL++ depends on MySQL,
    so the MySQL C API library is rightmost.
You might need to add more libraries to the
    LDLIBS line. -lnsl,
    -lz and -lm are
    common. If you study how MySQL++ itself gets built on your system,
    you can see what it uses, and emulate that.
You may be wondering why we have used both
    LDLIBS and LDFLAGS here. Some
    Makefiles you have seen collect both types
    of flags in a single variable. That can work if the variable
    is used in the right place in the link command. However, this
    particular Makefile is made with GNU make
    in mind, and uses its standard rules implicitly. Those rules
    are designed to use these two variables separately like this.
    If you were writing your own compilation rules, you could write
    them in such a way that you didn’t have to do this.
Beyond that, we have a pretty vanilla
    Makefile, thanks in large part to the fact
    that the default make rules are fine for
    such a simple program.
The generic
      Makefile instructions above
      cover most of what you need to know about using Makefiles on
      OS X.
One thing that may trip you up on OS X is that it uses an
      uncommon dynamic linkage system. The easiest way to cope with
      this is to link your executables with the compiler, rather than
      call ld directly.
Another tricky bit on OS X is the concept of Universal
      binaries. See README-Mac-OS-X.txt for
      details on building a Universal version of the MySQL++ library,
      if you need one. By default, you only get a version tuned for
      the system type you build it on.
The generic
      Makefile instructions above apply
      to MinGW’s version of GNU make as
      well. You will have some differences due to the platform, so
      here’s the adjusted Makefile:
SHELL := $(COMSPEC) MYSQL_DIR := "c:/Program Files/MySQL/MySQL Connector C 6.1" CXXFLAGS := -I$(MYSQL_DIR)/include -Ic:/MySQL++/include LDFLAGS := -L$(MYSQL_DIR)/lib -Lc:/MySQL++/lib/MinGW LDLIBS := -lmysql -lmysqlpp EXECUTABLE := hello all: $(EXECUTABLE) clean: del $(EXECUTABLE)
Note that I’ve used del
      instead of rm in the clean target. In
      the past, at least, MinGW make
      had some funny rules about whether commands in target
      rules would get run with sh.exe
      or with cmd.exe. I can’t
      currently get my installation of MinGW to do anything
      but use sh.exe by default, but that
      may be because I have Cygwin installed, which provides
      sh.exe.  This explains the first
      line in the file, which overrides the default shell with
      cmd.exe, purely to get consistent
      behavior across platforms. If you knew all your platforms
      would have a better shell, you’d probably want to use
      that instead.
Note the use of forward slashes in the path to the MySQL
      Connector/C development files. GNU make
      uses the backslash as an escape character, so you’d
      have to double them if you’re unwilling to use forward
      slashes.
As far as I can tell, the simplest way to build a C++ project
    with Eclipse is to set up a Makefile for it
    as described above, then add an
    external run configuration for your local make
    tool. Get the project building from the command line with
    make, then go to Run | External Tools | Open
    External Tools Dialog and add a new launch configuration.
For example, on my OS X system I use
    /usr/bin/gnumake for the program location
    and pick the project root with the Browse Workspace button to
    set the working directory.
[23] MySQL++ has many header
  files, but the only one that isn’t intertwined with the rest is
  ssqls.h. mysql++.h brings
  in all of the others in the correct order. Some have tried to speed
  their build times by finding a subset of MySQL++ headers to include,
  but mysql++.h already does as much of this as
  is practical. MySQL++’s monolithic nature rules out finding
  a true subset of the library headers.
[24] The MySQL C API library
    is most commonly called libmysqlclient
    on Unixy systems, though it is also known as Connector/C.