bootstrap

Documentation

Overview

The Blueprint bootstrapping mechanism is intended to enable building a source tree with minimal prebuilts. The only prerequisites for performing such a build are:

1. A Ninja binary
2. A script interpreter (e.g. Bash or Python)
3. A Go toolchain

The Primary Builder

As part of the bootstrapping process, a binary called the "primary builder" is created. This primary builder is the binary that includes both the core Blueprint library and the build logic specific to the source tree. It is used to generate the Ninja file that describes how to build the entire source tree.

The primary builder must be a pure Go (i.e. no cgo) module built with the module type 'bootstrap_go_binary'. It should have the 'primaryBuilder' module property set to true in its Blueprints file. If more than one module sets primaryBuilder to true the build will fail.

The primary builder main function should look something like:

package main

import (
    "flag"
    "git.halogenos.org/xdevs23/blueprint"
    "git.halogenos.org/xdevs23/blueprint/bootstrap"
    "path/filepath"

    "my/custom/build/logic"
)

func main() {
    // The primary builder should use the global flag set because the
    // bootstrap package registers its own flags there.
    flag.Parse()

    // The top-level Blueprints file is passed as the first argument.
    srcDir := filepath.Dir(flag.Arg(0))

    // Create the build context.
    ctx := blueprint.NewContext()

    // Register custom module types
    ctx.RegisterModuleType("foo", logic.FooModule)
    ctx.RegisterModuleType("bar", logic.BarModule)

    // Register custom singletons
    ctx.RegisterSingleton("baz", logic.NewBazSingleton())

    // Create and initialize the custom Config object.
    config := logic.NewConfig(srcDir)

    // This call never returns
    bootstrap.Main(ctx, config)
}

Required Source Files

There are three files that must be included in the source tree to facilitate the build bootstrapping:

1. The top-level Blueprints file
2. The bootstrap script
3. The build wrapper script

The top-level Blueprints file describes how the entire source tree should be built. It must have a 'subdirs' assignment that includes both the core Blueprint library and the custom build logic for the source tree. It should also include (either directly or through a subdirs entry) describe all the modules to be built in the source tree.

The bootstrap script is a small script to setup the build directory, writing a couple configuration files (including the path the source directory, information about the Go build environment, etc), then copying the build wrapper into the build directory.

The Bootstrapping Process

There are three stages to the bootstrapping process, each with a corresponding Ninja file. The stages are referred to as the "bootstrap", "primary", and "main" stages. Each stage builds the next stage's Ninja file.

The bootstrapping process begins with the user running the bootstrap script to initialize a new build directory. The script is run from the build directory, and creates a ".minibootstrap/build.ninja" file that sets a few variables then includes blueprint's "bootstrap/build.ninja". It also writes out a ".blueprint.bootstrap" file that contains a few variables for later use:

BLUEPRINT_BOOTSTRAP_VERSION - Used to detect when a user needs to run
                              bootstrap.bash again

SRCDIR         - The path to the source directory
BLUEPRINTDIR   - The path to the blueprints directory (includes $SRCDIR)
GOROOT         - The path to the root directory of the Go toolchain
NINJA_BUILDDIR - The path to store .ninja_log, .ninja_deps

Once the script completes the build directory is initialized and ready to run a build. A wrapper script (blueprint.bash by default) has been installed in order to run a build. It iterates through the three stages of the build:

• Runs microfactory.bash to build minibp
• Runs the .minibootstrap/build.ninja to build .bootstrap/build.ninja
• Runs .bootstrap/build.ninja to build and run the primary builder
• Runs build.ninja to build your code

Microfactory takes care of building an up to date version of `minibp` and `bpglob` under the .minibootstrap/ directory.

During <builddir>/.minibootstrap/build.ninja, the following actions are taken, if necessary:

• Run minibp to generate .bootstrap/build.ninja (Primary stage)
• Includes .minibootstrap/build-globs.ninja, which defines rules to run bpglob during incremental builds. These outputs are listed in the dependency file output by minibp.

During the <builddir>/.bootstrap/build.ninja, the following actions are taken, if necessary:

