Skip to content

Commit 73f1015

Browse files
wldehAbduqodiri Qurbonzoda
wldeh
authored and
Abduqodiri Qurbonzoda
committed
docs: add READMEs to examples
1 parent 7a2417a commit 73f1015

File tree

5 files changed

+265
-0
lines changed

5 files changed

+265
-0
lines changed

‎examples/README.md

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
# kotlinx-benchmark Examples Guide
2+
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.
11+
12+
## Getting Started
13+
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:
21+
22+
```
23+
cd kotlinx-benchmark/examples
24+
```
25+
26+
## Running the Examples
27+
28+
Each example is a separate project that can be built and run independently. Here's how you can do it:
29+
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:
31+
32+
```
33+
cd kotlin-kts
34+
```
35+
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:
37+
38+
```
39+
gradle build
40+
```
41+
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.
49+
50+
## Troubleshooting
51+
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).
58+
59+
Happy benchmarking!

‎examples/java/README.md

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
# Java Example
2+
3+
[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/Kotlin/kotlinx-benchmark)
4+
5+
## Project Structure
6+
7+
Inside of this example, you'll see the following folders and files:
8+
9+
```
10+
/
11+
├── build.gradle
12+
└── src/
13+
└── main/
14+
└── java/
15+
└── test/
16+
└── SampleJavaBenchmark.java
17+
```
18+
19+
## Tasks
20+
21+
All tasks can be run from the root of the project, from a terminal:
22+
23+
| Task Name | Action |
24+
| --- | --- |
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 |
33+
34+
## Want to learn more?
35+
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: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
# Kotlin-KTS Example
2+
3+
[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/Kotlin/kotlinx-benchmark)
4+
5+
## Project Structure
6+
7+
Inside of this example, you'll see the following folders and files:
8+
9+
```
10+
/
11+
├── build.gradle.kts
12+
└── main/
13+
└── src/
14+
└── KtsTestBenchmark.kt
15+
```
16+
17+
## Tasks
18+
19+
All tasks can be run from the root of the project, from a terminal:
20+
21+
| Task Name | Action |
22+
| --- | --- |
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' |
29+
30+
## Want to learn more?
31+
32+
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-multiplatform/README.md

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
# Kotlin-Multiplatform Example
2+
3+
[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/Kotlin/kotlinx-benchmark)
4+
5+
## Project Structure
6+
7+
Inside of this example, you'll see the following folders and files:
8+
9+
```
10+
│ build.gradle ==> Build configuration file for Gradle
11+
│
12+
└───src ==> Source code root
13+
├───commonMain ==> Shared code
14+
│ └───kotlin
15+
│ │ CommonBenchmark.kt ==> Common benchmarks
16+
│ │ InheritedBenchmark.kt ==> Inherited benchmarks
17+
│ │ ParamBenchmark.kt ==> Parameterized benchmarks
18+
│ │
19+
│ └───nested ==> Nested benchmarks
20+
│ CommonBenchmark.kt
21+
│
22+
├───jsMain ==> JavaScript-specific code
23+
│ └───kotlin
24+
│ JsAsyncBenchmarks.kt ==> JS async benchmarks
25+
│ JsTestBenchmark.kt ==> JS benchmarks
26+
│
27+
├───jvmBenchmark ==> JVM-specific benchmarks
28+
│ └───kotlin
29+
│ JvmBenchmark.kt
30+
│
31+
├───jvmMain ==> JVM-specific code
32+
│ └───kotlin
33+
│ JvmTestBenchmark.kt ==> JVM benchmarks
34+
│
35+
├───nativeMain ==> Native-specific code
36+
│ └───kotlin
37+
│ NativeTestBenchmark.kt ==> Native benchmarks
38+
│
39+
└───wasmMain ==> WebAssembly-specific code
40+
└───kotlin
41+
WasmTestBenchmark.kt ==> WebAssembly benchmarks
42+
```
43+
44+
## Tasks
45+
46+
All tasks can be run from the root of the project, from a terminal:
47+
48+
| Task Name | Action |
49+
| --- | --- |
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 |
100+
101+
## Want to learn more?
102+
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: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# Kotlin Example
2+
3+
[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/Kotlin/kotlinx-benchmark)
4+
5+
## Project Structure
6+
7+
Inside of this example, you'll see the following folders and files:
8+
9+
```
10+
/
11+
├── build.gradle
12+
├── benchmarks/
13+
│ └── src/
14+
│ └── TestBenchmark.kt
15+
└── main/
16+
└── src/
17+
└── TestData.kt
18+
```
19+
20+
## Tasks
21+
22+
All tasks can be run from the root of the project, from a terminal:
23+
24+
| Task Name | Action |
25+
| --- | --- |
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' |
32+
33+
## Want to learn more?
34+
35+
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.

0 commit comments

Comments
 (0)