libfossil  building

Building libfossil

See also: AmalgamationBuild

libfossil's canonical build system is currently aimed at platforms hosting GNU Make 3.81 or newer (most relatively recent platforms have 3.81, though some name it 'gmake' instead of 'make').

Prerequisites: libfossil requires that zlib, both the library and headers, be installed at the system level (where they normally are).

The first step is to configure the build tree, which generates some configuration and makefiles:

$ ./configure

Pass it the --help option for the list of options, but none are normally needed.

To change the compiler, pass CC=compiler-name to the configuration script. It is currently known to build cleanly with gcc, clang, and tcc on x64 and i386 Linux. Note that the makefiles tweak the compiler flags for those particular compilers, and may need similar tweaks for other compilers (see config.make.in). When using clang it might be useful to pass CC='clang -fno-color-diagnostics' to disable color output. Normally clang detects that automatically, but it mis-detects when compiling from xemacs and the color codes break xemacs' understanding of the output.

To build it:

$ make # or gmake

That will compile the library and a few sample/test/demo applications. Be careful with them - some modify the repository (but never without being told to).

Running Tests

The majority of the library's functionality is either covered by unit tests or tested indirectly via unit tests. The remaining functionality (which cannot be easily tested without modifying the repo) is tested via various apps.

The most fundamental of the sanity tests is the aptly-named f-sanity, which can be used like this:

$ cd f-apps
$ make # or gmake
$ ./f-sanity

If that runs to completion, without triggering an exception, the basic sanity test looks good. To be sure, though, it also should be run through valgrind:

$ valgrind --leak-check=full -v --show-reachable=yes --track-origins=yes ./f-sanity

If both of those run to completion without triggering an exception, leak, or memory usage violation, "the world is round." Note that if an assertion is triggered, valgrind will report many leaks as a side-effect, so first make sure it runs assertion-free without valgrind.

On Unix-like systems it should be possible to build the th1ish script bindings and run those unit tests:

$ cd th1ish
$ make # or gmake
$ make unit # runs the unit tests
$ make vg # runs the unit tests through valgrind,
          # complaining if it finds problems.
          # Also collects memory stats to a CSV file.

Again, if those don't complain then the world is (still) round. If you really want to stress-test the core cwal/th1ish engine, try running the vgs, vgr, vgt, and vgrst targets, all of which do the same as vg but disable different recycling options/optimizations in th1ish/cwal. The vgrst build disables almost every memory-related optimization there is, and will report much higher total allocations and memory costs for all but the most basic scripts. Each of those targets generates a separate CSV report which can then be perused and speculated upon at one's leisure ("'i' before 'e', except after 'c', and when sounding like 'a' in 'neighbor' and 'weigh'..." and leisure, apparently).

System vs. Local sqlite3

Because libfossil uses bleeding-edge features of sqlite3 (namely recursive queries), it includes its own copy of sqlite3 amalgamation. Once those features are widely out and about in the wild, we can revert the build process to use a system-level sqlite3. As of 20140201, it requires sqlite3 3.8.3+.