Chapter 4. Targets
Prev |  | Next

## Chapter 4. Targets

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