Update README with more builder.toml details

Signed-off-by: Andrew Meyer <ameyer@pivotal.io>
benmoss · May 16, 2019 · c2c430e · c2c430e
1 parent 6ef6114
commit c2c430e
Show file tree

Hide file tree

Showing 2 changed files with 119 additions and 15 deletions.
diff --git a/README.md b/README.md
@@ -22,6 +22,7 @@ Otherwise, read the rest of this document for detailed explanations and examples
 - [Working with builders using `create-builder`](#working-with-builders-using-create-builder)
   - [Example: Creating a builder from buildpacks](#example-creating-a-builder-from-buildpacks)
   - [Builders explained](#builders-explained)
+  - [Builder configuration](#builder-configuration)
 - [Managing stacks](#managing-stacks)
   - [Run image mirrors](#run-image-mirrors)
 - [Resources](#resources)
@@ -80,16 +81,16 @@ The `--buildpack` parameter can be
 ### Example: Building with user provided environment variables
 
 In the following example, an app image is created from Node.js application source code and the environment 
-variable 'HELLO' with the value 'WORLD' is provided to the buildpacks at build time.
+variable `HELLO` with the value `WORLD` is provided to the buildpacks at build time.
 
 ```bash
 $ cd path/to/node/app
 $ pack build my-app:my-tag --env "HELLO=WORLD"
 ```
 
 The `--env` parameter must be one of
-- 'VARIABLE=VALUE'
-- 'VARIABLE', where the value of 'VARIABLE' will be taken from the current environment
+- `VARIABLE=VALUE`, or
+- `VARIABLE`, where the value of `VARIABLE` will be taken from the current environment
 
 > Multiple environment variables can be specified by supplying `--env` multiple times.
 
@@ -100,13 +101,13 @@ $ cd path/to/node/app
 $ pack build my-app:my-tag --env-file ./my-env-file
 ```
 
-The `--env-file` parameter must be a path to a file where each line must be one of
-- 'VARIABLE=VALUE'
-- 'VARIABLE', where the value of 'VARIABLE' will be taken from the current environment
+The `--env-file` parameter must be a path to a file where each line is one of
+- `VARIABLE=VALUE`, or
+- `VARIABLE`, where the value of `VARIABLE` will be taken from the current environment
 
 > Multiple environment variables can be specified by supplying variables on each line of the file.
 >
-> Variables defined using `--env` take precedence over variables defined in `--env-file`. 
+> Variables defined using `--env` take precedence over variables defined in `--env-file`.
 
 ### Building explained
 
@@ -168,12 +169,12 @@ $ pack create-builder <image-name> --builder-config <path-to-builder-toml>
 ### Example: Creating a builder from buildpacks
 
 In this example, a builder image is created from buildpacks `org.example.buildpack-1` and `org.example.buildpack-2`.
-A TOML file (typically named `builder.toml`) provides necessary configuration to the command.
+A [TOML configuration file](#builder-configuration) provides necessary configuration to the command.
 
 ```toml
 [[buildpacks]]
   id = "org.example.buildpack-1"
-  uri = "relative/path/to/buildpack-1" # URIs without schemes are read as paths relative to builder.toml
+  uri = "relative/path/to/buildpack-1"
 
 [[buildpacks]]
   id = "org.example.buildpack-2"
@@ -194,8 +195,6 @@ A TOML file (typically named `builder.toml`) provides necessary configuration to
   run-image = "example/run"
 ```
 
-> For more information on stacks, see the [Managing stacks](#managing-stacks) section.
-
 Running `create-builder` while supplying this configuration file will produce the builder image.
 
 ```bash
@@ -215,8 +214,9 @@ $ pack build my-app:my-tag --builder my-builder:my-tag --buildpack org.example.b
 
 ![create-builder diagram](docs/create-builder.svg)
 
-A builder is an image containing a collection of buildpack groups that will be executed against app source code, in the order
-that they appear in `builder.toml`. This image's base will be the build image associated with a given stack.
+A builder is an image containing a collection of buildpacks that will be executed against application source code, in
+the order defined by the builder's [configuration file](#builder-configuration). This image's base will be the build
+image associated with a given stack.
 
 > A buildpack's primary role is to inspect the source code, determine any
 > dependencies that will be required to compile and/or run the app, and provide runtime dependencies as layers in the
@@ -225,10 +225,114 @@ that they appear in `builder.toml`. This image's base will be the build image as
 > It's important to note that the buildpacks in a builder are not actually executed until
 > [`build`](#building-explained) is run.
 
+#### Lifecycle
+
+A builder also includes a layer with a series of binaries that are executed during [`build`](#building-explained).
+These binaries represent a specific implementation of the buildpack **lifecycle**, as defined by the
+[Cloud Native Buildpacks API Specification](https://github.com/buildpack/spec#buildpack-api-v3---specification). While
+most users will find the [default lifecycle implementation](https://github.com/buildpack/lifecycle#lifecycle)
+sufficient, users are free to implement their own or use a different release of the default implementation. See
+[Builder configuration](#builder-configuration) for more information on configuring which lifecycle to use for a builder.
+
+### Builder configuration
+
+The [`create-builder`](#working-with-builders-using-create-builder) command requires a TOML configuration file (commonly
+referred to as `builder.toml`). This file has a number of fields.
+
+- **`description`** _(string, optional)_
+  <br>
+  A human-readable description of the builder, to be shown in `inspect-builder` output
+  (run `pack inspect-builder -h` for more information).
+
+- **`buildpacks`** _(list, required)_
+  <br>
+  A list of buildpacks, each with the following fields:
+
+  - **`id`** _(string, required)_
+    <br>
+    An identifier for the buildpack
+
+  - **`uri`** _(string, required)_
+    <br>
+    Either a fully-qualified URL to a `.tgz` file, or a path to a local buildpack's `.tgz` file or directory (relative to
+    `builder.toml`)
+
+  - **`latest`** _(boolean, optional, default: `false`)_
+    <br>
+    Whether or not this buildpack is considered the latest version (for use in specifying `groups` below).
+
+  > Multiple versions of the same buildpack (i.e. buildpacks with the same ID but with URIs to differing versions) may be
+  > specified in this list, though only one entry per ID may be marked as `latest`.
+
+- **`groups`** _(list, required)_
+  <br>
+  A list of buildpack groups. This list determines the order in which groups of buildpacks
+  will be tested during detection. Detection is a phase of the [lifecycle](#lifecycle) where
+  buildpacks are tested, one group at a time, for compatibility with the provided application source code. The first
+  group whose non-optional buildpacks all pass detection will be the group selected for the remainder of the build. Each
+  group currently contains a single required field:
+
+  - **`buildpacks`** _(list, required)_
+    <br>
+    The set of buildpacks belonging to the group. Each buildpack specified has the following fields (different from the
+    buildpack fields mentioned previously):
+
+    - **`id`** _(string, required)_
+      <br>
+      The identifier of a buildpack from the configuration's top-level `buildpacks` list. Buildpacks with the same ID may
+      appear in multiple groups at once but never in the same group.
+
+    - **`version`** _(string, required)_
+      <br>
+      The version of the buildpack being referred to. Alternately, specify `"latest"` to use the buildpack marked as
+      `latest` in the configuration's top-level `buildpacks` list.
+
+    - **`optional`** _(boolean, optional, default: false)_
+      <br>
+      Whether or not this buildpack is optional during detection.
+
+- **`stack`** _(required)_
+  <br>
+  The stack to use for the builder. See [Managing stacks](#managing-stacks) for more information about this field. It
+  contains the following fields:
+
+  - **`id`** _(required, string)_
+    <br>
+    Identifier for the stack
+
+  - **`build-image`** _(required, string)_
+    <br>
+    Build image for the stack
+
+  - **`run-image`** _(required, string)_
+    <br>
+    Run image for the stack
+
+  - **`run-image-mirrors`** _(optional, string list)_
+    <br>
+    [Run image mirrors](#run-image-mirrors) for the stack
+
+- **`lifecycle`** _(optional)_
+  <br>
+  The [lifecycle](#lifecycle) to use for the builder. It contains the following fields:
+
+  - **`version`** _(string, optional)_
+    <br>
+    The version of the lifecycle (semver format). If omitted, defaults to the latest release of the lifecycle captured
+    at the time of `pack`'s particular release (i.e. if you're pinned to a particular release of `pack`, this default
+    will never change, even when new versions of the lifecycle are released).
+
+  - **`uri`** _(string, optional)_
+    <br>
+    Either a fully-qualified URL to a `.tgz` file, or a path to a local lifecycle's `.tgz` file (relative to
+    `builder.toml`). If omitted, a URL to a GitHub release for the defined `version` will be used.
+
+  > If the `lifecycle` field itself is omitted, default values for each sub-field will be used.
+
 ## Managing stacks
 
 As mentioned [previously](#building-explained), a stack is a named association of a build image and a run image.
-Stacks are managed through a builder's TOML file:
+Stacks are managed through a builder's [configuration file](#builder-configuration):
 
 ```toml
 [[buildpacks]]

diff --git a/docs/create-builder.svg b/docs/create-builder.svg