This is an archive of the discontinued Mercurial Phabricator instance.

Differential D11808

docs: add documentation about Rust
ClosedPublic

Authored by Alphare on Nov 26 2021, 8:30 AM.

Details

Reviewers
pulkit
Group Reviewers
hg-reviewers
Commits
rHG7ccd31fda132: docs: add documentation about Rust
Summary

This makes the features more discoverable for users.

Diff Detail

Repository
rHG Mercurial
Branch
stable
Lint
No Linters Available
Unit
No Unit Test Coverage

Event Timeline

Alphare created this revision.Nov 26 2021, 8:30 AM

Pending CI refresh

Alphare planned changes to this revision.Nov 26 2021, 10:06 AM

This patch is missing some updates to tests, I'm pushing them now. I'm also rebasing on stable because this should go into 6.0.1.

Alphare updated this revision to Diff 31155.Nov 26 2021, 10:13 AM
Alphare added a comment.Nov 26 2021, 10:13 AM

Should be good now. Again, this is destined for stable :)

pulkit accepted this revision.Nov 28 2021, 5:09 PM
This revision is now accepted and ready to land.Nov 28 2021, 5:09 PM
joerg.sonnenberger added a subscriber: joerg.sonnenberger.Dec 23 2021, 9:06 AM
joerg.sonnenberger added inline comments.
mercurial/helptext/rust.txt
8

...FreeBSD, and other ...

30

"how you got" pr "how you installed"?

Alphare updated this revision to Diff 31568.Dec 23 2021, 10:02 AM
Alphare added a commit: rHG7ccd31fda132: docs: add documentation about Rust.Jan 5 2022, 11:46 AM
Closed by commit rHG7ccd31fda132: docs: add documentation about Rust (authored by Alphare). · Explain Why
This revision was automatically updated to reflect the committed changes.

Revision Contents
Changeset List

Diff 31155

mercurial/help.py

