From c5a811b80db99cec58e0738a7cea1873f532080d Mon Sep 17 00:00:00 2001 From: Prince Date: Thu, 22 Jan 2026 13:06:18 +0530 Subject: [PATCH] docs: clarify how to generate and replay trace files --- README.md | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/README.md b/README.md index 23bc2ff..d0ac2c1 100644 --- a/README.md +++ b/README.md @@ -70,6 +70,38 @@ vardbg replay qsort.json -v sort_vis.mp4 It is possible to generate videos live while running the debugged program, but this is discouraged because the overhead of video creation inflates execution times greatly and thus ruins profiler results. However, if profiling is not important to you, it is a valid use case. +### Step-by-Step Example (Common Pitfalls Explained) + +This section provides a minimal working example and explains common errors reported by new users. + +#### 1. Example Python file + +Ensure the function you want to debug exists and matches the name provided in the command. + +Example: `qsort.py` + +```python +def quick_sort(arr): + if len(arr) <= 1: + return arr + pivot = arr[0] + left = [x for x in arr[1:] if x <= pivot] + right = [x for x in arr[1:] if x > pivot] + return quick_sort(left) + [pivot] + quick_sort(right) + + +### Generating and Replaying a Trace + +The `replay` command requires a JSON trace file. +This file must be generated first using `vardbg run`. + +```bash +vardbg run qsort.py quick_sort -o qsort.json -a 9 -a 3 -a 5 -a 1 + +To generate a visualization video from the trace: +vardbg replay qsort.json -v qsort.mp4 + + ## Configuration The video generator has many options: resolution, speed, fonts, and sizes. These options can be modified using a [TOML](https://learnxinyminutes.com/docs/toml/) config file. The [default config](https://github.com/CCExtractor/vardbg/blob/master/vardbg/output/video_writer/default_config.toml) documents the available options, which can be customized in an minimal overlay config without having to duplicate the entire config. The config can then be used by passing the `-c` argument on the command line.