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

mail settings
Submitter phabricator
Date March 12, 2020, 4:19 p.m.
Message ID <68af6d07abc69e76379156c7e501b028@localhost.localdomain>
Download mbox | patch
Permalink /patch/45754/
State Not Applicable
Headers show


phabricator - March 12, 2020, 4:19 p.m.
Closed by commit rHG47f8c741df0f: rust: update the README with more up-to-date and thorough information (authored by Alphare).
This revision was automatically updated to reflect the committed changes.
This revision was not accepted when it landed; it landed in state "Needs Review".

  rHG Mercurial






To: Alphare, #hg-reviewers
Cc: mercurial-devel


diff --git a/rust/README.rst b/rust/README.rst
--- a/rust/README.rst
+++ b/rust/README.rst
@@ -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 ./ # only the .t
-  $ ./hg debuginstall | grep rust # to validate rust is in use
+  $ make PURE=--rust local # to use ./hg
+  $ ./tests/ --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:
+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
+For example::
+  $ cargo check --features with-re2