rust/README.rst
author Simon Sapin <simon.sapin@octobus.net>
Thu, 03 Mar 2022 07:53:11 +0100
changeset 48933 649ff7f86f96
parent 48349 799fdf4cca80
child 49747 eb383f093a01
permissions -rw-r--r--
rust: enable Python 3 support unconditionally Note: `cpython/python3-sys` is a default feature. Differential Revision: https://phab.mercurial-scm.org/D12316
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
35569
964212780daf rust: implementation of `hg`
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
     1
===================
964212780daf rust: implementation of `hg`
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
     2
Mercurial Rust Code
964212780daf rust: implementation of `hg`
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
     3
===================
964212780daf rust: implementation of `hg`
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
     4
964212780daf rust: implementation of `hg`
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
     5
This directory contains various Rust code for the Mercurial project.
44115
e1b8b4e4f496 rust: add a README
Valentin Gatien-Baron <valentin.gatienbaron@gmail.com>
parents: 44114
diff changeset
     6
Rust is not required to use (or build) Mercurial, but using it
e1b8b4e4f496 rust: add a README
Valentin Gatien-Baron <valentin.gatienbaron@gmail.com>
parents: 44114
diff changeset
     7
improves performance in some areas.
35569
964212780daf rust: implementation of `hg`
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
     8
48349
799fdf4cca80 docs: update Rust readme with a mention of `rhg`
Raphaël Gomès <rgomes@octobus.net>
parents: 48296
diff changeset
     9
There are currently four independent Rust projects:
799fdf4cca80 docs: update Rust readme with a mention of `rhg`
Raphaël Gomès <rgomes@octobus.net>
parents: 48296
diff changeset
    10
- chg. An implementation of chg, in Rust instead of C.
799fdf4cca80 docs: update Rust readme with a mention of `rhg`
Raphaël Gomès <rgomes@octobus.net>
parents: 48296
diff changeset
    11
- hgcli. A project that provides a (mostly) self-contained "hg" binary,
44962
69d3ce00df99 rust: update the mention of hgcli in rust/README.rst
Valentin Gatien-Baron <valentin.gatienbaron@gmail.com>
parents: 44944
diff changeset
    12
  for ease of deployment and a bit of speed, using PyOxidizer. See
69d3ce00df99 rust: update the mention of hgcli in rust/README.rst
Valentin Gatien-Baron <valentin.gatienbaron@gmail.com>
parents: 44944
diff changeset
    13
  hgcli/README.md.
44559
47f8c741df0f rust: update the README with more up-to-date and thorough information
Raphaël Gomès <rgomes@octobus.net>
parents: 44115
diff changeset
    14
- hg-core (and hg-cpython): implementation of some
48349
799fdf4cca80 docs: update Rust readme with a mention of `rhg`
Raphaël Gomès <rgomes@octobus.net>
parents: 48296
diff changeset
    15
  functionality of mercurial in Rust, e.g. ancestry computations in
44559
47f8c741df0f rust: update the README with more up-to-date and thorough information
Raphaël Gomès <rgomes@octobus.net>
parents: 44115
diff changeset
    16
  revision graphs, status or pull discovery. The top-level ``Cargo.toml`` file
44115
e1b8b4e4f496 rust: add a README
Valentin Gatien-Baron <valentin.gatienbaron@gmail.com>
parents: 44114
diff changeset
    17
  defines a workspace containing these crates.
48349
799fdf4cca80 docs: update Rust readme with a mention of `rhg`
Raphaël Gomès <rgomes@octobus.net>
parents: 48296
diff changeset
    18
- rhg: a pure Rust implementation of Mercurial, with a fallback mechanism for
799fdf4cca80 docs: update Rust readme with a mention of `rhg`
Raphaël Gomès <rgomes@octobus.net>
parents: 48296
diff changeset
    19
  unsupported invocations. It reuses the logic `hg-core` but completely forgoes
