Table of Contents
Bakefile targets correspond to native makefiles targets, they are compiled programs, libraries or more complex actions such as "install" or "dist" (which makes "make dist" command possible). Target syntax is similar to commands syntax:
<RULE id="NAME" [template="TEMPLATE,..."] [template_append="TEMPLATE2,..."] [cond="CONDITION"] [category="CATEGORY"]> SPECIFICATION </RULE>
There are six elementary rules (types of targets): exe, dll, module, lib, phony and action. More target types can be defined in ruleset (or even in the makefile) using define-rule command. Such new rules only extend one of elementary rules, though.
Target has unique id. This ID is usually present in generated makefile (so you can type make myprogram if you have target with ID myprogram). Name of the generated file is based on the ID, too.
template is optional comma-separated list of IDs of templates that the target is derived from. template_append is optional comma-separated list of templates that are appended to target specification (template inserts the template before the specification).
If cond attribute was given then the target is only compiled if given condition was met (the decision may be done either by Bakefile if the condition is weak or by generated makefile).
In addition to the ID, every target can have variables attached to it. These variables are only effective for the target (unlike global variables that affect all targets). They can be used to override global default (for example DLLEXT variable is .dll for Windows makefiles but you can override the variable locally for sharpen_plugin target to be .plugin).
Target is described using SPECIFICATION, which is a list of set command and so-called tags. Tags are rule-specific constructs that provide simple way to e.g. list source files for an executable, set include directories or define compiler flags. Unlike set they don't set any specific variable, but rather set various variables in generator-specific way. Tag syntax is almost identical to set function, but without variable name:
<TAGNAME>VALUE</TAGNAME></RULE>
Common tags are described in the section bellow, tags specific to particular modules are described in Chapter 8, Modules. A small example of using tags:
<exe id="myprogram"> <!-- set target-specific variable: --> <set var="SOME_VAR">value</set> <!-- three tags: --> <sources>file1.c myprogram.c utils.c</sources> <include>./includes</include> <define>USE_UNICODE</define> </exe>
Unless the documentation says otherwise, you can use the same tag repeatedly with same target.
Optional category attribute can be given to clasify the target. Possible clasifications are all (reserved for the all target of makefiles and cannot be used in user bakefiles), normal for targets declared in bakefiles and automatic for targets that are created as a side-effect of Bakefile's processing (e.g. object file targets). The targets are sorted in generated makefile according to the category: all target is first, followed by normal targets and automatic targets are last.
Some rules don't declare real targets but so-called pseudo targets. Pseudo targets are processed as standard targets, but they don't appear in the generated makefile, have no action associated with them and can't depend on any other target or be dependency of another target. They are used as user-friendly means of modifying behaviour of other targets. An example of pseudo target is data-files.
The advantage of pseudo targets is that the id attribute is not required. The disadvantage is that they can't be conditional.
Description of builtin rules and their tags follows. Additional rules and tags are defined by modules, see Chapter 8, Modules.
Builds a program.
Tag | Description |
---|---|
dllname | Similar to libname tag on dll, but it affects the name of shared library/DLL. |
libname | Similar to dllname, but used for import library on Windows and .so symlink on Unix. |
version | |
so_version | |
mac_version |
Builds loadable module (aka plugin). Unlike dll, this one does not create import library on Windows.
Tag | Description |
---|---|
dllname | See dllname. |
This type of target does nothing. It is usually used as convenience target together with depends tag to easily build set of targets. Standard target all is an example of phony target.
This is most generic rule. It allows you to execute arbitrary sequence of commands when building the target and can therefore be used to extend Bakefile with custom build rules. Note that this rule is not platform- and compiler-independent as the rest of rules.
Tag | Description |
---|---|
command |
Adds command to list of commands to be executed when building the target. <action id="manual.html"> <command>docbook2html manual.xml manual.html</command> </action>
|
Declares subproject. Subproject is typically another makefile in a subdirectory and is indepent on its parent project. Therefore you can't use any variables or refer to targets from parent project in subproject.
These tags are always available, it is not neccessary to load any module to use them.
Tag | Description | Availability |
---|---|---|
depends |
This tag is used to express target's dependency on other targets. All targets in depends tag must be built prior to building this target. The value is whitespace-separated list of target IDs. It is an error to specify nonexistent target here. Note that library tag implies depends. <copy-file id="setup"> <source>setup0.h</source> <dest>setup.h</dest> </copy-file> <exe id="app"> <depends>setup</depends> <sources>app.c</sources> <define>USE_SETUP_H</define> </exe> | all rules |
objects-depend |
Same as depends, except the dependency is added to all object files used to build the target instead of to the target itself. This is useful e.g. in combination with precompiled headers (which must be generated before any source file is compiled) or when a commonly used header file is generated by the makefile. | exe, dll, module, lib |
dirname | Set name of directory where the target will be created. BUILDDIR is used by default. | exe, dll, module, lib |
dependency-of |
Mark the target as dependency of target specified in tag's
value. The value must be ID of existing target. This tag
is opposite of depends. Following two
examples have identical effect:
<exe id="setup"></exe> <exe id="app"> <depends>setup</depends> </exe> <exe id="app"></exe> <exe id="setup"> <dependency-of>app</dependency-of> </exe>Note that only one of these tags should be used, it is not necessary to specify both of them. | all |
sources |
Specify source files used to build the target.
<exe id="app"> <sources>app.c</sources> <sources>utils.c utils2.c</sources> </exe> | exe, dll, module, lib |
include | Add directory where the compiler should look for headers. Calls res-include with same value. | exe, dll, module, lib |
define | Define C preprocessor macro. The value may be empty, in which case no flag is added. Calls res-define with same value. | exe, dll, module, lib |
sys-lib |
Link against specified library installed in the system. Note
that this is not meant for linking in
libraries that were built by the same makefile, use
library for that. This command links
against a library installed in the system or provided by the
compiler and corresponds to the -l switch
of Unix compilers.
<exe id="png2bmp"> <sources>png2bmp.c</sources> <sys-lib>png</sys-lib> <sys-lib>z</sys-lib> </exe>Library name may be empty. Only one library may be specified as argument, following usage is incorrect: <exe id="png2bmp"> <sources>png2bmp.c</sources> <sys-lib>png z</sys-lib> <!-- INCORRECT --> </exe>Note that the name of library in this tag is not filename and must not include paths; use lib-path to specify library search path. | exe, dll, module |
lib-path | Add directory where to look for system libraries. | exe, dll, module |
library |
Link against library compiled by this makefile. The value
passed to this tag must be name of existing target. Compare
sys-lib.
<lib id="mylib"> <sources>lib1.c lib2.c</sources> </lib> <exe id="myapp"> <sources>main.c</sources> <library>mylib</library> <sys-lib>X11</sys-lib> <sys-lib>GL</sys-lib> </exe> | exe, dll, module |
optimize |
Set compiler's optimization level. May be one of
off (no optimization),
speed (generate fastest code) or
size (smallest code).
<set var="OPTIMIZE_FLAG"> <if cond="BUILD=='release'">speed</if> <if cond="BUILD=='debug'">off</if> </set> <exe id="myapp"> <optimize>$(OPTIMIZE_FLAG)</optimize> <sources>main.c</sources> <sys-lib>GL</sys-lib> </exe> | exe, dll, module, lib |
debug-info | Enable or disable debugging information. Can be either on or off. | exe, dll, module, lib |
debug-runtime-libs | Enable or disable linking against debug version of C runtime. Can be either on or off and must appear after debug-info. If not specified, then debug runtime libraries are used if and only if debug-info was set to on. Note that this tag has effect only with Visual C++; other compilers respect only debug-info. | exe, dll, module, lib |
arch | Set target CPU architecture. Note that this is not portable and should be avoided if possible. Accepted values are i[3456]86. | exe, dll, module, lib |
pic | Tells the compiler whether to generate position-independent code or not. The default is to use PIC for DLLs and not use it for executables and static libraries, but you may want to change it if your static library may be linked into a DLL. Accepted values are on and off. | exe, lib |
threading | Use multi to enable and single to disable multithreading in the application. This affects what libraries are linked into executable on some platforms. | exe, dll, module, lib |
warnings | Sets warnings level for C/C++ compiler. Possible values are no, default and max. | exe, dll, module, lib |
precomp-headers | Can be on or off, enables or disables use of precompiled headers with compilers that support them. | exe, dll, module, lib |
cxx-rtti | Enable or disable RTTI when compiling C++ sources. Can be either on or off. | exe, dll, module, lib |
cxx-exceptions | Enable or disable C++ exceptions handling. Can be either on or off. | exe, dll, module, lib |
precomp-headers-file | Use this tag to fine-tune where precompiled headers are stored. The compiler must support this and the value passed to precomp-headers-file can be modified by Bakefile, e.g. by apending .pch extension to it. | exe, dll, module, lib |
Add compiler dependent compilation flags to compiler flags. | exe, dll, module, lib | |
Add linker dependent flags for the linker. | exe, dll, module, lib | |
Same as ldflags, but adds the flags after all flags specified using ldflags. This is useful when resolving command line order problems that gcc is prone to. | exe, dll, module | |
win32-res | Sets win32 resource (.rc) file for executable or DLL. The tag does nothing on platforms other than Windows. Compilation of the resource respects define and include tags on the target, as well as their resource specific counterparts res-define and res-include. | exe, dll, module |
mac-res | Sets Mac resource (.r) file for executable or DLL. The tag does nothing on platforms other than Mac. Compilation of the resource respects define and include tags on the target, as well as their resource specific counterparts res-define and res-include. | exe, dll, module |
res-include | Similar to include, but applies only to resources (mac-res, win32-res) and not to C/C++ sources. | exe, dll, module |
res-define | Similar to define, but applies only to resources (mac-res, win32-res) and not to C/C++ sources. | exe, dll, module |
clean-files | Adds files to list of files that are cleaned when make clean is run -- i.e. files created while building the target. | all |
install-to | If used, then the target is installed into directory specified as tag's value by make install. | exe, dll, module, lib |
install-if |
Install (see install-to
the target conditionally. The value must be well-formed
condition.
<option name="INSTALL_HELLO"> <values>0,1</values> <default-value>1</default-value> </option> <exe id="hello"> <sources>hello.c</sources> <install-to>$(BINDIR)</install-to> <install-if>INSTALL_HELLO=='1'</install-if> </exe> | exe, dll, module, lib |
postlink-command | Use this tag to specify command(s) that must be executed after the target is linked. This can be used to e.g. add resources or strip debugging information. | exe, dll, module, lib |
uid | Defines target's unique ID number for formats that need it. FIXME: currently not implemented in any format; document use of type=symbian1 etc. once it is used by something | exe, dll, module |
Many configuration options listed above are not supported by the Autoconf format (e.g. optimize, debug-info or arch. This is because configure is used to find appropriate compiler flags.