Abstract: Understand makes it easy to know where to start looking to track down a bug, Find where to place breakpoints, and identify which locations in the code need to be updated.
Today’s bug report: The user can’t build an Understand project from their CMake project because the compile_commands.json file won’t load. The error returned is “compile_commands.json is not a valid import file. Stopping Add”
What can Understand tell me about this error? First, if I didn’t already know where the error came from, I could use instant search to find it. With Instant Search, I’ll specify that I’m looking for a string and start in the middle of the message since the file path (compile_commands.json) is unlikely to be part of the literal text.
Clicking on the result brings it up in the Previewer since the Previewer is open:
From the code, either the importer (fi) was null or the status was not set. At this point, I could put a breakpoint on the location and just run the code to see what’s going wrong. Unfortunately, the problem doesn’t reproduce on my machine.
I can do a little more digging with Understand even without reproducing the problem. Let’s check the status call. I’ll Ctrl+Click on it from the Previewer to go to the definition.
Now I need to find the mStatus variable. I can Ctrl+Click on it which would also navigate to the definition in the Previewer or use Ctrl+i (or right-click menu -> View Information) to just update the information browser.
The file path (compile_commands.json) is for a CMake file, so I’ll click on the first CMakeImporter reference to bring it up.
If the status is the problem, then either the file path was invalid or the json document constructed from the file was invalid (null or not formatted as an array). At this point, I really do need a machine that reproduces the problem so I can step through the code. But, there is one other piece of information I could get quickly from Understand. If I open CMakeImporter in a full editor instead of the Previewer, I can see the Git Blame margin that I always have on.
This shows me that the file has recently been changed (by me). The recent change likely introduced the error. I can click on the change in the Blame Margin to bring up a diff:
The problem is likely related to the recent change to use ReadFile instead of QFile to open the file. This hypothesis is supported by the fact that the engineer who reproduced the problem (Thanks Kevin!) also traced the problem to having started around December 2.
With the headstart from Understand and a machine from Kevin that reproduces the problem, I can put a breakpoint at the beginning of the CMakeImporter constructor and step through. ReadFile did in fact cause the problem. The read function returned empty contents because ReadFile enforced that files were smaller than the “max file size parsed” value in project settings. That value is 10 MB by default and the file Kevin used was 11 MB. Mine was only 7.9 MB and therefore didn’t show the problem.
To fix the problem, I need to add a parameter to the ReadFile::read function to skip the size test for imported files. I add that for CMake, but I also need to check the other importers (Visual Studio and XCode). There are several different overloads of read. How can I quickly find connections from the import library to readfile? I used a Called-By tree on readfile.h to find all the files that call functions in that header file. Grouping by directory structure lets me focus on the edge from import into readfile.
Clicking on the edge with the dependency browser open shows me all the references contributing to that edge.
Now I can quickly find all the calls I need to update to ensure the import files are read even if they are over the “max file size parsed” limit. The fix will be in build 1093.
