From a83f1bb034a4cf46f74d093d1d3d814edc243d13 Mon Sep 17 00:00:00 2001 From: Hanan Younes Date: Sun, 6 Oct 2024 20:53:39 -0400 Subject: [PATCH 1/5] adds platform env var related content from the spec Signed-off-by: Hanan Younes --- .../how-to/build-inputs/build-env.md | 59 +++++++++++++++++++ 1 file changed, 59 insertions(+) create mode 100644 content/docs/for-platform-operators/how-to/build-inputs/build-env.md diff --git a/content/docs/for-platform-operators/how-to/build-inputs/build-env.md b/content/docs/for-platform-operators/how-to/build-inputs/build-env.md new file mode 100644 index 000000000..a05e75b10 --- /dev/null +++ b/content/docs/for-platform-operators/how-to/build-inputs/build-env.md @@ -0,0 +1,59 @@ ++++ +title="Specify the build time environment variables" +weight=4 ++++ + +Environment variables are any values used to allow `Buildpacks` configurability. Some environment variables can't be modified while others are expected to get changed to allow a level of customization. + + + +## Buildpack Environment + +### Base Image-Provided Variables + +Environment variables that are set in the `lifecycle` execution environment and are inherited by the +buildpack without any modification, such as: + +| Env Variable | Description | +|-----------------------------|--------------------------------| +| `HOME` | Current user's home directory | + +### POSIX Path Variables + +Environment variables that are set in the `lifecycle` execution environment. These variables can be modified by previous buildpacks before they being passed to the next buildpack: + +| Env Variable | Layer Path | Contents | +|-------------------|--------------|------------------| +| `PATH` | `/bin` | binaries | +| `LD_LIBRARY_PATH` | `/lib` | shared libraries | +| `LIBRARY_PATH` | `/lib` | static libraries | +| `CPATH` | `/include` | header files | +| `PKG_CONFIG_PATH` | `/pkgconfig` | pc files | + +> Note: the `platform` does not assume any other `base-image` provided environment variables are inherited by the buildpack. + +### User-Provided Variables + +These variables are usually supplied by the `platform` as files in the `/env/` directory. Each file defines a single environment variable, where the file name defines the key and the file contents define the value. + +Only user-provided environment variables that are [POSIX path variables](#posix-path-variables) can be modified by prior buildpacks; however the user-provided value always get prepended to the buildpack-provided value. + +> Note: the `platform` does not set user-provided environment variables directly in the `lifecycle` execution environment. + +### Operator-Defined Variables + +The `platform` supplies Operator-defined environment variables as files in the `/env/` directory. + +Operator-defined environment variables can be modified by previous buildpacks before getting passed to the following buildpack; however, the operator-defined value is always applied after the buildpack-provided value. + +> Note: the `platform` does not set operator-provided environment variables directly in the `lifecycle` execution environment. + +## Launch Environment + +User-provided modifications to the process execution environment are set directly in the `lifecycle` execution environment. + +The process inherits both `base-image-provided` and `user-provided` variables from the `lifecycle` execution environment with the following exceptions: + +* `CNB_APP_DIR`, `CNB_LAYERS_DIR` and `CNB_PROCESS_TYPE` SHALL NOT be set in the process execution environment. +* `/cnb/process` SHALL be removed from the beginning of `PATH`. +* The lifecycle SHALL apply buildpack-provided modifications to the environment as outlined in the [Buildpack Interface Specification](https://github.com/buildpacks/spec/blob/main/buildpack.md). From 811a4aa9c49fd5643f8eafb69b9d92d9a62970c1 Mon Sep 17 00:00:00 2001 From: Hanan Younes Date: Thu, 10 Oct 2024 21:24:50 -0400 Subject: [PATCH 2/5] adds reviewers feedback Signed-off-by: Hanan Younes --- .../how-to/build-inputs/build-env.md | 51 ++----------------- 1 file changed, 5 insertions(+), 46 deletions(-) diff --git a/content/docs/for-platform-operators/how-to/build-inputs/build-env.md b/content/docs/for-platform-operators/how-to/build-inputs/build-env.md index a05e75b10..014a8c7b2 100644 --- a/content/docs/for-platform-operators/how-to/build-inputs/build-env.md +++ b/content/docs/for-platform-operators/how-to/build-inputs/build-env.md @@ -7,53 +7,12 @@ Environment variables are any values used to allow `Buildpacks` configurability. -## Buildpack Environment +At `build` time, platform operators usually control what is included in the `build` environment because `platform-defined` environment variables override any previous values such as `user-provided` and `buildpack-provided` variables. -### Base Image-Provided Variables +### Example -Environment variables that are set in the `lifecycle` execution environment and are inherited by the -buildpack without any modification, such as: +PLACEHOLDER -| Env Variable | Description | -|-----------------------------|--------------------------------| -| `HOME` | Current user's home directory | +For more details on environment variables, see the [Specify the environment][env] page. -### POSIX Path Variables - -Environment variables that are set in the `lifecycle` execution environment. These variables can be modified by previous buildpacks before they being passed to the next buildpack: - -| Env Variable | Layer Path | Contents | -|-------------------|--------------|------------------| -| `PATH` | `/bin` | binaries | -| `LD_LIBRARY_PATH` | `/lib` | shared libraries | -| `LIBRARY_PATH` | `/lib` | static libraries | -| `CPATH` | `/include` | header files | -| `PKG_CONFIG_PATH` | `/pkgconfig` | pc files | - -> Note: the `platform` does not assume any other `base-image` provided environment variables are inherited by the buildpack. - -### User-Provided Variables - -These variables are usually supplied by the `platform` as files in the `/env/` directory. Each file defines a single environment variable, where the file name defines the key and the file contents define the value. - -Only user-provided environment variables that are [POSIX path variables](#posix-path-variables) can be modified by prior buildpacks; however the user-provided value always get prepended to the buildpack-provided value. - -> Note: the `platform` does not set user-provided environment variables directly in the `lifecycle` execution environment. - -### Operator-Defined Variables - -The `platform` supplies Operator-defined environment variables as files in the `/env/` directory. - -Operator-defined environment variables can be modified by previous buildpacks before getting passed to the following buildpack; however, the operator-defined value is always applied after the buildpack-provided value. - -> Note: the `platform` does not set operator-provided environment variables directly in the `lifecycle` execution environment. - -## Launch Environment - -User-provided modifications to the process execution environment are set directly in the `lifecycle` execution environment. - -The process inherits both `base-image-provided` and `user-provided` variables from the `lifecycle` execution environment with the following exceptions: - -* `CNB_APP_DIR`, `CNB_LAYERS_DIR` and `CNB_PROCESS_TYPE` SHALL NOT be set in the process execution environment. -* `/cnb/process` SHALL be removed from the beginning of `PATH`. -* The lifecycle SHALL apply buildpack-provided modifications to the environment as outlined in the [Buildpack Interface Specification](https://github.com/buildpacks/spec/blob/main/buildpack.md). +[env]: https://buildpacks.io/docs/for-buildpack-authors/how-to/write-buildpacks/specify-env/ From a51eed2dcc5f52bc40183932ebae65c1b20be50e Mon Sep 17 00:00:00 2001 From: Hanan Younes Date: Fri, 25 Oct 2024 21:14:32 -0400 Subject: [PATCH 3/5] adds few updates & links Signed-off-by: Hanan Younes --- .../how-to/build-inputs/build-env.md | 17 +++++++++++++---- 1 file changed, 13 insertions(+), 4 deletions(-) diff --git a/content/docs/for-platform-operators/how-to/build-inputs/build-env.md b/content/docs/for-platform-operators/how-to/build-inputs/build-env.md index 014a8c7b2..59a2e0dfc 100644 --- a/content/docs/for-platform-operators/how-to/build-inputs/build-env.md +++ b/content/docs/for-platform-operators/how-to/build-inputs/build-env.md @@ -3,16 +3,25 @@ title="Specify the build time environment variables" weight=4 +++ -Environment variables are any values used to allow `Buildpacks` configurability. Some environment variables can't be modified while others are expected to get changed to allow a level of customization. +Environment variables are used to configure buildpack behavior. They may be specified by: + +* The platform operator (this page) +* The end user (see [Customize buildpack behavior with build-time environment variables][end user]) +* Other buildpacks (see [Specify the environment][env]) -At `build` time, platform operators usually control what is included in the `build` environment because `platform-defined` environment variables override any previous values such as `user-provided` and `buildpack-provided` variables. +When more than one entity specifies the same environment variable, the order of precedence is as shown above, with the platform operator having ultimate say over what the final value of the variable will be. + +The platform operator specifies environment variables in a manner that is very similar to buildpacks (see XXX), but with a few differences. Namely: + +* The env directory is `/cnb/build-config` +* When no suffix is provided, the modification behavior is `default` +For more information, consult the [Platform Specification](https://github.com/buildpacks/spec/blob/main/platform.md). ### Example PLACEHOLDER -For more details on environment variables, see the [Specify the environment][env] page. - [env]: https://buildpacks.io/docs/for-buildpack-authors/how-to/write-buildpacks/specify-env/ +[end user]: https://buildpacks.io/docs/for-app-developers/how-to/build-inputs/configure-build-time-environment/ From 18a1208a3bf29ae3340608fecda119a749f9dd49 Mon Sep 17 00:00:00 2001 From: Hanan Younes Date: Fri, 25 Oct 2024 21:16:58 -0400 Subject: [PATCH 4/5] adds minor update Signed-off-by: Hanan Younes --- .../for-platform-operators/how-to/build-inputs/build-env.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/content/docs/for-platform-operators/how-to/build-inputs/build-env.md b/content/docs/for-platform-operators/how-to/build-inputs/build-env.md index 59a2e0dfc..11914f814 100644 --- a/content/docs/for-platform-operators/how-to/build-inputs/build-env.md +++ b/content/docs/for-platform-operators/how-to/build-inputs/build-env.md @@ -3,7 +3,7 @@ title="Specify the build time environment variables" weight=4 +++ -Environment variables are used to configure buildpack behavior. They may be specified by: +`Environment variables` are used to configure buildpack behavior. They may be specified by: * The platform operator (this page) * The end user (see [Customize buildpack behavior with build-time environment variables][end user]) @@ -11,9 +11,9 @@ Environment variables are used to configure buildpack behavior. They may be spec -When more than one entity specifies the same environment variable, the order of precedence is as shown above, with the platform operator having ultimate say over what the final value of the variable will be. +When more than one entity specifies the same `environment variable`, the order of precedence is as shown above, with the platform operator having ultimate say over what the final value of the variable will be. -The platform operator specifies environment variables in a manner that is very similar to buildpacks (see XXX), but with a few differences. Namely: +The platform operator specifies `environment variables` in a manner that is very similar to buildpacks (see XXX), but with a few differences. Namely: * The env directory is `/cnb/build-config` * When no suffix is provided, the modification behavior is `default` From 1e0fd93a229d91fc517497ca5494121735fa1346 Mon Sep 17 00:00:00 2001 From: Hanan Younes Date: Wed, 30 Oct 2024 09:29:00 -0400 Subject: [PATCH 5/5] added an example Signed-off-by: Hanan Younes --- .../how-to/build-inputs/build-env.md | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/content/docs/for-platform-operators/how-to/build-inputs/build-env.md b/content/docs/for-platform-operators/how-to/build-inputs/build-env.md index 11914f814..7efdc32b7 100644 --- a/content/docs/for-platform-operators/how-to/build-inputs/build-env.md +++ b/content/docs/for-platform-operators/how-to/build-inputs/build-env.md @@ -15,13 +15,20 @@ When more than one entity specifies the same `environment variable`, the order o The platform operator specifies `environment variables` in a manner that is very similar to buildpacks (see XXX), but with a few differences. Namely: -* The env directory is `/cnb/build-config` +* The directory for environment variable settings `/cnb/build-config` * When no suffix is provided, the modification behavior is `default` For more information, consult the [Platform Specification](https://github.com/buildpacks/spec/blob/main/platform.md). ### Example -PLACEHOLDER +Platform operators can make choices that "override" or provide defaults for application authors. In the following configuration the platform operator overrides the value of `CGO_ENABLED` for all application authors. The value of `PIP_VERBOSE` is set by default and can be overridden by buildpack authors or application authors. Any value for the environment variable `CLASSPATH` is prepended with the values provided by the platform operator. + +```bash +$ tree /cnb/buildconfig/env +├── CGO_ENABLED.override +├── PIP_VERBOSE +└── CLASSPATH.prepend +``` [env]: https://buildpacks.io/docs/for-buildpack-authors/how-to/write-buildpacks/specify-env/ [end user]: https://buildpacks.io/docs/for-app-developers/how-to/build-inputs/configure-build-time-environment/