Skip to content

Commit c363089

Browse files
shanshinsandwwraithqwwdfsad
authored
Improved Kover documentation
PR #369 Co-authored-by: Leonid Startsev <sandwwraith@users.noreply.github.com> Co-authored-by: Vsevolod Tolstopyatov <qwwdfsad@gmail.com>
1 parent 3afb354 commit c363089

File tree

171 files changed

+1309
-2226
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

171 files changed

+1309
-2226
lines changed

‎README.md

+22-351
Large diffs are not rendered by default.

‎api/kover-gradle-plugin.api

+2-3
Original file line numberDiff line numberDiff line change
@@ -195,9 +195,8 @@ public abstract interface class kotlinx/kover/gradle/plugin/dsl/KoverProjectExte
195195
public fun instrumentation (Lkotlin/jvm/functions/Function1;)V
196196
public fun isDisabled ()Z
197197
public fun setEngine (Ljava/lang/Void;)V
198-
public abstract fun useJacocoTool ()V
199-
public abstract fun useJacocoTool (Ljava/lang/String;)V
200-
public abstract fun useKoverTool ()V
198+
public abstract fun useJacoco ()V
199+
public abstract fun useJacoco (Ljava/lang/String;)V
201200
public fun verify (Lkotlin/jvm/functions/Function0;)V
202201
public fun xmlReport (Lkotlin/jvm/functions/Function0;)V
203202
}

‎build.gradle.kts

