Clang Rename Tool

[klimek]

Summary

This is the first patch for the clang rename tool. In order to reduce the amount of code in this patch, a fair amount of code has been removed from USRFinder.cpp and USRLocFinder.cpp, at the request of Manuel. This reduces the functionality of the tool to just renaming variables, and wont rename them in all contexts. The remaining code will be added when it is found to be appropriate (it does in fact exist; I have it in a tar in my home directory).

It builds fine, and I can run the program just fine on my home laptop as well as my work computer.

[klimek]

First round focused on ClangRename.cpp. More to come :)

clang-rename/ClangRename.cpp

70–72

I usually find offsets better to use for tools (and humans are not going to enter lines and columns here anyway).

83

This is also already a feature of ClangTool / RefactoringTool if I'm not mistaken.

91

I'd try to not use getNameAsString to do matching against - can't we solve this in the type system?

101

Name this getAllConstructorUSRs?

114

I wonder whether we could do something similar for constructors (perhaps by changing the AST).

126–129

Needs a comment.

132

points

132–134

Renaming operators seems ... strange; I would expect to add that (if at all) somewhen much later.

170

I find this rather strange architecturally - why don't we just visit the whole thing twice?

174

s/mail/main/

234

Remove comment.

249–259

Any reason you're not using RefactoringTool (which already does basically everything that's in this file)?

[mplant]

Responded to comments and such

clang-rename/ClangRename.cpp

70–72

I added the option to use an offset. And I would not be too sure about the second claim. No matter how obtuse an interface, someone will prefer it. After all, ed is bundled with every Ubuntu install ;)

83

You are correct. As explained later, we can't use RefactoringTool, unless you can think of a solution to the problem explained later.

91

Not in a way that also conveniently gives us the operator spelling.

101

I was thinking that there would be other get*EquivUSRs functions. The term "Equivalent USRs" makes more sense to me in a context where there are multiple of them. But that is not the case here, so I'll change it.

114

I'm not so sure. Constructors and destructors are pretty different; there can only be one destructor for example.

132–134

It is very strange, but it's there. The code for fixOperatorLocs however is not too complicated, and we already have some code for operator renaming I'm planning to place in USR(Loc)Finder later. So I'd rather not remove this just for the sake of the review.

234

But then how will anyone know what the '}' means?? (kidding)

249–259

We need to create a factory for RefactoringTool, which allocates and returns a new consumer per file. Unfortunately, we can't in the factory control where the allocated consumer is deleted - it's free'd by RefactoringTool! This means we can't have persistent state in our consumer without global or static variables - which would require us to violate http://llvm.org/docs/CodingStandards.html#do-not-use-static-constructors. Since we need persistent state for the USR (see comment above), we are left with avoiding RefactoringTool

[mplant]

clang-rename/ClangRename.cpp

170

The reason is that the point may not be in the file we are currently looking at. If we were to attempt to find the USR, we would not find it. Thus we must save it when we initially find it.

this is part of the reason why we can't use refactoring tool - see below for more info on that.

[klimek]

clang-rename/ClangRename.cpp

67–76

Ok, I'm *very* opposed to having both interfaces. This just complicates the code. I stand by what I said - I think users will not enter this manually (because that doesn't really make sense), so we should only use the offset.

91

I thought there was a different way to get the operator name... I'll take a look.

132–134

"It's there" is not a good argument. Neither is "it's not too complicated".
A good argument for a feature needs to involve "it's useful". Note that the code will be maintained by other people, which is why we have pretty strict requirements on the code.

170

I'm not sure I understand:
If you're concerned about finding it when we want to look at multiple files, we have to make sure we look at the file that has the USR *first*, otherwise we might miss refactorings, right?
If you're only concerned about a single file, visiting it twice won't hurt, and be architecturally the right thing to do so we don't run into problems later.

249–259

"This means we can't have persistent state in our consumer without global or static variables"

Just have the state at function scope (for example, here, in a class) and pass a pointer to that state down through the factory into the consumer. The consumer doesn't need to delete things it references when it's destroyed (or I'm missing something).

[mplant]

Questions before (hopefully) substantial cleanup

clang-rename/ClangRename.cpp

67–76

It's your decision, but let me also add that this will make writing shell scripts and such that use the command line tool.
Imagine a shell script that took every "the symbol at x:y:z could not be found, did you mean <other symbol>" and renamed the file accordingly.

132–134

It is useful, in some instance. because "new-name" can be any string, you could use it to do some pretty cool stuff I'm sure.
Also I don't have any problem maintaining just this tool, although I imagine there's just one maintainer for clang-tools-extra. It's not like I have work during the school year after all.

170

Yes, we do have to make sure we're looking at the file that has the USR first. That is guaranteed actually, because we push it to the front of the FileNames list.

249–259

That solves one problem, but there's another:
What about the actual renaming part? I seem to recall a rewriter will become invalid when the RefactoringTool gets a new consumer. Does the factory need to create a new rewriter each time it creates a new consumer?

For what it's worth, I did try to use RefactoringTool; there's more examples on it. But for some reason during my experimentation I concluded that it was insufficient.

[mplant]

Updated to use RefactoringTool

[mplant]

Updated to use RefactoringTool - and removed support for file:line:column arguments. I need to update rename_test.py to fix this at some point.

[klimek]

clang-rename/ClangRename.cpp

160–189

As mentioned before, I think we want an extra run for this, so it can be called outside the RenamingASTConsumer. It seems completely unrelated to renaming.

202–207

What's the reason not to sink this into getLocationsOfUSR?

216–217

I'd pull that out of the loop and invert the if (PrintLocations) to only affect the errs() <<. Also, I'd probably use outs() unless this is for debugging, in which case we'd want to use the debugging facilities instead of just dumping to stderr...

263

I'd prefer this class (and everything it uses) to go into its own .h/.cpp file.
Perhaps call it RenamingAction.h/.cpp.

I'd still want to modularize it further:

• One action to find the USRs (perhaps just export it from USRFinder.h)
• (mid-term) An AST matcher matchUSRs(const std::vector<std::string>&) that matches when a node matches one of the given USRs; this is non-trival to implement, so I'm fine with having an extra AST consumer for now (the getLocationsOfUSRs seems like a good abstraction for now, but I'd want to add a FIXME)
• most of the code in RenamingASTConsumer seems non-renaming related; see comments there.

275

Please add:
// FIXME: Use clang diagnostics.

284

You don't actually need this.
Rename CreateASTConsumer to createASTConsumer, and you'll be able to just say:
newFrontendActionFactory(&Action)
below.

clang-rename/USRFinder.cpp

42

I'd prefer giving this class a getResults() method over handing in a NamedDecl**.

102–126

It's amazing how most of these functions seem to be handling overloaded operators :(

210–213

Should we check that Start and End are in the same file?

clang-rename/USRFinder.h

35

Nit: add newline below.

clang-rename/USRLocFinder.cpp

41–49

