Skip to content

Document the relenv.runtime bootstrap pipeline (#154) - #350

Open
dwoz wants to merge 1 commit into
mainfrom
docs-runtime-bootstrap
Open

dwoz wants to merge 1 commit into
mainfrom
docs-runtime-bootstrap

Conversation

@dwoz

@dwoz dwoz commented Nov 20, 2026

Copy link
Copy Markdown
Contributor

Closes #154.

The developer docs for relenv.runtime have been a 5-line automodule stub since the module was first added. Issue #154 asks for a narrative page covering what relenv does when the interpreter starts up — this PR delivers it.

Depends on #349

The new doc references wrap_venv (from the gh-161 fix), so this PR should land after #349 merges. Until then the ``:func:`wrap_venv``` references will unresolve.

What's in it

Rewrite docs/source/developer/runtime.rst from the stub to a 292-line reference walking the full startup pipeline. Sections:

  1. Overview — why relocatable onedirs need runtime patching.
  2. Entry point: relenv.pth — the .pth body quoted verbatim from relenv/build/common/install.py:44, and the rationale for the SourceFileLoader dance over a bare import relenv.runtime (from the comment block at relenv/runtime.py:64).
  3. bootstrap() call chain — nine numbered steps walking the body, each citing file:line. Covers warnings.filterwarnings, sys.RELENV = relenv_root(), setup_openssl, the site.execsitecustomize wrap, setup_crossroot, install_cargo_config, wrap_venv, the sys.meta_path insert, and the 3.13+-only wrap_sysconfig('sysconfig') call.
  4. The RelenvImporter meta-path hook — class description, full table of the 10 registered wrappers (module name → wrapper function), a worked example using wrap_sysconfig + get_config_var_wrapper showing how RELENV_PIP_DIR toggles BINDIR, and a note on the __wrapped__ idempotence guard that survives importlib.reload(site).
  5. Environment variables — field-list style covering RELENV_DEBUG, RELENV_BUILDENV, RELENV_PIP_DIR, RELENV_CROSS, HOST_PYTHON, SSL_CERT_DIR/SSL_CERT_FILE, OPENSSL_MODULES, CARGO_HOME, OPENSSL_DIR, RUSTFLAGS.
  6. venv children (Relenv breaks virtualenvs (At least in FIPS enabled systems) #161) — explains wrap_venv, the absolute-path requirement, and the stdlib-only scope limit.
  7. API reference — original automodule block retained so function docstrings still render.

Test plan

  • cd docs && make html — builds cleanly; no new warnings (the 6 pre-existing warnings are all docutils gripes in relenv/common.py docstrings).
  • Human spot-check that the rendered HTML reads well.

The developer docs for ``relenv.runtime`` have been a five-line
``automodule`` stub since the module was first added.  Issue #154
specifically asks for a narrative page covering what relenv does when
the interpreter starts up.

Rewrite ``docs/source/developer/runtime.rst`` into a 292-line reference
walking the full startup pipeline:

* the ``relenv.pth`` entry point that lands in the base interpreter's
  ``site-packages/`` -- the ``.pth`` body quoted verbatim and the reason
  the ``SourceFileLoader`` dance is used instead of a bare
  ``import relenv.runtime``;
* every step inside ``bootstrap()``, in order, with a one-paragraph
  rationale for each (``warnings.filterwarnings``,
  ``sys.RELENV = relenv_root()``, ``setup_openssl``, the
  ``site.execsitecustomize`` wrap, ``setup_crossroot``,
  ``install_cargo_config``, ``wrap_venv``, the ``sys.meta_path`` insert,
  and the 3.13+-only ``wrap_sysconfig('sysconfig')`` call);
* the ``RelenvImporter`` meta-path hook: full table of the ten registered
  wrappers, a worked example using ``wrap_sysconfig`` +
  ``get_config_var_wrapper`` to show how ``RELENV_PIP_DIR`` toggles the
  ``BINDIR`` value, and a note on the idempotence pattern that survives
  ``importlib.reload(site)``;
* a field list of every environment variable the runtime consults --
  ``RELENV_DEBUG``, ``RELENV_BUILDENV``, ``RELENV_PIP_DIR``,
  ``RELENV_CROSS``, ``HOST_PYTHON``, ``SSL_CERT_DIR``/``SSL_CERT_FILE``,
  ``OPENSSL_MODULES``, ``CARGO_HOME``, ``OPENSSL_DIR``, ``RUSTFLAGS``;
* a dedicated section on child venvs (gh-161): how ``wrap_venv``
  monkey-patches ``venv.EnvBuilder.post_setup`` to drop a ``relenv.pth``
  into stdlib-created children so ``bootstrap()`` runs there too, with
  the stated scope limit (stdlib ``venv`` only).

The original ``automodule`` block is preserved at the end of the file so
individual function docstrings still render.

Depends on PR #349 landing first for the ``wrap_venv`` references to
resolve.  Verified with ``sphinx-build`` -- no warnings from the new
file (the six pre-existing warnings in ``relenv/common.py`` docstrings
are unchanged).

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Better documentation of runtime bootstrap

1 participant