docs: add READMEs to examples

Kotlin · Jul 7, 2023 · e5cd512 · e5cd512
1 parent e00221d
commit e5cd512
Show file tree

Hide file tree

Showing 5 changed files with 265 additions and 0 deletions.
diff --git a/examples/README.md b/examples/README.md
@@ -0,0 +1,59 @@
+# 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.
+
+## 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:
+
+   ```
+   cd kotlinx-benchmark/examples
+   ```
+
+## Running the Examples
+
+Each example is a separate project that can be built and run independently. Here's how you can do it:
+
+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:
+
+   ```
+   cd kotlin-kts
+   ```
+
+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:
+
+   ```
+   gradle build
+   ```
+
+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.
+
+## 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).
+
+Happy benchmarking!
diff --git a/examples/java/README.md b/examples/java/README.md
@@ -0,0 +1,36 @@
+# Java Example
+
+[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/Kotlin/kotlinx-benchmark)
+
+## Project Structure
+
+Inside of this example, you'll see the following folders and files:
+
+```
+/
+├── build.gradle
+└── src/
+    └── main/
+        └── java/
+            └── test/
+                └── SampleJavaBenchmark.java
+```
+
+## Tasks
+
+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 '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 |
+
+## 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.
diff --git a/examples/kotlin-kts/README.md b/examples/kotlin-kts/README.md
@@ -0,0 +1,32 @@
+# Kotlin-KTS Example
+
+[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/Kotlin/kotlinx-benchmark)
+
+## Project Structure
+
+Inside of this example, you'll see the following folders and files:
+
+```
+/
+├── build.gradle.kts
+└── main/
+    └── src/
+        └── KtsTestBenchmark.kt
+```
+
+## Tasks
+
+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' |
+
+## 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.
diff --git a/examples/kotlin-multiplatform/README.md b/examples/kotlin-multiplatform/README.md
@@ -0,0 +1,103 @@
+# Kotlin-Multiplatform Example
+
+[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/Kotlin/kotlinx-benchmark)
+
+## Project Structure
+
+Inside of this example, you'll see the following folders and files:
+
+```
+│   build.gradle  ==> Build configuration file for Gradle
+│
+└───src  ==> Source code root
+    ├───commonMain  ==> Shared code
+    │   └───kotlin  
+    │       │   CommonBenchmark.kt  ==> Common benchmarks
+    │       │   InheritedBenchmark.kt  ==> Inherited benchmarks
+    │       │   ParamBenchmark.kt  ==> Parameterized benchmarks
+    │       │
+    │       └───nested  ==> Nested benchmarks
+    │               CommonBenchmark.kt
+    │
+    ├───jsMain  ==> JavaScript-specific code
+    │   └───kotlin
+    │           JsAsyncBenchmarks.kt  ==> JS async benchmarks
+    │           JsTestBenchmark.kt  ==> JS benchmarks
+    │
+    ├───jvmBenchmark  ==> JVM-specific benchmarks
+    │   └───kotlin
+    │           JvmBenchmark.kt
+    │
+    ├───jvmMain  ==> JVM-specific code
+    │   └───kotlin
+    │           JvmTestBenchmark.kt  ==> JVM benchmarks
+    │
+    ├───nativeMain  ==> Native-specific code
+    │   └───kotlin
+    │           NativeTestBenchmark.kt  ==> Native benchmarks
+    │
+    └───wasmMain  ==> WebAssembly-specific code
+        └───kotlin
+                WasmTestBenchmark.kt  ==> WebAssembly benchmarks
+```
+
+## Tasks
+
+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 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 |
+
+## 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.
diff --git a/examples/kotlin/README.md b/examples/kotlin/README.md
@@ -0,0 +1,35 @@
+# Kotlin Example
+
+[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/Kotlin/kotlinx-benchmark)
+
+## Project Structure
+
+Inside of this example, you'll see the following folders and files:
+
+```
+/
+├── build.gradle
+├── benchmarks/
+│   └── src/
+│       └── TestBenchmark.kt
+└── main/
+    └── src/
+        └── TestData.kt
+```
+
+## Tasks
+
+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' |
+
+## 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.