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