Skip to content

Commit

Permalink
fix: fixing minor edge cases with custom commands; refreshing documen…
Browse files Browse the repository at this point in the history 
…tation (#49)

* fix: simplifying logic for custom commands; fixing edge cases when empty picker is presented

* docs: refreshing documentation; including extra docs for available vscode settings

* chore: apply suggestions from code review

Co-authored-by: Neil Campbell <[email protected]>

---------

Co-authored-by: Neil Campbell <[email protected]>
  • Loading branch information
@aorumbayev @neilcampbell
aorumbayev and neilcampbell authored Oct 31, 2024
1 parent 4a740db commit 557389e
Show file tree
Hide file tree
Showing 3 changed files with 95 additions and 50 deletions.
76 changes: 59 additions & 17 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@

---

The AlgoKit AVM VS Code Debugger extension provides a convenient way to debug any Algorand Smart Contracts written in TEAL.
The AlgoKit AVM VS Code Debugger extension enables line-by-line debugging of Algorand smart contracts on the AVM, whether written in TEAL directly or compiled from [Puya](https://github.com/algorandfoundation/puya). It leverages AVM simulate traces and source maps to provide a seamless debugging experience. For detailed setup instructions, see the [Detailed Usage](#detailed-usage) section.

---

Expand All @@ -23,7 +23,7 @@ The AlgoKit AVM VS Code Debugger extension provides a convenient way to debug an

---

It is built on top of the official [AVM Debug Adapter](https://github.com/algorand/avm-debugger) provided by [Algorand Technologies](https://www.algorand.com/). Additionally, a set of companion utilities are provided in the [TypeScript](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/docs/capabilities/debugging.md) and [Python](https://github.com/algorandfoundation/algokit-utils-py/blob/main/docs/source/capabilities/debugging.md) versions of `algokit-utils`, making it easier for developers to set up the required prerequisites and run the debugger.
The core functionality is built on top of the [AVM Debug Adapter](https://github.com/algorand/avm-debugger). Additionally, a set of companion utilities are provided in the [TypeScript](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/docs/capabilities/debugging.md) and [Python](https://github.com/algorandfoundation/algokit-utils-py/blob/main/docs/source/capabilities/debugging.md) versions of `algokit-utils`, making it easier for developers to set up the required prerequisites and run the debugger.

> To skip straight to the list of features, go to [Features](#features).
Expand All @@ -46,14 +46,39 @@ Before you can use the AVM Debugger extension, you need to ensure that you have
- [Visual Studio Code](https://code.visualstudio.com/download): Version 1.80.0 or higher. You can check your version by going to `Help > About` in VS Code.
- [Node.js](https://nodejs.org/en/download/): Version 18.x or higher. The extension is built with Node.js. Check your Node.js version by running `node -v` in your terminal/command prompt.

> The extension is designed to debug TEAL programs running on the Algorand Virtual Machine. It provides a step-by-step debugging experience by utilizing transaction execution traces and compiled source maps of your smart contract. However, it's crucial to understand that debugging a smart contract language like TEAL has its unique aspects compared to general-purpose languages. For a comprehensive guide on how to initiate a debugging session, please refer to the [Usage](#usage) section.
### Quick Start

## Installation
Below is a bare-bones example of how to get started with the AVM Debugger extension in an AlgoKit based project relying on `algokit-utils`.

1. Install the extension from the [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=algorandfoundation.algokit-avm-vscode-debugger).
2. Follow the next steps in the [Usage](#usage) section.
1. **Enable debugging in algokit-utils**:

## Usage
```typescript
// In your main file (TypeScript)
import { config } from 'algokit-utils-ts'
config.configure({ debug: true, traceAll: true })
```

or

```python
# In your main file (Python)
from algokit_utils.config import config
config.configure(debug=True, trace_all=True)
```

2. **Interact with your smart contract**: Perform an application call using `algokit-utils`.

3. **Start debugging**:
- Open the AVM simulate trace file (ends with `.trace.avm.json`)
- If using an official `algokit-python-template`, execute the `Debug TEAL via AlgoKit AVM Debugger` launch configuration. Otherwise, create a new VSCode launch configuration of type `avm` (which will automatically set recommended defaults).
- The extension can also be invoked via the debug icon in the editor (visible in top right corner when viewing a trace file) or using the `Debug AVM Trace File` command from the Command Palette.
- The debugger will guide you through the process of selecting the correct source files and traces and will initiate the debugging session.

> **Pro Tip**: Use the `Clear AVM Debug Registry` command if you need to reset your sourcemap selections or if you're experiencing mapping issues.
To learn more about the features and how to use them, continue reading below.

## Detailed Usage

The AVM Debugger extension automatically detects and operates on the following files:

Expand Down Expand Up @@ -163,6 +188,33 @@ The extension also offers an interactive picker for simulation trace files. The

> Please note the limit for max visible items in the extension picker is 100. If you have more than 100 `sources.avm.json` files in the working directory, consider using the `programSourcesDescriptionFile` property to specify the path to a specific file.
### VSCode Commands and Settings

The following will become available within the IDE after the extension is installed.

#### Commands

The extension provides the following commands that can be accessed via the Command Palette (Ctrl+Shift+P / Cmd+Shift+P):

| Command | Description |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `Debug AVM Trace File` | Initiates a debugging session from an open trace file. Can also be triggered via the debug icon when viewing a trace file |
| `Clear AVM Debug Registry` | Resets the AVM debug registry file (sources.avm.json) - useful when you want to start fresh with sourcemap selections |
| `Edit AVM Debug Registry` | Opens the AVM debug registry file for manual editing |

#### Settings

Configure the debugger behavior through VS Code settings:

| Setting | Description | Default |
| ------------------------------------------ | ------------------------------------------------------------------------------------------ | ----------------------------------- |
| `avmDebugger.debugAdapter.port` | Port number for the debug adapter when running in server mode. Leave empty for inline mode | `null` |
| `avmDebugger.defaultSourcemapRegistryFile` | Custom path to the sources.avm.json registry file | `.algokit/sources/sources.avm.json` |

> **Tip for Beginners**: Start with the default settings. The inline debug adapter mode (default when `debugAdapter.port` is not set) is perfect for most use cases.
> **Advanced Usage**: Set `debugAdapter.port` when you need to run the debug adapter as a separate process, which can be useful for development or debugging of the extension itself.
## Features

This document outlines the features supported by the AVM debugger. Screenshots and features are based on the VS Code client.
Expand All @@ -181,16 +233,6 @@ This document outlines the features supported by the AVM debugger. Screenshots a
| Support for Puya sourcemaps | The debugger now supports Puya sourcemaps, allowing debugging of contracts written in Puya. | ![Puya sourcemap](images/puya-sources.png) |
| Ability to ignore or select external sourcemaps | Users can browse and select external sourcemap files if they're not found in the workspace. Additionaly providing an option to ignore sourcemaps for specific hashes, which can be reset via the 'Clear AVM Registry' command. | ![Picker v2](images/pickerv2.png) |

### VSCode Commands

The extension provides the following commands:

| Name | Command | Description |
| ------------------------ | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| Debug AVM Trace File | extension.avmDebugger.debugOpenTraceFile | Opens a trace file for debugging. Also accessible via debug icon visible when a trace file is opened in the editor. |
| Clear AVM Debug Registry | extension.avmDebugger.clearAvmDebugRegistry | Clears the AVM debug registry (contents of sources.avm.json). |
| Edit AVM Debug Registry | extension.avmDebugger.editAvmDebugRegistry | Edits the AVM debug registry (contents of sources.avm.json). |

## How can I contribute?

This is an open source project managed by the Algorand Foundation. See the [contributing page](./CONTRIBUTING.md) to learn about making improvements, including developer setup instructions.
Expand Down
63 changes: 30 additions & 33 deletions src/activateAvmDebug.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -27,20 +27,16 @@ export function activateAvmDebug(context: vscode.ExtensionContext, factory: vsco

context.subscriptions.push(
vscode.commands.registerCommand('extension.avmDebugger.clearAvmDebugRegistry', async () => {
const config = vscode.workspace.getConfiguration('avmDebugger')
let sourcesFilePath = config.get<string>('programSourcesDescriptionFile')

if (!sourcesFilePath) {
const workspaceFolder = await getWorkspaceFolder()
if (!workspaceFolder) return
const workspaceFolder = await getWorkspaceFolder()
if (!workspaceFolder) return

sourcesFilePath = await findAndPickFile(workspaceFolder, SOURCES_FILE_PATTERN, {
title: 'Select program sources description file to clear',
placeHolder: 'Please select a file to clear',
noFilesErrorMessage: `No program sources description files (with name ${SOURCES_FILE_NAME}) were found in the workspace.`,
})
if (!sourcesFilePath) return
}
const sourcesFilePath = await findAndPickFile(workspaceFolder, SOURCES_FILE_PATTERN, {
title: 'Select program sources description file to clear',
placeHolder: 'Please select a file to clear',
noFilesErrorMessage: `No program sources description files (with name ${SOURCES_FILE_NAME}) were found in the workspace.`,
exitIfNoFiles: true,
})
if (!sourcesFilePath) return

const confirmation = await vscode.window.showWarningMessage(
`Are you sure you want to clear the content of ${sourcesFilePath}?`,
Expand All @@ -49,34 +45,35 @@ export function activateAvmDebug(context: vscode.ExtensionContext, factory: vsco
)

if (confirmation === 'Yes') {
await workspaceFileAccessor.writeFile(sourcesFilePath, new TextEncoder().encode(JSON.stringify({}, null, 2)))
vscode.window.showInformationMessage('AVM Debug Registry cleared.')
const fileUri = vscode.Uri.joinPath(workspaceFolder.uri, sourcesFilePath)
await vscode.workspace.fs.delete(fileUri)
await workspaceFileAccessor.writeFile(fileUri.fsPath, new TextEncoder().encode(JSON.stringify({}, null, 2)))
vscode.window.showInformationMessage(
'AVM Debug Registry file cleared. You can now restart the debugger to pick a new sourcemap to use.',
)
}
}),
)

context.subscriptions.push(
vscode.commands.registerCommand('extension.avmDebugger.editAvmDebugRegistry', async () => {
const config = vscode.workspace.getConfiguration('avmDebugger')
const currentFile = config.get<string>('programSourcesDescriptionFile')

if (currentFile) {
const document = await vscode.workspace.openTextDocument(currentFile)
await vscode.window.showTextDocument(document)
} else {
const workspaceFolder = await getWorkspaceFolder()
if (!workspaceFolder) return
const workspaceFolder = await getWorkspaceFolder()
if (!workspaceFolder) {
vscode.window.showWarningMessage('No workspace folder found.')
return
}

const sourcesFilePath = await findAndPickFile(workspaceFolder, SOURCES_FILE_PATTERN, {
title: 'Program sources description file',
placeHolder: 'Please select a program sources description file',
noFilesErrorMessage: `No program sources description files (with name ${SOURCES_FILE_NAME}) were found in the workspace.`,
})
if (!sourcesFilePath) return
const sourcesFilePath = await findAndPickFile(workspaceFolder, SOURCES_FILE_PATTERN, {
title: 'Program sources description file',
placeHolder: 'Please select a program sources description file',
noFilesErrorMessage: `No program sources description files (with name ${SOURCES_FILE_NAME}) were found in the workspace.`,
exitIfNoFiles: true,
})
if (!sourcesFilePath) return

const document = await vscode.workspace.openTextDocument(sourcesFilePath)
await vscode.window.showTextDocument(document)
}
const fileUri = vscode.Uri.joinPath(workspaceFolder.uri, sourcesFilePath)
const document = await vscode.workspace.openTextDocument(fileUri)
await vscode.window.showTextDocument(document)

vscode.window.showInformationMessage('AVM Debug Registry opened for editing.')
}),
Expand Down
6 changes: 6 additions & 0 deletions src/utils.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -116,6 +116,7 @@ export async function findAndPickFile(
noFilesErrorMessage: string
allowBrowse?: boolean
fileType?: string
exitIfNoFiles?: boolean
},
): Promise<string | undefined> {
const fileUris = await findFilesInWorkspace(workspaceFolder, filePattern)
Expand Down Expand Up @@ -145,6 +146,11 @@ export async function findAndPickFile(
)
}

if (options.exitIfNoFiles && fileUris.length === 0) {
vscode.window.showWarningMessage(options.noFilesErrorMessage)
return undefined
}

const selected = await vscode.window.showQuickPick(quickPickItems, {
title: options.title,
placeHolder: options.placeHolder,
Expand Down

0 comments on commit 557389e

Please sign in to comment.