Expand buildpack author concepts pages (#739)

* adds some build plan content Signed-off-by: Hanan Younes <[email protected]> * edits MD styling Signed-off-by: Hanan Younes <[email protected]> * adds component buildpack content Signed-off-by: Hanan Younes <[email protected]> * adds some dependency layer content Signed-off-by: Hanan Younes <[email protected]> * adds buildpack package content Signed-off-by: Hanan Younes <[email protected]> * adds reviewer feedback Signed-off-by: Hanan Younes <[email protected]> * adds 2nd reviewer feedback Signed-off-by: Hanan Younes <[email protected]> * Adds some links Signed-off-by: Hanan Younes <[email protected]> * updates dependency layer page Signed-off-by: Hanan Younes <[email protected]> * adds pages linking Signed-off-by: Hanan Younes <[email protected]> * adds more build-plan and layers content Signed-off-by: Hanan Younes <[email protected]> --------- Signed-off-by: Hanan Younes <[email protected]> Co-authored-by: Aidan Delaney <[email protected]>
buildpacks · Jul 12, 2024 · 646a1c2 · 646a1c2
1 parent 452e334
commit 646a1c2
Show file tree

Hide file tree

Showing 13 changed files with 176 additions and 84 deletions.
diff --git a/docs/for-buildpack-authors/concepts/build-plan/index.html b/docs/for-buildpack-authors/concepts/build-plan/index.html
@@ -8,7 +8,8 @@
 <meta charset="utf-8">
 <meta http-equiv="x-ua-compatible" content="ie=edge">
 <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
-
+<meta name="description" content="A build plan is a toml file that is the output of the detect phase, in which each component buildpack or image extension may express the dependencies it requires and the dependencies it provides.
+"/>
 <link rel="canonical" content="https://buildpacks.io/docs/for-buildpack-authors/concepts/build-plan/">
 <link rel="icon" type="image/png" href="/images/favicon.png">
 
@@ -22,7 +23,8 @@
 <meta property="og:url" content="https://buildpacks.io/docs/for-buildpack-authors/concepts/build-plan/">
 <meta property="og:locale" content="en_US">
 <meta property="og:site_name" content="Cloud Native Buildpacks">
-
+<meta property="og:description" content="A build plan is a toml file that is the output of the detect phase, in which each component buildpack or image extension may express the dependencies it requires and the dependencies it provides.
+">
 <meta property="og:type" content="article">
 <meta property="og:image" content="https://buildpacks.io/images/buildpacks-social-card.jpg">
 <meta property="og:image:alt" content="Buildpacks project logo">
@@ -897,8 +899,53 @@
           <h1 class="title">What is the build plan?</h1>
         </div>
 
-        <p>This page is a stub! The CNB project is applying to <a href="https://developers.google.com/season-of-docs/docs/timeline">Google Season of Docs</a> to receive support for improving our documentation. Please check back soon.</p>
-<p>If you are familiar with this content and would like to make a contribution, please feel free to open a PR :)</p>
+        <p>A <strong>build plan</strong> is a <code>toml</code> file that is the output of the <a href="https://buildpacks.io/docs/for-buildpack-authors/concepts/lifecycle-phases/#phase-2-detect">detect</a> phase, in which each component buildpack or image extension may express the dependencies it requires and the dependencies it provides.</p>
+<p>Before we dive into more details, let&rsquo;s explain the difference between three terms relevant to the concept of <code>build plan</code>.</p>
+<ul>
+<li>
+<p>First, the <a href="https://github.com/buildpacks/spec/blob/main/buildpack.md#build-plan-toml">build plan</a> piece that is contributed by the buildpack during the <code>detect</code> phase. This piece is seen as the <code>build plan</code> from buildpack&rsquo;s perspective and is written to a temporary directory by the buildpack.</p>
+</li>
+<li>
+<p>Second, the concatenation of all buildpacks contributions that passed <code>detect</code>, which is considered the true <a href="https://github.com/buildpacks/spec/blob/main/platform.md#plantoml-toml">build plan</a> from the platform&rsquo;s perspective. This file usually gets written to the <code>&lt;layers&gt;</code> directory—unless the platform provided another path for it.</p>
+</li>
+<li>
+<p>Finally, the build plan piece that is shown to the buildpack during the <code>build</code> phase that is referred to as the <a href="https://github.com/buildpacks/spec/blob/main/buildpack.md#buildpack-plan-toml">buildpack plan</a>. This file only contains dependencies that a buildpack is responsible for providing; however a buildpack may choose NOT to provide any of these dependencies, leaving that work for a future buildpack. The <code>buildpack plan</code> file is usually written to a temporary directory by the <code>lifecycle</code>.</p>
+</li>
+</ul>
+<h2 id="example-build-plan-toml">Example Build Plan (toml)</h2>
+<p>In order to make contributions to the <code>Build Plan</code>, a <code>/bin/detect</code> executable MUST write entries to <code>&lt;plan&gt;</code> in two sections: <code>requires</code> and <code>provides</code>. The generated <code>plan.toml</code> file is usually added under the <code>&lt;layers&gt;</code>directory.
+The <code>requires</code> and <code>provides</code> sections MAY be repeated together inside of an <code>or</code> array at the top-level.<br>
+Each <code>requires</code> and <code>provides</code> section MUST be a list of entries formatted as shown below:</p>
+<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-toml" data-lang="toml"><span class="line"><span class="cl"><span class="p">[[</span><span class="nx">provides</span><span class="p">]]</span>
+</span></span><span class="line"><span class="cl"><span class="nx">name</span> <span class="p">=</span> <span class="s2">&#34;&lt;dependency name&gt;&#34;</span>
+</span></span><span class="line"><span class="cl">
+</span></span><span class="line"><span class="cl"><span class="p">[[</span><span class="nx">requires</span><span class="p">]]</span>
+</span></span><span class="line"><span class="cl"><span class="nx">name</span> <span class="p">=</span> <span class="s2">&#34;&lt;dependency name&gt;&#34;</span>
+</span></span><span class="line"><span class="cl">
+</span></span><span class="line"><span class="cl"><span class="p">[</span><span class="nx">requires</span><span class="p">.</span><span class="nx">metadata</span><span class="p">]</span>
+</span></span><span class="line"><span class="cl"><span class="c"># buildpack-specific data</span>
+</span></span><span class="line"><span class="cl">
+</span></span><span class="line"><span class="cl"><span class="p">[[</span><span class="nx">or</span><span class="p">]]</span>
+</span></span><span class="line"><span class="cl">
+</span></span><span class="line"><span class="cl"><span class="p">[[</span><span class="nx">or</span><span class="p">.</span><span class="nx">provides</span><span class="p">]]</span>
+</span></span><span class="line"><span class="cl"><span class="nx">name</span> <span class="p">=</span> <span class="s2">&#34;&lt;dependency name&gt;&#34;</span>
+</span></span><span class="line"><span class="cl">
+</span></span><span class="line"><span class="cl"><span class="p">[[</span><span class="nx">or</span><span class="p">.</span><span class="nx">requires</span><span class="p">]]</span>
+</span></span><span class="line"><span class="cl"><span class="nx">name</span> <span class="p">=</span> <span class="s2">&#34;&lt;dependency name&gt;&#34;</span>
+</span></span><span class="line"><span class="cl">
+</span></span><span class="line"><span class="cl"><span class="p">[</span><span class="nx">or</span><span class="p">.</span><span class="nx">requires</span><span class="p">.</span><span class="nx">metadata</span><span class="p">]</span>
+</span></span><span class="line"><span class="cl"><span class="c"># buildpack-specific data</span>
+</span></span></code></pre></div><h2 id="key-points">Key Points</h2>
+<ul>
+<li>A valid <code>build plan</code> is a plan where all required dependencies are provided in the necessary order, meaning that during the <code>build</code> phase, each component buildpack will have its required dependencies provided by component buildpack or an image extension that runs before it.</li>
+<li>Each pairing of <code>requires</code> and <code>provides</code> sections (at the top level, or inside of an <code>or</code> array) is a potential build plan. For more details, see the <a href="https://buildpacks.io/docs/for-buildpack-authors/how-to/write-buildpacks/use-build-plan/#example-jvm-buildpack">JVM buildpack</a> example.</li>
+<li>A group will only pass detection if a valid build plan can be produced from the dependencies that all elements in the group require and provide.</li>
+<li>The <code>detect</code> phase could fail if a buildpack requires a dependency that it does not itself provide, or is not provided by another buildpack.</li>
+<li>The <code>detect</code> phase could also fail when the buildpacks order is incorrect, i.e, the buildpacks providing dependencies run <code>after</code> the buildpacks requiring them.</li>
+<li>The resulting <code>build plan</code> is passed as one of the inputs to the <code>build</code> phase.</li>
+</ul>
+<h2 id="resources">Resources</h2>
+<p>For further examples and guidance on using the build plan, see the <a href="https://buildpacks.io/docs/for-buildpack-authors/how-to/write-buildpacks/use-build-plan/">how-to page</a>.</p>
 
 
 

