Qt Creator and Clang

As mentioned in the recent editor news blog post, we have been working on integrating Clang as a replacement for our current C++ code-model in Qt Creator. While we are still in an early stage, we feel that it is now in a state where others can look at it, play with it, and even contribute to it.

Now I hear some people thinking: "But I already have a compiler!" I get this reaction a lot when I tell this to people. So first of all: a code-model is not a compiler, so you still need your own favourite one.

What is a code-model, what does it do?

The code-model is the part of an IDE that "understands" the language you are using to write your application. It is the framework which allows us to provide:

• code-completion
• highlighting (both syntactically and semantically)
• navigation (the locator, follow symbol, etc)
• introspection (the class browser, the outline, etc)
• diagnostics and tool-tips
• find usages and renaming
• refactoring actions

As such it needs to have a parser for the language, and the semantic analyses. The only difference with a compiler is that a code-model does not generate an executable.

Why switch to Clang?

Switching from our current code-model to Clang gives us some important improvements. Most notable of these is that Clang is an actual compiler which means that the information we get out of it is correct. So the feedback you get through warning and error markers is the same as the compiler will give you, not an incomplete set or a close approximation. When we are talking about those diagnostics: Clang focusses on detailed information for diagnostics, which is really useful in those rare cases where a developer makes a typo :-)

Also, Clang already supports C++98/03, C89 and C99, Objective-C (and Objective-C++), and C++11 support is in active development.

But all those good things do not come for free. When using Clang as code-model it does not need to generate object files, but it still needs to parse and analyse the source files. For small projects which only use STL, this works okay. But for bigger projects like Qt Creator, which uses large parts of Qt, processing a single file and all the included files can take a while. For this we use one or more pre-compiled headers, and with the current integration you will have to manually add them to your project or point Qt Creator to it. More details below.

What is switched already?

The current integration uses Clang for:

• syntactic highlighting ("keyword highlighting") and semantic highlighting (types/methods/fields/labels/etc)
• code-completion
• diagnostics
• code navigation

Please notice that some of the above items still only work in a limited range of situations.

Where to get it

First you need to compile Clang/LLVM, either version 3.0 or trunk. Build instructions can be found on the LLVM website. If you want to use git instead of svn, use llvm.git and clang.git. Please make sure that you do a release (optimised) build!

The Qt Creator integration is in the wip/clang branch in the git repository on gitorious. Building Qt Creator works as usual: run qmake, then make, and depending on your platform a make install. If you are on Linux/Mac and do not have the directory with llvm-config in your path, or if you are on Windows, you can use the LLVM_INSTALL_DIR qmake variable to tell qmake where to find the Clang/LLVM libraries and headers.

When starting Qt Creator, make sure the clang libraries are in the library search path by including the <llvm-install-prefix>/lib directory in your LD_LIBRARY_PATH (Linux), or in the PATH (Windows).

How to use it

You can use this version of Qt Creator as you would do with any other version. However, there is one thing to keep in mind: if you use big libraries like Qt or Boost in your project, you can speed up the code-model (and therefore the highlighting and completion) quite a bit by defining one or more pre-compiled header(s). For a typical Qt project, this header can consist of:

#ifndef PCH_H
#define PCH_H
#include <QtCore>
#include <QtGui>
#endif // PCH_H

Only header files that do not change (so those which are part of the system), otherwise the pre-compiled header needs to be re-generated, which in turn negates the caching advantage.

There are two ways to do tell Qt Creator to use this header as a cache:

• If you use qmake, then you can set the PRECOMPILED_HEADER variable in your .pro file:
  PRECOMPILED_HEADER = pch.h
  Depending on the qmake spec file for your compiler, this pre-compiled header might also be used for compilation.
• When you go to the "Projects" mode, you will see an extra tab with "Code Completion Settings", where you can select a "custom" header. When selecting this option, the code-model will use that header as a cache, but the compiler will not use it.

How to contribute

As mentioned at the beginning of this post, this release is mainly targeted towards people who would like to contribute, because no, we are not finished. There is still quite some work to do, so if you feel like helping out, let us know! The main communication channel is the qtcreator mailing-list, and #qt-creator on freenode.