Skip to content

Commit

Permalink
docs: improve descriptions and setup steps
Browse files Browse the repository at this point in the history
  • Loading branch information
@wldeh @qurbonzoda
wldeh authored and qurbonzoda committed Jul 7, 2023
1 parent e5cd512 commit e1d7432
Show file tree
Hide file tree
Showing 5 changed files with 90 additions and 114 deletions.
56 changes: 16 additions & 40 deletions examples/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,59 +1,35 @@
# kotlinx-benchmark Examples Guide

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.

## Prerequisites

Before you begin, ensure you have the following installed on your local machine:

- Git: Used to clone the repository. You can download it from [here](https://git-scm.com/downloads).
- 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.
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.

## Getting Started

1. **Clone the Repository**: Clone the `kotlinx-benchmark` repository to your local machine by running the following command in your terminal:

```
git clone https://github.com/Kotlin/kotlinx-benchmark.git
```

2. **Navigate to the Examples Directory**: Once the repository is cloned, navigate to the `examples` directory by running:
To begin, you'll need to clone the `kotlinx-benchmark` repository to your local machine:

```
cd kotlinx-benchmark/examples
```
```
git clone https://github.com/Kotlin/kotlinx-benchmark.git
```

## Running the Examples

Each example is a separate project that can be built and run independently. Here's how you can do it:
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.

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:
To execute all benchmarks for a specific example, you'll use the following command structure:

```
cd kotlin-kts
```
```
./gradlew :examples:[example-name]:benchmark
```

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:
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:

```
gradle build
```
```
./gradlew :examples:kotlin-kts:benchmark
```

3. **Run the Benchmark**: After the project is built, you can run the benchmark by executing:

```
gradle benchmark
```

Repeat these steps for each example you want to run.
This pattern applies to all examples in the repository.

## Troubleshooting

If you encounter any issues while setting up or running the examples, please check the following:

- Ensure you have all the prerequisites installed and they are added to your system's PATH.
- Make sure you are running the commands in the correct directory.

If you're still having issues, feel free to open an issue on the [kotlinx-benchmark repository](https://github.com/Kotlin/kotlinx-benchmark/issues).
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).

Happy benchmarking!
20 changes: 10 additions & 10 deletions examples/java/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,19 +18,19 @@ Inside of this example, you'll see the following folders and files:

## Tasks

All tasks can be run from the root of the project, from a terminal:
All tasks can be run from the root of the library:

| Task Name | Action |
| --- | --- |
| `gradle assembleBenchmarks` | Generate and build all benchmarks in the project |
| `gradle benchmark` | Execute all benchmarks in the project |
| `gradle mainBenchmark` | Execute benchmark for 'main' |
| `gradle mainBenchmarkCompile` | Compile JMH source files for 'main' |
| `gradle mainBenchmarkGenerate` | Generate JMH source files for 'main' |
| `gradle mainBenchmarkJar` | Build JAR for JMH compiled files for 'main' |
| `gradle mainSingleParamBenchmark` | Execute benchmark for 'main' |
| `gradle singleParamBenchmark` | Execute all benchmarks in the project |
| `assembleBenchmarks` | Generate and build all benchmarks in the project |
| `benchmark` | Execute all benchmarks in the project |
| `mainBenchmark` | Execute benchmark for the 'main' source set |
| `mainBenchmarkCompile` | Compile JMH source files for the 'main' source set |
| `mainBenchmarkGenerate` | Generate JMH source files for the 'main' source set |
| `mainBenchmarkJar` | Build JAR for JMH compiled files for the 'main' source set |
| `mainSingleParamBenchmark` | Execute benchmark for the 'main' source set with the 'singleParam' configuration |
| `singleParamBenchmark` | Execute all benchmarks in the project with the 'singleParam' configuration |

## Want to learn more?

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.
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.
12 changes: 6 additions & 6 deletions examples/kotlin-kts/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,12 +20,12 @@ All tasks can be run from the root of the project, from a terminal:

