Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/algorand/avm-debugger
Debug Adapter Protocol Debugger for the Algorand Virtual Machine
https://github.com/algorand/avm-debugger
algorand algorand-teal avm debug-adapter-protocol debugger teal vscode-extension
Last synced: 3 months ago
JSON representation
Debug Adapter Protocol Debugger for the Algorand Virtual Machine
- Host: GitHub
- URL: https://github.com/algorand/avm-debugger
- Owner: algorand
- License: other
- Created: 2023-09-19T15:46:51.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2024-08-22T15:53:45.000Z (4 months ago)
- Last Synced: 2024-09-29T06:42:22.303Z (3 months ago)
- Topics: algorand, algorand-teal, avm, debug-adapter-protocol, debugger, teal, vscode-extension
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/avm-debug-adapter
- Size: 2.04 MB
- Stars: 5
- Watchers: 2
- Forks: 12
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# AVM Debugger
[](https://www.npmjs.com/package/avm-debug-adapter)
## Summary
This repo contains an AVM debugger which adheres to the [Debug Adapter Protocol](https://microsoft.github.io/debug-adapter-protocol/).
This protocol is used by a variety of clients, and this repo additionally
implements a basic client for VS Code.
Unlike traditional debuggers, which typically execute code as it is being
debugged, this debugger operates on an execution trace. The trace is created by
the [algod simulate API](https://developer.algorand.org/docs/rest-apis/algod/#post-v2transactionssimulate).
This debugger is not responsible for compiling programs, assembling transaction groups, or executing
transactions/programs. It is only responsible for replaying the execution trace, which must already
exist.
This code is based on the [`vscode-mock-debug`](https://github.com/microsoft/vscode-mock-debug) repo.
## Usage
There are multiple ways to invoke the debug adapter exported by this package.
### CLI
The debug adapter can be invoked from the command line using the `avm-debug-adapter` command.
If given no arguments, the debug adapter will use stdin and stdout to process messages.
To run as a server, use the `--port` option, shown below:
```bash
$ npm exec avm-debug-adapter -- --port=8080
>> running as a server, listening on 8080
```
### Programmatically
```typescript
// AvmDebugSession is a vscode.DebugAdapter implementation and can be imported
// directly if you don't want to run it as a server.
import { AvmDebugSession } from 'avm-debug-adapter';
// From node, you can create a debug adapter server like so
import { Server, nodeFileAccessor } from 'avm-debug-adapter/node';
const server = new Server({
fileAccessor: nodeFileAccessor,
port: 8080,
onSocketError: (err) => {
console.error(err);
},
onServerError: (err) => {
console.error(err);
},
});
console.log('Server listening on port ' + server.port());
process.on('SIGTERM', () => {
server.close();
});
```
## Features
See [FEATURES.md](FEATURES.md) for a list of features this debugger supports.
## Build and Run
1. Clone the repo.
2. `npm i` to install dependencies.
3. Open the project folder in VS Code.
4. From the Run and Debug menu, run the `Extension` configuration to open the AVM Debug extension in another VS Code window.
5. In the new window, go to its Run and Debug menu to select and launch one of the existing configurations.
6. You are now in a debugging session of a transaction group. You can step through the transaction group, inspect variables, set breakpoints and more. See [FEATURES.md](FEATURES.md) for more details.