Chapter 5. Commands Reference

Table of Contents

Makefile Commands
set
unset
option
template
using
include
if
fragment
requires
error
Commands for Extending Bakefile
define-rule
define-tag
add-target
modify-target
output

Commands are top-level makefile constructs. They have following form:

<COMMAND [PROPERTY="VALUE", ...]>
    CONTENT
</COMMAND>

Here, CONTENT is either a text value (as in e.g. set) or XML subtree.

Makefile Commands

set

Sets a variable. There are two forms of the command. The first one if for setting variables unconditionally:

<set var="NAME" [append="APP"] [prepend="PREP"] [overwrite="OVERWRITE"]
     [scope="SCOPE"] [make_var="MAKEVAR"] [hints="HINTS"]>
  VALUE
</set>
  

The other one resembles switch statement known from C and is used to set the variable to one of possible values depending on certain condition:

<set var="NAME" [append="APP"] [prepend="PREP"] [overwrite="OVERWRITE"]
     [scope="SCOPE"] [make_var="MAKEVAR"] [hints="HINTS"]>
  <if cond="COND">VALUE</if>
  [
  <if cond="COND">VALUE</if>
  ...
  ]
</set>
  

If the second from is used then the variable is set to value from the first if node whose condition is met, or to empty string if no condition is met. Note that conditions within one set command must be mutually exclusive.

The value is any text that may contain variable expansions.

If an option with same name exists, the variable takes precedence and the option is shadowed by it. This behaviour allows you to hardcode values for some ruleset's options in the makefile or to specify the value on command line when running Bakefile.

Parameters:

var

Name of the variable to assign the value.

Required parameter

append

If 1, the value is appended to previous value of the variable if it is already defined (otherwise the command behaves as if append=0). Following two set commands are equivalent:

<set var="FOO" append="1">something</set>
<set var="FOO">$(FOO) something</set>

Default value: 0

prepend

If 1, the value is prepended in front of previous value of the variable if it is already defined (otherwise the command behaves as if prepend=0). Following two set commands are equivalent:

<set var="FOO" prepend="1">something</set>
<set var="FOO">something $(FOO)</set>

Default value: 0

cond

If present, the variable is set only if the condition is met. If the condition evaluates to 0, the variable is not set, if it evaluates to 1, the variable is set. If condition's value can't be determined at the time of makefile processing, a conditional variable is created instead of ordinary variable. See the section called “Conditions” for more details.

<set var="FILES">
  <if cond="BUILD=='debug'">foo_dbg.c</if>
  <if cond="BUILD=='release'">foo.c</if>
</set>

The condition can also value special value target, which can only be used within target specification. In that case parent target's condition is used (or 1 if there's no condition set on the target). The condition can also be "target andcondexpr" in which case target's condition (if any) is combined with condexpr.

The string with condition may itself be a constant expression, so you can write this:

<set var="IsRelease">=='release'</set>
<set var="CondDebug">BUILD=='debug'</set>
<set var="FILES">
  <if cond="BUILD$(IsRelease)">foo_dbg.c</if>
  <if cond="$(CondDebug)">foo.c</if>
</set>

overwrite

If set to 0 and variable with this name already exists, then it's value is not changed (the default is to change it).

Default value: 1

scope

Specify scope of variable being set. Possible values are local (current target if the command is applied on a target, same as global otherwise), global or a name of existing target (in which case the variable is set on that target).

Can't be used with conditional variables.

Default value: local

make_var

If set to 1, then the variable is preserved in the makefile instead of being substituted by Bakefile. This happens only if the output format supports it (FORMAT_HAS_VARIABLES is set to 1) and if variable's value is not empty string. This settings is useful together with frequently used variables with long values, it helps reduce size of generated makefiles.

Default value: 0

hints