| Task Name | Action |
| --- | --- |
| `gradle assembleBenchmarks` | Generate and build all benchmarks in the project |
| `gradle benchmark` | Execute all benchmarks in the project |
| `gradle mainBenchmark` | Execute benchmark for 'benchmarks' |
| `gradle mainBenchmarkCompile` | Compile JMH source files for 'benchmarks' |
| `gradle mainBenchmarkGenerate` | Generate JMH source files for 'benchmarks' |
| `gradle mainBenchmarkJar` | Build JAR for JMH compiled files for 'benchmarks' |
| `assembleBenchmarks` | Generate and build all benchmarks in the project |
| `benchmark` | Execute all benchmarks in the project |
| `mainBenchmark` | Execute benchmark for 'benchmarks' |
| `mainBenchmarkCompile` | Compile JMH source files for 'benchmarks' |
| `mainBenchmarkGenerate` | Generate JMH source files for 'benchmarks' |
| `mainBenchmarkJar` | Build JAR for JMH compiled files for 'benchmarks' |

## Want to learn more?

Expand Down
104 changes: 52 additions & 52 deletions examples/kotlin-multiplatform/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -43,61 +43,61 @@ Inside of this example, you'll see the following folders and files:

## Tasks

All tasks can be run from the root of the project, from a terminal:
All tasks can be run from the root of the library, from a terminal:

