blob: 69a1784aa27a1ad1d4d15923316c179a260f9eae [file] [log] [blame]
Colin Cross8e0c5112015-01-23 14:15:10 -08001// Copyright 2014 Google Inc. All rights reserved.
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7// http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
Dan Willemsenfeb1a222017-07-20 18:41:56 -070015// The Blueprint bootstrapping mechanism is intended to enable building a
16// source tree with minimal prebuilts. The only prerequisites for performing
17// such a build are:
Jamie Gennis7ab5f3c2014-06-11 15:51:08 -070018//
19// 1. A Ninja binary
20// 2. A script interpreter (e.g. Bash or Python)
21// 3. A Go toolchain
22//
23// The Primary Builder
24//
25// As part of the bootstrapping process, a binary called the "primary builder"
26// is created. This primary builder is the binary that includes both the core
27// Blueprint library and the build logic specific to the source tree. It is
28// used to generate the Ninja file that describes how to build the entire source
29// tree.
30//
31// The primary builder must be a pure Go (i.e. no cgo) module built with the
32// module type 'bootstrap_go_binary'. It should have the 'primaryBuilder'
33// module property set to true in its Blueprints file. If more than one module
34// sets primaryBuilder to true the build will fail.
35//
36// The primary builder main function should look something like:
37//
38// package main
39//
40// import (
Jamie Gennis7ab5f3c2014-06-11 15:51:08 -070041// "flag"
Jamie Gennis6cafc2c2015-03-20 22:39:29 -040042// "github.com/google/blueprint"
43// "github.com/google/blueprint/bootstrap"
Jamie Gennis7ab5f3c2014-06-11 15:51:08 -070044// "path/filepath"
45//
46// "my/custom/build/logic"
47// )
48//
49// func main() {
50// // The primary builder should use the global flag set because the
51// // bootstrap package registers its own flags there.
52// flag.Parse()
53//
54// // The top-level Blueprints file is passed as the first argument.
55// srcDir := filepath.Dir(flag.Arg(0))
56//
57// // Create the build context.
58// ctx := blueprint.NewContext()
59//
60// // Register custom module types
61// ctx.RegisterModuleType("foo", logic.FooModule)
62// ctx.RegisterModuleType("bar", logic.BarModule)
63//
64// // Register custom singletons
65// ctx.RegisterSingleton("baz", logic.NewBazSingleton())
66//
67// // Create and initialize the custom Config object.
68// config := logic.NewConfig(srcDir)
69//
70// // This call never returns
71// bootstrap.Main(ctx, config)
72// }
73//
74// Required Source Files
75//
76// There are three files that must be included in the source tree to facilitate
77// the build bootstrapping:
78//
79// 1. The top-level Blueprints file
Dan Willemsenfeb1a222017-07-20 18:41:56 -070080// 2. The bootstrap script
81// 3. The build wrapper script
Jamie Gennis7ab5f3c2014-06-11 15:51:08 -070082//
83// The top-level Blueprints file describes how the entire source tree should be
84// built. It must have a 'subdirs' assignment that includes both the core
85// Blueprint library and the custom build logic for the source tree. It should
86// also include (either directly or through a subdirs entry) describe all the
87// modules to be built in the source tree.
88//
Dan Willemsenfeb1a222017-07-20 18:41:56 -070089// The bootstrap script is a small script to setup the build directory, writing
90// a couple configuration files (including the path the source directory,
91// information about the Go build environment, etc), then copying the build
92// wrapper into the build directory.
Jamie Gennis7ab5f3c2014-06-11 15:51:08 -070093//
94// The Bootstrapping Process
95//
Dan Willemsen7d0dddd2016-08-13 12:42:11 -070096// There are three stages to the bootstrapping process, each with a
97// corresponding Ninja file. The stages are referred to as the "bootstrap",
98// "primary", and "main" stages. Each stage builds the next stage's Ninja file.
Jamie Gennis7ab5f3c2014-06-11 15:51:08 -070099//
100// The bootstrapping process begins with the user running the bootstrap script
101// to initialize a new build directory. The script is run from the build
Dan Willemsenfeb1a222017-07-20 18:41:56 -0700102// directory, and creates a ".minibootstrap/build.ninja" file that sets a few
103// variables then includes blueprint's "bootstrap/build.ninja". It also writes
104// out a ".blueprint.bootstrap" file that contains a few variables for later use:
Jamie Gennis7ab5f3c2014-06-11 15:51:08 -0700105//
Dan Willemsenfeb1a222017-07-20 18:41:56 -0700106// BLUEPRINT_BOOTSTRAP_VERSION - Used to detect when a user needs to run
107// bootstrap.bash again
108//
109// SRCDIR - The path to the source directory
110// BLUEPRINTDIR - The path to the blueprints directory (includes $SRCDIR)
111// GOROOT - The path to the root directory of the Go toolchain
112// NINJA_BUILDDIR - The path to store .ninja_log, .ninja_deps
Jamie Gennis7ab5f3c2014-06-11 15:51:08 -0700113//
Dan Willemsen7d0dddd2016-08-13 12:42:11 -0700114// Once the script completes the build directory is initialized and ready to run
115// a build. A wrapper script (blueprint.bash by default) has been installed in
116// order to run a build. It iterates through the three stages of the build:
Jamie Gennis7ab5f3c2014-06-11 15:51:08 -0700117//
Dan Willemsenfeb1a222017-07-20 18:41:56 -0700118// - Runs microfactory.bash to build minibp
119// - Runs the .minibootstrap/build.ninja to build .bootstrap/build.ninja
120// - Runs .bootstrap/build.ninja to build and run the primary builder
121// - Runs build.ninja to build your code
Jamie Gennis7ab5f3c2014-06-11 15:51:08 -0700122//
Dan Willemsenab223a52018-07-05 21:56:59 -0700123// Microfactory takes care of building an up to date version of `minibp` and
124// `bpglob` under the .minibootstrap/ directory.
Jamie Gennis7ab5f3c2014-06-11 15:51:08 -0700125//
Dan Willemsenfeb1a222017-07-20 18:41:56 -0700126// During <builddir>/.minibootstrap/build.ninja, the following actions are
127// taken, if necessary:
Dan Willemsen7d0dddd2016-08-13 12:42:11 -0700128//
Dan Willemsen7d0dddd2016-08-13 12:42:11 -0700129// - Run minibp to generate .bootstrap/build.ninja (Primary stage)
Dan Willemsenab223a52018-07-05 21:56:59 -0700130// - Includes .minibootstrap/build-globs.ninja, which defines rules to
131// run bpglob during incremental builds. These outputs are listed in
132// the dependency file output by minibp.
Dan Willemsen7d0dddd2016-08-13 12:42:11 -0700133//
Dan Willemsenfeb1a222017-07-20 18:41:56 -0700134// During the <builddir>/.bootstrap/build.ninja, the following actions are
135// taken, if necessary:
Dan Willemsen7d0dddd2016-08-13 12:42:11 -0700136//
Dan Willemsenfeb1a222017-07-20 18:41:56 -0700137// - Build the primary builder, anything marked `default: true`, and
138// any dependencies.
Dan Willemsen7d0dddd2016-08-13 12:42:11 -0700139// - Run the primary builder to generate build.ninja
140// - Run the primary builder to extract documentation
Dan Willemsenab223a52018-07-05 21:56:59 -0700141// - Includes .bootstrap/build-globs.ninja, which defines rules to run
142// bpglob during incremental builds. These outputs are listed in the
143// dependency file output by the primary builder.
Dan Willemsen7d0dddd2016-08-13 12:42:11 -0700144//
145// Then the main stage is at <builddir>/build.ninja, and will contain all the
146// rules generated by the primary builder. In addition, the bootstrap code
147// adds a phony rule "blueprint_tools" that depends on all blueprint_go_binary
148// rules (bpfmt, bpmodify, etc).
Jamie Gennis7ab5f3c2014-06-11 15:51:08 -0700149//
Jamie Gennis1bc967e2014-05-27 16:34:41 -0700150package bootstrap