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.
The first thing you have to do is include
mysql++.h in each module that uses MySQL++.
In modules that use SSQLS, you also
need to include ssqls.h.[17]
At this point, your project probably won’t compile, and it certainly won’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’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 Server 5.0\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)”.
Append the following to Linker | General |
Additional Library Directories for the Debug configuration:
C:\Program Files\MySQL\MySQL Server 5.0\lib\debug,
C:\mysql++\vc\debug
For the Release configuration, make it the same, but change the “debug” directory names to “opt”.
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:
CXX := g++
CXXFLAGS := -I/usr/include/mysql -I/usr/local/include/mysql++
LDFLAGS := -L/usr/local/lib -lmysqlpp -lmysqlclient
EXECUTABLE := hello
all: $(EXECUTABLE)
clean:
rm -f $(EXECUTABLE) *.o
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’t true for your system, and so will require changing.
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’re building a threaded program,
use -lmysqlclient_r instead. (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
LDFLAGS 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
LDFLAGS 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.
Beyond that, we have a pretty vanilla
Makefile. We don’t have any special
dependency or build rules, because the default rules should work
fine, particularly if you’re using GNU make, which is just
about universal these days.
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:
CXX := g++ MYSQL_DIR := "c:/Program Files/MySQL/MySQL Server 5.0" CXXFLAGS := -I$(MYSQL_DIR)/include -Ic:/MySQL++/include LDFLAGS := -L$(MYSQL_DIR)/lib/opt -Lc:/MySQL++/lib/MinGW -lmysqlclient -lmysqlpp EXECUTABLE := hello all: $(EXECUTABLE) clean: del $(EXECUTABLE)
Note the use of forward slashes. Also, we use
del instead of rm
in the clean target; this assumes there is no
sh.exe in your PATH,
which may not be true if you have Cygwin or MSYS installed. Read
on to see how to cope with that.
Compared to Unix, the biggest difference you’ll
find is that MinGW calls its make
executable mingw32-make. 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 Makefile 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.
If you have both MinGW and Cygwin installed, you may be
tempted to use Cygwin’s superior command line environment
over a Windows command shell or MSYS. If you’re like me,
you type make reflexively now; typing
mingw32-make instead isn’t going
to work. Another problem with having Cygwin and MinGW on the
same system is that this puts a sh.exe
program in your system’s PATH
which makes MinGW make send shell commands to it instead of
cmd.exe as it normally would. I find it
best to set up a special MinGW environment to avoid problems
stemming from these platform differences.
I’ve created a pair of scripts that let me work
in Cygwin mode most of the time and temporarily drop down
into “MinGW mode” only when necessary. I call the
first script mingw, and put it somewhere
in the Cygwin PATH:
#!/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
Then there’s a tiny little file called
.mingwrc that goes in your Cygwin home
directory:
alias make=mingw32-make PS1='MinGW: \W \$ '
(This split is necessary due to the way Bash works.)
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 make command to invoke
MinGW’s make program instead of Cygwin’s, and
changing the command prompt to remind you that you’re
in a sub-shell. Just say exit to get back
to Cygwin mode.
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.
[17] MySQL++
has many more header files, but don’t include any of them
directly. mysql++.h includes all of them for
you (except ssqls.h of course) in the correct
order.