5.2.2. Internals reference documentation

5.2.2.1. bkl – bootstrapping Bakefile

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

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

5.2.2.4. 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 (see process()) 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:

  1. Basic model is built (see bkl.interpreter.builder.Builder). No optimizations or checks are performed at this point.
  2. 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.
  3. The model is split into several copies, one per output toolset.
  4. Further optimization passes are done.
  5. Output files are generated.

Step 1 is done by add_module(). Steps 2-4 are done by finalize() and step 5 is implemented in generate().

process_file(filename)

Like process(), but takes filename as its argument.

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 new bkl.model.Module instance by create_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.

handle_children(children, context)

Runs model creation of all children nodes.

Parameters:
  • children – List of AST nodes to treat as children.
  • context – Context (aka “local scope”). Interpreter’s context is set to it for the duration of the call.