(Note: see also ticket:130.)

There isn't any formal documentation of what goes into a bkgen file, but there is now a schema in lib/schemas/bakefile_gen.xsd. That's helpful if you know the  XML Schema Language, but not much if you don't. Beginning with 0.2.3, bakefile_gen "validates" bkgen files against the schema, so if your file doesn't comply, you'll get a warning or an error:

No namespace:

warning: missing namespace declaration, should be "http://www.bakefile.org/schema/bakefile-gen"

Wrong namespace:

error: document has wrong namespace "http://www.bakefile.org/schema/bakefile", should be
"http://www.bakefile.org/schema/bakefile-gen"

If the bkgen file doesn't validate you should get a backtrace.

So, let's jump in and start the file:

<?xml version="1.0" encoding="utf-8"?>
<bakefile-gen xmlns="http://www.bakefile.org/schema/bakefile-gen">

Notice that xmlns="http://www.bakefile.org/schema/bakefile-gen" bit. That's what sets the namespace.

The bakefile_gen element is the main element of the document, so there has to be exactly one of them. It takes no attributes, but has several types of sub-element, all of which can occur as many times as you need.

<include file='another.bkgen' ignore-missing='1' />

Recursively loads (and validates) the file indicated in the 'file' attribute. It will throw and exception unless the 'ignore-missing' attribute is included and has a value other than 0. Regardless of location in the file, these are processed before anything else, so all of the included files make a single dataspace -- no scoping! Elements are added to the global list in the order in which they're encountered.

<input>inputfile1.bkl inputfile2.bkl</input>

Provides a space-separated list of bakefiles for bakefile_gen to process. Since it's optional in the schema, it won't fail validation, but bakefile_gen won't do anything, either, except report that "0 files modified". Since the files are space-separated, they can't contain whitespace. "/" will be converted to whatever is the appropriate file separator. Multiple input elements will add to the list. Glob characters for the operating system will be honored.

All of the input elements in all of the loaded files are processed before beginning to parse the other element types, but the order of the elements is maintained.

To tell the bakefile(s) what formats may be built, we can create two lists:

<enable-formats>format1,format_2</enable-formats>
<disable-formats>format_2,format-3,format4</disable-formats>

Disable-formats prevents a later add-formats element from adding that format. Enable-formats removes formats from the disabled-formats list, so only has an effect if the format was previously disabled. The formats should be ones which bakefile recognizes, but bakefile doesn't really see what's in these lists. Note that there should be no whitespace in the list. All of the disables and enables are processed in the order encountered in all of the recursively-added files before doing anything else.

If you have in your main bkgen file

<disable-formats>format1,format2,format3</disable-formats>
<include file='another.bkgen'>
<enable-formats>format2,format4</enable-formats>

and another.bkgen disables format4, then it will be re-enabled; but if the <include> comes after the <enable-formats>, then format4 will wind up disabled.

<add-formats files='inputfile1.bkl'>format1,format-3</add-formats>
<del-formats files='inputfile1.bkl'>format_2,format-3</del-formats>

These actually add and remove formats to process for the specified files. The attribute is optional, and if it isn't included the adds and deletes will be applied to all files in <input>. These only affect the formats not in the disable list, so in example above only format1 would be added. As before, formats are in a comma-delimited list with no whitespace, files likewise. As with disable and enable formats, all of these elements are processed together in the order encountered as files were recursively loaded.

<add-flags files='inputfile1.bkl' formats='format1'>-o path/to/file</add-flags>
<del-flags files='inputfile1.bkl' formats='format1'>-o path/to/file</del-flags>

To control bakefile behavior on a file and format basis. The attributes are optional, and if you leave them off the add or delete will be applied to all. The content is an option string that is put on the bakefile command line for each run. This is the last group processed, and as always they're handled in the order encountered in the final tree.