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.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. 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 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: Here’s a Makefile for building that program: 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 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. 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. 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: Note the use of forward slashes. GNU make uses the backslash as an escape character, so you’d have to double them if you’re unwilling to use forward slashes. Also note that I’ve used del instead of rm in the clean target. Unless there is a program called sh.exe in your PATH, MinGW make uses Windows’ cmd.exe for shell commands. The most likely reason to have sh.exe is if you also have Cygwin or MSYS installed. The next section covers the best way I’ve found 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. I have no information on how to do this. We’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. 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.