In my previous post I talked about the Woboq Code Browser. While the instructions for compilation and usage are quite good, in this post I will try to summarize them for a specific use case: the generation of HTML files for a KDE/Qt application using the CMake build system, on the Linux platform. These instructions should also works for a generic CMake project using plain C++.

Requirements

This post assumes that you are a Qt/KDE developer on a Linux system. This means that you should already have all the needed stuff (git, cmake, etc.). Just make sure to have clang (and llvm-config) installed under /usr/bin. This makes the process easier.

Compilation

First of all, you need to compile the codebrowser.

Clone the codebrowser source files:

$ git clone https://github.com/woboq/woboq_codebrowser.git
$ cd woboq_codebrowser/

Start compiling:

$ mkdir build && cd build
$ cmake .. -DLLVM_CONFIG_EXECUTABLE=/usr/bin/llvm-config -DCMAKE_BUILD_TYPE=Release
$ make

Now you have the two codebrowser components: build/generator/codebrowser_generator and build/indexgenerator/codebrowser_indexgenerator.

Installation

Since clang expects to find the system libraries in ../lib relative to the executable, you have two choices:

Option 1: install the codebrowser components.

In this way you can use the codebrowser everywhere:

$ sudo install -m755 generator/codebrowser_generator /usr/bin
$ sudo install -m755 indexgenerator/codebrowser_indexgenerator /usr/bin
$ ln -s /usr/lib .

I don’t like the latter because you need to type the extended path when using the codebrowser; but it’s up to you.

In either cases, you need to copy the data/ directory to the directory that will contain the generated HTML files. The output directory in this example will be ~/public_html:

$ cp -r ../data/ ~/public_html

Usage

Now you are ready to generate the HTML for your KDE or Qt foo project. Just make sure that you have a git local repository for foo.

Generate the compile_commands.json. This will tell to the codebrowser which source files has to process:

$ cd /path/to/foo/local/repo
$ mkdir build && cd build
$ cmake .. -DCMAKE_EXPORT_COMPILE_COMMANDS=ON

Then generate the source code HTML pages. The output directory in this example will be ~/public_html:

$ cd ..
$ git ls-files | egrep "\.cpp$" | xargs codebrowser_generator -b build/ \
-p foo:$PWD:`git describe` -o ~/public_html/foo

If you are interested, codebrowser_generator -help will explain the meaning of the used options.

Last step: generate the HTML index:

$ codebrowser_indexgenerator ~/public_html/foo

Done. Simply open in your preferred browser ~/public_html/foo/index.html and enjoy it!

(Optional) Optimization

By default, for (e.g.) a KDE project the codebrowser generates not only the code for the project itself, but also for all the included libraries. This translates in (at least) the whole KDE, the whole Qt and many C++ standard headers. If you want to upload the generated HTML on your webserver, this might be a problem if you have storage concerns, for example if you are on a shared server. Fortunately, the codebrowser gives you the option to link external generated libraries. Just use the -e option like in this way:

$ git ls-files | egrep "\.cpp$" | xargs codebrowser_generator \
-e include:/usr/include:http://code.woboq.org/kde -b build/ \
-p foo:$PWD:`git describe` -o ~/public_html/foo