This is an archive of the discontinued Mercurial Phabricator instance.

Differential D8274

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

Authored by Alphare on Mar 12 2020, 5:17 AM.

Details

Reviewers
None
Group Reviewers
hg-reviewers
Commits
rHG47f8c741df0f: rust: update the README with more up-to-date and thorough information

Diff Detail

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

Event Timeline

Alphare created this revision.Mar 12 2020, 5:17 AM
Alphare added a commit: rHG47f8c741df0f: rust: update the README with more up-to-date and thorough information.Mar 12 2020, 12:19 PM
This revision was not accepted when it landed; it landed in state Needs Review.
Closed by commit rHG47f8c741df0f: rust: update the README with more up-to-date and thorough information (authored by Alphare). · Explain Why
This revision was automatically updated to reflect the committed changes.

Revision Contents
Changeset List

PathPackages
Mrust/README.rst (81 lines)

Diff 20756

rust/README.rst

=================== ===================
Mercurial Rust Code Mercurial Rust Code
=================== ===================
This directory contains various Rust code for the Mercurial project. This directory contains various Rust code for the Mercurial project.
Rust is not required to use (or build) Mercurial, but using it Rust is not required to use (or build) Mercurial, but using it
improves performance in some areas. improves performance in some areas.
There are currently three independent rust projects: There are currently three independent rust projects:
- chg. An implementation of chg, in rust instead of C. - chg. An implementation of chg, in rust instead of C.
- hgcli. A experiment for starting hg in rust rather than in python, - hgcli. A experiment for starting hg in rust rather than in python,
by linking with the python runtime. Probably meant to be replaced by by linking with the python runtime. Probably meant to be replaced by
PyOxidizer at some point. 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 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. defines a workspace containing these crates.
Using hg-core Using Rust code
============= ===============
Local use (you need to clean previous build artifacts if you have Local use (you need to clean previous build artifacts if you have
built without rust previously):: built without rust previously)::
$ HGWITHRUSTEXT=cpython make local # to use ./hg $ make PURE=--rust local # to use ./hg
$ HGWITHRUSTEXT=cpython make tests # to run all tests $ ./tests/run-tests.py --rust # to run all tests
$ (cd tests; HGWITHRUSTEXT=cpython ./run-tests.py) # only the .t $ ./hg debuginstall | grep -i rust # to validate rust is in use
$ ./hg debuginstall | grep rust # to validate rust is in use checking Rust extensions (installed)
checking module policy (rust+c-allow) checking module policy (rust+c-allow)
checking "re2" regexp engine Rust bindings (installed)
Setting ``HGWITHRUSTEXT`` to other values like ``true`` is deprecated
and enables only a fraction of the rust code.
Developing hg-core 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
--------------------------------------
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
===============
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:: Simply run::
$ cargo build --release $ cargo build --release
It is possible to build without ``--release``, but it is not It is possible to build without ``--release``, but it is not
recommended if performance is of any interest: there can be an order recommended if performance is of any interest: there can be an order
of magnitude of degradation when removing ``--release``. of magnitude of degradation when removing ``--release``.
For faster builds, you may want to skip code generation:: For faster builds, you may want to skip code generation::
$ cargo check $ cargo check
For even faster typing::
$ cargo c
You can run only the rust-specific tests (as opposed to tests of You can run only the rust-specific tests (as opposed to tests of
mercurial as a whole) with:: mercurial as a whole) with::
$ cargo test --all $ 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