Page MenuHomePhabricator

rust: add a README
ClosedPublic

Authored by valentin.gatienbaron on Mon, Jan 20, 6:36 PM.

Details

Summary

In particular to explain how to build any of the rust. It's neither
obvious, nor easy to find out, nor easy to determine if you did it
right without some documentation.

Diff Detail

Repository
rHG Mercurial
Lint
Automatic diff as part of commit; lint not applicable.
Unit
Automatic diff as part of commit; unit tests not applicable.

Event Timeline

Alphare accepted this revision.Tue, Jan 21, 4:32 AM
Alphare added a subscriber: Alphare.
Alphare added inline comments.
rust/README.rst
27

I think you're missing the -l option for run-tests.py

34–37

I would add a mention of using cargo c(heck) for faster iteration and using cargo test --all to run the Rust tests, but this patch is already good enough on its own.

pulkit added inline comments.
rust/README.rst
25–29

IIRC, it's now possible to use HGMODULEPOLICY=rust. @gracinet that's possible now right?

Alphare added inline comments.Tue, Jan 21, 7:28 AM
rust/README.rst
25–29

HGMODULEPOLICY=rust+c to select it at runtime yes. But for not for make local AFAIK.

My general feeling is that I'd like to deprecate HGWITHRUSTEXT.

We now have python setup.py --rust [build|install|etc] and the coincidental make local PURE=--rust (works because $PURE, while meant to be for --pure is inserted blindly at the right place in the setup.py command.

Maybe this is a good time to decide of a better make variable ? EXTENSION_TYPE ? COMPILE_OPTIONS ? BUILD_OPTIONS ?

It's obviously a good thing to have official instructions, thank you Valentin for raising the subject.

rust/README.rst
25–29

HGMODULEPOLICY is for runtime, it can be rust+c or rust+c-allow.
In the first form, not having the Rust extension is a failure, in the second, there's a fallback.

"deprecate" was a bit too strong. Actually I'd like to downgrade HGWITHRUSTEXT to be something that'll be useful to play with alternative ways of building the Rust extension(s). Example: if someone wants to experiment with PyO3.

valentin.gatienbaron marked an inline comment as done.Tue, Jan 21, 9:35 AM

I didn't mention setup.py --rust because the toplevel readme doesn't mention setup.py, so I don't really know if that's really how mercurial is intended to be built or an implementation detail.

rust/README.rst
25–29

When I tested, setting HGMODULEPOLICY didn't work, perhaps because of what Raphael said.

27

Well, one can use -l to run rust tests, but it's not mandatory?

gracinet added inline comments.Tue, Jan 21, 10:10 AM
rust/README.rst
25–29

Both Raphaël and I were saying the same thin, perhaps a bit partially.

Here's the whole picture:

  • options to make or setup.py govern what is built (HGWITHRUSTEXT also).
  • among the built extensions, what is actually used at runtime depends on the module policy, which is read from mercurial/__modulepolicy__.py and can be overridden by HGMODULEPOLICY ,
  • at build time, a default policy value is set in mercurial/__modulepolicy__.py. For the record, this is rust+c-allow for local builds with Rust and rust+c for other Rust builds.

This policy system is actuallly not specific to Rust, it's also in use with the C extensions, the major difference being that C extensions are built by default.

For example, if one does not build the C extensions and use HGMODULEPOLICY=c, that's a hard error. With HGMODULEPOLICY=allow, one gets a fallback to the pure implementation.

Same with Rust: rust+c gives a hard error is Rust isn't built, while rust+c-allow fallbacks to C extensions only

pulkit accepted this revision.Tue, Jan 21, 11:02 AM
This revision is now accepted and ready to land.Tue, Jan 21, 11:02 AM
This revision was automatically updated to reflect the committed changes.