upstream/mercurial-mirror Files · rust/README.rst

rust-cpython: add macro for sharing references...

rust-cpython: add macro for sharing references Following an experiment done by Georges Racinet, we now have a working way of sharing references between Python and Rust. This is needed in many points of the codebase, for example every time we need to expose an iterator to a Rust-backed Python class. In a few words, references are (unsafely) marked as `'static` and coupled with manual reference counting; we are doing manual borrow-checking. This changes introduces two declarative macro to help reduce boilerplate. While it is better than not using macros, they are not perfect. They need to: - Integrate with the garbage collector for container types (not needed as of yet), as stated in the docstring - Allow for leaking multiple attributes at the same time - Inject the `py_shared_state` data attribute in `py_class`-generated structs - Automatically namespace the functions and attributes they generate For at least the last two points, we will need to write a procedural macro instead of a declarative one. While this reference-sharing mechanism is being ironed out I thought it best not to implement it yet. Lastly, and implementation detail renders our Rust-backed Python iterators too strict to be proper drop-in replacements, as will be illustrated in a future patch: if the data structure referenced by a non-depleted iterator is mutated, an `AlreadyBorrowed` exception is raised, whereas Python would allow it, only to raise a `RuntimeError` if `next` is called on said iterator. This will have to be addressed at some point. Differential Revision: https://phab.mercurial-scm.org/D6631

Gregory Szorc - - Load All Authors

File last commit:

r35587:96421278 default


                r42997:30320c7b

default

Download file

             README.rst
        
                    78 lines
            
             | 2.2 KiB
            
                | text/x-rst
            
             |
                RstLexer
            
             / rust / README.rst
          
                    History
                
                 |
                  Source
                 | Raw
                 |Copy content
                 |Copy permalink

        Gregory Szorc
    
rust: implementation of `hg`...

              r35587
            
      ===================

      Mercurial Rust Code

      ===================

      This directory contains various Rust code for the Mercurial project.

      The top-level ``Cargo.toml`` file defines a workspace containing

      all primary Mercurial crates.

      Building

      ========

      To build the Rust components::

         $ cargo build

      If you prefer a non-debug / release configuration::

         $ cargo build --release

      Features

      --------

      The following Cargo features are available:

      localdev (default)

         Produce files that work with an in-source-tree build.

         In this mode, the build finds and uses a ``python2.7`` binary from

         ``PATH``. The ``hg`` binary assumes it runs from ``rust/target/<target>hg``

         and it finds Mercurial files at ``dirname($0)/../../../``.

      Build Mechanism

      ---------------

      The produced ``hg`` binary is *bound* to a CPython installation. The

      binary links against and loads a CPython library that is discovered

      at build time (by a ``build.rs`` Cargo build script). The Python

      standard library defined by this CPython installation is also used.

      Finding the appropriate CPython installation to use is done by

      the ``python27-sys`` crate's ``build.rs``. Its search order is::

      1. ``PYTHON_SYS_EXECUTABLE`` environment variable.

      2. ``python`` executable on ``PATH``

      3. ``python2`` executable on ``PATH``

      4. ``python2.7`` executable on ``PATH``

      Additional verification of the found Python will be performed by our

      ``build.rs`` to ensure it meets Mercurial's requirements.

      Details about the build-time configured Python are built into the

      produced ``hg`` binary. This means that a built ``hg`` binary is only

      suitable for a specific, well-defined role. These roles are controlled

      by Cargo features (see above).

      Running

      =======

      The ``hgcli`` crate produces an ``hg`` binary. You can run this binary

      via ``cargo run``::

         $ cargo run --manifest-path hgcli/Cargo.toml

      Or directly::

         $ target/debug/hg

         $ target/release/hg

      You can also run the test harness with this binary::

         $ ./run-tests.py --with-hg ../rust/target/debug/hg

      .. note::

         Integration with the test harness is still preliminary. Remember to

         ``cargo build`` after changes because the test harness doesn't yet

         automatically build Rust code.

	Site-wide shortcuts
/	Use quick search box
g h	Goto home page
g g	Goto my private gists page
g G	Goto my public gists page
g 0-9	Goto bookmarked items from 0-9
n r	New repository page
n g	New gist page

	Repositories
g s	Goto summary page
g c	Goto changelog page
g f	Goto files page
g F	Goto files page with file search activated
g p	Goto pull requests page
g o	Goto repository settings
g O	Goto repository access permissions settings
t s	Toggle sidebar on some pages

Gregory Szorc rust: implementation of `hg`...	r35587	===================
		Mercurial Rust Code
		===================

		This directory contains various Rust code for the Mercurial project.

		The top-level ``Cargo.toml`` file defines a workspace containing
		all primary Mercurial crates.

		Building
		========

		To build the Rust components::

		$ cargo build

		If you prefer a non-debug / release configuration::

		$ cargo build --release

		Features
		--------

		The following Cargo features are available:

		localdev (default)
		Produce files that work with an in-source-tree build.

		In this mode, the build finds and uses a ``python2.7`` binary from
		``PATH``. The ``hg`` binary assumes it runs from ``rust/target/<target>hg``
		and it finds Mercurial files at ``dirname($0)/../../../``.

		Build Mechanism
		---------------

		The produced ``hg`` binary is bound to a CPython installation. The
		binary links against and loads a CPython library that is discovered
		at build time (by a ``build.rs`` Cargo build script). The Python
		standard library defined by this CPython installation is also used.

		Finding the appropriate CPython installation to use is done by
		the ``python27-sys`` crate's ``build.rs``. Its search order is::

		1. ``PYTHON_SYS_EXECUTABLE`` environment variable.
		2. ``python`` executable on ``PATH``
		3. ``python2`` executable on ``PATH``
		4. ``python2.7`` executable on ``PATH``

		Additional verification of the found Python will be performed by our
		``build.rs`` to ensure it meets Mercurial's requirements.

		Details about the build-time configured Python are built into the
		produced ``hg`` binary. This means that a built ``hg`` binary is only
		suitable for a specific, well-defined role. These roles are controlled
		by Cargo features (see above).

		Running
		=======

		The ``hgcli`` crate produces an ``hg`` binary. You can run this binary
		via ``cargo run``::

		$ cargo run --manifest-path hgcli/Cargo.toml

		Or directly::

		$ target/debug/hg
		$ target/release/hg

		You can also run the test harness with this binary::

		$ ./run-tests.py --with-hg ../rust/target/debug/hg

		.. note::

		Integration with the test harness is still preliminary. Remember to
		``cargo build`` after changes because the test harness doesn't yet
		automatically build Rust code.