Merge pull request wolfpld#1136 from moritz-h/python-docs

Update Python docs

Author: wolfpld

manual/tracy.md

@@ -12,7 +12,7 @@ The user manual
 
 **Bartosz Taudul** [\<wolf@nereid.pl\>](mailto:wolf@nereid.pl)
 
-2025-07-23 <https://github.com/wolfpld/tracy>
+2025-08-14 <https://github.com/wolfpld/tracy>
 :::
 
 # Quick overview {#quick-overview .unnumbered}
@@ -2109,33 +2109,26 @@ 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:
-
--   `EXTERNAL_PYBIND11` --- Can be used to disable the download of pybind11 when Tracy is embedded in another CMake project that already uses pybind11.
+    cd ../python
+    pip wheel .
 
--   `TRACY_CLIENT_PYTHON_TARGET` --- Optional directory to copy Tracy Python bindings to when Tracy is embedded in another CMake project.
+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.
 
--   `BUFFER_SIZE` --- The size of the global pointer buffer (defaults to 128) for naming Tracy profiling entities like frame marks, plots, and memory locations.
+You can pass additional CMake options to the package build to configure the Tracy-Client library:
 
--   `NAME_LENGTH` --- The maximum length (defaults to 128) of a name stored in the global pointer buffer.
-
-Be aware that the memory allocated by this buffer is global and is not freed, see section [3.1.2](#uniquepointers).
+    pip wheel . --config-settings cmake.define.TRACY_ENABLE=OFF
 
-See below for example steps to build the Python bindings using CMake:
+The following additional CMake options are available when building the Python package:
 
-    mkdir build
-    cd build
-    cmake -DTRACY_STATIC=OFF -DTRACY_CLIENT_PYTHON=ON ../
-    make -j$(nproc)
+-   `BUFFER_SIZE` --- The size of the global pointer buffer (defaults to 128) for naming Tracy profiling entities like frame marks, plots, and memory locations.
 
-Once this has finished building the Python package can be built as follows:
+-   `NAME_LENGTH` --- The maximum length (defaults to 128) of a name stored in the global pointer buffer.
 
-    cd ../python
-    python3 setup.py bdist_wheel
+-   `EXTERNAL_PYBIND11` --- Can be used to disable the download of pybind11 when Tracy is embedded in another CMake project that already uses pybind11.
 
-The created package will be in the folder `python/dist`.
+Be aware that the memory allocated by this buffer is global and is not freed, see section [3.1.2](#uniquepointers).
 
 ## Fortran API {#fortranapi}
 
@@ -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:
 

manual/tracy.tex

@@ -2392,37 +2392,30 @@ \subsubsection{Bindings}
 
 \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:
+To build the Python package, run the following commands:
 
 \begin{lstlisting}
-mkdir build
-cd build
-cmake -DTRACY_STATIC=OFF -DTRACY_CLIENT_PYTHON=ON ../
-make -j$(nproc)
+cd ../python
+pip wheel .
 \end{lstlisting}
 
-Once this has finished building the Python package can be built as follows:
+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}
-cd ../python
-python3 setup.py bdist_wheel
+pip wheel . --config-settings cmake.define.TRACY_ENABLE=OFF
 \end{lstlisting}
 
-The created package will be in the folder \texttt{python/dist}.
+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}