b'multirevs', b'multirevs',
b'mrevs', b'mrevs',
], ],
_(b'Specifying Revisions'), _(b'Specifying Revisions'),
loaddoc(b'revisions'), loaddoc(b'revisions'),
TOPIC_CATEGORY_IDS, TOPIC_CATEGORY_IDS,
), ),
( (
[
b'rust',
b'rustext',
],
_(b'Rust in Mercurial'),
loaddoc(b'rust'),
TOPIC_CATEGORY_CONFIG,
),
(
[b'filesets', b'fileset'], [b'filesets', b'fileset'],
_(b"Specifying File Sets"), _(b"Specifying File Sets"),
loaddoc(b'filesets'), loaddoc(b'filesets'),
TOPIC_CATEGORY_IDS, TOPIC_CATEGORY_IDS,
), ),
( (
[b'diffs'], [b'diffs'],
_(b'Diff Formats'), _(b'Diff Formats'),

mercurial/helptext/rust.txt

  • This file was added.
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, other UNIX-likes have been using the Rust extensions. Your
joerg.sonnenbergerUnsubmitted
Not Done

...FreeBSD, and other ...

joerg.sonnenberger: ...FreeBSD, and other ...
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 get Mercurial.
joerg.sonnenbergerUnsubmitted
Not Done

"how you got" pr "how you installed"?

joerg.sonnenberger: "how you got" pr "how you installed"?
$ 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.

tests/test-globalopts.t

config Configuration Files config Configuration Files
environment Environment Variables environment Environment Variables
extensions Using Additional Features extensions Using Additional Features
flags Command-line flags flags Command-line flags
hgweb Configuring hgweb hgweb Configuring hgweb
merge-tools Merge Tools merge-tools Merge Tools
pager Pager Support pager Pager Support
rust Rust in Mercurial
Concepts: Concepts:
bundlespec Bundle File Formats bundlespec Bundle File Formats
evolution Safely rewriting history (EXPERIMENTAL) evolution Safely rewriting history (EXPERIMENTAL)
glossary Glossary glossary Glossary
phases Working with Phases phases Working with Phases
subrepos Subrepositories subrepos Subrepositories
config Configuration Files config Configuration Files
environment Environment Variables environment Environment Variables
extensions Using Additional Features extensions Using Additional Features
flags Command-line flags flags Command-line flags
hgweb Configuring hgweb hgweb Configuring hgweb
merge-tools Merge Tools merge-tools Merge Tools
pager Pager Support pager Pager Support
rust Rust in Mercurial
Concepts: Concepts:
bundlespec Bundle File Formats bundlespec Bundle File Formats
evolution Safely rewriting history (EXPERIMENTAL) evolution Safely rewriting history (EXPERIMENTAL)
glossary Glossary glossary Glossary
phases Working with Phases phases Working with Phases
subrepos Subrepositories subrepos Subrepositories

tests/test-help-hide.t

config Configuration Files config Configuration Files
environment Environment Variables environment Environment Variables
extensions Using Additional Features extensions Using Additional Features
flags Command-line flags flags Command-line flags
hgweb Configuring hgweb hgweb Configuring hgweb
merge-tools Merge Tools merge-tools Merge Tools
pager Pager Support pager Pager Support
rust Rust in Mercurial
Concepts: Concepts:
bundlespec Bundle File Formats bundlespec Bundle File Formats
evolution Safely rewriting history (EXPERIMENTAL) evolution Safely rewriting history (EXPERIMENTAL)
glossary Glossary glossary Glossary
phases Working with Phases phases Working with Phases
subrepos Subrepositories subrepos Subrepositories
config Configuration Files config Configuration Files
environment Environment Variables environment Environment Variables
extensions Using Additional Features extensions Using Additional Features
flags Command-line flags flags Command-line flags
hgweb Configuring hgweb hgweb Configuring hgweb
merge-tools Merge Tools merge-tools Merge Tools
pager Pager Support pager Pager Support
rust Rust in Mercurial
Concepts: Concepts:
bundlespec Bundle File Formats bundlespec Bundle File Formats
evolution Safely rewriting history (EXPERIMENTAL) evolution Safely rewriting history (EXPERIMENTAL)
glossary Glossary glossary Glossary
phases Working with Phases phases Working with Phases
subrepos Subrepositories subrepos Subrepositories
(use 'hg help -v' to show built-in aliases and global options) (use 'hg help -v' to show built-in aliases and global options)

tests/test-help.t

config Configuration Files config Configuration Files
environment Environment Variables environment Environment Variables
extensions Using Additional Features extensions Using Additional Features
flags Command-line flags flags Command-line flags
hgweb Configuring hgweb hgweb Configuring hgweb
merge-tools Merge Tools merge-tools Merge Tools
pager Pager Support pager Pager Support
rust Rust in Mercurial
Concepts: Concepts:
bundlespec Bundle File Formats bundlespec Bundle File Formats
evolution Safely rewriting history (EXPERIMENTAL) evolution Safely rewriting history (EXPERIMENTAL)
glossary Glossary glossary Glossary
phases Working with Phases phases Working with Phases
subrepos Subrepositories subrepos Subrepositories
config Configuration Files config Configuration Files
environment Environment Variables environment Environment Variables
extensions Using Additional Features extensions Using Additional Features
flags Command-line flags flags Command-line flags
hgweb Configuring hgweb hgweb Configuring hgweb
merge-tools Merge Tools merge-tools Merge Tools
pager Pager Support pager Pager Support
rust Rust in Mercurial
Concepts: Concepts:
bundlespec Bundle File Formats bundlespec Bundle File Formats
evolution Safely rewriting history (EXPERIMENTAL) evolution Safely rewriting history (EXPERIMENTAL)
glossary Glossary glossary Glossary
phases Working with Phases phases Working with Phases
subrepos Subrepositories subrepos Subrepositories
-------- --------
"usegeneraldelta" "usegeneraldelta"
"dotencode" "dotencode"
"usefncache" "usefncache"
"exp-rc-dirstate-v2"
"use-persistent-nodemap" "use-persistent-nodemap"
"use-share-safe" "use-share-safe"
"usestore" "usestore"
"sparse-revlog" "sparse-revlog"
<tr><td> <tr><td>
<a href="/help/revisions"> <a href="/help/revisions">
revisions revisions
</a> </a>
</td><td> </td><td>
Specifying Revisions Specifying Revisions
</td></tr> </td></tr>
<tr><td> <tr><td>
<a href="/help/rust">
rust
</a>
</td><td>
Rust in Mercurial
</td></tr>
<tr><td>
<a href="/help/scripting"> <a href="/help/scripting">
scripting scripting
</a> </a>
</td><td> </td><td>
Using Mercurial from scripts and automation Using Mercurial from scripts and automation
</td></tr> </td></tr>
<tr><td> <tr><td>
<a href="/help/subrepos"> <a href="/help/subrepos">

tests/test-hgweb-json.t

"summary": "Working with Phases", "summary": "Working with Phases",
"topic": "phases" "topic": "phases"
}, },
{ {
"summary": "Specifying Revisions", "summary": "Specifying Revisions",
"topic": "revisions" "topic": "revisions"
}, },
{ {
"summary": "Rust in Mercurial",
"topic": "rust"
},
{
"summary": "Using Mercurial from scripts and automation", "summary": "Using Mercurial from scripts and automation",
"topic": "scripting" "topic": "scripting"
}, },
{ {
"summary": "Subrepositories", "summary": "Subrepositories",
"topic": "subrepos" "topic": "subrepos"
}, },
{ {