<?xml version="1.0" encoding='UTF-8'?>
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook V4.3//EN"
    "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">

<sect1 id="incorporating">
  <title>Using MySQL++ in Your Own Project</title>

  <para>Up to now, this manual has only discussed MySQL++ in
  conjunction with the example programs that come with it. This chapter
  covers the steps you need to take to incorporate MySQL++ into your own
  projects.</para>

  <para>The first thing you have to do is include
  <filename>mysql++.h</filename> in each module that uses MySQL++.
  In modules that use <link linkend="ssqls">SSQLS</link>, you also
  need to include <filename>ssqls.h</filename>.<footnote><para>MySQL++
  has many more header files, but don&rsquo;t include any of them
  directly.  <filename>mysql++.h</filename> includes all of them for
  you (except <filename>ssqls.h</filename> of course) in the correct
  order.</para></footnote></para>

  <para>At this point, your project probably won&rsquo;t compile, and
  it certainly won&rsquo;t link. The steps to fix this are dependent
  on your particular platform. The rest of this chapter is broken
  up into several sections, one for each major platform type. These
  sections are independent of each other. Feel free to ignore the
  sections for platforms you don&rsquo;t use.</para>


  <sect2 id="inc-vstudio">
    <title>Visual C++</title>

    <sect3 id="inc-vstudio-mfc">
      <title>Using MySQL++ in an MFC Project</title>

      <para>If you don&rsquo;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.</para>

      <para>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&rsquo;t
      specify Debug or Release, make the same change to both
      configurations.)</para>

      <itemizedlist>
        <listitem><para>Append the following to C/C++
        | General | Additional Include Directories:
        <filename>C:\Program Files\MySQL\MySQL Server 5.0\include,
        C:\mysql++\include</filename></para></listitem>

        <listitem><para>Under C/C++ | Code Generation change
        &ldquo;Runtime Library&rdquo; to &ldquo;Multi-threaded
        Debug DLL (/MDd)&rdquo; for the Debug configuration. For
        the Release configuration, make it &ldquo;Multi-threaded DLL
        (/MD)&rdquo;.</para></listitem>

        <listitem>
          <para>Append the following to Linker | General |
          Additional Library Directories for the Debug configuration:
          <filename>C:\Program Files\MySQL\MySQL Server 5.0\lib\debug,
          C:\mysql++\vc\debug</filename></para>

          <para>For the Release configuration, make it the same,
          but change the &ldquo;debug&rdquo; directory names to
          &ldquo;opt&rdquo;.</para>
        </listitem>

        <listitem>
          <para>Under Linker | Input add the following to
          &ldquo;Additional Dependencies&rdquo; for the Debug
          configuration: <filename>libmysql.lib wsock32.lib
          mysqlpp_d.lib</filename></para>

          <para>...and then for the Release configuration:
          <filename>libmysql.lib wsock32.lib
          mysqlpp.lib</filename></para>

          <para>This difference is because MySQL++&rsquo;s Debug
          DLL and import library have a <filename>_d</filename>
          suffix so you can have both in the same directory without
          conflicts.</para>
        </listitem>
      </itemizedlist>

      <para>You may want to study
      <filename>examples\vstudio\mfc\mfc.vcproj</filename>
      to see this in action. Note that some of the paths will
      be different, because it can use relative paths for
      <filename>mysqlpp.dll</filename>.</para>
    </sect3>


    <sect3 id="inc-vstudio-wforms">
      <title>Using MySQL++ in a Windows Forms C++/CLI Project</title>

      <para>Before you start work on getting MySQL++ working with your
      own program, you need to make some changes to the MySQL++ build
      settings. Open <filename>mysqlpp.sln</filename>, then right-click
      on the mysqlpp target and select Properties. Make the following
      changes for both the Debug and Release configurations:</para>

      <itemizedlist>
        <listitem><para>Under Configuration Properties | General,
        change &ldquo;Common Language Runtime support&rdquo; to the
        /clr setting.</para></listitem>

        <listitem><para>Under C/C++ | Code Generation, change
        &ldquo;Enable C++ Exceptions&rdquo; from &ldquo;Yes
        (/EHsc)&rdquo; to &ldquo;Yes With SEH Exceptions
        (/EHa)&rdquo;</para></listitem>
      </itemizedlist>

      <para>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++&rsquo;s Windows installer
      (<filename>install.hta</filename>) offers the option to install
      the CLR version into a separate directory; use it if you need
      both managed and unmanaged versions installed!</para>

      <para>For the same reason, you might give some thought about
      where you install <filename>mysqlpp.dll</filename> on your
      end user&rsquo;s machines when distributing your program.
      My recommendation is to install it in the same directory as
      the <filename>.exe</filename> file that uses it, rather than
      installing into a system directory where it could conflict
      with a <filename>mysqlpp.dll</filename> built with different
      settings.</para>

      <para>Once you have MySQL++ built with CLR support, open your
      program&rsquo;s project.  If you don&rsquo;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.</para>

      <para>The configuration process isn&rsquo;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:</para>

      <itemizedlist>
        <listitem><para>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++.)</para></listitem>

        <listitem><para>For the Linker | Input settings, you
        don&rsquo;t need <filename>wsock32.lib</filename>. The mere
        fact that you&rsquo;re using .NET takes care of that dependency
        for you.</para></listitem>
      </itemizedlist>

      <para>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&rsquo;s not strictly true for MFC, but it&rsquo;s
      an absolute requirement for C++/CLI. See the Remarks in <ulink
      url="http://msdn.microsoft.com/en-us/library/k8d11d4s.aspx">the
      MSDN article on the /clr switch</ulink> for details.</para>

      <para>You may want to study
      <filename>examples\vstudio\wforms\wforms.vcproj</filename>
      to see all this in action. Note that some of the
      paths will be different, because it can use relative
      paths for <filename>mysqlpp_d.dll</filename> and
      <filename>mysqlpp.dll</filename>.</para>
    </sect3>
  </sect2>


  <sect2 id="inc-unix">
    <title>Unixy Platforms: Linux, *BSD, OS X, Cygwin, Solaris...</title>

    <para>There are lots of ways to build programs on Unixy
    platforms.  We&rsquo;ll cover just the most generic way
    here, <filename>Makefile</filename>s. We&rsquo;ll use a very
    simple example so it&rsquo;s clear how to translate this to
    more sophisticated build systems such as GNU Autotools or
    Bakefile.</para>

    <para>&ldquo;Hello, world!&rdquo; for MySQL++ might look something
    like this:</para>

    <programlisting><xi:include href="hello.cpp" parse="text"
    xmlns:xi="http://www.w3.org/2001/XInclude"/></programlisting>

    <para>Here&rsquo;s a <filename>Makefile</filename> for building
    that program:</para>

    <programlisting><xi:include href="Makefile.hello.posix" parse="text"
    xmlns:xi="http://www.w3.org/2001/XInclude"/></programlisting>

    <para>The first three lines are where all of the assumptions
    about file and path names are laid out. Probably at least one of
    these assumptions isn&rsquo;t true for your system, and so will
    require changing.</para>

    <para>The trickiest line is the third 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. If you&rsquo;re building a threaded program,
    use <filename>-lmysqlclient_r</filename> instead. (See <xref
    linkend="threads"/> for more details on building thread-aware
    programs.)</para>

    <para>On some systems, the order of libraries in the
    <varname>LDFLAGS</varname> 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.</para>

    <para>You might need to add more libraries to the
    <varname>LDFLAGS</varname> line.  <filename>-lnsl</filename>,
    <filename>-lz</filename> and <filename>-lm</filename> are
    common. If you study how MySQL++ itself gets built on your system,
    you can see what it uses, and emulate that.</para>

    <para>Beyond that, we have a pretty vanilla
    <filename>Makefile</filename>. We don&rsquo;t have any special
    dependency or build rules, because the default rules should work
    fine, particularly if you&rsquo;re using GNU make, which is just
    about universal these days.</para>
  </sect2>


  <sect2 id="inc-osx">
    <title>OS X</title>

    <sect3 id="inc-osx-makefile">
      <title>Makefiles</title>

      <para>The <link linkend="inc-unix">generic Makefile
      instructions above</link> cover most of what you need to know
      about using Makefiles on OS X.</para>

      <para>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 <filename>ld</filename> directly.</para>

      <para>Another tricky bit on OS X is the concept of Universal
      binaries. See <filename>README-Mac-OS-X.txt</filename> 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.</para>
    </sect3>

    <sect3 id="inc-osx-xcode">
      <title>Xcode</title>

      <para>I have no information on how to incorporate MySQL++ in
      an Xcode project. Send a message to the MySQL++ mailing list
      if you can help out here.</para>
    </sect3>
  </sect2>


  <sect2 id="inc-mingw">
    <title>MinGW</title>

    <sect3 id="inc-mingw-makefile">
      <title>Makefiles</title>

      <para>The <link linkend="inc-unix">generic Makefile instructions
      above</link> apply to MinGW&rsquo;s version of GNU make as
      well. You will have some differences due to the platform, so
      here&rsquo;s the adjusted <filename>Makefile</filename>:</para>

      <programlisting><xi:include
      href="Makefile.hello.mingw" parse="text"
      xmlns:xi="http://www.w3.org/2001/XInclude"/></programlisting>

      <para>Note the use of forward slashes. Also, we use
      <command>del</command> instead of <command>rm</command>
      in the clean target; this assumes there is no
      <filename>sh.exe</filename> in your <varname>PATH</varname>,
      which may not be true if you have Cygwin or MSYS installed. Read
      on to see how to cope with that.</para>

      <sect4 id="inc-mingw-cygwin">
        <title>Working with MinGW Under Cygwin</title>

        <para>Compared to Unix, the biggest difference you&rsquo;ll
        find is that MinGW calls its <filename>make</filename>
        executable <filename>mingw32-make</filename>. As I understand
        it, this is to allow it to coexist with Cygwin, since the two
        versions have some behavioral differences, despite both being
        based on GNU Make.  A <filename>Makefile</filename> written
        for one is likely to fail to work correctly with the other,
        so you have to be able to specify which one you mean.</para>

        <para>If you have both MinGW and Cygwin installed, you may be
        tempted to use Cygwin&rsquo;s superior command line environment
        over a Windows command shell or MSYS. If you&rsquo;re like me,
        you type <filename>make</filename> reflexively now; typing
        <filename>mingw32-make</filename> instead isn&rsquo;t going
        to work. Another problem with having Cygwin and MinGW on the
        same system is that this puts a <filename>sh.exe</filename>
        program in your system&rsquo;s <varname>PATH</varname>
        which makes MinGW make send shell commands to it instead of
        <filename>cmd.exe</filename> as it normally would.  I find it
        best to set up a special MinGW environment to avoid problems
        stemming from these platform differences.</para>

        <para>I&rsquo;ve created a pair of scripts that let me work
        in Cygwin mode most of the time and temporarily drop down
        into &ldquo;MinGW mode&rdquo; only when necessary. I call the
        first script <filename>mingw</filename>, and put it somewhere
        in the Cygwin <varname>PATH</varname>:</para>

        <programlisting>
  #!/bin/sh
  PATH=/cygdrive/c/mingw/bin:/cygdrive/c/windows:/cygdrive/c/windows/system32:/cygdrive/c/cygwin/bin
  echo "Say 'exit' to leave MinGW shell and restore Cygwin environment."
  /usr/bin/bash --rcfile ~/.mingwrc
  </programlisting>

        <para>Then there&rsquo;s a tiny little file called
        <filename>.mingwrc</filename> that goes in your Cygwin home
        directory:</para>

        <programlisting>
  alias make=mingw32-make
  PS1='MinGW: \W \$ '
  </programlisting>

        <para>(This split is necessary due to the way Bash works.)</para>

        <para>The first script sets up most of the MinGW environment,
        putting the MinGW and Windows directories ahead of the Cygwin
        directory so programs in those locations take precedence. Then
        the second script finishes setting up the MinGW sub-shell,
        causing the <filename>make</filename> command to invoke
        MinGW&rsquo;s make program instead of Cygwin&rsquo;s, and
        changing the command prompt to remind you that you&rsquo;re
        in a sub-shell. Just say <command>exit</command> to get back
        to Cygwin mode.</para>
      </sect4>
    </sect3>

    <sect3 id="inc-mingw-ide">
      <title>Third-Party MinGW IDEs (Dev-C++, Code::Blocks...)</title>

      <para>I have no information on how to do this. We&rsquo;ve
      received reports on the mailing list from people that have made
      it work, but no specifics on what all needs to be done. The
      Makefile discussion above should give you some hints.</para>
    </sect3>
  </sect2>


  <sect2 id="inc-eclipse">
    <title>Eclipse</title>

    <para>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
    <link linkend="inc-unix">above</link>, 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.</para>

    <para>For example, on my OS X system I use
    <filename>/usr/bin/gnumake</filename> for the program location
    and pick the project root with the Browse Workspace button to
    set the working directory.</para>
  </sect2>
</sect1>