shadowsocks-libev/libcork

libcork

So what is libcork, exactly? It's a “simple, easily embeddable, cross-platform C library”. It falls roughly into the same category as glib or APR in the C world; the STL, POCO, or QtCore in the C++ world; or the standard libraries of any decent dynamic language.

So if libcork has all of these comparables, why a new library? Well, none of the C++ options are really applicable here. And none of the C options work, because one of the main goals is to have the library be highly modular, and useful in resource-constrained systems. Once we describe some of the design decisions that we've made in libcork, you'll hopefully see how this fits into an interesting niche of its own.

Using libcork

There are two primary ways to use libcork in your own software project: as a shared library, or embedded.

When you use libcork as a shared library, you install it just like you would any other C library. We happen to use CMake as our build system, so you follow the usual CMake recipe to install the library. (See the INSTALL file for details.) All of the libcork code is contained within a single shared library (called libcork.so, libcork.dylib, or cork.dll, depending on the system). We also install a pkg-config file that makes it easy to add the appropriate compiler flags in your own build scripts. So, you use pkg-config to find libcork's include and library files, link with libcork, and you're good to go.

The alternative is to embed libcork into your own software project's directory structure. In this case, your build scripts compile the libcork source along with the rest of your code. This has some advantages for resource-constrained systems, since (assuming your compiler and linker are any good), you only include the libcork routines that you actually use. And if your toolchain supports link-time optimization, the libcork routines can be optimized into the rest of your code.

Which should you use? That's really up to you. Linking against the shared library adds a runtime dependency, but gives you the usual benefits of shared libraries: the library in memory is shared across each program that uses it; you can install a single bug-fix update and all libcork programs automatically take advantage of the new release; etc. The embedding option is great if you really need to make your library as small as possible, or if you don't want to add that runtime dependency.

Design decisions

Note that having libcork be easily embeddable has some ramifications on the library's design. In particular, we don't want to make any assumptions about which build system you're embedding libcork into. We happen to use CMake, but you might be using autotools, waf, scons, or any number of others. Most cross-platform libraries follow the autotools model of performing some checks at compile time (maybe during a separate “configure” phase, maybe not) to choose the right API implementation for the current platform. Since we can't assume a build system, we have to take a different approach, and do as many checks as we can using the C preprocessor. Any check that we can't make in the preprocessor has to be driven by a C preprocessor macro definition, which you (the libcork user) are responsible for checking for and defining. So we need to have as few of those as possible.