This section presents the basics required for building a simple projects. The guide assumes you are already familiar with Makefiles or similar tools.
Rules, like their counterpart in `make`, consist of three parts: the targets (what is created), the dependencies (what is needed to create the targets), and a recipe that creates targets from dependencies using a list of commands. Rules take the form of
target1 target2 ... : depend1 depend2 ... {
cmd1 ;
cmd2 ;
...
}
Those familiar with `make` will notice two main differences. First, recipes are wrapped with braces (`{` and `}`) rather than denoted by indentation. Second, each command is seperated by a semicolon rather than a newline. These differences allow both commands and rules to take more than a single line.
Comments are denoted with a hash (`#`).
# this is a comment
foo = "abc"; # this is also a comment
All values are strings by default. Plain strings are those without quotes and may contain alphabetical characters (`[a-zA-Z]`), numbers (`[0-9]`), underscores (`_`), dashes (`-`), periods (`.`), plus signs (`+`), slashes (`/`), and tildes (`~`). Dollar signs are used for variable expansion. Any other strings must be quoted.
There are two types of quotes: single quotes (`'`) and double quotes (`"`). They can contain any characters except a null byte. Double quoted strings will expand variables prefixed with `$`. Single quoted strings will not expand variables.
The backslash (`\`) is used to escape a special character, and they may be used in plain or quoted strings.
The sequences `\n` and `\r` are a newline and carriage return, respectively.
The sequences `\'` and `\"` are a single quote and double-quote, respectively. These are used to add quotes within a quoted string.
The sequence `\ ` creates a literal space. This is not needed in quoted strings but is useful for plain strings to include a space.
The sequence `\$` creates a literal dollar sign. For plain strings an single quoted strings, this sequence inserts a dollar sign without expanding a variable.
All strings (and environments) may be used inside a list. For example, the value `foo bar baz` is different from `foo "bar baz". Given to the `touch` command, the first creates three files (`foo`, `bar`, and `baz`) and the second creates two files (`foo` and `bar baz`).
Variables are crated using an assignement `foo = "some value";`. The variable name can only consist of alphabetical characters (`[a-zA-Z]`), numbers (`[0-9]`), and underscore (`_`). Once created, the values may be used in strings by prefixing a dollar sign (e.g. `$foo`).
Variable names may be wrapped in curly braces to delimit the end of the variable names (`${foo}`), call a method (`${foo.trim()`), or access a namespace (`${ns.foo}`).
Environments are objects that contain evaluated variable assignments. This can be used as a key-value store, or, more commonly, an environment carries around the configuration values required for building. Environment are created using the "env" keyword followed by a block surrounded by brackets (`{` and `}`).
conf = env {
debug = 1;
path = "build/debug";
}
print "path=${conf.path}\n";
Rules inside an environment are evaluated immediately. If you want rules to be processed when invoked, you probably want to a function instead.
The `$@` variable is a list of all targets for the current rule. This variable may only be used within a recipe.
The `$^` variable is a list of all dependencies for the current rule. This variable may only be used within a recipe.
The `$<` variable is the first dependency for the current rule. This variable may only be used within a recipe.
The `$*` variable is a list of all targets created until the variable is evaluated. This variable is useful for generating a `.clean` rule for deleting all target files that placed at the end of the `Hammer` file.