799fdf4cca80 docs: update Rust readme with a mention of `rhg`
Raphaël Gomès <rgomes@octobus.net>
parents: 48296
diff changeset
    20
  interaction with Python. See `rust/rhg/README.md` for more details.
44115
e1b8b4e4f496 rust: add a README
Valentin Gatien-Baron <valentin.gatienbaron@gmail.com>
parents: 44114
diff changeset
    21
44559
47f8c741df0f rust: update the README with more up-to-date and thorough information
Raphaël Gomès <rgomes@octobus.net>
parents: 44115
diff changeset
    22
Using Rust code
47f8c741df0f rust: update the README with more up-to-date and thorough information
Raphaël Gomès <rgomes@octobus.net>
parents: 44115
diff changeset
    23
===============
35569
964212780daf rust: implementation of `hg`
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
    24
44115
e1b8b4e4f496 rust: add a README
Valentin Gatien-Baron <valentin.gatienbaron@gmail.com>
parents: 44114
diff changeset
    25
Local use (you need to clean previous build artifacts if you have
e1b8b4e4f496 rust: add a README
Valentin Gatien-Baron <valentin.gatienbaron@gmail.com>
parents: 44114
diff changeset
    26
built without rust previously)::
35569
964212780daf rust: implementation of `hg`
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
    27
44559
47f8c741df0f rust: update the README with more up-to-date and thorough information
Raphaël Gomès <rgomes@octobus.net>
parents: 44115
diff changeset
    28
  $ make PURE=--rust local # to use ./hg
47f8c741df0f rust: update the README with more up-to-date and thorough information
Raphaël Gomès <rgomes@octobus.net>
parents: 44115
diff changeset
    29
  $ ./tests/run-tests.py --rust # to run all tests
47f8c741df0f rust: update the README with more up-to-date and thorough information
Raphaël Gomès <rgomes@octobus.net>
parents: 44115
diff changeset
    30
  $ ./hg debuginstall | grep -i rust # to validate rust is in use
47f8c741df0f rust: update the README with more up-to-date and thorough information
Raphaël Gomès <rgomes@octobus.net>
parents: 44115
diff changeset
    31
  checking Rust extensions (installed)
44115
e1b8b4e4f496 rust: add a README
Valentin Gatien-Baron <valentin.gatienbaron@gmail.com>
parents: 44114
diff changeset
    32
  checking module policy (rust+c-allow)
44559
47f8c741df0f rust: update the README with more up-to-date and thorough information
Raphaël Gomès <rgomes@octobus.net>
parents: 44115
diff changeset
    33
47f8c741df0f rust: update the README with more up-to-date and thorough information
Raphaël Gomès <rgomes@octobus.net>
parents: 44115
diff changeset
    34
If the environment variable ``HGWITHRUSTEXT=cpython`` is set, the Rust
47f8c741df0f rust: update the README with more up-to-date and thorough information
Raphaël Gomès <rgomes@octobus.net>
parents: 44115
diff changeset
    35
extension will be used by default unless ``--no-rust``.
47f8c741df0f rust: update the README with more up-to-date and thorough information
Raphaël Gomès <rgomes@octobus.net>
parents: 44115
diff changeset
    36
47f8c741df0f rust: update the README with more up-to-date and thorough information
Raphaël Gomès <rgomes@octobus.net>
parents: 44115
diff changeset
    37
One day we may use this environment variable to switch to new experimental
47f8c741df0f rust: update the README with more up-to-date and thorough information
Raphaël Gomès <rgomes@octobus.net>
parents: 44115
diff changeset
    38
binding crates like a hypothetical ``HGWITHRUSTEXT=hpy``.
47f8c741df0f rust: update the README with more up-to-date and thorough information
Raphaël Gomès <rgomes@octobus.net>
parents: 44115
diff changeset
    39
45612
e604a3c03ab9 rust: introduce `dirstate-tree` cargo feature
Raphaël Gomès <rgomes@octobus.net>
parents: 44963
diff changeset
    40
Special features
e604a3c03ab9 rust: introduce `dirstate-tree` cargo feature
Raphaël Gomès <rgomes@octobus.net>
parents: 44963
diff changeset
    41
