ack/first/ackbuilder.md

ackbuilder
==========

# ackbuilder

## What is it?

ackbuilder is a very small build tool inspired by [bazel](https://bazel.io/)
which uses either make or [ninja](https://ninja-build.org/) 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.