Home

Awesome

AppVeyor Coverage Status <a href="#"><img src="https://img.shields.io/badge/C++-11-blue.svg?style=flat-square"></a>

Uncrustify

A source code beautifier for C, C++, C#, ObjectiveC, D, Java, Pawn and VALA

Features

</details> </details> </details> </details> </details> </details>

Here is an example configuration file, and here is a before and after C source example. That should give you a pretty good idea of what Uncrustify can do.

Binaries

Pre compiled binaries for Windows can be downloaded here.

Build

Python is an "interpreted high-level programming language for general-purpose programming", for this project it is needed to extend the capabilities of CMake.

CMake is a tool that generates build systems (Makefiles, Visual Studio project files, Xcode project files and others).

To generate a build system for Uncrustify using CMake, create a build folder and run CMake from it:

$ mkdir build
$ cd build
$ cmake ..

(Use cmake -G Xcode .. for Xcode)

Then use the build tools of your build system (in many cases this will simply be make, but on Windows it could be MSBuild or Visual Studio). Or use CMake to invoke it:

$ cmake --build .

If testing is enabled, CMake generates a test target, which you can build using your build system tools (usually make test). This can also be invoked using CTest:

$ ctest -V -C Debug

There is also an install target, which can be used to install the Uncrustify executable (typically make install).

A note on CMake configurations

Some build systems are single-configuration, which means you specify the build type when running CMake (by setting the CMAKE_BUILD_TYPE variable), and the generated files then build that configuration.

An example of a single-configuration build system are Makefiles. You can build the Release configuration of Uncrustify (from the build folder) with:

$ cmake -DCMAKE_BUILD_TYPE=Release ..
$ make

Other build systems are multi-configuration, which means you specify the build type when building.

An example of a multi-configuration build system are Visual Studios project files. When you open the project in Visual Studio, you can select which configuration to build. You can also do this while building from the command line with cmake --build . --config Release.

Bugs

Post any bugs to the issue tracker found on the projects GitHub page: https://github.com/uncrustify/uncrustify/issues

Please include the following with your issue:

More about this is in the ISSUE_TEMPLATE

Known problems

Look at the Wiki

Which repositories have uncrustify?

Look here

Contribute

If you want to add a feature, fix a bug, or implement missing functionality, feel free to do so! Patches are welcome! Here are some areas that need attention:

A note about pull requests

Firstly take a look at the CONTRIBUTING.md

Currently we have two continuous integration systems that test your PRs, TravisCI and Appveyor. Tested are the test cases, the formatting of the code base and the output of the command line options.

Test cases can be found in the tests/ directory. Every file ending with .test is a test set. Inside each line with these components is a single test: testNr[!] testConfigFileName testInputFileName [lang]

The configuration file testConfigFileName has to be located inside tests/config, the input file testInputFileName inside tests/input/<testSetName>/, and expected results file inside the tests/expected/<testSetName>/ directory. Expected results have the following naming convention: testNr-testInputFileName.

Optionally a ! can follow the testNr to enable a custom rerun configuration. Rerun configurations need to be named like this: testConfigFileName(without extension)+.rerun+.extension

Also, optionally a language for the input can be provided with lang.

The codebase has to be formatted by the options set up in forUncrustifySources.cfg. Failing to format the sources correctly will cause TravisCI build failures.

The Command line interface (CLI) output is tested by the test_cli_options.sh script. It is located inside of tests/cli/ and operates on the subdirectories of that folder.

