docs: add documentation about Rust
This makes the features more discoverable for users.
Differential Revision: https://phab.mercurial-scm.org/D11808
--- a/mercurial/help.py Mon Jan 03 10:43:17 2022 +0100
+++ b/mercurial/help.py Fri Nov 26 14:28:27 2021 +0100
@@ -484,6 +484,15 @@
TOPIC_CATEGORY_IDS,
),
(
+ [
+ b'rust',
+ b'rustext',
+ ],
+ _(b'Rust in Mercurial'),
+ loaddoc(b'rust'),
+ TOPIC_CATEGORY_CONFIG,
+ ),
+ (
[b'filesets', b'fileset'],
_(b"Specifying File Sets"),
loaddoc(b'filesets'),
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/mercurial/helptext/rust.txt Fri Nov 26 14:28:27 2021 +0100
@@ -0,0 +1,94 @@
+Mercurial can be augmented with Rust extensions for speeding up certain
+operations.
+
+Compatibility
+=============
+
+Though the Rust extensions are only tested by the project under Linux, users of
+MacOS, FreeBSD and 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.
+
+Features
+========
+
+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 install 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.
+
+Installing
+==========
+
+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 `setup.py` 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.
+
+MSRV
+====
+
+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.
+
+rhg
+===
+
+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.
+
+Contributing
+============
+
+If you would like to help the Rust endeavor, please refer to `rust/README.rst`
+in the Mercurial repository.
--- a/tests/test-globalopts.t Mon Jan 03 10:43:17 2022 +0100
+++ b/tests/test-globalopts.t Fri Nov 26 14:28:27 2021 +0100
@@ -414,6 +414,7 @@
hgweb Configuring hgweb
merge-tools Merge Tools
pager Pager Support
+ rust Rust in Mercurial
Concepts:
@@ -548,6 +549,7 @@
hgweb Configuring hgweb
merge-tools Merge Tools
pager Pager Support
+ rust Rust in Mercurial
Concepts:
--- a/tests/test-help-hide.t Mon Jan 03 10:43:17 2022 +0100
+++ b/tests/test-help-hide.t Fri Nov 26 14:28:27 2021 +0100
@@ -113,6 +113,7 @@
hgweb Configuring hgweb
merge-tools Merge Tools
pager Pager Support
+ rust Rust in Mercurial
Concepts:
@@ -251,6 +252,7 @@
hgweb Configuring hgweb
merge-tools Merge Tools
pager Pager Support
+ rust Rust in Mercurial
Concepts:
--- a/tests/test-help.t Mon Jan 03 10:43:17 2022 +0100
+++ b/tests/test-help.t Fri Nov 26 14:28:27 2021 +0100
@@ -165,6 +165,7 @@
hgweb Configuring hgweb
merge-tools Merge Tools
pager Pager Support
+ rust Rust in Mercurial
Concepts:
@@ -295,6 +296,7 @@
hgweb Configuring hgweb
merge-tools Merge Tools
pager Pager Support
+ rust Rust in Mercurial
Concepts:
@@ -1583,6 +1585,8 @@
"usefncache"
+ "exp-rc-dirstate-v2"
+
"use-persistent-nodemap"
"use-share-safe"
@@ -2413,6 +2417,13 @@
Specifying Revisions
</td></tr>
<tr><td>
+ <a href="/help/rust">
+ rust
+ </a>
+ </td><td>
+ Rust in Mercurial
+ </td></tr>
+ <tr><td>
<a href="/help/scripting">
scripting
</a>
--- a/tests/test-hgweb-json.t Mon Jan 03 10:43:17 2022 +0100
+++ b/tests/test-hgweb-json.t Fri Nov 26 14:28:27 2021 +0100
@@ -2324,6 +2324,10 @@
"topic": "revisions"
},
{
+ "summary": "Rust in Mercurial",
+ "topic": "rust"
+ },
+ {
"summary": "Using Mercurial from scripts and automation",
"topic": "scripting"
},