Examples_compile

ccanlint's examples_compile test extracts Example: sections and compiles them. If it fails, it shows the various versions it attempted before giving up, annotated with comments about its decisions.

It has a series of heuristics it uses, which are being slowly refined. Currently it is as follows:

1. It tries to compile the example as-is.
2. It tries to combine it with the previous example, then mangle it.
3. It tries to mangle it as it is.

It prefers a solution which gives no warnings.

The combine step involves:

• If the current example doesn't seem to belong inside a function, and the previous example has a line with just '...' (and maybe spaces), insert the current example at that point.

• Otherwise, append the current example to the previous one (which may have been combined with the one before, etc).

The mangling step looks something like this:

• Prepend a series of standard headers, including the main header of the current module.
• Creating a dummy function int somefunc(void) { return 0; }
• Creating a dummy string char somestring[] = "hello world";
• If we see "..." outside a function and the following lines seem to belong inside a function, we start 'int main(int argc, char *argv[]) {".
• Commenting out '...' lines.
• Inserting a final main() function if we didn't find or make one.
• Taking the addresses of any static functions we encounter, to suppress unused warnings.

The first of these which causes no errors or warnings wins. Otherwise, the first which causes no errors wins.

You can usually juggle your examples to be minimal, and still compile.

Note that the examples are compiled and linked against the module and any dependencies, but not run unless you turn it into a test as well, by adding a comment on what it should do, see examples_run.