changeset 44549:47f8c741df0f

rust: update the README with more up-to-date and thorough information

Differential Revision: https://phab.mercurial-scm.org/D8274

--- a/rust/README.rst	Fri Dec 08 02:29:02 2017 +0100
+++ b/rust/README.rst	Thu Mar 12 10:14:40 2020 +0100
@@ -11,28 +11,57 @@
 - 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
+- hg-core (and hg-cpython): implementation of some
   functionality of mercurial in rust, e.g. ancestry computations in
-  revision graphs or pull discovery. The top-level ``Cargo.toml`` file
+  revision graphs, status or pull discovery. The top-level ``Cargo.toml`` file
   defines a workspace containing these crates.
 
-Using hg-core
-=============
+Using Rust code
+===============
 
 Local use (you need to clean previous build artifacts if you have
 built without rust previously)::
 
-  $ 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
+  $ make PURE=--rust local # to use ./hg
+  $ ./tests/run-tests.py --rust # to run all tests
+  $ ./hg debuginstall | grep -i rust # to validate rust is in use
+  checking Rust extensions (installed)
   checking module policy (rust+c-allow)
+  checking "re2" regexp engine Rust bindings (installed)
+
+
+If the environment variable ``HGWITHRUSTEXT=cpython`` is set, the Rust
+extension will be used by default unless ``--no-rust``.
+
+One day we may use this environment variable to switch to new experimental
+binding crates like a hypothetical ``HGWITHRUSTEXT=hpy``.
+
+Using the full ``hg status`` extension
+--------------------------------------
 
-Setting ``HGWITHRUSTEXT`` to other values like ``true`` is deprecated
-and enables only a fraction of the rust code.
+The code for ``hg status`` needs to conform to ``.hgignore`` rules, which are
+all translated into regex. For compatibility and ease of development reasons
+the Re2 regex engine is in use until we figure out if the ``regex`` crate has
+similar enough behavior. This implies that you need to install ``Re2``
+following Google's guidelines: https://github.com/google/re2/wiki/Install
+
+Then, use ``HG_RUST_FEATURES=with-re2`` when building ``hg`` to use the full
+status code.
+
+Developing Rust
+===============
 
-Developing hg-core
-==================
+The current version of Rust in use is ``1.34.2``, because it's what Debian
+stable has. You can use ``rustup override set 1.34.2`` at the root of the repo
+to make it easier on you.
+
+Go to the ``hg-cpython`` folder::
+
+  $ cd rust/hg-cpython
+
+Or, only the ``hg-core`` folder. Be careful not to break compatibility::
+
+  $ cd rust/hg-core
 
 Simply run::
 
@@ -46,7 +75,35 @@
 
   $ cargo check
 
+For even faster typing::
+
+  $ cargo c
+
 You can run only the rust-specific tests (as opposed to tests of
 mercurial as a whole) with::
 
   $ cargo test --all
+
+Formatting the code
+-------------------
+
+We use ``rustfmt`` to keep the code formatted at all times. For now, we are
+using the nightly version because it has been stable enough and provides
+comment folding.
+
+To format the entire Rust workspace::
+
+  $ cargo +nightly fmt
+
+This requires you to have the nightly toolchain installed.
+
+Additional features
+-------------------
+
+As mentioned in the section about ``hg status``, code paths using ``re2`` are
+opt-in.
+
+For example::
+
+  $ cargo check --features with-re2
+