I think we either want to test this (which means it will not need a "This is correct as of" comment), or we don't want to rely on it.

test/clang-rename/VarTest.cpp

4

I'm honestly not sure I like this better than:
// CHECK: int bar;

[mplant]

Various refactorings.

[mplant]

comments

clang-rename/ClangRename.cpp

160–189

I agree, but I cannot refactor this to such a degree in such a short amount of time.

202–207

Because changing the location is only useful for renaming. If someone wants to use getLocationsOfUSR for anything else, they probably want a different location.

216–217

That would best be left when more of the code is refactored sensibly and renamed locations are easy to extract. At least by printing to stderr the data can be sensibly removed from the output.

263

I have done bits of the first parts, but future goals will have to wait until I move back to school

284

that is the weirdest interface in the world.

clang-rename/USRFinder.cpp

42

Yeah I changed this. Really I think that this could be done a lot better with a few static methods, but I really don't have enough time for that within the next week. It'll have to wait for later in the year.

102–126

It was decided (not by me) that out of the two things left to possible add before up-streaming - macros and overloaded operators - the latter was to be completed.

Also, that's not entirely the case - most of the code doesn't, but the code that handles common cases (like operators and variables) are places where operator overloading needs to be accounted for.

210–213

I guess...

clang-rename/USRLocFinder.cpp

41–49

We don't rely on it. I'll remove the comment

test/clang-rename/VarTest.cpp

4

This allows us to automatically find the location of the symbol. That way, it checks USRFinder's accuracy as well.

4

this lets the tool automatically find locations. I assure you, it is much easier.

[klimek]

clang-rename/ClangRename.cpp

160–189

If your time does not permit finishing this through, I'd say we stop the review now and start it once somebody is willing to pick up the patch and see it through to the end.

test/clang-rename/VarTest.cpp

4

But the tests are much harder to read. I'd actually say we want two kinds of tests: one for the USR finder, and one for the rename. The USR finder one might even be a unit test.

[mplant]

Modularizes clang-rename further, now with separate actions to find the USR and perform renaming.

[klimek]

This starts to look really good. Thanks for bearing with me :)

I'd really like to remove the conditional operator renaming for the first version - I think it'll be much easier to follow the code that way (and I don't think it'd be too much work).

For testing, I think there are multiple layers:

1. test that the location finding machinery works - for that I'd actually use unit tests; you can take a look at LocationVerifier in unittest/AST/MatchVerifier
2. test that the renaming works; for that, I think FileChecks are perfect, as you can just OldType t; // CHECK: NewType t;

clang-rename/ClangRename.cpp

70–71

Can you explain what exactly didn't work? Perhaps give me the compile error? But it's no biggie - I can also get rid of this once it's checked in - the template error messages are sometimes hard to get through :)

121–134

Nice, this looks much better structured now. Thanks!

[mplant]

I'll get rid of the operator renaming code and take a look at unit tests.

clang-rename/ClangRename.cpp

70–71

It spat out a virtual method not implemented error. I've grepped through the code, and I couldn't find one interface with a virtual method createASTConsumer. Did you mean some method with a different name?

[mplant]

Added renaming unittest and converted VarTest.cpp to use FileCheck. The added unittest builds and passes fine.

[klimek]

clang-rename/ClangRename.cpp

17–43

Are all of these still needed?

clang-rename/RenamingAction.cpp

35–42

Generally, we shouldn't rely on global variables to communicate between classes. The solution is to put all flags into the main file, and pass the information into the relevant classes via parameters.

clang-rename/USRFinder.cpp

57–58

You removed the operator stuff in the other file, but here it's still in. Is that intentional? Will tests break if we remove it? :)

clang-rename/USRFindingAction.h

33

I don't think "Prev" is a good name part here... (I assume this is left from when this was strictly for renaming).

Also, I'd prefer to have private variables and getters here (otherwise it's unclear what is to be set from where).

test/clang-rename/VarTest.cpp

4–9

Thanks! This is much easier for me to read :)

unittests/clang-rename/USRLocFindingTest.cpp

62–67

I'm not 100% sure I understand what the branch is for here (and the function is lacking comments ;)
It looks like it's basically saying "those offsets should yield the same USR", right?
I think that's a good test idea (as it keeps the USR as an implementation detail, which is nice), but why not use a different data structure here, like:
vector<vector<unsigned>> offsets;
where offsets[group] is a list of offsets that should evaluate to the same USR?

75

You can use raw strings to make this look better...

112

Nit: remove redundant empty line.

[mplant]

Updates, fixes, and misc.

clang-rename/ClangRename.cpp

17–43

Not entirely sure. The only real way to determine is to remove one at a time, or manually go through and determine if each is actually used.
Isn't there a clang tool for this? remove-unused-headers or something?

clang-rename/RenamingAction.cpp

35–42

Right-o, will fix. Thought it was a little dubious but decided to do it anyway.

clang-rename/USRFinder.cpp

57–58

Not intentional; I'll remove it.

clang-rename/USRFindingAction.h

33

Hmmm, sure. I renamed PrevName to SpellingName, I think that's better. Also added the setters and getters.

test/clang-rename/VarTest.cpp

4–9

No problem, but boy was that offset hard to find :P

unittests/clang-rename/USRLocFindingTest.cpp

62–67

You're correct on the intent. The idea is that we don't want to rely on USRs being any particular value so long as that the invariants described in rename_test.py are held. I'm not sure why I didn't choose a vector of vectors, that makes a lot more sense actually. I seem to recall the thought entering my brain but being dismissed for some reason. To be fixed.

75

Ah yes

[klimek]

I think there are basically 2 blockers before this can go in:

1. Make the tests actually test something :)
2. Use a member/getter for the result (see inline comment)

Otherwise LG for a first landing.

clang-rename/ClangRename.cpp

17–43

Not yet :) Patches welcome!

142–146

We really need to convert this to Diagnostics (fine in a follow-up patch though).

clang-rename/USRFinder.cpp

42

Use a class member and getter for the result.

clang-rename/USRLocFinder.cpp

44–48

This somehow sneaked back in?

test/clang-rename/VarTest.cpp

4–9

Ah, we need some adjustments:

1. Add // REQUIRES: shell at the top
2. copying the temp file only makes sense if we do in-place replacement; which I think we should do
3. The CHECK comments get matched by the CHECKS. You'll want:

sed 's,//.*,,' %t.cpp | FileCheck %s

4. Isn't that offset wrong? Both vim and

$ grep -FUbo 'foo;' /tmp/test
tell me the offset is 145. So, why not instead do
-offset=$(grep -FUbo 'foo;' %t.cpp |head -1 |cut -d: -f1)

unittests/clang-rename/USRLocFindingTest.cpp

78

