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

login
register
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

Comments

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".

REPOSITORY
  rHG Mercurial

CHANGES SINCE LAST UPDATE
  https://phab.mercurial-scm.org/D8274?vs=20756&id=20758

CHANGES SINCE LAST ACTION
  https://phab.mercurial-scm.org/D8274/new/

REVISION DETAIL
  https://phab.mercurial-scm.org/D8274

AFFECTED FILES
  rust/README.rst

CHANGE DETAILS




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

Patch

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 ./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
+