Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

A simple, easily embeddable cross-platform C library

Make buffer appending more efficient

We make cork_buffer_append_vprintf more efficient by not relying on
vsnprintf to determine the size of the format string.  Instead, we
call vsnprintf directly on the current buffer.  If it fails, we add
more space to the buffer and repeat.  The second call is guaranteed
to succeed since the call to cork_buffer_ensure_size_int guarantees
the requested space will be available upon return.
latest commit 0e98a5dea2
John Zachary johnzachary authored February 12, 2014
Octocat-spinner-32 .buzzy Build check if necessary July 24, 2013
Octocat-spinner-32 docs Additional doubly-linked list functions January 22, 2014
Octocat-spinner-32 extras Rename license file to COPYING September 10, 2012
Octocat-spinner-32 include Additional doubly-linked list functions January 22, 2014
Octocat-spinner-32 share Prefixing error messages October 22, 2013
Octocat-spinner-32 src Make buffer appending more efficient February 12, 2014
Octocat-spinner-32 tests Additional doubly-linked list functions January 22, 2014
Octocat-spinner-32 .gitignore Merge remote-tracking branch 'templates/c-template' into develop January 25, 2012
Octocat-spinner-32 CMakeLists.txt Merge remote-tracking branch 'template/c-template' into develop July 24, 2013
Octocat-spinner-32 COPYING Rename license file to COPYING September 10, 2012
Octocat-spinner-32 INSTALL Updating C template with libcork details March 04, 2011
Octocat-spinner-32 README.markdown Adding Sphinx documentation for config and core December 02, 2011
Octocat-spinner-32 make-dist.sh Port libcork to FreeBSD March 07, 2013
Octocat-spinner-32 run.sh Support for FreeBSD March 07, 2013
Octocat-spinner-32 version.sh Port libcork to FreeBSD March 07, 2013
README.markdown

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.

Something went wrong with that request. Please try again.