================
e604a3c03ab9 rust: introduce `dirstate-tree` cargo feature
Raphaël Gomès <rgomes@octobus.net>
parents: 44963
diff changeset
    42
48933
649ff7f86f96 rust: enable Python 3 support unconditionally
Simon Sapin <simon.sapin@octobus.net>
parents: 48349
diff changeset
    43
In the future, compile-time opt-ins may be added
649ff7f86f96 rust: enable Python 3 support unconditionally
Simon Sapin <simon.sapin@octobus.net>
parents: 48349
diff changeset
    44
to the `features` section in ``hg-cpython/Cargo.toml``.
45612
e604a3c03ab9 rust: introduce `dirstate-tree` cargo feature
Raphaël Gomès <rgomes@octobus.net>
parents: 44963
diff changeset
    45
46141
ec14c37958ec rust: document how to enable debug information in optimized builds
Simon Sapin <simon.sapin@octobus.net>
parents: 45617
diff changeset
    46
To use features from the Makefile, use the `HG_RUST_FEATURES` environment
45612
e604a3c03ab9 rust: introduce `dirstate-tree` cargo feature
Raphaël Gomès <rgomes@octobus.net>
parents: 44963
diff changeset
    47
variable: for instance `HG_RUST_FEATURES="some-feature other-feature"`
e604a3c03ab9 rust: introduce `dirstate-tree` cargo feature
Raphaël Gomès <rgomes@octobus.net>
parents: 44963
diff changeset
    48
44963
7ca1d635e4a6 rust: add a pointer for profiling to the README
Valentin Gatien-Baron <valentin.gatienbaron@gmail.com>
parents: 44962
diff changeset
    49
Profiling
7ca1d635e4a6 rust: add a pointer for profiling to the README
Valentin Gatien-Baron <valentin.gatienbaron@gmail.com>
parents: 44962
diff changeset
    50
=========
7ca1d635e4a6 rust: add a pointer for profiling to the README
Valentin Gatien-Baron <valentin.gatienbaron@gmail.com>
parents: 44962
diff changeset
    51
7ca1d635e4a6 rust: add a pointer for profiling to the README
Valentin Gatien-Baron <valentin.gatienbaron@gmail.com>
parents: 44962
diff changeset
    52
Setting the environment variable ``RUST_LOG=trace`` will make hg print
7ca1d635e4a6 rust: add a pointer for profiling to the README
Valentin Gatien-Baron <valentin.gatienbaron@gmail.com>
parents: 44962
diff changeset
    53
a few high level rust-related performance numbers. It can also
7ca1d635e4a6 rust: add a pointer for profiling to the README
Valentin Gatien-Baron <valentin.gatienbaron@gmail.com>
parents: 44962
diff changeset
    54
indicate why the rust code cannot be used (say, using lookarounds in
7ca1d635e4a6 rust: add a pointer for profiling to the README
Valentin Gatien-Baron <valentin.gatienbaron@gmail.com>
parents: 44962
diff changeset
    55
hgignore).
7ca1d635e4a6 rust: add a pointer for profiling to the README
Valentin Gatien-Baron <valentin.gatienbaron@gmail.com>
parents: 44962
diff changeset
    56
46141
ec14c37958ec rust: document how to enable debug information in optimized builds
Simon Sapin <simon.sapin@octobus.net>
parents: 45617
diff changeset
    57
Creating a ``.cargo/config`` file with the following content enables
ec14c37958ec rust: document how to enable debug information in optimized builds
Simon Sapin <simon.sapin@octobus.net>
parents: 45617
diff changeset
    58
debug information in optimized builds. This make profiles more informative
ec14c37958ec rust: document how to enable debug information in optimized builds
Simon Sapin <simon.sapin@octobus.net>
parents: 45617
diff changeset
    59
with source file name and line number for Rust stack frames and
ec14c37958ec rust: document how to enable debug information in optimized builds
Simon Sapin <simon.sapin@octobus.net>
parents: 45617
diff changeset
    60