diff --git a/docs/for-buildpack-authors/concepts/buildpack-group/index.html b/docs/for-buildpack-authors/concepts/buildpack-group/index.html
@@ -8,7 +8,7 @@
 <meta charset="utf-8">
 <meta http-equiv="x-ua-compatible" content="ie=edge">
 <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
-<meta name="description" content="A buildpack group is a list of individual buildpacks that are designged to work together to build an application.
+<meta name="description" content="A buildpack group is a list of individual buildpacks that are designed to work together to build an application.
 "/>
 <link rel="canonical" content="https://buildpacks.io/docs/for-buildpack-authors/concepts/buildpack-group/">
 <link rel="icon" type="image/png" href="/images/favicon.png">
@@ -23,7 +23,7 @@
 <meta property="og:url" content="https://buildpacks.io/docs/for-buildpack-authors/concepts/buildpack-group/">
 <meta property="og:locale" content="en_US">
 <meta property="og:site_name" content="Cloud Native Buildpacks">
-<meta property="og:description" content="A buildpack group is a list of individual buildpacks that are designged to work together to build an application.
+<meta property="og:description" content="A buildpack group is a list of individual buildpacks that are designed to work together to build an application.
 ">
 <meta property="og:type" content="article">
 <meta property="og:image" content="https://buildpacks.io/images/buildpacks-social-card.jpg">
