annotate rust/hgcli/README.md @ 49491:c6a1beba27e9

bisect: avoid copying ancestor list for non-merge commits

During a bisection, hg needs to compute a list of all ancestors for every
candidate commit. This is accomplished via a bottom-up traversal of the set of
candidates, during which each revision's ancestor list is populated using the
ancestor list of its parent(s). Previously, this involved copying the entire
list, which could be very long in if the bisection range was large.

To help improve this, we can observe that each candidate commit is visited
exactly once, at which point its ancestor list is copied into its children's
lists and then dropped. In the case of non-merge commits, a commit's ancestor
list consists exactly of its parent's list plus itself. This means that we can
trivially reuse the parent's existing list for one of its non-merge children,
which avoids copying entirely if that commit is the parent's only child. This
makes bisections over linear ranges of commits much faster.

During some informal testing in the large publicly-available `mozilla-central`
repository, this noticeably sped up bisections over large ranges of history:

Setup:
  $ cd mozilla-central
  $ hg bisect --reset
  $ hg bisect --good 0
  $ hg log -r tip -T '{rev}\n'
  628417

Test:
  $ time hg bisect --bad tip --noupdate

Before:
  real    3m35.927s
  user    3m35.553s
  sys     0m0.319s

After:
  real    1m41.142s
  user    1m40.810s
  sys     0m0.285s

# Oxidized Mercurial

This project provides a Rust implementation of the Mercurial (`hg`)
version control tool.

Under the hood, the project uses
[PyOxidizer](https://github.com/indygreg/PyOxidizer) to embed a Python
interpreter in a binary built with Rust. At run-time, the Rust `fn main()`
is called and Rust code handles initial process startup. An in-process
Python interpreter is started (if needed) to provide additional
functionality.

# Building

First, acquire and build a copy of PyOxidizer; you probably want to do this in
some directory outside of your clone of Mercurial:

    $ git clone https://github.com/indygreg/PyOxidizer.git
    $ cd PyOxidizer
    $ cargo build --release

Then build this Rust project using the built `pyoxidizer` executable:

    $ /path/to/pyoxidizer/target/release/pyoxidizer build --release

If all goes according to plan, there should be an assembled application
under `build/<arch>/release/app/` with an `hg` executable:

    $ build/x86_64-unknown-linux-gnu/release/app/hg version
    Mercurial Distributed SCM (version 5.3.1+433-f99cd77d53dc+20200331)
    (see https://mercurial-scm.org for more information)

    Copyright (C) 2005-2020 Olivia Mackall and others
    This is free software; see the source for copying conditions. There is NO
    warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

# Running Tests

To run tests with a built `hg` executable, you can use the `--with-hg`
argument to `run-tests.py`. But there's a wrinkle: many tests run custom
Python scripts that need to `import` modules provided by Mercurial. Since
these modules are embedded in the produced `hg` executable, a regular
Python interpreter can't access them! To work around this, set `PYTHONPATH`
to the Mercurial source directory. e.g.:

    $ cd /path/to/hg/src/tests
    $ PYTHONPATH=`pwd`/.. python3.9 run-tests.py \
        --with-hg `pwd`/../rust/hgcli/build/x86_64-unknown-linux-gnu/release/app/hg