Fix Qt Creator code highlighting on Windows/MSVC projects

Have you ever noticed code highlighting disappearing in Qt Creator for some projects, without any apparent reason?

Can't get Ctrl+Click to work on any class name or function name anymore?

Maybe you have ignored it at first, got used to it, and decided it's just one of those things that just "happen sometimes"; or maybe you have tried opening other projects and seen everything was fine there.

My colleagues and I have been there ourselves, we know how puzzling this can be. Luckily enough, the issue is as elusive as it's easy to fix.

Check your project and see if it falls into one of the following two scenarios:

1. You are using spaces in a compiler option

Some of Microsoft's "cl" C++ compiler options have a syntax that allows for spaces between the option and its associated value, that is usually a directory or a file path. This is the case for other compilers too, think about -isystem /path/to/include/dir in GCC or Clang.

However, these parameters aren't always well processed by Qt Creator, specifically when using the MSVC compiler; the rare examples where blanks are accepted work fine for GCC and Clang.

The only solution for this as I'm writing this post is to remove such spaces from compiler arguments.

So, for instance, if you are using /FI C:\force\included\file.h then you need to change it to /FIC:\force\included\file.h or even better /FI"C:\force\included\file.h" to avoid issues with paths containing spaces.

Note also that, although the official documentation doesn't explicitly state it, some compiler options such as /wd xxxx and /we xxxx work fine even with a space between the option name and the compiler warning code. However, Qt Creator's Clang code model will break also in this case.

2. You are using some "exotic" MSVC flags

Sometimes, even if no spaces are around, code highlighting may still be broken on your project.

This can happen if you're using some options that aren't currently handled by Qt Creator, but will be starting from Qt Creator 4.11.

One example above all is the set of experimental options such as /experimental:external and its companion options /external:I and /external:W.

The main reason why this is happening is that the option is passed to Clang to build the code model of the project being developed.Clang doesn't support argument syntax starting with a forward slash (/), and will interpret such options as file names instead. These "files" won't be found and clang will consequently fail to parse the codebase.

Note that some compiler options are already being ignored by Qt Creator itself, and therefore you don't see the issue if you use for instance /wdxxxx, which is a valid cl option but not a Clang one. This is however not the case for the options mentioned above.

There are two ways to fix this:

• Replace forward slash (/) with a dash (-) when passing the option to the compiler: this way Clang will correctly interpret it as a compiler option and if it doesn't know it it will just ignore that option.
• Add any option breaking your code model to the QTC_CLANG_CMD_OPTIONS_BLACKLIST environment variable. This way bad options won't be forwarded to Clang at all and your code highlighting will be ok.
  For instance QTC_CLANG_CMD_OPTIONS_BLACKLIST=/experimental:external;/external:I;/external:W

You can see how the fixes work in real qmake and CMake projects in the screenshots below:

Did you find this post useful for a project you are working on? Have you ever had to deal with elusive bugs like this one?
Let us know in the comments below!