diff options
Diffstat (limited to 'docs/ClangFormat.rst')
| -rw-r--r-- | docs/ClangFormat.rst | 216 |
1 files changed, 0 insertions, 216 deletions
diff --git a/docs/ClangFormat.rst b/docs/ClangFormat.rst deleted file mode 100644 index f2228c57505b..000000000000 --- a/docs/ClangFormat.rst +++ /dev/null @@ -1,216 +0,0 @@ -=========== -ClangFormat -=========== - -`ClangFormat` describes a set of tools that are built on top of -:doc:`LibFormat`. It can support your workflow in a variety of ways including a -standalone tool and editor integrations. - - -Standalone Tool -=============== - -:program:`clang-format` is located in `clang/tools/clang-format` and can be used -to format C/C++/Java/JavaScript/Objective-C/Protobuf code. - -.. code-block:: console - - $ clang-format -help - OVERVIEW: A tool to format C/C++/Java/JavaScript/Objective-C/Protobuf code. - - If no arguments are specified, it formats the code from standard input - and writes the result to the standard output. - If <file>s are given, it reformats the files. If -i is specified - together with <file>s, the files are edited in-place. Otherwise, the - result is written to the standard output. - - USAGE: clang-format [options] [<file> ...] - - OPTIONS: - - Clang-format options: - - -assume-filename=<string> - When reading from stdin, clang-format assumes this - filename to look for a style config file (with - -style=file) and to determine the language. - -cursor=<uint> - The position of the cursor when invoking - clang-format from an editor integration - -dump-config - Dump configuration options to stdout and exit. - Can be used with -style option. - -fallback-style=<string> - The name of the predefined style used as a - fallback in case clang-format is invoked with - -style=file, but can not find the .clang-format - file to use. - Use -fallback-style=none to skip formatting. - -i - Inplace edit <file>s, if specified. - -length=<uint> - Format a range of this length (in bytes). - Multiple ranges can be formatted by specifying - several -offset and -length pairs. - When only a single -offset is specified without - -length, clang-format will format up to the end - of the file. - Can only be used with one input file. - -lines=<string> - <start line>:<end line> - format a range of - lines (both 1-based). - Multiple ranges can be formatted by specifying - several -lines arguments. - Can't be used with -offset and -length. - Can only be used with one input file. - -offset=<uint> - Format a range starting at this byte offset. - Multiple ranges can be formatted by specifying - several -offset and -length pairs. - Can only be used with one input file. - -output-replacements-xml - Output replacements as XML. - -sort-includes - Sort touched include lines - -style=<string> - Coding style, currently supports: - LLVM, Google, Chromium, Mozilla, WebKit. - Use -style=file to load style configuration from - .clang-format file located in one of the parent - directories of the source file (or current - directory for stdin). - Use -style="{key: value, ...}" to set specific - parameters, e.g.: - -style="{BasedOnStyle: llvm, IndentWidth: 8}" - -verbose - If set, shows the list of processed files - - Generic Options: - - -help - Display available options (-help-hidden for more) - -help-list - Display list of available options (-help-list-hidden for more) - -version - Display the version of this program - - -When the desired code formatting style is different from the available options, -the style can be customized using the ``-style="{key: value, ...}"`` option or -by putting your style configuration in the ``.clang-format`` or ``_clang-format`` -file in your project's directory and using ``clang-format -style=file``. - -An easy way to create the ``.clang-format`` file is: - -.. code-block:: console - - clang-format -style=llvm -dump-config > .clang-format - -Available style options are described in :doc:`ClangFormatStyleOptions`. - - -Vim Integration -=============== - -There is an integration for :program:`vim` which lets you run the -:program:`clang-format` standalone tool on your current buffer, optionally -selecting regions to reformat. The integration has the form of a `python`-file -which can be found under `clang/tools/clang-format/clang-format.py`. - -This can be integrated by adding the following to your `.vimrc`: - -.. code-block:: vim - - map <C-K> :pyf <path-to-this-file>/clang-format.py<cr> - imap <C-K> <c-o>:pyf <path-to-this-file>/clang-format.py<cr> - -The first line enables :program:`clang-format` for NORMAL and VISUAL mode, the -second line adds support for INSERT mode. Change "C-K" to another binding if -you need :program:`clang-format` on a different key (C-K stands for Ctrl+k). - -With this integration you can press the bound key and clang-format will -format the current line in NORMAL and INSERT mode or the selected region in -VISUAL mode. The line or region is extended to the next bigger syntactic -entity. - -It operates on the current, potentially unsaved buffer and does not create -or save any files. To revert a formatting, just undo. - -An alternative option is to format changes when saving a file and thus to -have a zero-effort integration into the coding workflow. To do this, add this to -your `.vimrc`: - -.. code-block:: vim - - function! Formatonsave() - let l:formatdiff = 1 - pyf ~/llvm/tools/clang/tools/clang-format/clang-format.py - endfunction - autocmd BufWritePre *.h,*.cc,*.cpp call Formatonsave() - - -Emacs Integration -================= - -Similar to the integration for :program:`vim`, there is an integration for -:program:`emacs`. It can be found at `clang/tools/clang-format/clang-format.el` -and used by adding this to your `.emacs`: - -.. code-block:: common-lisp - - (load "<path-to-clang>/tools/clang-format/clang-format.el") - (global-set-key [C-M-tab] 'clang-format-region) - -This binds the function `clang-format-region` to C-M-tab, which then formats the -current line or selected region. - - -BBEdit Integration -================== - -:program:`clang-format` cannot be used as a text filter with BBEdit, but works -well via a script. The AppleScript to do this integration can be found at -`clang/tools/clang-format/clang-format-bbedit.applescript`; place a copy in -`~/Library/Application Support/BBEdit/Scripts`, and edit the path within it to -point to your local copy of :program:`clang-format`. - -With this integration you can select the script from the Script menu and -:program:`clang-format` will format the selection. Note that you can rename the -menu item by renaming the script, and can assign the menu item a keyboard -shortcut in the BBEdit preferences, under Menus & Shortcuts. - - -Visual Studio Integration -========================= - -Download the latest Visual Studio extension from the `alpha build site -<https://llvm.org/builds/>`_. The default key-binding is Ctrl-R,Ctrl-F. - - -Script for patch reformatting -============================= - -The python script `clang/tools/clang-format/clang-format-diff.py` parses the -output of a unified diff and reformats all contained lines with -:program:`clang-format`. - -.. code-block:: console - - usage: clang-format-diff.py [-h] [-i] [-p NUM] [-regex PATTERN] [-style STYLE] - - Reformat changed lines in diff. Without -i option just output the diff that - would be introduced. - - optional arguments: - -h, --help show this help message and exit - -i apply edits to files instead of displaying a diff - -p NUM strip the smallest prefix containing P slashes - -regex PATTERN custom pattern selecting file paths to reformat - -style STYLE formatting style to apply (LLVM, Google, Chromium, Mozilla, - WebKit) - -So to reformat all the lines in the latest :program:`git` commit, just do: - -.. code-block:: console - - git diff -U0 --no-color HEAD^ | clang-format-diff.py -i -p1 - -With Mercurial/:program:`hg`: - -.. code-block:: console - - hg diff -U0 --color=never | clang-format-diff.py -i -p1 - -In an SVN client, you can do: - -.. code-block:: console - - svn diff --diff-cmd=diff -x -U0 | clang-format-diff.py -i - -The option `-U0` will create a diff without context lines (the script would format -those as well). |