@@ -899,16 +899,16 @@
           <h1 class="title">What is a buildpack group?</h1>
         </div>
 
-        <p>A buildpack group is a list of individual buildpacks that are designged to work together to build an application.</p>
+        <p>A buildpack group is a list of individual buildpacks that are designed to work together to build an application.</p>
 <p>Buildpack groups allow you to connect multiple modular buildpacks together, making buildpacks modular and re-usable.</p>
 <p>For example, you might have a buildpack that installs Java and a buildpack that uses Maven to build your application. These two buildpacks can be combined into a group to implement higher-level functionality, specifically that the first one will install Java and the second will use Java to run Maven, which is a Java build tool.</p>
-<p>Because you can have many buildpack groups in a <a href="/docs/for-platform-operators/concepts/builder/">builder</a> or <a href="/docs/for-platform-operators/concepts/composite-buildpack">composite buildpack</a> (sometimes referred to as a &ldquo;meta buildpack&rdquo;),
+<p>Because you can have many buildpack groups in a <a href="/docs/for-platform-operators/concepts/builder/">builder</a> or <a href="/docs/for-buildpack-authors/concepts/composite-buildpack">composite buildpack</a> (sometimes referred to as a &ldquo;meta buildpack&rdquo;),
 and you can reuse buildpacks, you could have a second buildpack group that reuses the buildpack to provide Java but uses a third buildpack that provides Gradle to build your application. By doing this, you can create additional high-level functionality without having duplication.</p>
 <h2 id="anatomy-of-a-buildpack-group">Anatomy of a buildpack group</h2>
 <p>A <a href="/docs/reference/config/builder-config/#order-_list-required_">buildpack group</a> is a list of buildpack entries defined in the order in which they will run.</p>
 <p>A buildpack entry is identified by an id and a version. It may also be marked as optional. While you may have one or more buildpacks in a buildpack group, you may have one or more buildpack groups in a builder or composite buildpack.</p>
 <h2 id="detection-with-buildpack-groups">Detection with buildpack groups</h2>
