| 1 |
============ |
| 2 |
Clang-Rename |
| 3 |
============ |
| 4 |
|
| 5 |
.. contents:: |
| 6 |
|
| 7 |
See also: |
| 8 |
|
| 9 |
.. toctree:: |
| 10 |
:maxdepth: 1 |
| 11 |
|
| 12 |
|
| 13 |
:program:`clang-rename` is a C++ refactoring tool. Its purpose is to perform |
| 14 |
efficient renaming actions in large-scale projects such as renaming classes, |
| 15 |
functions, variables, arguments, namespaces etc. |
| 16 |
|
| 17 |
The tool is in a very early development stage, so you might encounter bugs and |
| 18 |
crashes. Submitting reports with information about how to reproduce the issue |
| 19 |
to `the LLVM bugtracker <https://bugs.llvm.org>`_ will definitely help the |
| 20 |
project. If you have any ideas or suggestions, you might want to put a feature |
| 21 |
request there. |
| 22 |
|
| 23 |
Using Clang-Rename |
| 24 |
================== |
| 25 |
|
| 26 |
:program:`clang-rename` is a `LibTooling |
| 27 |
<https://clang.llvm.org/docs/LibTooling.html>`_-based tool, and it's easier to |
| 28 |
work with if you set up a compile command database for your project (for an |
| 29 |
example of how to do this see `How To Setup Tooling For LLVM |
| 30 |
<https://clang.llvm.org/docs/HowToSetupToolingForLLVM.html>`_). You can also |
| 31 |
specify compilation options on the command line after `--`: |
| 32 |
|
| 33 |
.. code-block:: console |
| 34 |
|
| 35 |
$ clang-rename -offset=42 -new-name=foo test.cpp -- -Imy_project/include -DMY_DEFINES ... |
| 36 |
|
| 37 |
|
| 38 |
To get an offset of a symbol in a file run |
| 39 |
|
| 40 |
.. code-block:: console |
| 41 |
|
| 42 |
$ grep -FUbo 'foo' file.cpp |
| 43 |
|
| 44 |
|
| 45 |
The tool currently supports renaming actions inside a single translation unit |
| 46 |
only. It is planned to extend the tool's functionality to support multi-TU |
| 47 |
renaming actions in the future. |
| 48 |
|
| 49 |
:program:`clang-rename` also aims to be easily integrated into popular text |
| 50 |
editors, such as Vim and Emacs, and improve the workflow of users. |
| 51 |
|
| 52 |
Although a command line interface exists, it is highly recommended to use the |
| 53 |
text editor interface instead for better experience. |
| 54 |
|
| 55 |
You can also identify one or more symbols to be renamed by giving the fully |
| 56 |
qualified name: |
| 57 |
|
| 58 |
.. code-block:: console |
| 59 |
|
| 60 |
$ clang-rename -qualified-name=foo -new-name=bar test.cpp |
| 61 |
|
| 62 |
Renaming multiple symbols at once is supported, too. However, |
| 63 |
:program:`clang-rename` doesn't accept both `-offset` and `-qualified-name` at |
| 64 |
the same time. So, you can either specify multiple `-offset` or |
| 65 |
`-qualified-name`. |
| 66 |
|
| 67 |
.. code-block:: console |
| 68 |
|
| 69 |
$ clang-rename -offset=42 -new-name=bar1 -offset=150 -new-name=bar2 test.cpp |
| 70 |
|
| 71 |
or |
| 72 |
|
| 73 |
.. code-block:: console |
| 74 |
|
| 75 |
$ clang-rename -qualified-name=foo1 -new-name=bar1 -qualified-name=foo2 -new-name=bar2 test.cpp |
| 76 |
|
| 77 |
|
| 78 |
Alternatively, {offset | qualified-name} / new-name pairs can be put into a YAML |
| 79 |
file: |
| 80 |
|
| 81 |
.. code-block:: yaml |
| 82 |
|
| 83 |
--- |
| 84 |
- Offset: 42 |
| 85 |
NewName: bar1 |
| 86 |
- Offset: 150 |
| 87 |
NewName: bar2 |
| 88 |
... |
| 89 |
|
| 90 |
or |
| 91 |
|
| 92 |
.. code-block:: yaml |
| 93 |
|
| 94 |
--- |
| 95 |
- QualifiedName: foo1 |
| 96 |
NewName: bar1 |
| 97 |
- QualifiedName: foo2 |
| 98 |
NewName: bar2 |
| 99 |
... |
| 100 |
|
| 101 |
That way you can avoid spelling out all the names as command line arguments: |
| 102 |
|
| 103 |
.. code-block:: console |
| 104 |
|
| 105 |
$ clang-rename -input=test.yaml test.cpp |
| 106 |
|
| 107 |
:program:`clang-rename` offers the following options: |
| 108 |
|
| 109 |
.. code-block:: console |
| 110 |
|
| 111 |
$ clang-rename --help |
| 112 |
USAGE: clang-rename [subcommand] [options] <source0> [... <sourceN>] |
| 113 |
|
| 114 |
OPTIONS: |
| 115 |
|
| 116 |
Generic Options: |
| 117 |
|
| 118 |
-help - Display available options (-help-hidden for more) |
| 119 |
-help-list - Display list of available options (-help-list-hidden for more) |
| 120 |
-version - Display the version of this program |
| 121 |
|
| 122 |
clang-rename common options: |
| 123 |
|
| 124 |
-export-fixes=<filename> - YAML file to store suggested fixes in. |
| 125 |
-extra-arg=<string> - Additional argument to append to the compiler command line |
| 126 |
Can be used several times. |
| 127 |
-extra-arg-before=<string> - Additional argument to prepend to the compiler command line |
| 128 |
Can be used several times. |
| 129 |
-force - Ignore nonexistent qualified names. |
| 130 |
-i - Overwrite edited <file>s. |
| 131 |
-input=<string> - YAML file to load oldname-newname pairs from. |
| 132 |
-new-name=<string> - The new name to change the symbol to. |
| 133 |
-offset=<uint> - Locates the symbol by offset as opposed to <line>:<column>. |
| 134 |
-p <string> - Build path |
| 135 |
-pl - Print the locations affected by renaming to stderr. |
| 136 |
-pn - Print the found symbol's name prior to renaming to stderr. |
| 137 |
-qualified-name=<string> - The fully qualified name of the symbol. |
| 138 |
|
| 139 |
Vim Integration |
| 140 |
=============== |
| 141 |
|
| 142 |
You can call :program:`clang-rename` directly from Vim! To set up |
| 143 |
:program:`clang-rename` integration for Vim see |
| 144 |
`clang/tools/clang-rename/clang-rename.py |
| 145 |
<https://github.com/llvm/llvm-project/blob/main/clang/tools/clang-rename/clang-rename.py>`_. |
| 146 |
|
| 147 |
Please note that **you have to save all buffers, in which the replacement will |
| 148 |
happen before running the tool**. |
| 149 |
|
| 150 |
Once installed, you can point your cursor to symbols you want to rename, press |
| 151 |
`<leader>cr` and type new desired name. The `<leader> key |
| 152 |
<http://vim.wikia.com/wiki/Mapping_keys_in_Vim_-_Tutorial_(Part_3)#Map_leader>`_ |
| 153 |
is a reference to a specific key defined by the mapleader variable and is bound |
| 154 |
to backslash by default. |
| 155 |
|
| 156 |
Emacs Integration |
| 157 |
================= |
| 158 |
|
| 159 |
You can also use :program:`clang-rename` while using Emacs! To set up |
| 160 |
:program:`clang-rename` integration for Emacs see |
| 161 |
`clang-rename/tool/clang-rename.el |
| 162 |
<https://github.com/llvm/llvm-project/blob/main/clang/tools/clang-rename/clang-rename.el>`_. |
| 163 |
|
| 164 |
Once installed, you can point your cursor to symbols you want to rename, press |
| 165 |
`M-X`, type `clang-rename` and new desired name. |
| 166 |
|
| 167 |
Please note that **you have to save all buffers, in which the replacement will |
| 168 |
happen before running the tool**. |