--- a/rust/README.rst	Mon Jan 20 17:44:03 2020 -0500
+++ b/rust/README.rst	Mon Jan 20 18:28:46 2020 -0500
@@ -3,17 +3,50 @@
 ===================
 
 This directory contains various Rust code for the Mercurial project.
+Rust is not required to use (or build) Mercurial, but using it
+improves performance in some areas.
 
-The top-level ``Cargo.toml`` file defines a workspace containing
-all primary Mercurial crates.
+There are currently three independent rust projects:
+- chg. An implementation of chg, in rust instead of C.
+- hgcli. A experiment for starting hg in rust rather than in python,
+  by linking with the python runtime. Probably meant to be replaced by
+  PyOxidizer at some point.
+- hg-core (and hg-cpython/hg-directffi): implementation of some
+  functionality of mercurial in rust, e.g. ancestry computations in
+  revision graphs or pull discovery. The top-level ``Cargo.toml`` file
+  defines a workspace containing these crates.
+
+Using hg-core
+=============
 
-Building
-========
+Local use (you need to clean previous build artifacts if you have
+built without rust previously)::
 
-To build the Rust components::
+  $ HGWITHRUSTEXT=cpython make local # to use ./hg
+  $ HGWITHRUSTEXT=cpython make tests # to run all tests
+  $ (cd tests; HGWITHRUSTEXT=cpython ./run-tests.py) # only the .t
+  $ ./hg debuginstall | grep rust # to validate rust is in use
+  checking module policy (rust+c-allow)
 
-   $ cargo build
+Setting ``HGWITHRUSTEXT`` to other values like ``true`` is deprecated
+and enables only a fraction of the rust code.
 
-If you prefer a non-debug / release configuration::
+Developing hg-core
+==================
+
+Simply run::
 
    $ cargo build --release
+
+It is possible to build without ``--release``, but it is not
+recommended if performance is of any interest: there can be an order
+of magnitude of degradation when removing ``--release``.
+
+For faster builds, you may want to skip code generation::
+
+  $ cargo check
+
+You can run only the rust-specific tests (as opposed to tests of
+mercurial as a whole) with::
+
+  $ cargo test --all