Add new API to SBTarget and SBModule classes.

[apolyakov]

Summary

The new API allows to find a list of compile units related to target/module.

[aprantl]

This seems like a reasonable addition. Could you also add documentation for the new API?

[clayborg]

needs a test, but looks good.

[apolyakov]

Added documentation and tests.

[aprantl]

include/lldb/API/SBModule.h

136

We typically use \param instead of @param in LLVM.

packages/Python/lldbsuite/test/python_api/module_section/TestModuleAndSection.py

151

shouldn't this be self.getBuildArtifact('b.out')?

packages/Python/lldbsuite/test/python_api/target/TestTargetAPI.py

54

shouldn't this be self.getBuildArtifact('b.out')?

[apolyakov]

packages/Python/lldbsuite/test/python_api/target/TestTargetAPI.py

54

Do you mean: shouldn't self.getBuildArtifact be as a find_compile_units parameter?

[apolyakov]

include/lldb/API/SBModule.h

136

I did it like it's done in other places in lldb. Are you sure about \param and @param?

[jingham]

Alex is right, lldb uses @param everywhere.

[aprantl]

Fre

packages/Python/lldbsuite/test/python_api/target/TestTargetAPI.py

54

self.find_compile_units(self.getBuildArtifact('b.out'))

[apolyakov]

Updated passing an argument to find_compile_units function.

include/lldb/API/SBModule.h

ResolveSymbolContextForAddress(const lldb::SBAddress &addr,
                                  uint32_t resolve_scope);
 
   bool GetDescription(lldb::SBStream &description);
 
   uint32_t GetNumCompileUnits();
 
   lldb::SBCompileUnit GetCompileUnitAtIndex(uint32_t);
 
