libtabula

Update of "FAQ"
Login

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview

Artifact ID: f4d11b069cb889ef01329d5e7a3136411deeb1c0
Page Name:FAQ
Date: 2018-10-27 07:22:44
Original User: tangent
Mimetype:text/x-markdown
Content

Frequently-Asked Questions About libtabula

Should I use libtabula yet?

If you're mainly looking for a stable library, you should probably still be using MySQL++, this library's predecessor.

Until this library reaches a point of stability, the main reason to use it is if you need some of its new features.

We try to keep the trunk in a buildable state at all times, confining experimental work to branches.

What platforms does it work on?

libtabula should work on any platform that has a C++98 or newer compiler and the MariaDB or MySQL C API development files. libtabula does use some C99/TR1 features that didn’t make it into C++ until C++11 or later, but these are optional, so it still works with C++98 compilers.

In practice, libtabula works best on the platforms that get the most attention. This means mass-market operating systems on common hardware, and the default tool chain for the platform. There are FAQ items for most common platforms below; if your platform isn’t addressed and it’s outside the mainstream or is older than about 2003, the chance of it working out of the box are low. We’re happy to discuss porting on the forum, but be prepared to do most of the work yourself; if libtabula hasn’t been ported to your system already, there’s usually a pretty good reason why not.

If you use a different platform and it isn’t mentioned in the subsequent FAQ items, probably little is known about it. Feel free to discuss the port or provide patches to make libtabula build on the forum. We will support any platform that gets enough interest from the users.

What versions of MariaDB and MySQL does it work with?

libtabula should work with any release version of MariaDB.

libtabula works best with MySQL version 5.0 or higher, simply because this is the oldest version that it’s regularly tested against during development. It could be ported to older versions with some work.

We do most of the development against the current GA release of MariaDB, because that is the intended deployment platform. Sometimes we test on older versions. As a rule, we don't test against beta or alpha versions.

What software license does libtabula use? Is it free?

libtabula is free software, licensed under the GNU LGPL.

What does the LGPL license mean to me, as far as libtabula goes?

The common wisdom regarding LGPL’d libraries is that you can use them with a program using almost any software license as long as you’re willing to link dynamically. Think of the GNU C library (glibc) on Linux: it’s LGPL’d and linked to almost everything on a Linux system, at least indirectly. If your program’s software license allows dynamic linking to glibc, it should allow you to use libtabula dynamically, too.

If you link to libtabula statically, you trigger the “viral” provisions of the LGPL. Practically speaking, it means your program must be licensed under the LGPL or something compatible with it, such as the GPL. This rules out static linking when you want to keep your source code closed, and even rules out static linking with some open source licenses, since not all of them are compatible with LGPL at that level.

The licensing history of libtabula is tangled, what with the numerous changes of maintainership and the lack of a copyright assignment system for third-party contributions. That means the license will not be changing, ever. It would simply be impractical to contact all of the past contributors and get them to agree on the licensing changes needed to make this happen.

Doesn’t the MySQL C API library’s GPL license override the LGPL?

The MySQL C API library is available under two different licenses, not one.

The default license for MySQL (including its C API library) is GPL with the FOSS license exception. This is what you get if you got MySQL for free, such as by downloading it from mysql.com or as part of your Linux distro. The less liberal distribution terms of the C API library’s GPL do override the less restrictive ones of the libtabula license. This matters if you want to distribute your program as a binary only, keeping the source to yourself.

If you need to be able to distribute closed-source programs, Oracle will happily sell you a commercial distribution license for their C API library.

The situation is similar for MariaDB, except that they also offer the LGPL-licensed MariaDB Connector/C as an alternative to the GPL-licensed C API library derived from libmysqlclient.

Will it build under GCC?

It should build with GCC version 3.x and up, but the oldest GCC it's regularly tested with is 4.1.2.

It definitely will not build with GCC 2.x or older.

Will it build on Linux?

Yes; this is one of our primary development platforms. (The other being macOS.) See the README-Linux.txt file.

Will it build on the BSDs or other “real” Unices?

Yes. See the README-Unix.txt file.

The BSDs behave mostly the same as Linux for the purposes of building libtabula.

If you're building on Solaris, see the README-Solaris.txt file for some platform-specific details. We have reports of people building it successfully on versions as old as Solaris 8. It gets the most testing with GCC, but we have heard occasional success reports from people using Sun CC.

Will it build under Visual C++?

Yes. See the README-Visual-C++.txt file.

Unlike MySQL++, libtabula does not ship with Visual Studio project files. It uses the CMake build system instead, which means you'll be building at the command line. CMake uses the command line compilers that ship with Visual Studio, and it produces libraries you can then use in Visual Studio. It's just as well: our example programs need to be run at the command line anyway, so you'll need to be comfortable with that anyway, if you want to get the most out of libtabula.

Visual Studio Community is perfectly suitable for use in building libtabula and programs linked to it. Indeed, this is the only version this library's maintainer tests with regularly these days.

Will it build on macOS?

Yes. See the README-Mac-OS-X.txt file.

For the most part, it builds the same way as on Unix.

We've successfully built its predecessor MySQL++ on every major release of Mac OS X going back to 10.3, but libtabula proper hasn't been tested on anything older than 10.12 or so. If it no longer builds on those older OSes, we can discuss fixing the problem on the forum.

