Initial commit for the llvm-dsymutil tool.

[friss]

Summary

This initial version is only able to parse debug maps contained
in mach-o binaries.

Apart from the general review, I'm especially interested in comments
around the build system plumbing.

Nick, the very simple DebugMap object that is present is this version
is meant to be filled with information during the binary link and
then passed to a DwarfLinker object as a separate step. Does that
look like the best flow for you, or would you prefer something more
'incremental'?

The big question around this tool is how the in-tree testing will be
performed. This revision doesn't include a test, but there will be
one in the initial commit. I plan to commit very simple small binaries
for the and then to extend that binary pool when adding new features.
Eevn if I plan to reuse the binaries as much as I can for the various
development steps, I fear that this won't scale in the long run. I'm
open to ideas. Is there some policy about storing binaries in the LLVM
repo?

The current approach has several known shortcomings even for the simple
task it performs. For example, it doesn't handle static libraries, and
it keeps all the object files open at the same time. This initial commit
just provides a base for the incremental updates that will improve that
situation.

[kledzik]

tools/dsymutil/DebugMap.h

40–42

This could be replaced by a begin()/end() which return an iterator that dereferences to a "const DebugMapObject &", to be nicer for clients.

49

It looks like "Filename" is the same as ObjectFile getFileName().

The existing debug map tracks the source (ex: /path/foo.c) path as well as the object (ex: /path/foo.o) path. Does this DebugMap need both? or just the object path?

59–60

Are these the address in the .o file and address in the final binary? Can the names be clearer.

What is the rule for tentative definitions which don't have an address in the .o file? Maybe OrigAddress could be an llvm::Optional<>?

62

What is "Used"? When would it be false?

71

Can this be more specific (e.g. getSourcePath() or getObjectFilePath()).

[friss]

Thanks for the initial review! Some explanations and further questions inline:

tools/dsymutil/DebugMap.h

49

I think it only needs the object path, I haven't seen the source entries of the debug map being used except for detecting the end-of-scope of the current object file. The source file doesn't make much sense anyway as IIRC it is the parent of the object file scope and in an LTO scenario you end up with only one source file.

50

I'll add that in a followup commit

53–57

