From e5cd5122f6213448a40e827f42031d7e0f512d36 Mon Sep 17 00:00:00 2001 From: wldeh <62161211+wldeh@users.noreply.github.com> Date: Tue, 27 Jun 2023 16:21:26 -0700 Subject: [PATCH] docs: add READMEs to examples --- examples/README.md | 59 ++++++++++++++ examples/java/README.md | 36 +++++++++ examples/kotlin-kts/README.md | 32 ++++++++ examples/kotlin-multiplatform/README.md | 103 ++++++++++++++++++++++++ examples/kotlin/README.md | 35 ++++++++ 5 files changed, 265 insertions(+) create mode 100644 examples/README.md create mode 100644 examples/java/README.md create mode 100644 examples/kotlin-kts/README.md create mode 100644 examples/kotlin-multiplatform/README.md create mode 100644 examples/kotlin/README.md diff --git a/examples/README.md b/examples/README.md new file mode 100644 index 00000000..365639e6 --- /dev/null +++ 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 new file mode 100644 index 00000000..2b59fdeb --- /dev/null +++ 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 new file mode 100644 index 00000000..40ed9db8 --- /dev/null +++ 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 new file mode 100644 index 00000000..98c5c3cc --- /dev/null +++ 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 new file mode 100644 index 00000000..e918cd75 --- /dev/null +++ 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.