portable-python 2.0.0__tar.gz → 2.0.1__tar.gz

portable_python-2.0.1/.claude/settings.json

@@ -0,0 +1,10 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(.venv/bin/portable-python:*)",
+      "Bash(.venv/bin/pytest:*)",
+      "Bash(.venv/bin/python scripts/check_okf.py:*)",
+      "Bash(tox:*)"
+    ]
+  }
+}

portable_python-2.0.1/.dockerignore

@@ -0,0 +1,15 @@
+.*cache
+.DS_Store*
+*.egg*
+.idea
+*.lock
+*.log
+.tox
+.venv*
+.*version
+
+_Dockerfile*
+__pycache__
+_tmp
+build
+dist

portable_python-2.0.1/.github/workflows/release.yml

@@ -0,0 +1,26 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v[0-9]*'
+
+jobs:
+  publish:
+
+    runs-on: ubuntu-latest
+    environment: release
+    permissions:
+      id-token: write  # mandatory for trusted publishing
+
+    steps:
+    - uses: actions/checkout@v6
+    - uses: actions/setup-python@v6
+      with:
+        python-version: "3.14"
+
+    - uses: astral-sh/setup-uv@v7
+    - run: uvx --with tox-uv tox -e py,style
+    - run: uv build
+    - name: Publish to PyPI
+      uses: pypa/gh-action-pypi-publish@release/v1

portable_python-2.0.1/.github/workflows/tests.yml

@@ -0,0 +1,59 @@
+name: Tests
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: Test py${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+
+    steps:
+    - uses: actions/checkout@v6
+    - uses: actions/setup-python@v6
+      with:
+        python-version: ${{ matrix.python-version }}
+
+    - uses: astral-sh/setup-uv@v7
+    - run: uvx --with tox-uv tox -e py
+
+    - uses: coverallsapp/github-action@v2
+      with:
+        file: .tox/test-reports/coverage.xml
+        flag-name: python-${{ matrix.python-version }}
+        parallel: true
+
+  coveralls-finish:
+    name: Finish Coveralls
+    needs: [test]
+    runs-on: ubuntu-latest
+    steps:
+    - name: Finish parallel build
+      uses: coverallsapp/github-action@v2
+      with:
+        parallel-finished: true
+
+  linters:
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v6
+    - uses: actions/setup-python@v6
+      with:
+        python-version: "3.14"
+
+    - uses: astral-sh/setup-uv@v7
+    - run: uvx --with tox-uv tox -e style

portable_python-2.0.1/.gitignore

@@ -0,0 +1,28 @@
+# Various
+*~
+\#*#
+.\#*
+.*cache
+.DS_Store*
+*.swp
+.*version
+.idea/
+.vscode/
+ehthumbs.db
+Icon?
+Thumbs.db
+.new*
+
+# Build artifacts
+_Dockerfile*
+__pycache__/
+*.egg*
+.tox/
+.venv*/
+build/
+dist/
+root/
+venv*/
+
+pp*.yml
+uv.lock

portable_python-2.0.1/CLAUDE.md

@@ -0,0 +1,25 @@
+# CLAUDE.md
+
+Guidance for Claude Code working in this repository.
+
+`portable-python` is a CLI and Python library that compiles portable (statically-linked, relocatable) CPython binaries from source — see [`docs/overview.md`](docs/overview.md) for the full picture.
+
+## Documentation lives in `docs/`
+
+The authoritative, self-contained documentation is the OKF knowledge bundle under **`docs/`** — start at [`docs/index.md`](docs/index.md). **Don't duplicate it in this file — link to it.** When you change behavior, update the matching `docs/` entry and add a line to [`docs/log.md`](docs/log.md).
+
+| Looking for… | Go to |
+|--------------|-------|
+| What it does, guiding principles, end-to-end build flow | [`docs/overview.md`](docs/overview.md) |
+| Core classes & how they collaborate | [`docs/architecture/`](docs/architecture/index.md) |
+| Concepts: portability, static linking, telltale detection, folder masking, ppp-marker, build layout | [`docs/concepts/`](docs/concepts/index.md) |
+| CLI commands & options | [`docs/cli/`](docs/cli/index.md) |
+| External modules (the statically-linked C libraries) | [`docs/modules/`](docs/modules/index.md) |
+| Configuration (`portable-python.yml`) | [`docs/configuration/`](docs/configuration/index.md) |
+| Dev setup, tests, code style, debugging, Docker, CI/CD, and common tasks | [`docs/guides/`](docs/guides/index.md) |
+
+## Working in this repo
+
+- Check **runez** before reimplementing file / system / CLI / logging / version helpers — see [`docs/guides/local-development.md`](docs/guides/local-development.md).
+- The docs use the OKF format; keep the bundle conformant (`scripts/check_okf.py docs`) when you edit it.
+- As changes land, keep a top section in [`docs/changelog.md`](docs/changelog.md) for the upcoming release — `## Unreleased`, or the next version directly once it's known. Maintain it as PRs come in; it's double-checked at release. Don't fuss over marking released-vs-unreleased (small audience, `git tag` says what's out).

