5.2.1. API reference documentation¶

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¶

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

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¶

Type for target IDs.

class bkl.vartypes.ListType(item_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¶

A file or directory name.

class bkl.vartypes.StringType¶

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

5.2.1.4. `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¶

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

bkl.api.Property

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¶

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, returns True.

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) or None. 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 an bkl.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¶

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`).

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.

properties = []¶: List of all properties supported on this target type, as Property instances. Note that properties list is automagically inherited from base classes, if any.

class bkl.api.Toolset¶

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.

properties = []¶: List of all properties supported on this target type, as Property instances. Note that properties list is automagically inherited from base classes, if any.

5.2.1.5. `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 be None.

exception bkl.error.NonConstError(msg, pos=None)¶

Exception thrown when attempting to convert an expression into bake-time constant.

exception bkl.error.NotFoundError(msg, pos=None)¶

Exception thrown when a property or variable wasn’t found at all.

exception bkl.error.ParserError(msg, pos=None)¶

Exception class for errors encountered by the Bakefile parser.

exception bkl.error.TypeError(type, expr, msg=None, pos=None)¶

Exception class for variable type errors.

detail¶: Any extra details about the error or (usually) None.

See also

bkl.vartypes.Type

Convenience constructor creates error message appropriate for the type and expression test, in the form of expression expr is not type or expression 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)¶

Exception thrown when a property or variable is undefined, i.e. doesn’t have a value.

exception bkl.error.UnsupportedError(msg, pos=None)¶

Exception class for errors when something is unsupported, e.g. unrecognized file extension.

exception bkl.error.VersionError(msg, pos=None)¶

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 be None.

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)

5.2.1.6. `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().

5.2.1.7. `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¶