I'm so so so sorry, but I lied about raw strings :'( - apparently VS 2012 doesn't support them yet, so they're not allowed in clang :( :( :(

[mplant]

New diff!

clang-rename/ClangRename.cpp

17–43

Oh man I'll totally do that at some point.

142–146

That sounds fine for a follow up patch.

clang-rename/USRFinder.cpp

42

I already did! Funnily enough, you'll notice the Result argument is discarded, and the Result member is a single pointer! I just forgot to remove the constructor argument. oops!

clang-rename/USRLocFinder.cpp

44–48

Yeah oops.

[klimek]

Apart from the nits, I think this now LG :)

clang-rename/USRFinder.cpp

42

Heh :)

133–150

This now returns an uninitialized pointer if we find nothing... How about:

for (...) {
  if (...) {
    if (const NamedDecl *Result = Visitor.getNamedDecl())
      return Result;
    }
  }
}

return nullptr;

test/clang-rename/VarTest.cpp

2–5

I assume you checked that the test fails if you break the code? :)

[mplant]

Fix for nits!

[mplant]

clang-rename/USRFinder.cpp

133–150

Good catch!

test/clang-rename/VarTest.cpp

2–5

The realization that these had to go at the end because of the grep: >.<

[klimek]

Various changes needed. This is FYI.

[klimek]

Hm, I wanted to upload the changes that I needed to make, but phab apparently doesn't handle that well... So you'll have to make sure to look at what I changed before submitting.

[klimek]

Submitted as r215839. Note that
a) I had to do a couple of changes for this to compile without warning with latest head
b) I fixed the newFrontendActionFactory problem, please take a look how that works
c) the code is still grossly undertested; the next step will be to get test coverage up so people can work with the code; I just looked at a few places in USRFinder, and added FIXMEs; note that you'll need to do that for the rest of the code

Possible ways to add enough tests:

1. get a good test coverage tool (although that will still miss a lot, but will be a good first indicator)
2. reverse-TDD your code:

a) comment out all the code (*ALL* the code);
b) comment in enough code to make all tests pass (not that if you only need a single part of if (A || B), leave the part you don't need commented out (for example: if (A /* || B*/))
c) write test that forces you to uncomment part of the code
d) repeat until all your code is commented back in

If you have problems writing a test, please let me know.

CMakeLists.txt

 add_subdirectory(clang-apply-replacements)
 add_subdirectory(clang-modernize)
+add_subdirectory(clang-rename)
 add_subdirectory(modularize)
 add_subdirectory(module-map-checker)
 add_subdirectory(remove-cstr-calls)
 if(CLANG_ENABLE_STATIC_ANALYZER)
 add_subdirectory(clang-tidy)
 endif()
 
 add_subdirectory(clang-query)

Makefile

 ##===- tools/extra/Makefile --------------------------------*- Makefile -*-===##
 #
 #                     The LLVM Compiler Infrastructure
 #
 # This file is distributed under the University of Illinois Open Source
 # License. See LICENSE.TXT for details.
 #
 ##===----------------------------------------------------------------------===##
 
 CLANG_LEVEL := ../..
 
 include $(CLANG_LEVEL)/../../Makefile.config
 
 PARALLEL_DIRS := remove-cstr-calls tool-template modularize \
  module-map-checker pp-trace
-DIRS := clang-apply-replacements clang-modernize clang-tidy clang-query \
-  unittests
+DIRS := clang-apply-replacements clang-modernize clang-rename clang-tidy \
+  clang-query unittests
 
 include $(CLANG_LEVEL)/Makefile
 
 ###
 # Handle the nested test suite.
 
 ifneq ($(PROJ_SRC_ROOT),$(PROJ_OBJ_ROOT))
 $(RecursiveTargets)::

clang-rename/CMakeLists.txt

+set(LLVM_LINK_COMPONENTS support)
+
+add_clang_executable(clang-rename
+  ClangRename.cpp
+  USRFinder.cpp
+  USRFindingAction.cpp
+  USRLocFinder.cpp
+  RenamingAction.cpp
+  )
+
+target_link_libraries(clang-rename
+  clangAnalysis
+  clangAST
+  clangBasic
+  clangDriver
+  clangEdit
+  clangFrontend
+  clangFrontendTool
+  clangIndex
+  clangLex
+  clangParse
+  clangRewrite
+  clangRewriteFrontend
+  clangSerialization
+  clangSema
+  clangTooling
+  )
+
+install(TARGETS clang-rename RUNTIME DESTINATION bin)
 No newline at end of file

clang-rename/ClangRename.cpp

