Step-by-step guide to using Uncrustify in Code::Blocks

The default source code formatter in Code::Blocks is AStyle. It’s ok as a general purpose formatter, but it lacks fine-grained control and thus the ability to adhere to a very specific coding style, such as the OF code style specification. Uncrustify on the other hand is a highly configurable, easily modifiable source code beautifier. It offers more options than AStyle, and is the basic tool for OF code formatting.

This post is step-by-step guide to setting up and using Uncrustify in Code::Blocks. Let me start with a disclaimer that this information is provided as-is and I am not responsible for missing code as a result of running this. But don’t let me scare you away, it really works quite nicely. :smile:

SETTING UP

  1. Download Uncrustify via this page. Unzip the downloaded file somewhere on your computer. Let’s call the folder where Uncrustify is installed [UNCRUSTIFY_FOLDER]. For example on my computer this is “C:\Coding\uncrustify-0.61.3-gf65394e-win32”.

  2. Download the OF code style config file for Uncrustify from here and place it in the folder [UNCRUSTIFY_FOLDER]\cfg\. For example on my computer the final location of the config file is “C:\Coding\uncrustify-0.61.3-gf65394e-win32\cfg\openFrameworks_style.cfg”.

  3. In the Code::Blocks menu, go to Tools, then Configure tools…, then click the Add button.

  4. Use the following settings, where of course the [UNCRUSTIFY_FOLDER] locations are correctly filled in for YOUR computer:

    Name: Uncrustify Code Format [RUN]
    Executable: [UNCRUSTIFY_FOLDER]\uncrustify.exe
    Parameters: -c [UNCRUSTIFY_FOLDER]\cfg\openFrameworks_style.cfg --no-backup ${ACTIVE_EDITOR_FILENAME}
    Working directory: ${PROJECT_DIR}
    Launching options: Launch tool visible (without output redirection)

  5. Click Ok and you are done!

USING

  1. Open an existing workspace and then a .h or .cpp source file.

  2. Add a few tabs and spaces that will have to be formatted.

  3. Save the file! This is important, since the formatter is an external tool, so it will open the file from the disk.

  4. In the menu go to Tools, then click on Uncrustify Code Format [RUN]. This will run the script.

  5. A command prompt window flashes and after that you are asked if you want to reload the file because it has been modified outside the IDE. Click yes to open the formatted file.

SETTING UP WITH AUTO-SAVE

It’s possible to add more then one tool. When you add a tool using the settings below, the source file is saved in CB before the formatter is run, thus ensuring that the most recent file is formatted. The only downside is that this only works with a console window, which you have to close by pressing any key.

Name: Uncrustify Code Format [SAVE]
Executable: [[GetEditorManager().SaveActive();]] cmd.exe /c “timeout” “1” && “[UNCRUSTIFY_FOLDER]\uncrustify.exe”
Parameters: -c [UNCRUSTIFY_FOLDER]\cfg\openFrameworks_style.cfg --no-backup ${ACTIVE_EDITOR_FILENAME}
Working directory: ${PROJECT_DIR}
Launching options: Launch tool in a new console window and wait for a keypress when done

ADDITIONAL REMARKS

  • You can change the order the tools appear in the menu via Tools > Configure tools > Move up / down.
  • The CB console will report on launching the tool and when it is has finished succesfully it will say “Tool execution terminated with status 0”.
  • If no changes have been made as a result of formatting, then you will not get asked to reload the file.

WARNINGS

  • There is NO undo, there is NO going back. Your old file has been overwritten. If you don’t like the formatting, you can NOT go back to the way it was, because the old file is gone.

  • If you use the [RUN] script on a file that was changed, but not saved, all your changes since you last save are gone. So make sure to either save the file and then choose the [RUN] script or choose the [SAVE] script, which will save your file for you, before running the formatter.

Nice! Regarding the “No undo” - here it comes in handy if your code is under git/version control. :wink:

Indeed. And for someone who needs a quick safeguard, it’s of course also possible to copy the code into the clipboard before running the code formatter. Thought it was better to add some clear warnings now, than for someone to realise this afterwards. :grin: