build: tracy integration (#3253)

* build: tracy integration * docs: tracy guide * build: fix policy CMP0135 error see: https://cmake.org/cmake/help/latest/policy/CMP0135.html * build: add framemark * docs: installation guide * docs: desktop entry * build: add `TRACY_ON_DEMAND` * test: profile `do_turn` * feat: profile `monmove` * fix: ignore tracy macros when disabled * docs: explain how to use tracy * docs: guide on dependencies * ci: exclude `-Wno-everything` on MSVC Co-authored-by: Olanti <[email protected]> * ci: Apply suggestions from code review Co-authored-by: Olanti <[email protected]> * ci: take account of static linking Co-authored-by: Olanti <[email protected]> * ci: bump minimum required cmake version * ci: pin tracy version to `v0.10` see: https://github.com/cataclysmbnteam/Cataclysm-BN/pull/3253/files?w=1#r1545267113 Co-authored-by: olanti-p <[email protected]> * ci: use latest commit on linux see: #3253 (comment) * docs: fileselector workaround * docs: explain version --------- Co-authored-by: Olanti <[email protected]>
cataclysmbnteam · Mar 30, 2024 · d603949 · d603949
1 parent 51d0bca
commit d603949
Show file tree

Hide file tree

Showing 23 changed files with 376 additions and 3 deletions.
diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -1,4 +1,4 @@
-cmake_minimum_required(VERSION 3.20)
+cmake_minimum_required(VERSION 3.24)
 
 project(CataclysmBN C CXX)
 
@@ -38,6 +38,7 @@ option(JSON_FORMAT "Build JSON formatter" "OFF")
 option(CATA_CCACHE "Try to find and build with ccache" "ON")
 option(TESTS "Compile Cata's tests" "ON")
 option(CATA_CLANG_TIDY_PLUGIN "Build Cata's custom clang-tidy plugin" "OFF")
+option(USE_TRACY "Use Tracy profiler" "OFF")
 set(CATA_CLANG_TIDY_INCLUDE_DIR "" CACHE STRING
         "Path to internal clang-tidy headers required for plugin (e.g. ClangTidy.h)")
 set(CATA_CHECK_CLANG_TIDY "" CACHE STRING "Path to check_clang_tidy.py for plugin tests")
@@ -211,6 +212,7 @@ message(STATUS "SOUND                         : ${SOUND}")
 message(STATUS "LUA                           : ${LUA}")
 message(STATUS "BACKTRACE                     : ${BACKTRACE}")
 message(STATUS "LIBBACKTRACE                  : ${LIBBACKTRACE}")
+message(STATUS "USE_TRACY                     : ${USE_TRACY}")
 message(STATUS "USE_XDG_DIR                   : ${USE_XDG_DIR}")
 message(STATUS "USE_HOME_DIR                  : ${USE_HOME_DIR}")
 message(STATUS "UNITY_BUILD                   : ${USE_UNITY_BUILD}")
@@ -270,6 +272,36 @@ endif ()
 set(CMAKE_THREAD_PREFER_PTHREAD True)
 find_package(Threads REQUIRED)
 
+if (USE_TRACY)
+    include(FetchContent)
+
+    if (NOT TRACY_VERSION)
+        if("${CMAKE_SYSTEM_NAME}" MATCHES "Linux")
+            set(TRACY_VERSION 30f1b901a9bab40a193c97c77ec82ac70805164d)
+        else()
+            set(TRACY_VERSION v0.10)
+        endif()
+        message(STATUS "Using tracy version: ${TRACY_VERSION}")
+    endif()
+
+    FetchContent_Declare(
+        tracy
+        GIT_REPOSITORY https://github.com/wolfpld/tracy.git
+        GIT_TAG "${TRACY_VERSION}"
+        GIT_SHALLOW TRUE
+        GIT_PROGRESS TRUE)
+
+    FetchContent_MakeAvailable(tracy)
+    set_target_properties(TracyClient PROPERTIES TRACY_ENABLE ON TRACY_ON_DEMAND ON)
+
+    if(NOT MSVC)
+        target_compile_options(TracyClient PRIVATE "-Wno-everything")
+    endif()
+    if (NOT DYNAMIC_LINKING)
+        set_target_properties(TracyClient PROPERTIES TRACY_STATIC ON)
+    endif ()
+endif ()
+
 # Check for build types and libraries
 if (TILES)
     # Find SDL, SDL_ttf & SDL_image for graphical install

diff --git a/doc/src/assets/img/tracy/main.png b/doc/src/assets/img/tracy/main.png
diff --git a/doc/src/assets/img/tracy/options.png b/doc/src/assets/img/tracy/options.png
diff --git a/doc/src/assets/img/tracy/stats.png b/doc/src/assets/img/tracy/stats.png
diff --git a/doc/src/content/docs/en/dev/guides/building/cmake.md b/doc/src/content/docs/en/dev/guides/building/cmake.md
@@ -362,6 +362,10 @@ much faster.
 
 [libbacktrace]: https://github.com/ianlancetaylor/libbacktrace
 
+- USE_TRACY=`<boolean>`
+
+Use tracy profiler. See [Profiling with tracy](../tracy.md) for more information.
+
 - GIT_BINARY=`<str>`
 
 Override default Git binary name or path.

diff --git a/doc/src/content/docs/en/dev/guides/building/vs_cmake.md b/doc/src/content/docs/en/dev/guides/building/vs_cmake.md
@@ -10,7 +10,7 @@ CMake build is work-in-progress.
 
 ## Prerequisites
 
-- `cmake` >= 3.20.0
+- `cmake` >= 3.24.0
 - `vcpkg` from [vcpkg.io](https://vcpkg.io/en/getting-started.html)
 
 Note that starting from Visual Studio 2022 version 17.6, `vcpkg` is included with the distribution

diff --git a/doc/src/content/docs/en/dev/guides/tracy.md b/doc/src/content/docs/en/dev/guides/tracy.md
@@ -0,0 +1,150 @@
+---
+title: Profiling with tracy
+---
+
+[Tracy](https://github.com/wolfpld/tracy) is a realtime profiler which you can use to analyze
+performance bottleneck. It consists of two parts: client and profiler. The client integrated in BN
+sends profiling data to the profiler. As the client is opt-in, you need to build BN with tracy
+client in order to start profiling.
+
+## Install Tracy Profiler
+
+:::caution
+
+Both the game and profiler have to be built with same version of tracy to work properly. Due to
+[numerous issues](https://github.com/cataclysmbnteam/Cataclysm-BN/pull/3253#discussion_r1545267113),
+The windows version uses [`v0.10`](https://github.com/wolfpld/tracy/releases/tag/v0.10) wheras the
+linux version uses
+[`30f1b90`](https://github.com/wolfpld/tracy/commit/30f1b901a9bab40a193c97c77ec82ac70805164d).
+
+:::
+
+### Linux
+
+```sh
+$ git clone https://github.com/wolfpld/tracy
+$ cd tracy
+$ git checkout 30f1b901a9bab40a193c97c77ec82ac70805164d # the commit used by BN tracy client
+```
+
+1. Clone <https://github.com/wolfpld/tracy>.
+
+```sh
+# for ubuntu
+$ sudo apt install cmake clang git libcapstone-dev xorg-dev dbus libgtk-3-dev
+
+# for arch, copied from https://github.com/wolfpld/tracy/blob/master/.github/workflows/linux.yml#L16C12-L16C163
+$ pacman -Syu --noconfirm && pacman -S --noconfirm --needed freetype2 tbb debuginfod wayland dbus libxkbcommon libglvnd meson cmake git wayland-protocols
+```
+
+2. Install dependencies.
+
+```sh
+$ cmake -B profiler/build -S profiler # if you're using wayland
+```
+
+3. Set up cmake. By default tracy uses wayland, if you want to use X11, you need to add `LEGACY=1`
+   flag.
+
+:::note{title="for X11"}
+
+```sh
+$ cmake -DLEGACY=ON -B profiler/build -S profiler # if you're using X11
+```
+
+tracy uses wayland by default, if you want to use X11, you need to add `LEGACY=1` flag.
+
+:::
+
+:::note{title="fileselector fixes"}
+
+```sh
+$ cmake -DGTK_FILESELECTOR=ON -B profiler/build -S profiler
+```
+
+Due to issues with [default fileselector (xdg-portal)](https://github.com/wolfpld/tracy/issues/764),
+tracy may fail to open or save trace history. As an workaround, add `GTK_FILESELECTOR=ON` in compile
+flags to use gtk fileselector.
+
+:::
+
+```sh
+$ cmake --build profiler/build --config Release --parallel $(nproc)
+```
+
+4. Build the binary. It will be available on `./profiler/build/tracy-profiler`.
+
+:::tip{title="Adding desktop entry"}
+
+```
+[Desktop Entry]
+Version=1.0
+Type=Application
+Name=Tracy Profiler
+GenericName=Code profiler
+GenericName[pl]=Profiler kodu
+GenericName[ko]=코드 프로파일러
+Comment=Examine code to see where it is slow
+Comment[pl]=Znajdowanie wolno wykonującego się kodu
+Comment[ko]=코드 분석해서 느린 곳 찾기
+Exec=<THE_PATH_WHERE_YOU_INSTALLED_TRACY>/profiler/build/tracy-profiler %f
+Icon=<THE_PATH_WHERE_YOU_INSTALLED_TRACY>/icon/icon.ico
+Terminal=false
+Categories=Development;Profiling;
+MimeType=application/tracy;
+X-Desktop-File-Install-Version=0.26
+```
+
+To make the profiler available in app runner, create `$HOME/.local/share/applications/tracy.desktop`
+file with the following content. Make sure to replace `<THE_PATH_WHERE_YOU_INSTALLED_TRACY>` with
+the path where you installed tracy!
+
+:::
+
+### Windows
+
+![image](https://github.com/cataclysmbnteam/Cataclysm-BN/assets/54838975/b6f73c09-969c-4305-b8fb-070d14fb834a)
+
+Download pre-compiled executable from <https://github.com/wolfpld/tracy/releases>.
+
+## Build BN with Tracy Client
+
+Build on [cmake](../guides/building/cmake.md) with `-D USE_TRACY=ON` flag. For example,
+
+```sh
+$ cmake -B build -DUSE_TRACY=ON ...other flags...
+```
+
+See [CMake options](building/cmake.md#cataclysmbn-specific-options) for more information.
+
+## Mark zone to profile
+
+Mark `ZoneScoped` in the function you'd like to profile. It will be displayed in the tracy GUI. For
+example,
+
+```cpp
+bool game::do_turn()
+{
+    ZoneScoped;
+
+    /** Other code... */
+}
+```
+
+There are also more complex profiling macros available. Check following links for more:
+
+- <https://github.com/wolfpld/tracy>
+- <https://luxeengine.com/integrating-tracy-profiler-in-cpp/>
+- [An Introduction to Tracy Profiler in C++ - Marcos Slomp - CppCon 2023](https://www.youtube.com/watch?v=ghXk3Bk5F2U)
+
+## Use Tracy Profiler
+
+1. Start BN (built with `USE_TRACY=ON`), and run the tracy profiler.
+
+![](../../../../../assets/img/tracy/main.png)
+
+2. Click `connect` button to connect to the game.
+
+![](../../../../../assets/img/tracy/stats.png)
+
+3. Profiling data will be displayed in the GUI.
diff --git a/src/CMakeLists.txt b/src/CMakeLists.txt
@@ -124,6 +124,12 @@ if (TILES)
         target_link_libraries(cataclysm-tiles-common PUBLIC backtrace)
     endif ()
 
+    if (USE_TRACY)
+        target_link_libraries(cataclysm-tiles-common PUBLIC TracyClient)
+        target_include_directories(cataclysm-tiles-common SYSTEM PUBLIC ${tracy_SOURCE_DIR}/public)
+        target_compile_definitions(cataclysm-tiles-common PUBLIC USE_TRACY)
+    endif ()
+
     if (RELEASE)
         install(TARGETS cataclysm-tiles RUNTIME)
     endif ()
@@ -192,6 +198,12 @@ if (CURSES)
         target_link_libraries(cataclysm-common PUBLIC backtrace)
     endif ()
 
+    if (USE_TRACY)
+        target_link_libraries(cataclysm-common PUBLIC TracyClient)
+        target_include_directories(cataclysm-common SYSTEM PUBLIC ${tracy_SOURCE_DIR}/public)
+        target_compile_definitions(cataclysm-common PUBLIC USE_TRACY)
+    endif ()
+
     if (RELEASE)
         install(TARGETS cataclysm RUNTIME)
     endif ()

diff --git a/src/character_turn.cpp b/src/character_turn.cpp
@@ -30,6 +30,7 @@
 #include "vpart_position.h"
 #include "weather_gen.h"
 #include "weather.h"
+#include "profile.h"
 
 static const trait_id trait_ACIDBLOOD( "ACIDBLOOD" );
 static const trait_id trait_ARACHNID_ARMS_OK( "ARACHNID_ARMS_OK" );
@@ -839,6 +840,8 @@ void Character::environmental_revert_effect()
 
 void Character::process_items()
 {
+    ZoneScoped;
+
     auto process_item = [this]( detached_ptr<item> &&ptr ) {
         return item::process( std::move( ptr ), as_player(), pos(), false );
     };

diff --git a/src/creature.cpp b/src/creature.cpp
@@ -49,6 +49,7 @@
 #include "vehicle.h"
 #include "vehicle_part.h"
 #include "vpart_position.h"
+#include "profile.h"
 
 static const ammo_effect_str_id ammo_effect_APPLY_SAP( "APPLY_SAP" );
 static const ammo_effect_str_id ammo_effect_BEANBAG( "BEANBAG" );
@@ -255,6 +256,8 @@ bool Creature::is_dangerous_field( const field_entry &entry ) const
 
 bool Creature::sees( const Creature &critter ) const
 {
+    ZoneScoped;
+
     // Creatures always see themselves (simplifies drawing).
     if( &critter == this ) {
         return true;

diff --git a/src/game.cpp b/src/game.cpp
@@ -176,6 +176,7 @@
 #include "wcwidth.h"
 #include "weather.h"
 #include "worldfactory.h"
+#include "profile.h"
 
 class computer;
 
@@ -1343,6 +1344,7 @@ void game::calc_driving_offset( vehicle *veh )
 // Returns true if game is over (death, saved, quit, etc)
 bool game::do_turn()
 {
+    ZoneScoped;
     cleanup_arenas();
     if( is_game_over() ) {
         return cleanup_at_end();
@@ -1502,6 +1504,7 @@ bool game::do_turn()
         overmap_npc_move();
     }
     if( calendar::once_every( 10_seconds ) ) {
+        ZoneScopedN( "field_emits" );
         for( const tripoint &elem : m.get_furn_field_locations() ) {
             const auto &furn = m.furn( elem ).obj();
             for( const emit_id &e : furn.emissions ) {
@@ -1552,6 +1555,7 @@ bool game::do_turn()
         }
     }
     if( wait_redraw ) {
+        ZoneScopedN( "wait_redraw" );
         if( first_redraw_since_waiting_started ||
             calendar::once_every( std::min( 1_minutes, wait_refresh_rate ) ) ) {
             if( first_redraw_since_waiting_started || calendar::once_every( wait_refresh_rate ) ) {
@@ -1644,6 +1648,7 @@ void game::process_voluntary_act_interrupt()
 
 void game::process_activity()
 {
+    ZoneScoped;
     if( !u.activity ) {
         return;
     }
@@ -3828,6 +3833,8 @@ void game::mon_info( const catacurses::window &w, int hor_padding )
 
 void game::mon_info_update( )
 {
+    ZoneScoped;
+
     int newseen = 0;
     const int safe_proxy_dist = get_option<int>( "SAFEMODEPROXIMITY" );
     const int iProxyDist = ( safe_proxy_dist <= 0 ) ? MAX_VIEW_DISTANCE :
@@ -4067,6 +4074,7 @@ void game::cleanup_dead()
 
 void game::monmove()
 {
+    ZoneScoped;
     cleanup_dead();
 
     for( monster &critter : all_monsters() ) {
@@ -4193,6 +4201,7 @@ void game::monmove()
 
 void game::overmap_npc_move()
 {
+    ZoneScoped;
     std::vector<npc *> travelling_npcs;
     static constexpr int move_search_radius = 600;
     for( auto &elem : overmap_buffer.get_npcs_near_player( move_search_radius ) ) {
@@ -10859,6 +10868,8 @@ void game::replace_stair_monsters()
 // TODO: refactor so zombies can follow up and down stairs instead of this mess
 void game::update_stair_monsters()
 {
+    ZoneScoped;
+
     // Search for the stairs closest to the player.
     std::vector<int> stairx;
     std::vector<int> stairy;

diff --git a/src/lightmap.cpp b/src/lightmap.cpp
@@ -31,6 +31,7 @@
 #include "npc.h"
 #include "player.h"
 #include "point.h"
+#include "profile.h"
 #include "string_formatter.h"
 #include "submap.h"
 #include "tileray.h"
@@ -434,6 +435,7 @@ void map::build_sunlight_cache( int pzlev )
 
 void map::generate_lightmap( const int zlev )
 {
+    ZoneScoped;
     auto &map_cache = get_cache( zlev );
     auto &lm = map_cache.lm;
     auto &sm = map_cache.sm;