Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,10 +38,10 @@ All notable changes to the "Gimlet" extension will be documented in this file.
### Added

- feat(ui): activity-bar pane and status-bar item showing debug session state (Idle / Ready / Attached) ([#58](https://github.com/LimeChain/gimlet/pull/58))
- feat: `Gimlet: Attach Debugger` command attach via the Gimlet pane or the Command Palette
- feat: `Gimlet: Attach Debugger` command - attach via the Gimlet pane or the Command Palette
- feat(config): `platformToolsDir`, `lldbLibraryPath`, and `artifactsPath` overrides in `gimlet.json` for non-standard platform-tools installs ([#57](https://github.com/LimeChain/gimlet/pull/57))
- feat(config): schema-based validation of `gimlet.json`; debug launch is gated while errors exist
- feat(config): tri-state apply valid keys apply, absent keys reset to defaults, invalid keys keep prior value
- feat(config): tri-state apply - valid keys apply, absent keys reset to defaults, invalid keys keep prior value
- feat(config): enforce `platformToolsVersion` >= 1.54 and integer `tcpPort` >= 1024

### Changed
Expand All @@ -55,7 +55,7 @@ All notable changes to the "Gimlet" extension will be documented in this file.

- fix: handle `startDebugging` errors and restore lldb config on failure
- fix: check llvm lib directory exists before use
- fix: validate `sbfTraceDir` stays within workspace reject `..` traversal
- fix: validate `sbfTraceDir` stays within workspace - reject `..` traversal
- fix: quote `metadataFile` and `debugPath` in lldb commands to handle paths with spaces
- fix: use `os.tmpdir()` instead of hardcoded `/tmp/` for cross-platform temp dir
- fix: missing `await` on `listenAndStartDebugForPort()`
Expand All @@ -75,7 +75,7 @@ All notable changes to the "Gimlet" extension will be documented in this file.

## [0.1.20] - 2026-04-16

Stable release consolidates all changes since v0.0.10.
Stable release - consolidates all changes since v0.0.10.

### Added

Expand Down
9 changes: 4 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -59,21 +59,20 @@ You can customize this file to:

| Option | Default | Description |
|------------------------|----------|-----------------------------------------------------------------------------|
| `tcpPort` | `1212` | TCP port the gdbstub listens on. Must be in the unprivileged range strictly greater than `1023` and less than `65536`. |
| `tcpPort` | `1212` | TCP port the gdbstub listens on. Must be in the unprivileged range - strictly greater than `1023` and less than `65536`. |
| `platformToolsVersion` | `"1.54"` | Solana platform-tools version. Major.minor only (e.g. `"1.54"`); minimum supported is `1.54`. |
| `stopOnEntry` | `true` | Stop at program entry point; set to `false` to skip to the first breakpoint |
| `sbfTracePath` | `target/sbf/trace` | **Workspace-relative** path to the SBF trace directory. |
| `artifactsPath` | `target/deploy/debug` | **Workspace-relative** path to the directory holding your compiled `.so` programs (plus `.debug` files); must stay inside the workspace. Resolved in order: (1) this key when set; (2) `$CARGO_TARGET_DIR/deploy/debug` if that env var is exported; (3) `target/deploy/debug`. |
| `platformToolsPath` | `~/.cache/solana/v{platformToolsVersion}/platform-tools/` | Absolute path to your platform-tools root. Gimlet derives the LLDB library, Python site-packages, and scripts dir from `{platformToolsPath}/llvm/{lib,bin}/` override when your toolchain lives outside the default `cargo build-sbf` cache location. |
| `lldbLibraryPath` | `{platformToolsPath}/llvm/lib/liblldb.{ext}` | Absolute path to a specific `liblldb.dylib` / `liblldb.so` file. Wins over the derived LLDB default use for non-standard library filenames (e.g. `liblldb.20.1.7-rust-dev.dylib`) or missing `liblldb.{ext}` symlinks. Does not affect Python/scripts paths; pair with `platformToolsPath` when the whole install is non-standard. |
| `platformToolsPath` | `~/.cache/solana/v{platformToolsVersion}/platform-tools/` | Absolute path to your platform-tools root. Gimlet derives the LLDB library, Python site-packages, and scripts dir from `{platformToolsPath}/llvm/{lib,bin}/` - override when your toolchain lives outside the default `cargo build-sbf` cache location. |
| `lldbLibraryPath` | `{platformToolsPath}/llvm/lib/liblldb.{ext}` | Absolute path to a specific `liblldb.dylib` / `liblldb.so` file. Wins over the derived LLDB default - use for non-standard library filenames (e.g. `liblldb.20.1.7-rust-dev.dylib`) or missing `liblldb.{ext}` symlinks. Does not affect Python/scripts paths; pair with `platformToolsPath` when the whole install is non-standard. |

> **Which key do I need?** `platformToolsPath` alone covers most cases it reroutes all three paths Gimlet depends on. Use `lldbLibraryPath` only when the LLDB library filename is non-standard or its symlink is missing. Leave both unset for the default `cargo build-sbf` layout at `~/.cache/solana/v{platformToolsVersion}/platform-tools/`.
> **Which key do I need?** `platformToolsPath` alone covers most cases - it reroutes all three paths Gimlet depends on. Use `lldbLibraryPath` only when the LLDB library filename is non-standard or its symlink is missing. Leave both unset for the default `cargo build-sbf` layout at `~/.cache/solana/v{platformToolsVersion}/platform-tools/`.

Gimlet also adjusts a few **VS Code workspace settings** (`.vscode/settings.json`) to ensure smooth integration:

| Setting | Value | Why |
|---------|-------|-----|
| `rust-analyzer.debug.engine` | `"vadimcn.vscode-lldb"` | Tells rust-analyzer to use the CodeLLDB adapter for debugging |
| `lldb.library` | Path to Solana platform-tools `liblldb` | Points CodeLLDB at the Solana-patched LLDB that understands sBPF ELFs |
| `lldb.adapterEnv` → `PYTHONPATH` | Path to platform-tools Python packages | Ensures LLDB can find its Python dependencies at startup |

Expand Down
4 changes: 2 additions & 2 deletions src/config.js
Original file line number Diff line number Diff line change
Expand Up @@ -194,7 +194,7 @@ class GimletConfigManager {
};

const resetToDefaults = () => {
// File removed treat as an empty config so every override clears back to null.
// File removed - treat as an empty config so every override clears back to null.
globalState.setConfig({});
this.resolveGimletConfig();
vscode.window.showInformationMessage(
Expand All @@ -204,7 +204,7 @@ class GimletConfigManager {

// All three events route through the same handlers. Atomic-save editors
// (rename+replace on save, common with format-on-save or on Windows) fire
// onDidDelete + onDidCreate instead of onDidChange without the Create
// onDidDelete + onDidCreate instead of onDidChange - without the Create
// handler, Gimlet would miss the save entirely.
watcher.onDidChange(reloadFromDisk);
watcher.onDidCreate(reloadFromDisk);
Expand Down
16 changes: 6 additions & 10 deletions src/extension.js
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,6 @@ const gimletConfigManager = require('./config');
const { globalState } = require('./state/globalState');
const { createSessionState } = require('./state/sessionState');

const { rustAnalyzerSettingsManager } = require('./managers/vscodeSettingsManager');
const portManager = require('./managers/portManager');
const { StatusBarManager } = require('./managers/statusBarManager');
const { TreeView } = require('./managers/treeView');
Expand Down Expand Up @@ -85,16 +84,13 @@ async function scanDeployDirectory(session) {
}

// Run the side effects that turn an opened workspace into a Gimlet workspace:
// write .vscode/gimlet.json, attach the config watcher, override
// rust-analyzer's debug engine, and surface the status bar item. Idempotent —
// safe to call from every entry point that needs an engaged extension.
// write .vscode/gimlet.json, attach the config watcher, and surface the status
// bar item. Idempotent - safe to call from every entry point that needs an
// engaged extension.
async function engage(context) {
if (engaged) return;
engaged = true;

// TODO(lime): rust-analyzer.debug.engine silently overwritten at workspace level, never restored. Hostile to users who prefer a different engine
await rustAnalyzerSettingsManager.set('debug.engine', 'vadimcn.vscode-lldb');

gimletConfigManager.ensureGimletConfig();
gimletConfigManager.watchGimletConfig(context);

Expand All @@ -119,7 +115,7 @@ function gimletConfigExists() {
async function activate(context) {
log('Activating Gimlet...');

// TODO(lime): multi-root workspaces are silently ignored grabs workspaceFolders[0]
// TODO(lime): multi-root workspaces are silently ignored - grabs workspaceFolders[0]
const workspaceUri = vscode.workspace.workspaceFolders?.[0]?.uri;
if (!workspaceUri) {
log('No workspace folder found');
Expand Down Expand Up @@ -168,7 +164,7 @@ async function activate(context) {
if (globalState.lastConfigErrors.length > 0) {
const body = globalState.lastConfigErrors.map((e) => ` - ${e}`).join('\n');
vscode.window.showErrorMessage(
`Gimlet: cannot start debug fix gimlet.json first:\n${body}`
`Gimlet: cannot start debug - fix gimlet.json first:\n${body}`
);
return;
}
Expand Down Expand Up @@ -207,7 +203,7 @@ async function activate(context) {
stopDisposable
);

// A workspace that already has .vscode/gimlet.json has engaged before keep
// A workspace that already has .vscode/gimlet.json has engaged before - keep
// the status bar and palette commands available without forcing the user to
// click Attach again.
if (gimletConfigExists()) {
Expand Down
6 changes: 3 additions & 3 deletions src/managers/debugConfigManager.js
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@ class DebugConfigManager {
.find((entry) => entry.startsWith('python'));
if (!pythonDir) {
throw new Error(
`Platform-tools install at ${libDir} is missing its python* directory LLDB scripts cannot load. ` +
`Platform-tools install at ${libDir} is missing its python* directory - LLDB scripts cannot load. ` +
`Reinstall with 'cargo-build-sbf --tools-version v${globalState.platformToolsVersion} --force-tools-install', ` +
`or point "platformToolsPath" in .vscode/gimlet.json at a complete install.`
);
Expand All @@ -42,7 +42,7 @@ class DebugConfigManager {
.find((entry) => entry.endsWith('-packages'));
if (!packagesDir) {
throw new Error(
`Platform-tools install at ${pythonLibDir} is missing its *-packages directory LLDB scripts cannot load. ` +
`Platform-tools install at ${pythonLibDir} is missing its *-packages directory - LLDB scripts cannot load. ` +
`Reinstall with 'cargo-build-sbf --tools-version v${globalState.platformToolsVersion} --force-tools-install', ` +
`or point "platformToolsPath" in .vscode/gimlet.json at a complete install.`
);
Expand Down Expand Up @@ -111,7 +111,7 @@ class DebugConfigManager {
if (!session) {
throw new Error(
'Gimlet debug session was cleared before program modules could load. ' +
'This usually means the session was stopped concurrently try debugging again.'
'This usually means the session was stopped concurrently - try debugging again.'
);
}

Expand Down
19 changes: 0 additions & 19 deletions src/managers/vscodeSettingsManager.js

This file was deleted.

2 changes: 1 addition & 1 deletion src/state/configSchema.js
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@ const CHECKS = {
],
};

// Compares Solana platform-tools versions ("1.54", "2.0") major.minor only.
// Compares Solana platform-tools versions ("1.54", "2.0") - major.minor only.
// Returns negative if a<b, zero if equal, positive if a>b.
function compareVersions(a, b) {
const [aMajor, aMinor] = a.split('.').map(Number);
Expand Down
4 changes: 2 additions & 2 deletions src/state/globalState.js
Original file line number Diff line number Diff line change
Expand Up @@ -145,8 +145,8 @@ class GimletGeneralState {
' Install the matching Solana platform-tools:',
` cargo build-sbf --tools-version v${this.platformToolsVersion} --debug --arch v1 --force-tools-install`,
' Or point Gimlet at an existing install by setting one of:',
' "platformToolsPath" in .vscode/gimlet.json root of your platform-tools (covers LLDB, Python and scripts paths)',
` "lldbLibraryPath" in .vscode/gimlet.json exact path to your liblldb.${LIB_EXT} (LLDB only; use when the lib has a non-standard filename)`,
' "platformToolsPath" in .vscode/gimlet.json - root of your platform-tools (covers LLDB, Python and scripts paths)',
` "lldbLibraryPath" in .vscode/gimlet.json - exact path to your liblldb.${LIB_EXT} (LLDB only; use when the lib has a non-standard filename)`,
].join('\n')
);
}
Expand Down
Loading