Skip to content

[docs] Add a section about debugging individual tests #1750

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
StephanTLavavej merged 6 commits into from
Mar 23, 2021
Merged

[docs] Add a section about debugging individual tests #1750

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
c713139
[docs] Add a section about debugging individual tests
miscco Mar 17, 2021
a1281df
Apply Caseys proof reading
miscco Mar 17, 2021
34dca4a
Clean up the command line a bit
miscco Mar 17, 2021
8fb37f2
Make clear that we only need to set the path with dynamic linkage
miscco Mar 17, 2021
8fe45e8
Review feedback.
StephanTLavavej Mar 20, 2021
3032abe
Merge branch 'main' into debugging_tips
StephanTLavavej Mar 23, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 38 additions & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -362,6 +362,44 @@ The `SKIPPED` result code indicates that a given test was explicitly skipped by
* taking a very long time to run
* failing or passing for the incorrect reason

### Debugging Individual Tests

While `stl-lit` is super awesome in finding out that *something* is wrong or not even compiling, it is not really
helpful in debugging *what* is going wrong. However, debugging individual tests is rather simple given some additional
steps. Let's assume we want to debug a new feature with tests located in `tests\std\tests\GH_XXXX_meow`.

As always, build the STL from your branch and run the tests:
```
C:\STL\out\build\x64> ninja
C:\STL\out\build\x64> python tests\utils\stl-lit\stl-lit.py -v C:\STL\tests\std\tests\GH_XXXX_meow
```

Let's assume one of the tests fails an assert and we want to debug that configuration. `stl-lit` will conveniently print
the build command, which is far too long to provide here in full. The important part is to add the following options to
provide debug symbols: `/Zi /Fdbark.pdb`.

You can replace `bark` with any descriptive name you like. Add these before the `"-link"` option in the command line
and recompile. Example:
```
C:\STL\out\build\x64>cl "C:\STL\tests\std\tests\GH_XXXX_meow\test.cpp" [... more arguments ...]
"-FeC:\STL\out\build\x64\tests\std\tests\GH_XXXX_meow\Output\02\GH_XXXX_meow.exe" /Zi /Fdbark.pdb "-link"
[... more arguments ...]
```

You can now start debugging the test via:
```
devenv "C:\STL\out\build\x64\tests\std\tests\GH_XXXX_meow\Output\02\GH_XXXX_meow.exe"
"C:\STL\tests\std\tests\GH_XXXX_meow\test.cpp"
```

However, this might not work right away, as Visual Studio may complain about a missing `msvcp140_oss.dll`. The reason
is that the STL builds those and other DLLs itself and we should under no circumstances overwrite the installed ones.
If you are testing one of the configurations with dynamic linkage (`/MD` or `/MDd`) the easiest solution is to add the
build folder to your path:
```
set PATH=C:\STL\out\build\x64\out\bin\amd64;%PATH%
```

# Editing And Testing The Debugger Visualizer

### Modify The Visualizer
Expand All @@ -375,7 +413,6 @@ You can add the natvis file to any Visual Studio C++ project if you right click
select the STL.natvis file. After doing this you should be able to see your changes in a Visual Studio debugging
session.


# Block Diagram

The STL is built atop other compiler support libraries that ship with Windows and Visual Studio, like the UCRT,
Expand Down