D7952: rust: add a README
valentin.gatienbaron (Valentin Gatien-Baron)
phabricator at mercurial-scm.org
Tue Jan 21 11:26:14 EST 2020
Closed by commit rHGe1b8b4e4f496: rust: add a README (authored by valentin.gatienbaron).
This revision was automatically updated to reflect the committed changes.
REPOSITORY
rHG Mercurial
CHANGES SINCE LAST UPDATE
https://phab.mercurial-scm.org/D7952?vs=19472&id=19473
CHANGES SINCE LAST ACTION
https://phab.mercurial-scm.org/D7952/new/
REVISION DETAIL
https://phab.mercurial-scm.org/D7952
AFFECTED FILES
rust/README.rst
setup.py
CHANGE DETAILS
diff --git a/setup.py b/setup.py
--- a/setup.py
+++ b/setup.py
@@ -1382,9 +1382,9 @@
class RustEnhancedExtension(RustExtension):
"""A C Extension, conditionally enhanced with Rust code.
- If the HGRUSTEXT environment variable is set to something else
- than 'cpython', the Rust sources get compiled and linked within the
- C target shared library object.
+ If the HGWITHRUSTEXT environment variable is set to something else
+ than 'cpython', the Rust sources get compiled and linked within
+ the C target shared library object.
"""
def __init__(self, mpath, sources, rustlibname, subcrate, **kw):
diff --git a/rust/README.rst b/rust/README.rst
--- a/rust/README.rst
+++ b/rust/README.rst
@@ -3,17 +3,50 @@
===================
This directory contains various Rust code for the Mercurial project.
+Rust is not required to use (or build) Mercurial, but using it
+improves performance in some areas.
-The top-level ``Cargo.toml`` file defines a workspace containing
-all primary Mercurial crates.
+There are currently three independent rust projects:
+- chg. An implementation of chg, in rust instead of C.
+- hgcli. A experiment for starting hg in rust rather than in python,
+ by linking with the python runtime. Probably meant to be replaced by
+ PyOxidizer at some point.
+- hg-core (and hg-cpython/hg-directffi): implementation of some
+ functionality of mercurial in rust, e.g. ancestry computations in
+ revision graphs or pull discovery. The top-level ``Cargo.toml`` file
+ defines a workspace containing these crates.
+
+Using hg-core
+=============
-Building
-========
+Local use (you need to clean previous build artifacts if you have
+built without rust previously)::
-To build the Rust components::
+ $ HGWITHRUSTEXT=cpython make local # to use ./hg
+ $ HGWITHRUSTEXT=cpython make tests # to run all tests
+ $ (cd tests; HGWITHRUSTEXT=cpython ./run-tests.py) # only the .t
+ $ ./hg debuginstall | grep rust # to validate rust is in use
+ checking module policy (rust+c-allow)
- $ cargo build
+Setting ``HGWITHRUSTEXT`` to other values like ``true`` is deprecated
+and enables only a fraction of the rust code.
-If you prefer a non-debug / release configuration::
+Developing hg-core
+==================
+
+Simply run::
$ cargo build --release
+
+It is possible to build without ``--release``, but it is not
+recommended if performance is of any interest: there can be an order
+of magnitude of degradation when removing ``--release``.
+
+For faster builds, you may want to skip code generation::
+
+ $ cargo check
+
+You can run only the rust-specific tests (as opposed to tests of
+mercurial as a whole) with::
+
+ $ cargo test --all
To: valentin.gatienbaron, #hg-reviewers, Alphare, pulkit
Cc: pulkit, gracinet, Alphare, mjpieters, mercurial-devel
More information about the Mercurial-devel
mailing list