# VS Code extension

> The Elide extension for VS Code 1.105 or newer: project sync for Kotlin and Java code intelligence, the Elide sidebar, code lenses, tests, debugging, tasks and settings.

The Elide extension turns any folder with an `elide.pkl` into a VS Code project: it syncs dependencies and source sets
into the Kotlin language server, and runs, tests and debugs through the `elide` CLI.

## Requirements

| Requirement | Notes |
| --- | --- |
| VS Code 1.105 or newer | Desktop VS Code or a remote/server build with a local filesystem. |
| Elide 1.5 or newer | Found through `elide.home`, `$ELIDE_HOME`, the install locations, then `PATH`. Elide 1.6 needs extension 0.6.0 or newer. |
| **Kotlin by JetBrains** | `JetBrains.kotlin-server`; installed with the extension. Finish its first-run prompt. |
| A JDK | For code intelligence; set `elide.jdk.home` or `$JAVA_HOME`. |

The extension needs a trusted workspace: a sync runs the workspace's `elide` CLI.

## Install

```bash
curl -LOJ "https://plugins.elide.dev/vscode/files?id=elide.elide"
code --install-extension elide-*.vsix
```

**Help → Get Started → Get started with Elide** walks through install, project, sync, run and test.

## Sync a project

Opening a folder with `elide.pkl` syncs it: Elide resolves the manifest, installs dependencies when the lockfile is
stale, and writes `workspace.json` for the Kotlin language server. Add `workspace.json` to `.gitignore`.

| Status bar | Meaning |
| --- | --- |
| **Elide** with a check | In sync |
| **Elide** with a spinner | Syncing |
| **Elide: out of date** | `elide.pkl` or the resolved dependencies changed |
| **Elide**, error-colored | Sync failed; **Elide: Show Output** has the CLI log |

Click the status bar item for the Elide menu: sync, run a command, run all tests, open `elide.pkl` or the output.
When `elide.pkl` changes, the extension asks to reload (`elide.sync.onManifestChange`).

## The Elide sidebar

The **Elide** view in the activity bar lists each project:

| Group | Rows | Actions |
| --- | --- | --- |
| Entrypoints | `jvm.main`, `entrypoint` and `scripts` entries | Run, Debug |
| Tasks | `build`, `test`, `install`, and **Build targets** from `elide build --inspect` | Run, Debug on targets that take `--debugger` |
| Source sets | Each source set and its roots | |
| Dependencies | Resolved libraries | Reveal in the file manager |

## Code intelligence

Kotlin and Java completion, navigation and diagnostics come from the Kotlin language server, which imports the synced
`workspace.json`: one module per source set, every library with its sources, the JDK and the manifest's Kotlin options.

- Sources jars are installed for declared Maven packages, so **Go to Definition** opens library code
  (`elide.install.classifiers`).
- The JDK comes from `elide.jdk.home`, then `jvm.javaHome`, `$JAVA_HOME`, or an installed JDK matching `jvm.target`.
- A checkout can keep an IntelliJ `.idea` directory: the extension sets `intellij.buildTool` to `json` in the
  workspace settings, so each editor reads its own model.

## Run

Code lenses run what the project declares:

| Where | Lenses |
| --- | --- |
| Above a JVM `main` function | **Run with Elide**, **Debug with Elide** |
| `jvm.main` and `entrypoint` in `elide.pkl` | **Run**, **Debug** |
| `scripts` entries | **Run script** |
| `artifacts` entries | **Build**; Native Image binaries also **Run** and **Debug** |

Runs are VS Code tasks of type `elide`; compiler errors become Problems on the reported file and line.

| Command | Effect |
| --- | --- |
| `Elide: Run Elide Command…` | Run `build`, `test`, `install` or `run <entrypoint>` as a task. |
| `Elide: Sync Project(s)` | Sync again. |
| `Elide: Show Menu` | The status bar menu. |
| `Elide: New Project…` | Create a project from a template of the installed CLI. |
| `Elide: Add Workspace Member…` | Create a project inside this one and add it to `workspace.members`. |
| `Elide: Open generated Kotlin LSP workspace` | Open `workspace.json`. |
| `Elide: Show Output` | Show the CLI output and the sync log. |

In `.vscode/tasks.json`:

```jsonc
{ "type": "elide", "command": "test", "args": ["src/api"], "options": { "bail": 3 } }
```

