diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/markdown/Code-formatting.md | 58 | ||||
| -rw-r--r-- | docs/markdown/snippets/clang-format.md | 43 | ||||
| -rw-r--r-- | docs/sitemap.txt | 1 |
3 files changed, 102 insertions, 0 deletions
diff --git a/docs/markdown/Code-formatting.md b/docs/markdown/Code-formatting.md new file mode 100644 index 0000000..c8d83de --- /dev/null +++ b/docs/markdown/Code-formatting.md @@ -0,0 +1,58 @@ +--- +short-description: Code formatting +... + +# clang-format + +*Since 0.50.0* + +When `clang-format` is installed and a `.clang-format` file is found at the main +project's root source directory, Meson automatically adds a `clang-format` target +that reformat all C and C++ files (currently only with Ninja backend). + +```sh +ninja -C builddir clang-format +``` + +*Since 0.58.0* + +It is possible to restrict files to be reformatted with optional +`.clang-format-include` and `.clang-format-ignore` files. + +The file `.clang-format-include` contains a list of patterns matching the files +that will be reformatted. The `**` pattern matches this directory and all +subdirectories recursively. Empty lines and lines starting with `#` are ignored. +If `.clang-format-include` is not found, the pattern defaults to `**/*` which +means all files recursively in the source directory but has the disadvantage to +walk the whole source tree which could be slow in the case it contains lots of +files. + +Example of `.clang-format-include` file: +``` +# All files in src/ and its subdirectories +src/**/* + +# All files in include/ but not its subdirectories +include/* +``` + +The file `.clang-format-ignore` contains a list of patterns matching the files +that will be excluded. Files matching the include list (see above) that match +one of the ignore pattern will not be reformatted. Unlike include patters, ignore +patterns does not support `**` and a single `*` match any characters including +path separators. Empty lines and lines starting with `#` are ignored. + +The build directory and file without a well known C or C++ suffix are always +ignored. + +Example of `.clang-format-ignore` file: +``` +# Skip C++ files in src/ directory +src/*.cpp +``` + +Note that `.clang-format-ignore` has the same format as used by +[`run-clang-format.py`](https://github.com/Sarcasm/run-clang-format). + +Modified files will be printed on the console which can be used for example by +CI to ensure all files are correctly formatted. diff --git a/docs/markdown/snippets/clang-format.md b/docs/markdown/snippets/clang-format.md new file mode 100644 index 0000000..8cb88e0 --- /dev/null +++ b/docs/markdown/snippets/clang-format.md @@ -0,0 +1,43 @@ +## clang-format include and ignore lists + +When clang-format is installed and a `.clang-format` file is found at the main +project's root source directory, Meson automatically adds a `clang-format` target +that reformat all C and C++ files. + +It is now possible to restrict files to be reformatted with optional +`.clang-format-include` and `.clang-format-ignore` files. + +The file `.clang-format-include` contains a list of patterns matching the files +that will be reformatted. The `**` pattern matches this directory and all +subdirectories recursively. Empty lines and lines starting with `#` are ignored. +If `.clang-format-include` is not found, the pattern defaults to `**/*` which +means all files recursively in the source directory but has the disadvantage to +walk the whole source tree which could be slow in the case it contains lots of +files. + +Example of `.clang-format-include` file: +``` +# All files in src/ and its subdirectories +src/**/* + +# All files in include/ but not its subdirectories +include/* +``` + +The file `.clang-format-ignore` contains a list of patterns matching the files +that will be excluded. Files matching the include list (see above) that match +one of the ignore pattern will not be reformatted. Unlike include patters, ignore +patterns does not support `**` and a single `*` match any characters including +path separators. Empty lines and lines starting with `#` are ignored. + +The build directory and file without a well known C or C++ suffix are always +ignored. + +Example of `.clang-format-ignore` file: +``` +# Skip C++ files in src/ directory +src/*.cpp +``` + +Modified files will be printed on the console which can be used for example by +CI to ensure all files are correctly formatted. diff --git a/docs/sitemap.txt b/docs/sitemap.txt index de98cd0..29c54c4 100644 --- a/docs/sitemap.txt +++ b/docs/sitemap.txt @@ -32,6 +32,7 @@ index.md Build-options.md Subprojects.md Disabler.md + Code-formatting.md Modules.md CMake-module.md Cuda-module.md |