explain use of cppyy-backend instead of PyPy-cppyy-backend

doc/source/distribution.rst

@@ -1,15 +1,10 @@
 Distribution
 ============
 
-On this page, $CPPYYHOME is expected to point the location of the backend, e.g.
-$PYTHONHOME/site-packages/cppyy_backend if it was installed in the default
-location.
-
 Loading code directly into Cling is fine for interactive work and small
 scripts, but large scale applications should take advantage of pre-packaging
 code, linking in libraries, and describing other dependencies.
-Tools are available as part of the backend, under $CPPYYHOME/bin, which should
-be added to your executable path (PATH).
+The necessary tools are installed as part of the backend.
 
 
 Dictionary generation
@@ -26,7 +21,7 @@ residing in ``libproject.so``, the following will generate a
 ``libProjectDict.so`` reflection dictionary::
 
     $ genreflex project_header.h
-    $ g++ -std=c++11 -fPIC -rdynamic -O2 -shared -I$CPPYYHOME/include project_header_rflx.cpp -o libProjectDict.so -L$PROJECTHOME/lib -lproject
+    $ g++ -std=c++11 -fPIC -rdynamic -O2 -shared `genreflex --cppflags` project_header_rflx.cpp -o libProjectDict.so -L$PROJECTHOME/lib -lproject
 
 Instead of loading the header text into Cling, you can now load the
 dictionary:
@@ -61,7 +56,7 @@ The ``genreflex`` tool can produce rootmap files automatically.
 For example::
 
     $ genreflex project_header.h --rootmap=libProjectDict.rootmap --rootmap-lib=libProjectDict.so
-    $ g++ -std=c++11 -fPIC -rdynamic -O2 -shared -I$CPPYYHOME/include project_header_rflx.cpp -o libProjectDict.so -L$CPPYYHOME/lib -lCling -L$PROJECTHOME/lib -lproject
+    $ g++ -std=c++11 -fPIC -rdynamic -O2 -shared `genreflex --cppflags` project_header_rflx.cpp -o libProjectDict.so -L$CPPYYHOME/lib -lCling -L$PROJECTHOME/lib -lproject
 
 where the first option (``--rootmap``) specifies the output file name, and the
 second option (``--rootmap-lib``) the name of the reflection library.

doc/source/installation.rst

@@ -1,59 +1,38 @@
 Installation
 ============
 
-The installation instructions depend on whether you install for PyPy or
-CPython.
-The former has a builtin cppyy module, and thus only requires the backend.
-The latter needs both cppyy and the backend.
-Compiling the backend takes a long time (it contains a customized version
-of Clang/LLVM), so it is recommended to set the MAKE_NPROCS environment
-variable to the number of cores available on your machine.
-
-
-PyPy
-----
-
-This assumes PyPy2.7 v5.7 or later; earlier versions use a Reflex-based cppyy
-module, which is no longer supported.
-Both the tooling and user-facing Python codes are however very backwards
-compatible.
-Further build dependencies are cmake (for general build), Python2.7 (for LLVM),
-and a modern C++ compiler (one that supports at least C++11).
-
-Install for PyPy, using pip::
-
- $ MAKE_NPROCS=8 pypy-c -m pip install --verbose PyPy-cppyy-backend
-
-Set the number of parallel builds ('8' in this example) to a number appropriate
-for your machine.
-The use of --verbose is recommended so that you can see the build progress.
-
-The default installation of the backend will be under
-$PYTHONHOME/site-packages/cppyy_backend/lib,
-which needs to be added to your dynamic loader path (LD_LIBRARY_PATH).
-If you need the dictionary and class map generation
-:doc:`tools <distribution>`, you need to add
-$PYTHONHOME/site-packages/cppyy_backend/bin to your executable path (PATH).
-
-
-CPython
--------
-
-Both Python2 and Python3 are supported.
-Further build dependencies are cmake (for general build), Python2.7 (for LLVM),
-and a modern C++ compiler (supporting at least C++11).
-
-Install using pip::
-
- $ MAKE_NPROCS=8 pip install --verbose cppyy
-
-Set the number of parallel builds ('8' in this example) to a number appropriate
-for your machine.
-Installing cppyy will pull in PyPy-cppyy-backend, which does not depend on
-Python and can thus be shared between PyPy and CPython by installing it in a
-common location (the platform-specific wheel is shared through pip and will not
-be rebuild).
-
-If you need the dictionary and class map generation
-:doc:`tools <distribution>`, you need to add
-$PYTHONHOME/site-packages/cppyy_backend/bin to your executable path (PATH).
+The ``cppyy`` module and its dependencies are available through `PyPI`_ for
+both CPython (2 and 3) and PyPy (5.9.0 and later).
+Build-time only dependencies are ``cmake`` (for general build), ``python2.7``
+(for LLVM), and a modern C++ compiler (one that supports at least C++11).
+
+Compilation of the backend, which contains a customized version of
+Clang/LLVM, can take a long time, so it is recommended to set the MAKE_NPROCS
+environment variable to the number of cores available on your machine or more.
+To see progress, use ``--verbose``::
+
+ $ MAKE_NPROCS=32 pip install --verbose cppyy
+
+The bdist_wheel of the backend is reused by pip for all versions of CPython
+and PyPy, thus the long compilation is needed only once.
+
+PyPy 5.7 and 5.8 have a built-in module ``cppyy``.
+You can still install the ``cppyy`` package (or, alternatively, just
+``cppyy-backend``), but the built-in takes precedence.
+To use ``cppyy`` without further setting environment variables, simply load
+the backend explicitly, before importing ``cppyy``::
+
+ $ pypy
+ [PyPy 5.8.0 with GCC 5.4.0] on linux2
+ >>>> from cppyy_backend import loader
+ >>>> c = loader.load_cpp_backend()
+ >>>> import cppyy
+ >>>>
+
+Older versions of PyPy (5.6.0 and earlier) have a built-in ``cppyy`` based on
+`Reflex`_, which is less feature-rich and no longer supported.
+However, both the :doc:`distribution tools <distribution>` and user-facing
+Python codes are very backwards compatible.
+
+.. _`PyPI`: https://pypi.python.org/pypi/cppyy/
+.. _`Reflex`: https://root.cern.ch/how/how-use-reflex