Mercurial > hg
annotate rust/README.rst @ 47877:2174f54aab18
store: return just one filename in walk functions
Various walk functions return `(revlog_type, decoded, encoded)` where
decoded could be None. But no-one cares about `encoded` and expects
`unencoded` to be present, except verify (because this can only happen
with old repo formats).
Simplify all this by either failing outright if a decoding a filename
fails (instead of almost certainly failing with a type error due to
treating None as a bytes), or skipping the filename but providing in
an out argument for hg verify.
Differential Revision: https://phab.mercurial-scm.org/D11248
author | Valentin Gatien-Baron <valentin.gatienbaron@gmail.com> |
---|---|
date | Mon, 02 Aug 2021 08:05:13 -0400 |
parents | ec14c37958ec |
children | 4ee6b8b40787 |
rev | line source |
---|---|
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 |
44115
e1b8b4e4f496
rust: add a README
Valentin Gatien-Baron <valentin.gatienbaron@gmail.com>
parents:
44114
diff
changeset
|
9 There are currently three independent rust projects: |
e1b8b4e4f496
rust: add a README
Valentin Gatien-Baron <valentin.gatienbaron@gmail.com>
parents:
44114
diff
changeset
|
10 - chg. An implementation of chg, in rust instead of C. |
44903
69d3ce00df99
rust: update the mention of hgcli in rust/README.rst
Valentin Gatien-Baron <valentin.gatienbaron@gmail.com>
parents:
44885
diff
changeset
|
11 - hgcli. A project that provide a (mostly) self-contained "hg" binary, |
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 |
44115
e1b8b4e4f496
rust: add a README
Valentin Gatien-Baron <valentin.gatienbaron@gmail.com>
parents:
44114
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. |
e1b8b4e4f496
rust: add a README
Valentin Gatien-Baron <valentin.gatienbaron@gmail.com>
parents:
44114
diff
changeset
|
18 |
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
|
19 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
|
20 =============== |
35569
964212780daf
rust: implementation of `hg`
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
21 |
44115
e1b8b4e4f496
rust: add a README
Valentin Gatien-Baron <valentin.gatienbaron@gmail.com>
parents:
44114
diff
changeset
|
22 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
|
23 built without rust previously):: |
35569
964212780daf
rust: implementation of `hg`
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
24 |
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
|
25 $ 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
|
26 $ ./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
|
27 $ ./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
|
28 checking Rust extensions (installed) |
44115
e1b8b4e4f496
rust: add a README
Valentin Gatien-Baron <valentin.gatienbaron@gmail.com>
parents:
44114
diff
changeset
|
29 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
|
30 |
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 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
|
32 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
|
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 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
|
35 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
|
36 |
45609
e604a3c03ab9
rust: introduce `dirstate-tree` cargo feature
Raphaël Gomès <rgomes@octobus.net>
parents:
44904
diff
changeset
|
37 Special features |
e604a3c03ab9
rust: introduce `dirstate-tree` cargo feature
Raphaël Gomès <rgomes@octobus.net>
parents:
44904
diff
changeset
|
38 ================ |
e604a3c03ab9
rust: introduce `dirstate-tree` cargo feature
Raphaël Gomès <rgomes@octobus.net>
parents:
44904
diff
changeset
|
39 |
e604a3c03ab9
rust: introduce `dirstate-tree` cargo feature
Raphaël Gomès <rgomes@octobus.net>
parents:
44904
diff
changeset
|
40 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
|
41 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
|
42 |
46140
ec14c37958ec
rust: document how to enable debug information in optimized builds
Simon Sapin <simon.sapin@octobus.net>
parents:
45614
diff
changeset
|
43 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
|
44 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
|
45 |
44904
7ca1d635e4a6
rust: add a pointer for profiling to the README
Valentin Gatien-Baron <valentin.gatienbaron@gmail.com>
parents:
44903
diff
changeset
|
46 Profiling |
7ca1d635e4a6
rust: add a pointer for profiling to the README
Valentin Gatien-Baron <valentin.gatienbaron@gmail.com>
parents:
44903
diff
changeset
|
47 ========= |
7ca1d635e4a6
rust: add a pointer for profiling to the README
Valentin Gatien-Baron <valentin.gatienbaron@gmail.com>
parents:
44903
diff
changeset
|
48 |
7ca1d635e4a6
rust: add a pointer for profiling to the README
Valentin Gatien-Baron <valentin.gatienbaron@gmail.com>
parents:
44903
diff
changeset
|
49 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
|
50 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
|
51 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
|
52 hgignore). |
7ca1d635e4a6
rust: add a pointer for profiling to the README
Valentin Gatien-Baron <valentin.gatienbaron@gmail.com>
parents:
44903
diff
changeset
|
53 |
46140
ec14c37958ec
rust: document how to enable debug information in optimized builds
Simon Sapin <simon.sapin@octobus.net>
parents:
45614
diff
changeset
|
54 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
|
55 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
|
56 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
|
57 (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
|
58 |
ec14c37958ec
rust: document how to enable debug information in optimized builds
Simon Sapin <simon.sapin@octobus.net>
parents:
45614
diff
changeset
|
59 [profile.release] |
ec14c37958ec
rust: document how to enable debug information in optimized builds
Simon Sapin <simon.sapin@octobus.net>
parents:
45614
diff
changeset
|
60 debug = true |
ec14c37958ec
rust: document how to enable debug information in optimized builds
Simon Sapin <simon.sapin@octobus.net>
parents:
45614
diff
changeset
|
61 |
44904
7ca1d635e4a6
rust: add a pointer for profiling to the README
Valentin Gatien-Baron <valentin.gatienbaron@gmail.com>
parents:
44903
diff
changeset
|
62 ``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
|
63 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
|
64 (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
|
65 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
|
66 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
|
67 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
|
68 |
46140
ec14c37958ec
rust: document how to enable debug information in optimized builds
Simon Sapin <simon.sapin@octobus.net>
parents:
45614
diff
changeset
|
69 Example usage: |
ec14c37958ec
rust: document how to enable debug information in optimized builds
Simon Sapin <simon.sapin@octobus.net>
parents:
45614
diff
changeset
|
70 |
ec14c37958ec
rust: document how to enable debug information in optimized builds
Simon Sapin <simon.sapin@octobus.net>
parents:
45614
diff
changeset
|
71 $ 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
|
72 $ 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
|
73 |
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
|
74 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
|
75 =============== |
35569
964212780daf
rust: implementation of `hg`
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
76 |
45614
7bd13bf99d1c
rust: update minimum supported Rust compiler version
Raphaël Gomès <rgomes@octobus.net>
parents:
45609
diff
changeset
|
77 The current version of Rust in use is ``1.41.1``, because it's what Debian |
7bd13bf99d1c
rust: update minimum supported Rust compiler version
Raphaël Gomès <rgomes@octobus.net>
parents:
45609
diff
changeset
|
78 stable has. You can use ``rustup override set 1.41.1`` 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
|
79 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
|
80 |
47f8c741df0f
rust: update the README with more up-to-date and thorough information
Raphaël Gomès <rgomes@octobus.net>
parents:
44115
diff
changeset
|
81 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
|
82 |
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 $ 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
|
84 |
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 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
|
86 |
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 $ cd rust/hg-core |
44115
e1b8b4e4f496
rust: add a README
Valentin Gatien-Baron <valentin.gatienbaron@gmail.com>
parents:
44114
diff
changeset
|
88 |
e1b8b4e4f496
rust: add a README
Valentin Gatien-Baron <valentin.gatienbaron@gmail.com>
parents:
44114
diff
changeset
|
89 Simply run:: |
35569
964212780daf
rust: implementation of `hg`
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
90 |
964212780daf
rust: implementation of `hg`
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
91 $ cargo build --release |
44115
e1b8b4e4f496
rust: add a README
Valentin Gatien-Baron <valentin.gatienbaron@gmail.com>
parents:
44114
diff
changeset
|
92 |
e1b8b4e4f496
rust: add a README
Valentin Gatien-Baron <valentin.gatienbaron@gmail.com>
parents:
44114
diff
changeset
|
93 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
|
94 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
|
95 of magnitude of degradation when removing ``--release``. |
e1b8b4e4f496
rust: add a README
Valentin Gatien-Baron <valentin.gatienbaron@gmail.com>
parents:
44114
diff
changeset
|
96 |
e1b8b4e4f496
rust: add a README
Valentin Gatien-Baron <valentin.gatienbaron@gmail.com>
parents:
44114
diff
changeset
|
97 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
|
98 |
e1b8b4e4f496
rust: add a README
Valentin Gatien-Baron <valentin.gatienbaron@gmail.com>
parents:
44114
diff
changeset
|
99 $ cargo check |
e1b8b4e4f496
rust: add a README
Valentin Gatien-Baron <valentin.gatienbaron@gmail.com>
parents:
44114
diff
changeset
|
100 |
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
|
101 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
|
102 |
47f8c741df0f
rust: update the README with more up-to-date and thorough information
Raphaël Gomès <rgomes@octobus.net>
parents:
44115
diff
changeset
|
103 $ 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
|
104 |
44115
e1b8b4e4f496
rust: add a README
Valentin Gatien-Baron <valentin.gatienbaron@gmail.com>
parents:
44114
diff
changeset
|
105 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
|
106 mercurial as a whole) with:: |
e1b8b4e4f496
rust: add a README
Valentin Gatien-Baron <valentin.gatienbaron@gmail.com>
parents:
44114
diff
changeset
|
107 |
e1b8b4e4f496
rust: add a README
Valentin Gatien-Baron <valentin.gatienbaron@gmail.com>
parents:
44114
diff
changeset
|
108 $ 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
|
109 |
47f8c741df0f
rust: update the README with more up-to-date and thorough information
Raphaël Gomès <rgomes@octobus.net>
parents:
44115
diff
changeset
|
110 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
|
111 ------------------- |
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 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
|
114 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
|
115 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
|
116 |
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 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
|
118 |
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 $ 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
|
120 |
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 This requires you to have the nightly toolchain installed. |