Sets a variable. There are two forms of the command. The first one is 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.

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 set. Note that you can only unset a variable, not an option or conditional variable.

<unset var="NAME"/>
  

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

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>

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.

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

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

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"]/>

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.

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.

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

Example:

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

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>

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>

Prints the text in tag's value to output and, unlike error, 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).

Example:

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

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 define-tag 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>

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>

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 define-rule, 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.

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>

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

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>

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.

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>

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

Example:

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

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.

### beging block BLOCKNAME ###

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