+//===--- tools/extra/clang-rename/ClangRename.cpp - Clang rename tool -----===//
+//
+//                     The LLVM Compiler Infrastructure
+//
+// This file is distributed under the University of Illinois Open Source
+// License. See LICENSE.TXT for details.
+//
+//===----------------------------------------------------------------------===//
+///
+/// \file
+/// \brief This file implements a clang-rename tool that automatically finds and
+/// renames symbols in C++ code.
+///
+//===----------------------------------------------------------------------===//
+
+#include "USRFindingAction.h"
+#include "RenamingAction.h"
+#include "clang/AST/ASTConsumer.h"
+#include "clang/AST/ASTContext.h"
+#include "clang/Basic/FileManager.h"
+#include "clang/Basic/LangOptions.h"
+#include "clang/Basic/TargetInfo.h"
+#include "clang/Basic/TargetOptions.h"
+#include "clang/Frontend/CommandLineSourceLoc.h"
+#include "clang/Frontend/CompilerInstance.h"
+#include "clang/Frontend/FrontendAction.h"
+#include "clang/Frontend/TextDiagnosticPrinter.h"
+#include "clang/Lex/Preprocessor.h"
+#include "clang/Lex/Lexer.h"
+#include "clang/Parse/Parser.h"
+#include "clang/Parse/ParseAST.h"
+#include "clang/Rewrite/Core/Rewriter.h"
+#include "clang/Tooling/CommonOptionsParser.h"
+#include "clang/Tooling/Refactoring.h"
+#include "clang/Tooling/Tooling.h"
+#include "llvm/ADT/IntrusiveRefCntPtr.h"
+#include "llvm/Support/Host.h"
+#include <stdio.h>
+#include <stdlib.h>
+#include <time.h>
+#include <ctype.h>
+#include <string>
+#include <vector>
+
+using namespace llvm;
+
+cl::OptionCategory ClangRenameCategory("Clang-rename options");
+
+static cl::opt<std::string>
+NewName(
+    "new-name",
+    cl::desc("The new name to change the symbol to."),
+    cl::cat(ClangRenameCategory));
+static cl::opt<unsigned>
+SymbolOffset(
+    "offset",
+    cl::desc("Locates the symbol by offset as opposed to <line>:<column>."),
+    cl::cat(ClangRenameCategory));
+static cl::opt<bool>
+Inplace(
+    "i",
+    cl::desc("Overwrite edited <file>s."),
+    cl::cat(ClangRenameCategory));
+static cl::opt<bool>
+PrintName(
+    "pn",
+    cl::desc("Print the found symbol's name prior to renaming to stderr."),
+    cl::cat(ClangRenameCategory));
+static cl::opt<bool>
+PrintLocations(
+    "pl",
+    cl::desc("Print the locations affected by renaming to stderr."),
+    cl::cat(ClangRenameCategory));
+
+#define CLANG_RENAME_VERSION "0.0.1"
+
+static void PrintVersion() {
+  outs() << "clang-rename version " << CLANG_RENAME_VERSION << "\n";
+}
+
+using namespace clang;
+
+const char RenameUsage[] = "A tool to rename symbols in C/C++ code.\n\
+clang-rename renames every occurrence of a symbol found at <offset> in\n\
+<source0>. If -i is specified, the edited files are overwritten to disk.\n\
+Otherwise, the results are written to stdout.\n";
+
+int main(int argc, const char **argv) {
+  cl::SetVersionPrinter(PrintVersion);
+  tooling::CommonOptionsParser OP(argc, argv, ClangRenameCategory, RenameUsage);
+
+  // Check the arguments for correctness.
+
+  if (NewName.empty()) {
+    errs() << "clang-rename: no new name provided.\n\n";
+    cl::PrintHelpMessage();
+    exit(1);
+  }
+
+  // Get the USRs.
+  auto Files = OP.getSourcePathList();
+  tooling::RefactoringTool Tool(OP.getCompilations(), Files);
+  rename::USRFindingAction USRAction(SymbolOffset);
+
+  // Find the USRs.
+  Tool.run(tooling::newFrontendActionFactory(&USRAction).get());
+  const auto &USRs = USRAction.getUSRs();
+  const auto &PrevName = USRAction.getUSRSpelling();
+
+  if (PrevName.empty())
+    // An error should have already been printed.
+    exit(1);
+
+  if (PrintName)
+    errs() << "clang-rename: found name: " << PrevName;
+
+  // Perform the renaming.
+  rename::RenamingAction RenameAction(NewName, PrevName, USRs,
+                                      Tool.getReplacements(), PrintLocations);
+  auto Factory = tooling::newFrontendActionFactory(&RenameAction);
+  int res;
+
+  if (Inplace) {
+    res = Tool.runAndSave(Factory.get());
+  } else {
+    res = Tool.run(Factory.get());
+
+    // Write every file to stdout. Right now we just barf the files without any
+    // indication of which files start where, other than that we print the files
+    // in the same order we see them.
+    LangOptions DefaultLangOptions;
+    IntrusiveRefCntPtr<DiagnosticOptions> DiagOpts =
+        new DiagnosticOptions();
+    TextDiagnosticPrinter DiagnosticPrinter(errs(), &*DiagOpts);
+    DiagnosticsEngine Diagnostics(
+        IntrusiveRefCntPtr<DiagnosticIDs>(new DiagnosticIDs()),
+        &*DiagOpts, &DiagnosticPrinter, false);
+    auto &FileMgr = Tool.getFiles();
+    SourceManager Sources(Diagnostics, FileMgr);
+    Rewriter Rewrite(Sources, DefaultLangOptions);
+
+    Tool.applyAllReplacements(Rewrite);
+    for (const auto &File : Files) {
+      const auto *Entry = FileMgr.getFile(File);
+      auto ID = Sources.translateFile(Entry);
+      Rewrite.getEditBuffer(ID).write(outs());
+    }
+  }
+
+  exit(res);
+}

clang-rename/Makefile

+##===- tools/extra/clang-rename/Makefile -------------------*- Makefile -*-===##
+#
+# The LLVM Compiler Infrastructure
+#
+# This file is distributed under the University of Illinois Open Source
+# License. See LICENSE.TXT for details.
+#
+##===----------------------------------------------------------------------===##
+
+CLANG_LEVEL := ../../..
+TOOLNAME = clang-rename
+include $(CLANG_LEVEL)/../../Makefile.config
+
+DIRS = test
+
+include $(CLANG_LEVEL)/Makefile

clang-rename/RenamingAction.h

+//===--- tools/extra/clang-rename/RenamingAction.h - Clang rename tool ----===//
+//
+//                     The LLVM Compiler Infrastructure
+//
+// This file is distributed under the University of Illinois Open Source
+// License. See LICENSE.TXT for details.
+//
+//===----------------------------------------------------------------------===//
+///
+/// \file
+/// \brief Provides an action to rename every symbol at a point.
+///
+//===----------------------------------------------------------------------===//
+
+#ifndef LLVM_CLANG_TOOLS_EXTRA_CLANG_RENAME_RENAMING_ACTION_H_
+#define LLVM_CLANG_TOOLS_EXTRA_CLANG_RENAME_RENAMING_ACTION_H_
+
+#include "clang/Tooling/Refactoring.h"
+
+namespace clang {
+class ASTConsumer;
+class CompilerInstance;
+
+namespace rename {
+
+class RenamingAction {
+public:
+  RenamingAction(const std::string &NewName, const std::string &PrevName,
+                 const std::vector<std::string> &USRs,
+                 tooling::Replacements &Replaces, bool PrintLocations = false)
+      : NewName(NewName), PrevName(PrevName), USRs(USRs), Replaces(Replaces),
+        PrintLocations(PrintLocations) {
+  }
+
+  std::unique_ptr<ASTConsumer> newASTConsumer();
+
+private:
+  const std::string &NewName, &PrevName;
+  const std::vector<std::string> &USRs;
+  tooling::Replacements &Replaces;
+  bool PrintLocations;
+};
+
+}
+}
+
+#endif // LLVM_CLANG_TOOLS_EXTRA_CLANG_RENAME_RENAMING_ACTION_H_

clang-rename/RenamingAction.cpp

