[lldb] Add image dump pcm-info command

[kastiglione]

Summary

Add pcm-info to the target module dump subcommands.

This dump command shows information about clang .pcm files. This command
effectively runs clang -module-file-info and produces identical output.

The .pcm file format is tightly coupled to the clang version. The clang
embedded in lldb is not guaranteed to match the version of the clang executable
available on the local system.

There have been times when I've needed to view the details about a .pcm file
produced by lldb's embedded clang, but because the clang executable was a
slightly different version, the -module-file-info invocation failed. With
this command, users can inspect .pcm files generated by lldb too.

[kastiglione]

add @skipUnlessDarwin

[kastiglione]

remove commented-out code in test

[mib]

LGTM with a comment

lldb/test/API/commands/target/dump-pcm-info/TestDumpPCMInfo.py

38

Left over ?

[kastiglione]

lldb/test/API/commands/target/dump-pcm-info/TestDumpPCMInfo.py

38

yep thanks!

[JDevlieghere]

[bikeshedding] pcm-info seems a little odd. Do we have other command that end with -info? target modules dump already sounds like you're about to dump some kind of "info". What about just pcm? [/bikeshedding]

[kastiglione]

@JDevlieghere I had it as dump pcm at first, but switched it to pcm-info for two reasons

1. it doesn't dump the whole pcm, the actual ast itself is not dumped
2. to match the clang flag -module-file-info

I agree that pcm is better, but I was worried it would be misunderstood as dumping more than it actually does.

I think -info here is more like -metadata but shorter.

One option is to name it back to pcm, and update the help description to be more descriptive.

[kastiglione]

added error handling

[kastiglione]

simplify error handling by checking for .pcm extension

clang/include/clang/Frontend/FrontendActions.h

 public:
   ~SyntaxOnlyAction() override;
   bool hasCodeCompletionSupport() const override { return true; }
 };
 
 /// Dump information about the given module file, to be used for
 /// basic debugging and discovery.
 class DumpModuleInfoAction : public ASTFrontendAction {
+public:
+  // Allow other tools (ex lldb) to direct output for their use.
+  llvm::raw_ostream *OutputStream = nullptr;
+
 protected:
   std::unique_ptr<ASTConsumer> CreateASTConsumer(CompilerInstance &CI,
                                                  StringRef InFile) override;
   bool BeginInvocation(CompilerInstance &CI) override;
   void ExecuteAction() override;
 
 public:
   bool hasPCHSupport() const override { return false; }

clang/lib/Frontend/FrontendActions.cpp

void DumpModuleInfoAction::ExecuteAction() {
   assert(isCurrentFileAST() && "dumping non-AST?");
   // Set up the output file.
   std::unique_ptr<llvm::raw_fd_ostream> OutFile;
   StringRef OutputFileName = getCompilerInstance().getFrontendOpts().OutputFile;
   if (!OutputFileName.empty() && OutputFileName != "-") {
     std::error_code EC;
     OutFile.reset(new llvm::raw_fd_ostream(OutputFileName.str(), EC,
                                            llvm::sys::fs::OF_TextWithCRLF));
+    OutputStream = OutFile.get();
   }
-  llvm::raw_ostream &Out = OutFile.get()? *OutFile.get() : llvm::outs();
+  llvm::raw_ostream &Out = OutputStream ? *OutputStream : llvm::outs();
 
   Out << "Information for module file '" << getCurrentFile() << "':\n";
   auto &FileMgr = getCompilerInstance().getFileManager();
   auto Buffer = FileMgr.getBufferForFile(getCurrentFile());
   StringRef Magic = (*Buffer)->getMemBufferRef().getBuffer();
   bool IsRaw = (Magic.size() >= 4 && Magic[0] == 'C' && Magic[1] == 'P' &&
                 Magic[2] == 'C' && Magic[3] == 'H');
   Out << "  Module format: " << (IsRaw ? "raw" : "obj") << "\n";

lldb/source/Commands/CommandObjectTarget.cpp

 #include "lldb/Target/ABI.h"
 #include "lldb/Target/Process.h"
 #include "lldb/Target/RegisterContext.h"
 #include "lldb/Target/SectionLoadList.h"
 #include "lldb/Target/StackFrame.h"
 #include "lldb/Target/Thread.h"
 #include "lldb/Target/ThreadSpec.h"
 #include "lldb/Utility/Args.h"
+#include "lldb/Utility/ConstString.h"
+#include "lldb/Utility/FileSpec.h"
 #include "lldb/Utility/LLDBLog.h"
 #include "lldb/Utility/State.h"
 #include "lldb/Utility/Timer.h"
 #include "lldb/lldb-enumerations.h"
 #include "lldb/lldb-private-enumerations.h"
 
+#include "clang/CodeGen/ObjectFilePCHContainerOperations.h"
+#include "clang/Frontend/CompilerInstance.h"
+#include "clang/Frontend/CompilerInvocation.h"
+#include "clang/Frontend/FrontendActions.h"
 #include "llvm/ADT/ScopeExit.h"
 #include "llvm/Support/FileSystem.h"
 #include "llvm/Support/FormatAdapters.h"
 
 
 using namespace lldb;
 using namespace lldb_private;
 
if (num_dumped > 0)
       result.SetStatus(eReturnStatusSuccessFinishResult);
     else {
       result.AppendError("no matching executable images found");
     }
     return result.Succeeded();
   }
 };
 
