Chapter 4. Targets

Chapter 4. Targets
Prev		Next

Table of Contents

exe
lib
dll
module
phony
action
subproject

Bakefile targets correspond to native makefile targets: they are compiled programs, libraries, or more complex actions such as "install" or "dist". Target syntax is similar to command syntax:

<TYPE id="NAME" [template="TEMPLATE,..."] [template_append="TEMPLATE,..."]
      [cond="CONDITION"] [category="CATEGORY"]>
  SPECIFICATION
</TYPE>

There are six standard target types: exe, dll, module, lib, phony and action. You can define a new "rule" (that is, a target type) based on one of the standard rules using the define-rule command.

Each target requires a unique id. This ID is usually present in the generated makefile, so you can type make myprogram to create the target with the ID myprogram. The target's ID also controls the name of the output file.

template is an optional comma-separated list of IDs of templates that the target is derived from. template_append is an optional comma-separated list of templates that are appended to the target specification. (template inserts the template before the specification).

If the cond attribute is given, the target is only compiled if the named condition was met. (Follow that link to see the rules governing whether Bakefile evaluates the condition, or the native build system (e.g. make) evaluates it).

In addition to the ID, every target can have variables attached to it. These variables are only effective for the target; contrast global variables, which affect all targets. They can be used to override a global variable: for example, the DLLEXT variable is .dll for Windows makefiles, but you can override the variable locally for the sharpen_plugin target to be .plugin.

Target is described using SPECIFICATION, which is a list of set commands and tags. Tags are rule-specific constructs, so they come in several forms: they can 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 a generator-specific way. Tag syntax is almost identical to the set function, but without a variable name:

<TAGNAME>VALUE</TAGNAME>

Common tags are described in the section below. Tags specific to particular modules are described in Chapter 10, 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 the same target.

The optional category attribute can be given to classify the target. Possible classifications 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 the generated makefile according to the category: the all target is first, followed by normal targets, and then automatic targets.

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, can't depend on any other target, and can't be a dependency of another target. They can only modify the behavior of other targets. An example of a 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.

Standard Target Types ("Rules")

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

exe

Builds a program.

Tag	Description
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).
stack	Set the size of the stack on platforms where it is possible. The default stack size varies for different platforms and compilers. With too small stack you may get an error indicating stack has overflowed. (Currently used by Watcom format only.)

lib

Tag Description

Tag	Description
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>

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

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	Portable platform-independent shared library version. Not yet implemented.
so_version	The value consists of three numbers separated by dots. Library name plus the first component of the version together form soname (e.g. `libfoo.so.1` on Linux) which is used for runtime resolution of dependencies. Libraries with different sonames are binary incompatible and cannot be used interchangeable. On the other hand, the remaining two components contain information about minor versions that don't change backward compatibility and aren't used by runtime linker. Note that this version number is strictly for runtime linker's use and for maintaining binary compatiblity, it should not be version number of your library. This tag is only implemented in the `autoconf` format.
mac_version	This tag is used to specify shared library version for runtime linker on Darwin platforms. Similarly to so_version, it expects three numbers separated by dots, but their interpretation is different. The value is passed as-is to compilers `-current_version` argument and the first two components are passed to `--compatibility_version`. See See Apple's ld documentation for details. This tag is only implemented in the `autoconf` and `xcode2` formats.

module

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

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

Tag Description

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>
is-phony	Marks the target as phony. A phony target is target whose name is not really the name of file produced by it, as is the case with "standard" targets. Instead, it's just a symbolic name for some commands to be executed. In other words, this target should not be considered by `make` when creating the file dependency graph. For an example of why this is useful, consider a `tags` target that runs the Unix `ctags` program. That program creates a file called `tags`, so after saying `make tags` once, `make` will always say that the tags target is up to date. By marking the target as phony, you disable the file dependency checking for it, so `make tags` always runs the `ctags` program.

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>

is-phony

Marks the target as phony. A phony target is target whose name is not really the name of file produced by it, as is the case with "standard" targets. Instead, it's just a symbolic name for some commands to be executed. In other words, this target should not be considered by make when creating the file dependency graph. For an example of why this is useful, consider a tags target that runs the Unix ctags program. That program creates a file called tags, so after saying make tags once, make will always say that the tags target is up to date. By marking the target as phony, you disable the file dependency checking for it, so make tags always runs the ctags program.

