whio  Artifact Content

Artifact f58cbde63bd336357b57d98071cd718aef56f119:

Wiki page [AmalgamationBuild] by stephan 2011-05-23 18:50:52.
D 2011-05-23T18:50:52.601
L AmalgamationBuild
P 3ae1ddbbc14335d45d711817a933f42316e56c3d
U stephan
W 2903
<strong>ACHTUNG: AS OF 20110523, THIS PAGE IS NOW MAINTAINED IN THE NEW WIKI:</strong> [http://whiki.wanderinghorse.net/wikis/whio/?page=AmalgamationBuild]

<h1>Amalgamation Build</h1>

The build process supports compounding all of the whio <tt>.c</tt> files and <tt>.h</tt> files into a bundle containing only a single <tt>.c</tt> and <tt>.h</tt>.

The primary intention is to simplify inclusion of whio into arbitrary source trees (i use it in several other trees).

The secondary intention is performance. The developers of the [http://sqlite.org|sqlite project] have determined that such an amalgamation can improve performance of the code by a few ticks (i think they were averaging 5% or so) because compilers can (reportedly) typically perform more optimizations if all code is in the same compilation unit.

To create the amalgamation build do one of the following from the top source directory:

~> make amal
# or:
~> ./createAmalgamation.sh

The output will be two files, <tt>whio_amalgamation.{c,h}</tt>, which can be compiled into library form or included directly in a client application. The amalgamation contains the whole whio API, including [whio_dev], [whio_stream], and [whio_epfs]. It does not contain the [whio_epfs_tools], as those are standalone applications with their own <tt>main()</tt> routines.

The files are quite large, but a large percentage of the header file is documentation (about 85%, last time i checked). The C file contains only a small amount of comments/documentation (about 10% last i checked).

Compiling the amalgamation is quite fast.

Using the code from 20101204 on a dual-core 3.2 GHz 64-bit Ubuntu Linux system:

~> ls -la whio_amalgamation.?
-rw-r--r-- 1 stephan stephan 628748 Dec  4 12:32 whio_amalgamation.c
-rw-r--r-- 1 stephan stephan 556567 Dec  4 12:32 whio_amalgamation.h

~> time gcc -c -std=c99 -pedantic -Wall whio_amalgamation.c 

real	0m2.450s
user	0m2.110s
sys	0m0.210s

# tcc is _much_ faster:
~> time tcc -c whio_amalgamation.c 

real	0m0.068s
user	0m0.050s
sys	0m0.010s

As of 20101215, we have a small handful of scripts for generating "partial amalgamations." That is, amalgamations which include:

   *  Only the core bits: base [whio_dev] and [whio_stream] APIs and basic stream/device implementations.
   *  The "utility" bits, which include [whio_udb], [whio_ht], [whio_vlbm], the zlib extensions, and data encoding/decoding routines (<tt>whio_encode.h</tt>).
   *  The [whio_epfs] bits.

This cuts down on the amount of code one has to include when dropping the amalgamation build into other client trees (something i do surprisingly often).

The <tt>createAmalgamation.sh</tt> is now a wrapper around the various "mini-amalgamation" scripts, and generates the individual amalgamations and the conventional "mega-amalgamation."

Z 54ffb5ea368699fde9b3361edc78515d