rust/README.rst
author Raphaël Gomès <rgomes@octobus.net>
Thu, 16 Apr 2020 17:31:29 +0200
changeset 44714 8dbcd5138102
parent 44607 c13cbc3872c8
child 44929 9f96beb9bafe
permissions -rw-r--r--
rust: update README with new information about the Re2 path Differential Revision: https://phab.mercurial-scm.org/D8452
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
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.
44559
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
44559
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
44559
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
44559
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)
44559
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
44607
c13cbc3872c8 rust: update README to reflect use of `regex` crate
Raphaël Gomès <rgomes@octobus.net>
parents: 44559
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: 44559
diff changeset
    40
-------------------------------
35569
964212780daf rust: implementation of `hg`
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
    41
44559
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
44607
c13cbc3872c8 rust: update README to reflect use of `regex` crate
Raphaël Gomès <rgomes@octobus.net>
parents: 44559
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: 44559
diff changeset
    44
c13cbc3872c8 rust: update README to reflect use of `regex` crate
Raphaël Gomès <rgomes@octobus.net>
parents: 44559
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: 44559
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: 44559
diff changeset
    47
similar enough behavior.
44559
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
44607
c13cbc3872c8 rust: update README to reflect use of `regex` crate
Raphaël Gomès <rgomes@octobus.net>
parents: 44559
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: 44559
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: 44559
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: 44559
diff changeset
    52
c13cbc3872c8 rust: update README to reflect use of `regex` crate
Raphaël Gomès <rgomes@octobus.net>
parents: 44559
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: 44559
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: 44559
diff changeset
    55
c13cbc3872c8 rust: update README to reflect use of `regex` crate
Raphaël Gomès <rgomes@octobus.net>
parents: 44559
diff changeset
    56
If you want to use ``Re2``, you need to install ``Re2`` following Google's 
44714
8dbcd5138102 rust: update README with new information about the Re2 path
Raphaël Gomès <rgomes@octobus.net>
parents: 44607
diff changeset
    57
guidelines: https://github.com/google/re2/wiki/Install.
8dbcd5138102 rust: update README with new information about the Re2 path
Raphaël Gomès <rgomes@octobus.net>
parents: 44607
diff changeset
    58
Then, use ``HG_RUST_FEATURES=with-re2`` and 
8dbcd5138102 rust: update README with new information about the Re2 path
Raphaël Gomès <rgomes@octobus.net>
parents: 44607
diff changeset
    59
``HG_RE2_PATH=system|<path to your re2 install>`` when building ``hg`` to 
8dbcd5138102 rust: update README with new information about the Re2 path
Raphaël Gomès <rgomes@octobus.net>
parents: 44607
diff changeset
    60
signal the use of Re2. Using the local path instead of the "system" RE2 links
8dbcd5138102 rust: update README with new information about the Re2 path
Raphaël Gomès <rgomes@octobus.net>
parents: 44607
diff changeset
    61
it statically.
8dbcd5138102 rust: update README with new information about the Re2 path
Raphaël Gomès <rgomes@octobus.net>
parents: 44607
diff changeset
    62
8dbcd5138102 rust: update README with new information about the Re2 path
Raphaël Gomès <rgomes@octobus.net>
parents: 44607
diff changeset
    63
For example::
8dbcd5138102 rust: update README with new information about the Re2 path
Raphaël Gomès <rgomes@octobus.net>
parents: 44607
diff changeset
    64
8dbcd5138102 rust: update README with new information about the Re2 path
Raphaël Gomès <rgomes@octobus.net>
parents: 44607
diff changeset
    65
  $ HG_RUST_FEATURES=with-re2 HG_RE2_PATH=system make PURE=--rust
8dbcd5138102 rust: update README with new information about the Re2 path
Raphaël Gomès <rgomes@octobus.net>
parents: 44607
diff changeset
    66
  $ # OR
8dbcd5138102 rust: update README with new information about the Re2 path
Raphaël Gomès <rgomes@octobus.net>
parents: 44607
diff changeset
    67
  $ HG_RUST_FEATURES=with-re2 HG_RE2_PATH=/path/to/re2 make PURE=--rust
44559
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
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
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
    70
===============
35569
964212780daf rust: implementation of `hg`
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
    71
44559
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
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
    73
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
    74
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
    75
47f8c741df0f rust: update the README with more up-to-date and thorough information
Raphaël Gomès <rgomes@octobus.net>
parents: 44115
diff changeset
    76
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
    77
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
  $ 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
    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
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
    81
47f8c741df0f rust: update the README with more up-to-date and thorough information
Raphaël Gomès <rgomes@octobus.net>
parents: 44115
diff changeset
    82
  $ cd rust/hg-core
44115
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
Simply run::
35569
964212780daf rust: implementation of `hg`
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
    85
964212780daf rust: implementation of `hg`
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff changeset
    86
   $ cargo build --release
44115
e1b8b4e4f496 rust: add a README
Valentin Gatien-Baron <valentin.gatienbaron@gmail.com>
parents: 44114
diff changeset
    87
e1b8b4e4f496 rust: add a README
Valentin Gatien-Baron <valentin.gatienbaron@gmail.com>
parents: 44114
diff changeset
    88
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
    89
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
    90
of magnitude of degradation when removing ``--release``.
e1b8b4e4f496 rust: add a README
Valentin Gatien-Baron <valentin.gatienbaron@gmail.com>
parents: 44114
diff changeset
    91
e1b8b4e4f496 rust: add a README
Valentin Gatien-Baron <valentin.gatienbaron@gmail.com>
parents: 44114
diff changeset
    92
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
    93
e1b8b4e4f496 rust: add a README
Valentin Gatien-Baron <valentin.gatienbaron@gmail.com>
parents: 44114
diff changeset
    94
  $ cargo check
e1b8b4e4f496 rust: add a README
Valentin Gatien-Baron <valentin.gatienbaron@gmail.com>
parents: 44114
diff changeset
    95
44559
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
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
    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
  $ 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
    99
44115
e1b8b4e4f496 rust: add a README
Valentin Gatien-Baron <valentin.gatienbaron@gmail.com>
parents: 44114
diff changeset
   100
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
   101
mercurial as a whole) with::
e1b8b4e4f496 rust: add a README
Valentin Gatien-Baron <valentin.gatienbaron@gmail.com>
parents: 44114
diff changeset
   102
e1b8b4e4f496 rust: add a README
Valentin Gatien-Baron <valentin.gatienbaron@gmail.com>
parents: 44114
diff changeset
   103
  $ cargo test --all
44559
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
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
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
   106
-------------------
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
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
   109
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
   110
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
   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
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
   113
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
  $ 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
   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
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
   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
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
   119
-------------------
47f8c741df0f rust: update the README with more up-to-date and thorough information
Raphaël Gomès <rgomes@octobus.net>
parents: 44115
diff changeset
   120
47f8c741df0f rust: update the README with more up-to-date and thorough information
Raphaël Gomès <rgomes@octobus.net>
parents: 44115
diff changeset
   121
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
   122
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
   123
47f8c741df0f rust: update the README with more up-to-date and thorough information
Raphaël Gomès <rgomes@octobus.net>
parents: 44115
diff changeset
   124
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
   125
47f8c741df0f rust: update the README with more up-to-date and thorough information
Raphaël Gomès <rgomes@octobus.net>
parents: 44115
diff changeset
   126
  $ 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
   127