-<p>A <a href="/docs/for-platform-operators/concepts/builder/">builder</a> or <a href="/docs/for-platform-operators/concepts/composite-buildpack">composite buildpack</a> may contain multiple buildpack groups. When the lifecycle executes the detection process, it will process each buildpack group it finds in the order that the groups are specified. For each buildpack group, the lifecycle will execute the detect phase of all buildpacks in that group (these can be executed in parallel) and aggregate the results. The lifecycle will select the first buildpack group by order where all of the non-optional buildpacks in that group pass detection.</p>
+<p>A <a href="/docs/for-platform-operators/concepts/builder/">builder</a> or <a href="/docs/for-buildpack-authors/concepts/composite-buildpack">composite buildpack</a> may contain multiple buildpack groups. When the lifecycle executes the detection process, it will process each buildpack group it finds in the order that the groups are specified. For each buildpack group, the lifecycle will execute the detect phase of all buildpacks in that group (these can be executed in parallel) and aggregate the results. The lifecycle will select the first buildpack group by order where all of the non-optional buildpacks in that group pass detection.</p>
 <p>For example, if a builder has buildpack groups A, B and C. The lifecycle will run detection against A. If all of the non-optional buildpacks in that group pass detection, then it will select A. In that case, B and C will not be processed. If A has any failing non-optional buildpacks, then the lifecycle will move on to process buildpack group B. If B has any failing non-optional buildpacks, then the lifecycle will move on to process buildpack group C. If C fails, then the entire detection process will fail.</p>
 <p>If a buildpack group contains composite buildpacks, which in turn may contain more buildpack groups those are expanded using <a href="https://github.com/buildpacks/spec/blob/main/buildpack.md#order-resolution">the order resolution rules</a> such that each buildpack group in the composite buildpack is tried with the other buildpacks in the containing buildpack group.</p>
 <p>For example:</p>

diff --git a/docs/for-buildpack-authors/concepts/caching-strategies/index.html b/docs/for-buildpack-authors/concepts/caching-strategies/index.html
@@ -897,22 +897,22 @@
           <h1 class="title">What caching strategies are available to buildpacks?</h1>
         </div>
 
-        <h1 id="layers">Layers</h1>
+        <h2 id="layers">Layers</h2>
 <p>There are three types of layers that can be contributed to an image</p>
 <ul>
 <li><code>build</code> layers &ndash; the directory will be accessible by subsequent buildpacks,</li>
 <li><code>cache</code> layers &ndash; the directory will be included in the cache,</li>
 <li><code>launch</code> layers &ndash; the directory will be included in the final app image as a single layer,</li>
 </ul>
 <p>In this section we look at caching each layer type.</p>
-<h2 id="layer-metadata">Layer Metadata</h2>
+<h3 id="layer-metadata">Layer Metadata</h3>
 <p>buildpacks ensure byte-for-byte reproducibility of layers.  File creation time is <a href="https://medium.com/buildpacks/time-travel-with-pack-e0efd8bf05db">normalized to January 1, 1980</a> to ensure reproducibility.  Byte-for-byte reproducibility means previous layers can be reused.  However, we may want to invalidate previously cached layers if an important property changes, such as:</p>
 <ul>
 <li>the major version of the runtime changes eg: NodeJS changes from 16 to 18</li>
 <li>requested application dependencies have changed eg: a Python application adds a dependency on the <code>requests</code> module</li>
 </ul>
 <p>Launch layers are exported to an OCI registry.  The layer metadata is commonly used when deciding if a launch layer should be re-used.  A launch layer may be re-used on an OCI registry without downloading the layer to the machine running a build.</p>
-<h2 id="caching-strategies">Caching Strategies</h2>
+<h3 id="caching-strategies">Caching Strategies</h3>
 <p>Caching during the production of an application image is necessarily very flexible.  Most buildpacks that wish to contribute a layer to the application image need only to</p>
 <ol>
 <li>Check that the metadata of the cached layer is current,</li>

diff --git a/docs/for-buildpack-authors/concepts/component-buildpack/index.html b/docs/for-buildpack-authors/concepts/component-buildpack/index.html
@@ -8,7 +8,8 @@
 <meta charset="utf-8">
 <meta http-equiv="x-ua-compatible" content="ie=edge">
 <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
