146 lines
6 KiB
Go
146 lines
6 KiB
Go
// Copyright 2014 Google Inc. All rights reserved.
|
|
//
|
|
// Licensed under the Apache License, Version 2.0 (the "License");
|
|
// you may not use this file except in compliance with the License.
|
|
// You may obtain a copy of the License at
|
|
//
|
|
// http://www.apache.org/licenses/LICENSE-2.0
|
|
//
|
|
// Unless required by applicable law or agreed to in writing, software
|
|
// distributed under the License is distributed on an "AS IS" BASIS,
|
|
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
// See the License for the specific language governing permissions and
|
|
// limitations under the License.
|
|
|
|
// 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"
|
|
// "github.com/google/blueprint"
|
|
// "github.com/google/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` 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)
|
|
//
|
|
// During the <builddir>/.bootstrap/build.ninja, the following actions are
|
|
// taken, if necessary:
|
|
//
|
|
// - Rebuild .bootstrap/build.ninja, usually due to globs changing --
|
|
// other dependencies will trigger it to be built during minibootstrap
|
|
// - 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
|
|
//
|
|
// 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).
|
|
//
|
|
package bootstrap
|