Introduce docs/separate-benchmark-module.md

Author: Abduqodiri Qurbonzoda

README.md

@@ -30,7 +30,7 @@ kotlinx-benchmark is a toolkit for running benchmarks for multiplatform code wri
   - [Writing Benchmarks](#writing-benchmarks)
   - [Running Benchmarks](#running-benchmarks)
   - [Benchmark Configuration Profiles](#benchmark-configuration-profiles)
-  - [Separate source sets for benchmarks](#separate-source-sets-for-benchmarks)
+  - [Separate module for benchmarks](#separate-module-for-benchmarks)
 - [Examples](#examples)
 - [Contributing](#contributing)
 
@@ -41,7 +41,7 @@ kotlinx-benchmark is a toolkit for running benchmarks for multiplatform code wri
   - [Understanding Benchmark Runtime](docs/benchmark-runtime.md)
   - [Configuring kotlinx-benchmark](docs/configuration-options.md)
   - [Interpreting and Analyzing Results](docs/interpreting-results.md)
-  - [Creating Separate Source Sets](docs/separate-source-sets.md)
+  - [Creating a Separate Benchmark Module](docs/separate-benchmark-module.md)
   - [Tasks Overview](docs/tasks-overview.md)
   - [Compatibility Guide](docs/compatibility.md)
   - [Submitting issues and PRs](CONTRIBUTING.md)
@@ -425,10 +425,10 @@ benchmark {
 
 Refer to our [comprehensive guide](docs/configuration-options.md) to learn about configuration options and how they affect benchmark execution.
 
-### Separate source sets for benchmarks
+### Separate module for benchmarks
 
 Often you want to have benchmarks in the same project, but separated from main code, much like tests.
-Refer to our [detailed documentation](docs/separate-source-sets.md) on configuring your project to add a separate source set for benchmarks.
+Refer to our [detailed documentation](docs/separate-benchmark-module.md) on configuring your project to add a separate module for benchmarks.
 
 ## Examples
 

docs/separate-benchmark-module.md

@@ -0,0 +1,102 @@
+# Creating Separate Module for Benchmarks
+
+This guide will walk you through the process of creating a separate module for benchmarks in your Kotlin project. 
+Creating a separate module for benchmarks is especially beneficial when you are integrating benchmarks into an existing project. 
+Here are a few advantages of doing so:
+
+1. **Organization**: It helps maintain a clean and organized project structure. Segregating benchmarks from the main code makes it easier to navigate and locate specific code segments.
+
+2. **Isolation**: Separating benchmarks ensures that the benchmarking code does not interfere with your main code or test code. This isolation guarantees accurate measurements without unintentional side effects.
+
+3. **Flexibility**: Creating a separate module allows you to manage your benchmarking code independently. You can compile, test, and run benchmarks without impacting your main source code.
+
+## Step-by-step Setup Guide
+
+Below are the step-by-step instructions to set up a separate module for benchmarks in both Kotlin Multiplatform and Kotlin/JVM projects:
+
+### Kotlin Multiplatform Project
+
+Follow these steps to set up a separate compilation for benchmarks:
+
+1. **Define New Compilation**:
+
+    Start by creating a new compilation in your target of choice (e.g. jvm, js, native, wasm etc.). 
+    In this example, we're associating the new compilation `benchmark` with the `main` compilation of the `jvm` target. 
+    This association allows the benchmark compilation to access the internal API of the main compilation, 
+    which is particularly useful when benchmarks need to measure the performance of specific components 
+    or functionalities within the main codebase.
+
+    ```kotlin
+    // build.gradle.kts
+    kotlin { 
+        jvm { 
+            compilations.create('benchmark') {
+                associateWith(compilations.main)
+            }
+        }
+    }
+    ```
+
+2. **Register Benchmark Compilation**:
+
+    Conclude by registering your new benchmark compilation using its default source set name. 
+    In this instance, `jvmBenchmark` is the name of the default source set of the `benchmark` compilation.
+
+    ```kotlin
+    // build.gradle.kts
+    benchmark {
+        targets {
+            register("jvmBenchmark")
+        }
+    }
+    ```
+
+For additional information, refer to the [Kotlin documentation on creating a custom compilation](https://kotlinlang.org/docs/multiplatform-configure-compilations.html#create-a-custom-compilation).
+and the [documentation on associating compiler tasks](https://kotlinlang.org/docs/gradle-configure-project.html#associate-compiler-tasks).
+[Here is a sample Kotlin Multiplatform project](/examples/kotlin-multiplatform) with a separate compilation for benchmarks.
+
+### Kotlin/JVM Project
+
+Set up a separate benchmark source set by following these simple steps:
+
+1. **Define Source Set**:
+
+    Begin by defining a new source set. We'll use `benchmark` as the name for the source set.
+
+    ```kotlin
+    // build.gradle.kts
+    sourceSets {
+        create("benchmark")
+    }
+    ```
+
+2. **Propagate Dependencies**:
+
+    Next, propagate dependencies and output from the `main` source set to your `benchmark` source set. 
+    This ensures the `benchmark` source set has access to classes and resources from the `main` source set.
+
+    ```kotlin
+    // build.gradle.kts
+    dependencies {
+        add("benchmarkImplementation", sourceSets.main.get().output + sourceSets.main.get().runtimeClasspath)
+    }
+    ```
+
+    You can also add output and `compileClasspath` from `sourceSets.test` in the same way 
+    if you wish to reuse some of the test infrastructure.
+
+3. **Register Benchmark Source Set**:
+
+    Finally, register your benchmark source set. This informs the kotlinx-benchmark tool 
+    that benchmarks reside within this source set and need to be executed accordingly.
+
+    ```kotlin
+    // build.gradle.kts
+    benchmark {
+        targets { 
+            register("benchmark")
+        }
+    }
+    ```
+
+[Here is a sample Kotlin/JVM project](/examples/kotlin) with custom source set for benchmarks.