+1-1
Original file line numberDiff line numberDiff line change
@@ -120,7 +120,7 @@ tasks.withType<KotlinCompile>().configureEach {
120120

121121
tasks.dokkaHtml {
122122
moduleName.set("Kover Gradle Plugin")
123-
outputDirectory.set(layout.projectDirectory.dir("docs/dokka").asFile)
123+
outputDirectory.set(layout.projectDirectory.dir("docs/gradle-plugin/dokka").asFile)
124124
dokkaSourceSets.configureEach {
125125
// source set configuration section
126126
perPackageOption {

‎docs/_config.yml

+12
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
remote_theme: pages-themes/slate@v0.2.0
2+
lsi: false
3+
safe: true
4+
source: /
5+
highlighter: rouge
6+
incremental: false
7+
gist:
8+
noscript: false
9+
kramdown:
10+
input: GFM
11+
hard_wrap: false
12+
syntax_highlighter: rouge

‎docs/assets/css/style.scss

+16
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
---
2+
---
3+
4+
@import "{{ site.theme }}";
5+
.inner{max-width:1280px;}
6+
#project_title {
7+
visibility: hidden;
8+
position: relative;
9+
}
10+
#project_title:after {
11+
visibility: visible;
12+
position: absolute;
13+
top: 0;
14+
left: 0;
15+
content: "Kover - Kotlin Coverage Tool";
16+
}

‎docs/cli/index.md

+148
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,148 @@
1+
# Kover Command Line Interface
2+
3+
This single jar artifact allows using some of the functionality of Kover Toolset through command-line calls.
4+
5+
Java 1.6 or higher is required for execution.
6+
7+
## Commands
8+
9+
### Offline instrumentation
10+
11+
For information about offline instrumentation, [see](#offline-instrumentation-1).
12+
13+
`java -jar kover-cli.jar instrument [<class-file-path> ...] --dest <dir> [--exclude <class-name>] [--excludeAnnotation <annotation-name>] [--hits] [--include <class-name>]`
14+
15+
| Option | Description | Required | Multiple |
16+
|---------------------------------------|----------------------------------------------------------------------------------------------------------------------------|:--------:|:--------:|
17+
| `<class-file-path>` | list of the compiled class-files roots | + | + |
18+
| --dest <dir> | path to write instrumented Java classes to | + | |
19+
| --exclude <class-name> | filter to exclude classes from instrumentation, wildcards `*` and `?` are acceptable. Excludes have priority over includes | | + |
20+
| --excludeAnnotation <annotation-name> | filter to exclude annotated classes from instrumentation, wildcards `*` and `?` are acceptable | | + |
21+
| --hits | a flag to enable line hits counting | | |
22+
| --include <class-name> | instrument only specified classes, wildcards `*` and `?` are acceptable | | + |
23+
24+
### Generating reports
25+
Allows you to generate HTML and XML reports from the existing binary report.
26+
27+
`java -jar kover-cli.jar report [<binary-report-path> ...] --classfiles <class-file-path> [--exclude <class-name>] [--excludeAnnotation <annotation-name>] [--html <html-dir>] [--include <class-name>] --src <sources-path> [--title <html-title>] [--xml <xml-file-path>]`
28+
29+
| Option | Description | Required | Multiple |
30+
|---------------------------------------|---------------------------------------------------------------------------------------------------------|:--------:|:--------:|
31+
| `<binary-report-path>` | list of binary reports files | | + |
32+
| --classfiles <class-file-path> | location of the compiled class-files root (must be original and not instrumented) | + | + |
33+
| --exclude <class-name> | filter to exclude classes, wildcards `*` and `?` are acceptable | | + |
34+
| --excludeAnnotation <annotation-name> | filter to exclude classes and functions marked by this annotation, wildcards `*` and `?` are acceptable | | + |
35+
| --html <html-dir> | generate a HTML report in the specified path | | |
36+
| --include <class-name> | filter to include classes, wildcards `*` and `?` are acceptable | | + |
37+
| --src <sources-path> | location of the source files root | + | + |
38+
| --title <html-title> | title in the HTML report | | |
39+
| --xml <xml-file-path> | generate a XML report in the specified path | | |
40+
41+
## Offline instrumentation
42+
43+
Offline instrumentation is suitable when using runtime environments that do not support Java agents.
44+
It instruments the files located in the file system and saves the result to the specified directory.
45+
46+
To run classes instrumented offline, you need to add `org.jetbrains.kotlinx:kover-offline` artifact to the application's classpath.
47+
48+
You also need to pass the system property `kover.offline.report.path` to the application with the path where you want binary report to be saved.
49+
50+
Also see [Gradle example](#gradle-example)
51+
52+
## Examples
53+
54+
### Gradle example
55+
Example of custom using Kover tool CLI in Gradle
56+
```
57+
plugins {
58+
kotlin("jvm") version "1.8.0"
59+
application
60+
}
61+
62+
repositories {
63+
mavenCentral()
64+
}
65+
66+
configurations.register("koverCli") {
67+
isVisible = false
68+
isCanBeConsumed = false
69+
isTransitive = true
70+
isCanBeResolved = true
71+
}
72+
73+
dependencies {
74+
runtimeOnly("org.jetbrains.kotlinx:kover-offline-runtime:0.7.0-Beta")
75+
add("koverCli", "org.jetbrains.kotlinx:kover-cli:0.7.0-Beta")
76+
77+
testImplementation(kotlin("test"))
78+
}
79+
80+
tasks.test {
81+
useJUnitPlatform()
82+
}
83+
84+
kotlin {
85+
jvmToolchain(11)
86+
}
87+
88+
fun cliJar(): File {
89+
val cliConfig = configurations.getByName("koverCli")
90+
return cliConfig.filter {it.name.startsWith("kover-cli")}.singleFile
91+
}
92+
93+
tasks.compileKotlin {
94+
doLast {
95+
val outputDir = destinationDirectory.get().asFile
96+
97+
exec {
98+
commandLine(
99+
"java",
100+
"-jar",
101+
cliJar().canonicalPath,
102+
"instrument",
103+
outputDir,
104+
"--dest",
105+
outputDir,
106+
"--hits",
107+
)
108+
}
109+
}
110+
}
111+
112+
val binaryReport = layout.buildDirectory.file("kover/report.ic").get().asFile
113+
114+
tasks.test {
115+
// set system property for binary report path
116+
systemProperty("kover.offline.report.path", binaryReport.absolutePath)
117+
}
118+
119+
tasks.register("koverReport") {
120+
dependsOn(tasks.test)
121+
122+
doLast {
123+
val args = mutableListOf<String>()
124+
125+
args += "java"
126+
args += "-jar"
127+
args += cliJar().canonicalPath
128+
args += "report"
129+
args += binaryReport.absolutePath
130+
args += "--classfiles"
131+
args += tasks.compileKotlin.get().destinationDirectory.get().asFile.absolutePath
132+
args += "--classfiles"
133+
args += tasks.compileJava.get().destinationDirectory.get().asFile.absolutePath
134+
args += "--xml"
135+
args += layout.buildDirectory.file("reports/kover/report.xml").get().asFile.absolutePath
136+
args += "--html"
137+
args += layout.buildDirectory.file("reports/kover/html").get().asFile.absolutePath
138+
139+
sourceSets.main.get().kotlin.sourceDirectories.files.forEach { src ->
140+
args += "--src"
141+
args += src.canonicalPath
142+
}
143+
144+
exec { commandLine(args) }
145+
}
146+
}
147+
148+
```

‎docs/dokka/-kover -gradle -plugin/kotlinx.kover.gradle.plugin.dsl/-kover-android-extension/index.html

-111
This file was deleted.

0 commit comments

Comments
 (0)