diff --git a/CHANGELOG.md b/CHANGELOG.md index 2f55ac6..6dbf676 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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 @@ -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()` @@ -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 diff --git a/README.md b/README.md index 51712e7..de41466 100644 --- a/README.md +++ b/README.md @@ -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 | diff --git a/src/config.js b/src/config.js index 78273d8..e6dded4 100644 --- a/src/config.js +++ b/src/config.js @@ -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( @@ -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); diff --git a/src/extension.js b/src/extension.js index 5077d64..d4005cb 100644 --- a/src/extension.js +++ b/src/extension.js @@ -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'); @@ -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); @@ -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'); @@ -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; } @@ -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()) { diff --git a/src/managers/debugConfigManager.js b/src/managers/debugConfigManager.js index 184e3fc..b1cbc7b 100644 --- a/src/managers/debugConfigManager.js +++ b/src/managers/debugConfigManager.js @@ -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.` ); @@ -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.` ); @@ -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.' ); } diff --git a/src/managers/vscodeSettingsManager.js b/src/managers/vscodeSettingsManager.js deleted file mode 100644 index 92355a7..0000000 --- a/src/managers/vscodeSettingsManager.js +++ /dev/null @@ -1,19 +0,0 @@ -const vscode = require('vscode'); - -// Configures and sets VS Code settings in the user workspace -class VSCodeSettingsManager { - constructor(section) { - this.section = section; - this.config = vscode.workspace.getConfiguration(section); - } - - async set(key, value) { - await this.config.update(key, value, vscode.ConfigurationTarget.Workspace); - } -} - -// ===== Instantiate managers for specific VS Code settings sections ===== - -const rustAnalyzerSettingsManager = new VSCodeSettingsManager('rust-analyzer'); - -module.exports = { rustAnalyzerSettingsManager }; \ No newline at end of file diff --git a/src/state/configSchema.js b/src/state/configSchema.js index b58c0fd..d2368e7 100644 --- a/src/state/configSchema.js +++ b/src/state/configSchema.js @@ -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 ab. function compareVersions(a, b) { const [aMajor, aMinor] = a.split('.').map(Number); diff --git a/src/state/globalState.js b/src/state/globalState.js index 6696572..a872156 100644 --- a/src/state/globalState.js +++ b/src/state/globalState.js @@ -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') ); }