7d0dddd84d
tl;dr: Read if you don't use the wrapper or use SKIP_NINJA
Previously, we were relying on the ninja behavior of restarting the
build when the build.ninja file was updated to switch between different
bootstrap stages. But that means that every step that could produce a
build.ninja must pass in order to switch to a different stage. That
wasn't a big problem when we had a two stage build -- there was very
little that could fail in the second stage before we chose to go back to
the first stage. But when we had a three stage build, it was possible to
get into a state (usually during development) where you were in the
second stage, but the build was failing because the first stage needed
to be run. This was fixed in d79f1af742
by adding a wrapper that always started building at the first stage.
But this kept all of the complexity of using ninja restarts without any
of the benefits, so this change removes that complexity and just runs
each stage sequentially in the wrapper. So the wrapper is now required.
Since we're no longer going through choosestage, we can also skip the
template parsing for the later stages that don't need to be templated --
this can save a couple of seconds for large files.
In addition to all of the above, this also lets Soong reduce the number
of times the main ninja file is loaded. We had been running the wrapper
once (3 stages), then running ninja again after combining the
Soong-generated build.ninja with the Kati-generated build.ninja. This
change lets us removing the intermediate parsing of Soong's build.ninja,
so that we only execute ninja 3 times per build. It also lets us have
dependencies on pools or rules from Kati in the primary builder, since
we're never executing the main build.ninja without the Kati build.ninja.
The wrapper has a new option, NINJA to provide the path to ninja. This
used to be hardcoded to `ninja`, and will still default to that. But
we'll be running the first two bootstrap stages with $NINJA even if
SKIP_NINJA is set.
The wrapper passes "-w dupbuild=err" to ninja now -- this really should
always be turned on if you care about reliable builds.
Change-Id: I6f656b74eb3d064b8b9e69d1d6dac1129d72b747
178 lines
8 KiB
Go
178 lines
8 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 using a Blueprint-based build system that is embedded (as source) in
|
|
// that source tree. 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 Ninja file template
|
|
// 3. The bootstrap 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 Ninja file template describes the build actions necessary to
|
|
// build the primary builder for the source tree. This template contains a set
|
|
// of placeholder Ninja variable values that get filled in by the bootstrap
|
|
// script to create a usable Ninja file. It can be created by running the
|
|
// minibp binary that gets created as part of the standalone Blueprint build.
|
|
// Passing minibp the path to the top-level Blueprints file will cause it to
|
|
// create a bootstrap Ninja file template named 'build.ninja.in'.
|
|
//
|
|
// The bootstrap script is a small script (or theoretically a compiled binary)
|
|
// that is included in the source tree to begin the bootstrapping process. It
|
|
// is responsible for filling in the bootstrap Ninja file template with some
|
|
// basic information about the Go build environemnt and the path to the root
|
|
// source directory. It does this by performing a simple string substitution on
|
|
// the template file to produce a usable build.ninja file.
|
|
//
|
|
// 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 when run with no arguments it copies the source bootstrap
|
|
// Ninja file into the build directory as ".minibootstrap/build.ninja". It
|
|
// also performs a set of string substitutions on the file to configure it for
|
|
// the user's build environment. Specifically, the following strings are
|
|
// substituted in the file:
|
|
//
|
|
// @@SrcDir@@ - The path to the root source directory (either
|
|
// absolute or relative to the build dir)
|
|
// @@BuildDir@@ - The path to the build directory
|
|
// @@GoRoot@@ - The path to the root directory of the Go toolchain
|
|
// @@GoCompile@@ - The path to the Go compiler (6g or compile)
|
|
// @@GoLink@@ - The path to the Go linker (6l or link)
|
|
// @@Bootstrap@@ - The path to the bootstrap script
|
|
// @@BootstrapManifest@@ - The path to the source bootstrap Ninja file
|
|
//
|
|
// 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:
|
|
//
|
|
// - Checks to see if the source bootstrap Ninja file is newer than the
|
|
// one that is in the build directory, if so, update the build dir copy.
|
|
// - Run the Bootstrap stage
|
|
// - Run the Primary stage
|
|
// - Run the Main stage
|
|
//
|
|
// Previously, we were keeping track of the "state" of the build directory and
|
|
// only going back to previous stages when something had changed. But that
|
|
// added complexity, and failed when there was a build error in the Primary
|
|
// stage that would have been fixed if the Bootstrap stage was re-run (we
|
|
// would only evaluate which stages needed to be run at the end of the stage).
|
|
// So now we always run through each stage, and the first two stages will do
|
|
// nothing when nothing has changed.
|
|
//
|
|
// During the Bootstrap stage, <builddir>/.minibootstrap/build.ninja, the
|
|
// following actions are taken, if necessary:
|
|
//
|
|
// - Build all bootstrap_core_go_binary rules, and dependencies --
|
|
// minibp and some test helpers.
|
|
// - Run minibp to generate .bootstrap/build.ninja (Primary stage)
|
|
// - Run minibp to generate .minibootstrap/build.ninja.in
|
|
// - Restart if .minibootstrap/build.ninja.in has changed
|
|
//
|
|
// During the Primary stage, <builddir>/.bootstrap/build.ninja, the following
|
|
// actions are taken, if necessary:
|
|
//
|
|
// - Build any bootstrap_go_binary rules and dependencies -- usually the
|
|
// primary builder and any build or runtime 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).
|
|
//
|
|
// Updating the Bootstrap Ninja File Template
|
|
//
|
|
// The main purpose of the bootstrap stage is to generate the Ninja file for the
|
|
// primary stage. The one additional thing it does is generate a new bootstrap
|
|
// Ninja file template at .minibootstrap/build.ninja.in. When generating this
|
|
// file, minibp will compare the new bootstrap Ninja file contents with the
|
|
// original (in the source tree).
|
|
//
|
|
// This scheme ensures that updates to the source tree are always incorporated
|
|
// into the build process.
|
|
//
|
|
package bootstrap
|