I'm not sure I'll use that actual type, but it seemed like some handy information to have (even if only for sanity checking that I'm not patch code addresses with data information). I actually use the Unknown type as an indicator that the Symbol hasn't been inserted in the map yet and I assert if a client tries to add 2 symbols with the same name in the same object file.

59–60

I agree that the names could be clearer.

What do you mean with "tentative definitions"? The OrigAddress gets filled with the value from the object file symbol table.

62

As you point out bellow, I add every symbol from the object file symbol table to the list of symbols. Then the ones that are present in the binary's debug map are marked Used.

I don't think libObject has a fast name -> symbol lookup, but I could have missed it. If such a feature exists, then I can populate the map with only symbols from the debug map and drop the used flag. An alternative would be to use a temporary StringMap with the whole object file symbol table in it, but this seemed a bit wasteful as I expect most of the object file symbol table to end up in the debug map anyway.

73–76

Of course adding a addSymbol(name, objectAddress, binaryAddress) is fine. The current API requires the OwningBinary to be created by the client, and that is bad. As I pointed out in the review message, we need to move away from that scheme because it might simply not be possible to hold all the objects in memory together. I think the final API will just use strings as object file identifiers (allowing the lib.a(objectfile) syntax for archives), and some smart OwningBinary caching will be performed in the DebugMap object or in the DwarfLInker itself.

81

I commented on that above. The map will be populated, but with unused symbols which won't be retained if they are not marked used by a relocateSymbol(). Or am I missing your point about the lld usecase?

[friss]

Simplified the DebugMap a lot. The way its used in the debug map
parser should be closer to what lld would like to do. i

Re: testing, I would prefer to include binaries because I like the
cross-platform testing even if the tool doesn't get used there. I
was going to include a test for the map parsing functionality and
some error handling in this review when I relized that ld64 would
embedded full absolute paths in the debug map. This will obviously
cause problems for testing in the testsuite. I'll defer that to
another update of this patch (I'll try to see if I can implement
and hack around --oso-prepend-path, and if not I'll switch to
compiling .ll files and testing on dwarwin systems only.).

[samsonov]

A few drive-by comments.

tools/Makefile

36

I'd prefer binary name (llvm-dsymutil) to match the directory name. I'm not aware of existing policy, though.

tools/dsymutil/DebugMap.cpp

25

Can you just use StringMap::insert() and use its return value to check if the key is already there?

32

why not outs()? (here and below). Or, better, you can probably take

llvm::raw_ostream &OS

as an input parameter.

56

see note about llvm::raw_ostream above.

tools/dsymutil/DebugMap.h

62

llvm::DebugMap is too generic, and I can imagine it can potentially conflict with some other class. Consider introducing a namespace for dsymutil-specific classes.

tools/dsymutil/DwarfLinker.cpp

15

s/Filename/OutputFilename (to match ctor declaration).

tools/dsymutil/MachODebugMapParser.cpp

19

Can you make use of ObjectFile::createMachOObjectFile() here?

53

This line is not needed, you already call resetParserState() above.

tools/dsymutil/MachODebugMapParser.h

53 ↗

(On Diff #16252)

newDebugMapObject() doesn't actually return anything, which is slightly confusing, especially when you call

return newDebugMapObject()

below.

[friss]

Thanks for taking the time to review that! I'll address most of your comments for the next update. Some comments inline:

tools/Makefile

36

This is in fact on purpose. The binary is currently called llvm-dsymutil so that it doesn't interfere with the system dsymutil. When the work will be complete enough to actually replace the system dsymutil, I want to rename the binary to just dsymutil so that it takes precedence when clang invokes dsymutil. I preferred to name the directory after the expected end-result rather than renaming the directory later.

tools/dsymutil/DebugMap.cpp

25

I like the simplicity of operator[] more. I'm not sure that using insert() would simplify anything especially as its return value would be used only in Assert builds.

32

AFAIK, dump() without argument is more canonical in LLVM, and it isn't usually even compiled in in non-debug builds.
However, you are right that in this case as I use it to emit user-visible diagnostics, this convention doesn't apply.

tools/dsymutil/DebugMap.h

62

I can rename that to DSYMDebugMap, although I find that this ties it a bit too much to Darwin. I can't be sure, but I'd expect the code using the DebugMap (as opposed to the code producing it) to be fairly generic. Not that it matters for the current unique useless though.

tools/dsymutil/MachODebugMapParser.cpp

19

I think the quantity of code would be the same because to use it I have to handle the MemoryBuffer creation myself. I'm not sure which one is preferable.

tools/dsymutil/MachODebugMapParser.h

53 ↗

(On Diff #16252)

Yeah the name dates back to a version where it would actually return the allocated object. I'll change that to switchToNewDebugMapObject(Name). Do you have an issue with the return voidReturningFunc(); idiom? I kinda like it when it allows to do early exits without having to brace the if body.

[samsonov]

tools/Makefile

36

Yep, makes sense.

tools/dsymutil/DebugMap.cpp

25

You can make addSymbol() return true iff the symbol wasn't there already, and assert (or print meaningful warning/error) in the caller.

32

LLVM classes often has dump() and print(llvm::raw_ostream), with former simply calling the latter.

tools/dsymutil/MachODebugMapParser.h

53 ↗

(On Diff #16252)

I'm neutral to this idiom, as long as function name doesn't imply that it's supposed to return the object :)

[friss]

• Added tests for the debug map parsing
• Added the -oso-prepend-path dsymutil option (used for tests)
• Addressed Alexey's feedback

If there are no further comments, I'll push that in a couple of days.

[friss]

ping!

I committed this briefly this morning considering that I could count your silence as approval, but Chandler told me not to do so. Sorry about that, I really didn't mean to force anything through.

My patch's short but intense in-tree live has produced one bot failure: http://bb.pgr.jp/builders/cmake-llvm-x86_64-linux/builds/19112
It seems the llvm-dsymutil tool hasn't been built at all there, thus I must be missing something in the build system hooks. I tried cmake and configure builds in Debug/Release before committing, so I'm not sure what I screwed up.

Thanks!

[samsonov]

In D6242#14, @friss wrote:

ping!

Sorry about that, will take a look at the revised patch shortly.

I committed this briefly this morning considering that I could count your silence as approval, but Chandler told me not to do so. Sorry about that, I really didn't mean to force anything through.

My patch's short but intense in-tree live has produced one bot failure: http://bb.pgr.jp/builders/cmake-llvm-x86_64-linux/builds/19112
It seems the llvm-dsymutil tool hasn't been built at all there, thus I must be missing something in the build system hooks. I tried cmake and configure builds in Debug/Release before committing, so I'm not sure what I screwed up.

You should probably add "llvm-dsymutil" to test/lit.cfg, next to all the other llvm-XXX tools listed there.

Thanks!

[samsonov]

tools/dsymutil/DebugMap.cpp

28

IIRC this might not work on MSVC, need to double-check.

38

Looks like SymbolMapping is lightweight enough. This code can be faster if you just use

std::vector<std::pair<StringRef, SymbolMapping>> Entries;

fill it with single scan over Symbols, and then std::sort it and print it.

tools/dsymutil/DwarfLinker.h

35 ↗

(On Diff #16904)

See the note for MachODebugMapParser class below - why not expose only a standalone function

bool linkDwarf(StringRef OutputFilename, const DebugMap &DM);

in a header?

tools/dsymutil/MachODebugMapParser.cpp

19

I think that using the more specific factory function would be more appropriate than calling createBinary(), and manually inspecting its output, making sure we return the same error code as Object library, etc.

53

Please use sys::path::append() here, so that you don't have to bother if oso-prepend-path should or should not end with a slash.

72

if (auto Error = ...)
  return Error;

161

Why do you initialize it lazily, instead of just calling loadMainBinarySymbols right after you have initialized MainOwningBinary?

182

Can/should we do smth. similar for loadCurrentObjectFileSymbols function?

tools/dsymutil/MachODebugMapParser.h

27 ↗

(On Diff #16904)

Do you actually plan to move this object to LLVM library in future? For now, I don't see why it's convenient or desirable to expose this object in a header. You can't really do anything with it - just construct it, and then call method parse() once.

What is more, you probably don't want to have the instance of MainOwningBinary object lying around in memory after parse() returned. Can you simply expose a function

ErrorOr<std::unique_ptr<DebugMap>> parseDebugMap(StringRef BinaryPath, StringRef PathPrefix = "");

and call the whole MachODebugMapParser an "mach-specific implementation detail", hidden in the .cpp file?

34 ↗

(On Diff #16904)

Is there a reason against making it a constructor argument (which can default to empty string)?

tools/dsymutil/dsymutil.cpp

20

Do you use it here?

32

Flag description could be helpful here.

66

If InputFile is stdin ("-"), this will be "-.dwarf"

[friss]

In D6242#15, @samsonov wrote:

In D6242#14, @friss wrote:

ping!

Sorry about that, will take a look at the revised patch shortly.

No worries, I wasn't really expecting anyone to do further review :-)

I committed this briefly this morning considering that I could count your silence as approval, but Chandler told me not to do so. Sorry about that, I really didn't mean to force anything through.

My patch's short but intense in-tree live has produced one bot failure: http://bb.pgr.jp/builders/cmake-llvm-x86_64-linux/builds/19112
It seems the llvm-dsymutil tool hasn't been built at all there, thus I must be missing something in the build system hooks. I tried cmake and configure builds in Debug/Release before committing, so I'm not sure what I screwed up.

You should probably add "llvm-dsymutil" to test/lit.cfg, next to all the other llvm-XXX tools listed there.

I don't think this will solve it. If I'm looking at the right place, then this seems to just ensure that we call the tool with its build directory added. Looking at the build log I have the feeling that llvm-dsymutil wasn't built at all. I spotted that I used the 'dsymutil' name in LLVMBuild.txt, maybe that's it. I'm just surprised that it isn't break in any of my builds.

Thanks a bunch!

tools/dsymutil/DebugMap.cpp

28

You remember that you made me introduce this use of insert? :-) It'd be much appreciated if you have a way to verify that.

38

Why do you think it would be faster? locality?

tools/dsymutil/DwarfLinker.h

35 ↗

(On Diff #16904)

That's actually a very good idea. In the code I developed since this was written, I struggled to keep the implementation details of DwarfLinker hidden, and that would make it trivial.

The choice is a bit more complicated than for MachODebugParser (which is really private) because we might want to expose the interface for lld's consumption at some point. And the free function approach might not be flexible enough depending on how much tunables I add in the linking phase.

I'll do it anyway, we can always revisit that later.

tools/dsymutil/MachODebugMapParser.cpp

53

will do

72

yep

161

Because it is not necessarily used. It is strictly needed only for common globals (this patch doesn't treat the commons differently from other globals, so the symbol table is read if you have any kind of global... which I guess you always have). Yeah, this optimization looks at least premature, if not totally useless. I'll drop it.

182

No because symbols from the object file are always useful. The debug map contains names associated with linked addresses (with the exception of common globals that need to be looked up in the binary), these linked addresses need to be correlated with the object file addresses that we always lookup in the object file's symbol table (and any defined symbol is of interest).

tools/dsymutil/MachODebugMapParser.h

27 ↗

(On Diff #16904)

As I said above, good idea. MachODebugParser should never get public anyway it is truly an implementation detail of dsymutil. When lld will want to use dsymutil's code, it will build its DebugMap objects itself anyway.

34 ↗

(On Diff #16904)

No real reason except that I prefer to use constructors for major properties and setters for optional/debug stuff. I can change that, it's not like the constructor will get confusing with one additional argument.

tools/dsymutil/dsymutil.cpp

20

llvm_shutdown_obj is defined there.

32

I have a description in my tree, must have missed merging that patch in the initial submission.

66

hehe, nice catch. I'm on the edge as to what to do with this: hardcoding the output file (a.out.dwarf?) or simply refusing to do that (and maybe allowing it later by adding a -o option).

[friss]

tools/dsymutil/MachODebugMapParser.cpp

19

The code I actually have in my tree moved to using createMachOObjectFile. I'll see how to change that in the initial version.

[samsonov]

In D6242#17, @friss wrote:

In D6242#15, @samsonov wrote:

In D6242#14, @friss wrote:

ping!

Sorry about that, will take a look at the revised patch shortly.

No worries, I wasn't really expecting anyone to do further review :-)

I committed this briefly this morning considering that I could count your silence as approval, but Chandler told me not to do so. Sorry about that, I really didn't mean to force anything through.

My patch's short but intense in-tree live has produced one bot failure: http://bb.pgr.jp/builders/cmake-llvm-x86_64-linux/builds/19112
It seems the llvm-dsymutil tool hasn't been built at all there, thus I must be missing something in the build system hooks. I tried cmake and configure builds in Debug/Release before committing, so I'm not sure what I screwed up.

You should probably add "llvm-dsymutil" to test/lit.cfg, next to all the other llvm-XXX tools listed there.

I don't think this will solve it. If I'm looking at the right place, then this seems to just ensure that we call the tool with its build directory added. Looking at the build log I have the feeling that llvm-dsymutil wasn't built at all. I spotted that I used the 'dsymutil' name in LLVMBuild.txt, maybe that's it. I'm just surprised that it isn't break in any of my builds.

Ah, you should also add llvm-dsymutil to LLVM_TEST_DEPENDS in test/CMakeLists.txt.

Thanks a bunch!

tools/dsymutil/DebugMap.cpp

38

Yes. But as you're comparing StringRef's, there are still indirection, so maybe it's not a big deal.

tools/dsymutil/dsymutil.cpp

66

Pipe the output to stdout? :) a.out.dwarf looks reasonable as well.

[friss]

In D6242#19, @samsonov wrote:

In D6242#17, @friss wrote:

In D6242#15, @samsonov wrote:

In D6242#14, @friss wrote:

ping!

Sorry about that, will take a look at the revised patch shortly.

No worries, I wasn't really expecting anyone to do further review :-)

I committed this briefly this morning considering that I could count your silence as approval, but Chandler told me not to do so. Sorry about that, I really didn't mean to force anything through.

My patch's short but intense in-tree live has produced one bot failure: http://bb.pgr.jp/builders/cmake-llvm-x86_64-linux/builds/19112
It seems the llvm-dsymutil tool hasn't been built at all there, thus I must be missing something in the build system hooks. I tried cmake and configure builds in Debug/Release before committing, so I'm not sure what I screwed up.

You should probably add "llvm-dsymutil" to test/lit.cfg, next to all the other llvm-XXX tools listed there.

I don't think this will solve it. If I'm looking at the right place, then this seems to just ensure that we call the tool with its build directory added. Looking at the build log I have the feeling that llvm-dsymutil wasn't built at all. I spotted that I used the 'dsymutil' name in LLVMBuild.txt, maybe that's it. I'm just surprised that it isn't break in any of my builds.

Ah, you should also add llvm-dsymutil to LLVM_TEST_DEPENDS in test/CMakeLists.txt.

That must be it!

tools/dsymutil/dsymutil.cpp

66

I considered that, of course, but a dsym bundle consists of a filesystem hierarchy and it is supposed to be the default output mode of dsymutil. I could fallback to a flat output file in that situation, though.

I'll just hardcode a.out for now.

[friss]

• Initial dsymutil tool commit.
• Add llvm-dsymutil to the test config files.
• Fix llvm-dsymtool name.
• Use a standard constructor for SymbolMapping.
• Change the default input file from '-' to a.out
• Use less indirections in DebugMapObject::print()
• Use ObjectFile::createMachOObjectFile instead of createBinary().
• Do not repeat the llvm::cl namespace over and over.
• Add a description to the oso-prepend-path option.
• Move the high-level interface from classes to free functions.
• Remove useless lazy loading.
• Better error handling style.
• Use sys::path::append()

The free functions in the llvm namespace look a bit strange. Do we have a policy about that? Should I put this into a dsymutil namespace (and thus maybe also the DebugMap class) ?

[friss]

• clang-format the initial submission.

[friss]

I uploaded a ew version there, but the mail must have been lost in the phab update mail black hole.

http://reviews.llvm.org/D6242

[samsonov]

LGTM. I have a handful of comments, feel free to submit after addressing them.

tools/dsymutil/DebugMap.cpp

39

Can you write range-based for loop here instead?

43

You don't need a comparator here - all keys in StringMap are different, and std::pair<> objects are compared lexicographically by default, which is what you need.

tools/dsymutil/DebugMap.h

22

prepend with LLVM_TOOLS_ ?

63

consider wrapping it in one more namespace (like llvm::dsymuitl) (probably not a big deal, though).

tools/dsymutil/DwarfLinker.cpp

16

This class does nothing for now. You can just delete it from this patch, and add it when it will actually do some work.

tools/dsymutil/MachODebugMapParser.cpp

217

Shouldn't this be a local variable defined inside for-loop with no default value? (as it will be initialized by Sym.getSection()) ?

tools/dsymutil/dsymutil.cpp

35

"names of object files"?

tools/dsymutil/dsymutil.h

17

LLVM_TOOLS_DSYMUTIL_DSYMUTIL_H

26

Shouldn't you #include DebugMap.h here to use DebugMap in unique_ptr?

[friss]

Thanks! I'll address your last comments before commit.

Couple of answers below:

tools/dsymutil/DebugMap.cpp

43

I didn't know pairs provided lexicographical relational operators, thanks for the tip!

tools/dsymutil/MachODebugMapParser.cpp

217

section_iterator doesn't provide a default constructor, and I didn't want to all Binary.section_end() for every iteration. The default value is there only to be able to construct the variable, its value will be overwritten every time it will actually be used.

tools/dsymutil/dsymutil.cpp

35

What about "Specify a directory to prepend to the paths of object files.". I find 'name' a bit too vague (is it only the basename?).

tools/dsymutil/dsymutil.h

26

Good point, I suppose that this didn't show up because every user of dsymutil.h is also a DebugMap.h user, and 'DebugMap' comes before 'dsymutil' in a sorted include list.

[friss]

tools/dsymutil/DebugMap.cpp

43

Unfortunately, the default comparators require the member types to be comparable. I don't see a need to put an operator< in SymbolMapping, thus I'll leave the lambda comparator there.

[friss]

Landed in r224134

test/CMakeLists.txt

set(LLVM_TEST_DEPENDS
           lli-child-target
           llvm-ar
           llvm-as
           llvm-bcanalyzer
           llvm-c-test
           llvm-cov
           llvm-diff
           llvm-dis
+          llvm-dsymutil
           llvm-dwarfdump
           llvm-extract
           llvm-link
           llvm-lto
           llvm-mc
           llvm-mcmarkup
           llvm-nm
           llvm-objdump

test/lit.cfg

for pattern in [r"\bbugpoint\b(?!-)",
                 r"\blli\b",
                 r"\bllvm-ar\b",
                 r"\bllvm-as\b",
                 r"\bllvm-bcanalyzer\b",
                 r"\bllvm-config\b",
                 r"\bllvm-cov\b",
                 r"\bllvm-diff\b",
                 r"\bllvm-dis\b",
+                r"\bllvm-dsymutil\b",
                 r"\bllvm-dwarfdump\b",
                 r"\bllvm-extract\b",
                 r"\bllvm-go\b",
                 r"\bllvm-link\b",
                 r"\bllvm-lto\b",
                 r"\bllvm-mc\b",
                 r"\bllvm-mcmarkup\b",
                 r"\bllvm-nm\b",

test/tools/dsymutil/Inputs/basic1.c

+/* This is the main file used to produce the basic* objects that are
+   used for the dsymutil tests.
+
+   These are compiled in a couple of different ways (always on a
+   Darwin system):
+   Basic compilation:
+      for FILE in basic1.c basic2.c basic3.c; do
+         clang -g -c $FILE -o ${FILE%.c}.macho.x86_64.o
+      done
+      clang basic1.macho.x86_64.o basic2.macho.x86_64.o basic3.macho.x86_64.o -o basic.macho.x86_64 -Wl,-dead_strip
+
+   LTO compilation:
+      for FILE in basic1.c basic2.c basic3.c; do
+         clang -g -c -flto $FILE -o ${FILE%.c}-lto.o
+      done
+      clang basic1-lto.o basic2-lto.o basic3-lto.o -o basic-lto.macho.x86_64 -Wl,-object_path_lto,$PWD/basic-lto.macho.x86_64.o -Wl,-dead_strip
+      rm basic1-lto.o basic2-lto.o basic3-lto.o
+
+*/
+
+int foo(int);
+
+int main(int argc, const char *argv[]) {
+  return foo(argc);
+}

test/tools/dsymutil/Inputs/basic2.c

+/* For compilation instructions see basic1.c. */
+
+static int baz = 42;
+static int private_int;
+extern volatile int val;
+int unused_data = 1;
+
+int bar(int);
+
+void unused1() {
+  bar(baz);
+}
+
+static int inc() {
+  return ++private_int;
+}
+
+__attribute__((noinline))
+int foo(int arg) {
+  return bar(arg+val) + inc() + baz++;
+}
+

test/tools/dsymutil/Inputs/basic3.c

+/* For compilation instructions see basic1.c. */
+
+volatile int val;
+
+extern int foo(int);
+
+int unused2() {
+  return foo(val);
+}
+
+static int inc() {
+  return ++val;
+}
+
+__attribute__((noinline))
+int bar(int arg) {
+  if (arg > 42)
+    return inc();
+  return foo(val + arg);
+}

test/tools/dsymutil/debug-map-parsing.test

+RUN: llvm-dsymutil -v -parse-only -oso-prepend-path=%p %p/Inputs/basic.macho.x86_64 | FileCheck %s
+RUN: llvm-dsymutil -v -parse-only -oso-prepend-path=%p %p/Inputs/basic-lto.macho.x86_64 | FileCheck %s --check-prefix=CHECK-LTO
+RUN: llvm-dsymutil -v -parse-only %p/Inputs/basic.macho.x86_64 2>&1 | FileCheck %s --check-prefix=NOT-FOUND
+RUN: not llvm-dsymutil -v -parse-only %p/Inputs/inexistant 2>&1 | FileCheck %s --check-prefix=NO-EXECUTABLE
+Check that We can parse the debug map of the basic executable.
+
+CHECK-NOT: error
+CHECK: DEBUG MAP:
+CHECK: /Inputs/basic1.macho.x86_64.o:
+CHECK:  0000000000000000 => 0000000100000ea0 _main
+CHECK: /Inputs/basic2.macho.x86_64.o:
+CHECK:  0000000000000310 => 0000000100001000 _baz
+CHECK:  0000000000000020 => 0000000100000ed0 _foo
+CHECK:  0000000000000070 => 0000000100000f20 _inc
+CHECK:  0000000000000560 => 0000000100001008 _private_int
+CHECK: /Inputs/basic3.macho.x86_64.o:
+CHECK:  0000000000000020 => 0000000100000f40 _bar
+CHECK:  0000000000000070 => 0000000100000f90 _inc
+CHECK:  0000000000000004 => 0000000100001004 _val
+CHECK: END DEBUG MAP
+
+
+Check that we can parse the debug-map of the basic-lto executable
+
+CHECK-LTO-NOT: error
+CHECK-LTO: DEBUG MAP:
+CHECK-LTO: /Inputs/basic-lto.macho.x86_64.o:
+CHECK-LTO:  0000000000000050 => 0000000100000f90 _bar
+CHECK-LTO:  0000000000000658 => 0000000100001000 _baz
+CHECK-LTO:  0000000000000010 => 0000000100000f50 _foo
+CHECK-LTO:  0000000000000000 => 0000000100000f40 _main
+CHECK-LTO:  00000000000008e8 => 0000000100001008 _private_int
+CHECK-LTO:  00000000000008ec => 0000000100001004 _val
+CHECK-LTO: END DEBUG MAP
+
+Check that we warn about missing object files (this presumes that the files aren't
+present in the machine's /Inputs/ folder, which should be a pretty safe bet).
+
+NOT-FOUND: cannot open{{.*}}"/Inputs/basic1.macho.x86_64.o": No such file
+NOT-FOUND: cannot open{{.*}}"/Inputs/basic2.macho.x86_64.o": No such file
+NOT-FOUND: cannot open{{.*}}"/Inputs/basic3.macho.x86_64.o": No such file
+NOT-FOUND: DEBUG MAP:
+NOT-FOUND-NEXT: END DEBUG MAP
+
+Check that we correctly error out on invalid executatble.
+
+NO-EXECUTABLE: cannot parse{{.*}}/inexistant": No such file
+NO-EXECUTABLE-NOT: DEBUG MAP

tools/CMakeLists.txt

 
 add_llvm_tool_subdirectory(llvm-extract)
 add_llvm_tool_subdirectory(llvm-diff)
 add_llvm_tool_subdirectory(macho-dump)
 add_llvm_tool_subdirectory(llvm-objdump)
 add_llvm_tool_subdirectory(llvm-readobj)
 add_llvm_tool_subdirectory(llvm-rtdyld)
 add_llvm_tool_subdirectory(llvm-dwarfdump)
+add_llvm_tool_subdirectory(dsymutil)
 add_llvm_tool_subdirectory(llvm-vtabledump)
 if( LLVM_USE_INTEL_JITEVENTS )
   add_llvm_tool_subdirectory(llvm-jitlistener)
 else()
   ignore_llvm_tool_subdirectory(llvm-jitlistener)
 endif( LLVM_USE_INTEL_JITEVENTS )
 
 add_llvm_tool_subdirectory(bugpoint)

tools/LLVMBuild.txt

 ;
 ; For more information on the LLVMBuild system, please see:
 ;
 ;   http://llvm.org/docs/LLVMBuild.html
 ;
 ;===------------------------------------------------------------------------===;
 
 [common]
-subdirectories = bugpoint llc lli llvm-ar llvm-as llvm-bcanalyzer llvm-cov llvm-diff llvm-dis llvm-dwarfdump llvm-extract llvm-jitlistener llvm-link llvm-lto llvm-mc llvm-nm llvm-objdump llvm-profdata llvm-rtdyld llvm-size macho-dump opt llvm-mcmarkup verify-uselistorder
+subdirectories = bugpoint llc lli llvm-ar llvm-as llvm-bcanalyzer llvm-cov llvm-diff llvm-dis llvm-dwarfdump llvm-extract llvm-jitlistener llvm-link llvm-lto llvm-mc llvm-nm llvm-objdump llvm-profdata llvm-rtdyld llvm-size macho-dump opt llvm-mcmarkup verify-uselistorder dsymutil
 
 [component_0]
 type = Group
 name = Tools
 parent = $ROOT

tools/Makefile

 # large and three small executables. This is done to minimize memory load
 # in parallel builds.  Please retain this ordering.
 DIRS := llvm-config
 PARALLEL_DIRS := opt llvm-as llvm-dis llc llvm-ar llvm-nm llvm-link \
                  lli llvm-extract llvm-mc bugpoint llvm-bcanalyzer llvm-diff \
                  macho-dump llvm-objdump llvm-readobj llvm-rtdyld \
                  llvm-dwarfdump llvm-cov llvm-size llvm-stress llvm-mcmarkup \
                  llvm-profdata llvm-symbolizer obj2yaml yaml2obj llvm-c-test \
-                 llvm-vtabledump verify-uselistorder
+                 llvm-vtabledump verify-uselistorder dsymutil
 
 # If Intel JIT Events support is configured, build an extra tool to test it.
 ifeq ($(USE_INTEL_JITEVENTS), 1)
   PARALLEL_DIRS += llvm-jitlistener
 endif
 
 # Let users override the set of tools to build from the command line.
 ifdef ONLY_TOOLS

tools/dsymutil/CMakeLists.txt

+set(LLVM_LINK_COMPONENTS
+  Object
+  Support
+  )
+
+add_llvm_tool(llvm-dsymutil
+  dsymutil.cpp
+  DebugMap.cpp
+  DwarfLinker.cpp
+  MachODebugMapParser.cpp
+  )
+

tools/dsymutil/DebugMap.h

+//===- tools/dsymutil/DebugMap.h - Generic debug map representation -------===//
+//
+//                             The LLVM Linker
+//
+// This file is distributed under the University of Illinois Open Source
+// License. See LICENSE.TXT for details.
+//
+//===----------------------------------------------------------------------===//
+///
+/// \file
+///
+/// This file contains the class declaration of the DebugMap
+/// entity. A DebugMap lists all the object files linked together to
+/// produce an executable along with the linked address of all the
+/// atoms used in these object files.
+/// The DebugMap is an input to the DwarfLinker class that will
+/// extract the Dwarf debug information from the referenced object
+/// files and link their usefull debug info together.
+///
+//===----------------------------------------------------------------------===//
+#ifndef DSYMUTIL_DEBUGMAP_H
+#define DSYMUTIL_DEBUGMAP_H
+
+#include "llvm/ADT/StringMap.h"
+#include "llvm/Object/ObjectFile.h"
+#include "llvm/Support/ErrorOr.h"
+#include "llvm/Support/Format.h"
+#include "llvm/ADT/iterator_range.h"
+#include <vector>
+
+namespace llvm {
+
+class raw_ostream;
+
+class DebugMapObject;
+
+/// \brief The DebugMap object stores the list of object files to
+/// query for debug information along with the mapping between the
+/// symbols' addresses in the object file to their linked address in
+/// the linked binary.
+///
+/// A DebugMap producer could look like this:
+/// DebugMap *DM = new DebugMap();
+/// for (const auto &Obj: LinkedObjects) {
+///     DebugMapObject &DMO = DM->addDebugMapObject(Obj.getPath());
+///     for (const auto &Sym: Obj.getLinkedSymbols())
+///         DMO.addSymbol(Sym.getName(), Sym.getObjectFileAddress(),
+///                       Sym.getBinaryAddress());
+/// }
+///
+/// A DebugMap consumer can then use the map to link the debug
+/// information. For example something along the lines of:
+/// for (const auto &DMO: DM->objects()) {
+///     auto Obj = createBinary(DMO.getObjectFilename());
+///     for (auto &DIE: Obj.getDwarfDIEs()) {
+///         if (SymbolMapping *Sym = DMO.lookup(DIE.getName()))
+///             DIE.relocate(Sym->ObjectAddress, Sym->BinaryAddress);
+///         else
+///             DIE.discardSubtree();
+///     }
+/// }
+class DebugMap
+{
+  typedef std::vector<std::unique_ptr<DebugMapObject>> ObjectContainer;
+  ObjectContainer Objects;
+
+public:
+  typedef ObjectContainer::const_iterator const_iterator;
+
+  iterator_range<const_iterator> objects() const {
+    return make_range(begin(), end());
+  }
+
+  const_iterator begin() const {
+    return Objects.begin();
+  }
+
+  const_iterator end() const {
+    return Objects.end();
+  }
+
+  /// This function adds an DebugMapObject to the list owned by this
+  /// debug map.
+  DebugMapObject& addDebugMapObject(StringRef ObjectFilePath);
+
+  void print(raw_ostream& OS) const;
+
+#ifndef NDEBUG
+  void dump() const;
+#endif
+};
+
+/// \brief The DebugMapObject represents one object file described by
+/// the DebugMap. It contains a list of mappings between addresses in
+/// the object file and in the linked binary for all the linked atoms
+/// in this object file.
+class DebugMapObject {
+public:
+  struct SymbolMapping {
+    uint64_t ObjectAddress;
+    uint64_t BinaryAddress;
+    SymbolMapping(uint64_t ObjectAddress, uint64_t BinaryAddress)
+    : ObjectAddress(ObjectAddress), BinaryAddress(BinaryAddress) {}
+  };
+
+  /// \brief Adds a symbol mapping to this DebugMapObject.
+  /// \returns false if the symbol was already registered. The request
+  /// is discarded in this case.
+  bool addSymbol(llvm::StringRef SymName, uint64_t ObjectAddress,
+                 uint64_t LinkedAddress);
+
+  /// \bried Lookup a symbol mapping.
+  /// \returns null if the symbol isn't found.
+  const SymbolMapping *lookupSymbol(StringRef SymbolName) const;
+
+  llvm::StringRef getObjectFilename() const { return Filename; }
+
+  void print(raw_ostream& OS) const;
+#ifndef NDEBUG
+  void dump() const;
+#endif
+private:
+  friend class DebugMap;
+  /// DebugMapObjects can only be constructed by the owning DebugMap.
+  DebugMapObject(StringRef ObjectFilename);
+
+  std::string Filename;
+  StringMap<SymbolMapping> Symbols;
+};
+
+}
+
+#endif // DSYMUTIL_DEBUGMAP_H

tools/dsymutil/DebugMap.cpp

+//===- tools/dsymutil/DebugMap.cpp - Generic debug map representation -----===//
+//
+//                             The LLVM Linker
+//
+// This file is distributed under the University of Illinois Open Source
+// License. See LICENSE.TXT for details.
+//
+//===----------------------------------------------------------------------===//
+#include "DebugMap.h"
+
+#include "llvm/ADT/STLExtras.h"
+#include "llvm/Support/DataTypes.h"
+#include "llvm/Support/Format.h"
+#include "llvm/Support/raw_ostream.h"
+#include <algorithm>
+
+namespace llvm {
+
+using namespace llvm::object;
+
+DebugMapObject::DebugMapObject(StringRef ObjectFilename)
+  : Filename(ObjectFilename) {}
+
+bool DebugMapObject::addSymbol(StringRef Name, uint64_t ObjectAddress,
+                               uint64_t LinkedAddress) {
+  auto InsertResult = Symbols.insert(std::make_pair(Name,
+                                                    SymbolMapping(ObjectAddress,
+                                                                  LinkedAddress)));
+  return InsertResult.second;
+}
+
+void DebugMapObject::print(raw_ostream& OS) const {
+  OS << getObjectFilename() << ":\n";
+  // Sort the symbols in alphabetical order, like llvm-nm (and to get
+  // deterministic output for testing).
+  typedef std::pair<StringRef, SymbolMapping> Entry;
+  std::vector<Entry> Entries;
+  Entries.reserve(Symbols.getNumItems());
+  for (auto SymIt = Symbols.begin(), End = Symbols.end(); SymIt != End; ++SymIt)
+    Entries.push_back(std::make_pair(SymIt->getKey(), SymIt->getValue()));
+  std::sort(Entries.begin(), Entries.end(),
+            [] (const Entry &LHS, const Entry &RHS) {
+              return LHS.first < RHS.first;
+            });
+  for (const auto &Sym: Entries) {
+    OS << format("\t%016" PRIx64 " => %016" PRIx64 "\t%s\n",
+                 Sym.second.ObjectAddress, Sym.second.BinaryAddress,
+                 Sym.first.data());
+  }
+  OS << '\n';
+}
+
+#ifndef NDEBUG
+void DebugMapObject::dump() const {
+  print(errs());
+}
+#endif
+
+DebugMapObject& DebugMap::addDebugMapObject(StringRef ObjectFilePath) {
+  Objects.emplace_back(new DebugMapObject(ObjectFilePath));
+  return *Objects.back();
+}
+
+const DebugMapObject::SymbolMapping *
+DebugMapObject::lookupSymbol(StringRef SymbolName) const {
+  StringMap<SymbolMapping>::const_iterator Sym = Symbols.find(SymbolName);
+  if (Sym == Symbols.end())
+    return nullptr;
+  return &Sym->getValue();
+}
+
+void DebugMap::print(raw_ostream& OS) const {
+  OS << "DEBUG MAP:   object addr =>  executable addr\tsymbol name\n";
+  for (const auto &Obj: objects())
+    Obj->print(OS);
+  OS << "END DEBUG MAP\n";
+}
+
+#ifndef NDEBUG
+void DebugMap::dump() const {
+  print(errs());
+}
+#endif
+}

tools/dsymutil/DwarfLinker.cpp

+//===- tools/dsymutil/DwarfLinker.cpp - Dwarf debug info linker -----------===//
+//
+//                             The LLVM Linker
+//
+// This file is distributed under the University of Illinois Open Source
+// License. See LICENSE.TXT for details.
+//
+//===----------------------------------------------------------------------===//
+#include "DebugMap.h"
+#include "dsymutil.h"
+
+namespace {
+using namespace llvm;
+
+class DwarfLinker {
+  std::string OutputFilename;
+public:
+  DwarfLinker(StringRef OutputFilename);
+
+  /// \brief Link the passed debug map into the ouptut file.
+  /// \returns false if the link encountered a fatal error.
+  bool link(const DebugMap&);
+};
+
+
+DwarfLinker::DwarfLinker(StringRef OutputFilename)
+  : OutputFilename(OutputFilename)
+{}
+
+bool DwarfLinker::link(const DebugMap &Map) {
+  return true;
+}
+
+}
+
+namespace llvm {
+
+bool linkDwarf(StringRef OutputFilename, const DebugMap &DM) {
+  DwarfLinker Linker(OutputFilename);
+  return Linker.link(DM);
+}
+
+}

tools/dsymutil/LLVMBuild.txt

-;===- ./tools/LLVMBuild.txt ------------------------------------*- Conf -*--===;
+;===- ./tools/dsymutil/LLVMBuild.txt ---------------------*- Conf -*--===;
 ;
 ;                     The LLVM Compiler Infrastructure
 ;
 ; This file is distributed under the University of Illinois Open Source
 ; License. See LICENSE.TXT for details.
 ;
 ;===------------------------------------------------------------------------===;
 ;
 ; This is an LLVMBuild description file for the components in this subdirectory.
 ;
 ; For more information on the LLVMBuild system, please see:
 ;
 ;   http://llvm.org/docs/LLVMBuild.html
 ;
 ;===------------------------------------------------------------------------===;
 
-[common]
-subdirectories = bugpoint llc lli llvm-ar llvm-as llvm-bcanalyzer llvm-cov llvm-diff llvm-dis llvm-dwarfdump llvm-extract llvm-jitlistener llvm-link llvm-lto llvm-mc llvm-nm llvm-objdump llvm-profdata llvm-rtdyld llvm-size macho-dump opt llvm-mcmarkup verify-uselistorder
-
 [component_0]
-type = Group
-name = Tools
-parent = $ROOT
+type = Tool
+name = llvm-dsymutil
+parent = Tools
+required_libraries = Object Support

tools/dsymutil/MachODebugMapParser.cpp

+//===- tools/dsymutil/MachODebugMapParser.cpp - Parse STABS debug maps ----===//
+//
+//                             The LLVM Linker
+//
+// This file is distributed under the University of Illinois Open Source
+// License. See LICENSE.TXT for details.
+//
+//===----------------------------------------------------------------------===//
+
+#include "DebugMap.h"
+#include "dsymutil.h"
+#include "llvm/Object/MachO.h"
+#include "llvm/Support/Path.h"
+#include "llvm/Support/raw_ostream.h"
+
+namespace {
+using namespace llvm;
+using namespace llvm::object;
+
+class MachODebugMapParser {
+public:
+  MachODebugMapParser(StringRef BinaryPath, StringRef PathPrefix = "")
+    : BinaryPath(BinaryPath), PathPrefix(PathPrefix) {}
+
+  /// \brief Parses and returns the DebugMap of the input binary.
+  /// \returns an error in case the provided BinaryPath doesn't exist
+  /// or isn't of a supported type.
+  ErrorOr<std::unique_ptr<DebugMap>> parse();
+
+private:
+  std::string BinaryPath;
+  std::string PathPrefix;
+
+  /// OwningBinary constructed from the BinaryPath.
+  object::OwningBinary<object::MachOObjectFile> MainOwningBinary;
+  /// Map of the binary symbol addresses.
+  StringMap<uint64_t> MainBinarySymbolAddresses;
+  /// The constructed DebugMap.
+  std::unique_ptr<DebugMap> Result;
+
+  /// Handle to the currently processed object file.
+  object::OwningBinary<object::MachOObjectFile> CurrentObjectFile;
+  /// Map of the currently processed object file symbol addresses.
+  StringMap<uint64_t> CurrentObjectAddresses;
+  /// Element of the debug map corresponfing to the current object file.
+  DebugMapObject *CurrentDebugMapObject;
+
+  void switchToNewDebugMapObject(StringRef Filename);
+  void resetParserState();
+  uint64_t getMainBinarySymbolAddress(StringRef Name);
+  void loadMainBinarySymbols();
+  void loadCurrentObjectFileSymbols();
+  void handleStabSymbolTableEntry(uint32_t StringIndex, uint8_t Type,
+                                  uint8_t SectionIndex, uint16_t Flags,
+                                  uint64_t Value);
+
+  template <typename STEType> void handleStabDebugMapEntry(const STEType &STE) {
+    handleStabSymbolTableEntry(STE.n_strx, STE.n_type, STE.n_sect, STE.n_desc,
+                               STE.n_value);
+  }
+};
+
+static void Warning(const Twine &Msg) { errs() << "warning: " + Msg + "\n"; }
+
+}
+
+static ErrorOr<OwningBinary<MachOObjectFile>> createMachOBinary(StringRef File) {
+  auto MemBufOrErr = MemoryBuffer::getFile(File);
+  if (auto Error = MemBufOrErr.getError())
+    return Error;
+
+  MemoryBufferRef BufRef = (*MemBufOrErr)->getMemBufferRef();
+  auto MachOOrErr = ObjectFile::createMachOObjectFile(BufRef);
+  if (auto Error = MachOOrErr.getError())
+    return Error;
+
+  return OwningBinary<MachOObjectFile>(std::move(*MachOOrErr),
+                                       std::move(*MemBufOrErr));
+}
+
+/// Reset the parser state coresponding to the current object
+/// file. This is to be called after an object file is finished
+/// processing.
+void MachODebugMapParser::resetParserState() {
+  CurrentObjectFile = OwningBinary<object::MachOObjectFile>();
+  CurrentObjectAddresses.clear();
+  CurrentDebugMapObject = nullptr;
+}
+
+/// Create a new DebugMapObject. This function resets the state of the
+/// parser that was referring to the last object file and sets
+/// everything up to add symbols to the new one.
+void MachODebugMapParser::switchToNewDebugMapObject(StringRef Filename) {
+  resetParserState();
+
+  SmallString<80> Path(PathPrefix);
+  sys::path::append(Path, Filename);
+
+  auto MachOOrError = createMachOBinary(Path);
+  if (auto Error = MachOOrError.getError()) {
+    Warning(Twine("cannot open debug object \"") + Path.str() + "\": "
+            + Error.message() + "\n");
+    return;
+  }
+
+  CurrentObjectFile = std::move(*MachOOrError);
+  loadCurrentObjectFileSymbols();
+  CurrentDebugMapObject = &Result->addDebugMapObject(Path);
+}
+
+/// This main parsing routine tries to open the main binary and if
+/// successful iterates over the STAB entries. The real parsing is
+/// done in handleStabSymbolTableEntry.
+ErrorOr<std::unique_ptr<DebugMap>> MachODebugMapParser::parse() {
+  auto MainBinaryOrError = createMachOBinary(BinaryPath);
+  if (auto Error = MainBinaryOrError.getError())
+    return Error;
+
+  MainOwningBinary = std::move(*MainBinaryOrError);
+  loadMainBinarySymbols();
+  Result = make_unique<DebugMap>();
+  const auto &MainBinary = *MainOwningBinary.getBinary();
+  for (const SymbolRef &Symbol : MainBinary.symbols()) {
+    const DataRefImpl &DRI = Symbol.getRawDataRefImpl();
+    if (MainBinary.is64Bit())
+      handleStabDebugMapEntry(MainBinary.getSymbol64TableEntry(DRI));
+    else
+      handleStabDebugMapEntry(MainBinary.getSymbolTableEntry(DRI));
+  }
+
+  resetParserState();
+  return std::move(Result);
+}
+
+/// Interpret the STAB entries to fill the DebugMap.
+void MachODebugMapParser::handleStabSymbolTableEntry(uint32_t StringIndex,
+                                                     uint8_t Type,
+                                                     uint8_t SectionIndex,
+                                                     uint16_t Flags,
+                                                     uint64_t Value) {
+  if (!(Type & MachO::N_STAB))
+    return;
+
+  const MachOObjectFile &MachOBinary = *MainOwningBinary.getBinary();
+  const char *Name = &MachOBinary.getStringTableData().data()[StringIndex];
+
+  // An N_OSO entry represents the start of a new object file description.
+  if (Type == MachO::N_OSO)
+    return switchToNewDebugMapObject(Name);
+
+  // If the last N_OSO object file wasn't found,
+  // CurrentDebugMapObject will be null. Do not update anything
+  // until we find the next valid N_OSO entry.
+  if (!CurrentDebugMapObject)
+    return;
+
+  switch (Type) {
+  case MachO::N_GSYM:
+    // This is a global variable. We need to query the main binary
+    // symbol table to find its address as it might not be in the
+    // debug map (for common symbols).
+    Value = getMainBinarySymbolAddress(Name);
+    if (Value == UnknownAddressOrSize)
+      return;
+    break;
+  case MachO::N_FUN:
+    // Functions are scopes in STABS. They have an end marker that we
+    // need to ignore.
+    if (Name[0] == '\0')
+      return;
+    break;
+  case MachO::N_STSYM:
+    break;
+  default:
+    return;
+  }
+
+  auto ObjectSymIt = CurrentObjectAddresses.find(Name);
+  if (ObjectSymIt == CurrentObjectAddresses.end())
+    return Warning("could not find object file symbol for symbol " +
+                   Twine(Name));
+  if (!CurrentDebugMapObject->addSymbol(Name, ObjectSymIt->getValue(), Value))
+    return Warning(Twine("failed to insert symbol '") + Name + "' in the debug map.");
+}
+
+/// Load the current object file symbols into CurrentObjectAddresses.
+void MachODebugMapParser::loadCurrentObjectFileSymbols() {
+  CurrentObjectAddresses.clear();
+  const auto &Binary = *CurrentObjectFile.getBinary();
+
+  for (auto Sym : Binary.symbols()) {
+    StringRef Name;
+    uint64_t Addr;
+    if (Sym.getAddress(Addr) || Addr == UnknownAddressOrSize ||
+        Sym.getName(Name))
+      continue;
+    CurrentObjectAddresses[Name] = Addr;
+  }
+}
+
+/// Lookup a symbol address in the main binary symbol table. The
+/// parser only needs to query common symbols, thus not every symbol's
+/// address is available through this function.
+uint64_t MachODebugMapParser::getMainBinarySymbolAddress(StringRef Name) {
+  auto Sym = MainBinarySymbolAddresses.find(Name);
+  if (Sym == MainBinarySymbolAddresses.end())
+    return UnknownAddressOrSize;
+  return Sym->second;
+}
+
+/// Load the interesting main binary symbols' addresses into
+/// MainBinarySymbolAddresses.
+void MachODebugMapParser::loadMainBinarySymbols() {
+  const MachOObjectFile &Binary = *MainOwningBinary.getBinary();
+  section_iterator Section = Binary.section_end();
+  for (const auto &Sym : Binary.symbols()) {
+    SymbolRef::Type Type;
+    // Skip undefined and STAB entries.
+    if (Sym.getType(Type) || (Type & SymbolRef::ST_Debug) ||
+        (Type & SymbolRef::ST_Unknown))
+      continue;
+    StringRef Name;
+    uint64_t Addr;
+    // The only symbols of interest are the global variables. These
+    // are the only ones that need to be queried because the address
+    // of common data won't be described in the debug map. All other
+    // addresses should be fetched for the debug map.
+    if (Sym.getAddress(Addr) || Addr == UnknownAddressOrSize ||
+        !(Sym.getFlags() & SymbolRef::SF_Global) ||
+        Sym.getSection(Section) || Section->isText() || Sym.getName(Name) ||
+        Name.size() == 0 || Name[0] == '\0')
+      continue;
+    MainBinarySymbolAddresses[Name] = Addr;
+  }
+}
+
+namespace llvm {
+
+llvm::ErrorOr<std::unique_ptr<llvm::DebugMap>>
+parseDebugMap(StringRef InputFile, StringRef PrependPath) {
+  MachODebugMapParser Parser(InputFile, PrependPath);
+  return Parser.parse();
+}
+
+}

tools/dsymutil/Makefile

+##===- tools/dsymutil/Makefile -----------------------------*- Makefile -*-===##
+#
+#                     The LLVM Compiler Infrastructure
+#
+# This file is distributed under the University of Illinois Open Source
+# License. See LICENSE.TXT for details.
+#
+##===----------------------------------------------------------------------===##
+
+LEVEL := ../..
+TOOLNAME := llvm-dsymutil
+LINK_COMPONENTS := Object Support
+
+# This tool has no plugins, optimize startup time.
+TOOL_NO_EXPORTS := 1
+
+include $(LEVEL)/Makefile.common

tools/dsymutil/dsymutil.h

+//===- tools/dsymutil/dsymutil.h - dsymutil high-level functionality ------===//
+//
+//                             The LLVM Linker
+//
+// This file is distributed under the University of Illinois Open Source
+// License. See LICENSE.TXT for details.
+//
+//===----------------------------------------------------------------------===//
+///
+/// \file
+///
+/// This file contains the class declaration for the code that parses STABS
+/// debug maps that are embedded in the binaries symbol tables.
+///
+//===----------------------------------------------------------------------===//
+#ifndef DSYMUTIL_DSYMUTIL_H
+#define DSYMUTIL_DSYMUTIL_H
+
+#include "llvm/ADT/StringRef.h"
+#include "llvm/Support/ErrorOr.h"
+#include <memory>
+
+namespace llvm {
+
+class DebugMap;
+
+/// \brief Extract the DebugMap from the given file.
+/// The file has to be a MachO object file.
+llvm::ErrorOr<std::unique_ptr<llvm::DebugMap>>
+parseDebugMap(StringRef InputFile, StringRef PrependPath = "");
+
+/// \brief Link the Dwarf debuginfo as directed by the passed DebugMap
+/// \p DM into a DwarfFile named \p OutputFilename.
+/// \returns false if the link failed.
+bool linkDwarf(StringRef OutputFilename, const DebugMap &DM);
+
+}
+
+#endif // DSYMUTIL_DSYMUTIL_H

tools/dsymutil/dsymutil.cpp

+//===-- dsymutil.cpp - Debug info dumping utility for llvm ----------------===//
+//
+//                     The LLVM Compiler Infrastructure
+//
+// This file is distributed under the University of Illinois Open Source
+// License. See LICENSE.TXT for details.
+//
+//===----------------------------------------------------------------------===//
+//
+// This program is a utility that aims to be a dropin replacement for
+// Darwin's dsymutil.
+//
+//===----------------------------------------------------------------------===//
+
+#include "DebugMap.h"
+#include "dsymutil.h"
+
+#include "llvm/Support/ManagedStatic.h"
+#include "llvm/Support/PrettyStackTrace.h"
+#include "llvm/Support/Options.h"
+#include "llvm/Support/raw_ostream.h"
+#include "llvm/Support/Signals.h"
+
+#include <string>
+
+namespace {
+using namespace llvm::cl;
+
+static opt<std::string> InputFile(Positional,
+                                  desc("<input file>"),
+                                  init("a.out"));
+
+static opt<std::string> OsoPrependPath("oso-prepend-path",
+                                       desc("Specify a path to prepend to the "
+                                            "object file's filenames."),
+                                       value_desc("path"));
+
+static opt<bool> Verbose("v", desc("Verbosity level"), init(false));
+
+static opt<bool> ParseOnly("parse-only",
+                           desc("Only parse the debug map, do not actaully link "
+                                "the DWARF."),
+                           init(false));
+}
+
+int main(int argc, char **argv) {
+  llvm::sys::PrintStackTraceOnErrorSignal();
+  llvm::PrettyStackTraceProgram StackPrinter(argc, argv);
+  llvm::llvm_shutdown_obj Shutdown;
+
+  llvm::cl::ParseCommandLineOptions(argc, argv, "llvm dsymutil\n");
+  auto DebugMapPtrOrErr = llvm::parseDebugMap(InputFile, OsoPrependPath);
+
+  if (auto EC = DebugMapPtrOrErr.getError()) {
+    llvm::errs() << "error: cannot parse the debug map for \"" << InputFile <<
+      "\": " << EC.message() << '\n';
+    return 1;
+  }
+
+  if (Verbose)
+    (*DebugMapPtrOrErr)->print(llvm::outs());
+
+  if (ParseOnly)
+    return 0;
+
+  std::string OutputBasename(InputFile);
+  if (OutputBasename == "-")
+    OutputBasename = "a.out";
+
+  return !llvm::linkDwarf(OutputBasename + ".dwarf", **DebugMapPtrOrErr);
+}