package bisect_ppx

  1. Overview
  2. Docs
Code coverage for OCaml

Install 

dune-project
 Dependency

github.com Readme MIT License Edit opam file Versions (21)

Authors

  1. X
    Xavier Clerc <bisect@x9c.fr>
  2. L
    Leonid Rozenberg <leonidr@gmail.com>
  3. Anton Bachin

Maintainers

  1. Anton Bachin
  2. L
    Leonid Rozenberg <leonidr@gmail.com>

Sources

2.7.0.tar.gz
sha256=50ef640123a7e2961cdbb5a6e9bad8f408547c38d0d7f3d2c2d355280ef7e5cb
md5=73cddd4025cff329b52b93bb663927f8

doc/bisect_ppx.common/Bisect_common/index.html

Module Bisect_commonSource

This module provides type definitions and functions that are shared between more than one part of Bisect, namely:

  • the instrumenter (PPX)
  • the native runtime (Bisect.Runtime in src/runtime/native/)
  • the ReScript runtime (Bisect.Runtime in src/runtime/bucklescript/)
  • the reporter (bisect-ppx-report)

Types

Types representing accumulated visit counts. This data is written to bisect*.coverage files when an instrumented binary exits.

The two types in this section, instrumented_file and coverage, and the value coverage_file_identifier, are the only items shared with the reporter. Otherwise, the reporter is self-contained.

Sourcetype instrumented_file = {
  1. filename : string;
    (*

    Source file name.

    *)
  2. points : int list;
    (*

    Byte offsets of the points placed in the file.

    *)
  3. counts : int array;
    (*

    Visitation counts, one for each point.

    *)
}

Data gathered for a single source file.

Sourcetype coverage = (string, instrumented_file) Hashtbl.t

A binary instrumented with Bisect, when run, produces coverage statistics for each of its source files. The runtime and reporter both index the statistics by source file name.

Sourceval coverage_file_identifier : string

A string written at the beginning of each bisect*.coverage files. Provides a sanity check for the reporter that it is reading a bisect*.coverage file, and the file format version.

Initialization

Sourceval register_file : filename:string -> points:int list -> [ `Visit of int -> unit ]

Each source file is instrumented to call Bisect.Runtime.register_file at run time, during program initialization. Bisect.Runtime.register_file eventually forwards to this function, Biesct_common.register_file. This function allocates the visit count array, with one array cell for each point, and registers the array for later writing to bisect*.coverage files.

  • ~filename is the name of the source file.
  • ~points is the list of byte offsets of the instrumentation points placed in the source file.

The return value is the function that is called by each instrumentation point to increment its own visit count. The instrumentation point passes its own index to the function.

.coverage output

Sourceval write_runtime_coverage : coverage -> out_channel -> unit

Writes the coverage to the given output channel.

Sourceval write_runtime_data : out_channel -> unit

Writes the current accumulated coverage data (of type coverage) to the given output channel.

Sourceval runtime_data_to_string : unit -> string option

Same as write_runtime_data, but writes the output to a string instead.

None is returned if there are no source files registered. This can occur when the runtime gets linked into a binary, but no files had been instrumented, because instrumentation was turned off. This combination normally shouldn't happen, but it can occur depending on the quality of the integration between the build system and Bisect.

Sourceval reset_counters : unit -> unit

Clears accumulated visit counts. All array cells are set to zero.

Sourceval random_filename : prefix:string -> string

Returns a random filename with the given prefix.