Skip to content

Commit 679c5c4

Browse files
wldehAbduqodiri Qurbonzoda
wldeh
authored and
Abduqodiri Qurbonzoda
committed
docs: improve descriptions and setup steps
1 parent 10e524e commit 679c5c4

File tree

5 files changed

+90
-114
lines changed

5 files changed

+90
-114
lines changed

‎examples/README.md

Lines changed: 16 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -1,59 +1,35 @@
11
# kotlinx-benchmark Examples Guide
22

3-
This guide is designed to help you navigate, set up, and run the benchmark examples provided here. Whether you're a seasoned developer or new to Kotlin and benchmarking, we've got you covered. Let's dive in and explore these practical examples together.
4-
5-
## Prerequisites
6-
7-
Before you begin, ensure you have the following installed on your local machine:
8-
9-
- Git: Used to clone the repository. You can download it from [here](https://git-scm.com/downloads).
10-
- Gradle: Used to build the projects. You can download it from [here](https://gradle.org/install/). Note that the projects come with a Gradle wrapper, so this is optional.
3+
This guide is specifically designed for experienced Kotlin developers. It aims to help you smoothly navigate and run the benchmark examples included in this repository.
114

125
## Getting Started
136

14-
1. **Clone the Repository**: Clone the `kotlinx-benchmark` repository to your local machine by running the following command in your terminal:
15-
16-
```
17-
git clone https://github.com/Kotlin/kotlinx-benchmark.git
18-
```
19-
20-
2. **Navigate to the Examples Directory**: Once the repository is cloned, navigate to the `examples` directory by running:
7+
To begin, you'll need to clone the `kotlinx-benchmark` repository to your local machine:
218

22-
```
23-
cd kotlinx-benchmark/examples
24-
```
9+
```
10+
git clone https://github.com/Kotlin/kotlinx-benchmark.git
11+
```
2512

2613
## Running the Examples
2714

28-
Each example is a separate project that can be built and run independently. Here's how you can do it:
15+
Each example in this repository is an autonomous project, encapsulated in its own environment. Reference the [tasks-overview](../docs/tasks-overview.md) for a detailed list and explanation of available tasks.
2916

30-
1. **Navigate to the Example Directory**: Navigate to the directory of the example you want to run. For instance, if you want to run the `kotlin-kts` example, you would run:
17+
To execute all benchmarks for a specific example, you'll use the following command structure:
3118

32-
```
33-
cd kotlin-kts
34-
```
19+
```
20+
./gradlew :examples:[example-name]:benchmark
21+
```
3522

36-
2. **Build the Project**: Each project uses Gradle as a build tool. If you have Gradle installed on your machine, you can build the project by running:
23+
Here, `[example-name]` is the name of the example you wish to benchmark. For instance, to run benchmarks for the `kotlin-kts` example, the command would be:
3724

38-
```
39-
gradle build
40-
```
25+
```
26+
./gradlew :examples:kotlin-kts:benchmark
27+
```
4128

42-
3. **Run the Benchmark**: After the project is built, you can run the benchmark by executing:
43-
44-
```
45-
gradle benchmark
46-
```
47-
48-
Repeat these steps for each example you want to run.
29+
This pattern applies to all examples in the repository.
4930

5031
## Troubleshooting
5132

52-
If you encounter any issues while setting up or running the examples, please check the following:
53-
54-
- Ensure you have all the prerequisites installed and they are added to your system's PATH.
55-
- Make sure you are running the commands in the correct directory.
56-
57-
If you're still having issues, feel free to open an issue on the [kotlinx-benchmark repository](https://github.com/Kotlin/kotlinx-benchmark/issues).
33+
In case of any issues encountered while setting up or running the benchmarks, verify that you're executing commands from the correct directory. For persisting issues, don't hesitate to open an [issue](https://github.com/Kotlin/kotlinx-benchmark/issues).
5834

5935
Happy benchmarking!

‎examples/java/README.md

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -18,19 +18,19 @@ Inside of this example, you'll see the following folders and files:
1818

1919
## Tasks
2020

21-
All tasks can be run from the root of the project, from a terminal:
21+
All tasks can be run from the root of the library:
2222

2323
| Task Name | Action |
2424
| --- | --- |
25-
| `gradle assembleBenchmarks` | Generate and build all benchmarks in the project |
26-
| `gradle benchmark` | Execute all benchmarks in the project |
27-
| `gradle mainBenchmark` | Execute benchmark for 'main' |
28-
| `gradle mainBenchmarkCompile` | Compile JMH source files for 'main' |
29-
| `gradle mainBenchmarkGenerate` | Generate JMH source files for 'main' |
30-
| `gradle mainBenchmarkJar` | Build JAR for JMH compiled files for 'main' |
31-
| `gradle mainSingleParamBenchmark` | Execute benchmark for 'main' |
32-
| `gradle singleParamBenchmark` | Execute all benchmarks in the project |
25+
| `assembleBenchmarks` | Generate and build all benchmarks in the project |
26+
| `benchmark` | Execute all benchmarks in the project |
27+
| `mainBenchmark` | Execute benchmark for the 'main' source set |
28+
| `mainBenchmarkCompile` | Compile JMH source files for the 'main' source set |
29+
| `mainBenchmarkGenerate` | Generate JMH source files for the 'main' source set |
30+
| `mainBenchmarkJar` | Build JAR for JMH compiled files for the 'main' source set |
31+
| `mainSingleParamBenchmark` | Execute benchmark for the 'main' source set with the 'singleParam' configuration |
32+
| `singleParamBenchmark` | Execute all benchmarks in the project with the 'singleParam' configuration |
3333

3434
## Want to learn more?
3535

36-
Feel free to engage in benchmarking discussions on the `#benchmarks` channel on [Kotlinlang Slack](https://kotlinlang.org/community/slack), explore the `kotlinx-benchmark` tagged questions on [Stack Overflow](https://stackoverflow.com/questions/tagged/kotlinx-benchmark), or dive into the [kotlinx-benchmark Github Discussions](https://github.com/Kotlin/kotlinx-benchmark/discussions) for more insights and interactions.
36+
Feel free to engage in benchmarking discussions on the `#benchmarks` channel on [Kotlinlang Slack](https://kotlinlang.org/community/slack), explore the `kotlinx-benchmark` tagged questions on [Stack Overflow](https://stackoverflow.com/questions/tagged/kotlinx-benchmark), or dive into the [kotlinx-benchmark Github Discussions](https://github.com/Kotlin/kotlinx-benchmark/discussions) for more insights and interactions.

‎examples/kotlin-kts/README.md

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -20,12 +20,12 @@ All tasks can be run from the root of the project, from a terminal:
2020

2121
| Task Name | Action |
2222
| --- | --- |
23-
| `gradle assembleBenchmarks` | Generate and build all benchmarks in the project |
24-
| `gradle benchmark` | Execute all benchmarks in the project |
25-
| `gradle mainBenchmark` | Execute benchmark for 'benchmarks' |
26-
| `gradle mainBenchmarkCompile` | Compile JMH source files for 'benchmarks' |
27-
| `gradle mainBenchmarkGenerate` | Generate JMH source files for 'benchmarks' |
28-
| `gradle mainBenchmarkJar` | Build JAR for JMH compiled files for 'benchmarks' |
23+
| `assembleBenchmarks` | Generate and build all benchmarks in the project |
24+
| `benchmark` | Execute all benchmarks in the project |
25+
| `mainBenchmark` | Execute benchmark for 'benchmarks' |
26+
| `mainBenchmarkCompile` | Compile JMH source files for 'benchmarks' |
27+
| `mainBenchmarkGenerate` | Generate JMH source files for 'benchmarks' |
28+
| `mainBenchmarkJar` | Build JAR for JMH compiled files for 'benchmarks' |
2929

3030
## Want to learn more?
3131

‎examples/kotlin-multiplatform/README.md

Lines changed: 52 additions & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -43,61 +43,61 @@ Inside of this example, you'll see the following folders and files:
4343

4444
## Tasks
4545

46-
All tasks can be run from the root of the project, from a terminal:
46+
All tasks can be run from the root of the library, from a terminal:
4747

4848
| Task Name | Action |
4949
| --- | --- |
50-
| `gradle assembleBenchmarks` | Generate and build all benchmarks in the project |
51-
| `gradle benchmark` | Execute all benchmarks in the project |
52-
| `gradle compileJsIrBenchmarkKotlinJsIr` | Compile JS benchmark source files for 'jsIr' |
53-
| `gradle compileJsIrBuiltInBenchmarkKotlinJsIrBuiltIn` | Compile JS benchmark source files for 'jsIrBuiltIn' |
54-
| `gradle compileWasmBenchmarkKotlinWasm` | Compile Wasm benchmark source files for 'wasm' |
55-
| `gradle csvBenchmark` | Execute all benchmarks in a project |
56-
| `gradle fastBenchmark` | Execute all benchmarks in a project |
57-
| `gradle forkBenchmark` | Execute all benchmarks in a project |
58-
| `gradle jsIrBenchmark` | Executes benchmark for 'jsIr' with NodeJS |
59-
| `gradle jsIrBenchmarkGenerate` | Generate JS source files for 'jsIr' |
60-
| `gradle jsIrBuiltInBenchmark` | Executes benchmark for 'jsIrBuiltIn' with NodeJS |
61-
| `gradle jsIrBuiltInBenchmarkGenerate` | Generate JS source files for 'jsIrBuiltIn' |
62-
| `gradle jsIrBuiltInCsvBenchmark` | Executes benchmark for 'jsIrBuiltIn' with NodeJS |
63-
| `gradle jsIrBuiltInFastBenchmark` | Executes benchmark for 'jsIrBuiltIn' with NodeJS |
64-
| `gradle jsIrBuiltInForkBenchmark` | Executes benchmark for 'jsIrBuiltIn' with NodeJS |
65-
| `gradle jsIrBuiltInParamsBenchmark` | Executes benchmark for 'jsIrBuiltIn' with NodeJS |
66-
| `gradle jsIrCsvBenchmark` | Executes benchmark for 'jsIr' with NodeJS |
67-
| `gradle jsIrFastBenchmark` | Executes benchmark for 'jsIr' with NodeJS |
68-
| `gradle jsIrForkBenchmark` | Executes benchmark for 'jsIr' with NodeJS |
69-
| `gradle jsIrParamsBenchmark` | Executes benchmark for 'jsIr' with NodeJS |
70-
| `gradle jvmBenchmark` | Execute benchmark for 'jvm' |
71-
| `gradle jvmBenchmarkBenchmark` | Execute benchmark for 'jvmBenchmark' |
72-
| `gradle jvmBenchmarkBenchmarkCompile` | Compile JMH source files for 'jvmBenchmark' |
73-
| `gradle jvmBenchmarkBenchmarkGenerate` | Generate JMH source files for 'jvmBenchmark' |
74-
| `gradle jvmBenchmarkBenchmarkJar` | Build JAR for JMH compiled files for 'jvmBenchmark' |
75-
| `gradle jvmBenchmarkCompile` | Compile JMH source files for 'jvm' |
76-
| `gradle jvmBenchmarkCsvBenchmark` | Execute benchmark for 'jvmBenchmark' |
77-
| `gradle jvmBenchmarkFastBenchmark` | Execute benchmark for 'jvmBenchmark' |
78-
| `gradle jvmBenchmarkForkBenchmark` | Execute benchmark for 'jvmBenchmark' |
79-
| `gradle jvmBenchmarkGenerate` | Generate JMH source files for 'jvm' |
80-
| `gradle jvmBenchmarkJar` | Build JAR for JMH compiled files for 'jvm' |
81-
| `gradle jvmBenchmarkParamsBenchmark` | Execute benchmark for 'jvmBenchmark' |
82-
| `gradle jvmCsvBenchmark` | Execute benchmark for 'jvm' |
83-
| `gradle jvmFastBenchmark` | Execute benchmark for 'jvm' |
84-
| `gradle jvmForkBenchmark` | Execute benchmark for 'jvm' |
85-
| `gradle jvmParamsBenchmark` | Execute benchmark for 'jvm' |
86-
| `gradle linkNativeBenchmarkReleaseExecutableNative` | Compile Native benchmark source files for 'native' |
87-
| `gradle nativeBenchmark` | Executes benchmark for 'native' |
88-
| `gradle nativeBenchmarkGenerate` | Generate Native source files for 'native' |
89-
| `gradle nativeCsvBenchmark` | Executes benchmark for 'native' |
90-
| `gradle nativeFastBenchmark` | Executes benchmark for 'native' |
91-
| `gradle nativeForkBenchmark` | Executes benchmark for 'native' |
92-
| `gradle nativeParamsBenchmark` | Executes benchmark for 'native' |
93-
| `gradle paramsBenchmark` | Execute all benchmarks in a project |
94-
| `gradle wasmBenchmark` | Executes benchmark for 'wasm' with D8 |
95-
| `gradle wasmBenchmarkGenerate` | Generate Wasm source files for 'wasm' |
96-
| `gradle wasmCsvBenchmark` | Executes benchmark for 'wasm' with D8 |
97-
| `gradle wasmFastBenchmark` | Executes benchmark for 'wasm' with D8 |
98-
| `gradle wasmForkBenchmark` | Executes benchmark for 'wasm' with D8 |
99-
| `gradle wasmParamsBenchmark` | Executes benchmark for 'wasm' with D8 |
50+
| `assembleBenchmarks` | Generates and builds all benchmarks in the project. |
51+
| `benchmark` | Executes all benchmarks in the project. |
52+
| `compileJsIrBenchmarkKotlinJsIr` | Compiles the source files for 'jsIr' benchmark. |
53+
| `compileJsIrBuiltInBenchmarkKotlinJsIrBuiltIn` | Compiles the source files for 'jsIrBuiltIn' benchmark. |
54+
| `compileWasmBenchmarkKotlinWasm` | Compiles the source files for 'wasm' benchmark. |
55+
| `csvBenchmark` | Executes all benchmarks in the project with the CSV configuration. |
56+
| `fastBenchmark` | Executes all benchmarks in the project with the Fast configuration. |
57+
| `forkBenchmark` | Executes all benchmarks in the project with the Fork configuration. |
58+
| `jsIrBenchmark` | Executes benchmark for the 'jsIr' source set. |
59+
| `jsIrBenchmarkGenerate` | Generates source files for the 'jsIr' source set. |
60+
| `jsIrBuiltInBenchmark` | Executes benchmark for the 'jsIrBuiltIn' source set. |
61+
| `jsIrBuiltInBenchmarkGenerate` | Generates source files for the 'jsIrBuiltIn' source set. |
62+
| `jsIrBuiltInCsvBenchmark` | Executes benchmark for the 'jsIrBuiltIn' source set with the CSV configuration. |
63+
| `jsIrBuiltInFastBenchmark` | Executes benchmark for the 'jsIrBuiltIn' source set with the Fast configuration. |
64+
| `jsIrBuiltInForkBenchmark` | Executes benchmark for the 'jsIrBuiltIn' source set with the Fork configuration. |
65+
| `jsIrBuiltInParamsBenchmark` | Executes benchmark for the 'jsIrBuiltIn' source set with the Params configuration. |
66+
| `jsIrCsvBenchmark` | Executes benchmark for the 'jsIr' source set with the CSV configuration. |
67+
| `jsIrFastBenchmark` | Executes benchmark for the 'jsIr' source set with the Fast configuration. |
68+
| `jsIrForkBenchmark` | Executes benchmark for the 'jsIr' source set with the Fork configuration. |
69+
| `jsIrParamsBenchmark` | Executes benchmark for the 'jsIr' source set with the Params configuration. |
70+
| `jvmBenchmark` | Executes benchmark for the 'jvm' source set. |
71+
| `jvmBenchmarkBenchmark` | Executes benchmark for the 'jvmBenchmark' source set. |
72+
| `jvmBenchmarkBenchmarkCompile` | Compiles the source files for 'jvmBenchmark'. |
73+
| `jvmBenchmarkBenchmarkGenerate` | Generates source files for the 'jvmBenchmark' source set. |
74+
| `jvmBenchmarkBenchmarkJar` | Builds the JAR for 'jvmBenchmark' compiled files. |
75+
| `jvmBenchmarkCompile` | Compiles the source files for the 'jvm' benchmark. |
76+
| `jvmBenchmarkCsvBenchmark` | Executes benchmark for the 'jvmBenchmark' source set with the CSV configuration. |
77+
| `jvmBenchmarkFastBenchmark` | Executes benchmark for the 'jvmBenchmark' source set with the Fast configuration. |
78+
| `jvmBenchmarkForkBenchmark` | Executes benchmark for the 'jvmBenchmark' source set with the Fork configuration. |
79+
| `jvmBenchmarkGenerate` | Generates source files for the 'jvm' source set. |
80+
| `jvmBenchmarkJar` | Builds the JAR for 'jvm' compiled files. |
81+
| `jvmBenchmarkParamsBenchmark` | Executes benchmark for the 'j| `jvmBenchmarkParamsBenchmark` | Executes benchmark for the 'jvmBenchmark' source set with the Params configuration. |
82+
| `jvmCsvBenchmark` | Executes benchmark for the 'jvm' source set with the CSV configuration. |
83+
| `jvmFastBenchmark` | Executes benchmark for the 'jvm' source set with the Fast configuration. |
84+
| `jvmForkBenchmark` | Executes benchmark for the 'jvm' source set with the Fork configuration. |
85+
| `jvmParamsBenchmark` | Executes benchmark for the 'jvm' source set with the Params configuration. |
86+
| `linkNativeBenchmarkReleaseExecutableNative` | Compiles the source files for 'native' benchmark. |
87+
| `nativeBenchmark` | Executes benchmark for the 'native' source set. |
88+
| `nativeBenchmarkGenerate` | Generates source files for the 'native' source set. |
89+
| `nativeCsvBenchmark` | Executes benchmark for the 'native' source set with the CSV configuration. |
90+
| `nativeFastBenchmark` | Executes benchmark for the 'native' source set with the Fast configuration. |
91+
| `nativeForkBenchmark` | Executes benchmark for the 'native' source set with the Fork configuration. |
92+
| `nativeParamsBenchmark` | Executes benchmark for the 'native' source set with the Params configuration. |
93+
| `paramsBenchmark` | Executes all benchmarks in the project with the Params configuration. |
94+
| `wasmBenchmark` | Executes benchmark for the 'wasm' source set. |
95+
| `wasmBenchmarkGenerate` | Generates source files for the 'wasm' source set. |
96+
| `wasmCsvBenchmark` | Executes benchmark for the 'wasm' source set with the CSV configuration. |
97+
| `wasmFastBenchmark` | Executes benchmark for the 'wasm' source set with the Fast configuration. |
98+
| `wasmForkBenchmark` | Executes benchmark for the 'wasm' source set with the Fork configuration. |
99+
| `wasmParamsBenchmark` | Executes benchmark for the 'wasm' source set with the Params configuration. |
100100

101101
## Want to learn more?
102102

103-
Feel free to engage in benchmarking discussions on the `#benchmarks` channel on [Kotlinlang Slack](https://kotlinlang.org/community/slack), explore the `kotlinx-benchmark` tagged questions on [Stack Overflow](https://stackoverflow.com/questions/tagged/kotlinx-benchmark), or dive into the [kotlinx-benchmark Github Discussions](https://github.com/Kotlin/kotlinx-benchmark/discussions) for more insights and interactions.
103+
Feel free to engage in benchmarking discussions on the `#benchmarks` channel on [Kotlinlang Slack](https://kotlinlang.org/community/slack), explore the `kotlinx-benchmark` tagged questions on [Stack Overflow](https://stackoverflow.com/questions/tagged/kotlinx-benchmark), or dive into the [kotlinx-benchmark Github Discussions](https://github.com/Kotlin/kotlinx-benchmark/discussions) for more insights and interactions.

‎examples/kotlin/README.md

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -23,12 +23,12 @@ All tasks can be run from the root of the project, from a terminal:
2323

2424
| Task Name | Action |
2525
| --- | --- |
26-
| `gradle assembleBenchmarks` | Generate and build all benchmarks in the project |
27-
| `gradle benchmark` | Execute all benchmarks in the project |
28-
| `gradle benchmarksBenchmark` | Execute benchmark for 'benchmarks' |
29-
| `gradle benchmarksBenchmarkCompile` | Compile JMH source files for 'benchmarks' |
30-
| `gradle benchmarksBenchmarkGenerate` | Generate JMH source files for 'benchmarks' |
31-
| `gradle benchmarksBenchmarkJar` | Build JAR for JMH compiled files for 'benchmarks' |
26+
| `assembleBenchmarks` | Generate and build all benchmarks in the project |
27+
| `benchmark` | Execute all benchmarks in the project |
28+
| `benchmarksBenchmark` | Execute benchmark for 'benchmarks' |
29+
| `benchmarksBenchmarkCompile` | Compile JMH source files for 'benchmarks' |
30+
| `benchmarksBenchmarkGenerate` | Generate JMH source files for 'benchmarks' |
31+
| `benchmarksBenchmarkJar` | Build JAR for JMH compiled files for 'benchmarks' |
3232

3333
## Want to learn more?
3434

0 commit comments

Comments
 (0)