[BuildLibcalls, Attrs] Support more variants of C++'s new, add attributes for C+...
[lldb.git] / clang-tools-extra / docs / clang-rename.rst
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/master/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/master/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**.