| Task Name | Action |
| --- | --- |
| `gradle assembleBenchmarks` | Generate and build all benchmarks in the project |
| `gradle benchmark` | Execute all benchmarks in the project |
| `gradle compileJsIrBenchmarkKotlinJsIr` | Compile JS benchmark source files for 'jsIr' |
| `gradle compileJsIrBuiltInBenchmarkKotlinJsIrBuiltIn` | Compile JS benchmark source files for 'jsIrBuiltIn' |
| `gradle compileWasmBenchmarkKotlinWasm` | Compile Wasm benchmark source files for 'wasm' |
| `gradle csvBenchmark` | Execute all benchmarks in a project |
| `gradle fastBenchmark` | Execute all benchmarks in a project |
| `gradle forkBenchmark` | Execute all benchmarks in a project |
| `gradle jsIrBenchmark` | Executes benchmark for 'jsIr' with NodeJS |
| `gradle jsIrBenchmarkGenerate` | Generate JS source files for 'jsIr' |
| `gradle jsIrBuiltInBenchmark` | Executes benchmark for 'jsIrBuiltIn' with NodeJS |
| `gradle jsIrBuiltInBenchmarkGenerate` | Generate JS source files for 'jsIrBuiltIn' |
| `gradle jsIrBuiltInCsvBenchmark` | Executes benchmark for 'jsIrBuiltIn' with NodeJS |
| `gradle jsIrBuiltInFastBenchmark` | Executes benchmark for 'jsIrBuiltIn' with NodeJS |
| `gradle jsIrBuiltInForkBenchmark` | Executes benchmark for 'jsIrBuiltIn' with NodeJS |
| `gradle jsIrBuiltInParamsBenchmark` | Executes benchmark for 'jsIrBuiltIn' with NodeJS |
| `gradle jsIrCsvBenchmark` | Executes benchmark for 'jsIr' with NodeJS |
| `gradle jsIrFastBenchmark` | Executes benchmark for 'jsIr' with NodeJS |
| `gradle jsIrForkBenchmark` | Executes benchmark for 'jsIr' with NodeJS |
| `gradle jsIrParamsBenchmark` | Executes benchmark for 'jsIr' with NodeJS |
| `gradle jvmBenchmark` | Execute benchmark for 'jvm' |
| `gradle jvmBenchmarkBenchmark` | Execute benchmark for 'jvmBenchmark' |
| `gradle jvmBenchmarkBenchmarkCompile` | Compile JMH source files for 'jvmBenchmark' |
| `gradle jvmBenchmarkBenchmarkGenerate` | Generate JMH source files for 'jvmBenchmark' |
| `gradle jvmBenchmarkBenchmarkJar` | Build JAR for JMH compiled files for 'jvmBenchmark' |
| `gradle jvmBenchmarkCompile` | Compile JMH source files for 'jvm' |
| `gradle jvmBenchmarkCsvBenchmark` | Execute benchmark for 'jvmBenchmark' |
| `gradle jvmBenchmarkFastBenchmark` | Execute benchmark for 'jvmBenchmark' |
| `gradle jvmBenchmarkForkBenchmark` | Execute benchmark for 'jvmBenchmark' |
| `gradle jvmBenchmarkGenerate` | Generate JMH source files for 'jvm' |
| `gradle jvmBenchmarkJar` | Build JAR for JMH compiled files for 'jvm' |
| `gradle jvmBenchmarkParamsBenchmark` | Execute benchmark for 'jvmBenchmark' |
| `gradle jvmCsvBenchmark` | Execute benchmark for 'jvm' |
| `gradle jvmFastBenchmark` | Execute benchmark for 'jvm' |
| `gradle jvmForkBenchmark` | Execute benchmark for 'jvm' |
| `gradle jvmParamsBenchmark` | Execute benchmark for 'jvm' |
| `gradle linkNativeBenchmarkReleaseExecutableNative` | Compile Native benchmark source files for 'native' |
| `gradle nativeBenchmark` | Executes benchmark for 'native' |
| `gradle nativeBenchmarkGenerate` | Generate Native source files for 'native' |
| `gradle nativeCsvBenchmark` | Executes benchmark for 'native' |
| `gradle nativeFastBenchmark` | Executes benchmark for 'native' |
| `gradle nativeForkBenchmark` | Executes benchmark for 'native' |
| `gradle nativeParamsBenchmark` | Executes benchmark for 'native' |
| `gradle paramsBenchmark` | Execute all benchmarks in a project |
| `gradle wasmBenchmark` | Executes benchmark for 'wasm' with D8 |
| `gradle wasmBenchmarkGenerate` | Generate Wasm source files for 'wasm' |
| `gradle wasmCsvBenchmark` | Executes benchmark for 'wasm' with D8 |
| `gradle wasmFastBenchmark` | Executes benchmark for 'wasm' with D8 |
| `gradle wasmForkBenchmark` | Executes benchmark for 'wasm' with D8 |
| `gradle wasmParamsBenchmark` | Executes benchmark for 'wasm' with D8 |
| `assembleBenchmarks` | Generates and builds all benchmarks in the project. |
| `benchmark` | Executes all benchmarks in the project. |
| `compileJsIrBenchmarkKotlinJsIr` | Compiles the source files for 'jsIr' benchmark. |
| `compileJsIrBuiltInBenchmarkKotlinJsIrBuiltIn` | Compiles the source files for 'jsIrBuiltIn' benchmark. |
| `compileWasmBenchmarkKotlinWasm` | Compiles the source files for 'wasm' benchmark. |
| `csvBenchmark` | Executes all benchmarks in the project with the CSV configuration. |
| `fastBenchmark` | Executes all benchmarks in the project with the Fast configuration. |
| `forkBenchmark` | Executes all benchmarks in the project with the Fork configuration. |
| `jsIrBenchmark` | Executes benchmark for the 'jsIr' source set. |
| `jsIrBenchmarkGenerate` | Generates source files for the 'jsIr' source set. |
| `jsIrBuiltInBenchmark` | Executes benchmark for the 'jsIrBuiltIn' source set. |
| `jsIrBuiltInBenchmarkGenerate` | Generates source files for the 'jsIrBuiltIn' source set. |
| `jsIrBuiltInCsvBenchmark` | Executes benchmark for the 'jsIrBuiltIn' source set with the CSV configuration. |
| `jsIrBuiltInFastBenchmark` | Executes benchmark for the 'jsIrBuiltIn' source set with the Fast configuration. |
| `jsIrBuiltInForkBenchmark` | Executes benchmark for the 'jsIrBuiltIn' source set with the Fork configuration. |
| `jsIrBuiltInParamsBenchmark` | Executes benchmark for the 'jsIrBuiltIn' source set with the Params configuration. |
| `jsIrCsvBenchmark` | Executes benchmark for the 'jsIr' source set with the CSV configuration. |
| `jsIrFastBenchmark` | Executes benchmark for the 'jsIr' source set with the Fast configuration. |
| `jsIrForkBenchmark` | Executes benchmark for the 'jsIr' source set with the Fork configuration. |
| `jsIrParamsBenchmark` | Executes benchmark for the 'jsIr' source set with the Params configuration. |
| `jvmBenchmark` | Executes benchmark for the 'jvm' source set. |
| `jvmBenchmarkBenchmark` | Executes benchmark for the 'jvmBenchmark' source set. |
| `jvmBenchmarkBenchmarkCompile` | Compiles the source files for 'jvmBenchmark'. |
| `jvmBenchmarkBenchmarkGenerate` | Generates source files for the 'jvmBenchmark' source set. |
| `jvmBenchmarkBenchmarkJar` | Builds the JAR for 'jvmBenchmark' compiled files. |
| `jvmBenchmarkCompile` | Compiles the source files for the 'jvm' benchmark. |
| `jvmBenchmarkCsvBenchmark` | Executes benchmark for the 'jvmBenchmark' source set with the CSV configuration. |
| `jvmBenchmarkFastBenchmark` | Executes benchmark for the 'jvmBenchmark' source set with the Fast configuration. |
| `jvmBenchmarkForkBenchmark` | Executes benchmark for the 'jvmBenchmark' source set with the Fork configuration. |
| `jvmBenchmarkGenerate` | Generates source files for the 'jvm' source set. |
| `jvmBenchmarkJar` | Builds the JAR for 'jvm' compiled files. |
| `jvmBenchmarkParamsBenchmark` | Executes benchmark for the 'j| `jvmBenchmarkParamsBenchmark` | Executes benchmark for the 'jvmBenchmark' source set with the Params configuration. |
| `jvmCsvBenchmark` | Executes benchmark for the 'jvm' source set with the CSV configuration. |
| `jvmFastBenchmark` | Executes benchmark for the 'jvm' source set with the Fast configuration. |
| `jvmForkBenchmark` | Executes benchmark for the 'jvm' source set with the Fork configuration. |
| `jvmParamsBenchmark` | Executes benchmark for the 'jvm' source set with the Params configuration. |
| `linkNativeBenchmarkReleaseExecutableNative` | Compiles the source files for 'native' benchmark. |
| `nativeBenchmark` | Executes benchmark for the 'native' source set. |
| `nativeBenchmarkGenerate` | Generates source files for the 'native' source set. |
| `nativeCsvBenchmark` | Executes benchmark for the 'native' source set with the CSV configuration. |
| `nativeFastBenchmark` | Executes benchmark for the 'native' source set with the Fast configuration. |
| `nativeForkBenchmark` | Executes benchmark for the 'native' source set with the Fork configuration. |
| `nativeParamsBenchmark` | Executes benchmark for the 'native' source set with the Params configuration. |
| `paramsBenchmark` | Executes all benchmarks in the project with the Params configuration. |
| `wasmBenchmark` | Executes benchmark for the 'wasm' source set. |
| `wasmBenchmarkGenerate` | Generates source files for the 'wasm' source set. |
| `wasmCsvBenchmark` | Executes benchmark for the 'wasm' source set with the CSV configuration. |
| `wasmFastBenchmark` | Executes benchmark for the 'wasm' source set with the Fast configuration. |
| `wasmForkBenchmark` | Executes benchmark for the 'wasm' source set with the Fork configuration. |
| `wasmParamsBenchmark` | Executes benchmark for the 'wasm' source set with the Params configuration. |

