##// END OF EJS Templates
rust: update README with new information about the Re2 path...
Raphaël Gomès -
r45208:8dbcd513 default
parent child Browse files
Show More
@@ -1,119 +1,127 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 three independent rust projects:
9 There are currently three independent rust projects:
10 - chg. An implementation of chg, in rust instead of C.
10 - chg. An implementation of chg, in rust instead of C.
11 - hgcli. A experiment for starting hg in rust rather than in python,
11 - hgcli. A experiment for starting hg in rust rather than in python,
12 by linking with the python runtime. Probably meant to be replaced by
12 by linking with the python runtime. Probably meant to be replaced by
13 PyOxidizer at some point.
13 PyOxidizer at some point.
14 - hg-core (and hg-cpython): implementation of some
14 - hg-core (and hg-cpython): implementation of some
15 functionality of mercurial in rust, e.g. ancestry computations 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
18
19 Using Rust code
19 Using Rust code
20 ===============
20 ===============
21
21
22 Local use (you need to clean previous build artifacts if you have
22 Local use (you need to clean previous build artifacts if you have
23 built without rust previously)::
23 built without rust previously)::
24
24
25 $ make PURE=--rust local # to use ./hg
25 $ make PURE=--rust local # to use ./hg
26 $ ./tests/run-tests.py --rust # to run all tests
26 $ ./tests/run-tests.py --rust # to run all tests
27 $ ./hg debuginstall | grep -i rust # to validate rust is in use
27 $ ./hg debuginstall | grep -i rust # to validate rust is in use
28 checking Rust extensions (installed)
28 checking Rust extensions (installed)
29 checking module policy (rust+c-allow)
29 checking module policy (rust+c-allow)
30 checking "re2" regexp engine Rust bindings (installed)
30 checking "re2" regexp engine Rust bindings (installed)
31
31
32
32
33 If the environment variable ``HGWITHRUSTEXT=cpython`` is set, the Rust
33 If the environment variable ``HGWITHRUSTEXT=cpython`` is set, the Rust
34 extension will be used by default unless ``--no-rust``.
34 extension will be used by default unless ``--no-rust``.
35
35
36 One day we may use this environment variable to switch to new experimental
36 One day we may use this environment variable to switch to new experimental
37 binding crates like a hypothetical ``HGWITHRUSTEXT=hpy``.
37 binding crates like a hypothetical ``HGWITHRUSTEXT=hpy``.
38
38
39 Using the fastest ``hg status``
39 Using the fastest ``hg status``
40 -------------------------------
40 -------------------------------
41
41
42 The code for ``hg status`` needs to conform to ``.hgignore`` rules, which are
42 The code for ``hg status`` needs to conform to ``.hgignore`` rules, which are
43 all translated into regex.
43 all translated into regex.
44
44
45 In the first version, for compatibility and ease of development reasons, the
45 In the first version, for compatibility and ease of development reasons, the
46 Re2 regex engine was chosen until we figured out if the ``regex`` crate had
46 Re2 regex engine was chosen until we figured out if the ``regex`` crate had
47 similar enough behavior.
47 similar enough behavior.
48
48
49 Now that that work has been done, the default behavior is to use the ``regex``
49 Now that that work has been done, the default behavior is to use the ``regex``
50 crate, that provides a significant performance boost compared to the standard
50 crate, that provides a significant performance boost compared to the standard
51 Python + C path in many commands such as ``status``, ``diff`` and ``commit``,
51 Python + C path in many commands such as ``status``, ``diff`` and ``commit``,
52
52
53 However, the ``Re2`` path remains slightly faster for our use cases and remains
53 However, the ``Re2`` path remains slightly faster for our use cases and remains
54 a better option for getting the most speed out of your Mercurial.
54 a better option for getting the most speed out of your Mercurial.
55
55
56 If you want to use ``Re2``, you need to install ``Re2`` following Google's
56 If you want to use ``Re2``, you need to install ``Re2`` following Google's
57 guidelines: https://github.com/google/re2/wiki/Install
57 guidelines: https://github.com/google/re2/wiki/Install.
58 Then, use ``HG_RUST_FEATURES=with-re2`` when building ``hg`` to use the full
58 Then, use ``HG_RUST_FEATURES=with-re2`` and
59 status code.
59 ``HG_RE2_PATH=system|<path to your re2 install>`` when building ``hg`` to
60 signal the use of Re2. Using the local path instead of the "system" RE2 links
61 it statically.
62
63 For example::
64
65 $ HG_RUST_FEATURES=with-re2 HG_RE2_PATH=system make PURE=--rust
66 $ # OR
67 $ HG_RUST_FEATURES=with-re2 HG_RE2_PATH=/path/to/re2 make PURE=--rust
60
68
61 Developing Rust
69 Developing Rust
62 ===============
70 ===============
63
71
64 The current version of Rust in use is ``1.34.2``, because it's what Debian
72 The current version of Rust in use is ``1.34.2``, because it's what Debian
65 stable has. You can use ``rustup override set 1.34.2`` at the root of the repo
73 stable has. You can use ``rustup override set 1.34.2`` at the root of the repo
66 to make it easier on you.
74 to make it easier on you.
67
75
68 Go to the ``hg-cpython`` folder::
76 Go to the ``hg-cpython`` folder::
69
77
70 $ cd rust/hg-cpython
78 $ cd rust/hg-cpython
71
79
72 Or, only the ``hg-core`` folder. Be careful not to break compatibility::
80 Or, only the ``hg-core`` folder. Be careful not to break compatibility::
73
81
74 $ cd rust/hg-core
82 $ cd rust/hg-core
75
83
76 Simply run::
84 Simply run::
77
85
78 $ cargo build --release
86 $ cargo build --release
79
87
80 It is possible to build without ``--release``, but it is not
88 It is possible to build without ``--release``, but it is not
81 recommended if performance is of any interest: there can be an order
89 recommended if performance is of any interest: there can be an order
82 of magnitude of degradation when removing ``--release``.
90 of magnitude of degradation when removing ``--release``.
83
91
84 For faster builds, you may want to skip code generation::
92 For faster builds, you may want to skip code generation::
85
93
86 $ cargo check
94 $ cargo check
87
95
88 For even faster typing::
96 For even faster typing::
89
97
90 $ cargo c
98 $ cargo c
91
99
92 You can run only the rust-specific tests (as opposed to tests of
100 You can run only the rust-specific tests (as opposed to tests of
93 mercurial as a whole) with::
101 mercurial as a whole) with::
94
102
95 $ cargo test --all
103 $ cargo test --all
96
104
97 Formatting the code
105 Formatting the code
98 -------------------
106 -------------------
99
107
100 We use ``rustfmt`` to keep the code formatted at all times. For now, we are
108 We use ``rustfmt`` to keep the code formatted at all times. For now, we are
101 using the nightly version because it has been stable enough and provides
109 using the nightly version because it has been stable enough and provides
102 comment folding.
110 comment folding.
103
111
104 To format the entire Rust workspace::
112 To format the entire Rust workspace::
105
113
106 $ cargo +nightly fmt
114 $ cargo +nightly fmt
107
115
108 This requires you to have the nightly toolchain installed.
116 This requires you to have the nightly toolchain installed.
109
117
110 Additional features
118 Additional features
111 -------------------
119 -------------------
112
120
113 As mentioned in the section about ``hg status``, code paths using ``re2`` are
121 As mentioned in the section about ``hg status``, code paths using ``re2`` are
114 opt-in.
122 opt-in.
115
123
116 For example::
124 For example::
117
125
118 $ cargo check --features with-re2
126 $ cargo check --features with-re2
119
127
General Comments 0
You need to be logged in to leave comments. Login now