Table of Contents
An Abuild.mk file must appear in every
directory in which something is to be built using the
GNU Make backend. In this chapter, we
describe how to use it in general and provide details specific to
the rule sets provided by abuild.
The Abuild.mk file is read by GNU Make and is
a GNU Make fragment. It therefore has GNU Make syntax. The
Abuild.mk file is intended to contain only
variable settings. It contains no make rules or include
directives. Abuild automatically includes your
Abuild.mk file at the appropriate time and in
the appropriate context.
The most important line in Abuild.mk is the
setting of the RULES variable. Its purpose is
to tell abuild which rule set should be used to generate
targets from sources. Most of the remaining variables that are
set are dependent upon which rules are being used. It is always
possible to run abuild rules-help to get
detailed rule-specific help about what variables you are expected
to define in your Abuild.mk for a specific
set of rules.
Sometimes, other build items may provide additional rules to
support code generators and similar functionality. To specify
that you wish to use rules provided by another build item,
include the name of the build item in the
BUILD_ITEM_RULES variable. This causes that
build item's Rules.mk to be loaded. You
must also list that build item as a dependency in your
Abuild.conf file, and you must be allowed to
see the item subject to scoping rules (see Section 6.3, “Build Item Name Scoping”).
In rare instances, it may be necessary to create local rules for
a specific build item. Examples may include one-off,
special-purpose code generators that are specific to a particular
build item. To use local rules, place a list of files that
contain definitions of your rules in the
LOCAL_RULES variable. Files listed there are
resolved relative to the Abuild.mk. They
may contain any valid GNU Make code.
If you have written the same local rule in more than one or two
places, you are probably doing something wrong and should be
using build item-specific rules or plugins (Chapter 26, Enhancing Abuild with Plugins) instead.
Please note that local rules are run from the context of the
output directory—you must keep this in mind when using
relative paths from your local rules. The make variable
SRCDIR is always set to a relative path to the
directory that contains the Abuild.mk file.
Also, local rules should avoid creating files outside of the
output directory since these files will not be removed by the
clean target.
[25]
[25] Defining your own clean target can be useful, but keep in mind that it is only run if you manually run abuild from inside the output directory, which most people would never do except when debugging abuild. For details about running abuild from an output directory, see Section 29.2, “Starting Abuild in an Output Directory”.