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.1.4. Coverage runtime setup for configurations with no Ada runtime
  • 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. Optimizing the execution of instrumented programs
  • 1.3.4. Building instrumented components
  • 1.3.5. Extracting a trace from standard output
  • 1.3.6. Composed instrumentation
  • 1.3.7. Instrumentation of a multi-languages project
  • 1.3.8. Instrumentation and coverage of SPARK code
    • 1.3.8.1. Inhibiting SPARK related pragmas
    • 1.3.8.2. Coverage obligations for SPARK code
  • 1.3.9. Example use cases
    • 1.3.9.1. Whole program instrumented at once, cross configuration, base64 output
    • 1.3.9.2. Library instrumented separately, native configuration, trace output
  • 1.3.10. Coverage runtime customization
    • 1.3.10.1. Basics
    • 1.3.10.2. Customize the base64-stdout dump channel
    • 1.3.10.3. When the customized runtime needs elaboration
  • 1.3.11. Building instrumented programs with CCG
    • 1.3.11.1. Customizing the runtime
    • 1.3.11.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. SARIF report (=sarif)
    • 1.5.2.4. Violations summary, text (=report)
    • 1.5.2.5. Annotated sources, text (=xcov[+])
    • 1.5.2.6. 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 (experimental)
    • 1.5.6.1. Core notions and Reporting (--level=...+atc)
  • 1.5.7. Assertion True Condition Coverage (ATCC) analysis (experimental)
    • 1.5.7.1. Core notions and Reporting (--level=...+atcc)
  • 1.5.8. Function and Call Coverage (FUN_CALL) analysis (experimental)
    • 1.5.8.1. Core notions and Reporting (--level=...+fun_call)
  • 1.5.9. Guarded Expression Coverage (GEXPR) analysis (experimental)
    • 1.5.9.1. Core notions and Reporting (--level=...+gexpr)
  • 1.5.10. Synthetic metrics
  • 1.5.11. Handling source relocation for annotated sources output formats
  • 1.5.12. Inlining & Ada generic units
    • 1.5.12.1. Combined coverage on generics
  • 1.5.13. Handling Ada assertions and contracts
  • 1.5.14. Processing of C macros
  • 1.5.15. 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. Disable coverage analysis
  • 1.8.1. Defining Disabled Coverage Regions
  • 1.8.2. Consolidating traces with varying disabled coverage regions
  • 1.8.3. Reporting about disabled coverage regions
• 1.9. External source annotations
  • 1.9.1. Generating external annotations
    • 1.9.1.1. Semantics of buffer manipulation annotations
    • 1.9.1.2. File relocation considerations
  • 1.9.2. Deleting a pre-existing annotation
  • 1.9.3. Displaying the annotations contained in annotation files
  • 1.9.4. Annotation stability through file modifications
• 1.10. Using project files
  • 1.10.1. General considerations
  • 1.10.2. Specifying gnatcov command Switches
  • 1.10.3. Specifying the Target and language Runtime
• 1.11. Using GNATcoverage from GNAT Studio
  • 1.11.1. Basic scenario
  • 1.11.2. Viewing a coverage report produced outside of GNAT Studio
  • 1.11.3. Using GNATtest’s coverage integration makefile
  • 1.11.4. GNATtest scenario
• 1.12. Glossary of terms & concepts
• 1.13. Appendices
  • 1.13.1. Sample html index
  • 1.13.2. Sample html annotated source