Show More
@@ -1,144 +1,146 b'' | |||||
1 | =================== |
|
1 | =================== | |
2 | Mercurial Rust Code |
|
2 | Mercurial Rust Code | |
3 | =================== |
|
3 | =================== | |
4 |
|
4 | |||
5 | This directory contains various Rust code for the Mercurial project. |
|
5 | This directory contains various Rust code for the Mercurial project. | |
6 | Rust is not required to use (or build) Mercurial, but using it |
|
6 | Rust is not required to use (or build) Mercurial, but using it | |
7 | improves performance in some areas. |
|
7 | improves performance in some areas. | |
8 |
|
8 | |||
9 | There are currently four independent Rust projects: |
|
9 | There are currently four independent Rust projects: | |
10 |
|
10 | |||
11 | - chg. An implementation of chg, in Rust instead of C. |
|
11 | - chg. An implementation of chg, in Rust instead of C. | |
12 | - hgcli. A project that provides a (mostly) self-contained "hg" binary, |
|
12 | - hgcli. A project that provides a (mostly) self-contained "hg" binary, | |
13 | for ease of deployment and a bit of speed, using PyOxidizer. See |
|
13 | for ease of deployment and a bit of speed, using PyOxidizer. See | |
14 | ``hgcli/README.md``. |
|
14 | ``hgcli/README.md``. | |
15 | - hg-core (and hg-cpython): implementation of some |
|
15 | - hg-core (and hg-cpython): implementation of some | |
16 | functionality of mercurial in Rust, e.g. ancestry computations in |
|
16 | functionality of mercurial in Rust, e.g. ancestry computations in | |
17 | revision graphs, status or pull discovery. The top-level ``Cargo.toml`` file |
|
17 | revision graphs, status or pull discovery. The top-level ``Cargo.toml`` file | |
18 | defines a workspace containing these crates. |
|
18 | defines a workspace containing these crates. | |
19 | - rhg: a pure Rust implementation of Mercurial, with a fallback mechanism for |
|
19 | - rhg: a pure Rust implementation of Mercurial, with a fallback mechanism for | |
20 | unsupported invocations. It reuses the logic ``hg-core`` but |
|
20 | unsupported invocations. It reuses the logic ``hg-core`` but | |
21 | completely forgoes interaction with Python. See |
|
21 | completely forgoes interaction with Python. See | |
22 | ``rust/rhg/README.md`` for more details. |
|
22 | ``rust/rhg/README.md`` for more details. | |
23 |
|
23 | |||
24 | Using Rust code |
|
24 | Using Rust code | |
25 | =============== |
|
25 | =============== | |
26 |
|
26 | |||
27 | Local use (you need to clean previous build artifacts if you have |
|
27 | Local use (you need to clean previous build artifacts if you have | |
28 | built without rust previously):: |
|
28 | built without rust previously):: | |
29 |
|
29 | |||
30 | $ make PURE=--rust local # to use ./hg |
|
30 | $ make PURE=--rust local # to use ./hg | |
31 | $ ./tests/run-tests.py --rust # to run all tests |
|
31 | $ ./tests/run-tests.py --rust # to run all tests | |
32 | $ ./hg debuginstall | grep -i rust # to validate rust is in use |
|
32 | $ ./hg debuginstall | grep -i rust # to validate rust is in use | |
33 | checking Rust extensions (installed) |
|
33 | checking Rust extensions (installed) | |
34 | checking module policy (rust+c-allow) |
|
34 | checking module policy (rust+c-allow) | |
35 |
|
35 | |||
36 | If the environment variable ``HGWITHRUSTEXT=cpython`` is set, the Rust |
|
36 | If the environment variable ``HGWITHRUSTEXT=cpython`` is set, the Rust | |
37 | extension will be used by default unless ``--no-rust``. |
|
37 | extension will be used by default unless ``--no-rust``. | |
38 |
|
38 | |||
39 | One day we may use this environment variable to switch to new experimental |
|
39 | One day we may use this environment variable to switch to new experimental | |
40 | binding crates like a hypothetical ``HGWITHRUSTEXT=hpy``. |
|
40 | binding crates like a hypothetical ``HGWITHRUSTEXT=hpy``. | |
41 |
|
41 | |||
42 | Special features |
|
42 | Special features | |
43 | ================ |
|
43 | ================ | |
44 |
|
44 | |||
45 | In the future, compile-time opt-ins may be added |
|
45 | In the future, compile-time opt-ins may be added | |
46 | to the ``features`` section in ``hg-cpython/Cargo.toml``. |
|
46 | to the ``features`` section in ``hg-cpython/Cargo.toml``. | |
47 |
|
47 | |||
48 | To use features from the Makefile, use the ``HG_RUST_FEATURES`` environment |
|
48 | To use features from the Makefile, use the ``HG_RUST_FEATURES`` environment | |
49 | variable: for instance ``HG_RUST_FEATURES="some-feature other-feature"``. |
|
49 | variable: for instance ``HG_RUST_FEATURES="some-feature other-feature"``. | |
50 |
|
50 | |||
51 | Profiling |
|
51 | Profiling | |
52 | ========= |
|
52 | ========= | |
53 |
|
53 | |||
54 | Setting the environment variable ``RUST_LOG=trace`` will make hg print |
|
54 | Setting the environment variable ``RUST_LOG=trace`` will make hg print | |
55 | a few high level rust-related performance numbers. It can also |
|
55 | a few high level rust-related performance numbers. It can also | |
56 | indicate why the rust code cannot be used (say, using lookarounds in |
|
56 | indicate why the rust code cannot be used (say, using lookarounds in | |
57 | hgignore). |
|
57 | hgignore). | |
58 |
|
58 | |||
59 | Creating a ``.cargo/config`` file with the following content enables |
|
59 | Creating a ``.cargo/config`` file with the following content enables | |
60 | debug information in optimized builds. This make profiles more informative |
|
60 | debug information in optimized builds. This make profiles more informative | |
61 | with source file name and line number for Rust stack frames and |
|
61 | with source file name and line number for Rust stack frames and | |
62 | (in some cases) stack frames for Rust functions that have been inlined:: |
|
62 | (in some cases) stack frames for Rust functions that have been inlined:: | |
63 |
|
63 | |||
64 | [profile.release] |
|
64 | [profile.release] | |
65 | debug = true |
|
65 | debug = true | |
66 |
|
66 | |||
67 | ``py-spy`` (https://github.com/benfred/py-spy) can be used to |
|
67 | ``py-spy`` (https://github.com/benfred/py-spy) can be used to | |
68 | construct a single profile with rust functions and python functions |
|
68 | construct a single profile with rust functions and python functions | |
69 | (as opposed to ``hg --profile``, which attributes time spent in rust |
|
69 | (as opposed to ``hg --profile``, which attributes time spent in rust | |
70 | to some unlucky python code running shortly after the rust code, and |
|
70 | to some unlucky python code running shortly after the rust code, and | |
71 | as opposed to tools for native code like ``perf``, which attribute |
|
71 | as opposed to tools for native code like ``perf``, which attribute | |
72 | time to the python interpreter instead of python functions). |
|
72 | time to the python interpreter instead of python functions). | |
73 |
|
73 | |||
74 | Example usage:: |
|
74 | Example usage:: | |
75 |
|
75 | |||
76 | $ make PURE=--rust local # Don't forget to recompile after a code change |
|
76 | $ make PURE=--rust local # Don't forget to recompile after a code change | |
77 | $ py-spy record --native --output /tmp/profile.svg -- ./hg ... |
|
77 | $ py-spy record --native --output /tmp/profile.svg -- ./hg ... | |
78 |
|
78 | |||
79 | Developing Rust |
|
79 | Developing Rust | |
80 | =============== |
|
80 | =============== | |
81 |
|
81 | |||
82 | The current version of Rust in use is ``1.61.0``, because it's what Debian |
|
82 | The current version of Rust in use is ``1.61.0``, because it's what Debian | |
83 | testing has. You can use ``rustup override set 1.61.0`` at the root of the repo |
|
83 | testing has. You can use ``rustup override set 1.61.0`` at the root of the repo | |
84 | to make it easier on you. |
|
84 | to make it easier on you. | |
85 |
|
85 | |||
86 | Go to the ``hg-cpython`` folder:: |
|
86 | Go to the ``hg-cpython`` folder:: | |
87 |
|
87 | |||
88 | $ cd rust/hg-cpython |
|
88 | $ cd rust/hg-cpython | |
89 |
|
89 | |||
90 | Or, only the ``hg-core`` folder. Be careful not to break compatibility:: |
|
90 | Or, only the ``hg-core`` folder. Be careful not to break compatibility:: | |
91 |
|
91 | |||
92 | $ cd rust/hg-core |
|
92 | $ cd rust/hg-core | |
93 |
|
93 | |||
94 | Simply run:: |
|
94 | Simply run:: | |
95 |
|
95 | |||
96 | $ cargo build --release |
|
96 | $ cargo build --release | |
97 |
|
97 | |||
98 | It is possible to build without ``--release``, but it is not |
|
98 | It is possible to build without ``--release``, but it is not | |
99 | recommended if performance is of any interest: there can be an order |
|
99 | recommended if performance is of any interest: there can be an order | |
100 | of magnitude of degradation when removing ``--release``. |
|
100 | of magnitude of degradation when removing ``--release``. | |
101 |
|
101 | |||
102 | For faster builds, you may want to skip code generation:: |
|
102 | For faster builds, you may want to skip code generation:: | |
103 |
|
103 | |||
104 | $ cargo check |
|
104 | $ cargo check | |
105 |
|
105 | |||
106 | For even faster typing:: |
|
106 | For even faster typing:: | |
107 |
|
107 | |||
108 | $ cargo c |
|
108 | $ cargo c | |
109 |
|
109 | |||
110 | You can run only the rust-specific tests (as opposed to tests of |
|
110 | You can run only the rust-specific tests (as opposed to tests of | |
111 | mercurial as a whole) with:: |
|
111 | mercurial as a whole) with:: | |
112 |
|
112 | |||
113 | $ cargo test --all |
|
113 | $ cargo test --all | |
114 |
|
114 | |||
115 | Formatting the code |
|
115 | Formatting the code | |
116 | ------------------- |
|
116 | ------------------- | |
117 |
|
117 | |||
118 | We use ``rustfmt`` to keep the code formatted at all times. For now, we are |
|
118 | We use ``rustfmt`` to keep the code formatted at all times. For now, we are | |
119 | using the nightly version because it has been stable enough and provides |
|
119 | using the nightly version because it has been stable enough and provides | |
120 | comment folding. |
|
120 | comment folding. | |
121 |
|
121 | |||
122 | To format the entire Rust workspace:: |
|
122 | Our CI enforces that the code does not need reformatting. Before | |
|
123 | submitting your changes, please format the entire Rust workspace by running:: | |||
|
124 | ||||
123 |
|
125 | |||
124 | $ cargo +nightly fmt |
|
126 | $ cargo +nightly fmt | |
125 |
|
127 | |||
126 | This requires you to have the nightly toolchain installed. |
|
128 | This requires you to have the nightly toolchain installed. | |
127 |
|
129 | |||
128 | Linting: code sanity |
|
130 | Linting: code sanity | |
129 | -------------------- |
|
131 | -------------------- | |
130 |
|
132 | |||
131 | We're using `Clippy`_, the standard code diagnosis tool of the Rust |
|
133 | We're using `Clippy`_, the standard code diagnosis tool of the Rust | |
132 | community. |
|
134 | community. | |
133 |
|
135 | |||
134 | Our CI enforces that the code is free of Clippy warnings, so you might |
|
136 | Our CI enforces that the code is free of Clippy warnings, so you might | |
135 | want to run it on your side before submitting your changes. Simply do:: |
|
137 | want to run it on your side before submitting your changes. Simply do:: | |
136 |
|
138 | |||
137 | % cargo clippy |
|
139 | % cargo clippy | |
138 |
|
140 | |||
139 | from the top of the Rust workspace. Clippy is part of the default |
|
141 | from the top of the Rust workspace. Clippy is part of the default | |
140 | ``rustup`` install, so it should work right away. In case it would |
|
142 | ``rustup`` install, so it should work right away. In case it would | |
141 | not, you can install it with ``rustup component add``. |
|
143 | not, you can install it with ``rustup component add``. | |
142 |
|
144 | |||
143 |
|
145 | |||
144 | .. _Clippy: https://doc.rust-lang.org/stable/clippy/ |
|
146 | .. _Clippy: https://doc.rust-lang.org/stable/clippy/ |
General Comments 0
You need to be logged in to leave comments.
Login now