From c3b2cf67f5b98d202ba66e18c2eef6eb220bc609 Mon Sep 17 00:00:00 2001 From: Martin Verzilli Date: Mon, 18 Dec 2023 14:29:04 +0100 Subject: [PATCH 1/3] Expand debugger docs with experimental features --- tooling/debugger/README.md | 94 ++++++++++++++++++++++++++++++++++---- 1 file changed, 85 insertions(+), 9 deletions(-) diff --git a/tooling/debugger/README.md b/tooling/debugger/README.md index 964784cb730..76b5a84939d 100644 --- a/tooling/debugger/README.md +++ b/tooling/debugger/README.md @@ -315,25 +315,101 @@ Finished execution Upon quitting the debugger after a solved circuit, the resulting circuit witness gets saved, equivalent to what would happen if we had run the same circuit with `nargo execute`. -## VS Code extension -We're working on extending Noir's official VS Code extension so it uses the editor's debugger facilities to debug Noir programs. +# Testing experimental features -This section will soon show how to load the extension from sources, in order to test the debugger. +There's a number of features that are in active development and that can't yet be merged to the main branch for different reasons. In this section we detail what those features are and how to try them out. +## Build from experimental branch at fork -## Variable value inspection (unstable) +Build Nargo by pulling the source version from https://github.com/manastech/noir/tree/dap-with-vars. -To enable the inspection of variable values at runtime from the debugger, we're in the process of instrumenting the compiler to track and collect the necessary mappings between source code level variable names and ACIR/Brillig state. +This will result in a Nargo binary being written to `PROJECT_ROOT/target/debug/nargo`. We will use this path later, so keep it at hand or export it to a an env var. For example: -At the time of writing, there are still some parts of the language that haven't been fully instrumented, which means certain programs will crash when compiled with this. +`export NARGO_EXP=PROJECT_ROOT/target/debug/nargo` -It is however possible to try out this feature, both from the REPL and VS Code, by building Nargo from branch https://github.com/manastech/noir/tree/dap-with-vars. +## About the experimental features -We'll soon expand this section with details on how to do so for the adventurous. +There are currently 2 experimental features in the debugger: +- Variables inspection +- Stacktrace inspection -## Towards debugging contracts +NOTE: Supporting variables inspection requires extensive instrumentation of the compiler, handling all cases of variable creation, types, and value assignment. At the time of writing this README, some cases are still not supported. For example, if your program uses slices or references, this compiler version might panic when trying to compile them, or at some point during the debugger step-by-step execution. This is the main reason why this feature has not yet been merged into master. + +## Trying out REPL experimental features + +To try out these features, go through the same steps as described at the REPL Debugger section above, but instead of using `nargo debug` use `$NARGO_EXP debug` (assuming you exported your custom built Nargo binary to NARGO_EXP). + +When entering `help` on this version, you'll find two new commands: + +``` +... +stacktrace display the current stack trace +... +vars show variable values available at this point + in execution +``` + +Running `vars` will print the current variables in scope, and its current values: + +``` +At /mul_1/src/main.nr:6:5 + 1 // Test unsafe integer multiplication with overflow: 12^8 = 429 981 696 + 2 // The circuit should handle properly the growth of the bit size + 3 fn main(mut x: u32, y: u32, z: u32) { + 4 x *= y; + 5 x *= x; //144 + 6 -> x *= x; //20736 + 7 x *= x; //429 981 696 + 8 assert(x == z); + 9 } +> vars +y:UnsignedInteger { width: 32 }=Field(4), z:UnsignedInteger { width: 32 }=Field(2¹⁶×6561), x:UnsignedInteger { width: 32 }=Field(2⁴×9) +> +``` + +Running `stacktrace` will print information about the current frame in the stacktrace: + +``` +> stacktrace +Frame #0, opcode 12: EXPR [ (1, _5, _5) (-1, _6) 0 ] +At /1_mul/src/main.nr:6:5 + 1 // Test unsafe integer multiplication with overflow: 12^8 = 429 981 696 + 2 // The circuit should handle properly the growth of the bit size + 3 fn main(mut x: u32, y: u32, z: u32) { + 4 x *= y; + 5 x *= x; //144 + 6 -> x *= x; //20736 + 7 x *= x; //429 981 696 + 8 assert(x == z); + 9 } +> +``` + +## Testing the VS Code extension (experimental) + +There is a fork of the official Noir Visual Studio extension which enables the debugger in VS Code. This fork is at: https://github.com/manastech/vscode-noir/tree/dap-support. + +In this section, we'll explain how to test the VS Code Noir debugger combining that extension fork with the experimental features branch discussed above. + +1. First, get a copy of the extension source code from https://github.com/manastech/vscode-noir/tree/dap-support. + +2. Package the extension by running `npm run package`. + +3. Open the root folder of the extension on VS Code. + +4. From VS Code, press fn+F5. This will open a new VS Code window with the extension loaded from source. + +5. Go to Code -> Settings -> Extensions -> Noir Language Server. Look for the property `Nargo Path` and enter the path to the experimental build you got as a result of following the steps at [Trying out REPL experimental features]. + +6. At the VS Code sidebar, go to the debugger section (see screenshot). Click "create new launch configuration". Overwrite the `projectFolder` property with the absolute path to the Nargo project you want to debug. + +7. Go to a Noir file you want to debug. You should see this button is enabled. Click the play button. + +The debugger should now start. Current features exposed to the debugger include different kinds of stepping interactions, variable inspection and stacktraces. At the time of writing, Brillig registers and memory are not being exposed, but they will soon be. + +## Towards debugging contracts ### Contracts Runtime From 8cd54ce38febf79571078d58cf267fad6accf5d1 Mon Sep 17 00:00:00 2001 From: Martin Verzilli Date: Mon, 18 Dec 2023 14:33:16 +0100 Subject: [PATCH 2/3] Fix broken link --- tooling/debugger/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tooling/debugger/README.md b/tooling/debugger/README.md index 76b5a84939d..9212434163b 100644 --- a/tooling/debugger/README.md +++ b/tooling/debugger/README.md @@ -401,7 +401,7 @@ In this section, we'll explain how to test the VS Code Noir debugger combining t 4. From VS Code, press fn+F5. This will open a new VS Code window with the extension loaded from source. -5. Go to Code -> Settings -> Extensions -> Noir Language Server. Look for the property `Nargo Path` and enter the path to the experimental build you got as a result of following the steps at [Trying out REPL experimental features]. +5. Go to Code -> Settings -> Extensions -> Noir Language Server. Look for the property `Nargo Path` and enter the path to the experimental build you got as a result of following the steps at [Trying out REPL experimental features](#trying-out-repl-experimental-features). 6. At the VS Code sidebar, go to the debugger section (see screenshot). Click "create new launch configuration". Overwrite the `projectFolder` property with the absolute path to the Nargo project you want to debug. From 01a1588d2c068db0dc15e3edf470f19bf8c82b1e Mon Sep 17 00:00:00 2001 From: Martin Verzilli Date: Mon, 18 Dec 2023 14:41:51 +0100 Subject: [PATCH 3/3] Add images to debugger README --- tooling/debugger/README.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/tooling/debugger/README.md b/tooling/debugger/README.md index 9212434163b..0ec3b6f0cd4 100644 --- a/tooling/debugger/README.md +++ b/tooling/debugger/README.md @@ -403,11 +403,15 @@ In this section, we'll explain how to test the VS Code Noir debugger combining t 5. Go to Code -> Settings -> Extensions -> Noir Language Server. Look for the property `Nargo Path` and enter the path to the experimental build you got as a result of following the steps at [Trying out REPL experimental features](#trying-out-repl-experimental-features). -6. At the VS Code sidebar, go to the debugger section (see screenshot). Click "create new launch configuration". Overwrite the `projectFolder` property with the absolute path to the Nargo project you want to debug. +6. At the VS Code sidebar, go to the debugger section (see screenshot). Click "Add configuration". Overwrite the `projectFolder` property with the absolute path to the Nargo project you want to debug. -7. Go to a Noir file you want to debug. You should see this button is enabled. Click the play button. +Screenshot 2023-12-18 at 14 37 38 -The debugger should now start. Current features exposed to the debugger include different kinds of stepping interactions, variable inspection and stacktraces. At the time of writing, Brillig registers and memory are not being exposed, but they will soon be. +7. Go to a Noir file you want to debug. Navigate again to the debug section of VS Code, and click the "play" icon. + +The debugger should now have started. Current features exposed to the debugger include different kinds of stepping interactions, variable inspection and stacktraces. At the time of writing, Brillig registers and memory are not being exposed, but they will soon be. + +![Screen Recording 2023-12-18 at 14 14 28](https://github.com/manastech/noir/assets/651693/36b4becb-953a-4158-9c5a-7a185673f54f) ## Towards debugging contracts