ack/first/ackbuilder.md

ackbuilder

ackbuilder

What is it?

ackbuilder is a very small build tool inspired by bazel which uses either make or ninja as a backend.

It supports fully parallelisable builds (in both make and ninja), as well as hopefully-robust support for rules which generate more than one output file, which is something make is very, very bad at.

It was written because the ACK is a really horribly complex thing to build and there wasn't anything else.

Basic concepts

Complete example, using the built-in C rules. This should be saved in a file called build.lua:

cprogram {
  name = 'prog',
  srcs = { "./*.c" },
}

This defines a rule prog which, when built, compiles all the source files in the same directory as the build.lua file into an executable.

Slightly more complex example:

clibrary {
  name = "library",
  srcs = { "./library.c" },
  hdrs = { "./library.h" },
}

cprogram {
  name = 'prog2',
  srcs = { "./prog2.c" },
  deps = { "+library" }
}

If we move the library into another directory, we can invoke it like this:

cprogram {
  name = 'prog3',
  srcs = { "./prog3.c" },
  deps = { "path/to/library+library" }
}

• Targets starting with ./ are relative to the current directory (i.e. the one the build file is in).

• Targets starting with a path are relative to the top directory of the project.

• Targets containing a + refer to a named target in another build file. So, on encountering the library in prog3 above, ackbuilder will look for path/to/library/build.lua, load it, and then try to find a target in it called library.

Warning: files are interpreted from top to bottom; every time a target referring to another build file is seen for the first time, that file is interpreted then and there. You can't have circular dependencies (these are caught and an error is generated). You can't refer to a target defined below you in the same source file (these are not caught, and just won't be found).

The cprogram and clibrary rules, by the way, are sophisticated enough to automatically handle library and header paths. The exported headers by the library are automatically imported into the program.

simplerule and normalrule

These are the building blocks out of which all other rules are made. If you want to run your own programs, you will be using these.

simplerule is the simplest. You give it inputs, and outputs, and commands, and it does it.

simplerule {
  name = 'sorted-input',
  ins = { './input.txt' },
  outs = { './output.txt' },
  commands = {
  	"sort < %{ins} > %{outs}"
  }
}

In a command block, %{...} will evaluate the Lua expression between the braces; various useful things are in scope, including the list of inputs and outputs.

However, this ends up leaving the output file lying around in the project directory, which we don't want, so we usually use normalrule instead. (normalrule is not strictly part of the ackbuilder core; it's in the standard library along with cprogram and clibrary.)

normalrule {
  name = 'sorted-input',
  ins = { './input.txt' },
  outleaves = { 'output.txt' },
  commands = {
    "sort < %{ins} > %{outs}"
  }
}

Note outleaves; there is no ./. This is a list of leaf filenames. The rule will create a directory in the object tree and put the files specified in it, somewhere; you don't care where. You can refer to the output file via the target name, so:

normalrule {
  name = 'reversed',
  ins = { '+sorted-input' },
  outleaves = { 'reversed.txt' },
  commands = {
    "rev < %{ins} > %{outs}"
  }
}

One common use for this is to generate C header or source files.

normalrule {
  name = 'reversed_h',
  ins = { '+reversed' },
  outleaves = { 'reversed.h' },
  commands = {
    'xxd -i %{ins} > %{outs}'
  }
}

cprogram {
  name = 'prog',
  srcs = { './*.c' },
  deps = { '+reversed_h' }
}

Now you can refer to reversed.h in one of your C files and it'll just work (+reversed_h's output directory gets added to the include path automatically).

Defining your own rules

Like this:

definerule("sort", { srcs = { type="targets" }, }, function(e) return normalrule { name = e.name, ins = e.srcs, outleaves = { 'sorted.txt' }, commands = { "sort < %{ins} > %{outs}" } } } )

sort { name = 'sorted', srcs = { './input.txt' } }

You give definerule() the name of the rule you want to define, a description of the properties the rule will take, and a callback that does the work.

You can do anything you like in the callback, including defining as many targets as you like; but remember that all targets must have unique names, so for any temporary files you probably want something like name = e.name.."/intermediate" to ensure uniqueness.

The callback should end by returning an invocation of another rule, with name = e.name as above.

Rules are defined whenever a build file containing them is seen. Letting this happen automatically doesn't always work so you probably want to explicitly include it:

include("foo/bar/baz/build.lua")

Rule properties are typed and can be specified to be required or optional (or have a default value).

definerule("sort",
  {
     srcs = { type="targets" },
	 numeric = { type="boolean", default=false }
  }
  ...omitted...

The most common one is targets. When the rule is invoked, ackbuilder will resolve these for you so that when your callback fires, the property is a flattened list of target objects.