TLDR:
Understand parses code like a compiler and to do its best work it needs to know compiler build options like include paths and macro definitions. We use “bear“, an open-source tool, to watch builds from a Makefile built project (bitcoin) and create a very useful Understand parse with it.
Details:
We have a parser (or parsers) for each language we support. For C/C++ variant languages we usually need to know the include paths and macro definitions sent to the compiler when a project is built.
For CMake and Visual Studio built projects we read project artifacts to get parsing information (compile_commands.json for CMake, and various project/solution files for Visual Studio).
Some projects, however, use Makefiles or other build systems. We could try to make a parser of Makefiles, but they are often too dynamic and integrated in with shell scripts or other building programs.
On Windows, we can “watch” the build from inside the Understand New Project Wizard and pick up those files, but for security reasons that’s not an option on Mac, so we use an open-source tool called “bear”:
rizsotto
which watches you build and detects the necessary compiler commands and then generates a CMake format “compile_commands.json” file.
tip – you can build bear, or grab binaries from the bear website, or as I did use “brew install bear” to put it on my OSX Mac.
I used it to build an Understand project that successfully parses and analyzes the source for the core “bitcoin” mining daemon.
Here’s what I did:
- Figured out how to build “bitcoin”. This was not trivial, but once I got the right dependencies installed I was able to run their automake and configure scripts and generate a set of Makefiles to build for my OSX Mac.
- I made “bitcoin” using the normal make target but on the “bear” command-line:
which eventually finished and a “compile_commands.json” file was now available and full of good project building information that Understand can use:
My next step is now easy…. fire up Understand, make a new project and let it scan the “bitcoin” directory for things it recognizes can help with project building:
It found a bunch of MSCV project files, which won’t be of use on my Mac machine, but here is the special one that will help:
I chose “Import” and it loaded up 1674 project files and started parsing them:
Parsing the 479 source files (.c/.cpp files) took a couple of minutes, and I ended up with 15 compile errors and 37 warnings – which roughly matches what I got when I did the command line make. I’ll clean up the compile errors, but I can get to work looking at “bitcoin” with a few errors here and there.
How much effort?
Total time from starting to generating the Understand project?
A little over an hour divided up this way:
- 15 minutes for me to figure out how to build “bitcoin” on my Mac
- 35 minutes for it to build while “bear” watched. I had lunch while I waited.
- 10 minutes to make the Understand project and make the above graphs.
Summary:
If you can build your software using Make or shell scripts, “bear” can watch and tell Understand what it needs to know to properly analyze that source code.
