1 //===- SourceCoverageView.h - Code coverage view for source code ----------===//
2 //
3 //                     The LLVM Compiler Infrastructure
4 //
5 // This file is distributed under the University of Illinois Open Source
6 // License. See LICENSE.TXT for details.
7 //
8 //===----------------------------------------------------------------------===//
9 ///
10 /// \file This class implements rendering for code coverage of source code.
11 ///
12 //===----------------------------------------------------------------------===//
13 
14 #ifndef LLVM_COV_SOURCECOVERAGEVIEW_H
15 #define LLVM_COV_SOURCECOVERAGEVIEW_H
16 
17 #include "CoverageViewOptions.h"
18 #include "llvm/ProfileData/Coverage/CoverageMapping.h"
19 #include "llvm/Support/MemoryBuffer.h"
20 #include <vector>
21 
22 namespace llvm {
23 
24 class SourceCoverageView;
25 
26 /// \brief A view that represents a macro or include expansion.
27 struct ExpansionView {
28   coverage::CounterMappingRegion Region;
29   std::unique_ptr<SourceCoverageView> View;
30 
31   ExpansionView(const coverage::CounterMappingRegion &Region,
32                 std::unique_ptr<SourceCoverageView> View)
33       : Region(Region), View(std::move(View)) {}
34   ExpansionView(ExpansionView &&RHS)
35       : Region(std::move(RHS.Region)), View(std::move(RHS.View)) {}
36   ExpansionView &operator=(ExpansionView &&RHS) {
37     Region = std::move(RHS.Region);
38     View = std::move(RHS.View);
39     return *this;
40   }
41 
42   unsigned getLine() const { return Region.LineStart; }
43   unsigned getStartCol() const { return Region.ColumnStart; }
44   unsigned getEndCol() const { return Region.ColumnEnd; }
45 
46   friend bool operator<(const ExpansionView &LHS, const ExpansionView &RHS) {
47     return LHS.Region.startLoc() < RHS.Region.startLoc();
48   }
49 };
50 
51 /// \brief A view that represents a function instantiation.
52 struct InstantiationView {
53   StringRef FunctionName;
54   unsigned Line;
55   std::unique_ptr<SourceCoverageView> View;
56 
57   InstantiationView(StringRef FunctionName, unsigned Line,
58                     std::unique_ptr<SourceCoverageView> View)
59       : FunctionName(FunctionName), Line(Line), View(std::move(View)) {}
60 
61   friend bool operator<(const InstantiationView &LHS,
62                         const InstantiationView &RHS) {
63     return LHS.Line < RHS.Line;
64   }
65 };
66 
67 /// \brief Coverage statistics for a single line.
68 struct LineCoverageStats {
69   uint64_t ExecutionCount;
70   unsigned RegionCount;
71   bool Mapped;
72 
73   LineCoverageStats() : ExecutionCount(0), RegionCount(0), Mapped(false) {}
74 
75   bool isMapped() const { return Mapped; }
76 
77   bool hasMultipleRegions() const { return RegionCount > 1; }
78 
79   void addRegionStartCount(uint64_t Count) {
80     // The max of all region starts is the most interesting value.
81     addRegionCount(RegionCount ? std::max(ExecutionCount, Count) : Count);
82     ++RegionCount;
83   }
84 
85   void addRegionCount(uint64_t Count) {
86     Mapped = true;
87     ExecutionCount = Count;
88   }
89 };
90 
91 /// \brief A file manager that handles format-aware file creation.
92 class CoveragePrinter {
93 public:
94   struct StreamDestructor {
95     void operator()(raw_ostream *OS) const;
96   };
97 
98   using OwnedStream = std::unique_ptr<raw_ostream, StreamDestructor>;
99 
100 protected:
101   const CoverageViewOptions &Opts;
102 
103   CoveragePrinter(const CoverageViewOptions &Opts) : Opts(Opts) {}
104 
105   /// \brief Return `OutputDir/ToplevelDir/Path.Extension`. If \p InToplevel is
106   /// false, skip the ToplevelDir component. If \p Relative is false, skip the
107   /// OutputDir component.
108   std::string getOutputPath(StringRef Path, StringRef Extension,
109                             bool InToplevel, bool Relative = true) const;
110 
111   /// \brief If directory output is enabled, create a file in that directory
112   /// at the path given by getOutputPath(). Otherwise, return stdout.
113   Expected<OwnedStream> createOutputStream(StringRef Path, StringRef Extension,
114                                            bool InToplevel) const;
115 
116   /// \brief Return the sub-directory name for file coverage reports.
117   static StringRef getCoverageDir() { return "coverage"; }
118 
119 public:
120   static std::unique_ptr<CoveragePrinter>
121   create(const CoverageViewOptions &Opts);
122 
123   virtual ~CoveragePrinter() {}
124 
125   /// @name File Creation Interface
126   /// @{
127 
128   /// \brief Create a file to print a coverage view into.
129   virtual Expected<OwnedStream> createViewFile(StringRef Path,
130                                                bool InToplevel) = 0;
131 
132   /// \brief Close a file which has been used to print a coverage view.
133   virtual void closeViewFile(OwnedStream OS) = 0;
134 
135   /// \brief Create an index which lists reports for the given source files.
136   virtual Error createIndexFile(ArrayRef<std::string> SourceFiles,
137                                 const coverage::CoverageMapping &Coverage) = 0;
138 
139   /// @}
140 };
141 
142 /// \brief A code coverage view of a source file or function.
143 ///
144 /// A source coverage view and its nested sub-views form a file-oriented
145 /// representation of code coverage data. This view can be printed out by a
146 /// renderer which implements the Rendering Interface.
147 class SourceCoverageView {
148   /// A function or file name.
149   StringRef SourceName;
150 
151   /// A memory buffer backing the source on display.
152   const MemoryBuffer &File;
153 
154   /// Various options to guide the coverage renderer.
155   const CoverageViewOptions &Options;
156 
157   /// Complete coverage information about the source on display.
158   coverage::CoverageData CoverageInfo;
159 
160   /// A container for all expansions (e.g macros) in the source on display.
161   std::vector<ExpansionView> ExpansionSubViews;
162 
163   /// A container for all instantiations (e.g template functions) in the source
164   /// on display.
165   std::vector<InstantiationView> InstantiationSubViews;
166 
167   /// Get the first uncovered line number for the source file.
168   unsigned getFirstUncoveredLineNo();
169 
170 protected:
171   struct LineRef {
172     StringRef Line;
173     int64_t LineNo;
174 
175     LineRef(StringRef Line, int64_t LineNo) : Line(Line), LineNo(LineNo) {}
176   };
177 
178   using CoverageSegmentArray = ArrayRef<const coverage::CoverageSegment *>;
179 
180   /// @name Rendering Interface
181   /// @{
182 
183   /// \brief Render a header for the view.
184   virtual void renderViewHeader(raw_ostream &OS) = 0;
185 
186   /// \brief Render a footer for the view.
187   virtual void renderViewFooter(raw_ostream &OS) = 0;
188 
189   /// \brief Render the source name for the view.
190   virtual void renderSourceName(raw_ostream &OS, bool WholeFile) = 0;
191 
192   /// \brief Render the line prefix at the given \p ViewDepth.
193   virtual void renderLinePrefix(raw_ostream &OS, unsigned ViewDepth) = 0;
194 
195   /// \brief Render the line suffix at the given \p ViewDepth.
196   virtual void renderLineSuffix(raw_ostream &OS, unsigned ViewDepth) = 0;
197 
198   /// \brief Render a view divider at the given \p ViewDepth.
199   virtual void renderViewDivider(raw_ostream &OS, unsigned ViewDepth) = 0;
200 
201   /// \brief Render a source line with highlighting.
202   virtual void renderLine(raw_ostream &OS, LineRef L,
203                           const coverage::CoverageSegment *WrappedSegment,
204                           CoverageSegmentArray Segments, unsigned ExpansionCol,
205                           unsigned ViewDepth) = 0;
206 
207   /// \brief Render the line's execution count column.
208   virtual void renderLineCoverageColumn(raw_ostream &OS,
209                                         const LineCoverageStats &Line) = 0;
210 
211   /// \brief Render the line number column.
212   virtual void renderLineNumberColumn(raw_ostream &OS, unsigned LineNo) = 0;
213 
214   /// \brief Render all the region's execution counts on a line.
215   virtual void renderRegionMarkers(raw_ostream &OS,
216                                    CoverageSegmentArray Segments,
217                                    unsigned ViewDepth) = 0;
218 
219   /// \brief Render the site of an expansion.
220   virtual void
221   renderExpansionSite(raw_ostream &OS, LineRef L,
222                       const coverage::CoverageSegment *WrappedSegment,
223                       CoverageSegmentArray Segments, unsigned ExpansionCol,
224                       unsigned ViewDepth) = 0;
225 
226   /// \brief Render an expansion view and any nested views.
227   virtual void renderExpansionView(raw_ostream &OS, ExpansionView &ESV,
228                                    unsigned ViewDepth) = 0;
229 
230   /// \brief Render an instantiation view and any nested views.
231   virtual void renderInstantiationView(raw_ostream &OS, InstantiationView &ISV,
232                                        unsigned ViewDepth) = 0;
233 
234   /// \brief Render \p Title, a project title if one is available, and the
235   /// created time.
236   virtual void renderTitle(raw_ostream &OS, StringRef CellText) = 0;
237 
238   /// \brief Render the table header for a given source file.
239   virtual void renderTableHeader(raw_ostream &OS, unsigned FirstUncoveredLineNo,
240                                  unsigned IndentLevel) = 0;
241 
242   /// @}
243 
244   /// \brief Format a count using engineering notation with 3 significant
245   /// digits.
246   static std::string formatCount(uint64_t N);
247 
248   /// \brief Check if region marker output is expected for a line.
249   bool shouldRenderRegionMarkers(bool LineHasMultipleRegions) const;
250 
251   /// \brief Check if there are any sub-views attached to this view.
252   bool hasSubViews() const;
253 
254   SourceCoverageView(StringRef SourceName, const MemoryBuffer &File,
255                      const CoverageViewOptions &Options,
256                      coverage::CoverageData &&CoverageInfo)
257       : SourceName(SourceName), File(File), Options(Options),
258         CoverageInfo(std::move(CoverageInfo)) {}
259 
260 public:
261   static std::unique_ptr<SourceCoverageView>
262   create(StringRef SourceName, const MemoryBuffer &File,
263          const CoverageViewOptions &Options,
264          coverage::CoverageData &&CoverageInfo);
265 
266   virtual ~SourceCoverageView() {}
267 
268   /// \brief Return the source name formatted for the host OS.
269   std::string getSourceName() const;
270 
271   const CoverageViewOptions &getOptions() const { return Options; }
272 
273   /// \brief Add an expansion subview to this view.
274   void addExpansion(const coverage::CounterMappingRegion &Region,
275                     std::unique_ptr<SourceCoverageView> View);
276 
277   /// \brief Add a function instantiation subview to this view.
278   void addInstantiation(StringRef FunctionName, unsigned Line,
279                         std::unique_ptr<SourceCoverageView> View);
280 
281   /// \brief Print the code coverage information for a specific portion of a
282   /// source file to the output stream.
283   void print(raw_ostream &OS, bool WholeFile, bool ShowSourceName,
284              unsigned ViewDepth = 0);
285 };
286 
287 } // namespace llvm
288 
289 #endif // LLVM_COV_SOURCECOVERAGEVIEW_H
290