Skip to content

Commit 942f3ba

Browse files
BRONSOLOBRONSOLO
authored
Merge pull request #10 from plotly/readme-updts
simplify readmes
2 parents bc90b0f + f88223b commit 942f3ba

File tree

3 files changed

+151
-151
lines changed

3 files changed

+151
-151
lines changed

‎.github/README.md

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# Paketo Buildpack for CPython Cloud Native
2+
3+
A copy of the upstream README.md can be found here: [README-upstream.md](README-upstream.md)
4+
5+
# Plotly Branches
6+
7+
- The `main-upstream` branch of this repository is used to sync in the `main` branch of the upstream as its source. It does not contain any custom Plotly code changes
8+
- The `main` branch of this repository is used to be the most up to date branch containing custom Plotly code changes
9+
- The `XY-release` branches of this repository are made off of the `main` branch as part of our code freeze process: [DE Release Guide](https://plotly.atlassian.net/wiki/x/doAbH)
10+
11+
# Plotly Release Flow
12+
13+
- All PRs (other than an upstream sync detailed below) should first land on `main`
14+
- If a PR is needed for a given release, a new PR should be made against that release branch
15+
- When needing to pull in upstream changes (typically done as a post-release task to stay up to date as needed):
16+
- Navigate the the [main-upstream](https://github.com/plotly/paketo-buildpacks_cpython/tree/main-upstream) branch
17+
- Select **Sync fork**
18+
- A PR should then be opened to add these changes to our `main` branch, favouring our custom work whenever there are conflicts
19+

‎README-upstream.md

Lines changed: 0 additions & 139 deletions
This file was deleted.

‎README.md

Lines changed: 132 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,139 @@
11
# Paketo Buildpack for CPython Cloud Native
2+
The CPython Buildpack provides CPython (reference implementation of Python) 3.
3+
The buildpack installs CPython onto the `$PATH` which makes it available for
4+
subsequent buildpacks and in the final running container. It also sets the
5+
`$PYTHONPATH` environment variable for subsequent buildpacks and launch-time
6+
processes.
27

3-
A copy of the upstream README.md can be found here: [README-upstream.md](README-upstream.md)
8+
The buildpack is published for consumption at `gcr.io/paketo-buildpacks/cpython` and
9+
`paketobuildpacks/cpython`.
410

5-
# Plotly Branches
11+
## Behavior
612

7-
- The `main-upstream` branch of this repository is used to sync in the `main` branch of the upstream as its source. It does not contain any custom Plotly code changes
8-
- The `main` branch of this repository is used to be the most up to date branch containing custom Plotly code changes
9-
- The `XY-release` branches of this repository are made off of the `main` branch as part of our code freeze process: [DE Release Guide](https://plotly.atlassian.net/wiki/x/doAbH)
13+
This buildpack always participates.
1014

11-
# Plotly Release Flow
15+
### Build time
16+
This buildpack performs the following actions at build time:
17+
* Contributes `cpython` to a layer - either via a precompiled dependency or by
18+
compiling from source.
19+
* Python is precompiled for recognized, supported stacks (currently the Ubuntu-based stacks)
20+
* Python is compiled from source during the build phase for unrecognized stacks.
21+
* [dependency/](dependency/README.md) contains more information how cpython is built.
22+
* Sets the `PYTHONPYCACHEPREFIX` environment variable to the `/tmp` directory
23+
for this and any subsequent buildpacks.
24+
* This effectively disables the `__pycache__` directories, in turn enabling
25+
reproducible builds.
26+
* It can be overridden via standard means (e.g. `pack build --env
27+
"PYTHONPYCACHEPREFIX=/some/other/dir"`) if there is a need to keep the
28+
`__pycache__` directories in place of reproducible builds.
29+
* Sets the `PYTHONPATH` to the `cpython` layer path for this and any subsequent
30+
buildpacks.
31+
* Adds the newly installed `cpython` bin dir location to the `PATH`.
1232

13-
- All PRs (other than an upstream sync detailed below) should first land on `main`
14-
- If a PR is needed for a given release, a new PR should be made against that release branch
15-
- When needing to pull in upstream changes (typically done as a post-release task to stay up to date as needed):
16-
- Navigate the the [main-upstream](https://github.com/plotly/paketo-buildpacks_cpython/tree/main-upstream) branch
17-
- Select **Sync fork**
18-
- A PR should then be opened to add these changes to our `main` branch, favouring our custom work whenever there are conflicts
33+
### Launch time
34+
This buildpack does the following at launch time:
1935

36+
* Sets a default value for the `PYTHONPATH` environment variable.
37+
38+
## Configuration
39+
40+
### `BP_CPYTHON_VERSION`
41+
The `BP_CPYTHON_VERSION` variable allows you to specify the version of CPython
42+
that is installed. (Available versions can be found in the
43+
[buildpack.toml](./buildpack.toml).)
44+
45+
#### `pack build` flag
46+
```shell
47+
pack build my-app --env BP_CPYTHON_VERSION=3.10.*
48+
```
49+
50+
#### In a [`project.toml`](https://github.com/buildpacks/spec/blob/main/extensions/project-descriptor.md)
51+
```toml
52+
[build]
53+
[[build.env]]
54+
name = 'BP_CPYTHON_VERSION'
55+
value = '3.10.*' # any valid semver constraints (e.g. 3.10.2, 3.*) are acceptable
56+
```
57+
58+
### `BP_CPYTHON_CONFIGURE_FLAGS`
59+
The `BP_CPYTHON_CONFIGURE_FLAGS` variable allows you to specify configure flags
60+
when python is installed from source. This is only applicable when using custom
61+
stacks. Paketo stacks such as `io.buildpacks.stacks.bionic` install pre-built binaries.
62+
63+
* The format is space-separated strings, and they are passed directly to the
64+
`cpython` `./configure` process , e.g. `--foo --bar=baz`.
65+
* See [python documentation](https://docs.python.org/3/using/configure.html) for supported flags.
66+
* Default flags if not specified: `--with-ensurepip`
67+
* Note that default flags are overridden if you specify this environment variable,
68+
which means you almost certainly want to include the defaults along with any custom flags.
69+
- e.g. `--with-ensurepip --foo --bar=baz`
70+
71+
### `BP_LOG_LEVEL`
72+
The `BP_LOG_LEVEL` flag controls the level of verbosity of the buildpack output logs.
73+
For more detail, set it to `debug`.
74+
75+
For example, when compiling from source, setting `BP_LOG_LEVEL=debug` shows the
76+
commands and outputs run to build python.
77+
78+
## Integration
79+
80+
The CPython Buildpack provides `cpython` as a dependency. Downstream
81+
buildpacks, can require the cpython dependency by generating [Build Plan
82+
TOML](https://github.com/buildpacks/spec/blob/master/buildpack.md#build-plan-toml)
83+
file that looks like the following:
84+
85+
```toml
86+
[[requires]]
87+
# The name of the CPython dependency is "cpython". This value is considered
88+
# part of the public API for the buildpack and will not change without a plan
89+
# for deprecation.
90+
name = "cpython"
91+
92+
# The CPython buildpack supports some non-required metadata options.
93+
[requires.metadata]
94+
95+
# The version of the CPython dependency is not required. In the case it
96+
# is not specified, the buildpack will provide the default version, which can
97+
# be seen in the buildpack.toml file.
98+
# If you wish to request a specific version, the buildpack supports
99+
# specifying a semver constraint in the form of "3.*", "3.10.*", or even
100+
# "3.10.2".
101+
version = "3.10.2"
102+
103+
# Setting the build flag to true will ensure that the CPython
104+
# depdendency is available on the $PATH for subsequent buildpacks during
105+
# their build phase. If you are writing a buildpack that needs to use CPython
106+
# during its build process, this flag should be set to true.
107+
build = true
108+
109+
# Setting the launch flag to true will ensure that cpython is
110+
# available to the running application. If you are writing an application
111+
# that needs to run cpython at runtime, this flag should be set to true.
112+
launch = true
113+
```
114+
115+
## Usage
116+
117+
To package this buildpack for consumption:
118+
119+
```
120+
$ ./scripts/package.sh --version <version-number>
121+
```
122+
123+
This will create a `buildpackage.cnb` file under the `build` directory which you
124+
can use to build your app as follows:
125+
`pack build <app-name> -p <path-to-app> -b build/buildpackage.cnb -b <other-buildpacks..>`
126+
127+
To run the unit and integration tests for this buildpack:
128+
```
129+
$ ./scripts/unit.sh && ./scripts/integration.sh
130+
```
131+
132+
## Compatibility
133+
134+
This buildpack is currently only supported on linux distributions.
135+
136+
Pre-compiled distributions of Python are provided for the Paketo stacks (i.e.
137+
`io.buildpacks.stack.jammy` and `io.buildpacks.stacks.bionic`).
138+
139+
Source distributions of Python are provided for all other linux stacks.

0 commit comments

Comments
 (0)