From e1d7432119b1c19ede3c60bc8b14bf9633cee72f Mon Sep 17 00:00:00 2001 From: wldeh <62161211+wldeh@users.noreply.github.com> Date: Wed, 5 Jul 2023 23:46:43 -0700 Subject: [PATCH] docs: improve descriptions and setup steps --- examples/README.md | 56 ++++--------- examples/java/README.md | 20 ++--- examples/kotlin-kts/README.md | 12 +-- examples/kotlin-multiplatform/README.md | 104 ++++++++++++------------ examples/kotlin/README.md | 12 +-- 5 files changed, 90 insertions(+), 114 deletions(-) diff --git a/examples/README.md b/examples/README.md index 365639e6..56e5e6a1 100644 --- a/examples/README.md +++ b/examples/README.md @@ -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! diff --git a/examples/java/README.md b/examples/java/README.md index 2b59fdeb..84fc8c53 100644 --- a/examples/java/README.md +++ b/examples/java/README.md @@ -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. \ No newline at end of file diff --git a/examples/kotlin-kts/README.md b/examples/kotlin-kts/README.md index 40ed9db8..d3121ef8 100644 --- a/examples/kotlin-kts/README.md +++ b/examples/kotlin-kts/README.md @@ -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? diff --git a/examples/kotlin-multiplatform/README.md b/examples/kotlin-multiplatform/README.md index 98c5c3cc..8da2d9ae 100644 --- a/examples/kotlin-multiplatform/README.md +++ b/examples/kotlin-multiplatform/README.md @@ -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. \ No newline at end of file diff --git a/examples/kotlin/README.md b/examples/kotlin/README.md index e918cd75..0f16cf3a 100644 --- a/examples/kotlin/README.md +++ b/examples/kotlin/README.md @@ -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?