+//===--- tools/extra/clang-rename/RenamingAction.cpp - Clang rename tool --===//
+//
+//                     The LLVM Compiler Infrastructure
+//
+// This file is distributed under the University of Illinois Open Source
+// License. See LICENSE.TXT for details.
+//
+//===----------------------------------------------------------------------===//
+///
+/// \file
+/// \brief Provides an action to rename every symbol at a point.
+///
+//===----------------------------------------------------------------------===//
+
+#include "RenamingAction.h"
+#include "USRLocFinder.h"
+#include "clang/AST/ASTConsumer.h"
+#include "clang/AST/ASTContext.h"
+#include "clang/Basic/FileManager.h"
+#include "clang/Frontend/CompilerInstance.h"
+#include "clang/Frontend/FrontendAction.h"
+#include "clang/Lex/Preprocessor.h"
+#include "clang/Lex/Lexer.h"
+#include "clang/Tooling/CommonOptionsParser.h"
+#include "clang/Tooling/Refactoring.h"
+#include "clang/Tooling/Tooling.h"
+#include <stdio.h>
+#include <stdlib.h>
+#include <ctype.h>
+#include <string>
+#include <vector>
+
+using namespace llvm;
+
+namespace clang {
+namespace rename {
+
+class RenamingASTConsumer : public ASTConsumer {
+public:
+  RenamingASTConsumer(const std::string &NewName,
+                      const std::string &PrevName,
+                      const std::vector<std::string> &USRs,
+                      tooling::Replacements &Replaces,
+                      bool PrintLocations)
+      : NewName(NewName), PrevName(PrevName), USRs(USRs), Replaces(Replaces),
+        PrintLocations(PrintLocations) {
+  }
+
+  void HandleTranslationUnit(ASTContext &Context) override {
+    const auto &SourceMgr = Context.getSourceManager();
+    std::vector<SourceLocation> RenamingCandidates;
+    std::vector<SourceLocation> NewCandidates;
+
+    for (const auto &USR : USRs) {
+      NewCandidates = getLocationsOfUSR(USR, Context.getTranslationUnitDecl());
+      RenamingCandidates.insert(RenamingCandidates.end(), NewCandidates.begin(),
+                                NewCandidates.end());
+      NewCandidates.clear();
+    }
+
+    auto PrevNameLen = PrevName.length();
+    if (PrintLocations)
+      for (const auto &Loc : RenamingCandidates) {
+        FullSourceLoc FullLoc(Loc, SourceMgr);
+        errs() << "clang-rename: renamed at: " << SourceMgr.getFilename(Loc)
+               << ":" << FullLoc.getSpellingLineNumber() << ":"
+               << FullLoc.getSpellingColumnNumber() << "\n";
+        Replaces.insert(tooling::Replacement(SourceMgr, Loc, PrevNameLen,
+                                             NewName));
+      }
+    else
+      for (const auto &Loc : RenamingCandidates)
+        Replaces.insert(tooling::Replacement(SourceMgr, Loc, PrevNameLen,
+                                             NewName));
+  }
+
+private:
+  const std::string &NewName, &PrevName;
+  const std::vector<std::string> &USRs;
+  tooling::Replacements &Replaces;
+  bool PrintLocations;
+};
+
+std::unique_ptr<ASTConsumer> RenamingAction::newASTConsumer() {
+  return llvm::make_unique<RenamingASTConsumer>(NewName, PrevName, USRs,
+                                                Replaces, PrintLocations);
+}
+
+}
+}

clang-rename/USRFinder.h

+//===--- tools/extra/clang-rename/USRFinder.h - Clang rename tool ---------===//
+//
+//                     The LLVM Compiler Infrastructure
+//
+// This file is distributed under the University of Illinois Open Source
+// License. See LICENSE.TXT for details.
+//
+//===----------------------------------------------------------------------===//
+///
+/// \file
+/// \brief Methods for determining the USR of a symbol at a location in source
+/// code.
+///
+//===----------------------------------------------------------------------===//
+#ifndef LLVM_CLANG_TOOLS_EXTRA_CLANG_RENAME_USR_FINDER_H
+#define LLVM_CLANG_TOOLS_EXTRA_CLANG_RENAME_USR_FINDER_H
+
+#include <string>
+
+namespace clang {
+class ASTContext;
+class Decl;
+class SourceLocation;
+class NamedDecl;
+
+namespace rename {
+
+// Given an AST context and a point, returns a NamedDecl identifying the symbol
+// at the point. Returns null if nothing is found at the point.
+const NamedDecl *getNamedDeclAt(const ASTContext &Context,
+                                const SourceLocation Point);
+
+// Converts a Decl into a USR.
+std::string getUSRForDecl(const Decl *Decl);
+
+}
+}
+
+#endif // LLVM_CLANG_TOOLS_EXTRA_CLANG_RENAME_USR_FINDER_H

clang-rename/USRFinder.cpp

+//===--- tools/extra/clang-rename/USRFinder.cpp - Clang rename tool -------===//
+//
+//                     The LLVM Compiler Infrastructure
+//
+// This file is distributed under the University of Illinois Open Source
+// License. See LICENSE.TXT for details.
+//
+//===----------------------------------------------------------------------===//
+///
+/// \file Implements a recursive AST visitor that finds the USR of a symbol at a
+/// point.
+///
+//===----------------------------------------------------------------------===//
+
+#include "USRFinder.h"
+#include "clang/AST/AST.h"
+#include "clang/AST/ASTContext.h"
+#include "clang/AST/RecursiveASTVisitor.h"
+#include "clang/Lex/Lexer.h"
+#include "clang/Index/USRGeneration.h"
+#include "llvm/ADT/SmallVector.h"
+
+using namespace llvm;
+
+namespace clang {
+namespace rename {
+
+// NamedDeclFindingASTVisitor recursively visits each AST node to find the
+// symbol underneath the cursor.
+// FIXME: move to seperate .h/.cc file if this gets too large.
+namespace {
+class NamedDeclFindingASTVisitor
+    : public clang::RecursiveASTVisitor<NamedDeclFindingASTVisitor> {
+public:
+  // \brief Finds the NamedDecl at a point in the source.
+  // \param Point the location in the source to search for the NamedDecl.
+  explicit NamedDeclFindingASTVisitor(const SourceManager &SourceMgr,
+                                      const SourceLocation Point)
+      : Result(nullptr), SourceMgr(SourceMgr),
+        Point(Point) {
+  }
+
+  // Declaration visitors:
+
+  // \brief Checks if the point falls within the NameDecl. This covers every
+  // declaration of a named entity that we may come across. Usually, just
+  // checking if the point lies within the length of the name of the declaration
+  // and the start location is sufficient.
+  bool VisitNamedDecl(const NamedDecl *Decl) {
+    return setResult(Decl, Decl->getLocation(),
+                     Decl->getNameAsString().length());
+  }
+
+  // Expression visitors:
+
+  bool VisitDeclRefExpr(const DeclRefExpr *Expr) {
+    // Check the namespace specifier first.
+    if (!checkNestedNameSpecifierLoc(Expr->getQualifierLoc()))
+      return false;
+
+    const auto *Decl = Expr->getFoundDecl();
+    return setResult(Decl, Expr->getLocation(),
+                     Decl->getNameAsString().length());
+  }
+
+  bool VisitMemberExpr(const MemberExpr *Expr) {
+    const auto *Decl = Expr->getFoundDecl().getDecl();
+    return setResult(Decl, Expr->getMemberLoc(),
+                     Decl->getNameAsString().length());
+  }
+
+  // Other:
+
+  const NamedDecl *getNamedDecl() {
+    return Result;
+  }
+
+private:
+  // \brief Determines if a namespace qualifier contains the point.
+  // \returns false on success and sets Result.
+  bool checkNestedNameSpecifierLoc(NestedNameSpecifierLoc NameLoc) {
+    while (NameLoc) {
+      const auto *Decl = NameLoc.getNestedNameSpecifier()->getAsNamespace();
+      if (Decl && !setResult(Decl, NameLoc.getLocalBeginLoc(),
+                             Decl->getNameAsString().length()))
+        return false;
+      NameLoc = NameLoc.getPrefix();
+    }
+    return true;
+  }
+
+  // \brief Sets Result to Decl if the Point is within Start and End.
+  // \returns false on success.
+  bool setResult(const NamedDecl *Decl, SourceLocation Start,
+                 SourceLocation End) {
+    if (!Start.isValid() || !Start.isFileID() || !End.isValid() ||
+        !End.isFileID() || !isPointWithin(Start, End)) {
+      return true;
+    }
+    Result = Decl;
+    return false;
+  }
+
+  // \brief Sets Result to Decl if Point is within Loc and Loc + Offset.
+  // \returns false on success.
+  bool setResult(const NamedDecl *Decl, SourceLocation Loc,
+                 unsigned Offset) {
+    // FIXME: Add test for Offset == 0. Add test for Offset - 1 (vs -2 etc).
+    return Offset == 0 ||
+           setResult(Decl, Loc, Loc.getLocWithOffset(Offset - 1));
+  }
+
+  // \brief Determines if the Point is within Start and End.
+  bool isPointWithin(const SourceLocation Start, const SourceLocation End) {
+    // FIXME: Add tests for Point == End.
+    return Point == Start || Point == End ||
+           (SourceMgr.isBeforeInTranslationUnit(Start, Point) &&
+            SourceMgr.isBeforeInTranslationUnit(Point, End));
+  }
+
+  const NamedDecl *Result;
+  const SourceManager &SourceMgr;
+  const SourceLocation Point; // The location to find the NamedDecl.
+};
+}
+
+const NamedDecl *getNamedDeclAt(const ASTContext &Context,
+                                const SourceLocation Point) {
+  const auto &SourceMgr = Context.getSourceManager();
+  const auto SearchFile = SourceMgr.getFilename(Point);
+
+  NamedDeclFindingASTVisitor Visitor(SourceMgr, Point);
+
+  // We only want to search the decls that exist in the same file as the point.
+  auto Decls = Context.getTranslationUnitDecl()->decls();
+  for (auto &CurrDecl : Decls) {
+    const auto FileLoc = CurrDecl->getLocStart();
+    const auto FileName = SourceMgr.getFilename(FileLoc);
+    // FIXME: Add test.
+    if (FileName == SearchFile) {
+      Visitor.TraverseDecl(CurrDecl);
+      if (const NamedDecl *Result = Visitor.getNamedDecl()) {
+        return Result;
+      }
+    }
+  }
+
+  return nullptr;
+}
+
+std::string getUSRForDecl(const Decl *Decl) {
+  llvm::SmallVector<char, 128> Buff;
+
+  // FIXME: Add test for the nullptr case.
+  if (Decl == nullptr || index::generateUSRForDecl(Decl, Buff))
+    return "";
+
+  return std::string(Buff.data(), Buff.size());
+}
+
+} // namespace clang
+} // namespace rename