(in some cases) stack frames for Rust functions that have been inlined.
ec14c37958ec rust: document how to enable debug information in optimized builds
Simon Sapin <simon.sapin@octobus.net>
parents: 45617
diff changeset
    61
ec14c37958ec rust: document how to enable debug information in optimized builds
Simon Sapin <simon.sapin@octobus.net>
parents: 45617
diff changeset
    62
  [profile.release]
ec14c37958ec rust: document how to enable debug information in optimized builds
Simon Sapin <simon.sapin@octobus.net>
parents: 45617
diff changeset
    63
  debug = true
ec14c37958ec rust: document how to enable debug information in optimized builds
Simon Sapin <simon.sapin@octobus.net>
parents: 45617
diff changeset
    64
44963
7ca1d635e4a6 rust: add a pointer for profiling to the README
Valentin Gatien-Baron <valentin.gatienbaron@gmail.com>
parents: 44962
diff changeset
    65
``py-spy`` (https://github.com/benfred/py-spy) can be used to
7ca1d635e4a6 rust: add a pointer for profiling to the README
Valentin Gatien-Baron <valentin.gatienbaron@gmail.com>
parents: 44962
diff changeset
    66
construct a single profile with rust functions and python functions
7ca1d635e4a6 rust: add a pointer for profiling to the README
Valentin Gatien-Baron <valentin.gatienbaron@gmail.com>
parents: 44962
diff changeset
    67
(as opposed to ``hg --profile``, which attributes time spent in rust
7ca1d635e4a6 rust: add a pointer for profiling to the README
Valentin Gatien-Baron <valentin.gatienbaron@gmail.com>
parents: 44962
diff changeset
    68
to some unlucky python code running shortly after the rust code, and
7ca1d635e4a6 rust: add a pointer for profiling to the README
Valentin Gatien-Baron <valentin.gatienbaron@gmail.com>
parents: 44962
diff changeset
    69
as opposed to tools for native code like ``perf``, which attribute
7ca1d635e4a6 rust: add a pointer for profiling to the README
Valentin Gatien-Baron <valentin.gatienbaron@gmail.com>
parents: 44962
diff changeset
    70
time to the python interpreter instead of python functions).
7ca1d635e4a6 rust: add a pointer for profiling to the README
Valentin Gatien-Baron <valentin.gatienbaron@gmail.com>
parents: 44962
diff changeset
    71
46141
ec14c37958ec rust: document how to enable debug information in optimized builds
Simon Sapin <simon.sapin@octobus.net>
parents: 45617
diff changeset
    72
Example usage:
ec14c37958ec rust: document how to enable debug information in optimized builds
Simon Sapin <simon.sapin@octobus.net>
parents: 45617
diff changeset
    73
ec14c37958ec rust: document how to enable debug information in optimized builds
Simon Sapin <simon.sapin@octobus.net>
parents: 45617
diff changeset
    74
  $ make PURE=--rust local # Don't forget to recompile after a code change
ec14c37958ec rust: document how to enable debug information in optimized builds
Simon Sapin <simon.sapin@octobus.net>
parents: 45617
diff changeset
    75
  $ py-spy record --native --output /tmp/profile.svg -- ./hg ...
ec14c37958ec rust: document how to enable debug information in optimized builds
Simon Sapin <simon.sapin@octobus.net>
parents: 45617
diff changeset
    76
44559
47f8c741df0f rust: update the README with more up-to-date and thorough information
Raphaël Gomès <rgomes@octobus.net>
parents: 44115
diff changeset
    77
Developing Rust
47f8c741df0f rust: update the README with more up-to-date and thorough information
Raphaël Gomès <rgomes@octobus.net>
parents: 44115
diff changeset
    78
===============
35569
964212780daf rust: implementation of `hg`
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
    79
48296
4ee6b8b40787 rust: update the minimum version of Rust
Raphaël Gomès <rgomes@octobus.net>
parents: 46141
diff changeset
    80
The current version of Rust in use is ``1.48.0``, because it's what Debian
4ee6b8b40787 rust: update the minimum version of Rust
Raphaël Gomès <rgomes@octobus.net>
parents: 46141
diff changeset
    81
stable has. You can use ``rustup override set 1.48.0`` at the root of the repo
44559
47f8c741df0f rust: update the README with more up-to-date and thorough information
Raphaël Gomès <rgomes@octobus.net>
parents: 44115
diff changeset
    82
to make it easier on you.
47f8c741df0f rust: update the README with more up-to-date and thorough information
Raphaël Gomès <rgomes@octobus.net>
parents: 44115
diff changeset
    83
47f8c741df0f rust: update the README with more up-to-date and thorough information
Raphaël Gomès <rgomes@octobus.net>
parents: 44115
diff changeset
    84
Go to the ``hg-cpython`` folder::
47f8c741df0f rust: update the README with more up-to-date and thorough information
Raphaël Gomès <rgomes@octobus.net>
parents: 44115
diff changeset
    85
47f8c741df0f rust: update the README with more up-to-date and thorough information
Raphaël Gomès <rgomes@octobus.net>
parents: 44115
diff changeset
    86
  $ cd rust/hg-cpython
47f8c741df0f rust: update the README with more up-to-date and thorough information
Raphaël Gomès <rgomes@octobus.net>
parents: 44115
diff changeset
    87
47f8c741df0f rust: update the README with more up-to-date and thorough information
Raphaël Gomès <rgomes@octobus.net>
parents: 44115
diff changeset
    88
Or, only the ``hg-core`` folder. Be careful not to break compatibility::
47f8c741df0f rust: update the README with more up-to-date and thorough information
Raphaël Gomès <rgomes@octobus.net>
parents: 44115
diff changeset
    89
47f8c741df0f rust: update the README with more up-to-date and thorough information
Raphaël Gomès <rgomes@octobus.net>
parents: 44115
diff changeset
    90
  $ cd rust/hg-core
44115
e1b8b4e4f496 rust: add a README
Valentin Gatien-Baron <valentin.gatienbaron@gmail.com>
parents: 44114
diff changeset
    91
e1b8b4e4f496 rust: add a README
Valentin Gatien-Baron <valentin.gatienbaron@gmail.com>
parents: 44114
diff changeset
    92
Simply run::
35569
964212780daf rust: implementation of `hg`
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
    93
964212780daf rust: implementation of `hg`
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
    94
   $ cargo build --release
44115
e1b8b4e4f496 rust: add a README
Valentin Gatien-Baron <valentin.gatienbaron@gmail.com>
parents: 44114
diff changeset
    95
e1b8b4e4f496 rust: add a README
Valentin Gatien-Baron <valentin.gatienbaron@gmail.com>
parents: 44114
diff changeset
    96
It is possible to build without ``--release``, but it is not
e1b8b4e4f496 rust: add a README
Valentin Gatien-Baron <valentin.gatienbaron@gmail.com>
parents: 44114
diff changeset
    97
recommended if performance is of any interest: there can be an order
e1b8b4e4f496 rust: add a README
Valentin Gatien-Baron <valentin.gatienbaron@gmail.com>
parents: 44114
diff changeset
    98
of magnitude of degradation when removing ``--release``.
e1b8b4e4f496 rust: add a README
Valentin Gatien-Baron <valentin.gatienbaron@gmail.com>
parents: 44114
diff changeset
    99
e1b8b4e4f496 rust: add a README
Valentin Gatien-Baron <valentin.gatienbaron@gmail.com>
parents: 44114
diff changeset
   100
For faster builds, you may want to skip code generation::
e1b8b4e4f496 rust: add a README
Valentin Gatien-Baron <valentin.gatienbaron@gmail.com>
parents: 44114
diff changeset
   101
e1b8b4e4f496 rust: add a README
Valentin Gatien-Baron <valentin.gatienbaron@gmail.com>
parents: 44114
diff changeset
   102
  $ cargo check
e1b8b4e4f496 rust: add a README
Valentin Gatien-Baron <valentin.gatienbaron@gmail.com>
parents: 44114
diff changeset
   103
44559
47f8c741df0f rust: update the README with more up-to-date and thorough information
Raphaël Gomès <rgomes@octobus.net>
parents: 44115
diff changeset
   104
For even faster typing::
47f8c741df0f rust: update the README with more up-to-date and thorough information
Raphaël Gomès <rgomes@octobus.net>
parents: 44115
diff changeset
   105
47f8c741df0f rust: update the README with more up-to-date and thorough information
Raphaël Gomès <rgomes@octobus.net>
parents: 44115
diff changeset
   106
  $ cargo c
47f8c741df0f rust: update the README with more up-to-date and thorough information
Raphaël Gomès <rgomes@octobus.net>
parents: 44115
diff changeset
   107
44115
e1b8b4e4f496 rust: add a README
Valentin Gatien-Baron <valentin.gatienbaron@gmail.com>
parents: 44114
diff changeset
   108
You can run only the rust-specific tests (as opposed to tests of
e1b8b4e4f496 rust: add a README
Valentin Gatien-Baron <valentin.gatienbaron@gmail.com>
parents: 44114
diff changeset
   109
mercurial as a whole) with::
e1b8b4e4f496 rust: add a README
Valentin Gatien-Baron <valentin.gatienbaron@gmail.com>
parents: 44114
diff changeset
   110
e1b8b4e4f496 rust: add a README
Valentin Gatien-Baron <valentin.gatienbaron@gmail.com>
parents: 44114
diff changeset
   111
  $ cargo test --all
44559
47f8c741df0f rust: update the README with more up-to-date and thorough information
Raphaël Gomès <rgomes@octobus.net>
parents: 44115
diff changeset
   112
47f8c741df0f rust: update the README with more up-to-date and thorough information
Raphaël Gomès <rgomes@octobus.net>
parents: 44115
diff changeset
   113
Formatting the code
47f8c741df0f rust: update the README with more up-to-date and thorough information
Raphaël Gomès <rgomes@octobus.net>
parents: 44115
diff changeset
   114
-------------------
47f8c741df0f rust: update the README with more up-to-date and thorough information
Raphaël Gomès <rgomes@octobus.net>
parents: 44115
diff changeset
   115
47f8c741df0f rust: update the README with more up-to-date and thorough information
Raphaël Gomès <rgomes@octobus.net>
parents: 44115
diff changeset
   116
We use ``rustfmt`` to keep the code formatted at all times. For now, we are
47f8c741df0f rust: update the README with more up-to-date and thorough information
Raphaël Gomès <rgomes@octobus.net>
parents: 44115
diff changeset
   117
using the nightly version because it has been stable enough and provides
47f8c741df0f rust: update the README with more up-to-date and thorough information
Raphaël Gomès <rgomes@octobus.net>
parents: 44115
diff changeset
   118
comment folding.
47f8c741df0f rust: update the README with more up-to-date and thorough information
Raphaël Gomès <rgomes@octobus.net>
parents: 44115
diff changeset
   119
47f8c741df0f rust: update the README with more up-to-date and thorough information
Raphaël Gomès <rgomes@octobus.net>
parents: 44115
diff changeset
   120
To format the entire Rust workspace::
47f8c741df0f rust: update the README with more up-to-date and thorough information
Raphaël Gomès <rgomes@octobus.net>
parents: 44115
diff changeset
   121
47f8c741df0f rust: update the README with more up-to-date and thorough information
Raphaël Gomès <rgomes@octobus.net>
parents: 44115
diff changeset
   122
  $ cargo +nightly fmt
47f8c741df0f rust: update the README with more up-to-date and thorough information
Raphaël Gomès <rgomes@octobus.net>
parents: 44115
diff changeset
   123
47f8c741df0f rust: update the README with more up-to-date and thorough information
Raphaël Gomès <rgomes@octobus.net>
parents: 44115
diff changeset
   124
This requires you to have the nightly toolchain installed.