document package structure

doc/source/installation.rst

@@ -47,3 +47,42 @@ Python codes are very backwards compatible.
 .. _`PyPI`: https://pypi.python.org/pypi/cppyy/
 .. _`are available`: https://cern.ch/wlav/wheels/
 .. _`Reflex`: https://root.cern.ch/how/how-use-reflex
+
+
+Package structure
+-----------------
+.. _package-structure:
+
+There are four PyPA packages involved in a full installation, with the
+following structure::
+
+               (A) _cppyy (PyPy)
+           /                        \
+ (1) cppyy                            (3) cling-backend -- (4) cppyy-cling
+           \                        /
+             (2) CPyCppyy (CPython)
+
+The user-facing package is always ``cppyy`` (1).
+It is used to select the other (versioned) required packages, based on the
+python interpreter for which it is being installed.
+
+Below (1) follows a bifurcation based on interpreter.
+This is needed for functionality and performance: for CPython, there is the
+CPyCppyy package (2).
+It is written in C++, makes use of the Python C-API, and installs as a Python
+extension module.
+For PyPy, there is the builtin module ``_cppyy`` (A).
+This is not a PyPA package.
+It is written in RPython as it needs access to low-level pointers, JIT hints,
+and the ``_cffi_backend`` backend module (itself builtin).
+
+Shared again across interpreters is the backend, which is split in a small
+wrapper (3) and a large package that contains Cling/LLVM (4).
+The former is still under development and expected to be updated frequently.
+It is small enough to download and build very quickly.
+The latter, however, takes a long time to build, but since it is very stable,
+splitting it if off allows the creation of binary wheels that need updating
+only infrequently (expected about twice a year).
+
+All code is publicly available; see the
+:doc:`section on repositories <repositories>`.

doc/source/repositories.rst

@@ -2,7 +2,8 @@ Repositories
 ============
 
 The ``cppyy`` module is a frontend that requires an intermediate (Python
-interpreter dependent) layer, and a backend.
+interpreter dependent) layer, and a backend (see
+:ref:`Package Structure <package-structure>`).
 Because of this layering and because it leverages several existing packages
 through reuse, the relevant codes are contained across a number of
 repositories.