+  //------------------------------------------------------------------
+  /// Find compile units related to *this module and passed source
+  /// file.
+  ///
+  /// @param[in] sb_file_spec
+  ///     A lldb::SBFileSpec object that contains source file
+  ///     specification.
+  ///
+  /// @return
+  ///     A lldb::SBSymbolContextList that gets filled in with all of
+  ///     the symbol contexts for all the matches.
+  //------------------------------------------------------------------
+  lldb::SBSymbolContextList
+  FindCompileUnits(const lldb::SBFileSpec &sb_file_spec);
+
   size_t GetNumSymbols();
 
   lldb::SBSymbol GetSymbolAtIndex(size_t idx);
 
   lldb::SBSymbol FindSymbol(const char *name,
                             lldb::SymbolType type = eSymbolTypeAny);
 
   lldb::SBSymbolContextList FindSymbols(const char *name,

include/lldb/API/SBTarget.h

public:
   lldb::SBModule GetModuleAtIndex(uint32_t idx);
 
   bool RemoveModule(lldb::SBModule module);
 
   lldb::SBDebugger GetDebugger() const;
 
   lldb::SBModule FindModule(const lldb::SBFileSpec &file_spec);
 
+  //------------------------------------------------------------------
+  /// Find compile units related to *this target and passed source
+  /// file.
+  ///
+  /// @param[in] sb_file_spec
+  ///     A lldb::SBFileSpec object that contains source file
+  ///     specification.
+  ///
+  /// @return
+  ///     A lldb::SBSymbolContextList that gets filled in with all of
+  ///     the symbol contexts for all the matches.
+  //------------------------------------------------------------------
+  lldb::SBSymbolContextList
+  FindCompileUnits(const lldb::SBFileSpec &sb_file_spec);
+
   lldb::ByteOrder GetByteOrder();
 
   uint32_t GetAddressByteSize();
 
   const char *GetTriple();
 
   //------------------------------------------------------------------
   /// Architecture data byte width accessor

packages/Python/lldbsuite/test/python_api/module_section/TestModuleAndSection.py

def test_module_compile_unit_iter(self):
         exe_module = target.GetModuleAtIndex(0)
 
         print("Exe module: %s" % str(exe_module))
         print("Number of compile units: %d" % exe_module.GetNumCompileUnits())
         INDENT = ' ' * 4
         INDENT2 = INDENT * 2
         for cu in exe_module.compile_unit_iter():
             print(cu)
+
+    @add_test_categories(['pyapi'])
+    def test_find_compile_units(self):
+        """Exercise SBModule.FindCompileUnits() API."""
+        d = {'EXE': 'b.out'}
+        self.build(dictionary=d)
+        self.setTearDownCleanup(dictionary=d)
+        self.find_compile_units('b.out')
+
+    def find_compile_units(self, exe_name):
+        """Exercise SBModule.FindCompileUnits() API."""
+        exe = self.getBuildArtifact(exe_name)
+        source_name_list = ["main.cpp", "b.cpp", "c.cpp"]
+
+        # Create a target by the debugger.
+        target = self.dbg.CreateTarget(exe)
+        self.assertTrue(target, VALID_TARGET)
+
+        num_modules = target.GetNumModules()
+        for i in range(num_modules):
+            module = target.GetModuleAtIndex(i)
+            for source_name in source_name_list:
+                list = module.FindCompileUnits(lldb.SBFileSpec(source_name, False))
+                for sc in list:
+                    self.assertTrue(
+                        sc.GetCompileUnit().GetFileSpec().GetFilename() ==
+                        source_name)

packages/Python/lldbsuite/test/python_api/target/TestTargetAPI.py

class TargetAPITestCase(TestBase):
     def test_find_global_variables(self):
         """Exercise SBTarget.FindGlobalVariables() API."""
         d = {'EXE': 'b.out'}
         self.build(dictionary=d)
         self.setTearDownCleanup(dictionary=d)
         self.find_global_variables('b.out')
 
     @add_test_categories(['pyapi'])
+    def test_find_compile_units(self):
+        """Exercise SBTarget.FindCompileUnits() API."""
+        d = {'EXE': 'b.out'}
+        self.build(dictionary=d)
+        self.setTearDownCleanup(dictionary=d)
+        self.find_compile_units('b.out')
+
+    @add_test_categories(['pyapi'])
     @expectedFailureAll(oslist=["windows"], bugnumber="llvm.org/pr24778")
     def test_find_functions(self):
         """Exercise SBTarget.FindFunctions() API."""
         d = {'EXE': 'b.out'}
         self.build(dictionary=d)
         self.setTearDownCleanup(dictionary=d)
         self.find_functions('b.out')
 
def find_global_variables(self, exe_name):
             if os.path.normpath(m.GetFileSpec().GetDirectory()) == self.getBuildDir() and m.GetFileSpec().GetFilename() == exe_name:
                 value_list = m.FindGlobalVariables(
                     target, 'my_global_var_of_char_type', 3)
                 self.assertTrue(value_list.GetSize() == 1)
                 self.assertTrue(
                     value_list.GetValueAtIndex(0).GetValue() == "'X'")
                 break
 
+    def find_compile_units(self, exe_name):
+        """Exercise SBTarget.FindCompileUnits() API."""
+        exe = self.getBuildArtifact(exe_name)
+        source_name = "main.c"
+
+        # Create a target by the debugger.
+        target = self.dbg.CreateTarget(exe)
+        self.assertTrue(target, VALID_TARGET)
+
+        list = target.FindCompileUnits(lldb.SBFileSpec(source_name, False))
+        # Executable has been built just from one source file 'main.c',
+        # so we may check only the first element of list.
+        self.assertTrue(
+            list[0].GetCompileUnit().GetFileSpec().GetFilename() == source_name)
+
     def find_functions(self, exe_name):
         """Exercise SBTaget.FindFunctions() API."""
         exe = self.getBuildArtifact(exe_name)
 
         # Create a target by the debugger.
         target = self.dbg.CreateTarget(exe)
         self.assertTrue(target, VALID_TARGET)
 

scripts/interface/SBModule.i

public:
     GetDescription (lldb::SBStream &description);
 
     uint32_t
     GetNumCompileUnits();
 
     lldb::SBCompileUnit
     GetCompileUnitAtIndex (uint32_t);
 
+    %feature("docstring", "
+    //------------------------------------------------------------------
+    /// Find compile units related to *this module and passed source
+    /// file.
+    ///
+    /// @param[in] sb_file_spec
+    ///     A lldb::SBFileSpec object that contains source file
+    ///     specification.
+    ///
+    /// @return
+    ///     A lldb::SBSymbolContextList that gets filled in with all of
+    ///     the symbol contexts for all the matches.
+    //------------------------------------------------------------------
+    ") FindCompileUnits;
+    lldb::SBSymbolContextList
+    FindCompileUnits (const lldb::SBFileSpec &sb_file_spec);
+
     size_t
     GetNumSymbols ();
     
     lldb::SBSymbol
     GetSymbolAtIndex (size_t idx);
 
     lldb::SBSymbol
     FindSymbol (const char *name,

scripts/interface/SBTarget.i

public:
     RemoveModule (lldb::SBModule module);
 
     lldb::SBDebugger
     GetDebugger() const;
 
     lldb::SBModule
     FindModule (const lldb::SBFileSpec &file_spec);
 
+    %feature("docstring", "
+    //------------------------------------------------------------------
+    /// Find compile units related to *this target and passed source
+    /// file.
+    ///
+    /// @param[in] sb_file_spec
+    ///     A lldb::SBFileSpec object that contains source file
+    ///     specification.
+    ///
+    /// @return
+    ///     A lldb::SBSymbolContextList that gets filled in with all of
+    ///     the symbol contexts for all the matches.
+    //------------------------------------------------------------------
+    ") FindCompileUnits;
+    lldb::SBSymbolContextList
+    FindCompileUnits (const lldb::SBFileSpec &sb_file_spec);
+
     lldb::ByteOrder
     GetByteOrder ();
 
     uint32_t
     GetAddressByteSize();
 
     const char *
     GetTriple ();

source/API/SBModule.cpp

SBCompileUnit SBModule::GetCompileUnitAtIndex(uint32_t index) {
   ModuleSP module_sp(GetSP());
   if (module_sp) {
     CompUnitSP cu_sp = module_sp->GetCompileUnitAtIndex(index);
     sb_cu.reset(cu_sp.get());
   }
   return sb_cu;
 }
 
+SBSymbolContextList
+SBModule::FindCompileUnits(const SBFileSpec &sb_file_spec) {
+  SBSymbolContextList sb_sc_list;
+  const ModuleSP module_sp(GetSP());
+  if (sb_file_spec.IsValid() && module_sp) {
+    const bool append = true;
+    module_sp->FindCompileUnits(*sb_file_spec, append, *sb_sc_list);
+  }
+  return sb_sc_list;
+}
+
 static Symtab *GetUnifiedSymbolTable(const lldb::ModuleSP &module_sp) {
   if (module_sp) {
     SymbolVendor *symbols = module_sp->GetSymbolVendor();
     if (symbols)
       return symbols->GetSymtab();
   }
   return NULL;
 }

source/API/SBTarget.cpp

SBModule SBTarget::FindModule(const SBFileSpec &sb_file_spec) {
   if (target_sp && sb_file_spec.IsValid()) {
     ModuleSpec module_spec(*sb_file_spec);
     // The module list is thread safe, no need to lock
     sb_module.SetSP(target_sp->GetImages().FindFirstModule(module_spec));
   }
   return sb_module;
 }
 
+SBSymbolContextList
+SBTarget::FindCompileUnits(const SBFileSpec &sb_file_spec) {
+  SBSymbolContextList sb_sc_list;
+  const TargetSP target_sp(GetSP());
+  if (target_sp && sb_file_spec.IsValid()) {
+    const bool append = true;
+    target_sp->GetImages().FindCompileUnits(*sb_file_spec,
+                                            append, *sb_sc_list);
+  }
+  return sb_sc_list;
+}
+
 lldb::ByteOrder SBTarget::GetByteOrder() {
   TargetSP target_sp(GetSP());
   if (target_sp)
     return target_sp->GetArchitecture().GetByteOrder();
   return eByteOrderInvalid;
 }
 
 const char *SBTarget::GetTriple() {