diff --git a/manual/tracy.md b/manual/tracy.md index 44d8ec3f..61b00444 100644 --- a/manual/tracy.md +++ b/manual/tracy.md @@ -12,7 +12,7 @@ The user manual **Bartosz Taudul** [\](mailto:wolf@nereid.pl) -2025-07-23 +2025-08-14 ::: # Quick overview {#quick-overview .unnumbered} @@ -2109,34 +2109,27 @@ Please not the use of ids as way to cope with the need for unique pointers for c ### Building the Python package -To build the Python package, you will need to use the CMake build system to compile the Tracy-Client. The CMake option `-D TRACY_CLIENT_PYTHON=ON` is used to enable the generation of the Python bindings in conjunction with a mandatory creation of a shared Tracy-Client library via one of the CMake options `-D BUILD_SHARED_LIBS=ON` or `-D DEFAULT_STATIC=OFF`. +To build the Python package, run the following commands: -The following other variables are available in addition: + cd ../python + pip wheel . -- `EXTERNAL_PYBIND11` --- Can be used to disable the download of pybind11 when Tracy is embedded in another CMake project that already uses pybind11. +This will create a wheel package in the `python` folder. Please note that this requires CMake and a C++ compiler installed on the system, as the Tracy-Client library is built in the background. -- `TRACY_CLIENT_PYTHON_TARGET` --- Optional directory to copy Tracy Python bindings to when Tracy is embedded in another CMake project. +You can pass additional CMake options to the package build to configure the Tracy-Client library: + + pip wheel . --config-settings cmake.define.TRACY_ENABLE=OFF + +The following additional CMake options are available when building the Python package: - `BUFFER_SIZE` --- The size of the global pointer buffer (defaults to 128) for naming Tracy profiling entities like frame marks, plots, and memory locations. - `NAME_LENGTH` --- The maximum length (defaults to 128) of a name stored in the global pointer buffer. +- `EXTERNAL_PYBIND11` --- Can be used to disable the download of pybind11 when Tracy is embedded in another CMake project that already uses pybind11. + Be aware that the memory allocated by this buffer is global and is not freed, see section [3.1.2](#uniquepointers). -See below for example steps to build the Python bindings using CMake: - - mkdir build - cd build - cmake -DTRACY_STATIC=OFF -DTRACY_CLIENT_PYTHON=ON ../ - make -j$(nproc) - -Once this has finished building the Python package can be built as follows: - - cd ../python - python3 setup.py bdist_wheel - -The created package will be in the folder `python/dist`. - ## Fortran API {#fortranapi} To profile code written in Fortran programming language, you will need to use the `tracy` module, which exposes the Fortran API. @@ -2395,6 +2388,8 @@ By default, sampling is performed at 8 kHz frequency on Windows (the maximum pos Call stack sampling may be disabled by using the `TRACY_NO_SAMPLING` define. +When enabled, by default, sampling starts at the beginning of the application and ends with it. You can instead have programmatic (manual) control over when sampling should begin and end by defining `TRACY_SAMPLING_PROFILER_MANUAL_START` when compiling `TracyClient.cpp`. Use `tracy::BeginSamplingProfiling()` and `tracy::EndSamplingProfiling()` to control it. There are C interfaces for it as well: `TracyCBeginSamplingProfiling()` and `TracyCEndSamplingProfiling()`. + ::: bclogo Linux sampling rate limits The operating system may decide that sampling takes too much CPU time and reduce the allowed sampling rate. This can be seen in `dmesg` output as: diff --git a/manual/tracy.tex b/manual/tracy.tex index aeb2b8f9..dc7ebfde 100644 --- a/manual/tracy.tex +++ b/manual/tracy.tex @@ -2392,37 +2392,30 @@ Please not the use of ids as way to cope with the need for unique pointers for c \subsubsection{Building the Python package} -To build the Python package, you will need to use the CMake build system to compile the Tracy-Client. -The CMake option \texttt{-D TRACY\_CLIENT\_PYTHON=ON} is used to enable the generation of the Python bindings in conjunction with a mandatory creation of a shared Tracy-Client library via one of the CMake options \texttt{-D BUILD\_SHARED\_LIBS=ON} or \texttt{-D DEFAULT\_STATIC=OFF}. - -The following other variables are available in addition: - -\begin{itemize} -\item \texttt{EXTERNAL\_PYBIND11} --- Can be used to disable the download of pybind11 when Tracy is embedded in another CMake project that already uses pybind11. -\item \texttt{TRACY\_CLIENT\_PYTHON\_TARGET} --- Optional directory to copy Tracy Python bindings to when Tracy is embedded in another CMake project. -\item \texttt{BUFFER\_SIZE} --- The size of the global pointer buffer (defaults to 128) for naming Tracy profiling entities like frame marks, plots, and memory locations. -\item \texttt{NAME\_LENGTH} --- The maximum length (defaults to 128) of a name stored in the global pointer buffer. -\end{itemize} - -Be aware that the memory allocated by this buffer is global and is not freed, see section~\ref{uniquepointers}. - -See below for example steps to build the Python bindings using CMake: - -\begin{lstlisting} -mkdir build -cd build -cmake -DTRACY_STATIC=OFF -DTRACY_CLIENT_PYTHON=ON ../ -make -j$(nproc) -\end{lstlisting} - -Once this has finished building the Python package can be built as follows: +To build the Python package, run the following commands: \begin{lstlisting} cd ../python -python3 setup.py bdist_wheel +pip wheel . \end{lstlisting} -The created package will be in the folder \texttt{python/dist}. +This will create a wheel package in the \texttt{python} folder. +Please note that this requires CMake and a C++ compiler installed on the system, as the Tracy-Client library is built in the background. + +You can pass additional CMake options to the package build to configure the Tracy-Client library: +\begin{lstlisting} +pip wheel . --config-settings cmake.define.TRACY_ENABLE=OFF +\end{lstlisting} + +The following additional CMake options are available when building the Python package: + +\begin{itemize} +\item \texttt{BUFFER\_SIZE} --- The size of the global pointer buffer (defaults to 128) for naming Tracy profiling entities like frame marks, plots, and memory locations. +\item \texttt{NAME\_LENGTH} --- The maximum length (defaults to 128) of a name stored in the global pointer buffer. +\item \texttt{EXTERNAL\_PYBIND11} --- Can be used to disable the download of pybind11 when Tracy is embedded in another CMake project that already uses pybind11. +\end{itemize} + +Be aware that the memory allocated by this buffer is global and is not freed, see section~\ref{uniquepointers}. \subsection{Fortran API} \label{fortranapi}