# Pseudo Kmp

> Pseudo Kmp is an Agent Skill for development published in the JetBrains/intellij-community repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Working with pseudo-KMP (Kotlin Multiplatform) modules in the IntelliJ monorepo. Use when creating, migrating, or modifying modules that use the expects-compiler-plugin for expect/actual emulation in JPS projects.

- Skill name: `pseudo-kmp`
- Category: [Development](https://www.openparable.com/skill/development/1)
- Source: https://github.com/JetBrains/intellij-community/blob/HEAD/.agents/skills/pseudo-kmp/SKILL.md
- Repository: JetBrains/intellij-community (20,363 GitHub stars when collected)

## SKILL.md

# Pseudo-KMP Modules

The monorepo is compiled by JPS, which does not support Kotlin Multiplatform. To emulate KMP expect/actual declarations, the Fleet team created the `expects-compiler-plugin`. This skill covers how to set up and work with modules that use this mechanism.

## Documentation

- [Multiplatform Migration Guide](../../../../docs/IntelliJ-Platform/4_man/Mutliplatform-Migration.md) — step-by-step migration instructions
- [Multiplatform Support README](../../../platform/multiplatformSupport/README.md) — compiler plugin usage and registration
- [ExpectInMultiplatform.kt](../../../platform/multiplatformSupport/src/fleet/util/multiplatform/ExpectInMultiplatform.kt) — `linkToActual()` and `@Actual` API docs

## Module Configuration Checklist

When creating or migrating a pseudo-KMP module:

1. **Register in the structure test.** Add your module name to the `multiplatformModules` list in `com.intellij.ideaProjectStructure.fast.MultiplatformModuleStructureTest` (`tests/ideaProjectStructure/testSrc/com/intellij/ideaProjectStructure/fast/MultiplatformModuleStructureTest.kt`).

2. **Use only allowed library dependencies.** The test enforces a closed set:
   - `kotlin-stdlib`
   - `kotlinx-coroutines-core`
   - `kotlinx-coroutines-debug`
   - `jetbrains-annotations`
   - `kotlinx-serialization-core`
   - `kotlinx-serialization-json`
   - `kotlin-reflect`
   - `kotlinx-collections-immutable`

   If you need a new library, add it to `allowedMultiplatformLibraryDependencies` in the test. Dependencies on other multiplatform modules (those in `multiplatformModules`) are also allowed.

3. **Set up source folders:**
   - `src/` — common code
   - `srcJvm/` or `srcJvmMain/` — JVM-specific code (Java code can live here too)
   - `srcWasmJs/` or `srcWasmJsMain/` — WasmJs-specific code
   - `srcJsMain/` — JS-specific code
   - `srcNativeMain/` — Native-specific code

   **Important:** Do NOT add `srcWasmJs`/`srcWasmJsMain` as a source root in the `.iml` file. The IDE would try to compile it in JVM mode.

4. **Add the `.pseudoCommonKotlinSourceSet` marker file** to the common source root (e.g., `src/.pseudoCommonKotlinSourceSet`). This empty file tells the Kotlin plugin that the source set is common code, preventing Optimize Imports from removing imports that are unnecessary on JVM but mandatory in common code (e.g., `@JvmStatic`, `@JvmField`).

## IML File Setup

Your `.iml` file needs two things: the `multiplatformSupport` dependency and the compiler plugin registration.

Use `community/platform/util/multiplatform/intellij.platform.util.multiplatform.iml` as a reference. To find the current plugin version, check that file rather than hardcoding.

### 1. Add the support module dependency (PROVIDED scope)

```xml
<orderEntry type="module" module-name="intellij.platform.multiplatformSupport" scope="PROVIDED" />
```

### 2. Add the Kotlin facet with expects-compiler-plugin

```xml
<facet type="kotlin-language" name="Kotlin">
  <configuration version="5" platform="JVM 1.8" allPlatforms="JVM [1.8]" useProjectSettings="false">
    <compilerSettings>
      <option name="additionalArguments" value="-Xjvm-default=all ..." />
    </compilerSettings>
    <compilerArguments>
      <stringArguments>
        <stringArg name="jvmTarget" arg="1.8" />
        <stringArg name="apiVersion" arg="2.3" />
        <stringArg name="languageVersion" arg="2.3" />
      </stringArguments>
      <arrayArguments>
        <arrayArg name="pluginClasspaths">
          <args>$MAVEN_REPOSITORY$/jetbrains/fleet/expects-compiler-plugin/{VERSION}/expects-compiler-plugin-{VERSION}.jar</args>
        </arrayArg>
      </arrayArguments>
    </compilerArguments>
  </configuration>
</facet>
```

Replace `{VERSION}` with the version from the reference IML.

## Expect/Actual Pattern

Only **top-level functions** are supported. Both the expect and actual declarations must be in the **same module**.

### Common side (in `src/`)

Use `linkToActual()` as the function body:

```kotlin
import fleet.util.multiplatform.linkToActual

internal fun myFunction(param1: String, param2: Int): Boolean = linkToActual()
```

### Platform side (in `srcJvm/`, `srcWasmJs/`, etc.)

Annotate with `@Actual`. The function name must be the expect function name + platform suffix:

```kotlin
import fleet.util.multiplatform.Actual

@Actual
internal fun myFunctionJvm(param1: String, param2: Int): Boolean {
  // JVM implementation
}
```

### Platform suffixes

| Platform             | Suffix   | Source folder                    |
|----------------------|----------|----------------------------------|
| JVM                  | `Jvm`    | `srcJvm/` or `srcJvmMain/`       |
| WasmJs               | `WasmJs` | `srcWasmJs/` or `srcWasmJsMain/` |
| JS                   | `Js`     | `srcJsMain/`                     |
| Native               | `Native` | `srcNativeMain/`                 |
| Multi-platform build | `Impl`   | (rare)                           |

### Real example

Common (`community/platform/util/base/multiplatform/src/com/intellij/util/text/CharArrayUtilKmp.kt`):
```kotlin
internal fun getCharsPlatformSpecific(
  sequence: CharSequence, srcOffset: Int, dst: CharArray, dstOffset: Int, len: Int
): Boolean = linkToActual()
```

JVM actual (`community/platform/util/base/multiplatform/srcJvmMain/com/intellij/util/text/jvm.kt`):
```kotlin
@Actual
internal fun getCharsPlatformSpecificJvm(
  string: CharSequence, srcOffset: Int, dst: CharArray, dstOffset: Int, len: Int
): Boolean {
  if (string is CharBuffer) { /* ... */ }
  return false
}
```

## Code Conversion Notes

- The monorepo uses the **JVM version** of the Kotlin standard library, which differs from the common version. Check which declarations are available in common code.
- `@JvmStatic`, `@JvmField`, and similar annotations are **not** auto-imported in common code. Import them manually. The `.pseudoCommonKotlinSourceSet` marker prevents the IDE from removing these imports.
- Java code can remain in platform-specific source sets (`srcJvm/`).

## After Editing

1. Run `./build/jpsModelToBazel.cmd` after modifying any `.iml` files.
2. Run `MultiplatformModuleStructureTest` to validate module structure:
   ```bash
   ./tests.cmd --module tests.ideaProjectStructure --test com.intellij.ideaProjectStructure.fast.MultiplatformModuleStructureTest
   ```
3. Lint changed files with `mcp__ijproxy__lint_files`.

## Artifact Publication

The monorepo does not publish multiplatform artifacts to Maven Central directly. Separate repositories with Gradle infrastructure extract module sources, compile with true KMP, and publish. See `fleet-multiplatform-deps` and `fleet-parser-collection` in JetBrains Space.

---

Source: https://www.openparable.com/skill/development/pseudo-kmp (OpenParable). Cite the canonical URL above.
