Merge pull request #634 from buildpacks/fix/node-js-docs

Use named platform variables instead of positional args

content/docs/buildpack-author-guide/create-buildpack/_index.md

@@ -17,7 +17,7 @@ Before we get started, make sure you've got the following installed:
 ## Overview
 <!--+end+-->
 
-This is a step-by-step tutorial for creating a Ruby Cloud Native Buildpack.
+This is a step-by-step tutorial for creating a nodeJS Cloud Native Buildpack.
 
 - [Set up your local environment](/docs/buildpack-author-guide/create-buildpack/setup-local-environment)
 - [Building blocks of a Cloud Native Buildpack](/docs/buildpack-author-guide/create-buildpack/building-blocks-cnb)

content/docs/buildpack-author-guide/create-buildpack/adding-bill-of-materials.md

@@ -66,7 +66,7 @@ Then, in our buildpack implementation we will generate the necessary SBOM metada
 # ...
 
 # Append a Bill-of-Materials containing metadata about the provided node-js version
-cat >> "${layersdir}/node-js.sbom.cdx.json" << EOL
+cat >> "${CNB_LAYERS_DIR}/node-js.sbom.cdx.json" << EOL
 {
   "bomFormat": "CycloneDX",
   "specVersion": "1.4",
@@ -85,7 +85,7 @@ EOL
 We can also add an SBOM entry for each dependency listed in `package.json`.  Here we use `jq` to add a new record to the `components` array in `bundler.sbom.cdx.json`:
 
 ```bash
-node-jsbom="${layersdir}/node-js.sbom.cdx.json"
+node-jsbom="${CNB_LAYERS_DIR}/node-js.sbom.cdx.json"
 cat >> ${node-jsbom} << EOL
 {
   "bomFormat": "CycloneDX",
@@ -113,18 +113,17 @@ echo "---> NodeJS Buildpack"
 
 # ======= MODIFIED =======
 # 1. GET ARGS
-layersdir=$1
-plan=$3
+plan=${CNB_BP_PLAN_PATH}
 
 # 2. CREATE THE LAYER DIRECTORY
-node_js_layer="${layersdir}"/node-js
+node_js_layer="${CNB_LAYERS_DIR}"/node-js
 mkdir -p "${node_js_layer}"
 
 # 3. DOWNLOAD node-js
 default_node_js_version="18.18.1"
 node_js_version=$(cat "$plan" | yj -t | jq -r '.entries[] | select(.name == "node-js") | .metadata.version' || echo ${default_node_js_version})
 node_js_url=https://nodejs.org/dist/v${node_js_version}/node-v${node_js_version}-linux-x64.tar.xz
-remote_nodejs_version=$(cat "${layersdir}/node-js.toml" 2> /dev/null | yj -t | jq -r .metadata.nodejs_version 2>/dev/null || echo 'NOT FOUND')
+remote_nodejs_version=$(cat "${CNB_LAYERS_DIR}/node-js.toml" 2> /dev/null | yj -t | jq -r .metadata.nodejs_version 2>/dev/null || echo 'NOT FOUND')
 if [[ "${node_js_url}" != *"${remote_nodejs_version}"* ]] ; then
     echo "-----> Downloading and extracting NodeJS"
     wget -q -O - "${node_js_url}" | tar -xJf - --strip-components 1 -C "${node_js_layer}"
@@ -133,7 +132,7 @@ else
 fi
 
 # 4. MAKE node-js AVAILABLE DURING LAUNCH and CACHE the LAYER
-    cat > "${layersdir}/node-js.toml" << EOL
+    cat > "${CNB_LAYERS_DIR}/node-js.toml" << EOL
 [types]
 cache = true
 launch = true
@@ -142,7 +141,7 @@ nodejs_version = "${node_js_version}"
 EOL
 
 # 5. SET DEFAULT START COMMAND
-cat >> "${layersdir}/launch.toml" << EOL
+cat >> "${CNB_LAYERS_DIR}/launch.toml" << EOL
 [[processes]]
 type = "web"
 command = "node app.js"
@@ -151,7 +150,7 @@ EOL
 
 # ========== ADDED ===========
 # 6. ADD A SBOM
-node_jsbom="${layersdir}/node-js.sbom.cdx.json"
+node_jsbom="${CNB_LAYERS_DIR}/node-js.sbom.cdx.json"
 cat >> ${node_jsbom} << EOL
 {
   "bomFormat": "CycloneDX",

content/docs/buildpack-author-guide/create-buildpack/build-app.md

@@ -16,7 +16,7 @@ Let's begin by changing the `node-js-buildpack/bin/build`<!--+"{{open}}"+--> so
 
 ### Creating a Layer
 
-A Buildpack layer is represented by a directory inside the [layers directory][layers-dir] provided to our buildpack by the Buildpack execution environment.  As defined by the buildpack specification, the layers directory is always passed to the `build` script as the first positional parameter. To create a new layer directory representing the NodeJS runtime, change the `build` script to look like this:
+A Buildpack layer is represented by a directory inside the [layers directory][layers-dir] provided to our buildpack by the Buildpack execution environment.  As defined by the buildpack specification, the layers directory is always passed to the `build` script as the first positional parameter. To create a new layer directory representing the NodeJS runtime, change the `build` script to look like the following.  The variable `CNB_LAYERS_DIR` is provided to the build script as defined by the [buildpacks specification](https://github.com/buildpacks/spec/blob/main/buildpack.md#positional-arguments-to-detect-and-build-executables).
 
 <!-- file=node-js-buildpack/bin/build -->
 ```bash
@@ -25,9 +25,7 @@ set -eo pipefail
 
 echo "---> NodeJS Buildpack"
 
-layersdir=$1
-
-node_js_layer="${layersdir}"/node-js
+node_js_layer="${CNB_LAYERS_DIR}"/node-js
 mkdir -p "${node_js_layer}"
 ```
 
@@ -48,7 +46,7 @@ The last step in creating a layer is writing a TOML file that contains metadata
 
 <!-- file=node-js-buildpack/bin/build data-target=append -->
 ```bash
-echo -e '[types]\nlaunch = true' > "${layersdir}/node-js.toml"
+echo -e '[types]\nlaunch = true' > "${CNB_LAYERS_DIR}/node-js.toml"
 ```
 
 Now the Buildpack is ready to test.
@@ -64,20 +62,17 @@ set -eo pipefail
 
 echo "---> NodeJS Buildpack"
 
-# 1. GET ARGS
-layersdir=$1
-
-# 2. CREATE THE LAYER DIRECTORY
-node_js_layer="${layersdir}"/node-js
+# 1. CREATE THE LAYER DIRECTORY
+node_js_layer="${CNB_LAYERS_DIR}"/node-js
 mkdir -p "${node_js_layer}"
 
-# 3. DOWNLOAD node-js
+# 2. DOWNLOAD node-js
 echo "---> Downloading and extracting NodeJS"
 node_js_url=https://nodejs.org/dist/v18.18.1/node-v18.18.1-linux-x64.tar.xz
 wget -q -O - "${node_js_url}" | tar -xJf - --strip-components 1 -C "${node_js_layer}"
 
-# 4. MAKE node-js AVAILABLE DURING LAUNCH
-echo -e '[types]\nlaunch = true' > "${layersdir}/node-js.toml"
+# 3. MAKE node-js AVAILABLE DURING LAUNCH
+echo -e '[types]\nlaunch = true' > "${CNB_LAYERS_DIR}/node-js.toml"
 ```
 
 Build your app again:

content/docs/buildpack-author-guide/create-buildpack/caching.md

@@ -13,14 +13,14 @@ To do this, replace the following lines in the `build` script:
 
 ```bash
 # 4. MAKE node-js AVAILABLE DURING LAUNCH
-echo -e '[types]\nlaunch = true' > "${layersdir}/node-js.toml"
+echo -e '[types]\nlaunch = true' > "${CNB_LAYERS_DIR}/node-js.toml"
 ```
 
 with the following:
 
 ```bash
 # 4. MAKE node-js AVAILABLE DURING LAUNCH and CACHE it
-echo -e '[types]\ncache = true\nlaunch = true' > "${layersdir}/node-js.toml"
+echo -e '[types]\ncache = true\nlaunch = true' > "${CNB_LAYERS_DIR}/node-js.toml"
 ```
 
 Your full `node-js-buildpack/bin/build`<!--+"{{open}}"+--> script should now look like the following:
@@ -32,24 +32,25 @@ set -eo pipefail
 
 echo "---> NodeJS Buildpack"
 
-# 1. GET ARGS
-layersdir=$1
-
-# 2. CREATE THE LAYER DIRECTORY
-node_js_layer="${layersdir}"/node-js
+# 1. CREATE THE LAYER DIRECTORY
+node_js_layer="${CNB_LAYERS_DIR}"/node-js
 mkdir -p "${node_js_layer}"
 
-# 3. DOWNLOAD NodeJS
+# 2. DOWNLOAD NodeJS
 echo "---> Downloading and extracting NodeJS"
 node_js_url=https://nodejs.org/dist/v18.18.1/node-v18.18.1-linux-x64.tar.xz
 wget -q -O - "$node_js_url" | tar -xJf - --strip-components 1 -C "${node_js_layer}"
 
-# 4. MAKE NodeJS AVAILABLE DURING LAUNCH and CACHE the LAYER
+# 3. MAKE NodeJS AVAILABLE DURING LAUNCH and CACHE the LAYER
 # ========== MODIFIED ===========
-echo -e '[types]\ncache = true\nlaunch = true' > "${layersdir}/node-js.toml"
+ cat > "${CNB_LAYERS_DIR}/node-js.toml" << EOL
+[types]
+cache = true
+launch = true
+EOL
 
-# 5. SET DEFAULT START COMMAND
-cat > "${layersdir}/launch.toml" << EOL
+# 4. SET DEFAULT START COMMAND
+cat > "${CNB_LAYERS_DIR}/launch.toml" << EOL
 # our web process
 [[processes]]
 type = "web"
@@ -90,18 +91,15 @@ set -eo pipefail
 
 echo "---> NodeJS Buildpack"
 
-# 1. GET ARGS
-layersdir=$1
-
-# 2. CREATE THE LAYER DIRECTORY
-node_js_layer="${layersdir}"/node-js
+# 1. CREATE THE LAYER DIRECTORY
+node_js_layer="${CNB_LAYERS_DIR}"/node-js
 mkdir -p "${node_js_layer}"
 
 # ======= MODIFIED =======
-# 3. DOWNLOAD node-js
+# 2. DOWNLOAD node-js
 node_js_version="18.18.1"
 node_js_url=https://nodejs.org/dist/v${node_js_version}/node-v${node_js_version}-linux-x64.tar.xz
-cached_nodejs_version=$(cat "${layersdir}/node-js.toml" 2> /dev/null | yj -t | jq -r .metadata.nodejs_version 2>/dev/null || echo 'NOT FOUND')
+cached_nodejs_version=$(cat "${CNB_LAYERS_DIR}/node-js.toml" 2> /dev/null | yj -t | jq -r .metadata.nodejs_version 2>/dev/null || echo 'NOT FOUND')
 if [[ "${node_js_url}" != *"${cached_nodejs_version}"* ]] ; then
     echo "-----> Downloading and extracting NodeJS"
     wget -q -O - "${node_js_url}" | tar -xJf - --strip-components 1 -C "${node_js_layer}"
@@ -110,17 +108,17 @@ else
 fi
 
 # ======= MODIFIED =======
-# 4. MAKE node-js AVAILABLE DURING LAUNCH and CACHE the LAYER
-    cat > "${layersdir}/node-js.toml" << EOL
+# 3. MAKE node-js AVAILABLE DURING LAUNCH and CACHE the LAYER
+    cat > "${CNB_LAYERS_DIR}/node-js.toml" << EOL
 [types]
 cache = true
 launch = true
 [metadata]
 nodejs_version = "${node_js_version}"
 EOL
 
-# 5. SET DEFAULT START COMMAND
-cat >> "${layersdir}/launch.toml" << EOL
+# 4. SET DEFAULT START COMMAND
+cat >> "${CNB_LAYERS_DIR}/launch.toml" << EOL
 [[processes]]
 type = "web"
 command = "node app.js"

content/docs/buildpack-author-guide/create-buildpack/make-app-runnable.md

@@ -12,7 +12,7 @@ To make your app runnable, a default start command must be set. You'll need to a
 # ...
 
 # Set default start command
-cat > "${layersdir}/launch.toml" << EOL
+cat > "${CNB_LAYERS_DIR}/launch.toml" << EOL
 [[processes]]
 type = "web"
 command = "node app.js"
@@ -31,24 +31,21 @@ set -eo pipefail
 
 echo "---> NodeJS Buildpack"
 
-# 1. GET ARGS
-layersdir=$1
-
-# 2. CREATE THE LAYER DIRECTORY
-node_js_layer="${layersdir}"/node-js
+# 1. CREATE THE LAYER DIRECTORY
+node_js_layer="${CNB_LAYERS_DIR}"/node-js
 mkdir -p "${node_js_layer}"
 
-# 3. DOWNLOAD node-js
+# 2. DOWNLOAD node-js
 echo "---> Downloading and extracting NodeJS"
 node_js_url=https://nodejs.org/dist/v18.18.1/node-v18.18.1-linux-x64.tar.xz
 wget -q -O - "$node_js_url" | tar -xJf - --strip-components 1 -C "${node_js_layer}"
 
-# 4. MAKE node-js AVAILABLE DURING LAUNCH
-echo -e '[types]\nlaunch = true' > "${layersdir}/node-js.toml"
+# 3. MAKE node-js AVAILABLE DURING LAUNCH
+echo -e '[types]\nlaunch = true' > "${CNB_LAYERS_DIR}/node-js.toml"
 
 # ========== ADDED ===========
-# 5. SET DEFAULT START COMMAND
-cat > "${layersdir}/launch.toml" << EOL
+# 4. SET DEFAULT START COMMAND
+cat > "${CNB_LAYERS_DIR}/launch.toml" << EOL
 [[processes]]
 type = "web"
 command = "node app.js"

content/docs/buildpack-author-guide/create-buildpack/make-buildpack-configurable.md

@@ -23,7 +23,7 @@ if [[ ! -f package.json ]]; then
 fi
 
 # ======= ADDED =======
-plan=$2
+plan=${CNB_BUILD_PLAN_PATH}
 version=3.1.3
 
 if [[ -f .node-js-version ]]; then
@@ -48,19 +48,18 @@ echo "---> NodeJS Buildpack"
 
 # ======= MODIFIED =======
 # 1. GET ARGS
-layersdir=$1
-plan=$3
+plan=${CNB_BP_PLAN_PATH}
 
 # 2. CREATE THE LAYER DIRECTORY
-node_js_layer="${layersdir}"/node-js
+node_js_layer="${CNB_LAYERS_DIR}"/node-js
 mkdir -p "${node_js_layer}"
 
 # ======= MODIFIED =======
 # 3. DOWNLOAD node-js
 default_node_js_version="18.18.1"
 node_js_version=$(cat "$plan" | yj -t | jq -r '.entries[] | select(.name == "node-js") | .metadata.version' || echo ${default_node_js_version})
 node_js_url=https://nodejs.org/dist/v${node_js_version}/node-v${node_js_version}-linux-x64.tar.xz
-remote_nodejs_version=$(cat "${layersdir}/node-js.toml" 2> /dev/null | yj -t | jq -r .metadata.nodejs_version 2>/dev/null || echo 'NOT FOUND')
+remote_nodejs_version=$(cat "${CNB_LAYERS_DIR}/node-js.toml" 2> /dev/null | yj -t | jq -r .metadata.nodejs_version 2>/dev/null || echo 'NOT FOUND')
 if [[ "${node_js_url}" != *"${remote_nodejs_version}"* ]] ; then
     echo "-----> Downloading and extracting NodeJS" ${node_js_version}
     wget -q -O - "${node_js_url}" | tar -xJf - --strip-components 1 -C "${node_js_layer}"
@@ -69,7 +68,7 @@ else
 fi
 
 # 4. MAKE node-js AVAILABLE DURING LAUNCH and CACHE the LAYER
-    cat > "${layersdir}/node-js.toml" << EOL
+    cat > "${CNB_LAYERS_DIR}/node-js.toml" << EOL
 [types]
 cache = true
 launch = true
@@ -79,7 +78,7 @@ EOL
 
 # ========== ADDED ===========
 # 5. SET DEFAULT START COMMAND
-cat >> "${layersdir}/launch.toml" << EOL
+cat >> "${CNB_LAYERS_DIR}/launch.toml" << EOL
 [[processes]]
 type = "web"
 command = "node app.js"

content/docs/buildpack-author-guide/create-buildpack/setup-local-environment.md

@@ -20,7 +20,7 @@ docker rmi test-node-js-app
 ```
 -->
 
-First, we'll create a sample Ruby app that you can use when developing your buildpack:
+First, we'll create a sample nodeJS app that you can use when developing your buildpack:
 
 <!-- test:exec -->
 ```bash

content/docs/buildpack-author-guide/create-buildpack/specify-multiple-process-types.md

@@ -12,7 +12,7 @@ To enable running the debug process, we'll need to have our buildpack define a "
 ```bash
 # ...
 
-cat > "${layersdir}/launch.toml" << EOL
+cat > "${CNB_LAYERS_DIR}/launch.toml" << EOL
 # our web process
 [[processes]]
 type = "web"
@@ -21,7 +21,7 @@ default = true
 
 # our debug process
 [[processes]]
-type = "debug"
+type = "worker"
 command = "node --inspect app.js"
 EOL
 
@@ -37,27 +37,24 @@ set -eo pipefail
 
 echo "---> NodeJS Buildpack"
 
-# 1. GET ARGS
-layersdir=$1
-
-# 2. CREATE THE LAYER DIRECTORY
-node_js_layer="${layersdir}"/node-js
+# 1. CREATE THE LAYER DIRECTORY
+node_js_layer="${CNB_LAYERS_DIR}"/node-js
 mkdir -p "${node_js_layer}"
 
-# 3. DOWNLOAD node-js
+# 2. DOWNLOAD node-js
 echo "---> Downloading and extracting NodeJS"
 node_js_url=https://nodejs.org/dist/v18.18.1/node-v18.18.1-linux-x64.tar.xz
 wget -q -O - "$node_js_url" | tar -xJf - --strip-components 1 -C "${node_js_layer}"
 
-# 4. MAKE node-js AVAILABLE DURING LAUNCH
-    cat > "${layersdir}/node-js.toml" << EOL
+# 3. MAKE node-js AVAILABLE DURING LAUNCH
+    cat > "${CNB_LAYERS_DIR}/node-js.toml" << EOL
 [types]
 launch = true
 EOL
 
 # ========== MODIFIED ===========
-# 5. SET DEFAULT START COMMAND
-cat > "${layersdir}/launch.toml" << EOL
+# 4. SET DEFAULT START COMMAND
+cat > "${CNB_LAYERS_DIR}/launch.toml" << EOL
 # our web process
 [[processes]]
 type = "web"