| Field | Value |
| --- | --- |
| `command` | `build`, `run`, `test` or `install` |
| `args` | Positional arguments: build targets, test paths, the entrypoint |
| `options` | CLI options: `{ "no-cache": true }` adds `--no-cache`; `false` drops an inherited one |
| `flags` | `-f NAME[=VALUE]` build flags |
| `programArgs` | Arguments after `--` |
| `env`, `project` | Environment; project root relative to the workspace folder |

## Test

JUnit tests in the test source sets appear in the **Testing** view, with gutter icons on each class and method. A run
calls `elide test --reporter=tap` for the selection and reports each test as it finishes; a failure shows its
assertion message and links to the failing line.

The **Debug** profile runs the same tests under the debugger.

**Run with Coverage** runs the selection with `--coverage` and shows the result in the editor gutter and the **Test
Coverage** view: JavaScript and TypeScript from LCOV, Java and Kotlin from a JaCoCo XML report. Request the XML report in
`elide.pkl`:

```pkl
import "elide:Coverage.pkl" as Coverage

coverage {
  jvm {
    reports { Coverage.xmlReport() }
  }
}
```

## Debug

**Debug with Elide** starts `elide run --debugger` and attaches to it. Breakpoints in Kotlin and Java sources stop the
program; ending the session stops Elide.

In `.vscode/launch.json`:

```jsonc
{
  "type": "elide",
  "request": "launch",
  "name": "Elide: Run (debug)",
  "entrypoint": "src/main/kotlin/shop/Main.kt"
}
```

| Field | Value |
| --- | --- |
| `command` | `run` (default), `test`, or `build` with `targets` |
| `entrypoint` | File, script or entrypoint; empty uses the manifest's |
| `args` | Program arguments |
| `elideArgs`, `options`, `flags`, `env`, `project` | As for tasks |

`elide.debug.adapter` picks the debugger: `intellij` (default, from the Kotlin extension) or `java`
([Debugger for Java](https://marketplace.visualstudio.com/items?itemName=vscjava.vscode-java-debug)). The debugger
listens on port `5005`, so one session runs at a time. For CDP and DAP debugging of JavaScript, TypeScript and Python,
see [Debugging](https://elide.help/docs/debugging#attach-a-debugger).

### Native Image

Launch type `elide-native` builds a Native Image artifact and debugs the binary under GDB, through the **C/C++**
extension (`ms-vscode.cpptools`):

```jsonc
{ "type": "elide-native", "request": "launch", "name": "Elide: Debug Native Image", "artifact": "bin" }
```

Add `-g` to the artifact's `options.flags` in `elide.pkl` for source-level breakpoints; debug info is emitted on Linux
only. `program` debugs an existing binary, `build: false` skips the build.

## Workspaces

A manifest with `workspace.members` syncs as one build. Each member is a project in the sidebar, the Testing view,
tasks and launch configurations, and code intelligence follows `project("name")` dependencies between members without
a build. Opening a member's directory offers to open the workspace root. See
[Workspaces](https://elide.help/docs/elide-pkl-reference#workspaces).

## Settings

| Setting | Default | Effect |
| --- | --- | --- |
| `elide.home` | `""` | Elide install root. Empty: `$ELIDE_HOME`, install locations, then `elide` on `PATH`. |
| `elide.jdk.home` | `""` | JDK for code intelligence. |
| `elide.sync.onStartup` | `true` | Sync when the workspace opens. |
| `elide.sync.onManifestChange` | `"prompt"` | `always`, `prompt` or `never`. |
| `elide.kotlinLsp.writeWorkspaceJson` | `true` | Write `workspace.json`. |
| `elide.install.classifiers` | `["sources"]` | Extra jars per Maven package: `sources`, `docs`. |
| `elide.flags` | `[]` | `-f NAME[=VALUE]` flags for every invocation, sync included. |
| `elide.build.options` | `{}` | Default options for `elide build`; `elide.run.options`, `elide.test.options` and `elide.install.options` likewise. |
| `elide.codeLens.enabled` | `true` | Show the Run and Debug code lenses. |
| `elide.debug.adapter` | `"intellij"` | `intellij` or `java`. |
| `elide.debug.nativeMiMode` | `"auto"` | `gdb`, `lldb` or `auto` for Native Image sessions. |
| `elide.debug.miDebuggerPath` | `""` | GDB or `lldb-mi` binary for Native Image sessions. |