You can build libtabula on macOS against either the official MariaDB or MySQL Connector/C libraries or against the C API libraries from the Homebrew mariadb package.

Will it build under Cygwin?

Yes. See the README-Cygwin.txt file.

Will it build under MinGW?

Yes. See the README-MinGW.txt file.

Occasionally a version of MinGW comes out that breaks libtabula, but there has always been a usable workaround.

g++ simple1.cpp -o simple1?

No!

You’re probably missing a -I flag for the libtabula headers, and you’re certainly missing correct link flags.

The user manual has a section that describes how to build a program based on libtabula.

It compiles, but it won’t link! Why?

To build any program using libtabula, at minimum you must link to the libtabula library and also to the same C API library that libtabula was built against. Check its build system for details.

Visual C++: An additional requirement with Visual C++ is that you must link to the same C Run-Time Library (RTL) for all modules throughout your project. The CMake build system for libtabula uses the multithreaded DLL version (/MD or /MDd) of the C RTL. If you link libtabula to a program or additional third party library that uses a different RTL, you will get link errors. Study the example projects’ settings to see how this is done. The instructions in the README-Visual-C++.txt file may also be helpful.

See Chapter 9, Using libtabula in Your Own Project in the libtabula User Manual for more on this.

Why is my program leaking memory?

The current version of libtabula has no known memory leaks. If you free all of the libtabula objects you allocate, it should not be leaking memory.

If you’re getting a report from a memory debugger about a leak, most likely you’re seeing memory that the MySQL or MariaDB C API library allocates for its own internal purposes. libtabula is built atop this library, so it can look like it’s libtabula leaking the memory. This underlying C library automatically allocates multiple blocks of memory in ways that are more or less outside our control. If you feel you must plug these leaks, it is up to your code to call the relevant C API functions.

These “leaks” are all harmless in practice for most programs. A typical program using libtabula needs database access for its entire effective run time, and the size of the leak doesn’t increase over run time if you follow the instructions in the threads chapter of the User Manual. The OS automatically frees this memory when your program exits.

That said, it’s annoying to see leak reports in a memory debugger, particularly if leak checking is a regular part of your build and test process. You can placate the memory debugger by calling Connection::thread_end() from each thread that uses a database connection when that thread finishes using the database. In addition, after the last bit of code that uses libtabula stops, you need to call the MySQL C API function mysql_library_end(). If you’re using a ConnectionPool, you might put this last call in the destructor, since the pool object is typically the last libtabula object to be destroyed.

If you’ve done that and still think you really have a serious memory leak — one of those “the longer it runs, the more memory it uses” sorts of leak — you need to tie it to some unit of work. Does memory go up as a function of time? number of queries issued? count of rows retreived? Until you can establish this link, it’s premature to post to the forum or to file a bug report claiming there’s a leak in libtabula. Even if you can establish such a link, it’s far more likely that you’re not releasing the libtabula objects you allocate than libtabula itself failing to release memory.

My program is crashing. Help!

The most common cause of crashes in libtabula is uncaught exceptions. The library throws exceptions when it detects errors, such as invalid SQL syntax, invalid login parameters, etc. Try running the example programs, since they all catch exceptions properly.

If the examples also crash and you’re using a package built for a different Linux distribution than the one you’re actually running, try rebuilding the package from source on the target OS. A binary package is fairly closely tied to the system it is built under, so it’s possible that RPMs you build on your system will work better than those built elsewhere.

Nothing’s working at all! Is it broken?

Maybe, but have you tried running the examples? Follow the instructions in the README-examples.txt file. If the examples work but your program doesn’t, chances are good that the error is in your program; study the examples, and read the manuals. If the examples also fail to work, post to the forum with a detailed failure report.

I’m sure I’ve found a bug. How do I submit a report?

We’ll want some code that demonstrates the bug. No doubt you’d rather not send us a copy of your database to demonstrate the problem, and to be frank, we don’t want your database, either. The best thing is to modify one of the libtabula examples so that it reproduces the problem you’re seeing. This lets the people that can help you reproduce the problem on their machines, without needing your database.

Once you have your problem boiled down to a simple example, post its source code in the forum along with a detailed report. We want to know what you expect the program to do, and what it actually does on your machine. Keep in mind, programs often behave differently on different systems. As a programmer yourself, you know what it is like to deal with vague user bug reports. Give us the sort of error report you’d like to receive for your own programs.

There's also the ticket tracker, but we prefer that you post on the forum for discussion first. Especially do not use the ticket tracker if you just need help using libtabula.

How do I submit a change to libtabula?

This is covered in detail in the library's hacker's guide.

But in brief: we want the patch in unified diff format, made against either the latest release of libtabula or (preferably) against the trunk of the Fossil repository. You can post your patch to either the forum or the ticket tracker. We prefer that you only use the ticket tracker for patches that are so trivial or obvious that they won’t need discussion.

When a patch is rejected, the most common reason is that it breaks the library’s binary interface (ABI), so that an old program can’t link to the changed library without recompiling. We only make such changes at major version transitions. These transitions are rare, and we can’t even promise that there will ever be another one, much less when it will occur. If you have a choice of two ways to get your desired effect and one of them doesn’t break the ABI, it will increase the chances that we accept your patch if you do it that way.