portable_python-2.0.1/Dockerfile

@@ -0,0 +1,18 @@
+FROM ubuntu:22.04
+
+ARG DEBIAN_FRONTEND=noninteractive
+ENV TZ=Etc/UTC
+
+RUN apt-get update && apt-get install -y git htop build-essential \
+    gdb lcov patchelf python3-pip python3-venv tcl \
+    libexpat1-dev libffi-dev zlib1g-dev libgdbm-dev libgdbm-compat-dev \
+    libssl-dev libsqlite3-dev uuid-dev \
+    liblzma-dev libbz2-dev libzstd-dev libmpdec-dev
+
+RUN /usr/bin/python3 -mpip install -U pip setuptools
+
+COPY ./scripts/portable-python.sh /usr/local/bin/portable-python
+COPY ./scripts/bashrc.sh /root/.bashrc
+WORKDIR /src
+
+CMD ["/bin/bash"]

portable_python-2.0.1/MANIFEST.in

@@ -0,0 +1,2 @@
+include LICENSE
+include README.rst

{portable_python-2.0.0/src/portable_python.egg-info → portable_python-2.0.1}/PKG-INFO

@@ -1,13 +1,9 @@
 Metadata-Version: 2.4
 Name: portable-python
-Version: 2.0.0
+Version: 2.0.1
 Summary: Portable python binaries
-Home-page: https://github.com/codrsquad/portable-python
-Author: Zoran Simic
-Author-email: zoran@simicweb.com
-License: MIT
-Project-URL: Documentation, https://github.com/codrsquad/portable-python/wiki
-Project-URL: Release notes, https://github.com/codrsquad/portable-python/wiki/Release-notes
+Author-email: Zoran Simic <zoran@simicweb.com>
+License-Expression: MIT
 Project-URL: Source, https://github.com/codrsquad/portable-python
 Keywords: python,portable,binary
 Classifier: Development Status :: 5 - Production/Stable
@@ -31,24 +27,12 @@ Classifier: Topic :: Utilities
 Requires-Python: >=3.10
 Description-Content-Type: text/x-rst
 License-File: LICENSE
-Requires-Dist: click~=8.0
-Requires-Dist: pyyaml~=6.0
-Requires-Dist: requests<3.0
-Requires-Dist: runez~=5.5
-Requires-Dist: urllib3~=1.26
-Dynamic: author
-Dynamic: author-email
-Dynamic: classifier
-Dynamic: description
-Dynamic: description-content-type
-Dynamic: home-page
-Dynamic: keywords
-Dynamic: license
+Requires-Dist: click<9
+Requires-Dist: pyyaml<7
+Requires-Dist: requests<3
+Requires-Dist: runez<6
+Requires-Dist: urllib3<3
 Dynamic: license-file
-Dynamic: project-url
-Dynamic: requires-dist
-Dynamic: requires-python
-Dynamic: summary
 
 Portable python binaries
 ========================
@@ -61,8 +45,8 @@ Portable python binaries
     :target: https://github.com/codrsquad/portable-python/actions
     :alt: Tested with Github Actions
 
