rust/README.rst
author Martin von Zweigbergk <martinvonz@google.com>
Mon, 18 Apr 2022 20:45:38 -0700
branchstable
changeset 49067 770e1352e9f9
parent 48535 799fdf4cca80
child 48842 649ff7f86f96
permissions -rw-r--r--
amend: don't remove unselected removals from memctx When there are removed files in the working copy and they are not selected to be amended into the parent, the `filectxfn` we create for the `memctx` would still return `None` before this patch. That's clearly incorrect; we should return the `filectx` from the unamended commit. Somehow it seems to not matter much except for the case with copies stored in changesets. Thanks to Kyle Lippincott for doing all the debugging and identifying the fix for this issue. Differential Revision: https://phab.mercurial-scm.org/D12573
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
48535
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,
44903
69d3ce00df99 rust: update the mention of hgcli in rust/README.rst
Valentin Gatien-Baron <valentin.gatienbaron@gmail.com>
parents: 44885
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: 44885
diff changeset
    13
  hgcli/README.md.
44549
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
48535
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
44549
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.
48535
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
44549
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
44549
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)
44549
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
45609
e604a3c03ab9 rust: introduce `dirstate-tree` cargo feature
Raphaël Gomès <rgomes@octobus.net>
parents: 44904
diff changeset
    40
Special features
e604a3c03ab9 rust: introduce `dirstate-tree` cargo feature
Raphaël Gomès <rgomes@octobus.net>
parents: 44904
diff changeset
    41
================
e604a3c03ab9 rust: introduce `dirstate-tree` cargo feature
Raphaël Gomès <rgomes@octobus.net>
parents: 44904
diff changeset
    42
e604a3c03ab9 rust: introduce `dirstate-tree` cargo feature
Raphaël Gomès <rgomes@octobus.net>
parents: 44904
diff changeset
    43
You might want to check the `features` section in ``hg-cpython/Cargo.toml``.
e604a3c03ab9 rust: introduce `dirstate-tree` cargo feature
Raphaël Gomès <rgomes@octobus.net>
parents: 44904
diff changeset
    44
It may contain features that might be interesting to try out.
e604a3c03ab9 rust: introduce `dirstate-tree` cargo feature
Raphaël Gomès <rgomes@octobus.net>
parents: 44904
diff changeset
    45
46140
ec14c37958ec rust: document how to enable debug information in optimized builds
Simon Sapin <simon.sapin@octobus.net>
parents: 45614
diff changeset
    46
To use features from the Makefile, use the `HG_RUST_FEATURES` environment
45609
e604a3c03ab9 rust: introduce `dirstate-tree` cargo feature
Raphaël Gomès <rgomes@octobus.net>
parents: 44904
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: 44904
diff changeset
    48
44904
7ca1d635e4a6 rust: add a pointer for profiling to the README
Valentin Gatien-Baron <valentin.gatienbaron@gmail.com>
parents: 44903
diff changeset
    49
Profiling
7ca1d635e4a6 rust: add a pointer for profiling to the README
Valentin Gatien-Baron <valentin.gatienbaron@gmail.com>
parents: 44903
diff changeset
    50
=========
7ca1d635e4a6 rust: add a pointer for profiling to the README
Valentin Gatien-Baron <valentin.gatienbaron@gmail.com>
parents: 44903
diff changeset
    51
7ca1d635e4a6 rust: add a pointer for profiling to the README
Valentin Gatien-Baron <valentin.gatienbaron@gmail.com>
parents: 44903
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: 44903
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: 44903
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: 44903
diff changeset
    55
hgignore).
7ca1d635e4a6 rust: add a pointer for profiling to the README
Valentin Gatien-Baron <valentin.gatienbaron@gmail.com>
parents: 44903
diff changeset
    56
46140
ec14c37958ec rust: document how to enable debug information in optimized builds
Simon Sapin <simon.sapin@octobus.net>
parents: 45614
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: 45614
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: 45614
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: 45614
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: 45614
diff changeset
    61
ec14c37958ec rust: document how to enable debug information in optimized builds
Simon Sapin <simon.sapin@octobus.net>
parents: 45614
diff changeset
    62
  [profile.release]
ec14c37958ec rust: document how to enable debug information in optimized builds
Simon Sapin <simon.sapin@octobus.net>
parents: 45614
diff changeset
    63
  debug = true
ec14c37958ec rust: document how to enable debug information in optimized builds
Simon Sapin <simon.sapin@octobus.net>
parents: 45614
diff changeset
    64
44904
7ca1d635e4a6 rust: add a pointer for profiling to the README
Valentin Gatien-Baron <valentin.gatienbaron@gmail.com>
parents: 44903
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: 44903
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: 44903
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: 44903
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: 44903
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: 44903
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: 44903
diff changeset
    71
46140
ec14c37958ec rust: document how to enable debug information in optimized builds
Simon Sapin <simon.sapin@octobus.net>
parents: 45614
diff changeset
    72
Example usage:
ec14c37958ec rust: document how to enable debug information in optimized builds
Simon Sapin <simon.sapin@octobus.net>
parents: 45614
diff changeset
    73
ec14c37958ec rust: document how to enable debug information in optimized builds
Simon Sapin <simon.sapin@octobus.net>
parents: 45614
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: 45614
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: 45614
diff changeset
    76
44549
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: 46140
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: 46140
diff changeset
    81
stable has. You can use ``rustup override set 1.48.0`` at the root of the repo
44549
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
44549
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
44549
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.