• Build the primary builder, anything marked `default: true`, and any dependencies.
• Run the primary builder to generate build.ninja
• Run the primary builder to extract documentation
• Includes .bootstrap/build-globs.ninja, which defines rules to run bpglob during incremental builds. These outputs are listed in the dependency file output by the primary builder.

Then the main stage is at <builddir>/build.ninja, and will contain all the rules generated by the primary builder. In addition, the bootstrap code adds a phony rule "blueprint_tools" that depends on all blueprint_go_binary rules (bpfmt, bpmodify, etc).

Index

• Variables
• func GlobFile(ctx GlobFileContext, pattern string, excludes []string, ...)
• func Main(ctx *blueprint.Context, config interface{}, extraNinjaFileDeps ...string)
• func ModuleTypeDocs(ctx *blueprint.Context, factories map[string]reflect.Value) ([]*bpdoc.Package, error)
• type Config
• type ConfigBlueprintToolLocation
• type ConfigInterface
• type ConfigRemoveAbandonedFilesUnder
• type ConfigStopBefore
• type GlobFileContext
• type GoBinaryTool
• type Stage
• type StopBefore

Variables

var (
	BuildDir      string
	NinjaBuildDir string
	SrcDir        string
)

var (

	// globRule rule traverses directories to produce a list of files that match $glob
	// and writes it to $out if it has changed, and writes the directories to $out.d
	GlobRule = pctx.StaticRule("GlobRule",
		blueprint.RuleParams{
			Command:     fmt.Sprintf(`%s -o $out $excludes "$glob"`, globCmd),
			CommandDeps: []string{globCmd},
			Description: "glob $glob",

			Restat:  true,
			Deps:    blueprint.DepsGCC,
			Depfile: "$out.d",
		},
		"glob", "excludes")
)

Functions

func GlobFile

func GlobFile(ctx GlobFileContext, pattern string, excludes []string,
	fileListFile, depFile string)

GlobFile creates a rule to write to fileListFile a list of the files that match the specified pattern but do not match any of the patterns specified in excludes. The file will include appropriate dependencies written to depFile to regenerate the file if and only if the list of matching files has changed.

func Main

func Main(ctx *blueprint.Context, config interface{}, extraNinjaFileDeps ...string)

func ModuleTypeDocs

func ModuleTypeDocs(ctx *blueprint.Context, factories map[string]reflect.Value) ([]*bpdoc.Package, error)

ModuleTypeDocs returns a list of bpdoc.ModuleType objects that contain information relevant to generating documentation for module types supported by the primary builder.

Types

type Config

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

type ConfigBlueprintToolLocation

type ConfigBlueprintToolLocation interface {
	// BlueprintToolLocation can return a path name to install blueprint tools
	// designed for end users (bpfmt, bpmodify, and anything else using
	// blueprint_go_binary).
	BlueprintToolLocation() string
}

type ConfigInterface

type ConfigInterface interface {
	// GeneratingPrimaryBuilder should return true if this build invocation is
	// creating a .bootstrap/build.ninja file to be used to build the
	// primary builder
	GeneratingPrimaryBuilder() bool
}

type ConfigRemoveAbandonedFilesUnder

type ConfigRemoveAbandonedFilesUnder interface {
	// RemoveAbandonedFilesUnder should return two slices:
	// - a slice of path prefixes that will be cleaned of files that are no
	//   longer active targets, but are listed in the .ninja_log.
	// - a slice of paths that are exempt from cleaning
	RemoveAbandonedFilesUnder() (under, except []string)
}

type ConfigStopBefore

type ConfigStopBefore interface {
	StopBefore() StopBefore
}

type GlobFileContext

type GlobFileContext interface {
	Build(pctx blueprint.PackageContext, params blueprint.BuildParams)
}

GlobFileContext is the subset of ModuleContext and SingletonContext needed by GlobFile

type GoBinaryTool

type GoBinaryTool interface {
	InstallPath() string
	// contains filtered or unexported methods
}

type Stage

type Stage int

const (
	StagePrimary Stage = iota
	StageMain
)

type StopBefore

type StopBefore int

const (
	StopBeforePrepareBuildActions StopBefore = 1
)