Just like professional documents have editorial style guides, so does professionally-made hobby code. It ensures we have a consistent style throughout the code making it easier to read and contribute to the code, and helps catch out bugs as well!
I spent time over the last couple of days getting the clang-tidy up and running for Mudlet. It’s a tool to verify our C++ code matches our style guide – and also helps finds bugs along the way. It comes with an extensive array of checks (https://clang.llvm.org/extra/clang-tidy/checks/list.html).
Now in an ideal situation we’d have any warnings right on the PR itself as it was submitted, and without any additional slowdown in the approval/build time – so that’s what I worked towards. I found a premade action in Github’s marketplace that did the job – https://github.com/ZedThree/clang-tidy-review, but it didn’t work out of the box.
First, it needed a compile_commands.json generated. This file is becoming the standard in representing the commands to compile a project across all major industry compilers, which is good, but it’s also one that we’ve never needed before so we didn’t have the infrastructure to generate it. What complicated matters is that Qt has some normally helpful tools to post-process the source code and because they weren’t accounted for out of the box, not a complete compile_commands.json was generated.
Now it’s possible to just compile the entire Mudlet and thus we’ll have a compile file at the end, but that would mean that compiling Mudlet + analyzing the code = longer build times than just when we compile Mudlet. That wasn’t acceptable, so I worked on a way to generate the complete file without compiling – which from my research doesn’t seem like its something that’s been done by any other Qt projects. I dug into that, and thanks to keneanung and and the #qt Slack channel we’ve worked it out – so I’ll do a separate ‘howto’ post on that later for the Qt community.
Now that we got all of the compile instructions sorted out, we intentionally broke one of the files, ran a check, and… nothing. It didn’t work. Tried using clang-tidy locally on my machine – it all worked fine. Reached out to the actions’ creator as well, and it worked fine for him on his machine. Weird eh?
It was time to dig out a trusty tool I’ve learnt that’s essential in debugging and more importantly, saving time – tmate. It allows you to connect to any Github CI machine while it’s running the job, peek around and run commands straight on it. Because the issue was only manifesting itself in the Github builder and not locally, this tool is amazing for time saving – instead of making a small change and having to wait 10mins before seeing the results, changes were visible real-time.
Digging deeper into this rabbithole, I worked out that the tool was learning about which code was changed from one source, but actually analysing a different version of the source code – so the line #’s that were changed didn’t actually match up with the code it was analyzing. That’s been fixed, and the fix was reported to the actions author, and that’s how the open-source community benefits and builds upon each other :)
The analysis tool is just about ready to go and soon will be in use by Mudlet. It’s likely we’ll have to tweak the checks it does to find the right balance between helpfulness / annoying-ness – for a start I tried to match our current style guide as close as possible + some no-brainer checks.
What’s also really nice about this whole clang-tidy setup is at this point it’s integrated into every IDE out there – Qt Creator, CLion, VS, VSCode, you name it, so developers can get the same code checks locally and don’t have to wait for a CI build to complain at them.
