blueprint/bootstrap/doc.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 with minimal prebuilts.  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 script
//   3. The build wrapper 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 script is a small script to setup the build directory, writing
// a couple configuration files (including the path the source directory,
// information about the Go build environment, etc), then copying the build
// wrapper into the build directory.
//
// 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 creates a ".minibootstrap/build.ninja" file that sets a few
// variables then includes blueprint's "bootstrap/build.ninja". It also writes
// out a ".blueprint.bootstrap" file that contains a few variables for later use:
//
//   BLUEPRINT_BOOTSTRAP_VERSION - Used to detect when a user needs to run
//                                 bootstrap.bash again
//
//   SRCDIR         - The path to the source directory
//   BLUEPRINTDIR   - The path to the blueprints directory (includes $SRCDIR)
//   GOROOT         - The path to the root directory of the Go toolchain
//   NINJA_BUILDDIR - The path to store .ninja_log, .ninja_deps
//
// 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:
//
//      - Runs microfactory.bash to build minibp
//      - Runs the .minibootstrap/build.ninja to build .bootstrap/build.ninja
//      - Runs .bootstrap/build.ninja to build and run the primary builder
//      - Runs build.ninja to build your code
//
// Microfactory takes care of building an up to date version of `minibp` and
// `bpglob` under the .minibootstrap/ directory.
//
// During <builddir>/.minibootstrap/build.ninja, the following actions are
// taken, if necessary:
//
//      - Run minibp to generate .bootstrap/build.ninja (Primary stage)
//      - Includes .minibootstrap/build-globs.ninja, which defines rules to
//        run bpglob during incremental builds. These outputs are listed in
//        the dependency file output by minibp.
//
// During the <builddir>/.bootstrap/build.ninja, the following actions are
// taken, if necessary:
//
//      - Build the primary builder, anything marked `default: true`, and
//        any dependencies.
//      - Run the primary builder to generate build.ninja
//      - Run the primary builder to extract documentation
//      - Includes .bootstrap/build-globs.ninja, which defines rules to run
//        bpglob during incremental builds. These outputs are listed in the
//        dependency file output by the primary builder.
//
// 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).
//
package bootstrap