1// Copyright 2015 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// Blueprint is a meta-build system that reads in Blueprints files that describe
16// modules that need to be built, and produces a Ninja
17// (https://ninja-build.org/) manifest describing the commands that need
18// to be run and their dependencies.  Where most build systems use built-in
19// rules or a domain-specific language to describe the logic how modules are
20// converted to build rules, Blueprint delegates this to per-project build logic
21// written in Go.  For large, heterogenous projects this allows the inherent
22// complexity of the build logic to be maintained in a high-level language,
23// while still allowing simple changes to individual modules by modifying easy
24// to understand Blueprints files.
25//
26// Blueprint uses a bootstrapping process to allow the code for Blueprint,
27// the code for the build logic, and the code for the project being compiled
28// to all live in the project.  Dependencies between the layers are fully
29// tracked - a change to the logic code will cause the logic to be recompiled,
30// regenerate the project build manifest, and run modified project rules.  A
31// change to Blueprint itself will cause Blueprint to rebuild, and then rebuild
32// the logic, etc.
33//
34// A Blueprints file is a list of modules in a pseudo-python data format, where
35// the module type looks like a function call, and the properties of the module
36// look like optional arguments.  For example, a simple module might look like:
37//
38//   cc_library {
39//       name: "cmd",
40//       srcs: [
41//           "main.c",
42//       ],
43//       deps: [
44//           "libc",
45//       ],
46//   }
47//
48//   subdirs = ["subdir1", "subdir2"]
49//
50// The modules from the top level Blueprints file and recursively through any
51// subdirectories listed by the "subdirs" variable are read by Blueprint, and
52// their properties are stored into property structs by module type.  Once
53// all modules are read, Blueprint calls any registered Mutators, in
54// registration order.  Mutators can visit each module top-down or bottom-up,
55// and modify them as necessary.  Common modifications include setting
56// properties on modules to propagate information down from dependers to
57// dependees (for example, telling a module what kinds of parents depend on it),
58// or splitting a module into multiple variants (for example, one per
59// architecture being compiled).  After all Mutators have run, each module is
60// asked to generate build rules based on property values, and then singletons
61// can generate any build rules from the output of all modules.
62//
63// The per-project build logic defines a top level command, referred to in the
64// documentation as the "primary builder".  This command is responsible for
65// registering the module types needed for the project, as well as any
66// singletons or mutators, and then calling into Blueprint with the path of the
67// root Blueprint file.
68package blueprint
69