01 Basics - HammerBS QuickStart Guide

This section presents the basics required for building a simple projects. The guide assumes you are already familiar with Makefiles or similar tools.

Rules

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

Comments are denoted with a hash (`#`).

# this is a comment
foo = "abc"; # this is also a comment

Strings & Quoting

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.

`\n`, `\r` Newline and carriage return

The sequences `\n` and `\r` are a newline and carriage return, respectively.

`\'`, `\"` Single quote and double quote

The sequences `\'` and `\"` are a single quote and double-quote, respectively. These are used to add quotes within a quoted string.

`\ ` Space

The sequence `\ ` creates a literal space. This is not needed in quoted strings but is useful for plain strings to include a space.

`\$` Dollar sign

The sequence `\$` creates a literal dollar sign. For plain strings an single quoted strings, this sequence inserts a dollar sign without expanding a variable.

Lists

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

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

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.

Methods

Special Variables

`$@` All targets

The `$@` variable is a list of all targets for the current rule. This variable may only be used within a recipe.

`$^` All dependencies

The `$^` variable is a list of all dependencies for the current rule. This variable may only be used within a recipe.

`$<` First dependency

The `$<` variable is the first dependency for the current rule. This variable may only be used within a recipe.

`$*` All global targets

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.