-.. image:: https://codecov.io/gh/codrsquad/portable-python/branch/main/graph/badge.svg
-    :target: https://codecov.io/gh/codrsquad/portable-python
+.. image:: https://coveralls.io/repos/github/codrsquad/portable-python/badge.svg?branch=main
+    :target: https://coveralls.io/github/codrsquad/portable-python?branch=main
     :alt: Test coverage
 
 .. image:: https://img.shields.io/pypi/pyversions/portable-python.svg
@@ -180,6 +164,64 @@ Note that you can use ``--dryrun`` mode to inspect what would be done without do
     Would tar build/3.9.7 -> dist/cpython-3.9.7-macos-x86_64.tar.gz
 
 
+CLI reference
+-------------
+
+Main entry point::
+
+    portable-python [OPTIONS] COMMAND [ARGS]
+
+**Global options**:
+
+- ``--config PATH``: Config file (default: ``portable-python.yml``)
+- ``--quiet``: Turn off DEBUG logging
+- ``--dryrun`` / ``-n``: Show what would be done
+- ``--target PLATFORM``: Override detected platform (for testing)
+
+
+**build** ``<PYTHON_SPEC>`` - Build a portable Python binary::
+
+    portable-python build 3.13.2 -m openssl,zlib
+
+- ``--modules, -m CSV``: External modules to include
+- ``--prefix, -p PATH``: Use ``--prefix`` (non-portable)
+
+
+**build-report** ``[PYTHON_SPEC]`` - Show module status and what will be compiled:
+
+- ``--modules, -m CSV``: Specific modules to check
+- Validates that modules can be built
+
+
+**inspect** ``<PATH>`` - Check if a Python installation is portable::
+
+    portable-python inspect /usr/bin/python3
+
+- ``--modules, -m MODULES``: Which modules to inspect
+- ``--verbose, -v``: Show full ``.so`` report
+- ``--prefix, -p``: Built with ``--prefix`` (not portable)
+- ``--skip-so, -s``: Don't check all ``.so`` files
+
+
+**list** ``[FAMILY]`` - List available versions (default: cpython)::
+
+    portable-python list cpython
+
+- ``--json``: Output as JSON
+
+
+**diagnostics** - Show system diagnostics
+
+
+**recompress** ``<PATH> <EXT>`` - Re-compress existing binary tarball (for comparing compression sizes)
+
+
+**lib-auto-correct** ``<PATH>`` - Auto-correct exes/libs to use relative paths:
+
+- ``--commit``: Actually perform changes (dryrun by default)
+- ``--prefix, -p PATH``: Expected ``--prefix`` from build
+
+
 Library
 -------
 

{portable_python-2.0.0 → portable_python-2.0.1}/README.rst

@@ -9,8 +9,8 @@ Portable python binaries
     :target: https://github.com/codrsquad/portable-python/actions
     :alt: Tested with Github Actions
 
-.. image:: https://codecov.io/gh/codrsquad/portable-python/branch/main/graph/badge.svg
-    :target: https://codecov.io/gh/codrsquad/portable-python
+.. image:: https://coveralls.io/repos/github/codrsquad/portable-python/badge.svg?branch=main
+    :target: https://coveralls.io/github/codrsquad/portable-python?branch=main
     :alt: Test coverage
 
 .. image:: https://img.shields.io/pypi/pyversions/portable-python.svg
@@ -128,6 +128,64 @@ Note that you can use ``--dryrun`` mode to inspect what would be done without do
     Would tar build/3.9.7 -> dist/cpython-3.9.7-macos-x86_64.tar.gz
 
 