clang-rename/USRFindingAction.h

+//===--- tools/extra/clang-rename/USRFindingAction.h - Clang rename tool --===//
+//
+//                     The LLVM Compiler Infrastructure
+//
+// This file is distributed under the University of Illinois Open Source
+// License. See LICENSE.TXT for details.
+//
+//===----------------------------------------------------------------------===//
+///
+/// \file
+/// \brief Provides an action to find all relevent USRs at a point.
+///
+//===----------------------------------------------------------------------===//
+
+#ifndef LLVM_CLANG_TOOLS_EXTRA_CLANG_RENAME_USR_FINDING_ACTION_H_
+#define LLVM_CLANG_TOOLS_EXTRA_CLANG_RENAME_USR_FINDING_ACTION_H_
+
+#include "clang/Frontend/FrontendAction.h"
+
+namespace clang {
+class ASTConsumer;
+class CompilerInstance;
+class NamedDecl;
+
+namespace rename {
+
+struct USRFindingAction {
+  USRFindingAction(unsigned Offset) : SymbolOffset(Offset) {
+  }
+  std::unique_ptr<ASTConsumer> newASTConsumer();
+
+  // \brief get the spelling of the USR(s) as it would appear in source files.
+  const std::string &getUSRSpelling() {
+    return SpellingName;
+  }
+
+  const std::vector<std::string> &getUSRs() {
+    return USRs;
+  }
+
+private:
+  unsigned SymbolOffset;
+  std::string SpellingName;
+  std::vector<std::string> USRs;
+};
+
+}
+}
+
+#endif // LLVM_CLANG_TOOLS_EXTRA_CLANG_RENAME_USR_FINDING_ACTION_H_

clang-rename/USRFindingAction.cpp

+//===--- tools/extra/clang-rename/USRFindingAction.cpp - Clang rename tool ===//
+//
+//                     The LLVM Compiler Infrastructure
+//
+// This file is distributed under the University of Illinois Open Source
+// License. See LICENSE.TXT for details.
+//
+//===----------------------------------------------------------------------===//
+///
+/// \file
+/// \brief Provides an action to rename every symbol at a point.
+///
+//===----------------------------------------------------------------------===//
+
+#include "USRFindingAction.h"
+#include "USRFinder.h"
+#include "clang/AST/AST.h"
+#include "clang/AST/ASTConsumer.h"
+#include "clang/AST/ASTContext.h"
+#include "clang/Basic/FileManager.h"
+#include "clang/Frontend/CompilerInstance.h"
+#include "clang/Frontend/FrontendAction.h"
+#include "clang/Lex/Preprocessor.h"
+#include "clang/Lex/Lexer.h"
+#include "clang/Tooling/CommonOptionsParser.h"
+#include "clang/Tooling/Refactoring.h"
+#include "clang/Tooling/Tooling.h"
+#include <stdio.h>
+#include <stdlib.h>
+#include <ctype.h>
+#include <string>
+#include <vector>
+
+using namespace llvm;
+
+namespace clang {
+namespace rename {
+
+// Get the USRs for the constructors of the class.
+static std::vector<std::string> getAllConstructorUSRs(
+    const CXXRecordDecl *Decl) {
+  std::vector<std::string> USRs;
+
+  // We need to get the definition of the record (as opposed to any forward
+  // declarations) in order to find the constructor and destructor.
+  const auto *RecordDecl = Decl->getDefinition();
+
+  // Iterate over all the constructors and add their USRs.
+  for (const auto &CtorDecl : RecordDecl->ctors())
+    USRs.push_back(getUSRForDecl(CtorDecl));
+
+  // Ignore destructors. GetLocationsOfUSR will find the declaration of and
+  // explicit calls to a destructor through TagTypeLoc (and it is better for the
+  // purpose of renaming).
+  //
+  // For example, in the following code segment,
+  //  1  class C {
+  //  2    ~C();
+  //  3  };
+  // At line 3, there is a NamedDecl starting from '~' and a TagTypeLoc starting
+  // from 'C'.
+
+  return USRs;
+}
+
+struct NamedDeclFindingConsumer : public ASTConsumer {
+  void HandleTranslationUnit(ASTContext &Context) override {
+    const auto &SourceMgr = Context.getSourceManager();
+    // The file we look for the USR in will always be the main source file.
+    const auto Point = SourceMgr.getLocForStartOfFile(
+        SourceMgr.getMainFileID()).getLocWithOffset(SymbolOffset);
+    if (!Point.isValid())
+      return;
+    const NamedDecl *FoundDecl = getNamedDeclAt(Context, Point);
+    if (FoundDecl == nullptr) {
+      FullSourceLoc FullLoc(Point, SourceMgr);
+      errs() << "clang-rename: could not find symbol at "
+             << SourceMgr.getFilename(Point) << ":"
+             << FullLoc.getSpellingLineNumber() << ":"
+             << FullLoc.getSpellingColumnNumber() << " (offset " << SymbolOffset
+             << ").\n";
+      return;
+    }
+
+    // If the decl is a constructor or destructor, we want to instead take the
+    // decl of the parent record.
+    if (const auto *CtorDecl = dyn_cast<CXXConstructorDecl>(FoundDecl))
+      FoundDecl = CtorDecl->getParent();
+    else if (const auto *DtorDecl = dyn_cast<CXXDestructorDecl>(FoundDecl))
+      FoundDecl = DtorDecl->getParent();
+
+    // If the decl is in any way relatedpp to a class, we want to make sure we
+    // search for the constructor and destructor as well as everything else.
+    if (const auto *Record = dyn_cast<CXXRecordDecl>(FoundDecl))
+      *USRs = getAllConstructorUSRs(Record);
+
+    USRs->push_back(getUSRForDecl(FoundDecl));
+    *SpellingName = FoundDecl->getNameAsString();
+  }
+
+  unsigned SymbolOffset;
+  std::string *SpellingName;
+  std::vector<std::string> *USRs;
+};
+
+std::unique_ptr<ASTConsumer>
+USRFindingAction::newASTConsumer() {
+  std::unique_ptr<NamedDeclFindingConsumer> Consumer(
+      new NamedDeclFindingConsumer);
+  SpellingName = "";
+  Consumer->SymbolOffset = SymbolOffset;
+  Consumer->USRs = &USRs;
+  Consumer->SpellingName = &SpellingName;
+  return std::move(Consumer);
+}
+
+} // namespace rename
+} // namespace clang

