[llvm] llvm-tapi-diff

[spowell]

Summary

This patch introduces a new tool, llvm-tapi-diff, that compares and returns the diff of two TBD files.

[spowell]

fixed patch upload for -U999999

[spowell]

clang-format fixes and replaced macho.dylib for macho.yaml

[JDevlieghere]

llvm/lib/TextAPI/Platform.cpp

134

Should this be llvm::MachO::PlatformKind?

llvm/tools/llvm-tapi-diff/DiffEngine.cpp

2

This seems to be missing a few dashes.

221–222

This is still using 1 and 2 while everything else is now using LHS and RHS.

325–327

The llvm style guidelines say no braces around single-line ifs.

llvm/tools/llvm-tapi-diff/DiffEngine.h

49–59

Rather than documenting the class as a whole, it's good practice to document the individual members like this. This is much more maintainable when a member gets added or removed, and Doxygen will associate the comment with the variable for you, which means you don't have to repeat the type etc.

55–57

Should these members really be public? If the answer is yes, you'd want to use struct instead of class, which has public visibility by default. It's not so much about avoiding the access specifier on line 53, but more about conveying your intention to other developers.

147

This probably also needs an unreachable. Same for the function below. There might be more in this patch.

163

Several files seem to be missing newlines at the end.

[spowell]

llvm.MachO.PlatformKind => llvm::MachO::PlatformKind in platform.cpp; removed 1 and 2 in favor of LHS and RHS in DiffEngine.cpp; refactored comments in DiffEngine.h; changed DiffOutput from class to struct; added llvm_unreachable in switch statements in DiffEngine.h; Added new lines at end of files.

[spowell]

added new lines to test input files.

[spowell]

rebased patch from main to fix patch apply issue, added new line for CMakeLists.txt

[spowell]

uploading patch again to trigger rebuild

[spowell]

update separators in tests

[spowell]

use regex to try to fix windows failure.

[spowell]

fixed brackets for regex in test

[JDevlieghere]

llvm/tools/llvm-tapi-diff/DiffEngine.cpp

10–11

This is not a header tho :-)

93–96

Could we reduce the density of this code by adding a helper that looks something like:

void DiffAttribute(StringRef Name, std::vector<DiffOutput>& Output, AttributeDiff Attr) {
  Output.push_back(getSingleAttrDiff(Attr, Name));
}

and then simplify these calls to:

DiffAttribute("Install Name", ReturnedOutput, DiffScalarVal<StringRef, AD_Diff_Scalar_Str>(Order, Interface->getInstallName()));

Having the name of the attribute first makes it clear what you're diffing. I'd probably also rename ReturnedOutput to something shorter (Output) to reduce the length of those calls.

llvm/tools/llvm-tapi-diff/DiffEngine.h

65–66

Can these two be private? These members look like implementation details. Same in the other classes.

73

I see (this->Order == lhs) ? "< " : "> ") in several places. How about creating a helper that takes a InterfaceInputOrder and returns a StringRef to avoid this duplication?

133

Why are these functions implemented in the header?

172

The LLVM Coding Guide says that comments should be sentences, i.e. capitalized and with a period at the end.

223

You're passing the vector by value, so this will copy all its element for printing. Can this be a const ref?

[cishida]

llvm/tools/llvm-tapi-diff/DiffEngine.cpp

129

you don't need this conditional, the body of the for loop would never run if its empty

172

These don't need to be scoped

llvm/tools/llvm-tapi-diff/DiffEngine.h

57

Most, if not all, instances of this type are named Diff Diff.DiffVec is redundant and is also used as a variable name in other places.
What about Values?

82

nit: this-> calls are unecessarcy

102

Remove the typo at the end.

llvm/tools/llvm-tapi-diff/llvm-tapi-diff.cpp

2

sorry for the confusion on notation, I mean either tapi or tbd should be in the description.

[sgraenitz]

Hey, just a few notes on proper error handling.

llvm/tools/llvm-tapi-diff/llvm-tapi-diff.cpp

41

The idiomatic solution for this is ExitOnErr as described here:
https://llvm.org/docs/ProgrammersManual.html#using-exitonerror-to-simplify-tool-code

53

Could the result be returned directly here? Like this?