+CLI reference
+-------------
+
+Main entry point::
+
+    portable-python [OPTIONS] COMMAND [ARGS]
+
+**Global options**:
+
+- ``--config PATH``: Config file (default: ``portable-python.yml``)
+- ``--quiet``: Turn off DEBUG logging
+- ``--dryrun`` / ``-n``: Show what would be done
+- ``--target PLATFORM``: Override detected platform (for testing)
+
+
+**build** ``<PYTHON_SPEC>`` - Build a portable Python binary::
+
+    portable-python build 3.13.2 -m openssl,zlib
+
+- ``--modules, -m CSV``: External modules to include
+- ``--prefix, -p PATH``: Use ``--prefix`` (non-portable)
+
+
+**build-report** ``[PYTHON_SPEC]`` - Show module status and what will be compiled:
+
+- ``--modules, -m CSV``: Specific modules to check
+- Validates that modules can be built
+
+
+**inspect** ``<PATH>`` - Check if a Python installation is portable::
+
+    portable-python inspect /usr/bin/python3
+
+- ``--modules, -m MODULES``: Which modules to inspect
+- ``--verbose, -v``: Show full ``.so`` report
+- ``--prefix, -p``: Built with ``--prefix`` (not portable)
+- ``--skip-so, -s``: Don't check all ``.so`` files
+
+
+**list** ``[FAMILY]`` - List available versions (default: cpython)::
+
+    portable-python list cpython
+
+- ``--json``: Output as JSON
+
+
+**diagnostics** - Show system diagnostics
+
+
+**recompress** ``<PATH> <EXT>`` - Re-compress existing binary tarball (for comparing compression sizes)
+
+
+**lib-auto-correct** ``<PATH>`` - Auto-correct exes/libs to use relative paths:
+
+- ``--commit``: Actually perform changes (dryrun by default)
+- ``--prefix, -p PATH``: Expected ``--prefix`` from build
+
+
 Library
 -------
 

portable_python-2.0.1/docs/architecture/build-setup.md

@@ -0,0 +1,29 @@
+---
+type: Class
+title: BuildSetup
+description: Orchestrates a build end to end — resolves the spec, builds external modules then CPython, validates, and compresses the result.
+tags: [class, build, coordinator]
+timestamp: 2026-06-23T00:00:00Z
+---
+
+# BuildSetup
+
+The build orchestrator (`__init__.py`). The [`build`](/cli/build.md) command — and library users — construct one from a python spec and call `compile()`:
+
+```python
+from portable_python import BuildSetup
+
+BuildSetup("cpython:3.13.2").compile()
+```
+
+## Mental model
+
+A conductor: it compiles nothing itself, it sequences the pieces. `compile()` is the spine — it cleans the [build folders](/concepts/build-layout.md), enters a [`BuildContext`](/concepts/folder-masking.md) (macOS isolation), builds the [external modules](/modules/index.md) into `build/deps/`, then builds CPython through its [`PythonBuilder`](/architecture/python-builder.md) (a [`Cpython`](/architecture/cpython.md)), and finally compresses the install into `dist/`. **External libraries first, CPython last.**
+
+It owns the [`Folders`](/architecture/config.md) (resolved paths) and the python builder; shared config, target platform, and version family come from [`PPG`](/architecture/ppg.md).
+
+## Worth knowing
+
+- **Start reading at `compile()`** — it calls everything else in order.
+- A `--prefix` makes the build **non-portable**; without it the result is relocatable (see [ppp-marker](/concepts/ppp-marker.md) and [portability](/concepts/portability.md)).
+- It requires a full `X.Y.Z` spec — a bare `3.13` is rejected; `"latest"` (or empty) resolves to the newest known version.

portable_python-2.0.1/docs/architecture/config.md

@@ -0,0 +1,30 @@
+---
+type: Class
+title: Config & Folders
+description: Config loads and merges YAML configuration with platform-specific overrides; Folders resolves the templated build/dist/sources paths.
+tags: [class, configuration, folders, yaml]
+timestamp: 2026-06-23T00:00:00Z
+---
+
+# Config & Folders
+
+`Config` (`config.py`) loads, merges, and queries the YAML [configuration](/configuration/portable-python-yml.md). `Folders` (`versions.py`) turns its templated path settings into concrete filesystem paths. Both are reached through [`PPG`](/architecture/ppg.md).
+
+## Merge & precedence
+
+The mental model is layering. A built-in `DEFAULT_CONFIG` provides sane defaults; user files (default `portable-python.yml`, plus any `include:`d files) layer on top. Within a file, **platform-specific** sections override generic ones, and the most specific match for the [target platform](/architecture/ppg.md) wins:
+
+```yaml
+ext: gz            # generic default
+windows:
+  ext: zip         # used only when targeting windows
+macos:
+  env:
+    MACOSX_DEPLOYMENT_TARGET: 13
+```
+
+A lookup returns that most-specific value (with the option to ignore platform overrides).
+
+## Folders
+
+`Folders` resolves the templated `folders:` settings (placeholders like `{build}`, `{version}`, `{abi_suffix}`) into the concrete `build/`, `deps/`, `dist/`, … paths every component uses — including the [ppp-marker](/concepts/ppp-marker.md) install prefix. See [build layout](/concepts/build-layout.md) for the resulting tree.