clang-rename/USRLocFinder.h

+//===--- tools/extra/clang-rename/USRLocFinder.h - Clang rename tool ------===//
+//
+//                     The LLVM Compiler Infrastructure
+//
+// This file is distributed under the University of Illinois Open Source
+// License. See LICENSE.TXT for details.
+//
+//===----------------------------------------------------------------------===//
+///
+/// \file
+/// \brief Provides functionality for finding all instances of a USR in a given
+/// AST.
+///
+//===----------------------------------------------------------------------===//
+
+#ifndef LLVM_CLANG_TOOLS_EXTRA_CLANG_RENAME_USR_LOC_FINDER_H
+#define LLVM_CLANG_TOOLS_EXTRA_CLANG_RENAME_USR_LOC_FINDER_H
+
+#include <string>
+#include <vector>
+
+namespace clang {
+
+class Decl;
+class SourceLocation;
+
+namespace rename {
+
+// FIXME: make this an AST matcher. Wouldn't that be awesome??? I agree!
+std::vector<SourceLocation> getLocationsOfUSR(const std::string usr,
+                                              Decl *decl);
+}
+}
+
+#endif // LLVM_CLANG_TOOLS_EXTRA_CLANG_RENAME_USR_LOC_FINDER_H

clang-rename/USRLocFinder.cpp

+//===--- tools/extra/clang-rename/USRLocFinder.cpp - Clang rename tool ----===//
+//
+//                     The LLVM Compiler Infrastructure
+//
+// This file is distributed under the University of Illinois Open Source
+// License. See LICENSE.TXT for details.
+//
+//===----------------------------------------------------------------------===//
+///
+/// \file
+/// \brief Mehtods for finding all instances of a USR. Our strategy is very
+/// simple; we just compare the USR at every relevant AST node with the one
+/// provided.
+///
+//===----------------------------------------------------------------------===//
+
+#include "USRLocFinder.h"
+#include "USRFinder.h"
+#include "clang/AST/ASTContext.h"
+#include "clang/AST/RecursiveASTVisitor.h"
+#include "clang/Basic/SourceLocation.h"
+#include "clang/Index/USRGeneration.h"
+#include "llvm/ADT/SmallVector.h"
+
+using namespace llvm;
+
+namespace clang {
+namespace rename {
+
+namespace {
+// \brief This visitor recursively searches for all instances of a USR in a
+// translation unit and stores them for later usage.
+class USRLocFindingASTVisitor
+    : public clang::RecursiveASTVisitor<USRLocFindingASTVisitor> {
+public:
+  explicit USRLocFindingASTVisitor(const std::string USR) : USR(USR) {
+  }
+
+  // Declaration visitors:
+
+  bool VisitNamedDecl(const NamedDecl *Decl) {
+    if (getUSRForDecl(Decl) == USR) {
+      LocationsFound.push_back(Decl->getLocation());
+    }
+    return true;
+  }
+
+  // Expression visitors:
+
+  bool VisitDeclRefExpr(const DeclRefExpr *Expr) {
+    const auto *Decl = Expr->getFoundDecl();
+
+    checkNestedNameSpecifierLoc(Expr->getQualifierLoc());
+    if (getUSRForDecl(Decl) == USR) {
+      LocationsFound.push_back(Expr->getLocation());
+    }
+
+    return true;
+  }
+
+  bool VisitMemberExpr(const MemberExpr *Expr) {
+    const auto *Decl = Expr->getFoundDecl().getDecl();
+    if (getUSRForDecl(Decl) == USR) {
+      LocationsFound.push_back(Expr->getMemberLoc());
+    }
+    return true;
+  }
+
+  // Non-visitors:
+
+  // \brief Returns a list of unique locations. Duplicate or overlapping
+  // locations are erroneous and should be reported!
+  const std::vector<clang::SourceLocation> &getLocationsFound() const {
+    return LocationsFound;
+  }
+
+private:
+  // Namespace traversal:
+  void checkNestedNameSpecifierLoc(NestedNameSpecifierLoc NameLoc) {
+    while (NameLoc) {
+      const auto *Decl = NameLoc.getNestedNameSpecifier()->getAsNamespace();
+      if (Decl && getUSRForDecl(Decl) == USR)
+        LocationsFound.push_back(NameLoc.getLocalBeginLoc());
+      NameLoc = NameLoc.getPrefix();
+    }
+  }
+
+  // All the locations of the USR were found.
+  const std::string USR;
+  std::vector<clang::SourceLocation> LocationsFound;
+};
+} // namespace
+
+std::vector<SourceLocation> getLocationsOfUSR(const std::string USR,
+                                              Decl *Decl) {
+  USRLocFindingASTVisitor visitor(USR);
+
+  visitor.TraverseDecl(Decl);
+  return visitor.getLocationsFound();
+}
+
+} // namespace rename
+} // namespace clang

