Buildpack api changes to support phase 1 of Dockerfiles implementation

image_extension.md

@@ -0,0 +1,133 @@
+# Image Extension Interface Specification (**experimental**)
+
+This document specifies the interface between a lifecycle program and one or more image extensions.
+
+## Table of Contents
+
+<!-- Using https://github.com/yzhang-gh/vscode-markdown to manage toc -->
+- [Image Extension Interface Specification](#image-extension-interface-specification)
+  - [Table of Contents](#table-of-contents)
+  - [Image Extension API Version](#image-extension-api-version)
+  - [Image Extension Interface](#image-extension-interface)
+    - [Detection](#detection)
+    - [Generation](#generation)
+  - [Phase: Generation](#phase-generation)
+    - [Purpose](#purpose)
+    - [Process](#process)
+      - [Dockerfile Requirements](#dockerfile-requirements)
+  - [Data Format](#data-format)
+    - [Files](#files)
+    - [extension.toml (TOML)](#extensiontoml-toml)
+
+## Image Extension API Version
+
+This document accompanies Buildpack API version `0.9`.
+
+## Image Extension Interface
+
+Unless otherwise noted, image extensions are expected to conform to the [Buildpack Interface Specification](buildpack.md).
+
+### Detection
+
+Executable: `/bin/detect`, Working Dir: `<app[AR]>`
+
+Image extensions participate in the buildpack [detection](buildpack.md#detection) process, with the same interface for `/bin/detect`. However:
+- Detection is optional for image extensions, and they are assumed to pass detection when `/bin/detect` is not present.
+- If an image extension is missing `/bin/detect`, the image extension root `/detect` directory MUST be treated as a pre-populated `<output>` directory.
+- Image extensions MUST only output `provides` entries to the build plan. They MUST NOT output `requires`.
+
+### Generation
+
+Executable: `/bin/generate`, Working Dir: `<app[AR]>`
+
+Image extensions participate in a generation process that is similar to the buildpack [build](buildpack.md#build) process, with an interface that is similar to `/bin/build`. However:
+- Image extensions' `/bin/generate` MUST NOT write to the app directory.
+- Instead of the `CNB_LAYERS_DIR` input, image extensions MUST receive a `CNB_OUTPUT_DIR` which MUST be the absolute path of an `<output>` directory and MUST NOT be the path of the buildpack layers directory.
+- If an image extension is missing `/bin/generate`, the image extension root `/generate` directory MUST be treated as a pre-populated `<output>` directory.
+
+## Phase: Generation
+
+### Purpose
+
+The purpose of the generation phase is to generate Dockerfiles that can be used to define the runtime base image.
+
+### Process
+
+**GIVEN:**
+- The final ordered group of image extensions determined during the detection phase,
+- A directory containing application source code,
+- The Buildpack Plan,
+- An `<output>` directory used to store generated artifacts,
+- A shell, if needed,
+
+For each image extension in the group in order, the lifecycle MUST execute `/bin/generate`.
+
+1. **If** the exit status of `/bin/generate` is non-zero, \
+   **Then** the lifecycle MUST fail the build.
+
+2. **If** the exit status of `/bin/generate` is zero,
+    1. **If** there are additional image extensions in the group, \
+       **Then** the lifecycle MUST proceed to the next image extension's `/bin/generate`.
+
+    2. **If** there are no additional image extensions in the group, \
+       **Then** the lifecycle MUST proceed to the build phase.
+
+For each `/bin/generate` executable in each image extension, the lifecycle:
+
+- MUST provide path arguments to `/bin/generate` as described in the [generation](#generation) section.
+- MUST configure the build environment as described in the [Environment](buildpack.md#environment) section.
+- MUST provide all `<plan>` entries that were required by any buildpack in the group during the detection phase with names matching the names that the image extension provided.
+
+Correspondingly, each `/bin/generate` executable:
+
+- MAY read from the `<app>` directory.
+- MUST NOT write to the `<app>` directory.
+- MAY read the build environment as described in the [Environment](buildpack.md#environment) section.
+- MAY read the Buildpack Plan.
+- MAY log output from the build process to `stdout`.
+- MAY emit error, warning, or debug messages to `stderr`.
+- MAY write a run.Dockerfile to the `<output>` directory. This file MUST adhere to the requirements listed below.
+- MUST NOT write SBOM (Software-Bill-of-Materials) files as described in the [Software-Bill-of-Materials](#software-bill-of-materials) section.
+
+#### Dockerfile Requirements
+
+run.Dockerfiles:
+
+- MAY contain a single `FROM` instruction
+- MUST NOT contain any other instructions
+
+## Data Format
+
+### Files
+
+### extension.toml (TOML)
+
+This section describes the 'Extension descriptor'.
+
+```toml
+api = "<buildpack API version>"
+
+[extension]
+id = "<extension ID>"
+name = "<extension name>"
+version = "<extension version>"
+homepage = "<extension homepage>"
+description = "<extension description>"
+keywords = [ "<string>" ]
+
+[[extension.licenses]]
+type = "<string>"
+uri = "<uri>"
+```
+
+Image extension authors MUST choose a globally unique ID, for example: "io.buildpacks.apt".
+
+The image extension `id`, `version`, `api`, and `licenses` entries MUST follow the requirements defined in the [Buildpack Interface Specification](buildpack.md).
+
+### Build Plan (TOML)
+
+See the [Buildpack Interface Specification](buildpack.md).
+
+### Buildpack Plan (TOML)
+
+See the [Buildpack Interface Specification](buildpack.md). Image extensions MUST satisfy all entries in the Buildpack Plan.

img/genmatrix.sh

@@ -0,0 +1,15 @@
+#!/bin/bash
+
+# A quick script to use tex.s2cms.ru to generate various matrix svgs.
+# (requests were previously inlined directly from buildpack.md, this allows the doc to be read if the remote side is down)
+
+wget -O matrix1.svg http://tex.s2cms.ru/svg/%0AO%20%3D%0A%5Cbegin%7Bbmatrix%7D%0AA%2C%20%26%20B%20%5C%5C%0AC%2C%20%26%20D%0A%5Cend%7Bbmatrix%7D%0A
+wget -O matrix2.svg http://tex.s2cms.ru/svg/%0AP%20%3D%0A%5Cbegin%7Bbmatrix%7D%0AE%2C%20%26%20F%20%5C%5C%0AG%2C%20%26%20H%0A%5Cend%7Bbmatrix%7D%0A
+wget -O matrix3.svg http://tex.s2cms.ru/svg/%0A%5Cbegin%7Bbmatrix%7D%0AE%2C%20%26%20O%2C%20%26%20F%0A%5Cend%7Bbmatrix%7D%20%3D%20%0A%5Cbegin%7Bbmatrix%7D%0AE%2C%20%26%20A%2C%20%26%20B%2C%20%26%20F%20%5C%5C%0AE%2C%20%26%20C%2C%20%26%20D%2C%20%26%20F%20%5C%5C%0A%5Cend%7Bbmatrix%7D%0A
+wget -O matrix4.svg http://tex.s2cms.ru/svg/%0A%5Cbegin%7Bbmatrix%7D%0AO%2C%20%26%20P%0A%5Cend%7Bbmatrix%7D%20%3D%20%0A%5Cbegin%7Bbmatrix%7D%0AA%2C%20%26%20B%2C%20%26%20E%2C%20%26%20F%20%5C%5C%0AA%2C%20%26%20B%2C%20%26%20G%2C%20%26%20H%20%5C%5C%0AC%2C%20%26%20D%2C%20%26%20E%2C%20%26%20F%20%5C%5C%0AC%2C%20%26%20D%2C%20%26%20G%2C%20%26%20H%20%5C%5C%0A%5Cend%7Bbmatrix%7D%0A
+
+# add background color.. (helps with github darkmode)
+sed -i -e's/<svg/<svg style="background-color:white"/' matrix1.svg
+sed -i -e's/<svg/<svg style="background-color:white"/' matrix2.svg
+sed -i -e's/<svg/<svg style="background-color:white"/' matrix3.svg
+sed -i -e's/<svg/<svg style="background-color:white"/' matrix4.svg