return createBinary(BufferOrErr.get()->getMemBufferRef());

74

I think with ExitOnError this could be:

std::unique_ptr<Binary> BinLHS = ExitOnErr(convertFileToBinary(InputFileNameLHS));

It is not uncommon to have it as a static global in a tool's driver cpp and use it directly all over the place. There is a number of good examples, e.g. llvm-link https://github.com/llvm/llvm-project/blob/81bc732816107f6aff4fd61980f7b03cc92332b5/llvm/tools/llvm-link/llvm-link.cpp#L296

[spowell]

fixed heading on DiffEngine.cpp; made helper to collect single scalar values; ReturnedOutput => Output; made implementation details private for class variables; made helper to set order indicator for print functions; moved functions that did not need to be in header; removed unneeded conditional; removed unneeded scope; DiffVec => Values, TargValues, DocValues; addValToDiffVec => addDiffToTargetSlice; removed unnecessary this-> calls; removed typo in comment; fixed heading on llvm-tapi-diff.cpp; fixed error handling in llvm-tapi-diff.cpp

[spowell]

removed import that was auto-added by text editor causing failure of tests.

[spowell]

fix error handling in llvm-tapi-diff.cpp

[JDevlieghere]

A few small nits and this should be ready to go.

llvm/tools/llvm-tapi-diff/DiffEngine.cpp

384–387

LHS? DocLHS?

458

This line got me thinking that it might be nice to make the raw_ostream an argument to printDifferences and do the same for compareFiles below. That aligns nicely with LLVM's library design, where the actual implementation (the DiffEngine) can remain unaware of where its output is being printed while centralize the fact that it's going to stdout in llvm-tapi-diff.cpp.

llvm/tools/llvm-tapi-diff/llvm-tapi-diff.cpp

30–33

This is generally lowercase.

[spowell]

Doc1 => DocLHS; Doc2 => DocRHS; made raw_ostream argument in compareFiles and printDifferences; lowercase argument prompts;

[JDevlieghere]

LGTM! Thanks for bearing with me :-)

[spowell]

formatting fixes

[ributzka]

LGTM

[thakis]

llvm/test/tools/llvm-tapi-diff/tapi-diff-matching-tbd.test

1

Shouldn't you add llvm-tapi-diff to llvm/test/CMakeLists.txt to make sure it gets built when you build check-llvm? And to the tools.extend( bit in llvm/test/lit.cfg.py?

[jyknight]

llvm/tools/llvm-tapi-diff/DiffEngine.h

57

std::vector<std::unique_ptr<AttributeDiff>>

Storing a subclass of AttributeDiff into a unique_ptr<AttributeDiff> is not OK, because AttributeDiff does not have a virtual destructor. So, this tool is invoking UB.

Just adding the virtual destructor to AttributeDiff is probably ok -- there doesn't seem to be any reason to avoid using virtual dispatch in this tool's class hierarchy, afaict.

[hubert.reinterpretcast]

The tests for this tool are observed to be failing on multiple big-endian platforms:
clang-s390x-linux: https://lab.llvm.org/buildbot/#/builders/94/builds/4116
clang-ppc64be-linux: https://lab.llvm.org/buildbot/#/builders/52/builds/8035

[cishida]

In D101835#2798031, @hubert.reinterpretcast wrote:

The tests for this tool are observed to be failing on multiple big-endian platforms:
clang-s390x-linux: https://lab.llvm.org/buildbot/#/builders/94/builds/4116
clang-ppc64be-linux: https://lab.llvm.org/buildbot/#/builders/52/builds/8035

Thanks for letting us know! @spowell from reading the lit output, it appears like the output order for the target slices isn't stable. I've reverted while we investigate and fix.

[danilaml]

I'm pretty sure this also causes a build failure on older, but supported versions of GCC due to this bug (https://gcc.gnu.org/bugzilla/show_bug.cgi?id=56480):

../tools/llvm-tapi-diff/DiffEngine.cpp:35:71: error: specialization of template<class T, llvm::DiffAttrKind U> void llvm::DiffScalarVal<T, U>::print(llvm::raw_ostream&, std::__cxx11::string) in different namespace [-fpermissive]
                                                     std::string Indent) {
                                                                       ^