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/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**.