docs: update docs on distributions

Author: indygreg

docs/distributions.rst

@@ -4,11 +4,17 @@
 Distribution Archives
 =====================
 
-The output of a build is referred to as a Python *distribution*.
+This project produces tarball archives containing Python distributions.
 
-A distribution is a zstandard-compressed tar file. All paths inside the
-tar archive are prefixed with ``python/``. Within the ``python/`` directory
-are the following well-known paths:
+Full Archive
+============
+
+The canonical output of this project's build system are ``.tar.zst``
+(zstandard compressed tarballs) files.
+
+All files within the tar are prefixed with ``python/``.
+
+Within the ``python/`` directory are the following well-known paths:
 
 PYTHON.json
    Machine readable file describing this Python distribution.
@@ -22,7 +28,7 @@ The ``PYTHON.json`` file should be read to determine where specific entities
 are located within the archive.
 
 PYTHON.json File
-================
+----------------
 
 The ``PYTHON.json`` file describes the Python distribution in a machine
 readable manner. This file is meant to be opened by downstream consumers
@@ -572,3 +578,23 @@ system
 
    System libraries are typically passed into the linker by name only and
    found using default library search paths.
+
+Install Only Archive
+====================
+
+At release time, this project produces tar files containing just the
+Python installation, without the ``PYTHON.json`` or build files from
+the full ``.tar.zst`` archives. These are referred to as *install only*
+archives.
+
+An *install only* archive is created by taking a ``.tar.zst`` and
+rewriting ``python/install/*`` to ``python/*``. All files not under
+``python/install/*`` are not carried forward to the *install only*
+archive.
+
+The fastest available build for a given target is used for the *install
+only* archive. Builds are generally preferred in the following order:
+``pgo+lto``, ``pgo``, ``lto``, ``noopt``.
+
+For maximum compatibility, gzipped compressed versions of the
+*install only* archives are made available.

docs/index.rst

@@ -3,34 +3,36 @@ Python Standalone Builds
 
 This project produces self-contained, highly-portable Python
 distributions. These Python distributions contain a fully-usable,
-full-featured Python installation as well as their build artifacts
-(object files, libraries, etc).
-
-The included build artifacts can be recombined by downstream
-repackagers to derive a custom Python distribution, possibly without
-certain features like SQLite and OpenSSL. This is useful for
-embedding Python in a larger binary, where a full Python is
-often not needed and where interfacing with the Python C API
-is desirable. (See the
-`PyOxidizer <https://github.com/indygreg/PyOxidizer>`_ sister project
-for such a downstream repackager.)
+full-featured Python installation: most extension modules from
+the Python standard library are present and their library
+dependencies are either distributed with the distribution or
+are statically linked.
 
 The Python distributions are built in a manner to minimize
 run-time dependencies. This includes limiting the CPU instructions
 that can be used and limiting the set of shared libraries required
 at run-time. The goal is for the produced distribution to work on
 any system for the targeted architecture.
 
+Some distributions ship with their build artifacts (object files,
+libraries, etc) along with rich metadata describing the distribution
+and how it was assembled. The build artifacts can be recombined by
+downstream repackagers to derive a custom Python distribution, possibly
+without certain features like SQLite and OpenSSL. This is useful for
+embedding Python in a larger binary. See the
+`PyOxidizer <https://github.com/indygreg/PyOxidizer>`_ sister project
+for such a downstream repackager.
+
 .. toctree::
    :maxdepth: 2
    :caption: Contents:
 
-   building.rst
-   running.rst
-   quirks.rst
-   technotes.rst
-   distributions.rst
-   status.rst
+   running
+   building
+   quirks
+   technotes
+   distributions
+   status
 
 Indices and tables
 ==================

docs/running.rst

@@ -4,10 +4,55 @@
 Running Distributions
 =====================
 
+Obtaining Distributions
+=======================
+
+Pre-built distributions are published as releases on GitHub at
+https://github.com/indygreg/python-build-standalone/releases.
+Simply go to that page and find the latest release along with
+its release notes.
+
+Published distributions vary by their:
+
+* Python version
+* Target machine architecture
+* Build configuration
+* Archive flavor
+
+The Python version is hopefully pretty obvious.
+
+The target machine architecture defines the CPU type and operating
+system the distribution runs on. We use LLVM target triples.
+
+The build configuration denotes how Python and its dependencies were built.
+Common configurations include:
+
+``pgo+lto``
+   Profile guided optimization and link-time optimization. These should be
+   the fastest distributions since they have the most build-time
+   optimizations.
+
+``pgo``
+   Profile guided optimization.
+
+``lto``
+   Link-time optimization.
+
+``noopt``
+   A regular optimized build without PGO or LTO.
+
+``debug``
+   A debug build. No optimizations.
+
+The archive flavor denotes the content in the archive. See
+:ref:`distributions` for more. Casual users will likely want to use the
+``install_only`` archive, as most users do not need the build artifacts
+present in the ``full`` archive.
+
 Extracting Distributions
 ========================
 
-Distributions are defined as zstandard-compressed tarballs.
+Distributions are defined as zstandard or gzip compressed tarballs.
 
 Modern versions of ``tar`` support zstandard and you can extract
 like any normal archive::