Chapter 4. Targets

Table of Contents

Rules
exe
lib
dll
module
phony
action
subproject
Common tags

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.

Pseudo targets

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.

Rules

Description of builtin rules and their tags follows. Additional rules and tags are defined by modules, see Chapter 8, Modules.

exe

Builds a program.

TagDescription
app-type Use this tag to specify whether the executable is console application (console) or windowed one (gui). These two kinds of applications are linked differently on Windows.
<exe id="foo">
  <app-type>gui</app-type>
  <sources>foo.c bar.c</sources>
</exe>
exename Set name of the executable. By default, the name is same as id, but it is sometimes useful to use different name to identify the executable in makefiles (id) and for created program file (exename). Physical filename is deriver from exename and format-specific extension (e.g. .exe on Windows).

lib

TagDescription
libname Set name of the library. By default, the name is same as id, but it is sometimes useful to use different name to identify the library in makefiles (id) and for created library file (libname). This tag does not set physical filename -- that is derived from libname and other generator-specific variables.
<lib id="foo">
  <libname>foo$(COMPILER)_$(DBGFLAG)</libname>
  <sources>foo.c bar.c</sources>
</lib>

dll

TagDescription
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

module

Builds loadable module (aka plugin). Unlike dll, this one does not create import library on Windows.

TagDescription
dllname See dllname.

phony

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.

action

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.

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

subproject

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.

TagDescriptionRequired/Default value
dir

Directory with subproject -- parent makefile calls makefile in this directory.

required
target

Optional argument which specifies what target to build in the subproject.

all
installable

Whether make install (if supported by the format) should descend into subproject's directory. The value can only be yes or no and must be constant expression.

yes

Common tags

These tags are always available, it is not neccessary to load any module to use them.

TagDescriptionAvailability
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

cflags

cxxflags

cppflags

Add compiler dependent compilation flags to compiler flags. exe, dll, module, lib

ldflags

Add linker dependent flags for the linker. exe, dll, module, lib

ldlibs

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

Autoconf Note

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.