+class CommandObjectTargetModulesDumpClangPCMInfo : public CommandObjectParsed {
+public:
+  CommandObjectTargetModulesDumpClangPCMInfo(CommandInterpreter &interpreter)
+      : CommandObjectParsed(
+            interpreter, "target modules dump pcm-info",
+            "Dump information about the given clang module (pcm).") {
+    // Take a single file argument.
+    CommandArgumentData arg{eArgTypeFilename, eArgRepeatPlain};
+    m_arguments.push_back({arg});
+  }
+
+  ~CommandObjectTargetModulesDumpClangPCMInfo() override = default;
+
+protected:
+  bool DoExecute(Args &command, CommandReturnObject &result) override {
+    if (command.GetArgumentCount() != 1) {
+      result.AppendErrorWithFormat("'%s' takes exactly one pcm path argument.",
+                                   m_cmd_name.c_str());
+      return false;
+    }
+
+    const char *pcm_path = command.GetArgumentAtIndex(0);
+    FileSpec pcm_file{pcm_path};
+
+    if (pcm_file.GetFileNameExtension().GetStringRef() != ".pcm") {
+      result.AppendError("file must have a .pcm extension");
+      return false;
+    }
+
+    if (!FileSystem::Instance().Exists(pcm_file)) {
+      result.AppendError("pcm file does not exist");
+      return false;
+    }
+
+    clang::CompilerInstance compiler;
+    compiler.createDiagnostics();
+
+    const char *clang_args[] = {"clang", pcm_path};
+    compiler.setInvocation(clang::createInvocation(clang_args));
+
+    clang::DumpModuleInfoAction dump_module_info;
+    dump_module_info.OutputStream = &result.GetOutputStream().AsRawOstream();
+    // DumpModuleInfoAction requires ObjectFilePCHContainerReader.
+    compiler.getPCHContainerOperations()->registerReader(
+        std::make_unique<clang::ObjectFilePCHContainerReader>());
+
+    if (compiler.ExecuteAction(dump_module_info))
+      result.SetStatus(eReturnStatusSuccessFinishResult);
+
+    return result.Succeeded();
+  }
+};
+
 #pragma mark CommandObjectTargetModulesDumpClangAST
 
 // Clang AST dumping command
 
 class CommandObjectTargetModulesDumpClangAST
     : public CommandObjectTargetModulesModuleAutoComplete {
 public:
   CommandObjectTargetModulesDumpClangAST(CommandInterpreter &interpreter)

 // Dump multi-word command for target modules
 
 class CommandObjectTargetModulesDump : public CommandObjectMultiword {
 public:
   // Constructors and Destructors
   CommandObjectTargetModulesDump(CommandInterpreter &interpreter)
       : CommandObjectMultiword(
             interpreter, "target modules dump",
-            "Commands for dumping information about one or "
-            "more target modules.",
+            "Commands for dumping information about one or more target "
+            "modules.",
             "target modules dump "
-            "[headers|symtab|sections|ast|symfile|line-table] "
+            "[objfile|symtab|sections|ast|symfile|line-table|pcm-info] "
             "[<file1> <file2> ...]") {
     LoadSubCommand("objfile",
                    CommandObjectSP(
                        new CommandObjectTargetModulesDumpObjfile(interpreter)));
     LoadSubCommand(
         "symtab",
         CommandObjectSP(new CommandObjectTargetModulesDumpSymtab(interpreter)));
     LoadSubCommand("sections",
                    CommandObjectSP(new CommandObjectTargetModulesDumpSections(
                        interpreter)));
     LoadSubCommand("symfile",
                    CommandObjectSP(
                        new CommandObjectTargetModulesDumpSymfile(interpreter)));
     LoadSubCommand(
         "ast", CommandObjectSP(
                    new CommandObjectTargetModulesDumpClangAST(interpreter)));
     LoadSubCommand("line-table",
                    CommandObjectSP(new CommandObjectTargetModulesDumpLineTable(
                        interpreter)));
+    LoadSubCommand(
+        "pcm-info",
+        CommandObjectSP(
+            new CommandObjectTargetModulesDumpClangPCMInfo(interpreter)));
   }
 
   ~CommandObjectTargetModulesDump() override = default;
 };
 
 class CommandObjectTargetModulesAdd : public CommandObjectParsed {
 public:
   CommandObjectTargetModulesAdd(CommandInterpreter &interpreter)

lldb/test/API/commands/target/dump-pcm-info/Makefile

+OBJC_SOURCES := main.m
+USE_PRIVATE_MODULE_CACHE = YES
+include Makefile.rules
+

lldb/test/API/commands/target/dump-pcm-info/TestDumpPCMInfo.py

+"""
+Test 'target modules dump pcm-info'.
+"""
+
+import os
+import shutil
+import glob
+
+from lldbsuite.test.decorators import *
+from lldbsuite.test.lldbtest import *
+from lldbsuite.test import lldbutil
+
+
+class TestCase(TestBase):
+    @no_debug_info_test
+    @skipUnlessDarwin
+    def test(self):
+        self.build()
+
+        lldbutil.run_to_source_breakpoint(
+            self, "return", lldb.SBFileSpec("main.m"))
+
+        mod_cache = self.getBuildArtifact("private-module-cache")
+        if os.path.isdir(mod_cache):
+            shutil.rmtree(mod_cache)
+
+        self.runCmd(f"settings set symbols.clang-modules-cache-path '{mod_cache}'")
+
+        # Cause lldb to generate a Darwin-*.pcm
+        self.runCmd("p @import Darwin")
+
+        # root/<config-hash>/<module-name>-<modulemap-path-hash>.pcm
+        pcm_paths = glob.glob(os.path.join(mod_cache, '*', 'Darwin-*.pcm'))
+        self.assertEqual(len(pcm_paths), 1, "Expected one Darwin pcm")
+        pcm_path = pcm_paths[0]
+
+        self.expect(
+            f"target modules dump pcm-info '{pcm_path}'",
+            startstr=f"Information for module file '{pcm_path}'",
+            substrs=["Module name: Darwin"])

lldb/test/API/commands/target/dump-pcm-info/main.m

+int main() { return 0; }