-
+<meta name="description" content="A component buildpack is a buildpack containing /bin/detect and /bin/build executables and that implements the Buildpack Interface.
+"/>
 <link rel="canonical" content="https://buildpacks.io/docs/for-buildpack-authors/concepts/component-buildpack/">
 <link rel="icon" type="image/png" href="/images/favicon.png">
 
@@ -22,7 +23,8 @@
 <meta property="og:url" content="https://buildpacks.io/docs/for-buildpack-authors/concepts/component-buildpack/">
 <meta property="og:locale" content="en_US">
 <meta property="og:site_name" content="Cloud Native Buildpacks">
-
+<meta property="og:description" content="A component buildpack is a buildpack containing /bin/detect and /bin/build executables and that implements the Buildpack Interface.
+">
 <meta property="og:type" content="article">
 <meta property="og:image" content="https://buildpacks.io/images/buildpacks-social-card.jpg">
 <meta property="og:image:alt" content="Buildpacks project logo">
@@ -897,8 +899,22 @@
           <h1 class="title">What is a component buildpack?</h1>
         </div>
 
-        <p>This page is a stub! The CNB project is applying to <a href="https://developers.google.com/season-of-docs/docs/timeline">Google Season of Docs</a> to receive support for improving our documentation. Please check back soon.</p>
-<p>If you are familiar with this content and would like to make a contribution, please feel free to open a PR :)</p>
+        <p>A <strong>component buildpack</strong> is a buildpack containing <code>/bin/detect</code> and <code>/bin/build</code> executables and that implements the <a href="https://github.com/buildpacks/spec/blob/main/buildpack.md#buildpack-interface">Buildpack Interface</a>.</p>
+<h2 id="key-points">Key Points</h2>
+<p>During the <code>build</code> phase, typical component buildpacks might perform one, or more, of the following actions:</p>
+<ul>
+<li>Read the <a href="https://buildpacks.io/docs/for-buildpack-authors/concepts/build-plan/">Buildpack Plan</a> in <code>&lt;plan&gt;</code> to determine what dependencies to provide</li>
+<li>Supply the application with <a href="https://buildpacks.io/docs/for-buildpack-authors/concepts/layer/">dependencies</a> for launch in <code>&lt;layers&gt;/&lt;layer&gt;</code></li>
+<li>Reuse application <a href="https://buildpacks.io/docs/for-buildpack-authors/how-to/write-buildpacks/re-use-layers/">dependencies</a> from a previous image by appending <code>[types]</code> and <code>launch = true</code> to <code>&lt;layers&gt;/&lt;layer&gt;.toml</code></li>
+<li>Contribute <a href="https://buildpacks.io/docs/for-buildpack-authors/concepts/layer/">dependencies</a> added in <code>&lt;layers&gt;/&lt;layer&gt;</code> to subsequent buildpacks</li>
+<li>Reuse <a href="https://buildpacks.io/docs/for-buildpack-authors/how-to/write-buildpacks/create-layer/">cached build dependencies</a> from a previous build by appending <code>[types]</code>, <code>build = true</code> and <code>cache = true</code> to <code>&lt;layers&gt;/&lt;layer&gt;.toml</code></li>
+<li>Compile the application source code into object code</li>
+<li>Remove application source code that is not necessary for launch</li>
+<li>Supply start command in <code>&lt;layers&gt;/launch.toml</code></li>
+<li>Write a partial <a href="https://buildpacks.io/docs/for-buildpack-authors/how-to/write-buildpacks/add-sbom/">Software Bill of Materials</a> to <code>&lt;layers&gt;/&lt;layer&gt;.sbom.&lt;ext&gt;</code> describing any dependencies provided in the layer</li>
+<li>Write a partial <a href="https://buildpacks.io/docs/for-buildpack-authors/how-to/write-buildpacks/add-sbom/">Software Bill of Materials</a> to <code>&lt;layers&gt;/launch.sbom.&lt;ext&gt;</code> describing any provided application dependencies not associated with a layer</li>
+<li>Write a partial <a href="https://buildpacks.io/docs/for-buildpack-authors/how-to/write-buildpacks/add-sbom/">Software Bill of Materials</a> to <code>&lt;layers&gt;/build.sbom.&lt;ext&gt;</code> describing any provided build dependencies not associated with a layer</li>
+</ul>