Colin Cross | 8e0c511 | 2015-01-23 14:15:10 -0800 | [diff] [blame] | 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 | |
Dan Willemsen | feb1a22 | 2017-07-20 18:41:56 -0700 | [diff] [blame] | 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: |
Jamie Gennis | 7ab5f3c | 2014-06-11 15:51:08 -0700 | [diff] [blame] | 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 ( |
Jamie Gennis | 7ab5f3c | 2014-06-11 15:51:08 -0700 | [diff] [blame] | 41 | // "flag" |
Jamie Gennis | 6cafc2c | 2015-03-20 22:39:29 -0400 | [diff] [blame] | 42 | // "github.com/google/blueprint" |
| 43 | // "github.com/google/blueprint/bootstrap" |
Jamie Gennis | 7ab5f3c | 2014-06-11 15:51:08 -0700 | [diff] [blame] | 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 |
Dan Willemsen | feb1a22 | 2017-07-20 18:41:56 -0700 | [diff] [blame] | 80 | // 2. The bootstrap script |
| 81 | // 3. The build wrapper script |
Jamie Gennis | 7ab5f3c | 2014-06-11 15:51:08 -0700 | [diff] [blame] | 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 | // |
Dan Willemsen | feb1a22 | 2017-07-20 18:41:56 -0700 | [diff] [blame] | 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. |
Jamie Gennis | 7ab5f3c | 2014-06-11 15:51:08 -0700 | [diff] [blame] | 93 | // |
| 94 | // The Bootstrapping Process |
| 95 | // |
Dan Willemsen | 7d0dddd | 2016-08-13 12:42:11 -0700 | [diff] [blame] | 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. |
Jamie Gennis | 7ab5f3c | 2014-06-11 15:51:08 -0700 | [diff] [blame] | 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 |
Dan Willemsen | feb1a22 | 2017-07-20 18:41:56 -0700 | [diff] [blame] | 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: |
Jamie Gennis | 7ab5f3c | 2014-06-11 15:51:08 -0700 | [diff] [blame] | 105 | // |
Dan Willemsen | feb1a22 | 2017-07-20 18:41:56 -0700 | [diff] [blame] | 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 |
Jamie Gennis | 7ab5f3c | 2014-06-11 15:51:08 -0700 | [diff] [blame] | 113 | // |
Dan Willemsen | 7d0dddd | 2016-08-13 12:42:11 -0700 | [diff] [blame] | 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: |
Jamie Gennis | 7ab5f3c | 2014-06-11 15:51:08 -0700 | [diff] [blame] | 117 | // |
Dan Willemsen | feb1a22 | 2017-07-20 18:41:56 -0700 | [diff] [blame] | 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 |
Jamie Gennis | 7ab5f3c | 2014-06-11 15:51:08 -0700 | [diff] [blame] | 122 | // |
Dan Willemsen | ab223a5 | 2018-07-05 21:56:59 -0700 | [diff] [blame] | 123 | // Microfactory takes care of building an up to date version of `minibp` and |
| 124 | // `bpglob` under the .minibootstrap/ directory. |
Jamie Gennis | 7ab5f3c | 2014-06-11 15:51:08 -0700 | [diff] [blame] | 125 | // |
Dan Willemsen | feb1a22 | 2017-07-20 18:41:56 -0700 | [diff] [blame] | 126 | // During <builddir>/.minibootstrap/build.ninja, the following actions are |
| 127 | // taken, if necessary: |
Dan Willemsen | 7d0dddd | 2016-08-13 12:42:11 -0700 | [diff] [blame] | 128 | // |
Dan Willemsen | 7d0dddd | 2016-08-13 12:42:11 -0700 | [diff] [blame] | 129 | // - Run minibp to generate .bootstrap/build.ninja (Primary stage) |
Dan Willemsen | ab223a5 | 2018-07-05 21:56:59 -0700 | [diff] [blame] | 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. |
Dan Willemsen | 7d0dddd | 2016-08-13 12:42:11 -0700 | [diff] [blame] | 133 | // |
Dan Willemsen | feb1a22 | 2017-07-20 18:41:56 -0700 | [diff] [blame] | 134 | // During the <builddir>/.bootstrap/build.ninja, the following actions are |
| 135 | // taken, if necessary: |
Dan Willemsen | 7d0dddd | 2016-08-13 12:42:11 -0700 | [diff] [blame] | 136 | // |
Dan Willemsen | feb1a22 | 2017-07-20 18:41:56 -0700 | [diff] [blame] | 137 | // - Build the primary builder, anything marked `default: true`, and |
| 138 | // any dependencies. |
Dan Willemsen | 7d0dddd | 2016-08-13 12:42:11 -0700 | [diff] [blame] | 139 | // - Run the primary builder to generate build.ninja |
| 140 | // - Run the primary builder to extract documentation |
Dan Willemsen | ab223a5 | 2018-07-05 21:56:59 -0700 | [diff] [blame] | 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. |
Dan Willemsen | 7d0dddd | 2016-08-13 12:42:11 -0700 | [diff] [blame] | 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). |
Jamie Gennis | 7ab5f3c | 2014-06-11 15:51:08 -0700 | [diff] [blame] | 149 | // |
Jamie Gennis | 1bc967e | 2014-05-27 16:34:41 -0700 | [diff] [blame] | 150 | package bootstrap |