You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
396 lines
15 KiB
396 lines
15 KiB
[](https://ci.appveyor.com/project/uncrustify/uncrustify)
|
|
[](https://coveralls.io/github/uncrustify/uncrustify?branch=master)
|
|
<a href="#"><img src="https://img.shields.io/badge/C++-11-blue.svg?style=flat-square"></a>
|
|
[](https://conan.io/center/uncrustify)
|
|
|
|
---------------------------
|
|
|
|
# Uncrustify
|
|
A source code beautifier for C, C++, C#, Objective-C, D, Java, Pawn and Vala.
|
|
|
|
## Features
|
|
* Highly configurable - 850 configurable options as of version 0.78.1
|
|
- <details><summary>add/remove spaces</summary>
|
|
|
|
- `sp_before_sparen`: _Add or remove space before '(' of 'if', 'for', 'switch', 'while', etc._
|
|
- `sp_compare`: _Add or remove space around compare operator '<', '>', '==', etc_
|
|
</details>
|
|
|
|
- <details><summary>add/remove newlines</summary>
|
|
|
|
- `nl_if_brace`: _Add or remove newline between 'if' and '{'_
|
|
- `nl_brace_while`: _Add or remove newline between '}' and 'while' of 'do' statement_
|
|
</details>
|
|
|
|
- <details><summary>add/remove blanklines</summary>
|
|
|
|
- `eat_blanks_before_close_brace`: _Whether to remove blank lines before '}'_
|
|
- `nl_max`: _The maximum consecutive newlines (3 = 2 blank lines)_
|
|
</details>
|
|
|
|
- <details><summary>indent code</summary>
|
|
|
|
- `indent_switch_case`: _indent_switch_case: Spaces to indent 'case' from 'switch'_
|
|
- `indent_class_colon`: _Whether to indent the stuff after a leading base class colon_
|
|
</details>
|
|
|
|
- <details><summary>align code</summary>
|
|
|
|
- `align_func_params`: _Align variable definitions in prototypes and functions_
|
|
- `align_struct_init_span`: _The span for aligning struct initializer values (0=don't align)_
|
|
</details>
|
|
|
|
- <details><summary>modify code</summary>
|
|
|
|
- `mod_full_brace_for`: _Add or remove braces on single-line 'for' statement_
|
|
- `mod_paren_on_return`: _Add or remove unnecessary paren on 'return' statement_
|
|
</details>
|
|
|
|
Here is an example [configuration file](https://raw.githubusercontent.com/uncrustify/uncrustify/master/documentation/htdocs/ben.cfg.txt),
|
|
and here is a [before](https://raw.githubusercontent.com/uncrustify/uncrustify/master/documentation/htdocs/examples/c-1.in.c)
|
|
and [after](https://raw.githubusercontent.com/uncrustify/uncrustify/master/documentation/htdocs/examples/c-1.out.c)
|
|
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 from the [Releases](https://github.com/uncrustify/uncrustify/releases) page or from the [Sourceforge](https://sourceforge.net/projects/uncrustify/files/) website.
|
|
|
|
## Build
|
|
[Python](https://www.python.org/) is an "interpreted high-level programming language for general-purpose programming", for this project it is needed to extend the capabilities of CMake.
|
|
|
|
[CMake](https://cmake.org/) 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 on UNIX-like systems, create a
|
|
build folder and run CMake from it, making sure to specify Release mode:
|
|
|
|
```bash
|
|
$ mkdir build
|
|
$ cd build
|
|
$ cmake -DCMAKE_BUILD_TYPE=Release ..
|
|
```
|
|
Other systems may require other flags (e.g. `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:
|
|
|
|
```bash
|
|
$ cmake --build . --config Release
|
|
```
|
|
|
|
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:
|
|
|
|
```bash
|
|
$ 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 or Debug configurations of Uncrustify (from the build folder) with:
|
|
|
|
```bash
|
|
$ cmake -DCMAKE_BUILD_TYPE=Release ..
|
|
$ make
|
|
```
|
|
or
|
|
```bash
|
|
$ cmake -DCMAKE_BUILD_TYPE=Debug ..
|
|
$ 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 Debug`.
|
|
|
|
|
|
## 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:
|
|
- a description of what is not working right
|
|
- input code sufficient to demonstrate the issue
|
|
- expected output code
|
|
- configuration options used to generate the output
|
|
|
|
More about this is in the [ISSUE_TEMPLATE](https://github.com/uncrustify/uncrustify/blob/master/.github/ISSUE_TEMPLATE)
|
|
|
|
|
|
### Known problems
|
|
[Look at the Wiki](https://github.com/uncrustify/uncrustify/wiki/Known-Problems)
|
|
|
|
|
|
## Which repositories have uncrustify?
|
|
[Look here](https://repology.org/metapackage/uncrustify/versions)
|
|
|
|
|
|
## 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:
|
|
|
|
- __Patches for Objective-C support__. We really need someone who knows
|
|
this language as it has more than plenty open issues. A good starting
|
|
point would be to integrate changes made in the
|
|
[Unity fork](https://github.com/Unity-Technologies/uncrustify/tree/fixes/c-oc-java)
|
|
- Test Java support and provide feedback (or patches!)
|
|
- Test Embedded SQL to see what works
|
|
- A logo of some sort
|
|
- Anything else that you want to do to make it better?
|
|
|
|
### A note about pull requests
|
|
Firstly take a look at the [CONTRIBUTING.md](https://github.com/uncrustify/uncrustify/blob/master/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:
|
|
```.txt
|
|
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.
|
|
```.txt
|
|
# 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.
|
|
```.txt
|
|
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.
|
|
```.txt
|
|
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.
|
|
```.txt
|
|
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:
|
|
```.cpp
|
|
#define DEVELOP_ONLY
|
|
```
|
|
Import the package:
|
|
```.cpp
|
|
#include "unc_tools.h"
|
|
```
|
|
Add at some places the line:
|
|
```.cpp
|
|
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:
|
|
- Insert the code below to the file src/options.h
|
|
_NOTE:
|
|
This file is processed by make_options.py, and must conform to a particular
|
|
format. Option groups are marked by '//begin ' (in upper case; this example
|
|
is lower case to prevent being considered a region marker for code folding)
|
|
followed by the group description. Options consist of two lines of
|
|
declaration preceded by one or more lines of C++ comments. The comments form
|
|
the option description and are taken verbatim, aside from stripping the
|
|
leading '// '. Only comments immediately preceding an option declaration,
|
|
with no blank lines, are taken as part of the description, so a blank line
|
|
may be used to separate notations from a description.
|
|
An option declaration is 'extern TYPE\nNAME;', optionally followed by
|
|
' // = VALUE' if the option has a default value that is different from the
|
|
default-constructed value type of the option. The 'VALUE' must be valid C++
|
|
code, and is taken verbatim as an argument when creating the option's
|
|
instantiation. Note also that the line break, as shown, is required.
|
|
_
|
|
```.cpp
|
|
// Add or remove space around trailing return operator '->'.
|
|
extern Option<iarf_e>
|
|
sp_trailing_ret_t;
|
|
```
|
|
- Insert the code below to the file src/space.cpp
|
|
```.cpp
|
|
if (first->Is(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:
|
|
- Linux
|
|
- QNX
|
|
- OS X
|
|
- FreeBSD, NetBSD, OpenBSD
|
|
- Sun Solaris 9
|
|
- Windows (binary available)
|
|
|
|
|
|
---------------------------------------------------------------------------
|
|
|
|
## 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:
|
|
```bash
|
|
$ 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:
|
|
- all available options use:
|
|
```bash
|
|
uncrustify --show-config
|
|
```
|
|
|
|
- all available options in a usable configuration file format use:
|
|
```bash
|
|
uncrustify --update-config
|
|
```
|
|
|
|
or
|
|
|
|
```bash
|
|
uncrustify --update-config-with-doc
|
|
```
|
|
|
|
As the names suggest, both options can produce output that adds newly
|
|
introduced options to your old configuration file. For this your old
|
|
configuration file has to be passed via the `-c` flag:
|
|
```bash
|
|
uncrustify --update-config-with-doc -c path/to/your.cfg
|
|
```
|
|
|
|
Example configuration files that can be used as a starting point can be
|
|
found in the `etc/` directory (such as [ben.cfg](./etc/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:
|
|
- [Universal Indent GUI](http://universalindent.sourceforge.net/) - A
|
|
cross-platform graphical configuration file editor for many code
|
|
beautifiers, including Uncrustify.
|
|
- [uncrustify_config](https://github.com/CDanU/uncrustify_config) - A web
|
|
configuration tool based on Uncrustify's emscripten interface.
|
|
- [UncrustifyX](https://github.com/ryanmaxwell/UncrustifyX) - Uncrustify
|
|
utility and documentation browser for Mac OS X
|
|
|
|
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
|