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` under 124 // 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 // 131 // During the <builddir>/.bootstrap/build.ninja, the following actions are 132 // taken, if necessary: 133 // 134 // - Rebuild .bootstrap/build.ninja, usually due to globs changing -- 135 // other dependencies will trigger it to be built during minibootstrap 136 // - Build the primary builder, anything marked `default: true`, and 137 // any dependencies. 138 // - Run the primary builder to generate build.ninja 139 // - Run the primary builder to extract documentation 140 // 141 // Then the main stage is at <builddir>/build.ninja, and will contain all the 142 // rules generated by the primary builder. In addition, the bootstrap code 143 // adds a phony rule "blueprint_tools" that depends on all blueprint_go_binary 144 // rules (bpfmt, bpmodify, etc). 145 // 146 package bootstrap 147
