From 97924fd90d89cb42cc08d4f9d8d41435f3699928 Mon Sep 17 00:00:00 2001 From: Aziz Chynaliev Date: Sun, 18 Feb 2024 00:57:52 +0600 Subject: [PATCH] chore: update readme --- readme.md | 109 ++++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 86 insertions(+), 23 deletions(-) diff --git a/readme.md b/readme.md index f5ba40f..694e551 100644 --- a/readme.md +++ b/readme.md @@ -4,15 +4,18 @@ Para-byond-tracy glues together a byond server the tracy profiler allowing you t Note that the files generated cannot be loaded straight into tracy. You must use `replay.py` to load the `.utracy` file and stream "it over the network" (localhost) into `capture.exe` as part of Tracy. You can stream straight into `Tracy.exe`, but this is not advised due to performance overhead. -The above script requires the `lz4` library with the stream addon. The instructions for that are out of scope of this guide. +> The above script requires the `lz4` library with the stream addon. +> ```bash +> PYLZ4_EXPERIMENTAL=TRUE python3 -m pip install --no-cache-dir --no-binary lz4 lz4 +> ``` -Update 2023-12-29: You can now use [https://github.com/AffectedArc07/ParaTracyReplay](https://github.com/AffectedArc07/ParaTracyReplay) to stream the files much faster than the python script. +> **Update 2023-12-29**: You can now use [https://github.com/AffectedArc07/ParaTracyReplay](https://github.com/AffectedArc07/ParaTracyReplay) to stream the files much faster than the python script. -Update 2024-04-18: You can now use [https://github.com/Dimach/rtracy](https://github.com/Dimach/rtracy) to stream the files even faster than the C# code, as well as split traces and other cool things. +> **Update 2024-04-18**: You can now use [https://github.com/Dimach/rtracy](https://github.com/Dimach/rtracy) to stream the files even faster than the C# code, as well as split traces and other cool things. A massive thanks to `mafemergency` for even making this possible. The below readme is adapted from the original repo (branch: `stream-to-file`) [https://github.com/mafemergency/byond-tracy/](https://github.com/mafemergency/byond-tracy/) -## supported byond versions +## Supported byond versions | windows | linux | | -------- | -------- | @@ -64,43 +67,103 @@ A massive thanks to `mafemergency` for even making this possible. The below read | 515.1590 | 515.1590 | | 514.* | 514.* | -## supported tracy versions +## Supported tracy versions None built in, you need to reply these. -## usage +## Usage simply call `init` from `prof.dll` to begin writing to a file inside `data/profiler` init will return the filename it writes to upon success - the filename will always start with `.` ```dm -// returns a string filename whenever +// In case you need to start the capture as soon as the server boots, uncomment the following lines and recompile: + +// /world/New() +// prof_init() +// . = ..() + +#ifndef PROF +// Default automatic PROF detection. +// On Windows, looks in the standard places for `prof.dll`. +// On Linux, looks in `.`, `$LD_LIBRARY_PATH`, and `~/.byond/bin` for either of +// `libprof.so` (preferred) or `prof` (old). + +/* This comment bypasses grep checks */ /var/__prof + +/proc/__detect_prof() + if (world.system_type == UNIX) + if (fexists("./libprof.so")) + // No need for LD_LIBRARY_PATH badness. + return __prof = "./libprof.so" + else if (fexists("./prof")) + // Old dumb filename. + return __prof = "./prof" + else if (fexists("[world.GetConfig("env", "HOME")]/.byond/bin/prof")) + // Old dumb filename in `~/.byond/bin`. + return __prof = "prof" + else + // It's not in the current directory, so try others + return __prof = "libprof.so" + else + return __prof = "prof" + +#define PROF (__prof || __detect_prof()) +#endif + +// Handle 515 call() -> call_ext() changes +#if DM_VERSION >= 515 +#define PROF_CALL call_ext +#else +#define PROF_CALL call +#endif + +GLOBAL_VAR_INIT(profiler_enabled, FALSE) + +/** + * Starts Tracy and returns a string filename whenever + */ /proc/prof_init() - var/lib - - switch(world.system_type) - if(MS_WINDOWS) lib = "prof.dll" - if(UNIX) lib = "libprof.so" - else CRASH("unsupported platform") - - var/init = call_ext(lib, "init")() - if(length(init) != 0 && init[1] == ".") // if first character is ., then it returned the output filename - return init - else if("0" != init) - CRASH("[lib] init error: [init]") + var/init = PROF_CALL(PROF, "init")() + if("0" != init) CRASH("[PROF] init error: [init]") + GLOB.profiler_enabled = TRUE + if(length(init) != 0 && init[1] == ".") // if first character is ., then it returned the output filename + return init + +/** + * Stops Tracy + */ +/proc/prof_stop() + if(!GLOB.profiler_enabled) + return + + var/destroy = PROF_CALL(PROF, "destroy")() + if("0" != destroy) CRASH("[PROF] destroy error: [destroy]") + GLOB.profiler_enabled = FALSE /world/New() var/utracy_filename = prof_init() . = ..() + +/world/Del() + prof_stop() + . = ..() ``` -## building +## Building -no build system included, simply invoke your preferred c11 compiler. +cmake build system included, or simply invoke your preferred c11 compiler. examples: -(AA recommended: If you have the MSVC++ buildchain, open `x86 Native Tools Command Prompt for VS 2022` and then cd to this repo. `cl` should be on your path inside of that CLI environment) +> AA recommended: If you have the MSVC++ buildchain, open `x86 Native Tools Command Prompt for VS 2022` and then cd to this repo. `cl` should be on your path inside of that CLI environment + +> azizonkg recommended: use cmake on linux + +```console +cmake --build . --config Release +``` + ```console cl.exe /nologo /std:c11 /O2 /LD /DNDEBUG prof.c ws2_32.lib /Fe:prof.dll @@ -114,6 +177,6 @@ clang.exe -std=c11 -m32 -shared -Ofast3 -DNDEBUG -fuse-ld=lld-link prof.c -lws2_ gcc -std=c11 -m32 -shared -fPIC -Ofast -s -DNDEBUG prof.c -pthread -o libprof.so ``` -## remarks +## Remarks byond-tracy is in its infancy and is not production ready for live servers.