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 // (http://martine.github.io/ninja/) 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. 68 package blueprint 69