portable_python-2.0.1/docs/architecture/cpython.md

@@ -0,0 +1,24 @@
+---
+type: Class
+title: Cpython
+description: The concrete PythonBuilder that compiles CPython — configure/make/install, optimization flags, and the finalize step that makes the install relocatable.
+tags: [class, cpython, build, finalize]
+timestamp: 2026-06-23T00:00:00Z
+---
+
+# Cpython
+
+The concrete [`PythonBuilder`](/architecture/python-builder.md) that compiles CPython (`cpython.py`); `CPythonFamily.get_builder()` returns it (see [`PPG`](/architecture/ppg.md)). Most of its work is two things: configuring the build, and finalizing the install so it's relocatable.
+
+## Configure
+
+CPython is configured purely through flags — never source patches (the [no-patches principle](/overview.md)). Defaults come from `cpython-configure` in [config](/configuration/portable-python-yml.md) (optimizations, LTO, ensurepip), plus computed flags that point the build at the statically-compiled [deps](/concepts/static-linking.md).
+
+## Finalize — making it relocatable
+
+After `make install`, a portable build's interpreter still thinks it lives at the placeholder [`/ppp-marker/{version}`](/concepts/ppp-marker.md). Finalizing turns it into a [portable](/concepts/portability.md) install:
+
+- **Trim** — remove tests / idle / 2to3 before byte-compiling, then prune seldom-used pycaches after (driven by the `cpython-clean-*` config).
+- **Byte-compile** the standard library.
+- **Relativize** — rewrite `bin/` shebangs and the absolute paths baked into `sysconfig` so everything resolves relative to the install's own location.
+- **Verify** — sanity-check that `venv` works in the finished build.

portable_python-2.0.1/docs/architecture/index.md

@@ -0,0 +1,30 @@
+# Architecture
+
+The core classes and how they collaborate during a build.
+## Global state & configuration
+
+* [PPG](/architecture/ppg.md) - Global singleton holding config, target platform, and version families.
+* [Config](/architecture/config.md) - Loads and merges YAML configuration; the `Folders` helper resolves build paths.
+
+## Build coordination
+
+* [BuildSetup](/architecture/build-setup.md) - Drives the overall compilation: resolve spec, select modules, build, validate, compress.
+* [ModuleBuilder](/architecture/module-builder.md) - Abstract base for anything that gets compiled (external C libs and Python itself).
+* [PythonBuilder](/architecture/python-builder.md) - `ModuleBuilder` specialization for python implementations.
+* [Cpython](/architecture/cpython.md) - Concrete builder: CPython's configure/make/install, optimization, and finalization.
+
+## Validation
+
+* [PythonInspector](/architecture/python-inspector.md) - Validates the portability of a built (or any) python by checking shared-library dependencies and paths.
+
+## Collaboration at a glance
+
+```
+PPG (config, target, families)
+  └─ BuildSetup(python_spec)
+       ├─ Folders            (resolved build/dist/... paths)
+       ├─ BuildContext       (macOS folder masking, isolation)
+       └─ python_builder : Cpython (a PythonBuilder, a ModuleBuilder)
+            └─ modules : ModuleCollection
+                 └─ candidates/selected : ModuleBuilder (Openssl, Zlib, ...)
+```

portable_python-2.0.1/docs/architecture/module-builder.md

