First half of the ackbuilder documentation.

first/ackbuilder.md

@@ -0,0 +1,199 @@
+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.
+
+