From d6443e46f662bef92cf24c2253a7619472fe6d34 Mon Sep 17 00:00:00 2001 From: sboddy Date: Wed, 29 Jan 2025 21:08:28 +0000 Subject: [PATCH] Update debugging guide to deal with MS's Marketplace changes. (#6035) --- .../docs/guides/development/debugging.rst | 142 ++++++++++-------- 1 file changed, 80 insertions(+), 62 deletions(-) diff --git a/src/bonsai/docs/guides/development/debugging.rst b/src/bonsai/docs/guides/development/debugging.rst index 69bb2c6244..4cecc46fef 100644 --- a/src/bonsai/docs/guides/development/debugging.rst +++ b/src/bonsai/docs/guides/development/debugging.rst @@ -1,109 +1,127 @@ Debugging Bonsai ================ -This is a mini-guide to setting up an IDE and configuring it to debug Bonsai more -easily. It is currently specific to this writers own system (Ubuntu) but this -can be expanded by others. +This is a mini-guide to setting up an IDE and configuring it to debug Bonsai +more easily. It is currently specific to this writers own system (Ubuntu) but +this can be expanded by others. -1. **Install VSCodium**: This will be system specific. I used the available - snap package. +1. **Install VSCode/VSCodium**: This will be system specific. I used the + available snap package. .. code-block:: bash - sudo snap install --classic codium + sudo snap install --classic codium I chose VSCodium to avoid Microsoft telemetry and data harvesting, but - VSCode is going to be similar, and even a bit easier (i.e. steps 3 & 4). + VSCode is going to be similar, and even a bit easier (i.e. step 3). -2. **Activate Python language support**: Start VSCodium, open the Extensions, find the Python - language support and activate it. +2. **Activate Python language support**: Start VSCode/VSCodium, open the + Extensions tab, find the Python language support and activate it. -3. **Install Blender Addon**: It seems VSCodium is not allowed to directly access - the Marketplace, and this addon (and the next) is not available in - VSCodium's equivalent. (Or I'm an idiot... entirely possible). This means a - few more steps are needed. +3. **Install Blender Addon**: This step depends on which IDE you chose. - Download the Blender addon's ``.vsix`` file from marketplace (Under "Resources") - using your browser from `this `_ - page. + a. VSCode - Install it with "**...**" -> "**Install from VSIX...**" + Open up the Extensions tab on the left, and search for the *Blender + Development* extension. Select it, and click Install. -4. **Install ms-vscode.cpptools**: When trying to use the Blender addon I got - an error about a missing dependancy. I read somewhere that this addon was - not needed, but I can't currently find the reference. At least for me, it - needs to be added the same way as step 3, or the Blender addon fails to - start. + I haven't actually tested this, but this should install the + *ms-vscode.cpptools* dependancy for you. If not, you may need to search + for, and install, this extension too. - Download the Cpp Tools addon's ``.vsix`` file from marketplace (Under "Resources") - using your browser from `this `_ - page. You will need to select the correct download for your system OS and - architecture. + b. VSCodium - Install it with "**...**" -> "**Install from VSIX...**" + It seems VSCodium is not allowed to direct access the Marketplace, and + due to licensing it is not possible to install the *Blender Development* + extension because of the *ms-vscode.cpptools* dependancy. -5. **Set the Blender config directory**: In **Settings** -> **Extensions** -> **Blender** -> "**Environment Variables**" + VSCodium's equivalent Marketplace does not (and could not due to + licensing) provide a functioning *Blender Development* extension. (Or I'm + an idiot... entirely possible). + + I've created an alternative *Blender Development* extension with the + *ms-vscode.cpptools* dependancy removed. + + .. note:: + This alternative should also work in VSCode, but you may as well save + yourself the hassle, and just use the original one. + + Download the *Blender Development* ``.vsix`` file from my GitHub fork + using your browser from `this `_ + repository. The ``.vsix`` is available on the Releases page. + + In VSCodium's Extensions sidebar install it with "**...**" -> + "**Install from VSIX...**" + + If you are squeamish about downloading my ``.vsix``, you can review the + single commit, clone the repo and create your own. + +4. **Set the Blender config directory**: In **Settings** -> **Extensions** -> + **Blender** -> "**Environment Variables**" edit the json file to set the ``BLENDER_USER_RESOURCE`` to the config folder - you installed Bonsai to. For me: + you installed Bonsai to. *For me*: .. code-block:: json - { - "blender.environmentVariables": { - "BLENDER_USER_RESOURCES": "/home/steve/.config/blender/4.2bonsai" - } - } + { + "blender.environmentVariables": { + "BLENDER_USER_RESOURCES": "/home/steve/.config/blender/4.2bonsai" + } + } - .. note:: - You `must` change that path to the correct value for your system. + .. warning:: + You `must` change that path to the correct value for your system. -6. **Unset the Just My Code flag**: In **Settings** -> **Extensions** -> **Blender** -> "**Just My Code**" - by unchecking the box. +5. **Unset the Just My Code flag**: In **Settings** -> **Extensions** -> + **Blender** -> "**Just My Code**" by unchecking the box. Again, this was advice found searching around in a github issue. If not done, the breakpoints do not work for me. -7. **Open the folder in VSCodium**: This is the same folder set in step 5. +6. **Open the folder in VSCode/VSCodium**: This is the same folder set in step + 5. Again, *for me*: ``/home/steve/.config/blender/4.2bonsai`` This was a key point for me. Do `not` go deeper in the folder structure - - that just doesn't work. (Thanks @theoryshaw) + that just doesn't work. (Thanks @theoryshaw) This feels a little like + using a sledgehammer to crack a nut, and there might be a better, "proper" + way of setting this up. If there is I'd love to hear it. -8. **Start Blender**: In VSCodium press ``Ctrl+Shift+P``, and search/select - **Blender: Start**. +7. **Start Blender**: In VSCode/VSCodium press ``Ctrl+Shift+P``, and + search/select **Blender: Start**. -9. **Set the Blender binary path**: The first time you try to start Blender the +8. **Set the Blender binary path**: The first time you try to start Blender the addon will ask for the path of the binary. Navigate to your Blender binary - and select it. For me: + and select it. *For me*: ``/home/steve/Software/blender-git/build_linux/bin/blender`` .. warning:: - Do `not` try to use a binary installed using snap - it will `not` work. - Either install a debian package of Blender, or build it from source, and - use that. + Do `not` try to use a binary installed using snap - it will `not` work. + Either install a debian package of Blender, or build it from source, and + use that. All being well, Blender should start and show the usual Bonsai UI. -10. **Ensure Blender is behaving**: Exercise the interface a bit to be sure - Bonsai is working normally. Add a demo project, add some walls, etc. +9. **Ensure Blender is behaving**: Exercise the interface a bit to be sure + Bonsai is working normally. Add a demo project, add some walls, etc. - One issue I ran in to was opening the wrong folder in step 7. Due to the - way VSCodium works, I was getting two Bonsai plugins conflicting, and - failing in interesting ways. One symptom of this was the modal user - interface when adding walls was completely missing. Oh, and the debugger - completely failed to work. + One issue I ran in to was opening the wrong folder in step 7. Due to the + way VSCode/VSCodium works, I was getting two Bonsai plugins conflicting, + and failing in interesting ways. One symptom of this was the modal user + interface when adding walls was completely missing. Oh, and the debugger + completely failed to work. - If you are happy, quit Blender, and try setting some breakpoints in - VSCodium then run Blender again, and try to trigger them. I set one on - the ``bim.add_sheet`` operator at: - ``extensions/.local/lib/python3.11/site-packages/bonsai/bim/module/drawing/operator.py:1456`` + If you are happy, quit Blender, and try setting some breakpoints in + VSCode/VSCodium then run Blender again, and try to trigger them. I set one + on the ``bim.add_sheet`` operator at: + ``extensions/.local/lib/python3.11/site-packages/bonsai/bim/module/drawing/operator.py:1456`` - .. note:: - I made the mistake of setting the breakpoint on the ``_execute`` - methods ``def`` line, which did not work. This probably helped confuse - me when trying to get the addon to work. + .. note:: + I made the mistake of setting the breakpoint on the ``_execute`` + methods ``def`` line, which did not work. This probably helped confuse + me when trying to get the addon to work. If you get to this point, congratulations! You will now be 1000% more effective when troubleshooting issues, and able to make many more contributions, fixes