Mercurial > hg
annotate rust/README.rst @ 44708:61134a232d00
manifest: leave a TODO where we may have more work for sha1 portability
Differential Revision: https://phab.mercurial-scm.org/D8375
author | Augie Fackler <augie@google.com> |
---|---|
date | Thu, 02 Apr 2020 16:02:21 -0400 |
parents | c13cbc3872c8 |
children | 8dbcd5138102 |
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. |
e1b8b4e4f496
rust: add a README
Valentin Gatien-Baron <valentin.gatienbaron@gmail.com>
parents:
44114
diff
changeset
|
11 - hgcli. A experiment for starting hg in rust rather than in python, |
e1b8b4e4f496
rust: add a README
Valentin Gatien-Baron <valentin.gatienbaron@gmail.com>
parents:
44114
diff
changeset
|
12 by linking with the python runtime. Probably meant to be replaced by |
e1b8b4e4f496
rust: add a README
Valentin Gatien-Baron <valentin.gatienbaron@gmail.com>
parents:
44114
diff
changeset
|
13 PyOxidizer at some point. |
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 checking "re2" regexp engine Rust bindings (installed) |
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 |
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 |
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 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
|
34 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
|
35 |
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 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
|
37 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
|
38 |
44600
c13cbc3872c8
rust: update README to reflect use of `regex` crate
Raphaël Gomès <rgomes@octobus.net>
parents:
44549
diff
changeset
|
39 Using the fastest ``hg status`` |
c13cbc3872c8
rust: update README to reflect use of `regex` crate
Raphaël Gomès <rgomes@octobus.net>
parents:
44549
diff
changeset
|
40 ------------------------------- |
35569
964212780daf
rust: implementation of `hg`
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
41 |
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
|
42 The code for ``hg status`` needs to conform to ``.hgignore`` rules, which are |
44600
c13cbc3872c8
rust: update README to reflect use of `regex` crate
Raphaël Gomès <rgomes@octobus.net>
parents:
44549
diff
changeset
|
43 all translated into regex. |
c13cbc3872c8
rust: update README to reflect use of `regex` crate
Raphaël Gomès <rgomes@octobus.net>
parents:
44549
diff
changeset
|
44 |
c13cbc3872c8
rust: update README to reflect use of `regex` crate
Raphaël Gomès <rgomes@octobus.net>
parents:
44549
diff
changeset
|
45 In the first version, for compatibility and ease of development reasons, the |
c13cbc3872c8
rust: update README to reflect use of `regex` crate
Raphaël Gomès <rgomes@octobus.net>
parents:
44549
diff
changeset
|
46 Re2 regex engine was chosen until we figured out if the ``regex`` crate had |
c13cbc3872c8
rust: update README to reflect use of `regex` crate
Raphaël Gomès <rgomes@octobus.net>
parents:
44549
diff
changeset
|
47 similar enough behavior. |
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
|
48 |
44600
c13cbc3872c8
rust: update README to reflect use of `regex` crate
Raphaël Gomès <rgomes@octobus.net>
parents:
44549
diff
changeset
|
49 Now that that work has been done, the default behavior is to use the ``regex`` |
c13cbc3872c8
rust: update README to reflect use of `regex` crate
Raphaël Gomès <rgomes@octobus.net>
parents:
44549
diff
changeset
|
50 crate, that provides a significant performance boost compared to the standard |
c13cbc3872c8
rust: update README to reflect use of `regex` crate
Raphaël Gomès <rgomes@octobus.net>
parents:
44549
diff
changeset
|
51 Python + C path in many commands such as ``status``, ``diff`` and ``commit``, |
c13cbc3872c8
rust: update README to reflect use of `regex` crate
Raphaël Gomès <rgomes@octobus.net>
parents:
44549
diff
changeset
|
52 |
c13cbc3872c8
rust: update README to reflect use of `regex` crate
Raphaël Gomès <rgomes@octobus.net>
parents:
44549
diff
changeset
|
53 However, the ``Re2`` path remains slightly faster for our use cases and remains |
c13cbc3872c8
rust: update README to reflect use of `regex` crate
Raphaël Gomès <rgomes@octobus.net>
parents:
44549
diff
changeset
|
54 a better option for getting the most speed out of your Mercurial. |
c13cbc3872c8
rust: update README to reflect use of `regex` crate
Raphaël Gomès <rgomes@octobus.net>
parents:
44549
diff
changeset
|
55 |
c13cbc3872c8
rust: update README to reflect use of `regex` crate
Raphaël Gomès <rgomes@octobus.net>
parents:
44549
diff
changeset
|
56 If you want to use ``Re2``, you need to install ``Re2`` following Google's |
c13cbc3872c8
rust: update README to reflect use of `regex` crate
Raphaël Gomès <rgomes@octobus.net>
parents:
44549
diff
changeset
|
57 guidelines: https://github.com/google/re2/wiki/Install |
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
|
58 Then, use ``HG_RUST_FEATURES=with-re2`` when building ``hg`` to use the full |
47f8c741df0f
rust: update the README with more up-to-date and thorough information
Raphaël Gomès <rgomes@octobus.net>
parents:
44115
diff
changeset
|
59 status 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
|
60 |
47f8c741df0f
rust: update the README with more up-to-date and thorough information
Raphaël Gomès <rgomes@octobus.net>
parents:
44115
diff
changeset
|
61 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
|
62 =============== |
35569
964212780daf
rust: implementation of `hg`
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
63 |
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
|
64 The current version of Rust in use is ``1.34.2``, because it's what Debian |
47f8c741df0f
rust: update the README with more up-to-date and thorough information
Raphaël Gomès <rgomes@octobus.net>
parents:
44115
diff
changeset
|
65 stable has. You can use ``rustup override set 1.34.2`` at the root of the repo |
47f8c741df0f
rust: update the README with more up-to-date and thorough information
Raphaël Gomès <rgomes@octobus.net>
parents:
44115
diff
changeset
|
66 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
|
67 |
47f8c741df0f
rust: update the README with more up-to-date and thorough information
Raphaël Gomès <rgomes@octobus.net>
parents:
44115
diff
changeset
|
68 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
|
69 |
47f8c741df0f
rust: update the README with more up-to-date and thorough information
Raphaël Gomès <rgomes@octobus.net>
parents:
44115
diff
changeset
|
70 $ 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
|
71 |
47f8c741df0f
rust: update the README with more up-to-date and thorough information
Raphaël Gomès <rgomes@octobus.net>
parents:
44115
diff
changeset
|
72 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
|
73 |
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 $ cd rust/hg-core |
44115
e1b8b4e4f496
rust: add a README
Valentin Gatien-Baron <valentin.gatienbaron@gmail.com>
parents:
44114
diff
changeset
|
75 |
e1b8b4e4f496
rust: add a README
Valentin Gatien-Baron <valentin.gatienbaron@gmail.com>
parents:
44114
diff
changeset
|
76 Simply run:: |
35569
964212780daf
rust: implementation of `hg`
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
77 |
964212780daf
rust: implementation of `hg`
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
78 $ cargo build --release |
44115
e1b8b4e4f496
rust: add a README
Valentin Gatien-Baron <valentin.gatienbaron@gmail.com>
parents:
44114
diff
changeset
|
79 |
e1b8b4e4f496
rust: add a README
Valentin Gatien-Baron <valentin.gatienbaron@gmail.com>
parents:
44114
diff
changeset
|
80 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
|
81 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
|
82 of magnitude of degradation when removing ``--release``. |
e1b8b4e4f496
rust: add a README
Valentin Gatien-Baron <valentin.gatienbaron@gmail.com>
parents:
44114
diff
changeset
|
83 |
e1b8b4e4f496
rust: add a README
Valentin Gatien-Baron <valentin.gatienbaron@gmail.com>
parents:
44114
diff
changeset
|
84 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
|
85 |
e1b8b4e4f496
rust: add a README
Valentin Gatien-Baron <valentin.gatienbaron@gmail.com>
parents:
44114
diff
changeset
|
86 $ cargo check |
e1b8b4e4f496
rust: add a README
Valentin Gatien-Baron <valentin.gatienbaron@gmail.com>
parents:
44114
diff
changeset
|
87 |
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
|
88 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
|
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 $ 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
|
91 |
44115
e1b8b4e4f496
rust: add a README
Valentin Gatien-Baron <valentin.gatienbaron@gmail.com>
parents:
44114
diff
changeset
|
92 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
|
93 mercurial as a whole) with:: |
e1b8b4e4f496
rust: add a README
Valentin Gatien-Baron <valentin.gatienbaron@gmail.com>
parents:
44114
diff
changeset
|
94 |
e1b8b4e4f496
rust: add a README
Valentin Gatien-Baron <valentin.gatienbaron@gmail.com>
parents:
44114
diff
changeset
|
95 $ 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
|
96 |
47f8c741df0f
rust: update the README with more up-to-date and thorough information
Raphaël Gomès <rgomes@octobus.net>
parents:
44115
diff
changeset
|
97 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
|
98 ------------------- |
47f8c741df0f
rust: update the README with more up-to-date and thorough information
Raphaël Gomès <rgomes@octobus.net>
parents:
44115
diff
changeset
|
99 |
47f8c741df0f
rust: update the README with more up-to-date and thorough information
Raphaël Gomès <rgomes@octobus.net>
parents:
44115
diff
changeset
|
100 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
|
101 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
|
102 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
|
103 |
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 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
|
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 +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
|
107 |
47f8c741df0f
rust: update the README with more up-to-date and thorough information
Raphaël Gomès <rgomes@octobus.net>
parents:
44115
diff
changeset
|
108 This requires you to have the nightly toolchain installed. |
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 Additional features |
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 As mentioned in the section about ``hg status``, code paths using ``re2`` 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 opt-in. |
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 For example:: |
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 |
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 $ cargo check --features with-re2 |
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 |