# HG changeset patch
# User Simon Sapin <simon.sapin@octobus.net>
# Date 1608204519 -3600
# Node ID ec14c37958ecfe5541dfa09349c06e84d6db1272
# Parent  3ca5ca380a3477a81402947e23fc50d13a4bd9d9
rust: document how to enable debug information in optimized builds

This is particularly useful when profiling.

Differential Revision: https://phab.mercurial-scm.org/D9625

diff -r 3ca5ca380a34 -r ec14c37958ec .hgignore
--- a/.hgignore	Mon Dec 14 18:09:37 2020 -0800
+++ b/.hgignore	Thu Dec 17 12:28:39 2020 +0100
@@ -64,6 +64,10 @@
 # Generated wheels
 wheelhouse/
 
+syntax: rootglob
+# See Profiling in rust/README.rst
+.cargo/config
+
 syntax: regexp
 ^\.pc/
 ^\.(pydev)?project
diff -r 3ca5ca380a34 -r ec14c37958ec rust/README.rst
--- a/rust/README.rst	Mon Dec 14 18:09:37 2020 -0800
+++ b/rust/README.rst	Thu Dec 17 12:28:39 2020 +0100
@@ -40,7 +40,7 @@
 You might want to check the `features` section in ``hg-cpython/Cargo.toml``.
 It may contain features that might be interesting to try out.
 
-To use features from the Makefile, use the `HG_RUST_FEATURES` environment 
+To use features from the Makefile, use the `HG_RUST_FEATURES` environment
 variable: for instance `HG_RUST_FEATURES="some-feature other-feature"`
 
 Profiling
@@ -51,6 +51,14 @@
 indicate why the rust code cannot be used (say, using lookarounds in
 hgignore).
 
+Creating a ``.cargo/config`` file with the following content enables
+debug information in optimized builds. This make profiles more informative
+with source file name and line number for Rust stack frames and
+(in some cases) stack frames for Rust functions that have been inlined.
+
+  [profile.release]
+  debug = true
+
 ``py-spy`` (https://github.com/benfred/py-spy) can be used to
 construct a single profile with rust functions and python functions
 (as opposed to ``hg --profile``, which attributes time spent in rust
@@ -58,6 +66,11 @@
 as opposed to tools for native code like ``perf``, which attribute
 time to the python interpreter instead of python functions).
 
+Example usage:
+
+  $ make PURE=--rust local # Don't forget to recompile after a code change
+  $ py-spy record --native --output /tmp/profile.svg -- ./hg ...
+
 Developing Rust
 ===============