1// 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
15// 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:
18//
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 (
41//       "flag"
42//       "github.com/google/blueprint"
43//       "github.com/google/blueprint/bootstrap"
44//       "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
80//   2. The bootstrap script
81//   3. The build wrapper script
82//
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//
89// 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.
93//
94// The Bootstrapping Process
95//
96// 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.
99//
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
102// 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:
105//
106//   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
113//
114// 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:
117//
118//      - 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
122//
123// Microfactory takes care of building an up to date version of `minibp` and
124// `bpglob` under the .minibootstrap/ directory.
125//
126// During <builddir>/.minibootstrap/build.ninja, the following actions are
127// taken, if necessary:
128//
129//      - Run minibp to generate .bootstrap/build.ninja (Primary stage)
130//      - 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.
133//
134// During the <builddir>/.bootstrap/build.ninja, the following actions are
135// taken, if necessary:
136//
137//      - Build the primary builder, anything marked `default: true`, and
138//        any dependencies.
139//      - Run the primary builder to generate build.ninja
140//      - Run the primary builder to extract documentation
141//      - 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.
144//
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).
149//
150package bootstrap
151