diff --git a/docs/debugging-tests.md b/docs/debugging-tests.md index c1c9d8726..b36e4f287 100644 --- a/docs/debugging-tests.md +++ b/docs/debugging-tests.md @@ -1,24 +1,41 @@ # How to run & debug a specific test without anything else to keep the feedback loop short? -Borrowing from the CI scripts to make something workflow specific, we have the following. +There is a script called debug-test.sh in the scripts folder that takes a REGEX as its only parameter. For example, running the following command will output an interactive list from which you can select a test. It will then build & run in the debugger for you. ```bash +./scripts/debug-test.sh test-tokenizer + +# Once in the debugger, i.e. at the chevrons prompt, setting a breakpoint could be as follows: +>>> b main +``` + +  + +# How does the script work? +If you want to be able to use the concepts contained in the script separately, the important ones are briefly outlined below. +```bash +# Step 1: Prepare the Build Environment rm -rf build-ci-debug && mkdir build-ci-debug && cd build-ci-debug cmake -DCMAKE_BUILD_TYPE=Debug -DLLAMA_CUDA=1 -DLLAMA_FATAL_WARNINGS=ON .. && cd .. -# runs faster + +# Step 2: Build the Project make -j -# if you see the "you don't have "cache" installed warning, install it to save immense amounts of time!" + +# Step 3: Navigate to Test Directory +# Tip: If you see a warning about missing "cache" during installation. Then install it to save immense amounts of time! cd tests +# Step 4: Identify Test Command for Debugging # The output of this command will give you the command & arguments needed to run GDB. -# -R test-tokenizer -> looks for all the test files named test-tokenizer* (R=Regex) -# -N -> "show-only" disables test execution & shows test commands that you can feed to GDB. -ctest -R test-tokenizer-0 -V -N -# OUPUT: - # 1: Test command: /home/ubuntu/workspace/llama.cpp/bin/test-tokenizer-0 "/home/ubuntu/workspace/llama.cpp/tests/../models/ggml-vocab-llama-spm.gguf" - # 1: Working Directory: . - # Labels: main - # Test #1: test-tokenizer-0-llama-spm +# -R test-tokenizer : looks for all the test files named test-tokenizer* (R=Regex) +# -N : "show-only" disables test execution & shows test commands that you can feed to GDB. +# -V : Verbose Mode +ctest -R ${test_suite} -V -N -# Now that we have the command & arguments needed to run a test, we can debug it with GDB. -# I copied the command from the above output, your scenario will be different. +# Step 5: Debug the Test +gdb --args ${test_path} ${test_args} gdb --args /home/ubuntu/workspace/llama.cpp/bin/test-tokenizer-0 "/home/ubuntu/workspace/llama.cpp/tests/../models/ggml-vocab-llama-spm.gguf" + + ``` + + + diff --git a/scripts/debug-test.sh b/scripts/debug-test.sh index a725d3be5..f4e5eb1f9 100755 --- a/scripts/debug-test.sh +++ b/scripts/debug-test.sh @@ -31,9 +31,6 @@ then exit 1 fi - - - # Step 1: Prepare the Build Environment pushd $(git rev-parse --show-toplevel) rm -rf build-ci-debug && mkdir build-ci-debug && pushd build-ci-debug