diff --git a/manual/tracy.tex b/manual/tracy.tex index 7010cc9e..6da53ebc 100644 --- a/manual/tracy.tex +++ b/manual/tracy.tex @@ -756,7 +756,7 @@ vcpkg install --triplet x64-windows-static freetype glfw3 capstone[arm,arm64,x86 \paragraph{Unix} -On Unix systems you will need to install the \texttt{pkg-config} utility and the following libraries: \texttt{glfw}, \texttt{freetype}, \texttt{capstone}, \texttt{dbus}. Some Linux distributions will require you to add a \texttt{lib} prefix and a \texttt{-dev}, or \texttt{-devel} postfix to library names. You may also need to add a seemingly random number to the library name (for example: \texttt{freetype2}, or \texttt{freetype6}). Be aware that your package manager might distribute the deprecated \texttt{master}-branch version of \texttt{capstone}, and a build from source from the \texttt{next}-branch might be necesarry for you. Have fun! +On Unix systems you will need to install the \texttt{pkg-config} utility and the following libraries: \texttt{glfw}, \texttt{freetype}, \texttt{capstone}, \texttt{dbus}. Some Linux distributions will require you to add a \texttt{lib} prefix and a \texttt{-dev}, or \texttt{-devel} postfix to library names. You may also need to add a seemingly random number to the library name (for example: \texttt{freetype2}, or \texttt{freetype6}). Be aware that your package manager might distribute the deprecated \texttt{master}-branch version of \texttt{capstone}, and a build from source from the \texttt{next}-branch might be necessary for you. Have fun! In addition to the beforementioned libraries, you might also have to install the \texttt{tbb} library\footnote{Technically this is not a dependency of Tracy but rather of \texttt{libstdc++} but it may still not be installed by default.}. @@ -1644,10 +1644,29 @@ You will also need to setup proper dependencies, by setting the following input \paragraph{External libraries} -You may also be interested in symbols from external libraries, especially if you have sampling profiling enabled (section~\ref{sampling}). In MSVC you can retrieve such symbols by going to \menu[,]{Tools,Options,Debugging,Symbols} and selecting appropriate \emph{Symbol file (.pdb) location} servers. Note that additional symbols may significantly increase application startup times. +You may also be interested in symbols from external libraries, especially if you have sampling profiling enabled (section~\ref{sampling}). + +\subparagraph{Windows} + +In MSVC you can retrieve such symbols by going to \menu[,]{Tools,Options,Debugging,Symbols} and selecting appropriate \emph{Symbol file (.pdb) location} servers. Note that additional symbols may significantly increase application startup times. Libraries built with vcpkg typically provide PDB symbol files, even for release builds. Using vcpkg to obtain libraries has the extra benefit that everything is built using local source files, which allows Tracy to provide a source view not only of your application but also the libraries you use. +\subparagraph{Unix} + +On Linux\footnote{And possibly other systems, if they decide to adapt the required tooling.} information needed for debugging traditionally has been provided by special packages named \texttt{debuginfo}, \texttt{dbgsym}, or similar. You can use them to retrieve symbols, but keep in mind the following: + +\begin{enumerate} +\item Your distribution has to provide such packages. Not each one does. +\item Debug packages are usually stored in a separate repository, which you must manually enable. +\item You need to install a separate package for each library you want to have symbols for. +\item Debugging information can require large amounts of disk space. +\end{enumerate} + +A modern alternative to installing static debug packages is to use the \emph{debuginfod} system, which performs on-demand delivery of debugging information across the internet. See \url{https://sourceware.org/elfutils/Debuginfod.html} for more details. Since this new method of symbol delivery is not yet universally supported, you will have to manually enable it, both in your system and in Tracy. + +First, make sure your distribution maintains a debuginfod server. Then, install the debuginfod library. You also need to ensure you have appropriately configured which server to access, but distribution maintainers usually provide this. Next, add the \texttt{TRACY\_DEBUGINFOD} define to the program you want to profile and link it with \texttt{libdebuginfod}. This will enable network symbol delivery. + \paragraph{Using the dbghelp library on Windows} While Tracy will try to expand the known symbols list when it encounters a new module for the first time, you may want to be able to do such a thing manually. Or maybe you are using the \texttt{dbghelp.dll} library in some other way in your project, for example, to present a call stack to the user at some point during execution.