# Commands Reference

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. ) 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. Any constant expression is allowed for this attribute, not only literals.

      <set var="postfix">world</set>
      <set var="prefix">hello</set>

      <!-- the following <set> tag will create a "hello_world" variable: -->
      <set var="$(prefix)_$(postfix)">Hello world</set>
      <echo>$(hello_world)</echo>

  Required parameter

append

  If 1, the value is appended to previous value of the variable if it is already defined, with a space inserted between them. If the variable wasn't defined yet, 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 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 and` condexpr" 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 ( 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

Unsets variable previously set by . 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 [force="FORCE"]>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. Note that for options with listed values (see the `VALUES` parameter), the default value must be one of the values listed unless `FORCE` is set to `1`.

`FORCE` can be `0` (the default) or `1` to indicate that Bakefile should not check that the default value is in the list of allowed values. This is useful when you want to use e.g. a shell command as the default value (`$(shell some-command)`) or an environment variable `$(MYENVVAR)`. It is your responsibility to ensure that the default value is a legal value if you use `force=1`.

`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 .

`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 .

    <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 .

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"] [once="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

once

  If set to 1, then the file won't be included if it was already included previously.

  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 verbatim, 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.

Parameter | Description | Required/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.

Parameter | Description | Required/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>

### warning

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

    <if cond="FORMAT=='msvc'">
        <warning>msvc support is experimental</warning>
    </if>

### echo

Prints the text in tag's value to output and, unlike , continues processing. This command is useful for debugging bakefiles (e.g. by printing variable values or adding progress messages).

Note that if a variable is used in the text, it must evaluate to a constant (i.e. conditional variables or options cannot be used).

Parameter | Description | Default value
--- | --- | ---
level | Can be `verbose` (in which case the message is printed only when is run with `--verbose` argument), `debug` (printed only when using the `--debug` flag) or `normal` (message is printed in any case to stdout). | `normal`

Example:

    <!-- Show the content of the variable X -->
    <set var="X">$(someComplexFunction())</set>
    <echo>The content of the X variable is: $(X)</echo>

## Commands for Extending Bakefile

### define-rule

Creates a new rule which can then be used as any other rule. A rule consists of the template (which is processed before target-specific code for all targets created by this rule) and unlimited number of statements that define tags specific to this rule (and derived rules).

The usage of <define-rule> is as follows:

    <define-rule name="NAME">
      <template>
        <!-- here goes the template for this rule -->
      </template>

      <define-tag name="TAG1">
        ..
      </define-tag>
      <define-tag name="TAG2">
        ..
      </define-tag>
      ...
    </define-rule>

Parameter | Description | Required/Default value
--- | --- | ---
name | The name of the rule to create. | required
pseudo | Allowed values are `0` and `1`; the value of means that the rule is a pseudotarget. | `0`
extends | A comma-separed list of the rules which are extended by this rule. If rule B extends rule A, it means that all tags defined for A are also valid for B and the template of rule B automatically derives from the the template of rule A. |

Example:

    <!-- Creates a new "copymo" rule with its own specialized
         tags; example usage of this rule:

            <copymo id="i18n">
                <lang>en</lang>
                <mo>myfile.mo</mo>
            </copymo>
    -->
    <using module="datafiles"/>
    <define-rule name="copymo" extends="copy-files">
        <template>
            <srcdir>$(SRCDIR)/locale</srcdir>
            <files>$(__mofiles)</files>
            <dependency-of>all</dependency-of>
        </template>
        <define-tag name="lang">
            <dstdir>$(DATADIR)/locale/$(value)/LC_MESSAGES</dstdir>
        </define-tag>
        <define-tag name="mo">
            <set var="__mofiles">$(value)</set>
        </define-tag>
    </define-rule>

### define-tag

Creates a new tag which can be used inside target definition or rules templates.

This command can be used in two ways: either it's used inside of , in which case it defines a new tag for the current rule, or it's used in the global scope, in which case it must have the `rules` attribute that specifies which rules the tag applies to.

Parameter | Description | Required/Default value
--- | --- | ---
name | Name of the tag to define. | required
rules | Comma-separed list of rules to which the tag applies. | required in global scope, implicit inside

Example:

    <!--
    Create a new tag which adds include and lib paths for a "standard"
    library and can be used inside <exe> or <dll> tags; e.g.

      <exe id="test">
        <stdlib>lib1</stdlib>
        <stdlib>lib2</stdlib>
      </exe>
    -->
    <define-tag name="stdlib" rules="exe,dll">
      <include>$(value)/include</include>
      <lib-path>$(value)/lib</lib-path>
    </define-tag>

### define-global-tag

Like , but creates a tag that can only be used in the global scope (i.e. alongside targets definitions as opposed to inside them).

Parameter | Description | Required/Default value
--- | --- | ---
name | Name of the tag to define. | required

Example:

    <!--
    Create a global tag which defines 3 variables with the same given
    prefix and with the same content; e.g.

      <dummyset prefix="test">abc</dummyset>
      <echo>$(test_first) $(test_second) $(test_third)</echo>

    will display "abc abc abc"
    -->
    <define-global-tag name="dummyset">
      <set var="$(attributes['prefix'])_first">$(value)</set>
      <set var="$(attributes['prefix'])_second">$(value)</set>
      <set var="$(attributes['prefix'])_third">$(value)</set>
    </define-global-tag>

### add-target

Creates a target programmatically.

Using this command is equivalent to defining a target by using the standard rules syntax, but it makes it possible to add a target using dynamically determined rule. As such, it's only useful when implementing other, higher-level rules. This tag is hardly useful for normal uses of bakefile and is used mostly as an internal utility.

This command can only be used inside rule definition, not in the global scope.

Parameter | Description | Required/Default value
--- | --- | ---
target | ID of the target to create. | required
type | The rule for the target. | required
cond | The condition under which the target is built. In addition to regular condition syntax, two special forms are supported. If the condition is `target`, the condition of the target within which the tag has been used (if any). If the condition has the form of `target and` `someOtherCondition`, then target's condition as described above will be appended with `and` `someOtherCondition`. | `1`

Example:

    <!--
    Creates a new EXE target 'myexe'; this is equivalent to
      <exe id="myexe">
        <sources>source1.c</sources>
      </exe>
    -->
    <add-target target="myexe" type="exe">
      <sources>source1.c</sources>
    </add-target>

    <!--
    Now define a <do_special_cmd> tag which creates a target with
    a name dynamically defined by the target from which the tag is used
    -->
    <define-tag name="do_special_cmd" rules="exe">
      <add-target target="do_special_for_$(id)" type="action" cond="target"/>
      <modify-target target="do_special_for_$(id)">
        <command>special_command $(id)</command>
      </modify-target>
    </define-tag>

    <exe id="myapp" cond="BUILD_MYAPP=='1'">
      ...

      <!-- the following tag will create a target 'do_special_for_myapp' which will
           be executed only when BUILD_MYAPP=='1' -->
      <do_special_cmd/>
    </exe>

### modify-target

Modifies an existing target by appending tags under this node to its definition.

Parameter | Description | Required/Default value
--- | --- | ---
target | ID of the target to modify. | required

Example:

    <!-- Modifies the global 'install' target to run an additional command -->
    <modify-target target="install">
      <command>$(CP) myfile dest</command>
    </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.

Parameter | Description | Required/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`