test/CMakeLists.txt

 
 set(CLANG_TOOLS_TEST_DEPS
   # Base line deps.
   FileCheck count not
 
   # Individual tools we test.
   clang-apply-replacements
   clang-modernize
+  clang-rename
   clang-query
   clang-tidy
   modularize
   module-map-checker
   pp-trace
   remove-cstr-calls
 
   # Unit tests

test/clang-rename/VarTest.cpp

+namespace A {
+int foo;  // CHECK: int hector;
+}
+int foo;  // CHECK: int foo;
+int bar = foo; // CHECK: bar = foo;
+int baz = A::foo; // CHECK: baz = A::hector;
+void fun1() {
+  struct {
+    int foo; // CHECK: int foo;
+  } b = { 100 };
+  int foo = 100; // CHECK: int foo
+  baz = foo; // CHECK: baz = foo;
+  {
+    extern int foo; // CHECK: int foo;
+    baz = foo; // CHECK: baz = foo;
+    foo = A::foo + baz; // CHECK: foo = A::hector + baz;
+    A::foo = b.foo; // CHECK: A::hector = b.foo;
+  }
+  foo = b.foo; // CHECK: foo = b.foo;
+}
+// REQUIRES: shell
+// RUN: cat %s > %t.cpp
+// RUN: clang-rename -offset=$(grep -FUbo 'foo;' %t.cpp | head -1 | cut -d: -f1) -new-name=hector %t.cpp -i --
+// RUN: sed 's,//.*,,' %t.cpp | FileCheck %s

unittests/CMakeLists.txt

 add_custom_target(ExtraToolsUnitTests)
 set_target_properties(ExtraToolsUnitTests PROPERTIES FOLDER "Extra Tools Unit Tests")
 
 function(add_extra_unittest test_dirname)
   add_unittest(ExtraToolsUnitTests ${test_dirname} ${ARGN})
 endfunction()
 
 add_subdirectory(clang-apply-replacements)
 add_subdirectory(clang-modernize)
+add_subdirectory(clang-rename)
 add_subdirectory(clang-query)
 add_subdirectory(clang-tidy)

unittests/clang-rename/CMakeLists.txt

+set(LLVM_LINK_COMPONENTS
+  support
+  )
+
+get_filename_component(CLANG_RENAME_SOURCE_DIR
+  ${CMAKE_CURRENT_SOURCE_DIR}/../../clang-rename REALPATH)
+include_directories(
+  ${CLANG_RENAME_SOURCE_DIR}
+  )
+
+add_extra_unittest(ClangRenameTests
+  USRLocFindingTest.cpp
+  ${CLANG_RENAME_SOURCE_DIR}/USRFinder.cpp
+  ${CLANG_RENAME_SOURCE_DIR}/USRFindingAction.cpp
+  )
+
+target_link_libraries(ClangRenameTests
+  clangAnalysis
+  clangAST
+  clangBasic
+  clangDriver
+  clangEdit
+  clangFrontend
+  clangFrontendTool
+  clangIndex
+  clangLex
+  clangParse
+  clangRewrite
+  clangRewriteFrontend
+  clangSerialization
+  clangSema
+  clangTooling
+  )
 No newline at end of file

unittests/clang-rename/Makefile

+##===- unittests/clang-rename/Makefile ---------------------*- Makefile -*-===##
+#
+#                     The LLVM Compiler Infrastructure
+#
+# This file is distributed under the University of Illinois Open Source
+# License. See LICENSE.TXT for details.
+#
+##===----------------------------------------------------------------------===##
+
+CLANG_LEVEL = ../../../..
+include $(CLANG_LEVEL)/../../Makefile.config
+
+TESTNAME = ClangRenameTests
+LINK_COMPONENTS := asmparser bitreader support MC MCParser option \
+     TransformUtils
+USEDLIBS = clangAnalysis.a clangAST.a clangBasic.a clangDriver.a clangEdit.a \
+     clangFrontend.a clangFrontendTool.a clangIndex.a clangLex.a \
+     clangParse.a clangRewrite.a clangRewriteFrontend.a \
+     clangSerialization.a clangSema.a clangTooling.a
+
+include $(CLANG_LEVEL)/Makefile
+MAKEFILE_UNITTEST_NO_INCLUDE_COMMON := 1
+CPP.Flags += -I(PROJ_SRC_DIR)/../../clang-rename
+include $(LLVM_SRC_ROOT)/unittests/Makefile.unittest

unittests/clang-rename/USRLocFindingTest.cpp

+#include "USRFindingAction.h"
+#include "gtest/gtest.h"
+#include "clang/Tooling/Tooling.h"
+#include <stdio.h>
+#include <set>
+#include <map>
+#include <vector>
+
+namespace clang {
+namespace rename {
+namespace test {
+
+// Determines if the symbol group invariants hold. To recap, those invariants
+// are:
+//  (1) All symbols in the same symbol group share the same USR.
+//  (2) Two symbols from two different groups do not share the same USR.
+static void testOffsetGroups(const char *Code,
+                             const std::vector<std::vector<unsigned>> Groups) {
+  std::set<std::string> AllUSRs, CurrUSR;
+
+  for (const auto &Group : Groups) {
+    // Groups the invariants do not hold then the value of USR is also invalid,
+    // but at that point the test has already failed and USR ceases to be
+    // useful.
+    std::string USR;
+    for (const auto &Offset : Group) {
+      USRFindingAction Action(Offset);
+      auto Factory = tooling::newFrontendActionFactory(&Action);
+      EXPECT_TRUE(tooling::runToolOnCode(Factory->create(), Code));
+      const auto &USRs = Action.getUSRs();
+      EXPECT_EQ(1u, USRs.size());
+      USR = USRs[0];
+      CurrUSR.insert(USR);
+    }
+    EXPECT_EQ(1u, CurrUSR.size());
+    CurrUSR.clear();
+    AllUSRs.insert(USR);
+  }
+
+  EXPECT_EQ(Groups.size(), AllUSRs.size());
+}
+
+
+TEST(USRLocFinding, FindsVarUSR) {
+  const char VarTest[] = "\n\
+namespace A {\n\
+int foo;\n\
+}\n\
+int foo;\n\
+int bar = foo;\n\
+int baz = A::foo;\n\
+void fun1() {\n\
+  struct {\n\
+    int foo;\n\
+  } b = { 100 };\n\
+  int foo = 100;\n\
+  baz = foo;\n\
+  {\n\
+    extern int foo;\n\
+    baz = foo;\n\
+    foo = A::foo + baz;\n\
+    A::foo = b.foo;\n\
+  }\n\
+ foo = b.foo;\n\
+}\n";
+  std::vector<std::vector<unsigned>> VarTestOffsets = {
+    { 19, 63, 205, 223 },
+    { 30, 45, 172, 187 },
+    { 129, 148, 242 },
+  };
+
+  testOffsetGroups(VarTest, VarTestOffsets);
+}
+
+}
+}
+}