Comma-separated list of hint keywords. These hints are optional and Bakefile can (but doesn't have to) use them to better format generated makefiles. So far only files hint is supported. It tells Bakefile that the variable holds list of files and if it is either make or conditional variable, it is formatted in such way that only one file per line is written to the output (and therefore adding or removing files does only cause small differences).

Example:

<set var="APP_VERSION">1.0.3</set>
<set var="TAR_NAME">app-$(APP_VERSION).tar.gz</set>

See also: unset

unset

Unsets variable previously set by set. Note that you can only unset a variable, not an option or conditional variable.

<unset var="NAME"/>
  

Parameters:

var

The meaning is same as in set's properties.

option

Adds an option to the makefile.

<option name="NAME" [never_empty="NEVER_EMPTY"] [category="CATEGORY"]>
  [<default-value>DEFVALUE</default-value>]
  [<description>DESC</description>]
  [<values>VALUES</values>]
  [<values-description>VALUES_DESC</values-description>]
</option>

NAME is variable name under which the option is used in the makefile (using same syntax as when expanding variables). NAME is required, the rest of parameters is optional.

DEFVALUE is default value of the option, if appliable. It can be used by format backends that don't support options and it is used as default in those that do. Use it whenever possible.

NEVER_EMPTY may be set to 1 to tell Bakefile that it can treat the option as non-empty variable. This is useful only rarely in situations when Bakefile requires some non-empty value as tag's argument.

CATEGORY may be set to provide Bakefile additional information about the option. Certain operations (typically substitutions) may fail when applied to options unless all of its possible values are known. Because many tags use substitutions internally, this can be very limiting; the category hint can be used to work around most common problems. Possible values are unspecified (the default) and path, which indicates that the option will contain valid native, non-empty path name. An option with category set to path can be used as argument to tags like include.

DESC is human-readable description of the option, for use in comments.

VALUES is comma-separated list of all possible values the option can have. It is used by backends that don't support options (such as Visual C++ project files) to generate all possible configurations. It's use is highly recommended.

VALUES_DESC is comma-separated list of single-word description of corresponding values. It may be used only if VALUES were specified and both lists must have same length. These descriptions will show up in formats that don't support conditions, such as Visual C++ projects (the project will contain several configurations that will be described using these words).

template

Defines new template.

<template id="NAME" [template="TEMPLATE,..."]>
  SPECIFICATION
</template>
  

Template definition is syntactically identical to target definition. template is optional comma-separated list of templates this template derives from and SPECIFICATION may contain the very same things that target node.

Content of template node is not processed by Bakefile when it is encountered in makefile. It is stored in templates dictionary instead. When a target that derives from the template is encountered, the template is inserted before target's content.

For example consider this makefile fragment:

<template id="t1">
  <define>NAME=$(id)</define>
</template>
<template id="t2">
  <include>../headers</include>
</template>

<exe id="app" template="t1,t2">
  <sources>hello.c</sources>
</exe>

It looks like this after templates expansion:

<exe id="app" template="t1,t2">
  <define>NAME=$(id)</define>
  <include>../headers</include>
  <sources>hello.c</sources>
</exe>

using

This commands is used to declare what modules the makefile requires. See more about modules in the section called “Modules”.

<using module="MODULE1[,MODULE2[,...]]"/>
  

The effect of using is as follows: the modules are added to the list of used modules (unless they are already in it) and additional ruleset files are loaded from Bakefile search paths. Name of every file in every search path is decomposed into components by making every subdirectory name a component and splitting the basename into components by separating it on hyphens. A file is included as soon as all components of its name appear in the list of used modules. The inclusion behaves indentically to include.

Consider this structure of ruleset files:

python/common.bakefile        # python,common
python/cxx.bakefile           # python,cxx
cxx-common.bakefile           # cxx,common
cxx-qt.bakefile               # cxx,qt
qt/python.bakefile            # qt,python
qt/cxx-python.bakefile        # qt,cxx,python

Anotated makefile fragment illustrates order of modules loading:

<using module="python"/>
<!-- python/common.bakefile loaded -->

<using module="cxx"/>
<!-- cxx-common.bakefile loaded -->
<!-- python/cxx.bakefile loaded -->

<using module="qt"/>
<!-- qt/python.bakefile loaded -->
<!-- cxx-qt.bakefile loaded -->
<!-- qt/cxx-python.bakefile loaded -->

(Note that module "common" and module named after the target format are always used. Therefore ruleset files common/MODULE.bakefile are always loaded if they exist.)

The command may be used repeatedly in the makefile or included files. Repeating the using command with module that was already added to the list of used modules with using has no effect.

Parameters:

module

Comma-separated list of modules to use.

In this example the makefile uses Gettext, Python and Pascal modules:

<using module="gettext,python"/>
<using module="pascal"/>

include

Includes Bakefile file. This is done by loading the file and processing it immediately after include command is encountered during parsing. The effect of using include is identical to including content of the file in place of the include command.

<include file="FILENAME" [ignore_missing="0|1"]/>

Parameters:

file

Name of the file to include. The filename may be either absolute or relative. In the latter case, it is looked up relative to the location of the makefile that contains the include command and if that fails, relative to standard Bakefile search paths.

ignore_missing

If set to 1, it is not an error if the file can't be found. If 0, Bakefile will abort with an error if it can't find the file.

Default value: 0

if

Conditionally process part of the makefile.

<if cond="WEAKCONDITION">
  ...statements...
</if>

The condition must be weak. If it evaluates to 1 nodes under if node are processed as if they were toplevel nodes. If it evaluates to 0, they are discarded.

fragment

Inserts text into generated native makefile verbosely, so that it is possible to include things not yet supported by Bakefile in the makefiles. The text can be either read from a file or is taken from command node's content. Variables are not substituted in fragment's content, it is copied to the makefile as-is, with no changes.

ParameterDescriptionRequired/Default value
format Output format the fragment is for. required
file Read the fragment from file. no file, text is embedded

requires

Declares bakefile's requirements that the installed bakefile version must meet to be able to correctly generate native makefiles from it.

ParameterDescriptionRequired/Default value
version Minimal required version of Bakefile, e.g. 0.1.1. optional

Example:

<!-- refuse to run with Bakefile < 0.5.0,
     it's missing feature foo: -->
<requires version="0.5.0"/>

error

Reports error to output and exits. This command is useful for adding sanity checks to bakefiles (both user bakefiles and format definitions).

<!-- This code prevents creation of rules
     for console mode apps: -->
<define-tag name="app-type" rules="exe">
  <if cond="value == 'console'">
    <error>
      Windows CE doesn't support console applications.
      </error>
  </if>
</define-tag>

Commands for Extending Bakefile

define-rule

define-tag

add-target

modify-target

output

Bakefile uses this command to specify what files a format produces. Output is generated only as the result of output command's presence in ruleset.

ParameterDescriptionRequired/Default value
file The file where output goes. Commontly used value is $(OUTPUT_FILE). required
writer Name of Empy template that is used to generated the output. required
method

Method of combining generated output with existing content of the file. The default is replace, which overwrites the file.

mergeBlocks divides both the old and the new file's content into blocks that begin with block signature like this:

### beging block BLOCKNAME ###

Blocks of the new content are copied over to the file, replacing old copies of the blocks, but blocks that are not present in new content are preserved. This can be used e.g. to merge configuration settings from several makefiles.

mergeBlocksWithFilelist works similarly to mergeBlocks, but it includes list of input files that generated the block in the output and ensures that blocks that have no generator (e.g. because user's bakefiles changed and no longer cause some piece of code to be generated) are removed from the output. The list of files is added to block name like this:

### beging block
                      BLOCKNAME[file1.bkl,file2.bkl] ###

insertBetweenMarkers takes first and last line of generated output, finds them in the output file (which must exist and must contain them) and inserts generated content between them.

replace