@@ -0,0 +1,26 @@
+---
+type: Class
+title: ModuleBuilder
+description: Abstract base for everything that gets compiled — external C libraries and CPython itself — providing the common download/configure/make/install flow and environment injection.
+tags: [class, abstract, build, module]
+timestamp: 2026-06-23T00:00:00Z
+---
+
+# ModuleBuilder
+
+The abstract base for everything the tool compiles (`__init__.py`). Both the [external C modules](/modules/index.md) and [`PythonBuilder`](/architecture/python-builder.md) (hence [`Cpython`](/architecture/cpython.md)) extend it, so every component is built the same way and lands in the same [build layout](/concepts/build-layout.md).
+
+## Mental model
+
+A subclass is mostly **declarative**: it sets a few `m_*` class attributes (name, [telltale](/concepts/telltale-detection.md) marker, Debian package, include subfolder) and provides a source `url` + `version`. The base class runs the rest of the flow — download → unpack → patch → configure → make → install — into the shared `build/deps/` prefix. Platform differences are isolated to `_do_linux_compile()` / `_do_macos_compile()`, dispatched on [`PPG.target`](/architecture/ppg.md).
+
+Two mechanisms recur everywhere and are worth understanding:
+
+- **Environment injection** (`xenv_*` methods) — each contributes one variable (CPATH, LDFLAGS, PATH, …) pointing the compiler at `build/deps/`. This is how a statically-built dependency gets found by the next build; see [static linking](/concepts/static-linking.md).
+- **Per-module config overrides** — `cfg_*` helpers read `{module}-version`, `{module}-url`, `{module}-configure`, … from [configuration](/configuration/portable-python-yml.md), so any default can be overridden without code changes.
+
+`linker_outcome()` decides, per module and platform, whether it will be linked `static` / `shared`, is `absent`, or would `fail` — the verdict surfaced by [`build-report`](/cli/build-report.md).
+
+## Adding one
+
+Subclass `ModuleBuilder`, set the `m_*` attributes, implement `url` / `version` and `_do_linux_compile()` — see the [guide](/guides/add-an-external-module.md).

portable_python-2.0.1/docs/architecture/ppg.md

@@ -0,0 +1,21 @@
+---
+type: Class
+title: PPG
+description: Global singleton holding shared configuration, the target platform, and the registry of supported python version families.
+tags: [class, global-state, singleton, versions]
+timestamp: 2026-06-23T00:00:00Z
+---
+
+# PPG
+
+`PPG` ("**P**ortable **P**ython **G**lobals") is the global state holder (`versions.py`) — the one place the rest of the code reaches for three process-wide facts: the merged [configuration](/architecture/config.md), the target platform (OS/arch), and the registry of python version families. The CLI's `main` initializes it once; everything else reads from it.
+
+Like [`ppp-marker`](/concepts/ppp-marker.md), the name is a deliberately uncommon, greppable token — searching for `PPG` surfaces only its own usages, with no collisions in upstream CPython or third-party source.
+
+## Why a singleton
+
+The build depends on global facts — which config is active, what platform we target, which python versions exist — so centralizing them avoids threading that state through every constructor and gives the CLI one initialization point. Shared helpers hang off it too: resolving a python on `PATH`, building [`Folders`](/architecture/config.md) for a version, and expanding [telltale](/concepts/telltale-detection.md) markers against the target's system includes.
+
+## Version families
+
+A `VersionFamily` (e.g. `CPythonFamily`) lists the available versions and hands back the right builder ([`Cpython`](/architecture/cpython.md) for cpython). Versions are fetched lazily and cached — from `python.org/ftp`, or GitHub tags when configured — which is why [`list`](/cli/list.md) hits the network on first use. A family also pins the minimum supported version (non-EOL only).

portable_python-2.0.1/docs/architecture/python-builder.md

@@ -0,0 +1,25 @@
+---
+type: Class
+title: PythonBuilder
+description: A ModuleBuilder specialization for python implementations — adds module selection, the python install layout, and helpers to run the freshly built interpreter.
+tags: [class, abstract, python, build]
+timestamp: 2026-06-23T00:00:00Z
+---
+
+# PythonBuilder
+
+The abstract [`ModuleBuilder`](/architecture/module-builder.md) specialization for building a python interpreter (`__init__.py`); the concrete implementation is [`Cpython`](/architecture/cpython.md).
+
+## What it adds over ModuleBuilder
+
+Beyond the base compile flow, a `PythonBuilder` owns the **module selection** (which [external modules](/modules/index.md) to build) and can **run the freshly-built interpreter** — used during finalize and validation.
+
+## ModuleCollection
+
+A `PythonBuilder` owns a `ModuleCollection` that resolves which external modules actually get built — a distinction worth keeping straight:
+
+- **candidates** — every module this builder *could* compile.
+- **selected** — the ones chosen for *this* build (config + `--modules` + auto-selection). This is what's actually compiled, not all candidates.
+- **auto-selected** — modules force-included because the build can't succeed without them (each module's `auto_select_reason()`).
+
+It's what [`build-report`](/cli/build-report.md) renders.

