chore: add README files

sgaist · sgaist · commit 48b5f281a6d4 · 2025-05-20T17:27:50.000+02:00
diff --git a/README.md b/README.md
@@ -5,11 +5,10 @@ SPDX-FileContributor: Samuel Gaist <samuel.gaist@idiap.ch>
 SPDX-License-Identifier: Apache-2.0
 -->
 
-# Python Packagers Cloud Native Buildpack
+# Python Installers Cloud Native Buildpack
 
-The Paketo Buildpack for Python Packagers is a Cloud Native Buildpack that
-installs packages using the adequate tool selected based on the content of the
-application sources and makes it available to it.
+The Paketo Buildpack for Python Installers is a Cloud Native Buildpack that
+installs python package managers.
 
 The buildpack is published for consumption at
 `gcr.io/paketo-buildpacks/python-installers` and
@@ -18,14 +17,16 @@ The buildpack is published for consumption at
 ## Behavior
 This buildpack participates if one of the following detection succeeds:
 
-- (conda)[conda/README.md] -> `environment.yml`
-- (pip)[pip/README.md] -> `requirements.txt`
-- (pipenv)[pipenv/README.md] -> `Pipfile`
-- (poetry)[poetry/README.md] -> `pyproject.toml`
+- (miniconda)[installers/pkg/minconda/README.md] -> Always
+- (pip)[installers/ppkg/pip/README.md] -> Always
+- (pipenv)[installers/ppkg/pipenv/README.md] -> Always
+- (poetry)[installers/ppkg/poetry/README.md] -> `pyproject.toml` is present in the root folder
 
 The buildpack will do the following:
 * At build time:
-  - Installs the application packages to a layer made available to the app.
+  - Installs the package manager
+  - Makes it available on the `PATH`
+  - Adjusts `PYTHONPATH` as required
 * At run time:
   - Does nothing
 
diff --git a/pkg/installers/miniconda/README.md b/pkg/installers/miniconda/README.md
@@ -0,0 +1,74 @@
+<!--
+// SPDX-FileCopyrightText: Copyright (c) 2013-Present CloudFoundry.org Foundation, Inc. All Rights Reserved.
+SPDX-FileContributor: Samuel Gaist <samuel.gaist@idiap.ch>
+
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# Sub-package for Miniconda installation
+
+Original implementation from `paketo-buildpack/miniconda`
+
+This sub-package installs miniconda into a layer and makes it available on the
+PATH.
+
+## Configuration
+
+|  Environment Variable  | Description                                                      |
+|------------------------|------------------------------------------------------------------|
+| `$BP_MINICONDA_SOLVER` | Configure the solver to be used (current valid value is `mamba`) |
+
+## Integration
+
+The Miniconda CNB provides conda as a dependency. Downstream buildpacks can
+require the conda dependency by generating a [Build Plan
+TOML](https://github.com/buildpacks/spec/blob/master/buildpack.md#build-plan-toml)
+file that looks like the following:
+
+```toml
+[[requires]]
+
+  # The name of the Miniconda dependency is "conda". This value is considered
+  # part of the public API for the buildpack and will not change without a plan
+  # for deprecation.
+  name = "conda"
+
+  # The version of the conda dependency is not required. In the case it
+  # is not specified, the buildpack will provide the default version, which can
+  # be seen in the buildpack.toml file.
+  # If you wish to request a specific version, the buildpack supports
+  # specifying a semver constraint in the form of "4.*", "4.7.*", or even
+  # "4.7.12".
+  version = "4.7.12"
+
+  # The Miniconda buildpack supports some non-required metadata options.
+  [requires.metadata]
+
+    # Setting the build flag to true will ensure that the conda
+    # dependency is available on the $PATH for subsequent buildpacks during
+    # their build phase. If you are writing a buildpack that needs to run
+    # miniconda during its build process, this flag should be set to true.
+    build = true
+
+    # Setting the launch flag to true will ensure that the conda
+    # dependency is available on the $PATH for the running application. If you are
+    # writing an application that needs to run miniconda at runtime, this flag
+    # should be set to true.
+    launch = true
+```
+
+## Vendoring
+
+Follow these steps to vendor python packages in your app using conda
+
+**Prerequisites**
+- Must be run on linux OS and **case-sensitive file system**
+- Install conda build tools: `conda install conda-build`
+
+**Steps**
+1. `cd <my_conda_app>`
+1. Create `environment.yml` file in the root of your app
+1. `CONDA_PKGS_DIRS=vendor/noarch conda env create -f environment.yml -n <env_name>`
+1. `conda index vendor`
+1. `conda list -n <env_name> -e > package-list.txt`
+1. Commit `environment.yml`, `vendor`, and `package-list.txt`
diff --git a/pkg/installers/pip/README.md b/pkg/installers/pip/README.md
@@ -0,0 +1,74 @@
+<!--
+// SPDX-FileCopyrightText: Copyright (c) 2013-Present CloudFoundry.org Foundation, Inc. All Rights Reserved.
+SPDX-FileContributor: Samuel Gaist <samuel.gaist@idiap.ch>
+
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# Sub-package for pip installation
+
+Original implementation from `paketo-buildpack/pip`
+
+This sub-package installs pip into a layer and places it on the `PATH`.
+
+## Behavior
+This sub-package always participates.
+
+The buildpack will do the following:
+* At build time:
+  - Contributes the `pip` binary to a layer
+  - Prepends the `pip` layer to the `PYTHONPATH`
+  - Adds the newly installed pip location to `PATH`
+* At run time:
+  - Does nothing
+
+## Configuration
+| Environment Variable | Description
+| -------------------- | -----------
+| `$BP_PIP_VERSION` | Configure the version of pip to install. Buildpack releases (and the pip versions for each release) can be found [here](https://github.com/paketo-buildpacks/pip/releases).
+
+Note that Pip releases are of the form `X.Y` instead of `X.Y.0`, so providing
+`X.Y` will attempt to match that exact version. Providing `X.Y.Z` will select
+the exact patch version, and providing `X.Y.*` or `~X.Y` will select the latest
+patch version.
+
+## Integration
+
+The Pip CNB provides pip as a dependency. Downstream buildpacks can require the pip
+dependency by generating a [Build Plan
+TOML](https://github.com/buildpacks/spec/blob/master/buildpack.md#build-plan-toml)
+file that looks like the following:
+
+```toml
+[[requires]]
+
+  # The name of the Pip dependency is "pip". This value is considered
+  # part of the public API for the buildpack and will not change without a plan
+  # for deprecation.
+  name = "pip"
+
+  # The version of the Pip dependency is not required. In the case it
+  # is not specified, the buildpack will select the latest supported version in
+  # the buildpack.toml.
+  # If you wish to request a specific version, the buildpack supports
+  # specifying a semver constraint in the form of "21.*", "21.0.*", or even
+  # "21.0.1".
+  version = "21.0.1"
+
+  # The Pip buildpack supports some non-required metadata options.
+  [requires.metadata]
+
+    # Setting the build flag to true will ensure that the Pip dependency is
+    # available on the $PATH, and the $PYTHONPATH contains the path to pip for
+    # subsequent buildpacks during their build phase. If you are writing a
+    # buildpack that needs to run Pip during its build process, this flag should
+    # be set to true.
+    build = true
+
+    # Setting the launch flag to true will ensure that the Pip
+    # dependency is available on the $PATH, and the $PYTHONPATH contains the
+    # path to pip for the running application. If you are writing an
+    # application that needs to run Pip at runtime, this flag should be set to
+    # true.
+    launch = true
+```
diff --git a/pkg/installers/pipenv/README.md b/pkg/installers/pipenv/README.md
@@ -0,0 +1,75 @@
+<!--
+// SPDX-FileCopyrightText: Copyright (c) 2013-Present CloudFoundry.org Foundation, Inc. All Rights Reserved.
+SPDX-FileContributor: Samuel Gaist <samuel.gaist@idiap.ch>
+
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# Sub-package for Pipenv installation
+
+Original implementation from `paketo-buildpack/pipenv`
+
+This sub-package installs[pipenv](https://pypi.org/project/pipenv) into a layer
+and makes it available on the `PATH`.
+
+## Behavior
+This sub-package always participates.
+
+It will do the following:
+* At build time:
+  - Contributes the `pipenv` binary to a layer
+  - Prepends the `pipenv` layer to the `PYTHONPATH`
+  - Adds the newly installed pipenv location to `PATH`
+* At run time:
+  - Does nothing
+
+## Configuration
+| Environment Variable | Description                                                                                                                                                                                    |
+|----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `$BP_PIPENV_VERSION` | Configure the version of pipenv to install. Buildpack releases (and the supported pipenv versions for each release) can be found [here](https://github.com/paketo-buildpacks/pipenv/releases). |
+
+## Integration
+
+The Pipenv CNB provides pipenv as a dependency. Downstream buildpacks can
+require the pipenv dependency by generating a [Build Plan
+TOML](https://github.com/buildpacks/spec/blob/master/buildpack.md#build-plan-toml)
+file that looks like the following:
+
+```toml
+[[requires]]
+
+  # The name of the Pipenv dependency is "pipenv". This value is considered
+  # part of the public API for the buildpack and will not change without a plan
+  # for deprecation.
+  name = "pipenv"
+
+  # The Pipenv buildpack supports some non-required metadata options.
+  [requires.metadata]
+    
+    # Use `version` to request a specific version of `pipenv`.
+    # This buildpack supports specifying a semver constraint in the form of "2018.*", "2018.11.*",
+    # or even "2018.11.26".
+    # Optional, defaults to the latest version of `pipenv` found in the `buildpack.toml` file.
+    version = "2018.11.26"
+
+    # When `build` is true, this buildpack will ensure that `pipenv` is available
+    # on the `$PATH` for later buildpacks.
+    # Optional, default false.
+    build = true
+
+    # When `launch` is true, this buildpack will ensure that `pipenv` is available
+    # on the `$PATH` for the running application.
+    # Optional, default false.
+    launch = true
+```
+
+## Limitations
+
+This buildpack requires internet connectivity to install `pipenv`.
+Installation in an air-gapped environment is not supported.
+
+The dependency contained in `buildpack.toml` is not actually used, as `pipenv` is
+installed directly from the internet. However, the rest of the dependency
+metadata is used (e.g. for generating an SBOM). This will be addressed in
+upcoming work which will change the way dependencies are consumed by
+buildpacks.
diff --git a/pkg/installers/poetry/README.md b/pkg/installers/poetry/README.md
@@ -0,0 +1,90 @@
+<!--
+// SPDX-FileCopyrightText: Copyright (c) 2013-Present CloudFoundry.org Foundation, Inc. All Rights Reserved.
+SPDX-FileContributor: Samuel Gaist <samuel.gaist@idiap.ch>
+
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# Poetry Cloud Native Buildpack
+## `gcr.io/paketo-buildpacks/poetry`
+
+The Paketo Buildpack for Poetry is a Cloud Native Buildpack that installs [Poetry](https://python-poetry.org/) into a
+layer and places it on the `PATH`.
+
+The buildpack is published for consumption at `gcr.io/paketo-buildpacks/poetry` and
+`paketobuildpacks/poetry`.
+
+## Detection
+
+* Detects when `pyproject.toml` exists.
+* Provides `poetry`.
+* Always requires `cpython` and `pip`.
+* Optionally requires `poetry` when `BP_POETRY_VERSION` is set.
+
+## Build
+* Contributes the `poetry` binary to a layer
+* Prepends the `poetry` layer to the `PYTHONPATH` environment variable
+* Adds the newly installed `poetry` location to the `PATH` environment variable
+
+## Configuration
+| Environment Variable | Description                                                                                                                                                                          |
+|----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `$BP_POETRY_VERSION` | Configure the version of Poetry to install. Buildpack releases (and the Poetry versions for each release) can be found [here](https://github.com/paketo-buildpacks/poetry/releases). |
+
+## Integration
+
+The Poetry CNB provides Poetry as a dependency. Downstream buildpacks can require the Poetry
+dependency by generating a [Build Plan
+TOML](https://github.com/buildpacks/spec/blob/master/buildpack.md#build-plan-toml)
+file that looks like the following:
+
+```toml
+[[requires]]
+
+  # The name of the Poetry dependency is "poetry". This value is considered
+  # part of the public API for the buildpack and will not change without a plan
+  # for deprecation.
+  name = "poetry"
+
+  # The Poetry buildpack supports some non-required metadata options.
+  [requires.metadata]
+
+    # Optional.
+    # When not specified, the buildpack will select the latest supported version from buildpack.toml
+    # This buildpack only supports exact version numbers.
+    version = "21.0.1"
+
+    # Set to true to ensure that `poetry` is avilable on both `$PATH` and `$PYTHONPATH` for subsequent buildpacks.
+    build = true
+
+    # Set to true to ensure that `poetry` is avilable on both `$PATH` and `$PYTHONPATH` for the launch container.
+    launch = true
+```
+
+## Usage
+
+To package this buildpack for consumption:
+```
+$ ./scripts/package.sh --version x.x.x
+```
+This will create a `buildpackage.cnb` file under the build directory which you
+can use to build your app as follows:
+
+```shell
+pack build <app-name> \
+  --path <path-to-app> \
+  --buildpack build/buildpackage.cnb \
+  --buildpack <other-buildpacks..>
+```
+
+To run the unit and integration tests for this buildpack:
+```shell
+$ ./scripts/unit.sh && ./scripts/integration.sh
+```
+
+## Known issues and limitations
+
+* This buildpack does not work in an offline/air-gapped environment; it
+  requires internet access to install `poetry`. The impact of this limitation
+  is mitigated by the fact that `poetry` itself does not support vendoring of
+  dependencies, and so cannot function in an offline/air-gapped environment.
