Add valgrind/callgrind instructions and provide makefile.toml targets. (#732)

* Add targets to automate running with callgrind

This makes it easy to run the app under valgrind with --callgrind
to profile the function calls made.

Accessory script utils/symlink-qt-installer-libs-to-pyside6.sh is
provided to alter the PySide6 installation with Qt libraries that
contain debug information, so the callgrind logs have more useful
information in them.

* Add valgrind/callgrind instructions to README.md

Author: keithel-qt

Makefile.toml

@@ -164,6 +164,10 @@ Get-ChildItem .\console_backend -Recurse -Include @("*.egg-info", "*.dist-info")
 command = "${PYTHON}"
 args = ["-m", "swiftnav_console.main", "${@}"]
 
+[tasks.start-console-callgrind]
+command = "valgrind"
+args = ["--tool=callgrind", "${PYTHON}", "-m", "swiftnav_console.main", "${@}"]
+
 [tasks.start-console-gdb]
 command = "rust-gdb"
 args = [
@@ -200,6 +204,16 @@ dependencies = [
 ]
 run_task = "start-console-gdb"
 
+[tasks.callgrind-run]
+dependencies = [
+  "copy-capnp",
+  "generate-resources",
+  "remove-egg-dist",
+  "store-version",
+  "install-backend",
+]
+run_task = "start-console-callgrind"
+
 [tasks.prod-run]
 dependencies = [
   "copy-capnp",

README.md

@@ -193,6 +193,45 @@ cargo make check-all
 cargo make tests
 ```
 
+## Callgrind
+
+It may be helpful to profile the application. To do this, you can use valgrind.
+One mode of valgrind that is particularly useful is --callgrind.
+
+In order to use this, you need to install valgrind in your favorite OS.
+You can initiate this using the cargo make target `callgrind-run`.
+
+Once you run the app with callgrind and quit the application, it will generate a
+file named callgrind.out.\<unique id\>.
+
+To analyze the results, use kcachegrind or qcachegrind, which you should be able
+to find installable with your distribution's package manager.
+Both are the same tool, just have slightly different dependencies. If you are
+using KDE, install `kcachegrind`. If you are using Gnome, install `qcachegrind`.
+Pass the `callgrind.out` file to the tool like so:
+```
+qcachegrind callgrind.out.163238
+```
+
+To dive into the source code, download the sources for the libraries you wish to
+inspect (like Qt or Python), matching the exact version, and set the source
+directories in QCacheGrind from the configuration dialog accessible from the
+View menu (View-\>Configure...-\>Source Annotation-\>Add).
+
+The Qt libraries contained in the PySide6 python module do not contain debug
+symbols, and thus you see limited information from Qt when profiling. To add
+debug symbols to this, download and install Qt from qt.io, matching the PySide6
+version, and use the included `utils/symlink-qt-installer-libs-to-pyside6.sh`
+script.
+
+You can fetch the Qt source code either from the Qt installer, or from git
+using the `v6.n.n` tags.
+
+This has only been tested on Linux, but it should also work on macOS and
+Windows.
+
+Someone else may be able to expand this showing how to profile the Rust code.
+
 ## Technologies
 
 ### Rust

utils/symlink-qt-installer-libs-to-pyside6.sh

@@ -0,0 +1,111 @@
+#!/usr/bin/env bash
+
+set -e # Terminate with failure if any command returns nonzero
+set -u # Terminate with failure any time an undefined variable is expanded
+
+SCRIPT_DIR="$(cd -P "$(dirname "$BASH_SOURCE")" >/dev/null 2>&1 && pwd)"
+
+pyproject_toml="${SCRIPT_DIR}/../pyproject.toml"
+if [[ ! -f "$pyproject_toml" ]]; then
+    echo >&2 "Couldn't find pyproject.toml."
+    echo >&2 "Unable to determine PySide6 version. aborting."
+    exit 0
+fi
+
+set +e
+awk --version >/dev/null 2>&1
+if [[ $? -ne 0 ]]; then
+    echo >&2 "Couldn't find awk. Aborting."
+    exit 1
+fi
+set -e
+
+pysideversion=$(awk '/PySide6/{print(gensub(".*(PySide6 *== *([0-9]\\.[0-9]{1,2}\\.[0-9]{1,3})).*","\\2", "1")) }' "$pyproject_toml")
+
+if [[ ! "$pysideversion" =~ [0-9]\.[0-9]{1,2}\.[0-9]{1,3} ]]; then
+    echo >&2 "PySide version found is not a version number: $pysideversion"
+    exit 1
+fi
+
+qt_archdir=""
+case $OSTYPE in
+    "linux-gnu"*)
+        qt_archdir="gcc_64"
+        ;;
+    "darwin"*)
+        qt_archdir="macos"
+        ;;
+    *)
+        qt_archdir="msvc2019_64"
+        ;;
+esac
+
+# Standard Qt install location
+QTDIR="${HOME}/Qt/${pysideversion}/${qt_archdir}"
+
+kept_args=()
+for arg in "$@"; do
+  case $arg in
+    --qtdir=*)
+        QTDIR="${arg#*=}"
+        shift
+        ;;
+    -h|--help)
+        echo >&2 "$(basename "$BASH_SOURCE") [--qtdir=<Path to Qt base dir>] [-h|--help]"
+        echo >&2
+        echo >&2 "    --qtdir=<Path to Qt base dir>"
+        echo >&2 "        Use specified Qt dir to link Qt libraries into PySide6 installation."
+        echo >&2 "    -h, --help"
+        echo >&2 "        Show this help."
+        exit 0
+        ;;
+    -*|--*)
+        echo >&2 "Unknown option $arg."
+        exit 1
+        ;;
+    *)
+        kept_args+=($arg)
+        ;;
+  esac
+done
+set -- "${kept_args[@]}"
+
+
+# Check if Qt is installed
+if [[ ! -e "${QTDIR}/lib/libQt6Core.so.6" ]]; then
+    echo >&2 "Could not find ${QTDIR}/lib/libQt6Core.so.6. aborting."
+    exit 1
+fi
+
+# Check if PySide6 is installed
+pyside6_qt_lib_dir=$(realpath "${SCRIPT_DIR}/../py39/lib/python3.9/site-packages/PySide6/Qt/lib")
+if [[ ! -e "$pyside6_qt_lib_dir" ]]; then
+    echo >&2 "Could not find $pyside6_qt_lib_dir. aborting."
+    exit 1
+fi
+
+cd "${QTDIR}/lib"
+qtdir_libs=$(ls -1 libQt6*.so.6 | sort)
+cd "${SCRIPT_DIR}/../py39/lib/python3.9/site-packages/PySide6/Qt/lib"
+
+bkup_dir_suffix=""
+while [[ -e "original_libs${bkup_dir_suffix}" ]]; do
+    if [[ -z "$bkup_dir_suffix" ]]; then
+        bkup_dir_suffix=1
+    else
+        bkup_dir_suffix=$(($bkup_dir_suffix+1))
+    fi
+done
+orig_libs_dir="original_libs${bkup_dir_suffix}"
+mkdir "$orig_libs_dir"
+mv $qtdir_libs "$orig_libs_dir"
+
+for lib in $qtdir_libs ; do
+    ln -s "${QTDIR}/lib/$lib" $lib
+done
+
+echo "Done."
+echo "Qt libraries from
+    $QTDIR
+have been linked to
+    $pyside6_qt_lib_dir"