Skip to content

Commit c58e300

Browse files
sgaistsgaist
committed
chore: add README to each sub-package
Taken from original implementation and adapted.
1 parent 4786f8a commit c58e300

File tree

4 files changed

+300
-0
lines changed

4 files changed

+300
-0
lines changed

‎pkg/conda/README.md‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
<!--
2+
// SPDX-FileCopyrightText: Copyright (c) 2013-Present CloudFoundry.org Foundation, Inc. All Rights Reserved.
3+
SPDX-FileContributor: Samuel Gaist <[email protected]>
4+
5+
SPDX-License-Identifier: Apache-2.0
6+
-->
7+
8+
# Sub package for conda environment update
9+
10+
Original implementation from `paketo-buildpacks/conda-env-update`
11+
12+
This sub package runs commands to update the conda environment. It installs the conda environment into a
13+
layer which makes it available for subsequent buildpacks and in the final running container.
14+
15+
## Behavior
16+
17+
This sub package participates when there is an `environment.yml` or
18+
`package-list.txt` file in the app directory.
19+
20+
The buildpack will do the following:
21+
22+
* At build time:
23+
- Requires that conda has already been installed in the build container
24+
- Updates the conda environment and stores it in a layer
25+
- If a `package-list.txt` is in the app dir, a new environment is created
26+
from it
27+
- Otherwise, the `environment.yml` file is used to update the environment
28+
- Reuses the cached conda environment layer from a previous build if and
29+
only if a `package-list.txt` is in the app dir and it has not changed
30+
since the previous build
31+
* At run time:
32+
- Does nothing
33+
34+
## Integration
35+
36+
This sub package provides `conda-environment` as a dependency. Downstream buildpacks can require the
37+
conda-environment dependency by
38+
generating a [Build Plan TOML](https://github.com/buildpacks/spec/blob/master/buildpack.md#build-plan-toml)
39+
file that looks like the following:
40+
41+
```toml
42+
[[requires]]
43+
# The name of the Conda Env Update dependency is "conda-environment". This value is considered
44+
# part of the public API for the buildpack and will not change without a plan
45+
# for deprecation.
46+
name = "conda-environment"
47+
48+
# The Conda Env Update buildpack supports some non-required metadata options.
49+
[requires.metadata]
50+
51+
# Setting the build flag to true will ensure that the conda environment
52+
# layer is available for subsequent buildpacks during their build phase.
53+
# If you are writing a buildpack that needs the conda environment
54+
# during its build process, this flag should be set to true.
55+
build = true
56+
57+
# Setting the launch flag to true will ensure that the conda environment is
58+
# available to the running application. If you are writing an application
59+
# that needs to use the conda environment at runtime, this flag should be set to true.
60+
launch = true
61+
```
62+
63+
## SBOM
64+
65+
This buildpack can generate a Software Bill of Materials (SBOM) for the dependencies of an application.
66+
67+
However, this feature only works if an application vendors its dependencies in
68+
the `vendor` directory. This is due to a limitation in the upstream SBOM
69+
generation library (Syft).
70+
71+
Applications that declare their dependencies via a `package-list.txt` file but
72+
do not vendor them will result in an empty SBOM. Check out the [Paketo SBOM documentation](https://paketo.io/docs/howto/sbom/) for more information about how to access the SBOM.

‎pkg/pip/README.md‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
<!--
2+
// SPDX-FileCopyrightText: Copyright (c) 2013-Present CloudFoundry.org Foundation, Inc. All Rights Reserved.
3+
SPDX-FileContributor: Samuel Gaist <[email protected]>
4+
5+
SPDX-License-Identifier: Apache-2.0
6+
-->
7+
8+
# Sub package for pip installation
9+
10+
Original implementation from `paketo-buildpacks/pip-install`
11+
12+
This sub package installs packages using pip and makes it available to the
13+
application.
14+
15+
## Behavior
16+
This sub package participates if `requirements.txt` exists at the root the app.
17+
18+
The buildpack will do the following:
19+
* At build time:
20+
- Installs the application packages to a layer made available to the app.
21+
- Prepends the layer site-packages onto `PYTHONPATH`.
22+
- If a vendor directory is available, will attempt to run `pip install` in an offline manner.
23+
* At run time:
24+
- Does nothing
25+
26+
## Integration
27+
28+
This sub package provides `site-packages` as a dependency. Downstream buildpacks
29+
can require the `site-packages` dependency by generating a [Build Plan TOML]
30+
(https://github.com/buildpacks/spec/blob/master/buildpack.md#build-plan-toml)
31+
file that looks like the following:
32+
33+
```toml
34+
[[requires]]
35+
36+
# The name of the dependency provided by the Pip Install Buildpack is
37+
# "site-packages". This value is considered part of the public API for the
38+
# buildpack and will not change without a plan for deprecation.
39+
name = "site-packages"
40+
41+
# The Pip Install buildpack supports some non-required metadata options.
42+
[requires.metadata]
43+
44+
# Setting the build flag to true will ensure that the site-packages
45+
# dependency is available on the $PYTHONPATH for subsequent
46+
# buildpacks during their build phase. If you are writing a buildpack that
47+
# needs site-packages during its build process, this flag should be
48+
# set to true.
49+
build = true
50+
51+
# Setting the launch flag to true will ensure that the site-packages
52+
# dependency is available on the $PYTHONPATH for the running
53+
# application. If you are writing an application that needs site-packages
54+
# at runtime, this flag should be set to true.
55+
launch = true
56+
```
57+
58+
## Configuration
59+
60+
### `BP_PIP_DEST_PATH`
61+
62+
The `BP_PIP_DEST_PATH` variable allows you to specify a custom vendor directory.
63+
This should be a directory underneath the working directory.
64+
Will use `./vendor` if not provided.
65+
66+
```shell
67+
BP_PIP_DEST_PATH=my/custom/vendor-dir
68+
```
69+
70+
### `BP_PIP_REQUIREMENT`
71+
72+
The `BP_PIP_REQUIREMENT` variable allows you to specify a custom pip requirement path.
73+
This should be a file underneath the working directory.
74+
Will use `./requirements.txt` if not provided.
75+
76+
```shell
77+
BP_PIP_REQUIREMENT=requirements-dev.txt
78+
```
79+
80+
### `BP_PIP_FIND_LINKS`
81+
82+
The `BP_PIP_FIND_LINKS` variable allows you to specify one or more directories
83+
to pass to `--find-links`. This should be a local path or `file://` URL.
84+
85+
```shell
86+
BP_PIP_FIND_LINKS=./vendor-dir
87+
```
88+
89+
### `PIP_<UPPER_LONG_NAME>`
90+
91+
It is worth noting that the `PIP_<UPPER_LONG_NAME>` configuration is respected
92+
by this buildpack and can be used to tweak the build time CLI properties for
93+
Pip as documented in [Pip's
94+
configuration](https://pip.pypa.io/en/stable/topics/configuration/#environment-variables).

‎pkg/pipenv/README.md‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
<!--
2+
// SPDX-FileCopyrightText: Copyright (c) 2013-Present CloudFoundry.org Foundation, Inc. All Rights Reserved.
3+
SPDX-FileContributor: Samuel Gaist <[email protected]>
4+
5+
SPDX-License-Identifier: Apache-2.0
6+
-->
7+
8+
# Sub package for pipenv installation
9+
10+
Original implementation from `paketo-buildpacks/pipenv-install`
11+
12+
This sub package installs packages using pipenv and makes it available to the
13+
application.
14+
15+
## Behavior
16+
17+
This sub package participates if `Pipfile` exists at the root of the app.
18+
19+
The buildpack will do the following:
20+
- Installs the application packages to a layer made available to the app.
21+
- Prepends the layer site-packages onto `PYTHONPATH`.
22+
- Prepends the layer's `bin` directory to the `PATH`.
23+
24+
This buildpack speeds up the build process by reusing (the layer of) installed
25+
packages from a previous build if it exists, and later cleaning up any unused
26+
packages. For apps that do not have a `Pipfile.lock`, clean-up is not performed
27+
to avoid the overhead of generating a lock file. Users of such apps should
28+
either include a lock file with their app, or clear their build cache during a
29+
rebuild to avoid any unused packages in the built image.
30+
31+
## Integration
32+
33+
The sub package provides `site-packages` as a dependency. Downstream
34+
buildpacks can require the `site-packages` dependency by generating a [Build Plan TOML]
35+
(https://github.com/buildpacks/spec/blob/master/buildpack.md#build-plan-toml)
36+
file that looks like the following:
37+
38+
```toml
39+
[[requires]]
40+
41+
# The name of the dependency provided by the Pipenv Install Buildpack is
42+
# "site-packages". This value is considered part of the public API for the
43+
# buildpack and will not change without a plan for deprecation.
44+
name = "site-packages"
45+
46+
# The Pipenv Install buildpack supports some non-required metadata options.
47+
[requires.metadata]
48+
49+
# Set the build flag to true to make the site-packages dependency available on the $PYTHONPATH/$PATH
50+
# for subsequent buildpacks during their build phase.
51+
build = true
52+
53+
# Set the launch flag to true to make the site-packages dependency available on the $PYTHONPATH/$PATH
54+
# for the running application.
55+
launch = true
56+
```
57+
58+
## SBOM
59+
60+
This buildpack can generate a Software Bill of Materials (SBOM) for the dependencies of an application.
61+
62+
However, this feature only works if the application already has a `Pipfile.lock` file.
63+
This is due to a limitation in the upstream SBOM generation library (Syft).
64+
65+
Applications that declare their dependencies via a `Pipfile` but do not include
66+
a `Pipfile.lock` will result in an empty SBOM. Check out the [Paketo SBOM
67+
documentation](https://paketo.io/docs/howto/sbom/) for more information about
68+
how to access the SBOM.

‎pkg/poetry/README.md‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
<!--
2+
// SPDX-FileCopyrightText: Copyright (c) 2013-Present CloudFoundry.org Foundation, Inc. All Rights Reserved.
3+
SPDX-FileContributor: Samuel Gaist <[email protected]>
4+
5+
SPDX-License-Identifier: Apache-2.0
6+
-->
7+
8+
# Sub package for poetry installation
9+
10+
Original implementation from `paketo-buildpack/poetry-install`
11+
12+
This sub package installs packages using [Poetry](https://python-poetry.org/) and
13+
makes the installed packages available to the application.
14+
15+
## Behavior
16+
17+
This sub package participates if `pyproject.toml` exists at the root the app.
18+
19+
The buildpack will do the following:
20+
* At build time:
21+
- Creates a virtual environment, installs the application packages to it,
22+
and makes this virtual environment available to the app via a layer called `poetry-venv`.
23+
- Configures `poetry` to locate this virtual environment via the
24+
environment variable `POETRY_VIRTUAL_ENVS_PATH`.
25+
- Prepends the layer `poetry-venv` onto `PYTHONPATH`.
26+
- Prepends the `bin` directory of the `poetry-venv` layer to the `PATH` environment variable.
27+
* At run time:
28+
- Does nothing
29+
30+
## Integration
31+
32+
This sub package provides `poetry-venv` as a dependency. Downstream buildpacks
33+
can require the `poetry-venv` dependency by generating a [Build Plan TOML]
34+
(https://github.com/buildpacks/spec/blob/master/buildpack.md#build-plan-toml)
35+
file that looks like the following:
36+
37+
```toml
38+
[[requires]]
39+
40+
# The name of the dependency provided by the Poetry Install Buildpack is
41+
# "poetry-venv". This value is considered part of the public API for the
42+
# buildpack and will not change without a plan for deprecation.
43+
name = "poetry-venv"
44+
45+
# The Poetry Install buildpack supports some non-required metadata options.
46+
[requires.metadata]
47+
48+
# Setting the build flag to true will ensure that the poetry-venv
49+
# dependency is available on the $PYTHONPATH for subsequent
50+
# buildpacks during their build phase. If you are writing a buildpack that
51+
# needs poetry-venv during its build process, this flag should be
52+
# set to true.
53+
build = true
54+
55+
# Setting the launch flag to true will ensure that the poetry-venv
56+
# dependency is available on the $PYTHONPATH for the running
57+
# application. If you are writing an application that needs poetry-venv
58+
# at runtime, this flag should be set to true.
59+
launch = true
60+
```
61+
62+
## Known issues and limitations
63+
64+
* This buildpack will not work in an offline/air-gapped environment: vendoring
65+
of dependencies is not supported. This is a limitation of `poetry` - which
66+
itself does not support vendoring dependencies.

0 commit comments

Comments
 (0)