If a PR is altering the CLI output, files inside those directories might need to be manually updated. This often happens when options are added, removed or altered. Keep in mind that the version string line (example: # Uncrustify-0.69.0_f) of outputs from commands like --show-config should be replaced with a blank line.

Debugging

The first method is to use uncrustify itself to get debug informations. Using:

   uncrustify -c myExample.cfg -f myExample.cpp -p myExample.p -L A 2>myExample.A

you get two files for the first informations. The p-file gives you details of the parsing process and indentation.

# Line                Tag              Parent          Columns Br/Lvl/pp     Flag   Nl  Text
#   1>              CLASS[               NONE][  1/  1/  6/  0][0/0/0][  10070000][0-0] class
#   1>               TYPE[              CLASS][  7/  7/ 14/  1][0/0/0][  10000000][0-0]       Capteur
#   1>         BRACE_OPEN[              CLASS][ 15/ 15/ 16/  1][0/0/0][ 100000400][0-0]               {

The A-file gives you many details about the run itself, where the process is running thru, which values have the most important variables.

tokenize(2351): orig_line is 1, orig_col is 1, Text() 'class', type is CLASS, orig_col_end is 6
tokenize(2351): orig_line is 1, orig_col is 7, Text() 'Capteur', type is WORD, orig_col_end is 14
tokenize(2351): orig_line is 1, orig_col is 15, Text() '{', type is BRACE_OPEN, orig_col_end is 16

You can also dump the parsing information of each formatting step using the 'dump steps' option.

   uncrustify -c myExample.cfg -f myExample.cpp -ds dump

This will create a series of 'dump_nnn.log' files, each containing the parsing information at specific points of the formatting process ('dump_000.log' will list the formatting options in use).

You can combine this option with -p and -L to get a lot of detailed debugging information.

   uncrustify -c myExample.cfg -f myExample.cpp -p myExample.p -L A 2>myExample.A -ds dump

It might be useful to add some code lines to see where something is happening. Use the package unc_tools. Remove the comment at line:

#define DEVELOP_ONLY

Import the package:

#include "unc_tools.h"

Add at some places the line:

prot_the_line(__LINE__, 6, 0);

Compile again with DEBUG option.

How to add an option

If you need a new option, there are a few steps to follow. Take as example the option sp_trailing_ret_t

First define the option:

// Add or remove space around trailing return operator '->'.
extern Option<iarf_e>
sp_trailing_ret_t;

   if (chunk_is_token(first, CT_TRAILING_RET_T))
   {
      // Add or remove space around trailing return operator '->'.
      log_rule("sp_trailing_ret_t");
      return(options::sp_trailing_ret_t());
   }

Portability

We are pretty sure that nothing OS-specific is used in the code base. The software has been previously tested on the following operating systems:

Running the program

NOTE This application works reasonably well but it has bugs. Do not apply it on your whole codebase without checking the results!

Here are ways to run it:

$ uncrustify -c mystyle.cfg -f somefile.c -o somefile.c.unc
$ uncrustify -c mystyle.cfg -f somefile.c > somefile.c.unc
$ uncrustify -c mystyle.cfg somefile.c
$ uncrustify -c mystyle.cfg --no-backup somefile.c
$ uncrustify -c mystyle.cfg *.c
$ uncrustify -c mystyle.cfg --no-backup *.c

The -c flag selects the configuration file. The -f flag specifies the input file. The -o flag specifies the output file. If flag -f is used without flag -o the output will be send to stdout.

Alternatively multiple or single files that should be processed can be specified at the command end without flags. If the flag --no-backup is missing, every file is saved with the initial name and an additional suffix (can be changed with --suffix).

For more options descriptions call:

$ uncrustify -h

Configuring the program

Uncrustify usually reads configuration files that are passed via the -c flag. If the flag is not provided Uncrustify will try to find a configuration file via the UNCRUSTIFY_CONFIG environment variable or a file with the name .uncrustify.cfg or uncrustify.cfg in your home folder.

To get a list of:

Example configuration files that can be used as a starting point can be found in the etc/ directory (such as ben.cfg).

Modify to your liking. Use a quality side-by-side diff tool to determine if the program did what you wanted. Repeat until your style is refined.

To ease the process a bit, some 3rd party tools are available:

Under Windows: Uncrustify is a command-line tool, if you run it by double-clicking the executable, it will open a command prompt run the executable (which prints the help message), and then immediately close the window as uncrustify exits.

You can open the command prompt (which is an interactive terminal window that allows you to run commands without it closing as soon as they exit) and run uncrustify.exe there.

Using uncrustify with vim

Have a look [here]https://github.com/cofyc/vim-uncrustify

Using uncrustify with IntelliJ

Have a look at https://plugins.jetbrains.com/plugin/17528-uncrustify