diff --git a/docs/_docs/internals/coverage.md b/docs/_docs/internals/coverage.md new file mode 100644 index 000000000000..162aa182a1e0 --- /dev/null +++ b/docs/_docs/internals/coverage.md @@ -0,0 +1,37 @@ +--- +layout: doc-page +title: "Code Coverage for Scala 3" +--- + +## Instrument code for coverage analysis + +[PR#13880](https://github.com/lampepfl/dotty/pull/13880) has implemented code coverage support for Dotty. +In general, code coverage "instruments" the program at compile time: code is inserted to record which statement are called. This does not change the behavior of the program. Also, a list of all the coverable statements is produced. + +To use this feature, add the compile option `-coverage-out:DIR`, where `DIR` is the destination of the measurement files. + +You can also set `-sourceroot:PATHS_ROOT` to customize how the path of your source files are resolved. +Note that `-sourceroot` also sets the root path of the SemanticDB files. + +## Details: how the code is instrumented + +When the `-coverage-out` option is set, a new phase `instrumentCoverage` runs, just before `firstTransform`. +For a carefully selected list of tree types, it adds a call to `scala.runtime.Invoker.invoked(statementId, DIR)`. + +For instance, this code: +``` +def method() = + println(f()) +``` + +with `-coverage-out:target/cov` be turned to +``` +def method() = + Invoker.invoked(2, "target/cov") + println({ + Invoker.invoked(1, "target/cov") + f() + }) +``` + +At the end of the phase, the list of all the instrumented statements is serialized to the file `DIR/scoverage.coverage`. diff --git a/docs/_docs/usage/coverage.md b/docs/_docs/usage/coverage.md deleted file mode 100644 index 2e24b08ea29e..000000000000 --- a/docs/_docs/usage/coverage.md +++ /dev/null @@ -1,61 +0,0 @@ ---- -layout: doc-page -title: "Code Coverage for Scala 3" ---- - -## Instrument code for coverage analysis - -[PR#13880](https://github.com/lampepfl/dotty/pull/13880) has implemented code coverage support for Dotty. -In general, code coverage works in three steps: -1. The program is "instrumented" at compilation time: code is inserted to record which statement are called. This does not change the behavior of the program. Also, a list of all the coverable statements is produced. -2. The program is run, usually by unit tests, and the instrumentation code saves its measurements. -3. Some tool processes the data to generate a fancy coverage report, for instance a web page. - -In Scala 2, all these steps were performed by external tools. In particular, step 1 was implemented by a compiler plugin. - -In Scala 3, the compiler itself takes care of step 1. To use this feature, add the compile option `-coverage-out:DIR`, where `DIR` is the destination of the measurement files. - -You can also set `-sourceroot:PATHS_ROOT` to customize how the path of your source files are resolved. -Note that `-sourceroot` also sets the root path of the SemanticDB files. - -## How-to with sbt - -For now, the Scoverage sbt plugin doesn't apply the above options automatically. -However, you can easily do it yourself, and use the plugin to generate user-friendly reports. - -1. Add the scoverage sbt plugin by appending this line to your `project/plugins.sbt` -```scala -addSbtPlugin("org.scoverage" % "sbt-scoverage" % "2.0.0-M4") -``` - -2. Compile your project with -```scala -Compile/compile/scalacOptions += - s"-coverage-out:target/scala-${scalaVersion.value}/scoverage-data" -``` - -2. Run the tests: `sbt test` -3. Generate xml and html reports: `sbt coverageReport` - -## Details: how the code is instrumented - -When the `-coverage-out` option is set, a new phase `instrumentCoverage` runs, just before `firstTransform`. -For a carefully selected list of tree types, it adds a call to `scala.runtime.Invoker.invoked(statementId, DIR)`. - -For instance, this code: -``` -def method() = - println(f()) -``` - -with `-coverage-out:target/cov` be turned to -``` -def method() = - Invoker.invoked(2, "target/cov") - println({ - Invoker.invoked(1, "target/cov") - f() - }) -``` - -At the end of the phase, the list of all the instrumented statements is serialized to the file `DIR/scoverage.coverage`. diff --git a/docs/sidebar.yml b/docs/sidebar.yml index e3d496822003..e5491331937f 100644 --- a/docs/sidebar.yml +++ b/docs/sidebar.yml @@ -194,5 +194,6 @@ subsection: - page: internals/dotty-internals-1-notes.md - page: internals/debug-macros.md - page: internals/gadts.md + - page: internals/coverage.md - page: release-notes-0.1.2.md hidden: true