Mercurial > hg
annotate rust/README.rst @ 44563:1922694d638f
tests: remove doctest in narrowspec, it is broken
I think every item here is considered incorrect (if we fix doctest to run it),
so let's just delete it.
Differential Revision: https://phab.mercurial-scm.org/D8279
author | Kyle Lippincott <spectral@google.com> |
---|---|
date | Thu, 12 Mar 2020 20:08:05 -0700 |
parents | 47f8c741df0f |
children | c13cbc3872c8 |
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 |
47f8c741df0f
rust: update the README with more up-to-date and thorough information
Raphaël Gomès <rgomes@octobus.net>
parents:
44115
diff
changeset
|
39 Using the full ``hg status`` extension |
47f8c741df0f
rust: update the README with more up-to-date and thorough information
Raphaël Gomès <rgomes@octobus.net>
parents:
44115
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 |
47f8c741df0f
rust: update the README with more up-to-date and thorough information
Raphaël Gomès <rgomes@octobus.net>
parents:
44115
diff
changeset
|
43 all translated into regex. For compatibility and ease of development reasons |
47f8c741df0f
rust: update the README with more up-to-date and thorough information
Raphaël Gomès <rgomes@octobus.net>
parents:
44115
diff
changeset
|
44 the Re2 regex engine is in use until we figure out if the ``regex`` crate has |
47f8c741df0f
rust: update the README with more up-to-date and thorough information
Raphaël Gomès <rgomes@octobus.net>
parents:
44115
diff
changeset
|
45 similar enough behavior. This implies that you need to install ``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
|
46 following Google's guidelines: https://github.com/google/re2/wiki/Install |
47f8c741df0f
rust: update the README with more up-to-date and thorough information
Raphaël Gomès <rgomes@octobus.net>
parents:
44115
diff
changeset
|
47 |
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 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
|
49 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
|
50 |
47f8c741df0f
rust: update the README with more up-to-date and thorough information
Raphaël Gomès <rgomes@octobus.net>
parents:
44115
diff
changeset
|
51 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
|
52 =============== |
35569
964212780daf
rust: implementation of `hg`
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
53 |
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
|
54 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
|
55 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
|
56 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
|
57 |
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 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
|
59 |
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 $ 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
|
61 |
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 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
|
63 |
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 $ cd rust/hg-core |
44115
e1b8b4e4f496
rust: add a README
Valentin Gatien-Baron <valentin.gatienbaron@gmail.com>
parents:
44114
diff
changeset
|
65 |
e1b8b4e4f496
rust: add a README
Valentin Gatien-Baron <valentin.gatienbaron@gmail.com>
parents:
44114
diff
changeset
|
66 Simply run:: |
35569
964212780daf
rust: implementation of `hg`
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
67 |
964212780daf
rust: implementation of `hg`
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
68 $ cargo build --release |
44115
e1b8b4e4f496
rust: add a README
Valentin Gatien-Baron <valentin.gatienbaron@gmail.com>
parents:
44114
diff
changeset
|
69 |
e1b8b4e4f496
rust: add a README
Valentin Gatien-Baron <valentin.gatienbaron@gmail.com>
parents:
44114
diff
changeset
|
70 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
|
71 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
|
72 of magnitude of degradation when removing ``--release``. |
e1b8b4e4f496
rust: add a README
Valentin Gatien-Baron <valentin.gatienbaron@gmail.com>
parents:
44114
diff
changeset
|
73 |
e1b8b4e4f496
rust: add a README
Valentin Gatien-Baron <valentin.gatienbaron@gmail.com>
parents:
44114
diff
changeset
|
74 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
|
75 |
e1b8b4e4f496
rust: add a README
Valentin Gatien-Baron <valentin.gatienbaron@gmail.com>
parents:
44114
diff
changeset
|
76 $ cargo check |
e1b8b4e4f496
rust: add a README
Valentin Gatien-Baron <valentin.gatienbaron@gmail.com>
parents:
44114
diff
changeset
|
77 |
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
|
78 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
|
79 |
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 $ 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
|
81 |
44115
e1b8b4e4f496
rust: add a README
Valentin Gatien-Baron <valentin.gatienbaron@gmail.com>
parents:
44114
diff
changeset
|
82 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
|
83 mercurial as a whole) with:: |
e1b8b4e4f496
rust: add a README
Valentin Gatien-Baron <valentin.gatienbaron@gmail.com>
parents:
44114
diff
changeset
|
84 |
e1b8b4e4f496
rust: add a README
Valentin Gatien-Baron <valentin.gatienbaron@gmail.com>
parents:
44114
diff
changeset
|
85 $ 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
|
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 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
|
88 ------------------- |
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 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
|
91 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
|
92 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
|
93 |
47f8c741df0f
rust: update the README with more up-to-date and thorough information
Raphaël Gomès <rgomes@octobus.net>
parents:
44115
diff
changeset
|
94 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
|
95 |
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 $ 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
|
97 |
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 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
|
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 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
|
101 ------------------- |
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 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
|
104 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
|
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 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
|
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 $ 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
|
109 |