= Clang libtooling-based rename

== This tool vs clang-rename

This tool is similar to clang-rename, though there are a number of differences.

Pros wrt. data members:

- old name can be a simple qualified name, no need to manually specify a byte
  offset
- rename handles ctor initializer list, too
- handles macros, even nested ones
- comes with a wrapper to do fully automatic rewriting

Details:

- handles rename of:
  - data members
  - member functions
  - classes
- tested with clang
  - 12

== Hello world

Example usage:

----
bin/rename -dump -old-name=C::nX -new-name=m_nX test.cxx --
----

If you get missing includes:

----
ln -s /usr/lib64
----

== Searching for the members to rename

Build the LibreOffice build with some additional parameters, like:

-----
make <build-param> COMPILER_EXTERNAL_TOOL=1 CXX='<full-path>/bin/find-unprefixed-members-wrapper /usr/bin/clang++' RENAME_ARGS="-class-name=<class-name>"
-----

- <build-param> is what you'd normally provide to make, like sw.build or
  build.
- <class-name> is the class name you are interested in calling the 'find
  uprefixed' machinery to operate on.

The build will start, and at the first successful find of the class that has
the members to rename, it will output them, and stop the build.  They are also
stored in /tmp/rename.csv.

== Build system integration

LibreOffice integration example with csv handling, provided that:

- rename-wrapper is in your PATH
- rename.csv is something like in your HOME:

----
C::nX,m_nX
C::nY,m_nY
----

Then run:

----
make -sr -j8 COMPILER_EXTERNAL_TOOL=1 FORCE_COMPILE_ALL=1 CCACHE_PREFIX=rename-wrapper RENAME_ARGS="-csv=$HOME/rename.csv"
----

Once the rewriting is done, you can overwrite the original files with the .new-rename ones with:

----
for i in $(find . -name "*.new-rename"); do mv -f $i ${i%%.new-rename}; done
----

== Using find-unprefixed-members with clang-rename

With new enough clang-rename (clang-tools-extra r278201 towards 4.0 or newer)
it's possible to avoid using the simple rename tool included in this repo. One
advantage of doing so is correct handling of overriden member functions.  Here
is an example:

Detect unprefixed members for a class:

----
make -sr -j8 COMPILER_EXTERNAL_TOOL=1 CCACHE_PREFIX=find-unprefixed-members-wrapper2 RENAME_ARGS="-class-name=SwPagePreview -yaml"
----

(`find-unprefixed-members-wrapper2` is the same as `rename-wrapper`, just `s/=rename/=find-unprefixed-members/`.)

and save the output to `$HOME/rename.yaml`.

Rename them:

----
make -sr -j8 COMPILER_EXTERNAL_TOOL=1 CCACHE_PREFIX=clang-rename-wrapper RENAME_ARGS="-input=$HOME/rename.yaml"
----

(`clang-rename-wrapper` is the same as `rename-wrapper`, just `s/=rename/=clang-rename/`.)

Put output into git:

----
clang-apply-replacements -remove-change-desc-files /tmp/rename
----

// vim: ft=asciidoc