Skip to content

Commit ff74c24

Browse files
wldehAbduqodiri Qurbonzoda
wldeh
and
Abduqodiri Qurbonzoda
authored
Improve tasks-overview.md (#141)
Co-authored-by: Abduqodiri Qurbonzoda <[email protected]>
1 parent a5eb72a commit ff74c24

File tree

1 file changed

+52
-33
lines changed

1 file changed

+52
-33
lines changed

‎docs/tasks-overview.md

Lines changed: 52 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -1,45 +1,64 @@
1-
# Overview of Tasks for kotlinx-benchmark Plugin Across Different Platforms
1+
## Overview of Tasks Provided by kotlinx-benchmark Gradle Plugin
22

3-
This document describes the tasks generated by the kotlinx-benchmark plugin when used with different Kotlin and JVM platforms. Understanding these tasks can help you utilize them more effectively in your benchmarking projects. The tasks are divided into two categories: those that apply to all targets, and those that are target-specific.
3+
The kotlinx-benchmark plugin creates different Gradle tasks depending on how it is configured.
4+
For each pair of configuration profile and registered target a task is created to execute that profile on the respective platform.
5+
To learn more about configuration profiles, refer to [configuration-options.md](configuration-options.md).
46

5-
## General Tasks
7+
### Example Configuration
68

7-
These tasks are not platform-dependent and thus, are used across all targets.
9+
To illustrate, consider the following `kotlinx-benchmark` configuration:
810

9-
| Task | Description |
10-
| ---------------------- | -------------------------------------------------------------------------------------------------------------------- |
11-
| **assembleBenchmarks** | Generates and builds all benchmarks in the project, serving as a dependency for other benchmark tasks. |
12-
| **benchmark** | Executes all benchmarks in the project. It depends on `assembleBenchmarks` to ensure benchmarks are ready and built. |
11+
```kotlin
12+
// build.gradle.kts
13+
benchmark {
14+
configurations {
15+
named("main") {
16+
iterations = 20
17+
warmups = 20
18+
iterationTime = 1
19+
iterationTimeUnit = "s"
20+
}
21+
register("smoke") {
22+
include("Essential")
23+
iterations = 10
24+
warmups = 10
25+
iterationTime = 200
26+
iterationTimeUnit = "ms"
27+
}
28+
}
1329

14-
## Java & Kotlin/JVM Specific Tasks
30+
targets {
31+
register("jvm")
32+
register("js")
33+
}
34+
}
35+
```
1536

16-
| Task | Description |
17-
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
18-
| **{configName}Benchmark** | Executes all benchmarks under the specific configuration. Useful when different benchmarking requirements exist for different parts of the application. |
19-
| **{configName}BenchmarkGenerate** | Generates JMH source files for the specified configuration. |
20-
| **{configName}BenchmarkCompile** | Compiles the JMH source files generated for a specific configuration, transforming them into machine code for JVM execution. |
21-
| **{configName}BenchmarkJar** | Packages the compiled JMH files into a JAR (Java Archive) file for distribution and execution. |
37+
## Tasks for the "main" Configuration Profile
2238

23-
## Kotlin/JS Specific Tasks
39+
- **`benchmark`**:
40+
- Runs benchmarks within the "main" profile for all registered targets.
41+
- In our example, `benchmark` runs benchmarks within the "main" profile in both `jvm` and `js` targets.
2442

25-
| Task | Description |
26-
| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
27-
| **compile{configName}BenchmarkKotlin{configName}** | Compiles JS benchmark source files for the specified JS target. This includes setting up dependencies and setting up Kotlin compilation options. |
28-
| **{configName}Benchmark** | Executes all benchmarks for the specified JS target. |
29-
| **{configName}BenchmarkGenerate** | Generates JS source files for the specified JS target. These source files will be used in the benchmarking process. |
43+
- **`<targetName>Benchmark`**:
44+
- Runs benchmarks within the "main" profile for a particular target.
45+
- In our example, `jvmBenchmark` runs benchmarks within the "main" profile in the `jvm` target, while `jsBenchmark` runs them in the `js` target.
3046

31-
## Kotlin/WASM Specific Tasks
47+
## Tasks for Custom Configuration Profiles
3248

33-
| Task | Description |
34-
| -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
35-
| **compile{configName}BenchmarkKotlin{configName}** | Compiles Wasm benchmark source files for the specified Wasm target. This includes setting up dependencies and compiling the benchmarking code. |
36-
| **{configName}Benchmark** | Executes all benchmarks for the specified Wasm target. |
37-
| **{configName}BenchmarkGenerate** | Generates Wasm source files for the specified Wasm target. These source files will be used in the benchmarking process. |
49+
- **`<configName>Benchmark`**:
50+
- Runs benchmarks within `<configName>` profile in all registered targets.
51+
- In our example, `smokeBenchmark` runs benchmarks within the "smoke" profile.
3852

39-
## Kotlin/Native Specific Tasks
53+
- **`<targetName><configName>Benchmark`**:
54+
- Runs benchmarks within `<configName>` profile in `<targetName>` target.
55+
- In our example, `jvmSmokeBenchmark` runs benchmarks within the "smoke" profile in `jvm` target while `jsSmokeBenchmark` runs them in `js` target.
4056

41-
| Task | Description |
42-
| ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
43-
| **link{configName}BenchmarkReleaseExecutable{configName}** | Compiles the generated files and creates an executable. The entry point for the executable is the generated main function. |
44-
| **{configName}Benchmark** | Executes the benchmarks for each benchmark configuration defined in the plugin extension corresponding to the specific config. For the "main" configuration, `configName` is dropped. |
45-
| **{configName}BenchmarkGenerate** | Takes compiled user code, retrieves metadata and generates the code needed for measurement. This is a native-target-specific task (e.g., for `macosX64()`, `native` -> `macosX64`). |
57+
## Other useful tasks
58+
59+
- **`<targetName>BenchmarkJar`**:
60+
- Created only when a Kotlin/JVM target is registered for benchmarking.
61+
- Produces a self-contained executable JAR in `build/benchmarks/<targetName>/jars/` directory of your project that contains your benchmarks in `<targetName>` target, and all essential JMH infrastructure code.
62+
- The JAR file can be run using `java -jar path-to-the.jar` command with relevant options. Run with `-h` to see the available options.
63+
- The Jar file can be used for running JMH profilers
64+
- In our example, `jvmBenchmarkJar` produces a JAR file in `build/benchmarks/jvm/jars/` directory that contains benchmarks in `jvm` target.

0 commit comments

Comments
 (0)