Profiling & performance analysis
================================

Hare does not provide any Hare-specific profiling tools, but it is compatible
with most standard performance analysis tools.

.. note::
   Are you familiar with profiling tools for your operating system of choice,
   but it's not covered here? If so, please send us a patch improving this
   page.

perf(1)
-------

`perf(1)`_ is a high-performance, Linux-specific analysis tool.

.. _perf(1): https://manned.org/perf.1
.. _perf wiki: https://perf.wiki.kernel.org/index.php/Main_Page

To profile the example program above, run ``perf record -g <command>`` to
record a profile at ``./perf.data``. Terminate the program with Ctrl+C after
collecting enough samples, and view the report with ``perf report``.

perf can also analyze various events, monitor CPU performance registers to
characterize behavior like cache misses and branch prediction, and much more.
See also: `perf wiki`_

Visualizing reports with Firefox
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The most accessible and readily available tool for analyzing perf reports is
Firefox. Here is a quick recipe to view this report in Firefox:

.. code-block:: shell

   $ perf script record gecko <command>
   # ... press ctrl+c eventually...
   $ perf script report gecko <command>

.. TODO move this from catbox.moe to harelang.org

This will open the profile report in your default web browser. You can also
share this URL to share profiles with your collaborators -- you can see a
sample report `here <https://profiler.firefox.com/from-url/https%3A%2F%2Ffiles.catbox.moe%2Fxu53s6.json/calltree/?globalTrackOrder=0&thread=0&timelineType=category&v=10>`_.

callgrind
---------

`callgrind`_ is an generic intrusive profiler that's part of the Valgrind
suite. To capture a profile of the sample program above, run ``valgrind
--tool=callgrind -v --dump-every-bb=10000000 <command>`` and press Ctrl+C
after gathering enough samples. The profile is written to the current working
directory in ``callgrind.out.*`` files.

Callgrind supports Linux and FreeBSD.

.. _callgrind: https://valgrind.org/docs/manual/cl-manual.html

Visualizing reports with Kcachegrind
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

`Kcachegrind`_ is a graphical tool for exploring a profile captured with
callgrind. Simply run ``kcachegrind`` from the same directory as the profile
was captured to browse the results.

.. _Kcachegrind: https://kcachegrind.github.io/html/Home.html

Memory analysis
---------------

There are limited tools currently available for analyzing the memory usage of
Hare programs, though this will be improved in the future.

It is possible to analyze Hare programs with Valgrind provied that they are
linked to libc, which is done with ``hare build -lc ...``.