blueprint: github.com/google/blueprint Index | Files | Directories

package blueprint

import "github.com/google/blueprint"

Blueprint is a meta-build system that reads in Blueprints files that describe modules that need to be built, and produces a Ninja (http://martine.github.io/ninja/) manifest describing the commands that need to be run and their dependencies. Where most build systems use built-in rules or a domain-specific language to describe the logic how modules are converted to build rules, Blueprint delegates this to per-project build logic written in Go. For large, heterogenous projects this allows the inherent complexity of the build logic to be maintained in a high-level language, while still allowing simple changes to individual modules by modifying easy to understand Blueprints files.

Blueprint uses a bootstrapping process to allow the code for Blueprint, the code for the build logic, and the code for the project being compiled to all live in the project. Dependencies between the layers are fully tracked - a change to the logic code will cause the logic to be recompiled, regenerate the project build manifest, and run modified project rules. A change to Blueprint itself will cause Blueprint to rebuild, and then rebuild the logic, etc.

A Blueprints file is a list of modules in a pseudo-python data format, where the module type looks like a function call, and the properties of the module look like optional arguments. For example, a simple module might look like:

cc_library {
    name: "cmd",
    srcs: [
        "main.c",
    ],
    deps: [
        "libc",
    ],
}

subdirs = ["subdir1", "subdir2"]

The modules from the top level Blueprints file and recursively through any subdirectories listed by the "subdirs" variable are read by Blueprint, and their properties are stored into property structs by module type. Once all modules are read, Blueprint calls any registered Mutators, in registration order. Mutators can visit each module top-down or bottom-up, and modify them as necessary. Common modifications include setting properties on modules to propagate information down from dependers to dependees (for example, telling a module what kinds of parents depend on it), or splitting a module into multiple variants (for example, one per architecture being compiled). After all Mutators have run, each module is asked to generate build rules based on property values, and then singletons can generate any build rules from the output of all modules.

The per-project build logic defines a top level command, referred to in the documentation as the "primary builder". This command is responsible for registering the module types needed for the project, as well as any singletons or mutators, and then calling into Blueprint with the path of the root Blueprint file.

Index

Package Files

context.go doc.go glob.go live_tracker.go mangle.go module_ctx.go name_interface.go ninja_defs.go ninja_strings.go ninja_writer.go package_ctx.go scope.go singleton_ctx.go unpack.go

Constants

const MockModuleListFile = "bplist"

Variables

var ErrBuildActionsNotReady = errors.New("build actions are not ready")

func HasFilter Uses

func HasFilter(field reflect.StructTag) (k, v string, err error)

type BaseDependencyTag Uses

type BaseDependencyTag struct {
}

type BaseModuleContext Uses

type BaseModuleContext interface {
    ModuleName() string
    ModuleDir() string
    Config() interface{}

    ContainsProperty(name string) bool
    Errorf(pos scanner.Position, fmt string, args ...interface{})
    ModuleErrorf(fmt string, args ...interface{})
    PropertyErrorf(property, fmt string, args ...interface{})
    Failed() bool

    // GlobWithDeps returns a list of files and directories that match the
    // specified pattern but do not match any of the patterns in excludes.
    // Any directories will have a '/' suffix.  It also adds efficient
    // dependencies to rerun the primary builder whenever a file matching
    // the pattern as added or removed, without rerunning if a file that
    // does not match the pattern is added to a searched directory.
    GlobWithDeps(pattern string, excludes []string) ([]string, error)

    Fs() pathtools.FileSystem
    AddNinjaFileDeps(deps ...string)

    Namespace() Namespace
    // contains filtered or unexported methods
}

type BlueprintError Uses

type BlueprintError struct {
    Err error            // the error that occurred
    Pos scanner.Position // the relevant Blueprints file location
}

An Error describes a problem that was encountered that is related to a particular location in a Blueprints file.

func (*BlueprintError) Error Uses

func (e *BlueprintError) Error() string

type BottomUpMutator Uses

type BottomUpMutator func(mctx BottomUpMutatorContext)

type BottomUpMutatorContext Uses

type BottomUpMutatorContext interface {
    AddDependency(module Module, tag DependencyTag, name ...string)
    AddReverseDependency(module Module, tag DependencyTag, name string)
    CreateVariations(...string) []Module
    CreateLocalVariations(...string) []Module
    SetDependencyVariation(string)
    AddVariationDependencies([]Variation, DependencyTag, ...string)
    AddFarVariationDependencies([]Variation, DependencyTag, ...string)
    AddInterVariantDependency(tag DependencyTag, from, to Module)
    ReplaceDependencies(string)
    // contains filtered or unexported methods
}

type BuildParams Uses

type BuildParams struct {
    Comment         string            // The comment that will appear above the definition.
    Depfile         string            // The dependency file name.
    Deps            Deps              // The format of the dependency file.
    Description     string            // The description that Ninja will print for the build.
    Rule            Rule              // The rule to invoke.
    Outputs         []string          // The list of explicit output targets.
    ImplicitOutputs []string          // The list of implicit output targets.
    Inputs          []string          // The list of explicit input dependencies.
    Implicits       []string          // The list of implicit input dependencies.
    OrderOnly       []string          // The list of order-only dependencies.
    Args            map[string]string // The variable/value pairs to set.
    Optional        bool              // Skip outputting a default statement
}

A BuildParams object contains the set of parameters that make up a Ninja build statement. Each field except for Args corresponds with a part of the Ninja build statement. The Args field contains variable names and values that are set within the build statement's scope in the Ninja file.

type Context Uses

type Context struct {
    context.Context
    // contains filtered or unexported fields
}

A Context contains all the state needed to parse a set of Blueprints files and generate a Ninja file. The process of generating a Ninja file proceeds through a series of four phases. Each phase corresponds with a some methods on the Context object

      Phase                            Methods
   ------------      -------------------------------------------
1. Registration         RegisterModuleType, RegisterSingletonType

2. Parse                    ParseBlueprintsFiles, Parse

3. Generate            ResolveDependencies, PrepareBuildActions

4. Write                           WriteBuildFile

The registration phase prepares the context to process Blueprints files containing various types of modules. The parse phase reads in one or more Blueprints files and validates their contents against the module types that have been registered. The generate phase then analyzes the parsed Blueprints contents to create an internal representation for the build actions that must be performed. This phase also performs validation of the module dependencies and property values defined in the parsed Blueprints files. Finally, the write phase generates the Ninja manifest text based on the generated build actions.

func NewContext Uses

func NewContext() *Context

NewContext creates a new Context object. The created context initially has no module or singleton factories registered, so the RegisterModuleFactory and RegisterSingletonFactory methods must be called before it can do anything useful.

func (*Context) AllTargets Uses

func (c *Context) AllTargets() (map[string]string, error)

AllTargets returns a map all the build target names to the rule used to build them. This is the same information that is output by running 'ninja -t targets all'. If this is called before PrepareBuildActions successfully completes then ErrbuildActionsNotReady is returned.

func (*Context) BlueprintFile Uses

func (c *Context) BlueprintFile(logicModule Module) string

func (*Context) FinalModule Uses

func (c *Context) FinalModule(module Module) Module

func (*Context) Globs Uses

func (c *Context) Globs() []GlobPath

func (*Context) ListModulePaths Uses

func (c *Context) ListModulePaths(baseDir string) (paths []string, err error)

func (*Context) MockFileSystem Uses

func (c *Context) MockFileSystem(files map[string][]byte)

MockFileSystem causes the Context to replace all reads with accesses to the provided map of filenames to contents stored as a byte slice.

func (*Context) ModuleDir Uses

func (c *Context) ModuleDir(logicModule Module) string

func (*Context) ModuleErrorf Uses

func (c *Context) ModuleErrorf(logicModule Module, format string,
    args ...interface{}) error

func (*Context) ModuleName Uses

func (c *Context) ModuleName(logicModule Module) string

func (*Context) ModulePath Uses

func (c *Context) ModulePath(logicModule Module) string

func (*Context) ModuleSubDir Uses

func (c *Context) ModuleSubDir(logicModule Module) string

func (*Context) ModuleType Uses

func (c *Context) ModuleType(logicModule Module) string

func (*Context) ModuleTypeFactories Uses

func (c *Context) ModuleTypeFactories() map[string]ModuleFactory

func (*Context) ModuleTypePropertyStructs Uses

func (c *Context) ModuleTypePropertyStructs() map[string][]interface{}

ModuleTypePropertyStructs returns a mapping from module type name to a list of pointers to property structs returned by the factory for that module type.

func (*Context) NinjaBuildDir Uses

func (c *Context) NinjaBuildDir() (string, error)

func (*Context) ParseBlueprintsFiles Uses

func (c *Context) ParseBlueprintsFiles(rootFile string) (deps []string, errs []error)

func (*Context) ParseFileList Uses

func (c *Context) ParseFileList(rootDir string, filePaths []string) (deps []string,
    errs []error)

ParseBlueprintsFiles parses a set of Blueprints files starting with the file at rootFile. When it encounters a Blueprints file with a set of subdirs listed it recursively parses any Blueprints files found in those subdirectories.

If no errors are encountered while parsing the files, the list of paths on which the future output will depend is returned. This list will include both Blueprints file paths as well as directory paths for cases where wildcard subdirs are found.

func (*Context) PrepareBuildActions Uses

func (c *Context) PrepareBuildActions(config interface{}) (deps []string, errs []error)

PrepareBuildActions generates an internal representation of all the build actions that need to be performed. This process involves invoking the GenerateBuildActions method on each of the Module objects created during the parse phase and then on each of the registered Singleton objects.

If the ResolveDependencies method has not already been called it is called automatically by this method.

The config argument is made available to all of the Module and Singleton objects via the Config method on the ModuleContext and SingletonContext objects passed to GenerateBuildActions. It is also passed to the functions specified via PoolFunc, RuleFunc, and VariableFunc so that they can compute config-specific values.

The returned deps is a list of the ninja files dependencies that were added by the modules and singletons via the ModuleContext.AddNinjaFileDeps(), SingletonContext.AddNinjaFileDeps(), and PackageContext.AddNinjaFileDeps() methods.

func (*Context) PrimaryModule Uses

func (c *Context) PrimaryModule(module Module) Module

func (*Context) RegisterBottomUpMutator Uses

func (c *Context) RegisterBottomUpMutator(name string, mutator BottomUpMutator) MutatorHandle

RegisterBottomUpMutator registers a mutator that will be invoked to split Modules into variants. Each registered mutator is invoked in registration order (mixing TopDownMutators and BottomUpMutators) once per Module, will not be invoked on a module until the invocations on all of the modules dependencies have returned.

The mutator type names given here must be unique to all bottom up or early mutators in the Context.

Returns a MutatorHandle, on which Parallel can be called to set the mutator to visit modules in parallel while maintaining ordering.

func (*Context) RegisterEarlyMutator Uses

func (c *Context) RegisterEarlyMutator(name string, mutator EarlyMutator)

RegisterEarlyMutator registers a mutator that will be invoked to split Modules into multiple variant Modules before any dependencies have been created. Each registered mutator is invoked in registration order once per Module (including each variant from previous early mutators). Module order is unpredictable.

In order for dependencies to be satisifed in a later pass, all dependencies of a module either must have an identical variant or must have no variations.

The mutator type names given here must be unique to all bottom up or early mutators in the Context.

Deprecated, use a BottomUpMutator instead. The only difference between EarlyMutator and BottomUpMutator is that EarlyMutator runs before the deprecated DynamicDependencies.

func (*Context) RegisterModuleType Uses

func (c *Context) RegisterModuleType(name string, factory ModuleFactory)

RegisterModuleType associates a module type name (which can appear in a Blueprints file) with a Module factory function. When the given module type name is encountered in a Blueprints file during parsing, the Module factory is invoked to instantiate a new Module object to handle the build action generation for the module. If a Mutator splits a module into multiple variants, the factory is invoked again to create a new Module for each variant.

The module type names given here must be unique for the context. The factory function should be a named function so that its package and name can be included in the generated Ninja file for debugging purposes.

The factory function returns two values. The first is the newly created Module object. The second is a slice of pointers to that Module object's properties structs. Each properties struct is examined when parsing a module definition of this type in a Blueprints file. Exported fields of the properties structs are automatically set to the property values specified in the Blueprints file. The properties struct field names determine the name of the Blueprints file properties that are used - the Blueprints property name matches that of the properties struct field name with the first letter converted to lower-case.

The fields of the properties struct must be either []string, a string, or bool. The Context will panic if a Module gets instantiated with a properties struct containing a field that is not one these supported types.

Any properties that appear in the Blueprints files that are not built-in module properties (such as "name" and "deps") and do not have a corresponding field in the returned module properties struct result in an error during the Context's parse phase.

As an example, the follow code:

type myModule struct {
    properties struct {
        Foo string
        Bar []string
    }
}

func NewMyModule() (blueprint.Module, []interface{}) {
    module := new(myModule)
    properties := &module.properties
    return module, []interface{}{properties}
}

func main() {
    ctx := blueprint.NewContext()
    ctx.RegisterModuleType("my_module", NewMyModule)
    // ...
}

would support parsing a module defined in a Blueprints file as follows:

my_module {
    name: "myName",
    foo:  "my foo string",
    bar:  ["my", "bar", "strings"],
}

The factory function may be called from multiple goroutines. Any accesses to global variables must be synchronized.

func (*Context) RegisterPreSingletonType Uses

func (c *Context) RegisterPreSingletonType(name string, factory SingletonFactory)

RegisterPreSingletonType registers a presingleton type that will be invoked to generate build actions before any Blueprint files have been read. Each registered presingleton type is instantiated and invoked exactly once at the beginning of the parse phase. Each registered presingleton is invoked in registration order.

The presingleton type names given here must be unique for the context. The factory function should be a named function so that its package and name can be included in the generated Ninja file for debugging purposes.

func (*Context) RegisterSingletonType Uses

func (c *Context) RegisterSingletonType(name string, factory SingletonFactory)

RegisterSingletonType registers a singleton type that will be invoked to generate build actions. Each registered singleton type is instantiated and and invoked exactly once as part of the generate phase. Each registered singleton is invoked in registration order.

The singleton type names given here must be unique for the context. The factory function should be a named function so that its package and name can be included in the generated Ninja file for debugging purposes.

func (*Context) RegisterTopDownMutator Uses

func (c *Context) RegisterTopDownMutator(name string, mutator TopDownMutator) MutatorHandle

RegisterTopDownMutator registers a mutator that will be invoked to propagate dependency info top-down between Modules. Each registered mutator is invoked in registration order (mixing TopDownMutators and BottomUpMutators) once per Module, and the invocation on any module will have returned before it is in invoked on any of its dependencies.

The mutator type names given here must be unique to all top down mutators in the Context.

Returns a MutatorHandle, on which Parallel can be called to set the mutator to visit modules in parallel while maintaining ordering.

func (*Context) ResolveDependencies Uses

func (c *Context) ResolveDependencies(config interface{}) (deps []string, errs []error)

ResolveDependencies checks that the dependencies specified by all of the modules defined in the parsed Blueprints files are valid. This means that the modules depended upon are defined and that no circular dependencies exist.

func (*Context) SetAllowMissingDependencies Uses

func (c *Context) SetAllowMissingDependencies(allowMissingDependencies bool)

SetAllowMissingDependencies changes the behavior of Blueprint to ignore unresolved dependencies. If the module's GenerateBuildActions calls ModuleContext.GetMissingDependencies Blueprint will not emit any errors for missing dependencies.

func (*Context) SetIgnoreUnknownModuleTypes Uses

func (c *Context) SetIgnoreUnknownModuleTypes(ignoreUnknownModuleTypes bool)

SetIgnoreUnknownModuleTypes sets the behavior of the context in the case where it encounters an unknown module type while parsing Blueprints files. By default, the context will report unknown module types as an error. If this method is called with ignoreUnknownModuleTypes set to true then the context will silently ignore unknown module types.

This method should generally not be used. It exists to facilitate the bootstrapping process.

func (*Context) SetModuleListFile Uses

func (c *Context) SetModuleListFile(listFile string)

func (*Context) SetNameInterface Uses

func (c *Context) SetNameInterface(i NameInterface)

func (*Context) VisitAllModuleVariants Uses

func (c *Context) VisitAllModuleVariants(module Module,
    visit func(Module))

func (*Context) VisitAllModules Uses

func (c *Context) VisitAllModules(visit func(Module))

func (*Context) VisitAllModulesIf Uses

func (c *Context) VisitAllModulesIf(pred func(Module) bool,
    visit func(Module))

func (*Context) VisitDepsDepthFirst Uses

func (c *Context) VisitDepsDepthFirst(module Module, visit func(Module))

func (*Context) VisitDepsDepthFirstIf Uses

func (c *Context) VisitDepsDepthFirstIf(module Module, pred func(Module) bool, visit func(Module))

func (*Context) VisitDirectDeps Uses

func (c *Context) VisitDirectDeps(module Module, visit func(Module))

func (*Context) VisitDirectDepsIf Uses

func (c *Context) VisitDirectDepsIf(module Module, pred func(Module) bool, visit func(Module))

func (*Context) WalkBlueprintsFiles Uses

func (c *Context) WalkBlueprintsFiles(rootDir string, filePaths []string,
    visitor FileHandler) (deps []string, errs []error)

WalkBlueprintsFiles walks a set of Blueprints files starting with the given filepaths, calling the given file handler on each

When WalkBlueprintsFiles encounters a Blueprints file with a set of subdirs listed, it recursively parses any Blueprints files found in those subdirectories.

If any of the file paths is an ancestor directory of any other of file path, the ancestor will be parsed and visited first.

the file handler will be called from a goroutine, so it must be reentrant.

If no errors are encountered while parsing the files, the list of paths on which the future output will depend is returned. This list will include both Blueprints file paths as well as directory paths for cases where wildcard subdirs are found.

visitor will be called asynchronously, and will only be called once visitor for each ancestor directory has completed.

WalkBlueprintsFiles will not return until all calls to visitor have returned.

func (*Context) WriteBuildFile Uses

func (c *Context) WriteBuildFile(w io.Writer) error

WriteBuildFile writes the Ninja manifeset text for the generated build actions to w. If this is called before PrepareBuildActions successfully completes then ErrBuildActionsNotReady is returned.

type DependencyTag Uses

type DependencyTag interface {
    // contains filtered or unexported methods
}

DependencyTag is an interface to an arbitrary object that embeds BaseDependencyTag. It can be used to transfer information on a dependency between the mutator that called AddDependency and the GenerateBuildActions method. Variants created by CreateVariations have a copy of the interface (pointing to the same concrete object) from their original module.

type Deps Uses

type Deps int

A Deps value indicates the dependency file format that Ninja should expect to be output by a compiler.

const (
    DepsNone Deps = iota
    DepsGCC
    DepsMSVC
)

func (Deps) String Uses

func (d Deps) String() string

type DynamicDependerModule Uses

type DynamicDependerModule interface {
    Module

    // DynamicDependencies is called by the Context that created the
    // DynamicDependerModule during its generate phase.  This call should return
    // the list of module names that the DynamicDependerModule depends on
    // dynamically.  Module names that already appear in the "deps" property may
    // but do not need to be included in the returned list.
    DynamicDependencies(DynamicDependerModuleContext) []string
}

A DynamicDependerModule is a Module that may add dependencies that do not appear in its "deps" property. Any Module that implements this interface will have its DynamicDependencies method called by the Context that created it during generate phase.

Deprecated, use a BottomUpMutator instead

type DynamicDependerModuleContext Uses

type DynamicDependerModuleContext BottomUpMutatorContext

type EarlyMutator Uses

type EarlyMutator func(mctx EarlyMutatorContext)

type EarlyMutatorContext Uses

type EarlyMutatorContext interface {
    CreateVariations(...string) []Module
    CreateLocalVariations(...string) []Module
    // contains filtered or unexported methods
}

type FileHandler Uses

type FileHandler func(*parser.File)

type GlobPath Uses

type GlobPath struct {
    Pattern  string
    Excludes []string
    Files    []string
    Deps     []string
    Name     string
}

type Module Uses

type Module interface {
    // Name returns a string used to uniquely identify each module.  The return
    // value must be unique across all modules.  It is only called once, during
    // initial blueprint parsing.  To change the name later a mutator must call
    // MutatorContext.Rename
    //
    // In most cases, Name should return the contents of a "name:" property from
    // the blueprint file.  An embeddable SimpleName object can be used for this
    // case.
    Name() string

    // GenerateBuildActions is called by the Context that created the Module
    // during its generate phase.  This call should generate all Ninja build
    // actions (rules, pools, and build statements) needed to build the module.
    GenerateBuildActions(ModuleContext)
}

A Module handles generating all of the Ninja build actions needed to build a single module based on properties defined in a Blueprints file. Module objects are initially created during the parse phase of a Context using one of the registered module types (and the associated ModuleFactory function). The Module's properties struct is automatically filled in with the property values specified in the Blueprints file (see Context.RegisterModuleType for more information on this).

A Module can be split into multiple Modules by a Mutator. All existing properties set on the module will be duplicated to the new Module, and then modified as necessary by the Mutator.

The Module implementation can access the build configuration as well as any modules on which on which it depends (as defined by the "deps" property specified in the Blueprints file, dynamically added by implementing the (deprecated) DynamicDependerModule interface, or dynamically added by a BottomUpMutator) using the ModuleContext passed to GenerateBuildActions. This ModuleContext is also used to create Ninja build actions and to report errors to the user.

In addition to implementing the GenerateBuildActions method, a Module should implement methods that provide dependant modules and singletons information they need to generate their build actions. These methods will only be called after GenerateBuildActions is called because the Context calls GenerateBuildActions in dependency-order (and singletons are invoked after all the Modules). The set of methods a Module supports will determine how dependant Modules interact with it.

For example, consider a Module that is responsible for generating a library that other modules can link against. The library Module might implement the following interface:

type LibraryProducer interface {
    LibraryFileName() string
}

func IsLibraryProducer(module blueprint.Module) {
    _, ok := module.(LibraryProducer)
    return ok
}

A binary-producing Module that depends on the library Module could then do:

func (m *myBinaryModule) GenerateBuildActions(ctx blueprint.ModuleContext) {
    ...
    var libraryFiles []string
    ctx.VisitDepsDepthFirstIf(IsLibraryProducer,
        func(module blueprint.Module) {
            libProducer := module.(LibraryProducer)
            libraryFiles = append(libraryFiles, libProducer.LibraryFileName())
        })
    ...
}

to build the list of library file names that should be included in its link command.

GenerateBuildActions may be called from multiple threads. It is guaranteed to be called after it has finished being called on all dependencies and on all variants of that appear earlier in the ModuleContext.VisitAllModuleVariants list. Any accesses to global variables or to Module objects that are not dependencies or variants of the current Module must be synchronized by the implementation of GenerateBuildActions.

type ModuleContext Uses

type ModuleContext interface {
    BaseModuleContext

    OtherModuleName(m Module) string
    OtherModuleErrorf(m Module, fmt string, args ...interface{})
    OtherModuleDependencyTag(m Module) DependencyTag

    GetDirectDepWithTag(name string, tag DependencyTag) Module
    GetDirectDep(name string) (Module, DependencyTag)

    VisitDirectDeps(visit func(Module))
    VisitDirectDepsIf(pred func(Module) bool, visit func(Module))
    VisitDepsDepthFirst(visit func(Module))
    VisitDepsDepthFirstIf(pred func(Module) bool, visit func(Module))
    WalkDeps(visit func(child, parent Module) bool)

    ModuleSubDir() string

    Variable(pctx PackageContext, name, value string)
    Rule(pctx PackageContext, name string, params RuleParams, argNames ...string) Rule
    Build(pctx PackageContext, params BuildParams)

    PrimaryModule() Module
    FinalModule() Module
    VisitAllModuleVariants(visit func(Module))

    GetMissingDependencies() []string
}

type ModuleError Uses

type ModuleError struct {
    BlueprintError
    // contains filtered or unexported fields
}

A ModuleError describes a problem that was encountered that is related to a particular module in a Blueprints file

func (*ModuleError) Error Uses

func (e *ModuleError) Error() string

type ModuleFactory Uses

type ModuleFactory func() (m Module, propertyStructs []interface{})

A ModuleFactory function creates a new Module object. See the Context.RegisterModuleType method for details about how a registered ModuleFactory is used by a Context.

type ModuleGroup Uses

type ModuleGroup struct {
    // contains filtered or unexported fields
}

A ModuleGroup just points to a moduleGroup to allow external packages to refer to a moduleGroup but not use it

func (*ModuleGroup) String Uses

func (h *ModuleGroup) String() string

type MutatorHandle Uses

type MutatorHandle interface {
    // Set the mutator to visit modules in parallel while maintaining ordering.  Calling any
    // method on the mutator context is thread-safe, but the mutator must handle synchronization
    // for any modifications to global state or any modules outside the one it was invoked on.
    Parallel() MutatorHandle
}

type NameInterface Uses

type NameInterface interface {
    // Gets called when a new module is created
    NewModule(ctx NamespaceContext, group ModuleGroup, module Module) (namespace Namespace, err []error)

    // Finds the module with the given name
    ModuleFromName(moduleName string, namespace Namespace) (group ModuleGroup, found bool)

    // Returns an error indicating that the given module could not be found.
    // The error contains some diagnostic information about where the dependency can be found.
    MissingDependencyError(depender string, dependerNamespace Namespace, depName string) (err error)

    // Rename
    Rename(oldName string, newName string, namespace Namespace) []error

    // Returns all modules in a deterministic order.
    AllModules() []ModuleGroup

    // gets the namespace for a given path
    GetNamespace(ctx NamespaceContext) (namespace Namespace)

    // returns a deterministic, unique, arbitrary string for the given name in the given namespace
    UniqueName(ctx NamespaceContext, name string) (unique string)
}

A NameInterface tells how to locate modules by name. There should only be one name interface per Context, but potentially many namespaces

type Namespace Uses

type Namespace interface {
    // contains filtered or unexported methods
}

The Namespace interface is just a marker interface for usage by the NameInterface, to allow a NameInterface to specify that a certain parameter should be a Namespace. In practice, a specific NameInterface will expect to only give and receive structs of the same concrete type, but because Go doesn't support generics, we use a marker interface for a little bit of clarity, and expect implementers to do typecasting instead.

type NamespaceContext Uses

type NamespaceContext interface {
    ModulePath() string
}

A NamespaceContext stores the information given to a NameInterface to enable the NameInterface to choose the namespace for any given module

type NamespaceMarker Uses

type NamespaceMarker struct {
}

type PackageContext Uses

type PackageContext interface {
    Import(pkgPath string)
    ImportAs(as, pkgPath string)

    StaticVariable(name, value string) Variable
    VariableFunc(name string, f func(config interface{}) (string, error)) Variable
    VariableConfigMethod(name string, method interface{}) Variable

    StaticPool(name string, params PoolParams) Pool
    PoolFunc(name string, f func(interface{}) (PoolParams, error)) Pool

    StaticRule(name string, params RuleParams, argNames ...string) Rule
    RuleFunc(name string, f func(interface{}) (RuleParams, error), argNames ...string) Rule

    AddNinjaFileDeps(deps ...string)
    // contains filtered or unexported methods
}

A PackageContext provides a way to create package-scoped Ninja pools, rules, and variables. A Go package should create a single unexported package-scoped PackageContext variable that it uses to create all package- scoped Ninja object definitions. This PackageContext object should then be passed to all calls to define module- or singleton-specific Ninja definitions. For example:

package blah

import (
    "blueprint"
)

var (
    pctx = NewPackageContext("path/to/blah")

    myPrivateVar = pctx.StaticVariable("myPrivateVar", "abcdef")
    MyExportedVar = pctx.StaticVariable("MyExportedVar", "$myPrivateVar 123456!")

    SomeRule = pctx.StaticRule(...)
)

// ...

func (m *MyModule) GenerateBuildActions(ctx blueprint.Module) {
    ctx.Build(pctx, blueprint.BuildParams{
        Rule:    SomeRule,
        Outputs: []string{"$myPrivateVar"},
    })
}

func NewPackageContext Uses

func NewPackageContext(pkgPath string) PackageContext

NewPackageContext creates a PackageContext object for a given package. The pkgPath argument should always be set to the full path used to import the package. This function may only be called from a Go package's init() function or as part of a package-scoped variable initialization.

type Pool Uses

type Pool interface {
    String() string
    // contains filtered or unexported methods
}

A Pool represents a Ninja pool that will be written to the output .ninja file.

var Console Pool = NewBuiltinPool("console")

func NewBuiltinPool Uses

func NewBuiltinPool(name string) Pool

NewBuiltinPool returns a Pool object that refers to a pool name created outside of Blueprint

type PoolParams Uses

type PoolParams struct {
    Comment string // The comment that will appear above the definition.
    Depth   int    // The Ninja pool depth.
}

A PoolParams object contains the set of parameters that make up a Ninja pool definition.

type PropertyError Uses

type PropertyError struct {
    ModuleError
    // contains filtered or unexported fields
}

A PropertyError describes a problem that was encountered that is related to a particular property in a Blueprints file

func (*PropertyError) Error Uses

func (e *PropertyError) Error() string

type Rule Uses

type Rule interface {
    String() string
    // contains filtered or unexported methods
}

A Rule represents a Ninja build rule that will be written to the output .ninja file.

var Phony Rule = NewBuiltinRule("phony")

func NewBuiltinRule Uses

func NewBuiltinRule(name string) Rule

NewBuiltinRule returns a Rule object that refers to a rule that was created outside of Blueprint

type RuleParams Uses

type RuleParams struct {
    // These fields correspond to a Ninja variable of the same name.
    Command        string // The command that Ninja will run for the rule.
    Depfile        string // The dependency file name.
    Deps           Deps   // The format of the dependency file.
    Description    string // The description that Ninja will print for the rule.
    Generator      bool   // Whether the rule generates the Ninja manifest file.
    Pool           Pool   // The Ninja pool to which the rule belongs.
    Restat         bool   // Whether Ninja should re-stat the rule's outputs.
    Rspfile        string // The response file.
    RspfileContent string // The response file content.

    // These fields are used internally in Blueprint
    CommandDeps      []string // Command-specific implicit dependencies to prepend to builds
    CommandOrderOnly []string // Command-specific order-only dependencies to prepend to builds
    Comment          string   // The comment that will appear above the definition.
}

A RuleParams object contains the set of parameters that make up a Ninja rule definition.

type SimpleName Uses

type SimpleName struct {
    Properties struct {
        Name string
    }
}

SimpleName is an embeddable object to implement the ModuleContext.Name method using a property called "name". Modules that embed it must also add SimpleName.Properties to their property structure list.

func (*SimpleName) Name Uses

func (s *SimpleName) Name() string

type SimpleNameInterface Uses

type SimpleNameInterface struct {
    // contains filtered or unexported fields
}

a SimpleNameInterface just stores all modules in a map based on name

func NewSimpleNameInterface Uses

func NewSimpleNameInterface() *SimpleNameInterface

func (*SimpleNameInterface) AllModules Uses

func (s *SimpleNameInterface) AllModules() []ModuleGroup

func (*SimpleNameInterface) GetNamespace Uses

func (s *SimpleNameInterface) GetNamespace(ctx NamespaceContext) Namespace

func (*SimpleNameInterface) MissingDependencyError Uses

func (s *SimpleNameInterface) MissingDependencyError(depender string, dependerNamespace Namespace, dependency string) (err error)

func (*SimpleNameInterface) ModuleFromName Uses

func (s *SimpleNameInterface) ModuleFromName(moduleName string, namespace Namespace) (group ModuleGroup, found bool)

func (*SimpleNameInterface) NewModule Uses

func (s *SimpleNameInterface) NewModule(ctx NamespaceContext, group ModuleGroup, module Module) (namespace Namespace, err []error)

func (*SimpleNameInterface) Rename Uses

func (s *SimpleNameInterface) Rename(oldName string, newName string, namespace Namespace) (errs []error)

func (*SimpleNameInterface) UniqueName Uses

func (s *SimpleNameInterface) UniqueName(ctx NamespaceContext, name string) (unique string)

type Singleton Uses

type Singleton interface {
    GenerateBuildActions(SingletonContext)
}

type SingletonContext Uses

type SingletonContext interface {
    Config() interface{}

    ModuleName(module Module) string
    ModuleDir(module Module) string
    ModuleSubDir(module Module) string
    ModuleType(module Module) string
    BlueprintFile(module Module) string

    ModuleErrorf(module Module, format string, args ...interface{})
    Errorf(format string, args ...interface{})
    Failed() bool

    Variable(pctx PackageContext, name, value string)
    Rule(pctx PackageContext, name string, params RuleParams, argNames ...string) Rule
    Build(pctx PackageContext, params BuildParams)
    RequireNinjaVersion(major, minor, micro int)

    // SetNinjaBuildDir sets the value of the top-level "builddir" Ninja variable
    // that controls where Ninja stores its build log files.  This value can be
    // set at most one time for a single build, later calls are ignored.
    SetNinjaBuildDir(pctx PackageContext, value string)

    // AddSubninja adds a ninja file to include with subninja. This should likely
    // only ever be used inside bootstrap to handle glob rules.
    AddSubninja(file string)

    // Eval takes a string with embedded ninja variables, and returns a string
    // with all of the variables recursively expanded. Any variables references
    // are expanded in the scope of the PackageContext.
    Eval(pctx PackageContext, ninjaStr string) (string, error)

    VisitAllModules(visit func(Module))
    VisitAllModulesIf(pred func(Module) bool, visit func(Module))
    VisitDepsDepthFirst(module Module, visit func(Module))
    VisitDepsDepthFirstIf(module Module, pred func(Module) bool,
        visit func(Module))

    VisitAllModuleVariants(module Module, visit func(Module))

    PrimaryModule(module Module) Module
    FinalModule(module Module) Module

    AddNinjaFileDeps(deps ...string)

    // GlobWithDeps returns a list of files and directories that match the
    // specified pattern but do not match any of the patterns in excludes.
    // Any directories will have a '/' suffix. It also adds efficient
    // dependencies to rerun the primary builder whenever a file matching
    // the pattern as added or removed, without rerunning if a file that
    // does not match the pattern is added to a searched directory.
    GlobWithDeps(pattern string, excludes []string) ([]string, error)

    Fs() pathtools.FileSystem
}

type SingletonFactory Uses

type SingletonFactory func() Singleton

A SingletonFactory function creates a new Singleton object. See the Context.RegisterSingletonType method for details about how a registered SingletonFactory is used by a Context.

type TopDownMutator Uses

type TopDownMutator func(mctx TopDownMutatorContext)

A Mutator function is called for each Module, and can use MutatorContext.CreateVariations to split a Module into multiple Modules, modifying properties on the new modules to differentiate them. It is called after parsing all Blueprint files, but before generating any build rules, and is always called on dependencies before being called on the depending module.

The Mutator function should only modify members of properties structs, and not members of the module struct itself, to ensure the modified values are copied if a second Mutator chooses to split the module a second time.

type TopDownMutatorContext Uses

type TopDownMutatorContext interface {
    OtherModuleName(m Module) string
    OtherModuleErrorf(m Module, fmt string, args ...interface{})
    OtherModuleDependencyTag(m Module) DependencyTag

    CreateModule(ModuleFactory, ...interface{})

    GetDirectDepWithTag(name string, tag DependencyTag) Module
    GetDirectDep(name string) (Module, DependencyTag)

    VisitDirectDeps(visit func(Module))
    VisitDirectDepsIf(pred func(Module) bool, visit func(Module))
    VisitDepsDepthFirst(visit func(Module))
    VisitDepsDepthFirstIf(pred func(Module) bool, visit func(Module))
    WalkDeps(visit func(Module, Module) bool)
    // contains filtered or unexported methods
}

type Variable Uses

type Variable interface {
    String() string
    // contains filtered or unexported methods
}

A Variable represents a global Ninja variable definition that will be written to the output .ninja file. A variable may contain references to other global Ninja variables, but circular variable references are not allowed.

type Variation Uses

type Variation struct {
    // Mutator is the axis on which this variation applies, i.e. "arch" or "link"
    Mutator string
    // Variation is the name of the variation on the axis, i.e. "arm" or "arm64" for arch, or
    // "shared" or "static" for link.
    Variation string
}

A Variation is a way that a variant of a module differs from other variants of the same module. For example, two variants of the same module might have Variation{"arch","arm"} and Variation{"arch","arm64"}

Directories

PathSynopsis
bootstrapThe Blueprint bootstrapping mechanism is intended to enable building a source tree with minimal prebuilts.
bootstrap/bpdoc
bootstrap/bpglobbpglob is the command line tool that checks if the list of files matching a glob has changed, and only updates the output file list if it has changed.
bootstrap/minibp
bpfmt
bpmodify
deptools
gotestmain
gotestrunner
loadplugins
microfactoryMicrofactory is a tool to incrementally compile a go program.
microfactory/main
parser
pathtools
proptools

Package blueprint imports 24 packages (graph) and is imported by 15 packages. Updated 2019-02-18. Refresh now. Tools for package owners.