9. Using Libtabula in Your Own Project

Up to now, this manual has only discussed libtabula in conjunction with the example programs that come with the library. This chapter covers the steps you need to take to incorporate libtabula into your own projects.

The first thing you have to do is include libtabula.h in each module that uses libtabula. In modules that use SSQLS v1, you also need to include ssqls.h.[22]

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.

9.1. Visual C++

Using Libtabula in an MFC Project

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:\libtabula\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:\libtabula\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 libtabula_d.lib

    ...and then for the Release configuration: libmysql.lib wsock32.lib libtabula.lib

    This difference is because libtabula’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 libtabula.dll.

Using Libtabula in a Windows Forms C++/CLI Project

Before you start work on getting libtabula working with your own program, you need to make some changes to the libtabula build settings. Open libtabula.sln, then right-click on the libtabula 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 libtabula, 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 libtabula’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 libtabula.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 libtabula.dll built with different settings.

Once you have libtabula 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 libtabula.)

  • 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 libtabula_d.dll and libtabula.dll.

9.2. Unixy Platforms: Linux, *BSD, OS X, Cygwin, Solaris...

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 libtabula might look something like this:

#include <libtabula.h>

int main()
    libtabula::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/libtabula
LDFLAGS := -L/usr/local/lib
LDLIBS := -ltabula -lmysqlclient


    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. libtabula programs need to get built against both the MySQL and libtabula libraries, because libtabula is built on top of the MySQL C API library[23] If you’re building a threaded program, use -lmysqlclient_r instead of -lmysqlclient here. (See Section 7, “Using Libtabula 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, libtabula 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 libtabula 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.

9.3. OS X


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 libtabula 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 libtabula in an Xcode project. Send a message to the libtabula mailing list if you can help out here.

9.4. MinGW


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:

MYSQL_DIR := "c:/Program Files/MySQL/MySQL Connector C 6.1"
CXXFLAGS := -I$(MYSQL_DIR)/include -Ic:/libtabula/include
LDFLAGS := -L$(MYSQL_DIR)/lib -Lc:/libtabula/lib/MinGW
LDLIBS := -lmysql -ltabula



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.

Third-Party MinGW IDEs (Dev-C++, Code::Blocks...)

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.

9.5. Eclipse

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.

[22] Libtabula has many header files, but the only one that isn’t intertwined with the rest is ssqls.h. libtabula.h brings in all of the others in the correct order. Some have tried to speed their build times by finding a subset of libtabula headers to include, but libtabula.h already does as much of this as is practical. Libtabula’s monolithic nature rules out finding a true subset of the library headers.

[23] The MySQL C API library is most commonly called libmysqlclient on Unixy systems, though it is also known as Connector/C.