1    :  // Copyright 2012 Google Inc. All Rights Reserved.
   2    :  //
   3    :  // Licensed under the Apache License, Version 2.0 (the "License");
   4    :  // you may not use this file except in compliance with the License.
   5    :  // You may obtain a copy of the License at
   6    :  //
   7    :  //     http://www.apache.org/licenses/LICENSE-2.0
   8    :  //
   9    :  // Unless required by applicable law or agreed to in writing, software
  10    :  // distributed under the License is distributed on an "AS IS" BASIS,
  11    :  // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  12    :  // See the License for the specific language governing permissions and
  13    :  // limitations under the License.
  14    :  //
  15    :  // Declares utility functions for outputting an LCOV formatted coverage file
  16    :  // from a populated CoverageData object.
  17    :  //
  18    :  // We only support the minimum subset of LCOV that is used by Chromium code
  19    :  // coverage report generating tool, croc. Namely, the DA, LF and LH tags.
  20    :  //
  21    :  // There is no single document defining the LCOV file format so we summarize
  22    :  // it here. The information has been taken from LCOV source code and manpages
  23    :  // and collected here.
  24    :  //
  25    :  // An LCOV file is a plain-text ASCII file. Each line begins with a tag (in
  26    :  // all capital letters, to be discussed below) immediately followed by a
  27    :  // colon. Following each tag is an arbitrary amount of whitespace (may be none)
  28    :  // and then the tag data, the format of which depends on the tag type.
  29    :  //
  30    :  // The following tags are header tags and may be present only once at the
  31    :  // beginning of a file:
  32    :  //
  33    :  //   TN: <name of test>
  34    :  //   TD: <textual description of test>
  35    :  //
  36    :  // Following the header there are multiple records, one per source file for
  37    :  // which coverage results are present. Each record starts with the tag:
  38    :  //
  39    :  //   SF: <full path to source file>
  40    :  //
  41    :  // Each instrumented line of text is indicated using the tag:
  42    :  //
  43    :  //   DA: <line number>, <execution count>
  44    :  //
  45    :  // A line that is instrumented but not executed should be indicated with an
  46    :  // execution count of 0. A line that is not instrumented should have no DA
  47    :  // record.
  48    :  //
  49    :  // Optionally, a record may specify function information using the following
  50    :  // tags:
  51    :  //
  52    :  //   FN: <line number of start of function>, <function name>
  53    :  //   FNDA: <call count>, <function name>
  54    :  //
  55    :  // Again, FN* records should not be specified for functions that are not
  56    :  // instrumented.
  57    :  //
  58    :  // Optionally, branch coverage may be specified. For each instrumented branch
  59    :  // point in the code information is recorded using the following tag:
  60    :  //
  61    :  //   BA: <line number>, <branch coverage value>
  62    :  //
  63    :  // where <branch coverage value> is one of:
  64    :  //
  65    :  //   0 - branch not executed.
  66    :  //   1 - branch executed but not taken.
  67    :  //   2 - branch executed and taken.
  68    :  //
  69    :  // Following DA/FN/FNDA/BA tags a record should contain appropriate summary
  70    :  // tags.
  71    :  //
  72    :  // If line instrumentation is present the following tags should be present:
  73    :  //
  74    :  //   LH: <number of lines with non-zero execution count>
  75    :  //   LF: <number of instrumented lines (number of DA records)>
  76    :  //
  77    :  // If function information is present the followings tags should be present:
  78    :  //
  79    :  //   FNH: <number of functions (number of FN records)>
  80    :  //   FNF: <number of functions with non-zero call count>
  81    :  //
  82    :  // Finally, a record (information regarding a single source file) should be
  83    :  // terminated with a single line containing the string 'end_of_record'.
  84    :  
  85    :  #ifndef SYZYGY_GRINDER_LCOV_WRITER_H_
  86    :  #define SYZYGY_GRINDER_LCOV_WRITER_H_
  87    :  
  88    :  #include "base/files/file_path.h"
  89    :  #include "syzygy/grinder/coverage_data.h"
  90    :  
  91  m :  namespace grinder {
  92    :  
  93    :  // Dumps the provided @p coverage information to an LCOV file.
  94    :  // @param coverage the summarized coverage info to be written.
  95    :  // @param path the path to the file to be created or overwritten.
  96    :  // @param file the file handle to be written to.
  97    :  // @returns true on success, false otherwise.
  98  m :  bool WriteLcovCoverageFile(const CoverageData& coverage,
  99  m :                             const base::FilePath& path);
 100  m :  bool WriteLcovCoverageFile(const CoverageData& coverage, FILE* file);
 101    :  
 102  m :  }  // namespace grinder
 103    :  
 104    :  #endif  // SYZYGY_GRINDER_LCOV_WRITER_H_