1. GNATcoverage User’s Guide

• 1.1. Getting Started
  • 1.1.1. General notions
  • 1.1.2. Workflow overview
  • 1.1.3. A simple example
    • 1.1.3.1. Sample project
    • 1.1.3.2. Setup, Instrument, Build, Execute, Analyze
  • 1.1.4. Going Further
  • 1.1.5. Conventions used in the rest of this manual
• 1.2. Specifying Units Of Interest
  • 1.2.1. Using project files (-P, --projects, --units)
    • 1.2.1.1. Conveying projects of interest
    • 1.2.1.2. Conveying units of interest within projects
    • 1.2.1.3. Conveying subprograms of interest (experimental)
    • 1.2.1.4. Other switches or attributes of importance
  • 1.2.2. Conveying source files to ignore / handling Ada subunits
  • 1.2.3. Compilation unit vs source file names
  • 1.2.4. Providing coverage obligation files (--sid)
• 1.3. Producing source traces with gnatcov instrument
  • 1.3.1. Setting up the coverage runtime library
    • 1.3.1.1. Multiple runtimes in the same prefix
    • 1.3.1.2. Language restrictions
    • 1.3.1.3. Default source trace dump options
  • 1.3.2. Instrumenting programs
    • 1.3.2.1. gnatcov instrument command line
    • 1.3.2.2. Output strategies for main units
    • 1.3.2.3. Resetting coverage information during the execution
    • 1.3.2.4. Controlling trace file names
    • 1.3.2.5. Support for preprocessing
    • 1.3.2.6. gnatcov instrument limitations
  • 1.3.3. Building instrumented components
  • 1.3.4. Extracting a trace from standard output
  • 1.3.5. Composed instrumentation
  • 1.3.6. Instrumentation of a multi-languages project
  • 1.3.7. Instrumentation and coverage of SPARK code
    • 1.3.7.1. Inhibiting SPARK related pragmas
    • 1.3.7.2. Coverage obligations for SPARK code
  • 1.3.8. Example use cases
    • 1.3.8.1. Whole program instrumented at once, cross configuration, base64 output
    • 1.3.8.2. Library instrumented separately, native configuration, trace output
  • 1.3.9. Coverage runtime customization
    • 1.3.9.1. Basics
    • 1.3.9.2. Customize the base64-stdout dump channel
  • 1.3.10. Building instrumented programs with CCG
    • 1.3.10.1. Customizing the runtime
    • 1.3.10.2. Building an instrumented program with CCG
• 1.4. Producing source traces with integrated instrumentation (experimental)
  • 1.4.1. Specifying instrumentation switches
  • 1.4.2. Building an instrumented executable
  • 1.4.3. A simple Makefile example
  • 1.4.4. A simple CMake example
• 1.5. Source coverage analysis with gnatcov coverage
  • 1.5.1. gnatcov coverage command line
  • 1.5.2. Output report formats (--annotate)
    • 1.5.2.1. Cobertura report (=cobertura)
    • 1.5.2.2. Annotated sources, html (=html)
    • 1.5.2.3. Violations summary, text (=report)
    • 1.5.2.4. Annotated sources, text (=xcov[+])
    • 1.5.2.5. XML report, xml (=xml)
  • 1.5.3. Statement Coverage analysis
    • 1.5.3.1. Core notions and Reporting (--level=stmt)
    • 1.5.3.2. Example program and assessments
  • 1.5.4. Decision Coverage analysis
    • 1.5.4.1. Core notions and Reporting (--level=stmt+decision)
    • 1.5.4.2. Example program and assessments
  • 1.5.5. Modified Condition/Decision Coverage analysis
    • 1.5.5.1. Core notions and Reporting (--level=stmt+mcdc)
    • 1.5.5.2. Example decisions and conditions
    • 1.5.5.3. Handling non short-circuit operators
    • 1.5.5.4. MCDC variants
    • 1.5.5.5. Example program and assessments
  • 1.5.6. Assertion True Coverage (ATC) analysis
    • 1.5.6.1. Core notions and Reporting (--level=...+atc)
  • 1.5.7. Assertion True Condition Coverage (ATCC) analysis
    • 1.5.7.1. Core notions and Reporting (--level=...+atcc)
  • 1.5.8. Synthetic metrics
  • 1.5.9. Handling source relocation for annotated sources output formats
  • 1.5.10. Inlining & Ada generic units
    • 1.5.10.1. Combined coverage on generics (default behavior)
    • 1.5.10.2. Separated coverage on generics
  • 1.5.11. Handling Ada assertions and contracts
  • 1.5.12. Processing of C macros
  • 1.5.13. Optimization and non-coverable items
• 1.6. Coverage Consolidation
  • 1.6.1. Consolidation from trace files
    • 1.6.1.1. Single unit tested by different programs
    • 1.6.1.2. Disjoint units tested by different programs
    • 1.6.1.3. Multiple executions of a single program
  • 1.6.2. Consolidation from coverage checkpoints
    • 1.6.2.1. Efficient storage of test results
    • 1.6.2.2. Incremental coverage analysis
    • 1.6.2.3. Handle incidental coverage effects
    • 1.6.2.4. Compatibility considerations
• 1.7. Coverage Exemptions
  • 1.7.1. Defining Exemption Regions
  • 1.7.2. Reporting about coverage exemptions
    • 1.7.2.1. Undetermined Coverage state and Exemptions
  • 1.7.3. Object coverage exemptions
• 1.8. Using project files
  • 1.8.1. General considerations
  • 1.8.2. Specifying gnatcov command Switches
  • 1.8.3. Specifying the Target and language Runtime
• 1.9. Using GNATcoverage from GNAT Studio
  • 1.9.1. Basic scenario
  • 1.9.2. Viewing a coverage report produced outside of GNAT Studio
  • 1.9.3. GNATtest scenario
• 1.10. Glossary of terms & concepts