- File README-Visual-C++.md — part of check-in [a57c393299] at 2014-09-18 10:15:08 on branch trunk — Another pass on the README* files to move them away from Autotools, toward CMake. (user: tangent size: 5654)
Building libtabula with Visual C++
You need to have the MySQL or MariaDB C API development files on your system, since libtabula is built on top of it.
The easiest way to get these files is to download Connector/C.
If you need the DB server on your development system anyway, you may find that they come with the DBMS, either by default or as an option during the installation.
libtabula does not ship with
*.vc[x]proj files. Instead,
you generate them on your system using CMake, which produces a set
of such files customized to your particular system.
The standard way to use CMake on Windows is to:
Drop to a command prompt. Both PowerShell and
You can also use the Cygwin Bash shell, but you need to be sure you're not using the Cygwin version of
cmake, since that will try to build libtabula under Cygwin, even if your system also has Visual Studio installed. (The Cygwin version of CMake is built in such a way that it actually can't generate Visual Studio project and solution files.)
cdto the directory where you unpacked the libtabula sources.
Optional: Create a build directory underneath that, and
You can call it "build" if you have no better name. The name doesn't matter.
If you will be creating multiple build directories, we suggest that you call them "build-*", to clearly distinguish their purpose, or nest them under a single "build" directory:
libtabula-4.0.0/ build-32/ build-64/
libtabula-4.0.0/ build/ vs2010/ vs2012/ vs2013/
If you elect not to do this, the build products will be intermixed with the libtabula source files, making it harder to disentangle them. It also makes it more difficult to cope with multiple versions of Visual Studio on the same system, since the build products will conflict with each other.
cmake-guifollowed by the relative path to the source directory. If you created a single build directory underneath the source directory, the command is
If that succeeded, you can open the generated
If it failed, it should say why clearly enough that you can see how to fix it. If not, post the CMake output to the mailing list.
Locating C API Development Files
The CMake files try to figure out which C API development files you've got installed, automatically.
If it cannot find your MySQL/MariaDB development files, edit the
modules\FindMySQL.cmake file in a text editor, adding the library
and header file directories to the two directory lists you find within.
Then try again.
Choosing a Different C++ Compiler or CPU Target
The native Windows version of CMake normally tries to use Visual C++ if it's available, and it generates 32-bit project files by default.
If CMake finds multiple versions of Visual C++ installed, it will use the newest one. To force it to use another, give a command like:
cmake -G "Visual Studio 11 2012"
--help flag to get a list of available generators for the
To generate 64-bit executables instead, add "Win64" to the end of the generator name:
cmake -G "Visual Studio 12 2013 Win64"
If you have MinGW installed alongside Visual Studio and want it to
use MinGW instead, see
If you have Cygwin installed alongside Visual Studio and want CMake to
build under Cygwin instead of Visual C++, simply install the Cygwin
version of CMake using Cygwin's
setup*.exe program. That build of
CMake assumes you're building under Cygwin, for Cygwin, by default.
Building the Library and Example Programs
You must build both the Debug and Release versions of the library,
because a release build of your program won't work with a Debug
version of the libtabula DLL. These DLLs get different names, so you
can install them in the same directory if needed:
for the Debug version and
libtabula.dll for the Release version.
With the library built, run at least the
examples to ensure that the library is working correctly. In addition
to the other generic examples, there are a few Visual C++ specific
examples that you might want to look at in
See the examples README for further details.
Once you're sure the library is working correctly, you can run
install.hta file at the project root to install the library
files and headers in a directory of your choosing.
(Aside: You may not have come across the
.hta extension before.
It's for a rarely-used feature of Microsoft's Internet Explorer,
called HTML Applications. Know what Adobe AIR is? Kinda like
that, only without the compilation into a single binary blob which
you must install before you can run it. Just open
in a text editor to see how it works.)
Using libtabula in Your Own Projects
This is covered in the user manual, chapter 9.
If You Run Into Problems...
Especially if you have linking problems, make sure your project settings match the above. Visual C++ is very picky about things like run time library settings. When in doubt, try running one of the example programs. If it works, the problem is likely in your project settings, not in libtabula.