Patchwork D11808: docs: add documentation about Rust

mail settings
Submitter phabricator
Date Nov. 26, 2021, 1:31 p.m.
Message ID <>
Download mbox | patch
Permalink /patch/50134/
State New
Headers show


phabricator - Nov. 26, 2021, 1:31 p.m.
Alphare created this revision.
Alphare added a comment.
Herald added a reviewer: hg-reviewers.
Herald added a subscriber: mercurial-patches.

  Pending CI refresh

  This makes the features more discoverable for users.

  rHG Mercurial





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


diff --git a/mercurial/helptext/rust.txt b/mercurial/helptext/rust.txt
new file mode 100644
--- /dev/null
+++ b/mercurial/helptext/rust.txt
@@ -0,0 +1,94 @@ 
+Mercurial can be augmented with Rust extensions for speeding up certain
+Though the Rust extensions are only tested by the project under Linux, users of
+MacOS, FreeBSD, other UNIX-likes have been using the Rust extensions. Your
+mileage may vary, but by all means do give us feedback or signal your interest
+for better support.
+No Rust extensions are available for Windows at this time.
+The following operations are sped up when using Rust:
+    - discovery of differences between repositories (pull/push)
+    - nodemap (see :hg:`help config.format.use-persistent-nodemap`)
+    - all commands using the dirstate (status, commit, diff, add, update, etc.)
+    - dirstate-v2 (see :hg:`help config.format.exp-rc-dirstate-v2`)
+    - iteration over ancestors in a graph
+More features are in the works, and improvements on the above listed are still
+in progress. For more experimental work see the "rhg" section.
+Checking for Rust
+You may already have the Rust extensions depending on how you get Mercurial.
+  $ hg debuginstall | grep -i rust
+  checking Rust extensions (installed)
+  checking module policy (rust+c-allow)
+If those lines don't even exist, you're using an old version of `hg` which does
+not have any Rust extensions yet. 
+You will need `cargo` to be in your `$PATH`. See the "MSRV" section for which
+version to use.
+Using pip
+Users of `pip` can install the Rust extensions with the following command:
+  $ pip install mercurial --global-option --rust --no-use-pep517
+`--no-use-pep517` is here to tell `pip` to preserve backwards compatibility with
+the legacy `` system. Mercurial has not yet migrated its complex setup
+to the new system, so we still need this to add compiled extensions.
+This might take a couple of minutes because you're compiling everything.
+See the "Checking for Rust" section to see if the install succeeded.
+From your distribution
+Some distributions are shipping Mercurial with Rust extensions enabled and
+pre-compiled (meaning you won't have to install `cargo`), or allow you to
+specify an install flag. Check with your specific distribution for how to do
+that, or ask their team to add support for hg+Rust!
+From source
+Please refer to the `rust/README.rst` file in the Mercurial repository for
+instructions on how to install from source.
+The minimum supported Rust version is currently 1.48.0. The project's policy is
+to follow the version from Debian stable, to make the distributions' job easier.
+There exists an experimental pure-Rust version of Mercurial called `rhg` with a
+fallback mechanism for unsupported invocations. It allows for much faster
+execution of certain commands while adding no discernable overhead for the rest.
+The only way of trying it out is by building it from source. Please refer to
+`rust/README.rst` in the Mercurial repository.
+If you would like to help the Rust endeavor, please refer to `rust/README.rst`
+in the Mercurial repository.
diff --git a/mercurial/ b/mercurial/
--- a/mercurial/
+++ b/mercurial/
@@ -484,6 +484,15 @@ 
+            [
+                b'rust',
+                b'rustext',
+            ],
+            _(b'Rust in Mercurial'),
+            loaddoc(b'rust'),
+        ),
+        (
             [b'filesets', b'fileset'],
             _(b"Specifying File Sets"),