Ivan Donchevskii

ClangFormat plugin in Qt Creator 4.9

Published Wednesday April 17th, 2019
13 Comments on ClangFormat plugin in Qt Creator 4.9
Posted in C++, Compilers, QtCreator | Tags: , , , ,

Starting with Qt Creator 4.8 we ship the new ClangFormat plugin based on the LibFormat library. In 4.9 it is not experimental anymore but still disabled by default. Let’s shortly recall the history of ClangFormat support and why we’ve decided to have a new plugin.

Beautifier plugin

The clang-format tool could already be used in Qt Creator before as part of the experimental Beautifier plugin along with Uncrustify and Artistic Style. If you have this plugin enabled you can simply invoke the executable by the shortcut or apply formatting on save. Pretty straight forward. You edit your code, you format it when you’re done. We’re not planning to remove any of this functionality because it serves its purpose pretty well and can be customized to the clang-format version that you prefer to use in your project.

But Beautifier does not cover other important cases, it’s only a tool to finalize your code.

Indentation with ClangFormat

I assume that you already use Ctrl+I to have your code indented. The same thing happens when you press Return or move/paste some code into the C++ editor. Since ages Qt Creator has its own indentation engine to provide you the proper white space where necessary. At least it should be proper. But the reality is that Qt Creator indentation still does not fully support modern C++. For example we already have these bugs for quite a long time Qt Creator indentation bugs and they always raise our desire to fix them altogether.

So the main purpose of our new ClangFormat plugin is to indent the code properly. But it can potentially bring much more in the future.
To enable the plugin go to Help > About Plugins, click on ClangFormat and restart your Qt Creator.

Features

With the plugin you can not only indent but also apply standard clang-format formatting which will optimize lines if possible, remove trailing white space and empty lines, etc. We have decided that it’s a good idea to apply formatting on the same hotkey as indentation (Ctrl+I) but only when the checkbox is selected in Tools > Options > C++ > Code Style > ‘Format instead of indenting’. There are a few more checkboxes to customize the plugin behavior. ‘Format while typing’ will try to reformat code automatically if possible and ‘Format edited code on file save’ will go through and format the edited lines in the file you are saving.

By default the plugin uses the .clang-format configuration which it finds according to the standard clang-format rules. You can override them with either global Qt Creator settings or with specific settings for your project.

Limits

Because clang-format was never meant to be used as an indentation tool we have to use a modified version of the LibFormat library. It helps us to keep the line breaks if we are sure they must remain. To force indentation for empty lines we have to supply clang-format with some extra code which should behave as if it’s a valid code. In addition clang-format can be confused by incomplete code so if you have something like this:

int main() {
foo(//Press CR here
}

the default clang-format won’t properly format the parameters until you provide it a closing ‘)’. In such cases we try to predict the possible code and trigger the formatting with modified text but it is not very reliable yet. So if you encounter problems like that you might just manually press Ctrl+I to reformat such piece of code (or save the file) when the statement is complete.

Get Qt Creator 4.9.0

The opensource version is available on the Qt download page, and you find commercially licensed packages on the Qt Account Portal. Qt Creator 4.9.0 is also available through an update in the online installer. The Qt Creator Manual 4.9 is available here. Please post issues in our bug tracker. You can also find us on IRC on #qt-creator on chat.freenode.net, and on the Qt Creator mailing list.

Do you like this? Share it
Share on LinkedInGoogle+Share on FacebookTweet about this on Twitter

Posted in C++, Compilers, QtCreator | Tags: , , , ,

13 comments

Michael Möllney says:

I tried the ClangFormat plugin, but failed to generate the Whitesmiths style https://en.wikipedia.org/wiki/Indentation_style#Whitesmiths_style.

I like the style because of the fact that it shows, that the block contains braces and statements.
This style can be set with the former Code Style Editor easily: Check some options in the indent braces tab.
How can this be achieved with the ClangFormat….

As a side note: I like the old code style editor: switch an option and see directly the effect. In the new ClangFormat Editor you have to “Apply” each time you change a setting to see, if the effect is what you want. Maybe something like https://zed0.co.uk/clang-format-configurator/ would be nice…

Ivan Donchevskii Ivan Donchevskii says:

As far as I see here https://reviews.llvm.org/D6833 Whitesmiths style was planned but is still not submitted. You can ask the clang-format developers if they plan to proceed.
Immediate formatting requires a bit more complex configurator, with checkboxes for example. Currently we work with plain text and do not check in advance which parameters are valid.

