From 396268fc1241eb9163def02e95d0c69e5f824f11 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vladim=C3=ADr=20Vondru=C5=A1?= Date: Sun, 18 Sep 2022 12:23:01 +0200 Subject: [PATCH] doc: document GDB pretty printers, updated credits & changelog. Mostly just a copy of what's in Corrade already. --- doc/00-page-order.dox | 1 + doc/changelog.dox | 3 ++ doc/credits.dox | 3 +- doc/debuggers.dox | 69 ++++++++++++++++++++++++++++++++++++ src/debuggers/CMakeLists.txt | 6 ++-- 5 files changed, 79 insertions(+), 3 deletions(-) create mode 100644 doc/debuggers.dox diff --git a/doc/00-page-order.dox b/doc/00-page-order.dox index aa85c11d8..d1b9dec11 100644 --- a/doc/00-page-order.dox +++ b/doc/00-page-order.dox @@ -30,6 +30,7 @@ @page getting-started Getting started @page features Feature guide @page platforms Platform-specific guides +@page debuggers Debugger support @page example-index Examples @page tips Tips and tricks @page utilities Utilities diff --git a/doc/changelog.dox b/doc/changelog.dox index 0fc889703..3f0f736d1 100644 --- a/doc/changelog.dox +++ b/doc/changelog.dox @@ -59,6 +59,9 @@ See also: typedefs for half-float angles and ranges - New @ref Range1Dui, @ref Range2Dui and @ref Range3Dui typedefs for unsigned integer ranges +- Added pretty-printers for GDB. See @ref debuggers and + [mosra/magnum#589](https://github.com/mosra/magnum/pull/589) for more + information. @subsubsection changelog-latest-new-debugtools DebugTools library diff --git a/doc/credits.dox b/doc/credits.dox index f63a63132..85a24fe68 100644 --- a/doc/credits.dox +++ b/doc/credits.dox @@ -140,7 +140,8 @@ Are the below lists missing your name or something's wrong? algorithm bugfixes - **Guillaume Jacquemin** ([\@williamjcm](https://github.com/williamjcm)) --- MSYS2 packages, additions to @ref Audio, @ref Platform::Sdl2Application and - @ref Platform::GlfwApplication, [base-wxwidgets](https://github.com/mosra/magnum-bootstrap/tree/base-wxwidgets) + @ref Platform::GlfwApplication, GDB pretty-printers, + [base-wxwidgets](https://github.com/mosra/magnum-bootstrap/tree/base-wxwidgets) bootstrap project - **Hans Loeblich** ([\@thehans](https://github.com/thehans)) --- improvements to Debian package building experience diff --git a/doc/debuggers.dox b/doc/debuggers.dox new file mode 100644 index 000000000..c8753268e --- /dev/null +++ b/doc/debuggers.dox @@ -0,0 +1,69 @@ +/* + This file is part of Magnum. + + Copyright © 2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019, + 2020, 2021, 2022 Vladimír Vondruš + Copyright © 2022 Guillaume Jacquemin + + Permission is hereby granted, free of charge, to any person obtaining a + copy of this software and associated documentation files (the "Software"), + to deal in the Software without restriction, including without limitation + the rights to use, copy, modify, merge, publish, distribute, sublicense, + and/or sell copies of the Software, and to permit persons to whom the + Software is furnished to do so, subject to the following conditions: + + The above copyright notice and this permission notice shall be included + in all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL + THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING + FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER + DEALINGS IN THE SOFTWARE. +*/ + +namespace Magnum { +/** @page debuggers Debugger support +@brief Pretty-printers for Magnum types and other debugging aids +@m_since_latest + +@section debuggers-gdb-pretty-printers GDB pretty printers + +The [src/debuggers/gdb](https://github.com/mosra/magnum/tree/master/src/debuggers/gdb) +directory contains [GDB pretty printers](https://sourceware.org/gdb/onlinedocs/gdb/Pretty-Printing.html) +for important types in the @ref Magnum and @ref Animation namespace and most +@ref Math classes. Contents of this directory are also copied into +@cb{.sh} ${CMAKE_PREFIX_PATH}/share/magnum/debuggers/gdb @ce during +installation, where the prefix is usually `/usr` or `/usr/local`. + +Easiest is to auto-load them on startup, by putting the following snippet into +the user-specific `~/.gdbinit` or `~/.config/gdb/gdbinit` file: + +@code{.py} +python +import sys +# Adapt this path to the actual install location (or Magnum's src/ directory). +# Not pointing to the debuggers subdirectory here because it could conflict +# with the built-in GDB module. +sys.path.insert(0, '/usr/share') +from magnum.debuggers.gdb import register_magnum_printers +register_magnum_printers(gdb.current_objfile()) +end +@endcode + +In case of MSYS2/MinGW, when running outside of the MSYS2 shell, you may need +to put the file into @cb{.bat} %USERPROFILE%/.config/gdb/gdbinit @ce instead of +@cb{.sh} $HOME/.gdbinit @ce. + +Alternatively, it's possible to load the scripts manually using GDB commands +(basically, pasting contents the above snippet) or by executing a GDB script +file using the @m_class{m-doc-external} [source](https://sourceware.org/gdb/onlinedocs/gdb/Command-Files.html#Command-Files) +command. See also corresponding [GDB docs](https://sourceware.org/gdb/onlinedocs/gdb.html#Initialization-Files) +and [CLion docs](https://www.jetbrains.com/help/clion/configuring-debugger-options.html#gdbinit-lldbinit) +for more information. + +See also @ref corrade-debuggers-gdb-pretty-printers "Corrade GDB pretty printers". +*/ +} diff --git a/src/debuggers/CMakeLists.txt b/src/debuggers/CMakeLists.txt index fc25ddcae..09f080e68 100644 --- a/src/debuggers/CMakeLists.txt +++ b/src/debuggers/CMakeLists.txt @@ -24,5 +24,7 @@ # DEALINGS IN THE SOFTWARE. # -install(DIRECTORY gdb - DESTINATION ${MAGNUM_DATA_INSTALL_DIR}/debuggers) +# TODO: same TODOs as in corrade/src/debuggers/CMakeLists.txt apply here +if(NOT CORRADE_TARGET_MSVC AND NOT CORRADE_TARGET_EMSCRIPTEN) + install(DIRECTORY gdb DESTINATION ${MAGNUM_DATA_INSTALL_DIR}/debuggers) +endif()