portable_python-2.0.1/docs/architecture/python-inspector.md

@@ -0,0 +1,27 @@
+---
+type: Class
+title: PythonInspector
+description: Validates the portability of a python installation by parsing the dynamic-library dependencies of every executable and .so, and reporting any non-portable references.
+tags: [class, inspection, validation, portability]
+timestamp: 2026-06-23T00:00:00Z
+---
+
+# PythonInspector
+
+`PythonInspector` (`inspector.py`) answers the question the whole project exists for: *is this python [portable](/concepts/portability.md), and if not, why not?* It powers the [`inspect`](/cli/inspect.md) command and the portability gate at the end of [`BuildSetup.compile()`](/architecture/build-setup.md).
+
+## How it works
+
+It walks every executable and `.so` in an installation, lists each one's dynamic-library dependencies (parsing `ldd` on Linux / `otool` on macOS), and classifies every reference:
+
+- **system / standard** library → fine;
+- **relative / self** reference → fine (what a relocatable build should have);
+- **absolute, non-system** reference → a portability problem.
+
+For a portable build, any problem fails the inspection (the report exposes a single "first problem" verdict that callers check).
+
+## Relativization
+
+The fix lives in `LibAutoCorrect`, which rewrites the absolute library paths (rpaths) baked into binaries so they resolve relative to the install — `patchelf` on Linux (an `$ORIGIN`-relative rpath), `install_name_tool` on macOS (`@rpath` / `@loader_path`). It runs **during** finalize (so the result passes the portable check) and is exposed standalone as [`lib-auto-correct`](/cli/lib-auto-correct.md).
+
+The same step also supports **non-portable** builds: with `--prefix` or `--enable-shared`, it additionally keeps the real prefix's `lib/` in the rpath, so a build pinned to a fixed location still finds its libraries. (CPython is built with a deliberately long rpath — unlike `chrpath`, `patchelf` can set a fresh rpath of any length, leaving room to rewrite it.)

portable_python-2.0.1/docs/changelog.md

@@ -0,0 +1,13 @@
+---
+type: Changelog
+title: Changelog
+description: High-level release highlights for portable-python, newest first.
+tags: [changelog, releases]
+timestamp: 2026-06-23T00:00:00Z
+---
+
+## v2.0.1
+
+- Bumped the bundled components (OpenSSL, SQLite, Tcl/Tk, …) to current versions.
+- Refreshed dependencies and modernized CI (now on uv / tox-uv, with updated GitHub Actions).
+- Added an OKF documentation bundle under `docs/` (the old top-level docs folded into it).

portable_python-2.0.1/docs/cli/build-report.md

@@ -0,0 +1,24 @@
+---
+type: CLI Command
+title: build-report
+description: Show the status of buildable modules — which will be auto-compiled, which are present on the system, and which would fail — without building anything.
+tags: [cli, build, report, command]
+timestamp: 2026-06-23T00:00:00Z
+---
+
+# build-report
+
+Show which [modules](/modules/index.md) would be compiled for a spec, and whether the selection can actually build on this host — **without** building. The fastest way to catch a "broken" module before committing to a full compile.
+
+```
+portable-python build-report [OPTIONS] [PYTHON_SPEC]
+```
+
+For each candidate module it shows the [telltale](/concepts/telltale-detection.md) status and the linker outcome — `static` (will be compiled), `shared` (system copy used), `absent`, or `failed` (can't build here, e.g. a `-`-sigil Debian dev package is present). `PYTHON_SPEC` defaults to the latest known version.
+
+# Examples
+
+```shell
+portable-python build-report 3.13.2
+portable-python build-report 3.13.2 -m openssl,sqlite
+```