Mercurial > hg
changeset 48532:7ccd31fda132 stable
docs: add documentation about Rust
This makes the features more discoverable for users.
Differential Revision: https://phab.mercurial-scm.org/D11808
| author | Raphaël Gomès <rgomes@octobus.net> |
|---|---|
| date | Fri, 26 Nov 2021 14:28:27 +0100 |
| parents | b52cf5063865 |
| children | 5e7a0348acf8 |
| files | mercurial/help.py mercurial/helptext/rust.txt tests/test-globalopts.t tests/test-help-hide.t tests/test-help.t tests/test-hgweb-json.t |
| diffstat | 6 files changed, 122 insertions(+), 0 deletions(-) [+] |
line wrap: on
line diff
--- 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" },