Bakefile Documentation¶
Contents:
Introduction¶
Just Show Me How It Works¶
If you already have an idea of what Bakefile does, please feel free to skip directly to the Tutorial.
Motivation¶
Almost any introductory C or C++ book starts with presenting a version of “Hello, world” program. Some of them also show how to compile the program, although often enough the reader is advised to refer to the documentation of the compiler to learn how to do it. And almost none of the books or tutorials address the issue of how can the program be compiled not in a single environment and with a single compiler but on several different platforms or, perhaps, with different compilers on the same platform. And there is a good reason for avoiding discussing this: surprisingly, 40 years after the invention of C programming language, there is still no satisfactory solution to this problem.
Before discussing how Bakefile helps to address it, let’s briefly mention the two usual anti-solutions. The first one of them is to naively separately write build scripts, make files or projects for each of the environments used. While there is no problem with this approach as long as a single such environment is used, accurately propagating changes to one of the files to all the other ones becomes bothersome even when there are only two of them and, in practice, the divergences almost inevitably appear. For a cross-platform project, targeting many different platform, this quickly becomes a serious maintenance burden. But even for projects used under a single platform, keeping different versions of the project files can be annoying (a typical example is that of Microsoft Visual C++ compiler which has changed its project file format with each and every one of its last 5 releases).
The problems of this naive approach have resulted in creation of a huge number of cross-platform build tools. This manual is too short to discuss the cons and pros of each of them, but they all share one fundamental weakness that makes us classify them all as an anti-solution: the use of such tool replaces the use of the normal tools used for software development under any given platform. As anybody who has tried to convince a seasoned Unix programmer to switch to using Xcode instead of make, a Windows developer to use make instead of Microsoft Visual Studio or someone used to work with Xcode to live without it can attest, this can be a bad idea with effects ranging from the drop of participation in an Open Source project to poisoning the atmosphere in the office in a company one.
The Bakefile Solution¶
The solution proposed by Bakefile allows to combine the use of native development tools with the lack of maintenance headaches due to having to modify the files for each of the tool chains manually. Bakefile is a meta-make tool which does not replace the normal make program or IDE used for building the project but simply generates the input files for it from a unique meta-makefile which we call a “bakefile”.
It is important to notice that the make and project files created by bakefile [*] are as similar to the files with the same functionality created by hand as possible, i.e. are easy to understand for anybody familiar with the underlying tool. These files still should not be modified directly but, in a pinch, this can be done – and is as easy to do as with manually crafted versions.
This need to restrict modifications to the bakefiles themselves and avoid modifying the files generated from them does require some discipline but this is the smallest possible price to pay for solving the problem of how to let developers use their favourite tool chain under all platforms without having to manually ensure the synchronization between all of them.
[*] | This process is, inevitably, called “baking”. |
Tutorial¶
Hello, Bakefile¶
After complaining about the lack of examples of how “Hello, World” program can
be built in a portable way in the introduction, we’d be amiss to not provide
an example of doing this here. So, assuming the text of the program is in the
file hello.c
, here is the corresponding hello.bkl
bakefile to build it:
toolsets = gnu vs2010;
program hello {
sources { hello.cpp } // could also have been "hello.c"
}
To produce something interesting from it we need to run bakefile simply passing it this file name as argument:
$ bkl hello.bkl
or maybe:
C:\> bkl hello.bkl
In the grand tradition of Unix tools, Bakefile doesn’t produce any output
after running successfully. If this is too closemouthed for your taste, you
can try adding -v
option which will indicate all the files read and, more
importantly, written by the tool. Using this option or just examining the
directory you ran Bakefile in you can see that it created several new files.
In our case, they will be GNUmakefile
for “gnu” toolset (the one using
standard GNU development tools) or hello.sln
and its supporting files for
“vs2010” toolset (Microsoft Visual Studio 2010) one. These files then can be
used to build the project in the usual way, i.e. by running “make” or opening
the file in the IDE.
Please check that you can run Bakefile and generate a working make or project file appropriate for your platform (“gnu” for Unix systems including OS X, “vs2010” for Microsoft Windows ones).
Example Explained¶
Bakefile input language is C-like, with braces and semicolons playing their
usual roles. Additionally, both C and C++ style comments can be used. It
however also borrows some simple and uncontroversial elements [*] of make
syntax. Notably, there is no need to quote literal strings and, because of
this, Bakefile variables – such as toolsets
above – need to be
explicitly dereferenced using make-file $(toolsets)
expression when
needed.
Knowing this we can see that the first line of the hello bakefile above simply
sets a variable toolsets
to the list of two strings. This variable is
special for Bakefile – and hence is called “property” rather than a simple
“variable” – and indicates which make or project files should be generated
when it is ran. It must be present in all bakefiles as no output would be
created without it.
The next block – program hello { ... }
– defines an executable target with
the name “hello”. All the declarations until the closing bracket affect this
target only. In this simple example the only thing that we have here is the
definition of the sources which should be compiled to build the target. Source
files can be of any type but currently Bakefile only handles C (extension
.c
) and C++ (extension .cpp
, .cxx
or .C
) files automatically
and custom compilation rules need to be defined for the other ones. In any
real project there are going to be more than one source file, of course. In
this case they can just be listed all together inside the same block like
this:
sources {
foo.cpp subdir/bar.cpp
// Not necessarily on the same line
baz.cpp
}
or they can be separated in several blocks:
sources { foo.cpp }
sources { subdir/bar.cpp }
sources { baz.cpp }
The two fragments have exactly the same meaning.
Customizing Your Project¶
Compilation And Linking Options¶
A realistic project needs to specify not only the list of files to compile but
also the options to use for compiling them. The most common options needed for
C/C++ programs are the include paths allowing to find the header file used and
the preprocessor definitions and Bakefile provides convenient way to set both
of them by assigning to defines
and includedirs
properties inside a
target:
program hello {
defines = FOO "DEBUG=1"; // Quotes are needed if value is given
includedirs = ../include;
...
}
These properties can be set more than once but each subsequent assignment overrides the previous value which is not particular useful. It can be more helpful to append another value to the property instead, for example:
program hello {
defines = FOO;
...
defines += BAR;
...
defines += "VERSION=17";
defines += "VERSION_STR=\"v17\"";
}
will define “FOO” and “BAR” symbols (without value) as well as “VERSION” with the value of 17 and “VERSION_STR” with the value as a C string during compilation. This is still not very exciting as all these values could have been set at once, but the possibility of conditional assignment is more interesting:
program hello {
if ( $(toolset) == gnu )
defines += LINUX;
if ( $(toolset) == vs2010 )
defines += MSW;
}
would define LINUX
only for makefile-based build and MSW
for the
project files.
While defines
and includedirs
are usually enough to cover 90% of your
needs, sometimes some other compiler options may need to be specified and the
compiler-options
property can be used for this: you can simply any options
you want to be passed to C or C++ compiler into it. If you need to be more
precise and only use some options with a particular compiler in a project
using more than one of them, you can also use c-compiler-options
or
cxx-compiler-options
.
One aspect of using these properties is that different compilers use different format for their options, so it’s usually impossible to use the same value for all of them. Moreover, sometimes you may actually need to use custom options for a single toolset only. This can be done by explicitly testing for the toolset being used. For example, to use C++ 11 features with GNU compiler you could do
if ( $(toolset) == gnu )
cxx-compiler-options = "-std=c++11"
Similarly, any non trivial project usually links with some external libraries.
To specify these libraries, you need to assign to the libs
property and
also may need to set libdirs
if these libraries are not present in the
standard search path:
program hello {
libdirs = ../3rdparty/somelib/lib;
libs = somelib;
}
Notice that you only need to do the latter if the libraries are not built as part of the same project, otherwise you should simply list them as dependencies as shown in the next section.
And if you need to use any other linker option you can specify it using
link-options
property. As with compiler options, you would normally test
for the toolkit before doing it as linker options are toolset-specific.
Multiple Modules¶
Larger projects typically consist in more than just a single executable but of several of them and some libraries. The same bakefile can contain definitions of all of them:
library network {
sources { ... }
}
library gui {
sources { ... }
}
program main {
deps = network gui;
...
}
In this case, the libraries will be built before the main executable and will be linked with it. Bakefile is smart about linking and if a library has dependencies of its own, these will be linked in as well.
Alternatively, you can define each library or executable in its own bakefile.
This is especially convenient if each of them is built in a separate
directory. In this case you can use submodule
keyword to include the
sub-bakefiles.
Assorted Other Options¶
Under Windows, console and GUI programs are compiled differently. By default,
Bakefile builds console executables. You can change this by setting the
win32-subsystem
property to windows
.
Another Windows-specific peculiarity is that standard C run-time library
headers as well as Platform SDK headers are compiled differently depending on
whether _UNICODE
and UNICODE
macros, respectively, are defined or not.
By default, Bakefile does define these macros but you can set win32-unicode
target property to false
to prevent it from doing it.
Finally, Windows projects generated by default only contain configurations for Win32 platform. To generate 64 bit configurations as well, you need to explicitly request them by defining the architectures to build for:
archs = x86 x86_64;
The name of 64 bit architecture is x86_64
and not x64
which is usually
used under Windows because the architectures are also used under other
platforms, notably OS X where universal binaries containing both 32 bit and 64
bit binaries would be built with the above value of archs
.
[*] | So no meaningful tabulations or backslashes for line continuation. |
Advanced Stuff¶
Generated Source Files¶
Bakefile supports custom compilation steps; this can be used both for files generated with some script and for compilation of unsupported file types.
Compiling a custom file is as simple as setting the compile-commands
property on it to the command (or several commands) to compile the file,
outputs
property with the list of created files and optionally filling in
additional dependencies:
toolsets = gnu vs2010;
program hello {
sources { hello.cpp mygen.cpp mygen.desc }
mygen.desc::compile-commands = "tools/generator.py -o %(out) %(in)";
mygen.desc::outputs = mygen.cpp;
// add dependency on the generator script:
mygen.desc::dependencies = tools/generator.py;
}
Notice that the generated files listed in outputs
must be included in
sources
or headers
section as well.
Additionally, any number of other dependency files can be added to the
dependencies
list. The command uses two placeholders, %(in)
and
%(out)
, that are replaced with the name of the source file (mygen.desc
in our example) and outputs
respectively; both placeholders are optional.
If there are multiple output files, %(out0)
, %(out1)
, … placeholders
can be used to access individual items in the list.
Perhaps a better would be to demonstrate how to use this to generate a grammar parser with Bison:
sources {
main.cpp
parser.ypp // Bison grammar file
parser.cpp parser.hpp // generated C++ parser
}
parser.ypp::compile-commands = "bison -o %(out0) %(in)"
parser.ypp::outputs = parser.cpp parser.hpp;
Language reference¶
Statements, blocks, literals etc.¶
Statements in Bakefile are separated by semicolon (;
) and code blocks are
marked up in with {
and }
, as in C. See an example:
toolsets = gnu vs2010;
program hello {
sources { hello.cpp }
}
In particular, expressions may span multiple lines without the need to escape newlines or enclose the expression in parenthesis:
os_files = foo.cpp
bar.cpp
;
Values, types and literals¶
Similarly to the make
syntax, quotes around literals are optional –
anything not a keyword or special character or otherwise specially marked is a
literal; specifically, a string literal.
Quoting is only needed when the literal contains whitespace or special
characters such as =
or quotes. Quoted strings are enclosed between "
(double quote) or '
(single quote) characters and may contain any
characters except for the quotes. Additionally, backslash (\
) can be used
inside quoted strings to escape any character. [1]
The two kinds of quoting differ:
- Double-quoted strings are interpolated. That is, variable references using
$(...)
(see below) are recognized and evaluated. If you want to use$
as a literal, you must escape it (\$
).- Single-quoted strings are literal,
$
doesn’t have any special meaning and is treated as any other character.
Values in Bakefile are typed: properties have types associated with them and only values that are valid for that type can be assigned to them. The language isn’t strongly-typed, though: conversions are performed whenever needed and possible, variables are untyped by default. Type checking primarily shows up when validating values assigned to properties.
The basic types are:
- Boolean properties can be assigned the result of a boolean expression or one of the
true
orfalse
literals.- Strings. Enough said.
- Lists are items delimited with whitespace. Lists are typed and the items must all be of the same type. In the reference documentation, list types are described as “list of string”, “list of path” etc.
- Paths are file or directory paths and are described in more detail in the next section.
- IDs are identifiers of targets.
- Enums are used for properties where only a few possible values exist; the property cannot be set to anything other than one of the listed strings.
AnyType
is the pseudo-type used for untyped variables or expressions with undetermined type.
Paths¶
File paths is a type that deserves more explanation. They are arguably the most important element in makefiles and project files both and any incorrectness in them would cause breakage.
All paths in bakefiles must be written using a notation similar to the Unix
one, using /
as the separator, and are always relative. By default, if you
don’t say otherwise and write the path as a normal Unix path (e.g.
src/main.cpp
), it’s relative to the source directory (or srcdir for
short). Srcdir is the implicitly assumed directory for the input files
specified using relative paths. By default, it is the directory containing the
bakefile itself but it can be changed as described below. Note that this may
be – and often is – different from the location where the generated output
files are written to.
This is usually the most convenient choice, but it’s sometimes not sufficient.
For such situations, Bakefile has the ability to anchor paths under a
different root. This is done by adding a prefix of the form of @<anchor>/
in front of the path. The following anchors are recognized:
@srcdir
, as described above.@top_srcdir
is the top level source directory, i.e. srcdir of the top-most bakefile of the project. This is only different from @srcdir if this bakefile was included from another one as a submodule.@builddir
is the directory where build files of the current target are placed. Note that this is not where the generated makefiles or projects go either. It’s often a dedicated directory just for the build artifacts and typically depends on make-time configuration. Visual Studio, for example, puts build files intoDebug/
andRelease/
subdirectories depending on the configuration selected.@builddir
points to these directories.
Here are some examples showing common uses for the anchors:
sources {
hello.cpp; // relative to srcdir
@builddir/generated_file.c;
}
includedirs += @top_srcdir/include;
Changing srcdir¶
As mentioned above, @srcdir
can be changed if its default value is
inconvenient, as, for example, is the case when the bakefile itself is in a
subdirectory of the source tree.
Take this for an example:
// build/bakefiles/foo.bkl
library foo {
includedirs += ../../include;
sources {
../../src/foo.cpp
../../src/bar.cpp
}
}
This can be made much nicer using scrdir
:
// build/bakefiles/foo.bkl
srcdir ../..;
library foo {
includedirs += include;
sources {
src/foo.cpp
src/bar.cpp
}
}
The srcdir
statement takes one argument, path to the new srcdir (relative
to the location of the bakefile). It affects all @srcdir
-anchored paths,
including implicitly anchored ones, i.e. those without any explicit anchor, in
the module (but not its submodules). Notably, (default) paths for generated
files are also affected, because these too are relative to @srcdir
.
Notice that because it affects the interpretation of all path expressions in
the file, it can only be used before any assignments, target definitions etc.
The only thing that can precede it is requires
.
Variables and properties¶
Bakefile allows you to set arbitrary variables on any part of the model. Additionally, there are properties, which are pre-defined variables with a set meaning. Syntactically, there’s no difference between the two. There’s semantical difference in that the properties are usually typed and only values compatible with their type can be assigned to them. For example, you cannot assign arbitrary string to a path property or overwrite a read-only property.
Setting variables¶
Variables don’t need to be declared; they are defined on first assignment. Assignment to variables is done in the usual way:
variable = value;
// Lists can be appended to, too:
main_sources = foo.cpp;
main_sources += bar.cpp third.cpp;
Occasionally, it is useful to set variables on other objects, not just in the current scope. For example, you may want to set per-file compilation flags, add custom build step for a particular source file or even modify a global variable. Bakefile uses operator :: for this purpose, with semantics reminiscent of C++: any number of scopes delimited by :: may precede the variable name, with leading :: indicating global (i.e. current module) scope. Here’s a simple example:
Referencing variables¶
Because literals aren’t quoted, variables are referenced using the make-like
$(<varname>)
syntax:
platform = windows;
sources { os/$(platform).cpp }
A shorthand form, where the brackets are omitted, is also allowed when such use is unambiguous: [2]
if ( $toolset == gnu ) { ... }
Note that the substitution isn’t done immediately. Instead, the reference is included in the object model of the bakefiles and is dereferenced at a later stage, when generating makefile and project files. Sometimes, they are kept in the generated files too.
This has two practical consequences:
It is possible to reference variables that are defined later in the bakefile without getting errors.
Definitions cannot be recursive, a variable must not reference itself. You cannot write this:
defines = $(defines) SOME_MOREUse operator
+=
instead:defines += SOME_MORE
Targets¶
Target definition consists of three things: the type of the target (an executable, a library etc.), its ID (the name, which usually corresponds to built file’s name, but doesn’t have to) and detailed specification of its properties:
type id {
property = value;
property = value;
...sources specification...
...more content...
}
(It’s a bit more complicated than that, the content may contain conditional statements too, but that’s the overall structure.)
Sources files¶
Source files are added to the target using the sources
keyword, followed by
the list of source files inside curly brackets. Note the sources list may
contain any valid expression; in particular, references to variables are
permitted.
It’s possible to have multiple sources
statements in the same target.
Another use of sources
appends the files to the list of sources, it doesn’t
overwrite it; the effect is the same as that of operator +=
.
See an example:
program hello {
sources {
hello.cpp
utils.cpp
}
// add some more sources later:
sources { $(EXTRA_SOURCES) }
}
Headers¶
Syntax for headers specification is identical to the one used for source files,
except that the headers
keyword is used instead. The difference between
sources and headers is that the latter may be used outside of the target (e.g.
a library installs headers that are then used by users of the library).
Templates¶
It is often useful to share common settings or even code among multiple
targets. This can be handled, to some degree, by setting properties such as
includedirs
globally, but more flexibility is often needed.
Bakefile provides a convenient way of doing just that: templates. A template is a named block of code that is applied and evaluated before target’s own body. In a way, it’s similar to C++ inheritance: targets correspond to derived classes and templates would be abstract base classes in this analogy.
Templates can be derived from another template; both targets and templates can be based on more than one template. They are applied in the order they are specified in, with base templates first and derived ones after them. Each template in the inheritance chain is applied exactly once, i.e. if a target uses the same template two or more times, its successive appearances are simply ignored.
Templates may contain any code that is valid inside target definition and may reference any variables defined in the target.
The syntax is similar to C++ inheritance syntax:
template common_stuff {
defines += BUILDING;
}
template with_logging : common_stuff {
defines += "LOGGING_ID=\"$(id)\"";
libs += logging;
}
program hello : with_logging {
sources {
hello.cpp
}
}
Or equivalently:
template common_stuff {
defines += BUILDING;
}
template with_logging {
defines += "LOGGING_ID=\"$(id)\"";
libs += logging;
}
program hello : common_stuff, with_logging {
sources {
hello.cpp
}
}
Conditional statements¶
Any part of a bakefile may be enclosed in a conditional if
statement.
The syntax is similar to C/C++’s one:
defines = BUILD;
if ( $(toolset) == gnu )
defines += LINUX;
In this example, the defines
list will contain two items, [BUILD,
LINUX]
when generating makefiles for the gnu
toolset and only one item,
BUILD
, for other toolsets.
The condition doesn’t have to be constant, it may reference e.g. options, where
the value isn’t known until make-time; Bakefile will correctly translate them into
generated code. [3]
A long form with curly brackets is accepted as well; unlike the short form, this one can contain more than one statement:
if ( $(toolset) == gnu ) {
defines += LINUX;
sources { os/linux.cpp }
}
Conditional statements may be nested, too:
if ( $(build_tests) ) {
program test {
sources { main.cpp }
if ( $(toolset) == gnu ) {
defines += LINUX;
sources { os/linux.cpp }
}
}
}
The expression that specifies the condition uses C-style boolean operators: &&
for and, ||
for or, !
for not and ==
and !=
for equality
and inequality tests respectively.
Build configurations¶
A feature common to many IDEs is support for different build configurations,
i.e. for building the same project using different compilation options.
Bakefile generates the two standard “Debug” and “Release” configurations by
default for the toolsets that usually use them (currently “vs*”) and also
supports the use of configurations with the makefile-based toolsets by
allowing to specify config=NameOfConfig
on make command line, e.g.
$ make config=Debug
# ... files are compiled with "-g" option and without optimizations ...
Notice that configuration names shouldn’t be case-sensitive as
config=debug
is handled in the same way as config=Debug
in make-based
toolsets.
In addition to these two standard configurations, it is also possible to define your own custom configurations, which is especially useful for the project files which can’t be customized as easily as the makefiles at build time.
Here is a step by step guide to doing this. First, you need to define the new configuration. This is done by using a configuration declaration in the global scope, i.e. outside of any target, e.g.:
configuration ExtraDebug : Debug {
}
The syntax for configuration definition is reminiscent of C++ class definition and, as could be expected, the identifier after the colon is the name of the base configuration. The new configuration inherits the variables defined in its base configuration.
Notice that all custom configurations must derive from another existing one, which can be either a standard “Debug” or “Release” configuration or a previously defined another custom configuration.
Defining a configuration doesn’t do anything on its own, it also needs to be
used by at least some targets. To do it, the custom configuration name must be
listed in an assignment to the special configurations
variable:
configurations = Debug ExtraDebug Release;
This statement can appear either in the global scope, like above, in which case it affects all the targets, or inside one or more targets, in which case the specified configuration is only used for these targets. So if you only wanted to enable extra debugging for “hello” executable you could do
program hello {
configurations = Debug ExtraDebug Release;
}
However even if the configuration is present in the generated project files after doing all this, it is still not very useful as no custom options are defined for it. To change this, you will usually also want to set some project options conditionally depending on the configuration being used, e.g.:
program hello {
if ( $(config) == ExtraDebug ) {
defines += EXTRA_DEBUG;
}
}
config
is a special variable automatically set by bakefile to the name of
the current configuration and may be used in conditional expressions as any
other variable.
For simple cases like the above, testing config
explicitly is usually all
you need but in more complex situations it might be preferable to define some
variables inside the configuration definition and then test these variables
instead. Here is a complete example doing the same thing as the above snippets
using this approach:
configuration ExtraDebug : Debug {
extra_debug = true;
}
configurations = Debug ExtraDebug Release;
program hello {
if ( $(extra_debug) ) {
defines += EXTRA_DEBUG;
}
}
Note
As mentioned above, it is often unnecessary (although still possible) to
define configurations for the makefile-based toolsets as it’s always
possible to just write make CPPFLAGS=-DEXTRA_DEBUG
instead of using an
“ExtraDebug” configuration from the example above with them. If you want to
avoid such unnnecessary configurations in your makefiles, you could define
them only conditionally, for example:
toolsets = gnu vs2010;
if ( $toolset == vs2010 && $config == ExtraDebug )
defines += EXTRA_DEBUG;
would work as before in Visual Studio but would generate a simpler makefile.
Build settings¶
Sometimes, configurability provided by configurations is not enough and more flexible settings are required; e.g. configurable paths to 3rdparty libraries, tools and so on. Bakefile handles this with settings: variable-like constructs that are, unlike Bakefile variables, preserved in the generated output and can be modified by the user at make-time.
Settings are part of the object model and as such have a name and additional properties that affect their behavior. Defining a setting is similar to defining a target:
setting JDK_HOME { help = "Path to the JDK"; default = /opt/jdk; }
Notice that the setting object has some properties. You will almost always want to set the two shown in the above example. help is used to explain the setting to the user and default provides the default value to use if the user of the makefile doesn’t specify anything else; both are optional. See Setting properties for the full list.
When you need to reference a setting, use the same syntax as when referencing variables:
includedirs += $(JDK_HOME)/include;
In fact, settings also act as variables defined at the highest (project) level. This means that they can be assigned to as well and some nice tricks are easily done:
setting LIBFOO_PATH { help = "Path to the Foo library"; default = /opt/libfoo; } // On Windows, just use our own copy: if ( $toolset == vs2010 ) LIBFOO_PATH = @top_srcdir/3rdparty/libfoo;
This removes the user setting for toolsets that don’t need it. Another handy use is to import some common code or use a submodule with configurable settings and just hard-code their values when you don’t need the flexibility.
Note
Settings are currently only fully supported by makefiles, they are always replaced with their default values in the project files.
Submodules¶
A bakefile file – a module – can include other modules as its children.
The submodule
keyword is used for that:
submodule samples/hello/hello.bkl;
submodule samples/advanced/adv.bkl;
They are useful for organizing larger projects into more manageable chunks, similarly to how makefiles are used with recursive make. The submodules get their own makefiles (automatically invoked from the parent module’s makefile) and a separate Visual Studio solution file is created for them by default as well. Typical uses include putting examples or tests into their own modules.
Submodules may only be included at the top level and cannot be included
conditionally (i.e. inside an if
statement).
Importing other files¶
There’s one more way to organize source bakefiles in addition to submodules:
direct import of another file’s content. The syntax is similar to submodules
one, using the import
keyword:
// define variables, templates etc:
import common-defs.bkl;
program myapp { ... }
Import doesn’t change the layout of output files, unlike submodule
.
Instead, it directly includes the content of the referenced file at the point
of import. Think of it as a variation on C’s #include
.
Imports help with organizing large bakefiles into more manageable files. You could, for example, put commonly used variables or templates, files lists etc. into their own reusable files.
Notice that there are some important differences to #include
:
- A file is only imported once in the current scope, further imports are ignored. Specifically:
- Second import of
foo.bkl
from the same module is ignored.- Import of
foo.bkl
from a submodule is ignored if it was already imported into its parent (or any of its ancestors).- If two sibling submodules both import
foo.bkl
and none of their ancestors does, then the file is imported into both. That’s because their local scopes are independent of each other, so it isn’t regarded as duplicate import.- An imported file may contain templates or configurations definitions and be included repeatedly (in the (1c) case above). This would normally result in errors, but Bakefile recognizes imported duplicates as identical and handles them gracefully.
The import
keyword can only be included at the top level and cannot be
done conditionally (i.e. inside an if
statement).
Version checking¶
If a bakefile depends on features (or even syntax) not available in older
versions, it is possible to declare this dependency using the requires
keyword.
// Feature XYZ was added in Bakefile 1.1:
requires 1.1;
This statement causes fatal error if Bakefile version is older than the specified one.
Loading plugins¶
Standard Bakefile plugins are loaded automatically. But sometimes a custom
plugin needed only for a specific project is needed and such plugins must be
loaded explicitly, using the plugin
keyword:
plugin my_compiler.py;
Its argument is a path to a valid Python file that will be loaded into the
bkl.plugins
module. You can also use full name of the module to make it
clear the file is a Bakefile plugin:
plugin bkl.plugins.my_compiler.py;
See the Writing Bakefile plugins chapter for more information about plugins.
Comments¶
Bakefile uses C-style comments, in both the single-line and multi-line variants. Single-line comments look like this:
// we only generate code for GNU format for now
toolsets = gnu;
Multi-line comments can span several lines:
/*
We only generate code for GNU format for now.
This will change later, when we add Visual C++ support.
*/
toolsets = gnu;
They can also be included in an expression:
program hello {
sources { hello.c /*main() impl*/ lib.c }
}
[1] | A string literal containing quotes can therefore be written as, say,
"VERSION=\"1.2\"" ; backslashes must be escaped as double backslashes
("\\" ). |
[2] | A typical example of ambiguous use is in a concatenation. You can’t
write $toolset.cpp because . is a valid part of a literal; it
must be written as $(toolset).cpp so that it’s clear which part is a
variable name and which is a literal appended to the reference. For
similar reasons, the shorthand form cannot be used in double-quoted strings. |
[3] | Although the syntax imposes few limits, it’s not always possible to generate makefiles or projects with complicated conditional content even though the syntax supports it. In that case, Bakefile will exit with an explanatory error message. |
Reference documentation¶
Global project properties¶
Properties¶
toolset (type: toolset)
The toolset makefiles or projects are being generated for. This property is set by Bakefile and can be used for performing toolset-specific tasks or modifications.
Read-only property
Allowed values: “gnu”, “gnu-osx”, “gnu-suncc”, “vs2003”, “vs2005”, “vs2008”, “vs2010”, “vs2012”, “vs2013”, “vs2015”, “vs2017”
Inheritable from parent: no
config (type: string)
Current configuration.
This property is set by Bakefile and can be used for performing per-configuration modifications. The value is one of the configurations values specified for the target.
See Build configurations for more information.
Read-only property
Inheritable from parent: no
arch (type: string)
Current architecture.
This property is set by Bakefile and can be used for performing per-architecture modifications (if the toolset supports it, which currently only Visual Studio does). The value is one of the archs values specified for the target.
Read-only property
Inheritable from parent: no
Module properties¶
Properties¶
toolsets (type: list of toolsets)
List of toolsets to generate makefiles/projects for.
Default: empty
Allowed values: “gnu”, “gnu-osx”, “gnu-suncc”, “vs2003”, “vs2005”, “vs2008”, “vs2010”, “vs2012”, “vs2013”, “vs2015”, “vs2017”
Inheritable from parent: yes
vs2008.solutionfile (type: path)
File name of the solution file for the module.
Only for toolsets: Visual Studio 2008 (vs2008)
Default: same name as the module’s bakefile, with
.sln
extension, in@srcdir
Inheritable from parent: no
vs2008.generate-solution (type: bool)
Whether to generate solution file for the module. Set tofalse
if you want to omit the solution, e.g. for some submodules with only a single target.Only for toolsets: Visual Studio 2008 (vs2008)
Default: True
Inheritable from parent: no
gnu.makefile (type: path)
Name of output file for module’s makefile.
Only for toolsets: GNU toolchain for Unix systems (gnu)
Default: GNUmakefile
Inheritable from parent: no
vs2005.solutionfile (type: path)
File name of the solution file for the module.
Only for toolsets: Visual Studio 2005 (vs2005)
Default: same name as the module’s bakefile, with
.sln
extension, in@srcdir
Inheritable from parent: no
vs2005.generate-solution (type: bool)
Whether to generate solution file for the module. Set tofalse
if you want to omit the solution, e.g. for some submodules with only a single target.Only for toolsets: Visual Studio 2005 (vs2005)
Default: True
Inheritable from parent: no
vs2017.solutionfile (type: path)
File name of the solution file for the module.
Only for toolsets: Visual Studio 2017 (vs2017)
Default: same name as the module’s bakefile, with
.sln
extension, in@srcdir
Inheritable from parent: no
vs2017.generate-solution (type: bool)
Whether to generate solution file for the module. Set tofalse
if you want to omit the solution, e.g. for some submodules with only a single target.Only for toolsets: Visual Studio 2017 (vs2017)
Default: True
Inheritable from parent: no
gnu-suncc.makefile (type: path)
Name of output file for module’s makefile.
Only for toolsets: GNU toolchain for Sun CC compiler (gnu-suncc)
Default: Makefile.suncc
Inheritable from parent: no
vs2015.solutionfile (type: path)
File name of the solution file for the module.
Only for toolsets: Visual Studio 2015 (vs2015)
Default: same name as the module’s bakefile, with
.sln
extension, in@srcdir
Inheritable from parent: no
vs2015.generate-solution (type: bool)
Whether to generate solution file for the module. Set tofalse
if you want to omit the solution, e.g. for some submodules with only a single target.Only for toolsets: Visual Studio 2015 (vs2015)
Default: True
Inheritable from parent: no
vs2012.solutionfile (type: path)
File name of the solution file for the module.
Only for toolsets: Visual Studio 2012 (vs2012)
Default: same name as the module’s bakefile, with
.sln
extension, in@srcdir
Inheritable from parent: no
vs2012.generate-solution (type: bool)
Whether to generate solution file for the module. Set tofalse
if you want to omit the solution, e.g. for some submodules with only a single target.Only for toolsets: Visual Studio 2012 (vs2012)
Default: True
Inheritable from parent: no
vs2013.solutionfile (type: path)
File name of the solution file for the module.
Only for toolsets: Visual Studio 2013 (vs2013)
Default: same name as the module’s bakefile, with
.sln
extension, in@srcdir
Inheritable from parent: no
vs2013.generate-solution (type: bool)
Whether to generate solution file for the module. Set tofalse
if you want to omit the solution, e.g. for some submodules with only a single target.Only for toolsets: Visual Studio 2013 (vs2013)
Default: True
Inheritable from parent: no
vs2003.solutionfile (type: path)
File name of the solution file for the module.
Only for toolsets: Visual Studio 2003 (vs2003)
Default: same name as the module’s bakefile, with
.sln
extension, in@srcdir
Inheritable from parent: no
vs2003.generate-solution (type: bool)
Whether to generate solution file for the module. Set tofalse
if you want to omit the solution, e.g. for some submodules with only a single target.Only for toolsets: Visual Studio 2003 (vs2003)
Default: True
Inheritable from parent: no
vs2010.solutionfile (type: path)
File name of the solution file for the module.
Only for toolsets: Visual Studio 2010 (vs2010)
Default: same name as the module’s bakefile, with
.sln
extension, in@srcdir
Inheritable from parent: no
vs2010.generate-solution (type: bool)
Whether to generate solution file for the module. Set tofalse
if you want to omit the solution, e.g. for some submodules with only a single target.Only for toolsets: Visual Studio 2010 (vs2010)
Default: True
Inheritable from parent: no
gnu-osx.makefile (type: path)
Name of output file for module’s makefile.
Only for toolsets: GNU toolchain for OS X (gnu-osx)
Default: Makefile.osx
Inheritable from parent: no
Setting properties¶
Properties¶
help (type: string)
Documentation for the setting. This will be used in the generated output to explain the setting to the user, if supported by the toolset.Default: null
Inheritable from parent: no
default (type: any)
Default value of the setting, if any.
Default: null
Inheritable from parent: no
Toolsets¶
GNU toolchain for Unix systems (gnu)¶
GNU toolchain for Unix systems.
This toolset generates makefiles for the GNU toolchain – GNU Make, GCC compiler, GNU LD linker etc. – running on Unix system.
Currently, only Linux systems (or something sufficiently compatible) are supported. In particular, file extensions and linker behavior (symlinks, sonames) are assumed to be Linux ones.
See GNU toolchain for OS X (gnu-osx) for OS X variant.
GNU toolchain for OS X (gnu-osx)¶
GNU toolchain for OS X.
This toolset is for building on OS X using makefiles, not Xcode. It incorporates some of the oddities of OS X’s toolchain and should be used instead of GNU toolchain for Unix systems (gnu).
GNU toolchain for Sun CC compiler (gnu-suncc)¶
GNU toolchain for Sun CC compiler.
This toolset is for building using the Sun CC (aka Oracle Studio) toolset.
Visual Studio 2003 (vs2003)¶
Visual Studio 2003.
Special properties¶
This toolset supports the same special properties that
Visual Studio 2008 (vs2008). The only difference is that they are prefixed
with vs2003.option.
instead of vs2008.option.
.
Properties¶
All targets¶
vs2003.projectfile (type: path)
File name of the project for the target.
Default:
$(id).vcxproj
in the same directory as the.sln
fileInheritable from parent: no
vs2003.guid (type: string)
GUID of the project.
Default: automatically generated
Inheritable from parent: no
Modules¶
vs2003.solutionfile (type: path)
File name of the solution file for the module.
Default: same name as the module’s bakefile, with
.sln
extension, in@srcdir
Inheritable from parent: no
vs2003.generate-solution (type: bool)
Whether to generate solution file for the module. Set tofalse
if you want to omit the solution, e.g. for some submodules with only a single target.Default: True
Inheritable from parent: no
Visual Studio 2005 (vs2005)¶
Visual Studio 2005.
Special properties¶
This toolset supports the same special properties that
Visual Studio 2008 (vs2008). The only difference is that they are prefixed
with vs2005.option.
instead of vs2008.option.
.
Properties¶
All targets¶
vs2005.projectfile (type: path)
File name of the project for the target.
Default:
$(id).vcxproj
in the same directory as the.sln
fileInheritable from parent: no
vs2005.guid (type: string)
GUID of the project.
Default: automatically generated
Inheritable from parent: no
Modules¶
vs2005.solutionfile (type: path)
File name of the solution file for the module.
Default: same name as the module’s bakefile, with
.sln
extension, in@srcdir
Inheritable from parent: no
vs2005.generate-solution (type: bool)
Whether to generate solution file for the module. Set tofalse
if you want to omit the solution, e.g. for some submodules with only a single target.Default: True
Inheritable from parent: no
Visual Studio 2008 (vs2008)¶
Visual Studio 2008.
Special properties¶
In addition to the properties described below, it’s possible to specify any
of the vcproj
properties directly in a bakefile. To do so, you have to
set specially named variables on the target.
The variables are prefixed with vs2008.option.
, followed by tool name and
attribute name. For example:
vs2008.option.VCCLCompilerTool.EnableFunctionLevelLinking
vs2008.option.VCLinkerTool.EnableCOMDATFolding
Additionally, the following are supported for non-tool nodes:
vs2008.option.*
(attributes of the rootVisualStudioProject
node)vs2008.option.Configuration.*
(Configuration
node attributes)
These variables can be used in several places in bakefiles:
- In targets, to applied them as project’s global settings.
- In modules, to apply them to all projects in the module and its submodules.
- On per-file basis, to modify file-specific settings.
Examples:
vs2008.option.VCCLCompilerTool.EnableFunctionLevelLinking = false;
crashrpt.cpp::vs2008.option.VCCLCompilerTool.ExceptionHandling = 2;
Properties¶
All targets¶
vs2008.projectfile (type: path)
File name of the project for the target.
Default:
$(id).vcxproj
in the same directory as the.sln
fileInheritable from parent: no
vs2008.guid (type: string)
GUID of the project.
Default: automatically generated
Inheritable from parent: no
Modules¶
vs2008.solutionfile (type: path)
File name of the solution file for the module.
Default: same name as the module’s bakefile, with
.sln
extension, in@srcdir
Inheritable from parent: no
vs2008.generate-solution (type: bool)
Whether to generate solution file for the module. Set tofalse
if you want to omit the solution, e.g. for some submodules with only a single target.Default: True
Inheritable from parent: no
Visual Studio 2010 (vs2010)¶
Visual Studio 2010.
Special properties¶
In addition to the properties described below, it’s possible to specify any
of the vcxproj
properties directly in a bakefile. To do so, you have to
set specially named variables on the target.
The variables are prefixed with vs2010.option.
, followed by node name and
property name. The following nodes are supported:
vs2010.option.Globals.*
vs2010.option.Configuration.*
vs2010.option.*
(this is the unnamedPropertyGroup
with global settings such asTargetName
)vs2010.option.ClCompile.*
vs2010.option.ResourceCompile.*
vs2010.option.Link.*
vs2010.option.Lib.*
vs2010.option.Manifest.*
These variables can be used in several places in bakefiles:
- In targets, to applied them as project’s global settings.
- In modules, to apply them to all projects in the module and its submodules.
- On per-file basis, to modify file-specific settings.
Examples:
vs2010.option.GenerateManifest = false;
vs2010.option.Link.CreateHotPatchableImage = Enabled;
crashrpt.cpp::vs2010.option.ClCompile.ExceptionHandling = Async;
Properties¶
All targets¶
vs2010.projectfile (type: path)
File name of the project for the target.
Default:
$(id).vcxproj
in the same directory as the.sln
fileInheritable from parent: no
vs2010.guid (type: string)
GUID of the project.
Default: automatically generated
Inheritable from parent: no
Modules¶
vs2010.solutionfile (type: path)
File name of the solution file for the module.
Default: same name as the module’s bakefile, with
.sln
extension, in@srcdir
Inheritable from parent: no
vs2010.generate-solution (type: bool)
Whether to generate solution file for the module. Set tofalse
if you want to omit the solution, e.g. for some submodules with only a single target.Default: True
Inheritable from parent: no
Visual Studio 2012 (vs2012)¶
Visual Studio 2012.
Special properties¶
This toolset supports the same special properties that
Visual Studio 2010 (vs2010). The only difference is that they are prefixed
with vs2012.option.
instead of vs2010.option.
, i.e. the nodes are:
vs2012.option.Globals.*
vs2012.option.Configuration.*
vs2012.option.*
(this is the unnamedPropertyGroup
with global settings such asTargetName
)vs2012.option.ClCompile.*
vs2012.option.ResourceCompile.*
vs2012.option.Link.*
vs2012.option.Lib.*
vs2012.option.Manifest.*
Properties¶
All targets¶
vs2012.projectfile (type: path)
File name of the project for the target.
Default:
$(id).vcxproj
in the same directory as the.sln
fileInheritable from parent: no
vs2012.guid (type: string)
GUID of the project.
Default: automatically generated
Inheritable from parent: no
Modules¶
vs2012.solutionfile (type: path)
File name of the solution file for the module.
Default: same name as the module’s bakefile, with
.sln
extension, in@srcdir
Inheritable from parent: no
vs2012.generate-solution (type: bool)
Whether to generate solution file for the module. Set tofalse
if you want to omit the solution, e.g. for some submodules with only a single target.Default: True
Inheritable from parent: no
Visual Studio 2013 (vs2013)¶
Visual Studio 2013.
Special properties¶
This toolset supports the same special properties that
Visual Studio 2010 (vs2010). The only difference is that they are prefixed
with vs2013.option.
instead of vs2010.option.
, i.e. the nodes are:
vs2013.option.Globals.*
vs2013.option.Configuration.*
vs2013.option.*
(this is the unnamedPropertyGroup
with global settings such asTargetName
)vs2013.option.ClCompile.*
vs2013.option.ResourceCompile.*
vs2013.option.Link.*
vs2013.option.Lib.*
vs2013.option.Manifest.*
Properties¶
All targets¶
vs2013.projectfile (type: path)
File name of the project for the target.
Default:
$(id).vcxproj
in the same directory as the.sln
fileInheritable from parent: no
vs2013.guid (type: string)
GUID of the project.
Default: automatically generated
Inheritable from parent: no
Modules¶
vs2013.solutionfile (type: path)
File name of the solution file for the module.
Default: same name as the module’s bakefile, with
.sln
extension, in@srcdir
Inheritable from parent: no
vs2013.generate-solution (type: bool)
Whether to generate solution file for the module. Set tofalse
if you want to omit the solution, e.g. for some submodules with only a single target.Default: True
Inheritable from parent: no
Visual Studio 2015 (vs2015)¶
Visual Studio 2015.
Special properties¶
This toolset supports the same special properties that
Visual Studio 2010 (vs2010). The only difference is that they are prefixed
with vs2015.option.
instead of vs2010.option.
, i.e. the nodes are:
vs2015.option.Globals.*
vs2015.option.Configuration.*
vs2015.option.*
(this is the unnamedPropertyGroup
with global settings such asTargetName
)vs2015.option.ClCompile.*
vs2015.option.ResourceCompile.*
vs2015.option.Link.*
vs2015.option.Lib.*
vs2015.option.Manifest.*
Properties¶
All targets¶
vs2015.projectfile (type: path)
File name of the project for the target.
Default:
$(id).vcxproj
in the same directory as the.sln
fileInheritable from parent: no
vs2015.guid (type: string)
GUID of the project.
Default: automatically generated
Inheritable from parent: no
Modules¶
vs2015.solutionfile (type: path)
File name of the solution file for the module.
Default: same name as the module’s bakefile, with
.sln
extension, in@srcdir
Inheritable from parent: no
vs2015.generate-solution (type: bool)
Whether to generate solution file for the module. Set tofalse
if you want to omit the solution, e.g. for some submodules with only a single target.Default: True
Inheritable from parent: no
Visual Studio 2017 (vs2017)¶
Visual Studio 2017.
Special properties¶
This toolset supports the same special properties that
Visual Studio 2010 (vs2010). The only difference is that they are prefixed
with vs2017.option.
instead of vs2010.option.
, i.e. the nodes are:
vs2017.option.Globals.*
vs2017.option.Configuration.*
vs2017.option.*
(this is the unnamedPropertyGroup
with global settings such asTargetName
)vs2017.option.ClCompile.*
vs2017.option.ResourceCompile.*
vs2017.option.Link.*
vs2017.option.Lib.*
vs2017.option.Manifest.*
Properties¶
All targets¶
vs2017.projectfile (type: path)
File name of the project for the target.
Default:
$(id).vcxproj
in the same directory as the.sln
fileInheritable from parent: no
vs2017.guid (type: string)
GUID of the project.
Default: automatically generated
Inheritable from parent: no
Modules¶
vs2017.solutionfile (type: path)
File name of the solution file for the module.
Default: same name as the module’s bakefile, with
.sln
extension, in@srcdir
Inheritable from parent: no
vs2017.generate-solution (type: bool)
Whether to generate solution file for the module. Set tofalse
if you want to omit the solution, e.g. for some submodules with only a single target.Default: True
Inheritable from parent: no
Targets¶
Custom action script (action)¶
Custom action script.
Action targets execute arbitrary commands. They can be used to do various tasks that don’t fit the model of compiling or creating files, such as packaging files, installing, uploading, running tests and so on.
Actions are currently only supported by makefile-based toolsets. See the
pre-build-commands
and post-build-commands
properties for another
alternative that is supported by Visual Studio projects.
If the optional outputs
property is specified, the action is supposed
to generate the files listed in this property. This means that other
targets depending on this action will depend on these files in the
generated makefile, instead of depending on the phony target for an action
without outputs and also that these files will be cleaned up by the
clean
target of the generated makefile.
action osx-bundle
{
deps = test;
commands = "mkdir -p Test.app/Contents/MacOS"
"cp -f test Test.app/Contents/MacOS/test"
;
}
Properties¶
commands (type: list of strings)
List of commands to run.
Default: empty
Inheritable from parent: no
outputs (type: list of paths)
Output files created by this action, if any.
Default: null
Inheritable from parent: no
id (type: id)
Target’s unique name (ID).
Read-only property
Inheritable from parent: no
deps (type: list of ids)
Dependencies of the target (list of IDs).
The dependencies are handled in target-specific ways. At the very least, they are added to the list of dependencies in generated makefiles or projects to ensure correct build order. Some targets may be smart about some kinds of the dependencies and do more.
In particular, compiled targets (executables, DLLs) will automatically link against all libraries found in deps.
Default: empty
Inheritable from parent: no
pre-build-commands (type: list of strings)
Custom commands to run before building the target.
The value is a list of shell commands to run. Notice that the commands are platform-specific and so typically need to be set conditionally depending on the value of
toolset
.Currently only implemented by Visual Studio.
Default: empty
Inheritable from parent: no
post-build-commands (type: list of strings)
Custom commands to run after building the target.
The value is a list of shell commands to run. Notice that the commands are platform-specific and so typically need to be set conditionally depending on the value of
toolset
.Currently only implemented by Visual Studio.
Default: empty
Inheritable from parent: no
configurations (type: list of strings)
List of configurations to use for this target.
See Build configurations for more information.
Default: Debug Release
Inheritable from parent: yes
vs2008.projectfile (type: path)
File name of the project for the target.
Only for toolsets: Visual Studio 2008 (vs2008)
Default:
$(id).vcxproj
in the same directory as the.sln
fileInheritable from parent: no
vs2008.guid (type: string)
GUID of the project.
Only for toolsets: Visual Studio 2008 (vs2008)
Default: automatically generated
Inheritable from parent: no
vs2005.projectfile (type: path)
File name of the project for the target.
Only for toolsets: Visual Studio 2005 (vs2005)
Default:
$(id).vcxproj
in the same directory as the.sln
fileInheritable from parent: no
vs2005.guid (type: string)
GUID of the project.
Only for toolsets: Visual Studio 2005 (vs2005)
Default: automatically generated
Inheritable from parent: no
vs2017.projectfile (type: path)
File name of the project for the target.
Only for toolsets: Visual Studio 2017 (vs2017)
Default:
$(id).vcxproj
in the same directory as the.sln
fileInheritable from parent: no
vs2017.guid (type: string)
GUID of the project.
Only for toolsets: Visual Studio 2017 (vs2017)
Default: automatically generated
Inheritable from parent: no
vs2015.projectfile (type: path)
File name of the project for the target.
Only for toolsets: Visual Studio 2015 (vs2015)
Default:
$(id).vcxproj
in the same directory as the.sln
fileInheritable from parent: no
vs2015.guid (type: string)
GUID of the project.
Only for toolsets: Visual Studio 2015 (vs2015)
Default: automatically generated
Inheritable from parent: no
vs2012.projectfile (type: path)
File name of the project for the target.
Only for toolsets: Visual Studio 2012 (vs2012)
Default:
$(id).vcxproj
in the same directory as the.sln
fileInheritable from parent: no
vs2012.guid (type: string)
GUID of the project.
Only for toolsets: Visual Studio 2012 (vs2012)
Default: automatically generated
Inheritable from parent: no
vs2013.projectfile (type: path)
File name of the project for the target.
Only for toolsets: Visual Studio 2013 (vs2013)
Default:
$(id).vcxproj
in the same directory as the.sln
fileInheritable from parent: no
vs2013.guid (type: string)
GUID of the project.
Only for toolsets: Visual Studio 2013 (vs2013)
Default: automatically generated
Inheritable from parent: no
vs2003.projectfile (type: path)
File name of the project for the target.
Only for toolsets: Visual Studio 2003 (vs2003)
Default:
$(id).vcxproj
in the same directory as the.sln
fileInheritable from parent: no
vs2003.guid (type: string)
GUID of the project.
Only for toolsets: Visual Studio 2003 (vs2003)
Default: automatically generated
Inheritable from parent: no
vs2010.projectfile (type: path)
File name of the project for the target.
Only for toolsets: Visual Studio 2010 (vs2010)
Default:
$(id).vcxproj
in the same directory as the.sln
fileInheritable from parent: no
vs2010.guid (type: string)
GUID of the project.
Only for toolsets: Visual Studio 2010 (vs2010)
Default: automatically generated
Inheritable from parent: no
External build system (external)¶
External build system.
This target type is used to invoke makefiles or project files not implemented in Bakefile, for example to build 3rd party libraries.
Currently, only Visual Studio projects (vcproj, vcxproj, csproj) are supported and only when using a Visual Studio toolset.
Properties¶
file (type: path)
File name of the external makefile or project.
Required property
Inheritable from parent: no
id (type: id)
Target’s unique name (ID).
Read-only property
Inheritable from parent: no
deps (type: list of ids)
Dependencies of the target (list of IDs).
The dependencies are handled in target-specific ways. At the very least, they are added to the list of dependencies in generated makefiles or projects to ensure correct build order. Some targets may be smart about some kinds of the dependencies and do more.
In particular, compiled targets (executables, DLLs) will automatically link against all libraries found in deps.
Default: empty
Inheritable from parent: no
pre-build-commands (type: list of strings)
Custom commands to run before building the target.
The value is a list of shell commands to run. Notice that the commands are platform-specific and so typically need to be set conditionally depending on the value of
toolset
.Currently only implemented by Visual Studio.
Default: empty
Inheritable from parent: no
post-build-commands (type: list of strings)
Custom commands to run after building the target.
The value is a list of shell commands to run. Notice that the commands are platform-specific and so typically need to be set conditionally depending on the value of
toolset
.Currently only implemented by Visual Studio.
Default: empty
Inheritable from parent: no
configurations (type: list of strings)
List of configurations to use for this target.
See Build configurations for more information.
Default: Debug Release
Inheritable from parent: yes
vs2008.projectfile (type: path)
File name of the project for the target.
Only for toolsets: Visual Studio 2008 (vs2008)
Default:
$(id).vcxproj
in the same directory as the.sln
fileInheritable from parent: no
vs2008.guid (type: string)
GUID of the project.
Only for toolsets: Visual Studio 2008 (vs2008)
Default: automatically generated
Inheritable from parent: no
vs2005.projectfile (type: path)
File name of the project for the target.
Only for toolsets: Visual Studio 2005 (vs2005)
Default:
$(id).vcxproj
in the same directory as the.sln
fileInheritable from parent: no
vs2005.guid (type: string)
GUID of the project.
Only for toolsets: Visual Studio 2005 (vs2005)
Default: automatically generated
Inheritable from parent: no
vs2017.projectfile (type: path)
File name of the project for the target.
Only for toolsets: Visual Studio 2017 (vs2017)
Default:
$(id).vcxproj
in the same directory as the.sln
fileInheritable from parent: no
vs2017.guid (type: string)
GUID of the project.
Only for toolsets: Visual Studio 2017 (vs2017)
Default: automatically generated
Inheritable from parent: no
vs2015.projectfile (type: path)
File name of the project for the target.
Only for toolsets: Visual Studio 2015 (vs2015)
Default:
$(id).vcxproj
in the same directory as the.sln
fileInheritable from parent: no
vs2015.guid (type: string)
GUID of the project.
Only for toolsets: Visual Studio 2015 (vs2015)
Default: automatically generated
Inheritable from parent: no
vs2012.projectfile (type: path)
File name of the project for the target.
Only for toolsets: Visual Studio 2012 (vs2012)
Default:
$(id).vcxproj
in the same directory as the.sln
fileInheritable from parent: no
vs2012.guid (type: string)
GUID of the project.
Only for toolsets: Visual Studio 2012 (vs2012)
Default: automatically generated
Inheritable from parent: no
vs2013.projectfile (type: path)
File name of the project for the target.
Only for toolsets: Visual Studio 2013 (vs2013)
Default:
$(id).vcxproj
in the same directory as the.sln
fileInheritable from parent: no
vs2013.guid (type: string)
GUID of the project.
Only for toolsets: Visual Studio 2013 (vs2013)
Default: automatically generated
Inheritable from parent: no
vs2003.projectfile (type: path)
File name of the project for the target.
Only for toolsets: Visual Studio 2003 (vs2003)
Default:
$(id).vcxproj
in the same directory as the.sln
fileInheritable from parent: no
vs2003.guid (type: string)
GUID of the project.
Only for toolsets: Visual Studio 2003 (vs2003)
Default: automatically generated
Inheritable from parent: no
vs2010.projectfile (type: path)
File name of the project for the target.
Only for toolsets: Visual Studio 2010 (vs2010)
Default:
$(id).vcxproj
in the same directory as the.sln
fileInheritable from parent: no
vs2010.guid (type: string)
GUID of the project.
Only for toolsets: Visual Studio 2010 (vs2010)
Default: automatically generated
Inheritable from parent: no
Static library (library)¶
Static library.
Properties¶
basename (type: string)
Library name.
This is not full filename or even path, it’s only its base part, to which platform-specific prefix (if applicable) and extension are added. By default, it’s the same as target’s ID, but it can be changed e.g. if the filename should contain version number, which would be impractical to use as target identifier in the bakefile.
library foo { // use e.g. libfoo24.a on Unix and foo24.lib basename = foo$(vermajor)$(verminor); }Default: $(id)
Inheritable from parent: no
sources (type: list of paths)
Source files.
Default: empty
Inheritable from parent: no
headers (type: list of paths)
Header files.
Default: empty
Inheritable from parent: no
defines (type: list of strings)
List of preprocessor macros to define.
Default: empty
Inheritable from parent: yes
includedirs (type: list of paths)
Directories where to look for header files.
Default: empty
Inheritable from parent: yes
warnings (type: warnings)
Warning level for the compiler.
Use
no
to completely disable warning,minimal
to show only the most important warning messages,all
to enable all warnings that usually don’t result in false positives andmax
to enable absolutely all warnings.Default: default
Allowed values: “no”, “minimal”, “default”, “all”, “max”
Inheritable from parent: yes
compiler-options (type: list of strings)
Additional compiler options common to all C-like compilers (C, C++, Objective-C, Objective-C++).
Note that the options are compiler-specific and so this property should only be set conditionally for particular compilers that recognize the options.
Default: empty
Inheritable from parent: yes
c-compiler-options (type: list of strings)
Additional options for C compiler.
Note that the options are compiler-specific and so this property should only be set conditionally for particular compilers that recognize the options.
Default: empty
Inheritable from parent: yes
cxx-compiler-options (type: list of strings)
Additional options for C++ compiler.
Note that the options are compiler-specific and so this property should only be set conditionally for particular compilers that recognize the options.
Default: empty
Inheritable from parent: yes
libs (type: list of strings)
Additional libraries to link with.
Do not use this property to link with libraries built as part of your project; use deps for that.
When this list is non-empty on a Static library (library), it will be used when linking executables that use the library.
Default: empty
Inheritable from parent: yes
libdirs (type: list of paths)
Additional directories where to look for libraries.
When this list is non-empty on a Static library (library), it will be used when linking executables that use the library.
Default: empty
Inheritable from parent: yes
link-options (type: list of strings)
Additional linker options.
Note that the options are compiler/linker-specific and so this property should only be set conditionally for particular compilers that recognize the options.
When this list is non-empty on a Static library (library), it will be used when linking executables that use the library.
Default: empty
Inheritable from parent: yes
archs (type: list of architectures)
Architectures to compile for.
Adds support for building binaries for specified architectures, if supported by the toolset. Support may take the form of either multi-arch binaries (OS X) or additional build configurations (Visual Studio).
The default empty value means to do whatever the default behavior of the toolset is.
Currently only supported on OS X and in Visual Studio.
Default: null
Allowed values: “x86”, “x86_64”
Inheritable from parent: yes
win32-crt-linkage (type: linkage)
How to link against the C Runtime Library.
If
dll
(the default), the executable may depend on some DLLs provided by the compiler. Ifstatic
then a static version of the CRT is linked directly into the executable.Default: dll
Allowed values: “static”, “dll”
Inheritable from parent: yes
win32-unicode (type: bool)
Compile win32 code in Unicode mode? If enabled,
_UNICODE
symbol is defined and the wide character entry point (WinMain
, …) is used.Default: True
Inheritable from parent: yes
outputdir (type: path)
Directory where final binaries are put.
Note that this is not the directory for intermediate files such as object files – these are put in
@builddir
. By default, output location is the same,@builddir
, but can be overwritten to for example put all executables intobin/
subdirectory.Default: @builddir/
Inheritable from parent: yes
pic (type: bool)
Compile position-independent code.
By default, libraries (both shared and static, because the latter could be linked into a shared lib too) are linked with -fPIC and executables are not.
Default: None
Inheritable from parent: yes
multithreading (type: bool)
Enable support for multithreading.
MT support is enabled by default, but can be disabled when not needed.
On Unix, this option causes the use of pthreads library. Visual Studio always uses MT-safe CRT, even if this setting is disabled.
Default: True
Inheritable from parent: yes
id (type: id)
Target’s unique name (ID).
Read-only property
Inheritable from parent: no
deps (type: list of ids)
Dependencies of the target (list of IDs).
The dependencies are handled in target-specific ways. At the very least, they are added to the list of dependencies in generated makefiles or projects to ensure correct build order. Some targets may be smart about some kinds of the dependencies and do more.
In particular, compiled targets (executables, DLLs) will automatically link against all libraries found in deps.
Default: empty
Inheritable from parent: no
pre-build-commands (type: list of strings)
Custom commands to run before building the target.
The value is a list of shell commands to run. Notice that the commands are platform-specific and so typically need to be set conditionally depending on the value of
toolset
.Currently only implemented by Visual Studio.
Default: empty
Inheritable from parent: no
post-build-commands (type: list of strings)
Custom commands to run after building the target.
The value is a list of shell commands to run. Notice that the commands are platform-specific and so typically need to be set conditionally depending on the value of
toolset
.Currently only implemented by Visual Studio.
Default: empty
Inheritable from parent: no
configurations (type: list of strings)
List of configurations to use for this target.
See Build configurations for more information.
Default: Debug Release
Inheritable from parent: yes
vs2008.projectfile (type: path)
File name of the project for the target.
Only for toolsets: Visual Studio 2008 (vs2008)
Default:
$(id).vcxproj
in the same directory as the.sln
fileInheritable from parent: no
vs2008.guid (type: string)
GUID of the project.
Only for toolsets: Visual Studio 2008 (vs2008)
Default: automatically generated
Inheritable from parent: no
vs2005.projectfile (type: path)
File name of the project for the target.
Only for toolsets: Visual Studio 2005 (vs2005)
Default:
$(id).vcxproj
in the same directory as the.sln
fileInheritable from parent: no
vs2005.guid (type: string)
GUID of the project.
Only for toolsets: Visual Studio 2005 (vs2005)
Default: automatically generated
Inheritable from parent: no
vs2017.projectfile (type: path)
File name of the project for the target.
Only for toolsets: Visual Studio 2017 (vs2017)
Default:
$(id).vcxproj
in the same directory as the.sln
fileInheritable from parent: no
vs2017.guid (type: string)
GUID of the project.
Only for toolsets: Visual Studio 2017 (vs2017)
Default: automatically generated
Inheritable from parent: no
vs2015.projectfile (type: path)
File name of the project for the target.
Only for toolsets: Visual Studio 2015 (vs2015)
Default:
$(id).vcxproj
in the same directory as the.sln
fileInheritable from parent: no
vs2015.guid (type: string)
GUID of the project.
Only for toolsets: Visual Studio 2015 (vs2015)
Default: automatically generated
Inheritable from parent: no
vs2012.projectfile (type: path)
File name of the project for the target.
Only for toolsets: Visual Studio 2012 (vs2012)
Default:
$(id).vcxproj
in the same directory as the.sln
fileInheritable from parent: no
vs2012.guid (type: string)
GUID of the project.
Only for toolsets: Visual Studio 2012 (vs2012)
Default: automatically generated
Inheritable from parent: no
vs2013.projectfile (type: path)
File name of the project for the target.
Only for toolsets: Visual Studio 2013 (vs2013)
Default:
$(id).vcxproj
in the same directory as the.sln
fileInheritable from parent: no
vs2013.guid (type: string)
GUID of the project.
Only for toolsets: Visual Studio 2013 (vs2013)
Default: automatically generated
Inheritable from parent: no
vs2003.projectfile (type: path)
File name of the project for the target.
Only for toolsets: Visual Studio 2003 (vs2003)
Default:
$(id).vcxproj
in the same directory as the.sln
fileInheritable from parent: no
vs2003.guid (type: string)
GUID of the project.
Only for toolsets: Visual Studio 2003 (vs2003)
Default: automatically generated
Inheritable from parent: no
vs2010.projectfile (type: path)
File name of the project for the target.
Only for toolsets: Visual Studio 2010 (vs2010)
Default:
$(id).vcxproj
in the same directory as the.sln
fileInheritable from parent: no
vs2010.guid (type: string)
GUID of the project.
Only for toolsets: Visual Studio 2010 (vs2010)
Default: automatically generated
Inheritable from parent: no
Runtime-loaded dynamic module (plugin) (loadable-module)¶
Runtime-loaded dynamic module (plugin).
Properties¶
basename (type: string)
Base name of the loadable module.
This is not full filename or even path, it’s only its base part, to which platform-specific prefix and/or extension are added. By default, it’s the same as target’s ID, but it can be changed e.g. if the filename should contain version number, which would be impractical to use as target identifier in the bakefile.
loadable-module myplugin { basename = myplugin-v1; }Default: $(id)
Inheritable from parent: no
extension (type: string)
File extension of the module, including the leading dot.
By default, native extension for shared libraries (e.g. “.dll” on Windows) is used.
loadable-module excel_plugin { extension = .xll; }Default: null
Inheritable from parent: no
sources (type: list of paths)
Source files.
Default: empty
Inheritable from parent: no
headers (type: list of paths)
Header files.
Default: empty
Inheritable from parent: no
defines (type: list of strings)
List of preprocessor macros to define.
Default: empty
Inheritable from parent: yes
includedirs (type: list of paths)
Directories where to look for header files.
Default: empty
Inheritable from parent: yes
warnings (type: warnings)
Warning level for the compiler.
Use
no
to completely disable warning,minimal
to show only the most important warning messages,all
to enable all warnings that usually don’t result in false positives andmax
to enable absolutely all warnings.Default: default
Allowed values: “no”, “minimal”, “default”, “all”, “max”
Inheritable from parent: yes
compiler-options (type: list of strings)
Additional compiler options common to all C-like compilers (C, C++, Objective-C, Objective-C++).
Note that the options are compiler-specific and so this property should only be set conditionally for particular compilers that recognize the options.
Default: empty
Inheritable from parent: yes
c-compiler-options (type: list of strings)
Additional options for C compiler.
Note that the options are compiler-specific and so this property should only be set conditionally for particular compilers that recognize the options.
Default: empty
Inheritable from parent: yes
cxx-compiler-options (type: list of strings)
Additional options for C++ compiler.
Note that the options are compiler-specific and so this property should only be set conditionally for particular compilers that recognize the options.
Default: empty
Inheritable from parent: yes
libs (type: list of strings)
Additional libraries to link with.
Do not use this property to link with libraries built as part of your project; use deps for that.
When this list is non-empty on a Static library (library), it will be used when linking executables that use the library.
Default: empty
Inheritable from parent: yes
libdirs (type: list of paths)
Additional directories where to look for libraries.
When this list is non-empty on a Static library (library), it will be used when linking executables that use the library.
Default: empty
Inheritable from parent: yes
link-options (type: list of strings)
Additional linker options.
Note that the options are compiler/linker-specific and so this property should only be set conditionally for particular compilers that recognize the options.
When this list is non-empty on a Static library (library), it will be used when linking executables that use the library.
Default: empty
Inheritable from parent: yes
archs (type: list of architectures)
Architectures to compile for.
Adds support for building binaries for specified architectures, if supported by the toolset. Support may take the form of either multi-arch binaries (OS X) or additional build configurations (Visual Studio).
The default empty value means to do whatever the default behavior of the toolset is.
Currently only supported on OS X and in Visual Studio.
Default: null
Allowed values: “x86”, “x86_64”
Inheritable from parent: yes
win32-crt-linkage (type: linkage)
How to link against the C Runtime Library.
If
dll
(the default), the executable may depend on some DLLs provided by the compiler. Ifstatic
then a static version of the CRT is linked directly into the executable.Default: dll
Allowed values: “static”, “dll”
Inheritable from parent: yes
win32-unicode (type: bool)
Compile win32 code in Unicode mode? If enabled,
_UNICODE
symbol is defined and the wide character entry point (WinMain
, …) is used.Default: True
Inheritable from parent: yes
outputdir (type: path)
Directory where final binaries are put.
Note that this is not the directory for intermediate files such as object files – these are put in
@builddir
. By default, output location is the same,@builddir
, but can be overwritten to for example put all executables intobin/
subdirectory.Default: @builddir/
Inheritable from parent: yes
pic (type: bool)
Compile position-independent code.
By default, libraries (both shared and static, because the latter could be linked into a shared lib too) are linked with -fPIC and executables are not.
Default: None
Inheritable from parent: yes
multithreading (type: bool)
Enable support for multithreading.
MT support is enabled by default, but can be disabled when not needed.
On Unix, this option causes the use of pthreads library. Visual Studio always uses MT-safe CRT, even if this setting is disabled.
Default: True
Inheritable from parent: yes
id (type: id)
Target’s unique name (ID).
Read-only property
Inheritable from parent: no
deps (type: list of ids)
Dependencies of the target (list of IDs).
The dependencies are handled in target-specific ways. At the very least, they are added to the list of dependencies in generated makefiles or projects to ensure correct build order. Some targets may be smart about some kinds of the dependencies and do more.
In particular, compiled targets (executables, DLLs) will automatically link against all libraries found in deps.
Default: empty
Inheritable from parent: no
pre-build-commands (type: list of strings)
Custom commands to run before building the target.
The value is a list of shell commands to run. Notice that the commands are platform-specific and so typically need to be set conditionally depending on the value of
toolset
.Currently only implemented by Visual Studio.
Default: empty
Inheritable from parent: no
post-build-commands (type: list of strings)
Custom commands to run after building the target.
The value is a list of shell commands to run. Notice that the commands are platform-specific and so typically need to be set conditionally depending on the value of
toolset
.Currently only implemented by Visual Studio.
Default: empty
Inheritable from parent: no
configurations (type: list of strings)
List of configurations to use for this target.
See Build configurations for more information.
Default: Debug Release
Inheritable from parent: yes
vs2008.projectfile (type: path)
File name of the project for the target.
Only for toolsets: Visual Studio 2008 (vs2008)
Default:
$(id).vcxproj
in the same directory as the.sln
fileInheritable from parent: no
vs2008.guid (type: string)
GUID of the project.
Only for toolsets: Visual Studio 2008 (vs2008)
Default: automatically generated
Inheritable from parent: no
vs2005.projectfile (type: path)
File name of the project for the target.
Only for toolsets: Visual Studio 2005 (vs2005)
Default:
$(id).vcxproj
in the same directory as the.sln
fileInheritable from parent: no
vs2005.guid (type: string)
GUID of the project.
Only for toolsets: Visual Studio 2005 (vs2005)
Default: automatically generated
Inheritable from parent: no
vs2017.projectfile (type: path)
File name of the project for the target.
Only for toolsets: Visual Studio 2017 (vs2017)
Default:
$(id).vcxproj
in the same directory as the.sln
fileInheritable from parent: no
vs2017.guid (type: string)
GUID of the project.
Only for toolsets: Visual Studio 2017 (vs2017)
Default: automatically generated
Inheritable from parent: no
vs2015.projectfile (type: path)
File name of the project for the target.
Only for toolsets: Visual Studio 2015 (vs2015)
Default:
$(id).vcxproj
in the same directory as the.sln
fileInheritable from parent: no
vs2015.guid (type: string)
GUID of the project.
Only for toolsets: Visual Studio 2015 (vs2015)
Default: automatically generated
Inheritable from parent: no
vs2012.projectfile (type: path)
File name of the project for the target.
Only for toolsets: Visual Studio 2012 (vs2012)
Default:
$(id).vcxproj
in the same directory as the.sln
fileInheritable from parent: no
vs2012.guid (type: string)
GUID of the project.
Only for toolsets: Visual Studio 2012 (vs2012)
Default: automatically generated
Inheritable from parent: no
vs2013.projectfile (type: path)
File name of the project for the target.
Only for toolsets: Visual Studio 2013 (vs2013)
Default:
$(id).vcxproj
in the same directory as the.sln
fileInheritable from parent: no
vs2013.guid (type: string)
GUID of the project.
Only for toolsets: Visual Studio 2013 (vs2013)
Default: automatically generated
Inheritable from parent: no
vs2003.projectfile (type: path)
File name of the project for the target.
Only for toolsets: Visual Studio 2003 (vs2003)
Default:
$(id).vcxproj
in the same directory as the.sln
fileInheritable from parent: no
vs2003.guid (type: string)
GUID of the project.
Only for toolsets: Visual Studio 2003 (vs2003)
Default: automatically generated
Inheritable from parent: no
vs2010.projectfile (type: path)
File name of the project for the target.
Only for toolsets: Visual Studio 2010 (vs2010)
Default:
$(id).vcxproj
in the same directory as the.sln
fileInheritable from parent: no
vs2010.guid (type: string)
GUID of the project.
Only for toolsets: Visual Studio 2010 (vs2010)
Default: automatically generated
Inheritable from parent: no
Executable program (program)¶
Executable program.
Properties¶
basename (type: string)
Base name of the executable.
This is not full filename or even path, it’s only its base part, to which platform-specific extension is added. By default, it’s the same as target’s ID, but it can be changed e.g. if the filename should contain version number, which would be impractical to use as target identifier in the bakefile.
program mytool { // use mytool2.exe or /usr/bin/mytool2 basename = $(id)$(vermajor); }Default: $(id)
Inheritable from parent: no
win32-subsystem (type: subsystem)
Windows subsystem the executable runs in. Must be set towindows
for console-less applications.Default: console
Allowed values: “console”, “windows”
Inheritable from parent: yes
sources (type: list of paths)
Source files.
Default: empty
Inheritable from parent: no
headers (type: list of paths)
Header files.
Default: empty
Inheritable from parent: no
defines (type: list of strings)
List of preprocessor macros to define.
Default: empty
Inheritable from parent: yes
includedirs (type: list of paths)
Directories where to look for header files.
Default: empty
Inheritable from parent: yes
warnings (type: warnings)
Warning level for the compiler.
Use
no
to completely disable warning,minimal
to show only the most important warning messages,all
to enable all warnings that usually don’t result in false positives andmax
to enable absolutely all warnings.Default: default
Allowed values: “no”, “minimal”, “default”, “all”, “max”
Inheritable from parent: yes
compiler-options (type: list of strings)
Additional compiler options common to all C-like compilers (C, C++, Objective-C, Objective-C++).
Note that the options are compiler-specific and so this property should only be set conditionally for particular compilers that recognize the options.
Default: empty
Inheritable from parent: yes
c-compiler-options (type: list of strings)
Additional options for C compiler.
Note that the options are compiler-specific and so this property should only be set conditionally for particular compilers that recognize the options.
Default: empty
Inheritable from parent: yes
cxx-compiler-options (type: list of strings)
Additional options for C++ compiler.
Note that the options are compiler-specific and so this property should only be set conditionally for particular compilers that recognize the options.
Default: empty
Inheritable from parent: yes
libs (type: list of strings)
Additional libraries to link with.
Do not use this property to link with libraries built as part of your project; use deps for that.
When this list is non-empty on a Static library (library), it will be used when linking executables that use the library.
Default: empty
Inheritable from parent: yes
libdirs (type: list of paths)
Additional directories where to look for libraries.
When this list is non-empty on a Static library (library), it will be used when linking executables that use the library.
Default: empty
Inheritable from parent: yes
link-options (type: list of strings)
Additional linker options.
Note that the options are compiler/linker-specific and so this property should only be set conditionally for particular compilers that recognize the options.
When this list is non-empty on a Static library (library), it will be used when linking executables that use the library.
Default: empty
Inheritable from parent: yes
archs (type: list of architectures)
Architectures to compile for.
Adds support for building binaries for specified architectures, if supported by the toolset. Support may take the form of either multi-arch binaries (OS X) or additional build configurations (Visual Studio).
The default empty value means to do whatever the default behavior of the toolset is.
Currently only supported on OS X and in Visual Studio.
Default: null
Allowed values: “x86”, “x86_64”
Inheritable from parent: yes
win32-crt-linkage (type: linkage)
How to link against the C Runtime Library.
If
dll
(the default), the executable may depend on some DLLs provided by the compiler. Ifstatic
then a static version of the CRT is linked directly into the executable.Default: dll
Allowed values: “static”, “dll”
Inheritable from parent: yes
win32-unicode (type: bool)
Compile win32 code in Unicode mode? If enabled,
_UNICODE
symbol is defined and the wide character entry point (WinMain
, …) is used.Default: True
Inheritable from parent: yes
outputdir (type: path)
Directory where final binaries are put.
Note that this is not the directory for intermediate files such as object files – these are put in
@builddir
. By default, output location is the same,@builddir
, but can be overwritten to for example put all executables intobin/
subdirectory.Default: @builddir/
Inheritable from parent: yes
pic (type: bool)
Compile position-independent code.
By default, libraries (both shared and static, because the latter could be linked into a shared lib too) are linked with -fPIC and executables are not.
Default: None
Inheritable from parent: yes
multithreading (type: bool)
Enable support for multithreading.
MT support is enabled by default, but can be disabled when not needed.
On Unix, this option causes the use of pthreads library. Visual Studio always uses MT-safe CRT, even if this setting is disabled.
Default: True
Inheritable from parent: yes
id (type: id)
Target’s unique name (ID).
Read-only property
Inheritable from parent: no
deps (type: list of ids)
Dependencies of the target (list of IDs).
The dependencies are handled in target-specific ways. At the very least, they are added to the list of dependencies in generated makefiles or projects to ensure correct build order. Some targets may be smart about some kinds of the dependencies and do more.
In particular, compiled targets (executables, DLLs) will automatically link against all libraries found in deps.
Default: empty
Inheritable from parent: no
pre-build-commands (type: list of strings)
Custom commands to run before building the target.
The value is a list of shell commands to run. Notice that the commands are platform-specific and so typically need to be set conditionally depending on the value of
toolset
.Currently only implemented by Visual Studio.
Default: empty
Inheritable from parent: no
post-build-commands (type: list of strings)
Custom commands to run after building the target.
The value is a list of shell commands to run. Notice that the commands are platform-specific and so typically need to be set conditionally depending on the value of
toolset
.Currently only implemented by Visual Studio.
Default: empty
Inheritable from parent: no
configurations (type: list of strings)
List of configurations to use for this target.
See Build configurations for more information.
Default: Debug Release
Inheritable from parent: yes
vs2008.projectfile (type: path)
File name of the project for the target.
Only for toolsets: Visual Studio 2008 (vs2008)
Default:
$(id).vcxproj
in the same directory as the.sln
fileInheritable from parent: no
vs2008.guid (type: string)
GUID of the project.
Only for toolsets: Visual Studio 2008 (vs2008)
Default: automatically generated
Inheritable from parent: no
vs2005.projectfile (type: path)
File name of the project for the target.
Only for toolsets: Visual Studio 2005 (vs2005)
Default:
$(id).vcxproj
in the same directory as the.sln
fileInheritable from parent: no
vs2005.guid (type: string)
GUID of the project.
Only for toolsets: Visual Studio 2005 (vs2005)
Default: automatically generated
Inheritable from parent: no
vs2017.projectfile (type: path)
File name of the project for the target.
Only for toolsets: Visual Studio 2017 (vs2017)
Default:
$(id).vcxproj
in the same directory as the.sln
fileInheritable from parent: no
vs2017.guid (type: string)
GUID of the project.
Only for toolsets: Visual Studio 2017 (vs2017)
Default: automatically generated
Inheritable from parent: no
vs2015.projectfile (type: path)
File name of the project for the target.
Only for toolsets: Visual Studio 2015 (vs2015)
Default:
$(id).vcxproj
in the same directory as the.sln
fileInheritable from parent: no
vs2015.guid (type: string)
GUID of the project.
Only for toolsets: Visual Studio 2015 (vs2015)
Default: automatically generated
Inheritable from parent: no
vs2012.projectfile (type: path)
File name of the project for the target.
Only for toolsets: Visual Studio 2012 (vs2012)
Default:
$(id).vcxproj
in the same directory as the.sln
fileInheritable from parent: no
vs2012.guid (type: string)
GUID of the project.
Only for toolsets: Visual Studio 2012 (vs2012)
Default: automatically generated
Inheritable from parent: no
vs2013.projectfile (type: path)
File name of the project for the target.
Only for toolsets: Visual Studio 2013 (vs2013)
Default:
$(id).vcxproj
in the same directory as the.sln
fileInheritable from parent: no
vs2013.guid (type: string)
GUID of the project.
Only for toolsets: Visual Studio 2013 (vs2013)
Default: automatically generated
Inheritable from parent: no
vs2003.projectfile (type: path)
File name of the project for the target.
Only for toolsets: Visual Studio 2003 (vs2003)
Default:
$(id).vcxproj
in the same directory as the.sln
fileInheritable from parent: no
vs2003.guid (type: string)
GUID of the project.
Only for toolsets: Visual Studio 2003 (vs2003)
Default: automatically generated
Inheritable from parent: no
vs2010.projectfile (type: path)
File name of the project for the target.
Only for toolsets: Visual Studio 2010 (vs2010)
Default:
$(id).vcxproj
in the same directory as the.sln
fileInheritable from parent: no
vs2010.guid (type: string)
GUID of the project.
Only for toolsets: Visual Studio 2010 (vs2010)
Default: automatically generated
Inheritable from parent: no
Extending and developing Bakefile¶
Writing Bakefile plugins¶
As mentioned in Loading plugins, it is possible to use plugins written in Python to extend Bakefile functionality. The most common types of plugins are those defining custom tool sets, i.e. new output formats, or custom build steps, allowing to perform more or less arbitrary actions.
But the simplest possible custom step plugin may actually not do anything at all, but just define some properties that can be used in bakefiles. For example, here is a complete example of a plugin:
from bkl.api import CustomStep, Property
from bkl.vartypes import StringType
from datetime import date
class MyVersion(CustomStep):
"""
Simple bakefile plugin defining MY_VERSION property.
The value of the version is just the current date.
"""
name = "my_version"
properties_project = [
Property("MY_VERSION",
type=StringType(),
default=data.today().isoformat(),
inheritable=False,
readonly=True),
]
This plugin can then be used in the following way:
plugin bkl.plugins.my_version.py;
program my_program {
basename = my_program-$(MY_VERSION);
...
}
Of course, a more realistic example would use something other than just the date of the last Bakefile execution as version. As plugin is just a normal Python script, there are a lot of possibilities, for example it could extract the version from the VCS used by the program or read it from some file inside the source tree.
Reference¶
API reference documentation¶
bkl.model
– project model¶
-
class
bkl.model.
Configuration
(name, base, is_debug, source_pos=None)¶ Bases:
object
Class representing a configuration.
Each model has two special configurations, Debug and Release, predefined.
-
name
¶ Name of the configuration
-
base
¶ Base configuration this one is derived from, as a
Configuration
instance, orNone
for “Debug” and “Release” configurations.
-
is_debug
¶ Is this a debug configuration?
-
source_pos
¶ Source code position of object’s definition, or
None
.
-
create_derived
(new_name, source_pos=None)¶ Returns a new copy of this configuration with a new name.
-
derived_from
(cfg)¶ Returns true if self derives, directly or indirectly, from configuration cfg.
Returns 0 if not derived. Returns degree of inheritance if derived: 1 if cfg is a direct base, 2 if it is a base of self’s base etc.
-
-
class
bkl.model.
ConfigurationProxy
(model, config)¶ Bases:
object
Proxy for accessing model part’s variables as configuration-specific. All expressions obtained using operator[] are processed to remove conditionals depending on the value of “config”, by substituting appropriate value according to the configuration name passed to proxy’s constructor.
See
bkl.model.ModelPartWithConfigurations.configurations()
for more information.-
apply_subst
(value)¶ Applies the proxy’s magic on given value. This is useful for when the proxy cannot be simply used in place of a real target. For example, NativeLinkedType.get_ldlibs() inspects other targets too and so the proxy is only partially effective.
-
-
class
bkl.model.
ConfigurationsPropertyMixin
¶ Mixin class for implementation configurations property.
-
configurations
¶ Returns all configurations for this model part (e.g. a target), as ConfigurationProxy objects that can be used similarly to the way the model part object itself is. In particular, it’s [] operator works the same.
The proxies are intended to be used in place of targets in code that needs to get per-configuration values of properties.
>>> for cfg in target.configurations: ... outdir = cfg["outdir"]
-
-
class
bkl.model.
ModelPart
(parent, source_pos=None)¶ Bases:
object
Base class for model “parts”, i.e. projects, modules or targets. Basically, anything that can have variables on it.
-
name
¶ Name of the part – e.g. target name, filename of source file etc.
-
variables
¶ Dictionary of all variables defined in global scope in this module
-
parent
¶ Parent model part of this one, i.e. the part one step higher in object model hierarchy (e.g. module for a target). May only be
None
for toplevel part (the project). Dictionary of all variables defined in global scope in this module
-
source_pos
¶ Source code position of object’s definition, or
None
.
-
add_variable
(var)¶ Adds a new variable object.
-
all_variables
()¶ Returns iterator over all variables in the target. Works recursively, i.e. scans all modules and targets under this object too.
-
child_parts
()¶ Yields model parts that are (direct) children of this.
-
enum_props
()¶ Enumerates properties defined on this object.
Like
get_prop()
, this method doesn’t work recursively upwards, but lists only properties that are defined for this scope.See also
-
get_child_part_by_name
(name)¶ Returns child of this part of the model with given name (e.g. target with that name). Throws if not found.
-
get_matching_prop_with_inheritance
(name)¶ Like
get_prop()
, but looks for inheritable properties defined for child scopes too (e.g. returns per-target property ‘outputdir’ even in module scope).(This is used for assigning into variables and validating them against properties. Don’t use unless you know what you’re doing.)
-
get_prop
(name)¶ Try to get a property name. Called by get_variable_value() if no variable with such name could be found.
Note that unlike
get_variable()
, this one doesn’t work recursively upwards, but finds only properties that are defined for this scope.See also
-
get_variable
(name)¶ Returns variable object for given variable or None if it is not defined at this scope.
This method does not do any recursive resolution or account for properties and their default values; it merely gets the variable object if it is defined at this scope.
See also
-
get_variable_value
(name)¶ Similar to get_variable(), but returns the expression with variable’s value. Throws and exception if the variable isn’t defined, neither in this scope or in any of its parent scopes.
If variable name is not explicitly defined, but a property with the same name exists in this scope, then its default value is used.
If the variable is not defined in this scope at all, looks in the parent – but only if name doesn’t correspond to non-inheritable property. In other words, fails only if the variable isn’t defined for use in this scope.
Throws if the value cannot be found.
As a shorthand syntax for this function, key indices may be used: >>> target[“includedirs”]
See also
-
is_variable_explicitly_set
(name)¶ Returns true if the variable was set in the bakefiles explicitly.
-
is_variable_null
(name)¶ Returns true if the variable is unset or null (which amounts to not being set in this toolset / under current condition).
-
make_variables_for_missing_props
(toolset)¶ Creates variables for properties that don’t have variables set yet.
Parameters: toolset – Name of the toolset to generate for. Properties specific to other toolsets are ignored for efficiency.
-
resolve_variable
(name)¶ Returns variable object for given variable or None if it is not defined.
Unlike
get_variable()
, this method does perform recursive resolution and finds the variable (if it exists) according to the same rules that apply to $(…) expressions and toget_variable_value()
.See also
Note
Unlike
get_variable_value()
, this method doesn’t look for properties’ default values.
-
set_property_value
(prop, value)¶ Adds variable with a value for property prop.
The property must exist on this model part. This is just a convenience wrapper around
add_variable()
andget_prop()
.
-
should_build
()¶ Evaluates the condition property on this part and returns True if it should be built or False otherwise. Throws NonConstError if it cannot be determined.
-
condition
¶ Condition expression (
bkl.expr.Expr
) that describes when should this part of the model be included. If it evaluates to true, the part is build, otherwise it is not. Typical use is enabling some targets or source files only for some toolsets, but it may be more complicated. Depending on the context and the toolset, the expression may even be undeterminable until make-time, if it references some user options (but not all toolsets can handle this). IsNone
if no condition is associated.
-
module
¶ The
bkl.model.Module
that this part belongs to.
-
project
¶ The
bkl.model.Project
project this part belongs to.
-
-
class
bkl.model.
Module
(parent, source_pos)¶ Bases:
bkl.model.ModelPart
Representation of single compilation unit. Corresponds to one Bakefile input file (either specified on command line or imported using import command; files included using include from other files are not represented by Module object) and typically to one generated output file.
-
targets
¶ Dictionary of all targets defined in this module
-
source_file
¶ Path to the input
.bkl
source file this module was created from.
-
srcdir
¶ @srcdir path effective for this module.
-
imports
¶ Set of filenames of sources imported using the ‘import’ keyword at this level.
-
child_parts
()¶ Yields model parts that are (direct) children of this.
-
enum_props
()¶ Enumerates properties defined on this object.
Like
get_prop()
, this method doesn’t work recursively upwards, but lists only properties that are defined for this scope.See also
get_prop()
-
is_submodule_of
(module)¶ Returns True if this module is (grand-)*child of module.
-
submodules
¶ Submodules of this module.
-
-
class
bkl.model.
Project
¶ Bases:
bkl.model.ModelPart
Abstract model that completely describes state of loaded and processed Bakefile file(s) within the project.
-
modules
¶ List of all modules included in the project.
-
configurations
¶ All configurations defined in the project.
-
settings
¶ List of all settings included in the project.
-
templates
¶ Dictionary of all templates defined in the project.
-
add_configuration
(config)¶ Adds a new configuration to the project.
-
add_template
(templ)¶ Adds a new template to the project.
-
all_targets
()¶ Returns iterator over all targets in the project.
-
child_parts
()¶ Yields model parts that are (direct) children of this.
-
clone
()¶ Makes an independent copy of the model.
Unlike deepcopy(), this does not copy everything, but uses an appropriate mix of deep and shallow copies. For example, expressions, which are read-only, are copied shallowly, but variables or model parts, both of which can be modified in further toolset-specific optimizations, are copied deeply.
-
enum_props
()¶ Enumerates properties defined on this object.
Like
get_prop()
, this method doesn’t work recursively upwards, but lists only properties that are defined for this scope.See also
get_prop()
-
get_target
(id)¶ Returns Target object identified by its string ID.
-
has_target
(id)¶ Returns true if target with given name exists.
-
top_module
¶ The toplevel module of this project.
-
-
class
bkl.model.
ProxyIfResolver
(config)¶ Bases:
bkl.expr.RewritingVisitor
Replaces references to $(config) with value, allowing the expressions to be evaluated.
-
if_
(e)¶ Called on
IfExpr
expressions.
-
placeholder
(e)¶ Called on
PlaceholderExpr
expressions.
-
reference
(e)¶ Called on
ReferenceExpr
expressions.
-
-
class
bkl.model.
Setting
(parent, name, source_pos)¶ Bases:
bkl.model.ModelPart
User-settable make-time configuration value.
-
child_parts
()¶ Yields model parts that are (direct) children of this.
-
enum_props
()¶ Enumerates properties defined on this object.
Like
get_prop()
, this method doesn’t work recursively upwards, but lists only properties that are defined for this scope.See also
get_prop()
-
-
class
bkl.model.
SourceFile
(parent, filename, source_pos)¶ Bases:
bkl.model.ModelPart
,bkl.model.ConfigurationsPropertyMixin
Source file object.
-
child_parts
()¶ Yields model parts that are (direct) children of this.
-
enum_props
()¶ Enumerates properties defined on this object.
Like
get_prop()
, this method doesn’t work recursively upwards, but lists only properties that are defined for this scope.See also
get_prop()
-
-
class
bkl.model.
Target
(parent, name, target_type, source_pos)¶ Bases:
bkl.model.ModelPart
,bkl.model.ConfigurationsPropertyMixin
A Bakefile target.
Variables are typed.
-
name
¶ Name (ID) of the target. This must be unique in the entire project.
-
type
¶ Type of the target, as
bkl.api.TargetType
instance.
-
sources
¶ List of source files, as SourceFile instances.
-
headers
¶ List of header files, as SourceFile instances. The difference from
sources
is that headers are installable and usable for compilation of other targets, while sources are not.
-
child_parts
()¶ Yields model parts that are (direct) children of this.
-
enum_props
()¶ Enumerates properties defined on this object.
Like
get_prop()
, this method doesn’t work recursively upwards, but lists only properties that are defined for this scope.See also
get_prop()
-
-
class
bkl.model.
Template
(name, bases, source_pos=None)¶ Bases:
object
A template.
-
name
¶ Name of the template.
-
bases
¶ List of base templates (as
bkl.model.Template
objects).
-
source_pos
¶ Source code position of template’s definition, or
None
.
-
-
class
bkl.model.
Variable
(name, value, type=None, readonly=False, source_pos=None)¶ Bases:
object
A Bakefile variable.
Variables can be either global or target-specific. Value held by a variable is stored as expression tree, it isn’t evaluated into string form until the final stage of processing, when output is generated.
Variables are typed.
-
name
¶ Name of the variable.
-
type
¶ Type of the property, as
bkl.vartypes.Type
instance.
-
value
¶ Value of the variable, as
bkl.expr.Expr
object.
-
readonly
¶ Indicates if the variable is read-only. Read-only variables can only be assigned once and cannot be modified afterwards.
-
is_property
¶ Indicates if the variable corresponds to a property.
-
is_explicitly_set
¶ Indicates if the value was set explicitly by the user. Normally true, only false for properties’ default values.
-
static
from_property
(prop, value=None)¶ Creates a variable from property prop. In particular, takes the type and
readonly
attribute from the property. Properties’ default value is not assigned; value is used instead.
-
set_value
(value)¶ Sets new value on the variable. The new value must have same type as current value. Read-only variable cannot be set.
Parameters: value – New value as bkl.expr.Expr
object.
-
bkl.expr
– representation of expressions¶
The Expr
class that represents a Bakefile expression (be it a
condition or variable value) is defined in this module, together with
useful functions for evaluating and manipulating expressions.
-
class
bkl.expr.
BoolExpr
(operator, left, right=None, pos=None)¶ Bases:
bkl.expr.Expr
Boolean expression.
-
operator
¶ Boolean operator of the node. The value is one of BoolExpr constants, e.g. BoolExpr.AND.
-
left
¶ Left (or in the case of NOT operator, only) operand.
-
right
¶ Right operand. Not set for the NOT operator.
-
as_py
()¶ Returns the expression as Python value (e.g. a list of strings) if it evaluates to a constant literal. Throws an exception if the expression cannot be evaluated at bake-time (such expressions cannot be used in some situations, e.g. to specify output files). Paths are returned as native paths.
Use
bkl.expr.Formatter
if you need to format expressions into strings.See also
is_const()
-
has_bool_operands
()¶ Returns true if the operator is such that it requires boolean operands (i.e. NOT, AND, OR).
-
AND
= '&&'¶ And operator
-
EQUAL
= '=='¶ Equality operator
-
NOT
= '!'¶ Not operator; unlike others, this one is unary and has no right operand.
-
NOT_EQUAL
= '!='¶ Inequality operator
-
OR
= '||'¶ Or operator
-
-
class
bkl.expr.
BoolValueExpr
(value, pos=None)¶ Bases:
bkl.expr.Expr
Constant boolean value, i.e. true or false.
-
value
¶ Value of the literal, as (Python) boolean.
-
as_py
()¶ Returns the expression as Python value (e.g. a list of strings) if it evaluates to a constant literal. Throws an exception if the expression cannot be evaluated at bake-time (such expressions cannot be used in some situations, e.g. to specify output files). Paths are returned as native paths.
Use
bkl.expr.Formatter
if you need to format expressions into strings.See also
is_const()
-
-
class
bkl.expr.
ConcatExpr
(items, pos=None)¶ Bases:
bkl.expr.Expr
Concatenation of several expression. Typically, used with LiteralExpr and ReferenceExpr to express values such as “$(foo).cpp”.
-
as_py
()¶ Returns the expression as Python value (e.g. a list of strings) if it evaluates to a constant literal. Throws an exception if the expression cannot be evaluated at bake-time (such expressions cannot be used in some situations, e.g. to specify output files). Paths are returned as native paths.
Use
bkl.expr.Formatter
if you need to format expressions into strings.See also
is_const()
-
-
class
bkl.expr.
CondTrackingMixin
¶ Helper mixin class for tracking currently active condition. Useful for handling e.g. nested if statements.
-
active_if_cond
¶ Currently active condition, if any.
-
-
class
bkl.expr.
Expr
(pos=None)¶ Bases:
object
Value expression.
Represents a value (typically assigned to a variable, but also expressions used somewhere else, e.g. as conditions) as tree of expression objects. In Bakefile, the expressions are kept in tree representation until the last possible moment, and are manipulated in this form.
Note that expression objects are immutable: if you need to modify an expression, replace it with a new object.
-
pos
¶ Location of the expression in source tree.
-
as_py
()¶ Returns the expression as Python value (e.g. a list of strings) if it evaluates to a constant literal. Throws an exception if the expression cannot be evaluated at bake-time (such expressions cannot be used in some situations, e.g. to specify output files). Paths are returned as native paths.
Use
bkl.expr.Formatter
if you need to format expressions into strings.See also
-
as_symbolic
()¶ Returns the value as a symbolic representation, see SymbolicFormatter.
-
is_const
()¶ Returns true if the expression is constant, i.e. can be evaluated at this time (bake-time), as opposed to expressions that depend on a setting that can only be determined at make-time.
See also
-
is_null
()¶ Returns true if the expression evaluates to null, i.e. empty value.
-
-
class
bkl.expr.
Formatter
(paths_info)¶ Bases:
bkl.expr.Visitor
Base class for expression formatters. A formatter is a class that formats the expression into a string in the way that is needed on the output. For example, it handles things such as path separators on different platforms, variable references, quoting of literals with whitespace in them and so on.
The base class implements commonly used formatting, such as using whitespace for delimiting list items etc.
Use the
format()
method to format an expression.-
list_sep
¶ Separator for list items (by default, single space).
-
paths_info
¶ PathAnchorsInfo
information object to use for formatting of paths.
-
bool_value
(e)¶ Called on
BoolValueExpr
expressions.
-
concat
(e)¶ Called on
ConcatExpr
expressions.
-
format
(e)¶ Formats expression e into a string.
-
literal
(e)¶ Called on
LiteralExpr
expressions.
-
reference
(e)¶ Called on
ReferenceExpr
expressions.
-
-
class
bkl.expr.
IfExpr
(cond, yes, no, pos=None)¶ Bases:
bkl.expr.Expr
Conditional expression.
-
cond
¶ The condition expression.
-
value_yes
¶ Value of the expression if the condition evaluates to True.
-
value_no
¶ Value of the expression if the condition evaluates to False.
-
as_py
()¶ Returns the expression as Python value (e.g. a list of strings) if it evaluates to a constant literal. Throws an exception if the expression cannot be evaluated at bake-time (such expressions cannot be used in some situations, e.g. to specify output files). Paths are returned as native paths.
Use
bkl.expr.Formatter
if you need to format expressions into strings.See also
is_const()
-
-
class
bkl.expr.
ListExpr
(items, pos=None)¶ Bases:
bkl.expr.Expr
List expression – list of several values of the same type.
-
as_py
()¶ Returns the expression as Python value (e.g. a list of strings) if it evaluates to a constant literal. Throws an exception if the expression cannot be evaluated at bake-time (such expressions cannot be used in some situations, e.g. to specify output files). Paths are returned as native paths.
Use
bkl.expr.Formatter
if you need to format expressions into strings.See also
is_const()
-
-
class
bkl.expr.
LiteralExpr
(value, pos=None)¶ Bases:
bkl.expr.Expr
Constant expression – holds a literal.
-
value
¶ Value of the literal.
-
pos
¶ Location of the expression in source tree.
-
as_py
()¶ Returns the expression as Python value (e.g. a list of strings) if it evaluates to a constant literal. Throws an exception if the expression cannot be evaluated at bake-time (such expressions cannot be used in some situations, e.g. to specify output files). Paths are returned as native paths.
Use
bkl.expr.Formatter
if you need to format expressions into strings.See also
is_const()
-
-
class
bkl.expr.
NullExpr
(pos=None)¶ Bases:
bkl.expr.Expr
Empty/unset value.
-
as_py
()¶ Returns the expression as Python value (e.g. a list of strings) if it evaluates to a constant literal. Throws an exception if the expression cannot be evaluated at bake-time (such expressions cannot be used in some situations, e.g. to specify output files). Paths are returned as native paths.
Use
bkl.expr.Formatter
if you need to format expressions into strings.See also
is_const()
-
-
class
bkl.expr.
PathAnchorsInfo
(dirsep, outfile, builddir, model)¶ Bases:
object
Struct with information about real values for symbolic anchors of
PathExpr
paths. These are needed in order to format path expression (usingbkl.expr.Formatter
or otherwise).-
dirsep
¶ Separator to separate path components (“/” on Unix and “” on Windows).
-
top_srcdir
¶ Path to the top source directory, as a list of components, relative to the output directory. Will be empty list if the paths are the same.
-
builddir
¶ Path to the build directory – the directory where object files and other generated files are put – as a list of components, relative to the output directory. Will be empty list if the paths are the same.
-
top_srcdir_abs
¶ Absolute native path to the top source directory.
-
outdir_abs
¶ Absolute native path to the output directory – the directory where the project or makefile currently being generated is written to.
-
builddir_abs
¶ Absolute native path to the build directory.
The constructor creates anchors information from native paths passed to it:
Parameters: - dirsep – Path components separator, same as the
dirsep
attribute. - outfile – (Native) path to the output file (project, makefile). Paths in
the output will be typically formatted relatively to this path.
The
outdir_abs
attribute is computed from this parameter. - builddir – (Native) path to the build directory. May be None if builddir-relative paths make no sense in this context (e.g. for VS2010 solution files).
- model – Part of the model (
bkl.model.Module
orbkl.model.Target
) that outfile corresponds to.
-
-
class
bkl.expr.
PathExpr
(components, anchor='@srcdir', anchor_file=None, pos=None)¶ Bases:
bkl.expr.Expr
Expression that holds a file or directory name, or part of it.
-
components
¶ List of path’s components (as expressions). For example, components of path
foo/bar/file.cpp
are["foo", "bar", "file.cpp"]
.
-
anchor
¶ The point to which the path is relative to. This can be one of the following:
expr.ANCHOR_SRCDIR
– Path is relative to the directory where the input bakefile is (unless overridden in it).expr.ANCHOR_TOP_SRCDIR
– Path is relative to the top source directory (where the toplevel.bkl
file is, unless overridden in it).expr.ANCHOR_BUILDDIR
– Path is relative to the build directory. Either this anchor orexpr.ANCHOR_TOP_BUILDDIR
should be used for all transient files (object files or other generated files).expr.ANCHOR_TOP_BUILDDIR
– Path is relative to the top build directory. This is currently only used by makefile backends where the build directory for a sub-makefile is different from the top one.
-
anchor_file
¶ Name of the file the anchor was written in. This is important for @srcdir, which is relative to this place.
-
pos
¶ Location of the expression in source tree.
-
as_native_path
(paths_info)¶ Returns the path expressed as absolute native path. Requires complete
bkl.expr.PathAnchorsInfo
information as its argument.Throws NonConstError if it cannot be done because of conditional subexpression.
See also
-
as_native_path_for_output
(model)¶ Specialized version of
as_native_path()
that only works with srcdir-based paths. It’s useful for code that needs to obtain output file name (which happens before PathAnchorsInfo can be constructed).Parameters: model – Any part of the model.
-
as_py
()¶ Returns the expression as Python value (e.g. a list of strings) if it evaluates to a constant literal. Throws an exception if the expression cannot be evaluated at bake-time (such expressions cannot be used in some situations, e.g. to specify output files). Paths are returned as native paths.
Use
bkl.expr.Formatter
if you need to format expressions into strings.See also
is_const()
-
change_extension
(newext)¶ Changes extension of the filename to newext and returns
bkl.expr.PathExpr
with the new path.
-
get_basename
()¶ Returns basename of the filename path (i.e. the name without directory or extension). Throws if it cannot be determined.
-
get_directory_path
()¶ Returns PathExpr with the directory component.
-
get_extension
()¶ Returns extension of the filename path. Throws if it cannot be determined.
-
is_external_absolute
()¶ Returns true if the path is to be treated as an absolute path provided externally (i.e. via an user setting) when the makefile was invoked.
TODO: add a @absdir anchor instead?
-
-
class
bkl.expr.
PlaceholderExpr
(var, pos=None)¶ Bases:
bkl.expr.Expr
This is a hack. It is used as placeholder for expressions with not yet known value. In particular, it is used for the “toolset” property before the model is split into toolset-specific copies, to allow partial evaluation common to all of them.
-
var
¶ Name of referenced setting (e.g. “config” or “toolset”).
-
as_py
()¶ Returns the expression as Python value (e.g. a list of strings) if it evaluates to a constant literal. Throws an exception if the expression cannot be evaluated at bake-time (such expressions cannot be used in some situations, e.g. to specify output files). Paths are returned as native paths.
Use
bkl.expr.Formatter
if you need to format expressions into strings.See also
is_const()
-
-
class
bkl.expr.
ReferenceExpr
(var, context, pos=None)¶ Bases:
bkl.expr.Expr
Reference to a variable.
-
var
¶ Name of referenced variable.
-
context
¶ Context of the reference, i.e. the scope in which it was used. This is the appropriate
bkl.model.ModelPart
instance (e.g. a target or a module).
-
as_py
()¶ Returns the expression as Python value (e.g. a list of strings) if it evaluates to a constant literal. Throws an exception if the expression cannot be evaluated at bake-time (such expressions cannot be used in some situations, e.g. to specify output files). Paths are returned as native paths.
Use
bkl.expr.Formatter
if you need to format expressions into strings.See also
is_const()
-
get_value
()¶ Returns value of the referenced variable. Throws an exception if the reference couldn’t be resolved.
-
get_variable
()¶ Return the variable object this reference points to.
Use this method only if necessary; whenever possible,
get_value()
should be used instead.Note that the returned value may be None, either if the referenced variable doesn’t exist or when the reference is to a property that wasn’t explicitly set and uses the default value.
-
-
class
bkl.expr.
RewritingVisitor
¶ Bases:
bkl.expr.Visitor
Base class for visitors that perform some changes to the expression.
RewritingVisitor is smart about the rewrites and if nothing changes, returns the same instance, instead of creating an identical copy.
It also implements all Visitor methods to do the right thing by default, so you only need to override the ones that are of interest. Default implementations of the others will do the right thing: for example, if an item in the list is rewritten, the list() method will detect it and return a new list.
-
concat
(e)¶ Called on
ConcatExpr
expressions.
-
-
class
bkl.expr.
SymbolicFormatter
¶ Bases:
bkl.expr.Formatter
Formats into unambiguous symbolic representation of the expression.
-
bool_value
(e)¶ Called on
BoolValueExpr
expressions.
-
concat
(e)¶ Called on
ConcatExpr
expressions.
-
literal
(e)¶ Called on
LiteralExpr
expressions.
-
placeholder
(e)¶ Called on
PlaceholderExpr
expressions.
-
-
class
bkl.expr.
Visitor
¶ Bases:
object
Implements visitor pattern for
Expr
expressions. This is abstract base class, derived classes must implement all of its methods exceptvisit()
. The way visitors are used is that the caller callsvisit()
on the expression.-
bool_value
(e)¶ Called on
BoolValueExpr
expressions.
-
concat
(e)¶ Called on
ConcatExpr
expressions.
-
literal
(e)¶ Called on
LiteralExpr
expressions.
-
noop
(e)¶ Helper to quickly implement handler functions that do nothing.
-
placeholder
(e)¶ Called on
PlaceholderExpr
expressions.
-
reference
(e)¶ Called on
ReferenceExpr
expressions.
-
visit
(e)¶ Call this method to visit expression e. One of object’s “callback” methods will be called, depending on e’s type.
Return value is the value returned by the appropriate callback and is typically
None
.
-
visit_children
(e)¶ Helper to implement visitor methods that just need to recursively work on all children. Ignores return value for the children.
-
-
bkl.expr.
add_prefix
(prefix, e)¶ Adds a prefix in front of the expression e or, if e is a list, in front of each of its elements.
Parameters: - prefix – The prefix to add; either an
bkl.expr.Expr
object or a string. - e – The expression to add the prefix in front of.
- prefix – The prefix to add; either an
-
bkl.expr.
are_equal
(a, b, _inside_cond=False)¶ Compares two expressions for equality.
Throws the CannotDetermineError exception if it cannot reliably determine equality.
-
bkl.expr.
concat
(*parts)¶ Concatenates all arguments and returns
bkl.expr.ConcatExpr
. The arguments may be expressions or string literals.
-
bkl.expr.
enum_possible_values
(e, global_cond=None)¶ Returns all values that are possible, together with their respective conditions, as an iteratable of (condition, value) tuples. The condition may be
None
if the value is always there, otherwise it is a booleanbkl.expr.Expr
.Note that this function returns possible elements for lists. It skips null expressions as well.
Parameters: - e – Expression to extract possible values from.
- global_cond – Optional condition expression (
bkl.expr.Expr
) to apply to all items. If specified, then every tuple in returned list will have the condition set to either global_cond (for unconditional items) or its combination with per-item condition.
-
bkl.expr.
format_string
(format, values)¶ Substitutes occurrences of “%(varname)” in the format string with values from the dictionary values, similarly to the ‘%’ operator. Values in the dictionary may be either Expr objects or strings.
Note that there’s currently no way to escape “%” in such expressions.
-
bkl.expr.
get_model_name_from_path
(e)¶ Give an expression representing filename, return name suitable for model.SourceFile.name.
-
bkl.expr.
keep_possible_values_unexpanded
(e)¶ Determines if the given reference value should be expanded or not.
This is a helper of enum_possible_values() and is used to decide whether a value returned by that function is fully expanded or kept in its original form, with variable references in it. The latter is useful when dealing with the source files containing variables as it prevents them from being expanded too early, before the variable value for the current target is really known.
However anything not representing a simple single value should still be expanded and this function task is to check whether the argument is a reference to such simple single value or not.
-
bkl.expr.
split
(e, sep)¶ Splits expression e into a list of expressions, using sep as the delimiter character. Works with conditional expressions and variable references too.
-
bkl.expr.
split_into_path
(e)¶ Splits expression e into a list of expressions, using ‘/’ as the delimiter character. Returns a PathExpr. Works with conditional expressions and variable references too.
bkl.vartypes
– variables types¶
This module defines types interface as well as basic types. The types – i.e.
objects derived from bkl.vartypes.Type
– are used to verify validity
of variable values and other expressions.
-
class
bkl.vartypes.
AnyType
¶ Bases:
bkl.vartypes.Type
A fallback type that allows any value at all.
-
validate
(e)¶ Validates if the expression e is of this type. If it isn’t, throws
bkl.error.TypeError
with description of the error.Note that this method transparently handles references and conditional expressions.
-
-
class
bkl.vartypes.
BoolType
¶ Bases:
bkl.vartypes.Type
Boolean value type. May be product of a boolean expression or one of the following literals with obvious meanings: “true” or “false”.
-
class
bkl.vartypes.
EnumType
(name, allowed_values)¶ Bases:
bkl.vartypes.Type
Enum type. The value must be one of allowed values passed to the constructor.
-
allowed_values
¶ List of allowed values (strings).
-
-
class
bkl.vartypes.
IdType
¶ Bases:
bkl.vartypes.Type
Type for target IDs.
-
class
bkl.vartypes.
ListType
(item_type)¶ Bases:
bkl.vartypes.Type
Type for a list of items of homogeneous type.
-
item_type
¶ Type of items stored in the list (
bkl.vartypes.Type
instance).
-
-
class
bkl.vartypes.
PathType
¶ Bases:
bkl.vartypes.Type
A file or directory name.
-
class
bkl.vartypes.
StringType
¶ Bases:
bkl.vartypes.Type
Any string value.
-
class
bkl.vartypes.
Type
¶ Bases:
object
Base class for all Bakefile types.
-
name
¶ Human-readable name of the type, e.g. “path” or “bool”.
-
normalize
(e)¶ Normalizes the expression e to be of this type, if it can be done. If it cannot be, does nothing.
Returns e if no normalization was done or a new expression with normalized form of e.
-
validate
(e)¶ Validates if the expression e is of this type. If it isn’t, throws
bkl.error.TypeError
with description of the error.Note that this method transparently handles references and conditional expressions.
-
-
bkl.vartypes.
guess_expr_type
(e)¶ Attempts to guess type of the expression if it’s possible. Returns AnyType type if unsure.
-
bkl.vartypes.
normalize_and_validate_bool_subexpressions
(e)¶ Performs type normalization and validation steps for typed subexpressions, namely for IfExpr conditions and boolean expressions.
-
bkl.vartypes.
TheAnyType
= <bkl.vartypes.AnyType object>¶ For efficiency, singleton instance of AnyType
bkl.api
– public extensions API¶
-
class
bkl.api.
BuildNode
(commands, inputs=[], outputs=[], name=None, source_pos=None)¶ Bases:
object
BuildNode represents a single node in traditional make-style build graph. Bakefile’s model is higher-level than that, its targets may represent entities that will be mapped into several makefile targets. But BuildNode is the simplest element of build process: a list of commands to run together with dependencies that describe when to run it and a list of outputs the commands create.
Node’s commands are executed if either a) some of its outputs doesn’t exist or b) any of the inputs was modified since the last time the outputs were modified.
-
name
¶ Name of build node. May be empty. If not empty and the node has no output files (i.e. is phony), then this name is used in the generated makefiles. It is ignored in all other cases.
-
inputs
¶ List of all inputs for this node. Its items are filenames (as
bkl.expr.PathExpr
expressions) or (phony) target names.
-
outputs
¶ List of all outputs this node generates. Its items are filenames (as
bkl.expr.PathExpr
expressions).A node with no outputs is called phony.
-
commands:
List of commands to execute when the rebuild condition is met, as
bkl.expr.Expr
.
-
source_pos
¶ Source code position of whatever code was the cause for the creation of this BuildNode (e.g. associated source file), or
None
.
-
-
class
bkl.api.
BuildSubgraph
(main, secondary=[])¶ Bases:
object
BuildSubgraph is a collection of
bkl.api.BuildNode
nodes.-
main
¶ Primary build node of a target (e.g. its executable file).
-
secondary
¶ A list of any secondary nodes needed to build the main nodes (e.g. object files for target’s source files). May be empty.
-
all_nodes
()¶ Yield all nodes included in the subgraph.
-
-
class
bkl.api.
CustomStep
¶ Bases:
bkl.api.Extension
Custom processing step that is applied to the loaded model.
Plugins of this kind can be used to perform any custom operations with the model. For example, they may enforce coding style, they may add or modify some properties or even generate auxiliary output files.
CustomStep class has several hook methods called at different phases of processing. All of them do nothing by default and reimplementing them is optional.
-
finalize
(model)¶ Called after loading the model from file(s) and before doing any optimizations or error checking on it.
Do not create any output files here, leave that to
generate()
.
-
generate
(model)¶ Called right before generating the output. It is called on the common model, before optimizing it for individual toolsets.
It is permitted to create output files in this method.
-
-
class
bkl.api.
Extension
¶ Bases:
object
Base class for all Bakefile extensions.
Extensions are singletons, there’s always only one instance of given extension at runtime. Use the get() method called on appropriate extension type to obtain it. For example:
program = TargetType.get(“program”) # …do something with it…-
name
¶ Use-visible name of the extension. For example, the name for targets extensions is what is used in target declarations; likewise for property names.
-
classmethod
all
()¶ Returns iterator over instances of all implementations of this extension type.
-
classmethod
all_names
()¶ Returns names of all implementations of this extension type.
-
classmethod
all_properties
(kind='properties')¶ For derived extension types that have properties e.g.
TargetType
), returns iterator over all properties.The class must have class member variable var:properties with a list of
bkl.api.Property
instances. Base class’ properties are automagically scanned too.Parameters: kind – Kind (i.e. attribute name) of the properties to list. By default, “properties”, but may be more specific, e.g. “properties_module” or “properties_vs2010”. See also
-
classmethod
all_properties_kinds
()¶ Returns a set of names of all properties attributes in this class. These are attributes named “properties” or “properties_<something>”, e.g. “properties_module” for properties with module scope.
-
classmethod
get
(name=None)¶ This class method is used to get an instance of an extension. In can be used in one of two ways:
When called on an extension type class with name argument, it returns instance of extension with given name and of the extension type on which this classmethod was called:
>>> bkl.api.Toolset.get("gnu") <bkl.plugins.gnu.GnuToolset object at 0x2232950>
When called without the name argument, it must be called on particular extension class and returns its (singleton) instance:
>>> GnuToolset.get() <bkl.plugins.gnu.GnuToolset object at 0x2232950>
Parameters: name – Name of the extension to read; this corresponds to class’ “name” attribute. If not specified, then get() must be called on a extension, not extension base class.
-
-
class
bkl.api.
FileCompiler
¶ Bases:
bkl.api.Extension
In Bakefile API, FileCompiler is used to define all compilation steps.
Traditionally, the term compiler is used for a tool that compiles source code into object files. In Bakefile, a file compiler is generalization of this term: it’s a tool that compiles file or files of one object type into one or more files of another type. In this meaning, a C/C++ compiler is a file compiler, but so is a linker (it “compiles” object files into executables) or e.g. Lex/Yacc compiler or Qt’s MOC preprocessor.
-
commands
(toolset, target, input, output)¶ Returns list of commands (as
bkl.expr.Expr
) to invoke the compiler.Parameters: - toolset – Toolset used.
- target – The target object for which the invocation is done.
- input – Input file (
bkl.expr.PathExpr
) or files (bkl.expr.ListExpr
), depending on cardinality. - output –
bkl.expr.Expr
expression with the name of output file.
-
is_supported
(toolset)¶ Returns whether given toolset is supported by this compiler.
Default implementation returns True for all toolsets.
-
cardinality
= '1'¶ Cardinality of the compiler. That is, whether it compiles one file into one file (
FileCompiler.ONE_TO_ONE
, e.g. C compilers) or whether it compiles many files of the same type into one output file (FileCompiler.MANY_TO_ONE
, e.g. the linker or Java compiler).
-
in_type
= None¶ bkl.api.FileType
for compiler’s input file.
-
out_type
= None¶ bkl.api.FileType
for compiler’s output file.
-
-
class
bkl.api.
FileRecognizer
¶ Bases:
object
Mixin base class for extensions that handle certain file types and need to be associated with a file automatically. The class provides easy to use get_for_file() mechanism.
To use this class, derive from both
bkl.api.Extension
and this one.-
detect
(filename)¶ Returns True if the file filename is supported by the class. Note that it is only called if the file has one of the extensions listed in
extensions
. By default, returnsTrue
.Parameters: filename – Name of the file to check. Note that this is native filename (as a string) and points to existing file.
-
classmethod
get_for_file
(filename)¶ Returns appropriate implementation of the class for given file.
Throws
bkl.error.UnsupportedError
if no implementation could be found.Parameters: filename – Name of the file, as a native path.
-
extensions
= []¶ List of file extensions recognized by this extension, without dots (e.g.
["vcproj", "vcxproj"]
).
-
-
class
bkl.api.
FileType
(extensions=[])¶ Bases:
bkl.api.Extension
,bkl.api.FileRecognizer
Description of a file type. File types are used by
bkl.api.FileCompiler
to define both input and output files.-
extensions
¶ List of extensions for this file type, e.g.
["cpp", "cxx", "cc"]
.
-
-
class
bkl.api.
Property
(name, type, default=None, readonly=False, inheritable=False, doc=None)¶ Bases:
object
Properties describe variables on targets etc. that are part of the API – that is, they have special meaning for the toolset and. Unlike free-form variables, properties have a type associated with them and any values assigned to them are checked for type correctness. They can optionally have a default value, too.
-
name
¶ Name of the property/variable.
-
type
¶ Type of the property, as
bkl.vartypes.Type
instance.
-
default
¶ Default value of the property (as
bkl.expr.Expr
or a function that returns an expression) orNone
. If not specified (i.e.None
), then this property is required and must always be set to a value in the bakefile.
-
readonly
¶ Indicates if the property is read-only. Read-only properties can only have the default value and cannot be modified. They are typically derived from some other value and exist as a convenience. An example of read-only property is the
id
property on targets.
-
scopes
¶ Optional scope of the property, as list of strings. Each item may be one of
Property.SCOPE_PROJECT
,Property.SCOPE_MODULE
,Property.SCOPE_TARGET
for any target or target type name (e.g.program
) for scoping on specific target name.Finally, may be
None
for default (depending from where the property was obtained from).
-
inheritable
¶ A property is inheritable if its value can be specified in the (grand-)parent scope. For example, an inheritable property on a target may be specified at the module level or even in the parent module; an inheritable property on a source file (e.g. “defines”) may be specified on the target, the module and so on.
-
toolsets
¶ List of toolset names for toolsets this property applies to. This is mostly for documentation purposes, it doesn’t affect their processing. Is
None
for toolset-agnostic properties.
-
doc
¶ Optional documentation for the property.
Example usage:
class FooTarget(bkl.api.TargetType): name = "foo" properties = [ Property("deps", type=ListType(IdType()), default=[], doc="Target's dependencies (list of IDs).") ] ...
-
default_expr
(for_obj, throw_if_required)¶ Returns the value of
default
expression. Always returns anbkl.expr.Expr
instance, even if the default is of a different type.Parameters: - for_obj – The class:bkl.model.ModelPart object to return the default for. If the default value is defined, its expression is evaluated in the context of for_obj.
- throw_if_required – If False, returns NullExpr if the property is a required one (doesn’t have a default value). If True, throws in that case.
-
internal
¶ True if the property is for internal purposes and shouldn’t be used by users, False otherwise.
-
-
class
bkl.api.
TargetType
¶ Bases:
bkl.api.Extension
Base class for implementation of a new target type.
-
get_build_subgraph
(toolset, target)¶ Returns a
bkl.api.BuildSubgraph
object with description of this target’s local part of build graph – that is, its part needed to produce output files associated with this target.Usually, a BuildSubgraph with just one main BuildNode will be returned, but it’s possible to have TargetTypes that correspond to more than one makefile target (e.g. libtool-style libraries or gettext catalogs).
Parameters: - toolset – The toolset used (
bkl.api.Toolset
). - target – Target instance (
bkl.model.Target
).
- toolset – The toolset used (
-
vs_project
(toolset, target)¶ Returns Visual Studio project file object (derived from
bkl.plugins.vsbase.VSProjectBase
) if the target type can be implemented as a Visual Studio project.Implementing this method is strictly optional.
-
-
class
bkl.api.
Toolset
¶ Bases:
bkl.api.Extension
This class encapsulates generating of the project files or makefiles.
The term “toolset” refers to collection of tools (compiler, linker, make, IDE, …) used to compile programs. For example, “Visual C++ 2008”, “Visual C++ 2005”, “Xcode” or “Borland C++” are toolsets.
In Bakefile API, this class is responsible for creation of the output. It puts all the components (platform-specific commands, make syntax, compiler invocation, …) together and writes out the makefiles or projects.
-
generate
(project)¶ Generates all output files for this toolset.
Parameters: project – model.Project instance with complete description of the output. It was already preprocessed to remove content not relevant for this toolset (e.g. targets or sub-modules built conditionally only for other toolsets, conditionals that are always true or false within the toolset and so on).
-
get_builddir_for
(target)¶ Returns build directory used for target.
Returned value must be a
bkl.expr.PathExpr
expression object, but it doesn’t have to be a constant (for example, it may reference configuration name, as e.g. Visual Studio does).The function is called after the model is fully loaded and partially simplified, on a model already specialized for this toolset only. It is used to replace path expression with the relative @builddir anchor with absolute paths.
-
bkl.error
– exceptions and errors handling¶
This module contains helper classes for simple handling of errors. In
particular, the Error
class keeps track of the position in source code
where the error occurred or to which it relates to.
-
exception
bkl.error.
CannotDetermineError
(msg=None, pos=None)¶ Bases:
bkl.error.NonConstError
Exception thrown when something (e.g. equality) cannot be determined. This usually signifies a weakness in Bakefile implementation that should be improved.
-
exception
bkl.error.
Error
(msg, pos=None)¶ Bases:
exceptions.Exception
Base class for all Bakefile errors.
When converted to string, the message is formatted in the usual way of compilers, as
file:line: error
.-
msg
¶ Error message to show to the user.
-
pos
¶ bkl.parser.ast.Position
object with location of the error. May beNone
.
-
-
exception
bkl.error.
NonConstError
(msg, pos=None)¶ Bases:
bkl.error.Error
Exception thrown when attempting to convert an expression into bake-time constant.
-
exception
bkl.error.
NotFoundError
(msg, pos=None)¶ Bases:
bkl.error.Error
Exception thrown when a property or variable wasn’t found at all.
-
exception
bkl.error.
ParserError
(msg, pos=None)¶ Bases:
bkl.error.Error
Exception class for errors encountered by the Bakefile parser.
-
exception
bkl.error.
TypeError
(type, expr, msg=None, pos=None)¶ Bases:
bkl.error.Error
Exception class for variable type errors.
-
detail
¶ Any extra details about the error or (usually)
None
.
See also
Convenience constructor creates error message appropriate for the type and expression test, in the form of
expression expr is not type
orexpression expr is not type: msg
if additional message is supplied.Parameters: - type –
bkl.vartypes.Type
instance the error is related to. - expr –
bkl.expr.Expr
expression that caused the error. - msg – Optional error message detailing reasons for the error.
This will be stored as
detail
if provided.
-
-
exception
bkl.error.
UndefinedError
(msg, pos=None)¶ Bases:
bkl.error.Error
Exception thrown when a property or variable is undefined, i.e. doesn’t have a value.
-
exception
bkl.error.
UnsupportedError
(msg, pos=None)¶ Bases:
bkl.error.Error
Exception class for errors when something is unsupported, e.g. unrecognized file extension.
-
exception
bkl.error.
VersionError
(msg, pos=None)¶ Bases:
bkl.error.Error
Exception raised when Bakefile version is too old for the input.
-
class
bkl.error.
error_context
(context)¶ Error context for adding positional information to exceptions thrown without one. This can happen in some situations when the particular expression causing the error isn’t available. In such situations, it’s much better to provide coarse position information (e.g. a target) instead of not providing any at all.
Usage:
with error_context(target): ...do something that may throw...
-
pos
¶ bkl.parser.ast.Position
object with location of the error. May beNone
.
-
-
bkl.error.
warning
(msg, *args, **kwargs)¶ Logs a warning.
The function takes position arguments similarly to logging module’s functions. It also accepts options pos argument with position information as
bkl.parser.ast.Position
.Uses active
error_context
instances to decorate the warning with position information if not provided.Usage:
bkl.error.warning("target %s not supported", t.name, pos=t.source_pos)
bkl.io
– I/O helpers¶
Helper classes for Bakefile I/O. Manages atomic writing of output, detecting changes, line endings conversions etc.
-
class
bkl.io.
OutputFile
(filename, eol, charset='utf-8', creator=None, create_for=None)¶ Bases:
object
File to be written by Bakefile.
Example usage:
f = io.OutputFile("Makefile") f.write(body) f.commit()
Notice the need to explicitly call commit().
Creates output file.
Parameters: - filename – Name of the output file. Should be either relative to CWD or absolute; the latter is recommended.
- eol – Line endings to use. One of EOL_WINDOWS and EOL_UNIX.
- charset – Charset to use if Unicode string is passed to write().
- creator – Who is creating the file; typically toolset object.
- create_for – Object the file is created for, e.g. a module or a target.
-
replace
(placeholder, value)¶ Replaces the value of the given placeholder with its real value. This is useful for parts of the output which are not known at the time they are written because they depend on other parts coming after them.
Notice that only the first occurrency of the placeholder is replaced.
-
write
(text)¶ Writes text to the output, performing line endings conversion as needed. Note that the changes don’t take effect until you call commit().
bkl.makefile
– support for implementing makefiles toolsets¶
Foundation code for makefile-based toolsets.
All makefile-based toolsets should derive from MakefileToolset defined in this module.
-
class
bkl.makefile.
MakefileExprFormatter
(toolset, paths_info)¶ Bases:
bkl.expr.Formatter
-
literal
(e)¶ Called on
LiteralExpr
expressions.
-
path
(e)¶ Called on
PathExpr
expressions.
-
placeholder
(e)¶ Called on
PlaceholderExpr
expressions.
-
-
class
bkl.makefile.
MakefileFormatter
¶ Bases:
bkl.api.Extension
MakefileFormatter extensions are used to format makefiles content (i.e. targets and their commands) in the particular makefiles format.
This includes things such as expressing conditional content, referencing variables and so on.
Note that formatters do not handle platform- or compiler-specific things, e.g. path separators or compiler invocation. There are done by
bkl.expr.Formatter
andbkl.api.FileCompiler
classes.This base class implements methods that are common for most make variants; derived classes can override them and they must implement the rest.
-
comment
(text)¶ Returns given (possibly multi-line) string formatted as a comment.
Parameters: text – text of the comment
-
multifile_target
(outputs, outfiles, deps, commands)¶ Returns string with target definition for targets that produce multiple files. A typical example is Bison parser generator, which produces both .c and .h files.
Parameters: - outputs – List of output files of the rule, as objects.
- outfiles – List of output files of the rule, as strings.
- deps – See target()
- commands – See target()
-
submake_command
(directory, filename, target)¶ Returns string with command to invoke
make
in subdirectory directory on makefile filename, running target.
-
target
(name, deps, commands)¶ Returns string with target definition.
Parameters: - name – Name of the target.
- deps – List of its dependencies. Items are strings
corresponding to some target’s name (may be expressions
that reference a variable, in that case the string
must already be formatted with appropriate
bkl.expr.Formatter
). May be empty. - commands – List of commands to execute to build the target; they
are already formatted to be in make’s syntax and each
command in the list is single-line shell command.
May be
None
.
-
var_definition
(var, value)¶ Returns string with definition of a variable value, typically var = value.
Parameters: - var – variable being defined
- value – value of the variable; this string is already formatted to be in make’s syntax and may be multi-line
-
-
class
bkl.makefile.
MakefileToolset
¶ Bases:
bkl.api.Toolset
Base class for makefile-based toolsets.
-
ExprFormatter
¶ expr.Formatter
-derived class for this toolset.alias of
MakefileExprFormatter
-
generate
(project)¶ Generates all output files for this toolset.
Parameters: project – model.Project instance with complete description of the output. It was already preprocessed to remove content not relevant for this toolset (e.g. targets or sub-modules built conditionally only for other toolsets, conditionals that are always true or false within the toolset and so on).
-
get_builddir_for
(target)¶ Returns build directory used for target.
Returned value must be a
bkl.expr.PathExpr
expression object, but it doesn’t have to be a constant (for example, it may reference configuration name, as e.g. Visual Studio does).The function is called after the model is fully loaded and partially simplified, on a model already specialized for this toolset only. It is used to replace path expression with the relative @builddir anchor with absolute paths.
Called at the end of generating the output to add any ending text, for example unconditional inclusion of dependencies tracking code.
-
on_header
(file, module)¶ Called before starting generating the output to add any header text, typically used to pre-define any make variables.
Call the base class version first to insert a warning about the file being auto-generated.
-
on_phony_targets
(file, targets)¶ Called with a list of all phony (i.e. not producing actual files) targets (as their names as strings) when generating given file.
-
Formatter
= None¶ MakefileFormatter
-derived class for this toolset.
-
autoclean_extensions
= []¶ Files with extensions from this list will be automatically deleted by “make clean”.
-
default_makefile
= None¶ Default filename from output makefile.
-
del_command
= None¶ Command used to delete files
-
bkl.compilers
– FileCompiler helpers¶
Helpers for working with bkl.api.FileType
and
bkl.api.FileCompiler
extensions.
-
class
bkl.compilers.
CFileType
¶ Bases:
bkl.api.FileType
-
class
bkl.compilers.
CxxFileType
¶ Bases:
bkl.api.FileType
-
class
bkl.compilers.
NativeLibFileType
(extensions=[])¶ Bases:
bkl.api.FileType
-
class
bkl.compilers.
NativeLoadableModuleFileType
(extensions=[])¶ Bases:
bkl.api.FileType
-
class
bkl.compilers.
NativeProgramFileType
(extensions=[])¶ Bases:
bkl.api.FileType
Bases:
bkl.api.FileType
-
bkl.compilers.
disambiguate_intermediate_file_names
(files)¶ Given a list of SourceFile objects, finds files that would have conflicting object file names (e.g. foo/x.cpp and bar/x.cpp would use the same x.obj filename).
Returns dictionary with SourceFile objects as keys and unambiguous basenames (e.g. ‘x_foo’ and ‘x_bar’ for the above example). Only files with conflicts are included in the dictionary (consequently, it will be empty or near-empty most of the time).
-
bkl.compilers.
get_compilation_subgraph
(toolset, target, ft_to, outfile)¶ Given list of source files (as
bkl.expr.ListExpr
), produces build subgraph (bkl.api.BuildSubgraph
) with appropriatebkl.api.BuildNode
nodes.Parameters: - toolset – The toolset used (as
bkl.api.Toolset
). - target – The target object for which the invocation is done.
- ft_to – Type of the output file to compile to.
- outfile – Name of the output file (as
bkl.expr.PathExpr
).
- toolset – The toolset used (as
-
bkl.compilers.
get_compiler
(toolset, ft_from, ft_to)¶ Finds the compiler that compiles files of type ft_from into ft_to. Both arguments are
bkl.api.FileType
instances.The returned object is a singleton. If such compiler cannot be found, returns None.
-
bkl.compilers.
get_file_type
(extension)¶ Returns file type instance based on extension.
The returned object is a singleton.
>>> a = get_file_type("cpp") >>> b = get_file_type("cpp") >>> assert a is b
-
bkl.compilers.
get_file_types_compilable_into
(toolset, ft)¶ Returns file types that can be compiled into ft.
Internals reference documentation¶
bkl.parser
– language parser¶
-
bkl.parser.
get_parser
(code, filename=None)¶ Prepares Bakefile parser for parsing given Bakefile code from string argument passed in. The optional filename argument allows specifying input file name for the purpose of errors reporting.
-
bkl.parser.
parse
(code, filename=None, detect_compatibility_errors=True)¶ Reads Bakefile code from string argument passed in and returns parsed AST. The optional filename argument allows specifying input file name for the purpose of errors reporting.
bkl.parser.ast
– AST representation¶
-
class
bkl.parser.ast.
AndNode
(payload)¶ Bases:
bkl.parser.ast.BoolNode
-
class
bkl.parser.ast.
AppendNode
(payload)¶ Bases:
bkl.parser.ast.AssignmentNode
Assignment of value to a variable by appending (operator +=).
-
class
bkl.parser.ast.
AssignmentNode
(payload)¶ Bases:
bkl.parser.ast.Node
Assignment of value to a variable.
-
lvalue
¶ Variable assigning to, LvalueNode
-
value
¶ Value being assigned.
-
-
class
bkl.parser.ast.
BaseListNode
(payload)¶ Bases:
bkl.parser.ast.Node
List of base templates.
-
names
¶ List of strings with base names
-
-
class
bkl.parser.ast.
BoolNode
(payload)¶ Bases:
bkl.parser.ast.Node
-
left
¶ Left operand
-
operator
¶ Boolean operator (token type, e.g. AND)
-
right
¶ Right operand
-
-
class
bkl.parser.ast.
BoolvalNode
(payload)¶ Bases:
bkl.parser.ast.Node
Boolean constant (true/false).
-
value
¶ Value of the node, as boolean
-
-
class
bkl.parser.ast.
ConcatNode
(payload)¶ Bases:
bkl.parser.ast.Node
Concatenation of several parts, to form single string.
-
values
¶ List of fragments.
-
-
class
bkl.parser.ast.
ConfigurationNode
(payload)¶ Bases:
bkl.parser.ast.Node
Definition of a configuration.
-
base
¶ Name of the base configuration or None
-
content
¶ Other content: variables assignments and such
-
name
¶ Name of the configuration
-
-
class
bkl.parser.ast.
EqualNode
(payload)¶ Bases:
bkl.parser.ast.BoolNode
-
class
bkl.parser.ast.
FilesListNode
(payload)¶ Bases:
bkl.parser.ast.Node
Setting of sources/headers.
-
files
¶ List of files.
-
kind
¶ Sources/headers
-
-
class
bkl.parser.ast.
IdNode
(payload)¶ Bases:
bkl.parser.ast.Node
Identifier (variable, target, template, …).
-
class
bkl.parser.ast.
IfNode
(payload)¶ Bases:
bkl.parser.ast.Node
Conditional content node – “if” statement.
-
cond
¶ Condition expression
-
content
¶ Conditional statements
-
-
class
bkl.parser.ast.
ImportNode
(payload)¶ Bases:
bkl.parser.ast.Node
Textual inclusion of a file.
-
file
¶ File to include
-
-
class
bkl.parser.ast.
ListNode
(payload)¶ Bases:
bkl.parser.ast.Node
Right side of variable assignment, contains list of values (LiteralNode, VarReferenceNode etc.).
-
values
¶ List of values in the assignment. May be single value, maybe be multiple values, code using this must correctly interpret it and check values’ types.
-
-
class
bkl.parser.ast.
LiteralNode
(payload)¶ Bases:
bkl.parser.ast.Node
Single value, i.e. literal.
-
text
¶ Text of the value, as string.
-
-
class
bkl.parser.ast.
LvalueNode
(payload)¶ Bases:
bkl.parser.ast.Node
Left side of assignment.
-
scope
¶ List of scope identifiers; first one may be None for global.
-
var
¶ Variable assigning to
-
-
class
bkl.parser.ast.
NilNode
(payload=None)¶ Bases:
bkl.parser.ast.Node
Empty node.
-
class
bkl.parser.ast.
Node
(payload)¶ Bases:
antlr3.tree.CommonTree
Base class for Bakefile AST tree node.
-
toString
()¶ Override to say how a node (not a tree) should look as text
-
toStringTree
(indent='')¶ Print out a whole tree not just a node
-
-
class
bkl.parser.ast.
NotEqualNode
(payload)¶ Bases:
bkl.parser.ast.BoolNode
-
class
bkl.parser.ast.
NotNode
(payload)¶ Bases:
bkl.parser.ast.BoolNode
-
class
bkl.parser.ast.
OrNode
(payload)¶ Bases:
bkl.parser.ast.BoolNode
-
class
bkl.parser.ast.
PathAnchorNode
(payload)¶ Bases:
bkl.parser.ast.LiteralNode
A literal with path anchor (@srcdir etc.).
-
class
bkl.parser.ast.
PluginNode
(payload)¶ Bases:
bkl.parser.ast.Node
Inclusion of a plugin.
-
file
¶ File with plugin code
-
-
class
bkl.parser.ast.
Position
(filename=None, line=None, column=None)¶ Bases:
object
Location of an error in input file.
All of its attributes are optional and may be None. Convert the object to string to get human-readable output.
-
filename
¶ Name of the source file.
-
line
¶ Line number.
-
column
¶ Column on the line.
-
-
class
bkl.parser.ast.
RootNode
(payload)¶ Bases:
bkl.parser.ast.Node
Root node of loaded .bkl file.
-
class
bkl.parser.ast.
SettingNode
(payload)¶ Bases:
bkl.parser.ast.Node
Definition of a user setting.
-
content
¶ Properties assignments and such
-
name
¶ Name of the setting
-
-
class
bkl.parser.ast.
SrcdirNode
(payload)¶ Bases:
bkl.parser.ast.Node
Overriding of the @srcdir value.
-
srcdir
¶ The new srcdir directory
-
-
class
bkl.parser.ast.
SubmoduleNode
(payload)¶ Bases:
bkl.parser.ast.Node
Inclusion of a submodule.
-
file
¶ File with submodule definition
-
-
class
bkl.parser.ast.
TargetNode
(payload)¶ Bases:
bkl.parser.ast.Node
Creation of a makefile target.
-
base_templates
¶ List of names of base templates
-
content
¶ Other content: variables assignments and such
-
name
¶ Name of the target
-
type
¶ Type of the target
-
-
class
bkl.parser.ast.
TemplateNode
(payload)¶ Bases:
bkl.parser.ast.Node
Template definition node.
-
base_templates
¶ List of names of base templates
-
content
¶ Other content: variables assignments and such
-
name
¶ Name of the target
-
-
class
bkl.parser.ast.
VarReferenceNode
(payload)¶ Bases:
bkl.parser.ast.Node
Reference to a variable.
-
var
¶ Referenced variable
-
bkl.interpreter
– language interpreter¶
This module contains the very core of Bakefile – the interpreter,
bkl.interpreter.Interpreter
, and its supporting classes.
-
class
bkl.interpreter.
Interpreter
¶ Bases:
object
The interpreter is responsible for doing everything necessary to “translate” input
.bkl
files into generated native makefiles. This includes building a project model from the input, checking it for correctness, optimizing it and creating outputs for all enabled toolsets.Interpreter
provides both high-level interface for single-call usage (seeprocess()
) and other methods with finer granularity that allows you to inspect individual steps (most useful for the test suite).-
model
¶ Model of the project, as
bkl.model.Project
. It’s state always reflects current state of processing.
-
toolsets_to_use
¶ Set of toolsets to generate for. This list may contain only a subset of toolsets the bakefile is written for and may even contain toolsets not specified in the bakefile.
If
None
(the default), then the toolsets listed in the bakefile are used.
-
add_module
(ast, parent)¶ Adds parsed AST to the model, without doing any optimizations. May be called more than once, with different parsed files.
Parameters: ast – AST of the input file, as returned by bkl.parser.parse_file()
.
-
finalize
()¶ Finalizes the model, i.e. checks it for validity, optimizes, creates per-toolset models etc.
-
finalize_for_toolset
(toolset_model, toolset)¶ Finalizes after “toolset” variable was set.
-
generate
()¶ Generates output files.
-
generate_for_toolset
(toolset, skip_making_copy=False)¶ Generates output for given toolset.
-
limit_toolsets
(toolsets)¶ Sets
toolsets_to_use
.
-
make_toolset_specific_model
(toolset, skip_making_copy=False)¶ Returns toolset-specific model, i.e. one that works only with toolset, has the
toolset
property set to it. The caller still needs to call finalize_for_toolset() on it.
-
process
(ast)¶ Interprets input file and generates the outputs.
Parameters: ast – AST of the input file, as returned by bkl.parser.parse_file()
.Processing is done in several phases:
- Basic model is built (see
bkl.interpreter.builder.Builder
). No optimizations or checks are performed at this point. - Several generic optimization and checking passes are run on the model. Among other things, types correctness and other constraints are checked, variables are substituted and evaluated.
- The model is split into several copies, one per output toolset.
- Further optimization passes are done.
- Output files are generated.
Step 1 is done by
add_module()
. Steps 2-4 are done byfinalize()
and step 5 is implemented ingenerate()
.- Basic model is built (see
-
-
class
bkl.interpreter.builder.
Builder
(on_submodule=None)¶ Bases:
object
,bkl.expr.CondTrackingMixin
interpreter.Builder processes parsed AST and builds a project model from it.
It doesn’t do anything smart like optimizing things, it does only the minimal processing needed to produce a valid, albeit suboptimal, model.
This includes checking variables scopes etc., but does not involve checks for type correctness. Passes further in the
bkl.interpreter.Interpreter
pipeline handle that.-
context
¶ Current context. This is the inner-most
bkl.model.ModelPart
at the time of parsing. Initially, it is set to a newbkl.model.Module
instance bycreate_model()
. When descending into a target, it is temporarily set to said target and then restored and so on.
Constructor.
Parameters: on_module – Callback to call (with filename as argument) on submodule
statement.-
create_expression
(ast, parent)¶ Creates
bkl.epxr.Expr
expression in given parent’s context.
-
create_model
(ast, parent)¶ Returns constructed model, as
bkl.model.Module
instance.
-
Glossary¶
- bake-time
- The moment when the Bakefile tool
bkl
is run to create native makefiles and projects. Nothing is compiled at this time, only the makefiles are created. Compare with make-time. - make-time
- The moment when a generated makefile, project or solution is used by the user to build their project. Compare with bake-time.