Gimlet is a VSCode Extension that makes Solana smart contract debugging seamless, automated, and fully integrated into the VS Code experience, eliminating the need for manual configuration or terminal-only workflows.
Before using Gimlet, ensure you have the following tools installed:
| Tool | Installation Command | Notes |
|---|---|---|
rust-analyzer |
Rust Analyzer Extension | VSCode extension |
codeLLDB |
CodeLLDB Extension | VSCode extension |
solana-cli |
Solana Docs | Use latest version |
platform-tools |
Solana Docs | Use versions >= 1.54 |
Gimlet uses LiteSVM to execute its tests. Each test transaction can start a VM instance running in SBPF, which exposes a gdbstub for debugging over TCP. Gimlet connects to this gdbstub using a specified tcpPort. It then launches lldb with a special library provided by the Solana platform-tools, enabling LLDB to load and debug ELF files—your compiled SBPF programs. It also supports CPI (Cross-Program Invocation) debugging.
Gimlet makes debugging Solana programs inside VS Code effortless. Follow these steps to get started:
When you open your Solana project, Gimlet automatically creates a .vscode/gimlet.json configuration file.
You can customize this file to:
- Specify a different platform-tools version
- Change the default TCP port used for debugging
- Control whether the debugger stops on entry or runs straight to your first breakpoint
| Option | Default | Description |
|---|---|---|
tcpPort |
1212 |
TCP port the gdbstub listens on |
platformToolsVersion |
"1.54" |
Solana platform-tools version |
stopOnEntry |
true |
Stop at program entry point; set to false to skip to the first breakpoint |
Gimlet also adjusts a few VS Code workspace settings to ensure smooth integration.
- Open VS Code in your Solana project folder.
- Install the Gimlet extension from the VS Code Marketplace.
- Build your program with debug symbols:
cargo-build-sbf --tools-version v1.54 --debug --arch v1
- Run your test with the debugger enabled:
SBF_DEBUG_PORT=1212 SBF_TRACE_DIR=$PWD/target/deploy/debug/trace cargo test --features sbpf-debugger
- Open the test file in VS Code — you’ll see a CodeLens button above it labeled:
Sbpf Debug→ for individual Rust testsSbpf Debug All→ for TypeScript test suites
- Click the button to connect Gimlet and start step-by-step debugging.
Example Anchor and Pinocchio programs to test Gimlet are available here.
Refer to the Apple Developer Forum thread for instructions on disabling debugging protection for macOS systems.
We recommend using platform-tools version v1.54.
To force-install the correct version inside your Rust project, run:
cargo build-sbf --tools-version v1.54 --debug --arch v1 --force-tools-installsudo apt update
sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt update
sudo apt install python3.10 python3.10-dev
python3.10 --version