Konstantin Isakov says:

It seems ClangFormat supports a small number of existing indentation styles well, but doesn’t seem to have enough knobs to customize it to one’s liking if the style desired is not merely a minor variation of the supported ones. For instance, I prefer to put each ‘if’ on a separate line, which includes breaking before ‘else’, e.g.:

if ( a )
foo();
else
if ( b )
bar();

Apparently this is not possible with ClangFormat, it would always put ‘else if’ together on the same line. Even if I break manually after ‘else’, it would indent the following ‘if’, making me having to unindent it back each time.

At this point I would have three options:

1) yield and switch to having ‘else if’ on the same line, which I think is less readable,
2) submit a patch to ClangFormat and hope they will include it and not reject it on the grounds that I’m the only person needing it, or
3) switch back to old Qt Creator formatting model, which, even though not being perfect, at least doesn’t incessantly indent my ifs in an undesired way.

Overall, I was having high hopes for ClangFormat, but it seems option 3 is still the most sensible one for me.

Konstantin Isakov says:

Note: there should be two spaces before foo() and before bar() in my example — the comment system has apparently eaten them.

Ivan Donchevskii Ivan Donchevskii says:

You can also disable all checkboxes and use ClangFormat only for indentation – it won’t try to reformat your code and put ‘else if’ on the same line.

bylee says:

clang-format support is very impressive. Now I am very happy with properly indented >> brackets.

beeka says:

I am trying to override the clang format configuration file with one generated by the zed0 configurator. If you miss of the carriage return after the “…” line you get a rather unhelpful “invalid argument” error. My config was quite short, so I took out each option in turn but without resolving the error.

Also, I am new to clang-format, so expanding on ” the plugin uses the .clang-format configuration which it finds according to the standard clang-format rules” would be helpful… what do I name the file so that it will find it on windows and linux and for all sub-projects? It is a bit confusing that the options are separate, and may conflict, with those on the beautifier tab: I don’t have clang-format installed and was expecting the options on the “Clang Format” tab to be editable and affect indentation. It would be better if the file that is being detected was shown in the Qt Creator config options. Also not clear when the external .clang-format is re-read (if it is at all).

Finally, would it be feasible to add an option to reformat on save only those portions of the file that has been modified? We have a very large code base that has operated without any automatic enforcement of coding style. I am concerned that forcing the whole file to be updated for style will make code reviews difficult to follow. Ideally I would make one “reformat all” commit but this is not practical for all projects (particularly the ones with ‘interesting’ branches would lead to complicated merges)… and there is no “reformat project” option in Qt Creator.

Ivan Donchevskii Ivan Donchevskii says:

In order to have better feedback about correct/incorrect style we need to make better UI for it, I believe we will go in that direction.
“the file that is being detected was shown in the Qt Creator config options” – the thing is that this file can be different for different source files in your project. What you can do is to open the .clang-format configuration file for the currently edited file by selecting “Open Used .clang-format Configuration File” in the C++ editor context menu.
“reformat on save only those portions of the file that has been modified” – this is actually what we currently do, we do not reformat the whole file.

jason says:

Technically for:
int main() {
foo(//Press CR here
}

It’s not CR, it’s LF you’re hitting. You’re feeding a line, not returning a carriage.

Ivan Donchevskii Ivan Donchevskii says:

I probably should have written something like instead 🙂

Slava says:

I enabled the plugin in Help->About-plugins, restarted and still do not see anything in Tools->Options->C++->Code-style.
In beautifier clang-format works OK, but that is not so useful as proper on-the-fly indentation. Arch Linux x64, QtCreator 4.9.0.

Ivan Donchevskii Ivan Donchevskii says:

I’m afraid that plugin works only with Qt Creator from the installer or if you build it yourself with LLVM/Clang from our repository. This is the case because we currently need a custom patch on top of Clang and without it (with upstream clang-7 or 8) the ClangFormat functionality is disabled. We currently think to add some message about that but it’s not yet there in Qt Creator 4.9.

MJ says:

I don’t think ctrl+I was a good decision. Why won’t you just adopt Alt+Shift+F shortcut that works on at least 3 popular IDE on the market? Unification is better than isolation.

Commenting closed.

Get started today with Qt Download now