## Want to learn more?

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.
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.
12 changes: 6 additions & 6 deletions examples/kotlin/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,12 +23,12 @@ All tasks can be run from the root of the project, from a terminal:

| Task Name | Action |
| --- | --- |
| `gradle assembleBenchmarks` | Generate and build all benchmarks in the project |
| `gradle benchmark` | Execute all benchmarks in the project |
| `gradle benchmarksBenchmark` | Execute benchmark for 'benchmarks' |
| `gradle benchmarksBenchmarkCompile` | Compile JMH source files for 'benchmarks' |
| `gradle benchmarksBenchmarkGenerate` | Generate JMH source files for 'benchmarks' |
| `gradle benchmarksBenchmarkJar` | Build JAR for JMH compiled files for 'benchmarks' |
| `assembleBenchmarks` | Generate and build all benchmarks in the project |
| `benchmark` | Execute all benchmarks in the project |
| `benchmarksBenchmark` | Execute benchmark for 'benchmarks' |
| `benchmarksBenchmarkCompile` | Compile JMH source files for 'benchmarks' |
| `benchmarksBenchmarkGenerate` | Generate JMH source files for 'benchmarks' |
| `benchmarksBenchmarkJar` | Build JAR for JMH compiled files for 'benchmarks' |

## Want to learn more?

Expand Down

0 comments on commit e1d7432

Please sign in to comment.