subproject

Declares a subproject. This is typically another makefile in a subdirectory and is independent of its parent project. Therefore you can't use any variables or refer to targets from the parent project in a subproject.

Tag	Description	Required/Default value
dir	Directory containing 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 a constant expression.	`yes`

Here is an example of how to use the subproject target:

<subproject id="examples">
  <dir>examples</dir>
  <installable>no</installable>
</subproject>

Common tags

These are tags you can use with any of the above target types. 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 the `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 a nonexistent target here. Note that the library tag implies `depends`. <exe id="app"> <sources>app.c</sources> <depends>setup</depends> </exe>	all rules
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
headers	Specify (C/C++) header files used by the target. <exe id="app"> <headers>app.h</headers> <headers>utils.h additionalheader.h</headers> <sources>app.c</sources> </exe>	exe, dll, module, lib
depends-on-file	Mark the target as depending on a given file. Use this when the dependency isn't one of the other declared targets. This can be useful for example when the dependency is generated by a script: <action id="generated-header.h"> <command>./header-generator.pl</command> <depends-on-file>header-generator.pl</depends-on-file> </action> In this example, the header-generator.pl script creates generated-header.h. You would want the script to be re-run any time it changes, since the change probably would make it generate different contents for that header file. But since generated-header.pl is not itself generated by the makefile, you cannot use the depends tag here.	all
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
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. This corresponds to the `-I` switch used by many compilers. Calls res-include with the same value. Example: <exe id="hello"> <sources>hello.c</sources> <include>../include/foo</include> </exe>	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> The library name may be empty. Only one library may be given as the tag's argument; the following usage is incorrect: <exe id="png2bmp"> <sources>png2bmp.c</sources> <sys-lib>png z</sys-lib> <!-- INCORRECT --> </exe> Note that the name of the library in this tag is not a file name and must not include paths. Use lib-path to add a directory to the library search path.	exe, dll, module
lib-path	Add a directory to the search path used by the compiler to find system libraries. This corresponds to the `-L` switch of Unix compilers. Example: <exe id="hello"> <sources>hello.c</sources> <!-- note that hardcoding library paths like this is a bad idea, it's done here only for the sake of simplicity; in real bakefile, an <option> would be used --> <lib-path>/usr/lib/mysql</lib-path> <sys-lib>mysqlclient</sys-lib> </exe> On a typical Unix system, this asks the linker to link the `hello` program against `libmysqlclient.so` and to search for it in the directory `/usr/lib/mysql` in addition to any other directories the linker is configured to use.	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
debug-info-edit-and-continue	Enable or disable additional debugging information to support Edit and Continue feature of Visual C++ compilers. Can be either `on` or `off` (default). Only supported by Visual C++ project files, does nothing in other formats.	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
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
precomp-headers-gen	For compilers that support it, specify which source file should be used to generate precompiled headers. <exe id="myapp"> <sources>foo.cpp bar.cpp</sources> <precomp-headers>on</precomp-headers> <precomp-headers-gen>foo.cpp</precomp-headers-gen> <precomp-headers-header>mypch.h</precomp-headers-header> </exe>	exe, dll, module, lib
precomp-headers-header	For compilers that support it, specify which header file should be used as the precompiled header. Typically, this header must be the first header included and it must be included by all source files. Some compilers (GCC in particular) ignore this, because they use different PCH model. <exe id="myapp"> <sources>foo.cpp bar.cpp</sources> <precomp-headers>on</precomp-headers> <precomp-headers-gen>foo.cpp</precomp-headers-gen> <precomp-headers-header>mypch.h</precomp-headers-header> </exe>	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
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
symbian-res	Sets Symbian resource file for executable or DLL. The tag does nothing on platforms other than Symbian. 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 (and uninstalled from there by the make uninstall target).	exe, dll, module, lib
install-headers-to	If used, then the headers (see headers tag) of the target are installed into the directory specified as tag's value by make install (and uninstalled from there by the make uninstall target).	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
msvc-guid	(Visual C++ project formats only.) Sets project's GUID.	exe, lib, 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.

Prev		Next
Chapter 3. Bakefile Concepts	Home	Chapter 5. Commands Reference