Hiding detail namespaces in Doxygen documentation

A common idiom in modern C++, pioneered by the developers of the Boost libraries, is to separate symbols that form part of the implementation of your module (that is, don’t form part of the public API) but that have to be publicly available into a separate sub-namespace, by convention named detail.  This is especially common in header-only libraries, where any symbol you define will leak into the translation unit that includes your header.  While the results of the Modules ISO C++ study group may provide a better solution to this eventually, the current solution is to hide these symbols in a detail namespace; even though these are still public symbols, the user can ignore all symbols in detail.

This can be made to work with Doxygen, the JavaDoc-style documentation generator for C++, very easily.  Because the symbols in any of the detail sub-namespaces are not part of the public API, we don’t generally want them in the API documentation generated by Doxygen. Luckily, though, Doxygen provides a configuration flag to ignore certain symbol patterns in generating documentation.  To get Doxygen to ignore any detail namespaces and any symbols within them, just add

EXCLUDE_SYMBOLS = detail

to your Doxyfile. Of course, if you have a different Doxyfile for internal documentation builds where you want your detail namespaces, you can leave this line out and generate documentation with those private symbols included.

This is the approach I’m taking with the Humm and Strumm Project’s API Documentation, on one of my branches to clean up our documentation. Until the next release, the above link will point to the 0.7 documentation, not the cleaned up 0.8 documentation. I may, along with our nightly builds, build the documentation every night and publicly host it if I have time before the next release.

Fixing warning MSB8029 with CMake and MSVC12

This week I fixed a bunch of warnings on the Humm and Strumm nightly build Windows machine that didn’t actually relate to our code, but instead our build system.  We use a CMake build system with (what I think is) a relatively standard out-of-source build pattern.  On the nightly machine, though, when the engine was built using “cmake –build”, we’d see 16 of the following warnings:

C:\Program Files (x86)\MSBuild\Microsoft.Cpp\v4.0\V120\Microsoft.CppBuild.targets(389,5): warning MSB8029: The Intermediate directory or Output directory cannot reside under the Temporary directory as it could lead to issues with incremental build.

This warning is a useful warning in many cases, where an incremental build could speed up build times, but since we clear the build directory every night on our virtual machines, we can’t do an incremental build.  Even worse, since this is the way CMake builds are structured, we can’t easily turn the warning off.

Googling, I found almost no answers, until I came across this question on MSDN.  Apparently, if you add <IgnoreWarnIntDirInTempDetected>true</IgnoreWarnIntDirInTempDetected> to the macros section of your Microsoft.Cpp.x64.user and Microsoft.Cpp.Win32.user files that are hidden away under %LOCALAPPDATA%\Microsoft\MSBuild\v4.0\, these warnings will be globally ignored.  In my case, since this machine only does nightly builds, and will never do incremental builds, that’s a pretty good solution.

I hope if anyone else runs into this problem, this will be helpful.

GNU Coding Standards with clang-format

As an Emacs user, I write most of my C++ code using cc-mode. cc-mode, though, works on regular expressions, which sometimes fail to parse correct C++ code and leave the file inconsistently indented. Even worse, cc-mode doesn’t have support for C++11 features yet. This has served as an annoyance to me for the past few years, but there hasn’t been any alternative until recently.

A new tool, clang-format, is built using the Clang C++ compiler and formats the code by first lexing and parsing it. While this is slower, it leads to better results and even integrates with Emacs. I’ve been unable to use clang-format in most of my projects, though, because both for Humm and Strumm and for personal projects, I tend to use the format from the GNU Coding Standards, adapted to C++, and GNU formatting was not yet supported by clang-format.

I sat down to write a patch for it today, but I found that nine days ago, support was added to the Clang repository. I’m very happy about this news, because it means that the 3.5 version of Clang should ship with it. It’s even in the clang-format-3.5 package in Debian Sid (which, as I write this, corresponds to Clang’s SVN revision r197556), so if you don’t want to try it out from the SVN version and you’re a Debian user, you can just grab it from there!

OpenPGP Key Transition

This is a short notice that I am transitioning from my old OpenPGP key to a new 4096-length key.  You can find an official notice of this transition here, signed both by my old key and my new key.  Although you can find information about how to acquire my new key in that document, I’ll also provide the key fingerprint below.

pub   4096R/DEBFA176 2013-12-10
      Key fingerprint = A66F 5099 CC43 0B02 5B53 D0B9 7F2A 9552 DEBF A176

Humm and Strumm: Move to Sourceforge is (mostly) complete

The past few months have been busy for me with the Humm and Strumm Project.  After we decided to move to Sourceforge from Google Code (seeing as Google Code will stop providing downloads space for projects soon), I’ve had to set up our new Sourceforge project, move our mailing lists, git repository, and wiki to the new host, and set up our new website.

Because Sourceforge gives us project web space, I decided to move our CDash testing dashboard, Doxygen API documentation, and website.  The website’s just a simple Drupal site, but with a custom theme, to match our old blogger website.  As an outsider, I have to say that Drupal has a lot of documentation, but that it’s not terribly helpful to a first-time user.  It took me much longer than I would have liked to get the simple theme going.  Sourceforge is also not ideal for Drupal, because they have low memory usage limits (which I ran into when trying to use Views) they don’t allow outgoing internet connections (so no OpenID login, feed aggregation, or even automatic updates), and their database seems somewhat slow.  Although there are still a few things I have left to do, like integrating the SMTP server with both our Drupal website and our CDash dashboard (which requires a patch to CDash), I think the website is basically done.

This means that I’m able to focus on development now. I think that there will be a release in the next month or two with some major changes that have been brewing since 0.6.1.  I’m also going to look into coercing clang-format into working with the GNU-like style we use.  Emacs’s C++ major mode still hasn’t been properly updated for C++11, so making Emacs use clang-format is a better solution at the moment.

std::cout << "Saluton, Mondo!\n";

I’m Patrick Niedzielski, and this blog is going to be my personal home one the internet. You can find out about me on the about page.

I’ll be posting pseudo-regularly about development (especially on the Free Software project Humm and Strumm (the website is not up yet)), conlanging, jazz harmonica, and Esperanto. I’m especially interested in high-performance concurrency and proper software engineering practices, especially in C++.

I hope to get a résumé posted shortly.