add docs on analysis updating in repl vs scripts

unknowntrojan · Nov 30, 2023 · d40ab66 · d40ab66
1 parent 49cb6a4
commit d40ab66
Show file tree

Hide file tree

Showing 2 changed files with 15 additions and 0 deletions.
diff --git a/docs/dev/concepts.md b/docs/dev/concepts.md
@@ -8,6 +8,18 @@ APIs that query these mappings are plural. So for example, while `current_hlil.l
 
 ![Mapping between ILs ><](../img/ilmapping.png "Mapping between ILs")
 
+## REPL versus Scripts
+
+When you're interacting with the Binary Ninja [scripting console](../guide/index.md#script-python-console), it's important to realize that every time you run a command, the UI is automatically going to update analysis. You can see this by even running a simply command like:
+
+```
+print("test")
+```
+
+and then checking the `Log` pane where you will see an `Analysis update took #.###` message. This is a convenience the UI does for you just like if you were to change a type or create a function, you almost always want the analysis to be updated. However, in scripts you run yourself as plugins or via the "Run Script" command, you may not get the same results mid-execution until after the entire script is finished running.
+
+![Scriping Console ><](../img/console.png "Python Scripting Console")
+
 ## Operating on IL versus Native
 
 Generally speaking, scripts should operate on ILs. The available information far surpasses the native addresses and querying properties and using APIs almost always beats directly manipulating bytes. However, when it comes time to change the binary, there are some operations that can only be done at a simple virtual address. So for example, the [comment](https://api.binary.ninja/binaryninja.binaryview-module.html#binaryninja.binaryview.BinaryView.set_comment_at) or [tag](https://api.binary.ninja/binaryninja.binaryview-module.html#binaryninja.binaryview.BinaryView.add_tag) APIs (among others) work off of native addressing irrespective of IL level.

diff --git a/docs/guide/index.md b/docs/guide/index.md
@@ -672,6 +672,9 @@ From here, you can add any custom functions or objects you want to be available
 
 #### "Run Script..."
 
+???+ Danger "Warning"
+    When you run commands in the scripting console, the UI will automatically update analysis. This is because quite often when you make a change in the console you expect it to be immediately reflected in the UI. The same is not true when running a script where you must trigger `bv.update_analysis_and_wait()` or `current_function.reanalze()` to experience the same behavior.
+
 The "Run Script..." option in the File Menu allows loading a python script from your filesystem and executing it
 within the console. It can also be run via the Command Palette or bound to a key.