d0p1/ack
1
0
Fork 0
Code Issues Pull requests Packages Projects Releases Wiki Activity

Add modeline, fix formatting.

Browse source
This commit is contained in:
David Given 2016-09-03 19:17:09 +02:00
parent 95ad06849b
commit 1b8df04e58
1 changed files with 88 additions and 86 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

174
first/ackbuilder.md
View file

@ -52,16 +52,16 @@ If we move the library into another directory, we can invoke it like this:
deps = { "path/to/library+library" } deps = { "path/to/library+library" }
} }
* Targets starting with `./` are relative to **the current directory** (i.e. * Targets starting with `./` are relative to **the current directory** (i.e.
the one the build file is in). the one the build file is in).
* Targets starting with a path are relative to the top directory of the * Targets starting with a path are relative to the top directory of the
project. project.
* Targets containing a `+` refer to a named target in another build file. So, * Targets containing a `+` refer to a named target in another build file. So,
on encountering the library in `prog3` above, ackbuilder will look for 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 `path/to/library/build.lua`, load it, and then try to find a target in it
called `library`. called `library`.
**Warning**: files are interpreted from top to bottom; every time a target **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 referring to another build file is seen for the first time, that file is
@ -86,13 +86,13 @@ want to run your own programs, you will be using these.
and it does it. and it does it.
simplerule { simplerule {
name = 'sorted-input', name = 'sorted-input',
ins = { './input.txt' }, ins = { './input.txt' },
outs = { './output.txt' }, outs = { './output.txt' },
commands = { commands = {
"sort < %{ins} > %{outs}" "sort < %{ins} > %{outs}"
} }
} }
In a command block, `%{...}` will evaluate the Lua expression between the In a command block, `%{...}` will evaluate the Lua expression between the
braces; various useful things are in scope, including the list of inputs and braces; various useful things are in scope, including the list of inputs and
@ -104,13 +104,13 @@ directory, which we don't want, so we usually use `normalrule` instead.
library along with `cprogram` and `clibrary`.) library along with `cprogram` and `clibrary`.)
normalrule { normalrule {
name = 'sorted-input', name = 'sorted-input',
ins = { './input.txt' }, ins = { './input.txt' },
outleaves = { 'output.txt' }, outleaves = { 'output.txt' },
commands = { commands = {
"sort < %{ins} > %{outs}" "sort < %{ins} > %{outs}"
} }
} }
Note `outleaves`; there is no `./`. This is a list of leaf filenames. The rule 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, will create a directory in the object tree and put the files specified in it,
@ -118,30 +118,30 @@ somewhere; you don't care where. You can refer to the output file via the
target name, so: target name, so:
normalrule { normalrule {
name = 'reversed', name = 'reversed',
ins = { '+sorted-input' }, ins = { '+sorted-input' },
outleaves = { 'reversed.txt' }, outleaves = { 'reversed.txt' },
commands = { commands = {
"rev < %{ins} > %{outs}" "rev < %{ins} > %{outs}"
} }
} }
One common use for this is to generate C header or source files. One common use for this is to generate C header or source files.
normalrule { normalrule {
name = 'reversed_h', name = 'reversed_h',
ins = { '+reversed' }, ins = { '+reversed' },
outleaves = { 'reversed.h' }, outleaves = { 'reversed.h' },
commands = { commands = {
'xxd -i %{ins} > %{outs}' 'xxd -i %{ins} > %{outs}'
} }
} }
cprogram { cprogram {
name = 'prog', name = 'prog',
srcs = { './*.c' }, srcs = { './*.c' },
deps = { '+reversed_h' } deps = { '+reversed_h' }
} }
Now you can refer to `reversed.h` in one of your C files and it'll just work 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 (`+reversed_h`'s output directory gets added to the include path
@ -151,26 +151,26 @@ automatically).
Like this: Like this:
definerule("sort", definerule("sort",
{ {
srcs = { type="targets" }, srcs = { type="targets" },
}, },
function(e) function(e)
return normalrule { return normalrule {
name = e.name, name = e.name,
ins = e.srcs, ins = e.srcs,
outleaves = { 'sorted.txt' }, outleaves = { 'sorted.txt' },
commands = { commands = {
"sort < %{ins} > %{outs}" "sort < %{ins} > %{outs}"
} }
}
} }
} )
)
sort { sort {
name = 'sorted', name = 'sorted',
srcs = { './input.txt' } srcs = { './input.txt' }
} }
You give `definerule()` the name of the rule you want to define, a description 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. of the properties the rule will take, and a callback that does the work.
@ -194,11 +194,11 @@ have a default value). If you try to invoke a rule with a property which isn't
declared, or missing a property which should be declared, you'll get an error. declared, or missing a property which should be declared, you'll get an error.
definerule("sort", definerule("sort",
{ {
srcs = { type="targets" }, srcs = { type="targets" },
numeric = { type="boolean", optional=true, default=false } numeric = { type="boolean", optional=true, default=false }
} }
...omitted... ...omitted...
(The `optional=true` part can be omitted if you specify a default which isn't (The `optional=true` part can be omitted if you specify a default which isn't
`nil`.) `nil`.)
@ -206,8 +206,8 @@ declared, or missing a property which should be declared, you'll get an error.
Types include: Types include:
* `targets`: the most common one. When the rule is invoked, ackbuilder will * `targets`: the most common one. When the rule is invoked, ackbuilder will
resolve these for you so that when your callback fires, the property is a resolve these for you so that when your callback fires, the property is a
flattened list of target objects. flattened list of target objects.
* `strings`: a Lua table of strings. If the invoker supplies a single string * `strings`: a Lua table of strings. If the invoker supplies a single string
which isn't a table, it'll get wrapped in one. which isn't a table, it'll get wrapped in one.
@ -226,8 +226,8 @@ When a rule callback is run, any targets it needs will be resolved into target
objects. These are Lua objects with assorted useful stuff in them. objects. These are Lua objects with assorted useful stuff in them.
* `object.is`: contains a set telling you which rules made the object. e.g. * `object.is`: contains a set telling you which rules made the object. e.g.
`object.is.cprogram` is true if `object` was built with `cprogram`. Bear in `object.is.cprogram` is true if `object` was built with `cprogram`. Bear in
mind that `object.is.normalrule` is _also_ going to be true. mind that `object.is.normalrule` is _also_ going to be true.
* `object.dir`: the object's build directory. Only exists if the object was * `object.dir`: the object's build directory. Only exists if the object was
built with `normalrule`. built with `normalrule`.
@ -250,16 +250,16 @@ e.g. `targetsof(a, b)` is equivalent to `targetsof({a, b})` is equivalent to
`targetsof({a, {b}})`. `targetsof({a, {b}})`.
* `targetsof(...)`: just flattens the list and resolves any string target * `targetsof(...)`: just flattens the list and resolves any string target
names. names.
* `filenamesof(...)`: returns a list of output files for all the supplied * `filenamesof(...)`: returns a list of output files for all the supplied
targets. targets.
* `targetnamesof(...)`: returns a list of fully qualified target names for * `targetnamesof(...)`: returns a list of fully qualified target names for
all the supplied stargets. all the supplied stargets.
* `selectof(targets, pattern)`: returns only those targets whose outputs * `selectof(targets, pattern)`: returns only those targets whose outputs
contain at least one file matching the pattern. contain at least one file matching the pattern.
### Manipulating filename lists ### Manipulating filename lists
@ -271,18 +271,18 @@ string, they return just a string.
e.g. `abspath({f})` returns a table; `abspath(f)` returns a string. e.g. `abspath({f})` returns a table; `abspath(f)` returns a string.
* `abspath(...)`: attempts to return the absolute path of its arguments. This * `abspath(...)`: attempts to return the absolute path of its arguments. This
isn't always possible due to variable references. isn't always possible due to variable references.
* `basename(...)`: returns the basenames of its arguments (the file part of * `basename(...)`: returns the basenames of its arguments (the file part of
the path). the path).
* `dirname(...)`: returns the directory name of its arguments. * `dirname(...)`: returns the directory name of its arguments.
* `matching(files, pattern)`: returns only those files which match a Lua * `matching(files, pattern)`: returns only those files which match a Lua
pattern. pattern.
* `replace(files, pattern, repl)`: performs a Lua pattern replace on the list * `replace(files, pattern, repl)`: performs a Lua pattern replace on the list
of files. of files.
* `uniquify(...)`: removes duplicates. * `uniquify(...)`: removes duplicates.
@ -319,12 +319,12 @@ build file).
Easiest to explain with an example: Easiest to explain with an example:
cprogram { cprogram {
name = 'another_test', name = 'another_test',
srcs = { './*.c' }, srcs = { './*.c' },
vars = { vars = {
cflags = { '-g', '-O3' } cflags = { '-g', '-O3' }
} }
} }
When `cprogram` builds each C file, the command will refer to `%{cflags}`. The When `cprogram` builds each C file, the command will refer to `%{cflags}`. The
value above will be flattened into a space-separated string and substituted in. value above will be flattened into a space-separated string and substituted in.
@ -334,16 +334,18 @@ stack. However, you can do this:
vars.cflags = { '-g' } vars.cflags = { '-g' }
cprogram { cprogram {
name = 'another_test', name = 'another_test',
srcs = { './*.c' }, srcs = { './*.c' },
vars = { vars = {
["+cflags"] = { '-O3' } ["+cflags"] = { '-O3' }
} }
} }
Now `cflags` will default to `-g` everywhere, because it's set at the top Now `cflags` will default to `-g` everywhere, because it's set at the top
level; but when `another_test` is built, it'll be `-g -O3`. level; but when `another_test` is built, it'll be `-g -O3`.
ackbuilder variables are only expanded in command templates, not in filenames. ackbuilder variables are only expanded in command templates, not in filenames.
<!-- # vim: set ts=2 sw=2 expandtab : -->