docs(suite): bcrypto build troubleshooting

Author: Lemonexe

.gitignore

@@ -158,3 +158,6 @@ packages/suite-data/files/translations/master.json
 # cypress download folder
 
 packages/suite-web/e2e/downloads
+
+# python virtualenv, some Linux users may need it for workaround
+.venv

README.md

@@ -10,7 +10,7 @@ Welcome to the Trezor Suite repository! This repository contains the source code
 
 # Development
 
-Development is not possible on Windows. This can be circumvented by tools such as [WSL](https://learn.microsoft.com/en-us/windows/wsl/install), see our [guide](https://docs.trezor.io/trezor-suite/misc/WSL.html).
+Development is not possible on Windows. This can be circumvented by tools such as [WSL](https://learn.microsoft.com/en-us/windows/wsl/install), see our [guide](https://docs.trezor.io/trezor-suite/misc/development-on-windows.html).
 
 ### Prerequisities
 
@@ -28,6 +28,8 @@ Development is not possible on Windows. This can be circumvented by tools such a
 -   `yarn`
 -   `yarn build:libs`
 
+For troubleshooting of common issues, [see guide](https://docs.trezor.io/trezor-suite/misc/suite-setup-troubleshooting.html).
+
 It's recommended to enable `git config --global submodule.recurse true` so you don't need to run `git submodule update --init --recursive` every time when submodules are updated.
 
 > You don't need a Trezor device to get into the app, you can use emulator. There is a [Trezor User Env](https://github.com/trezor/trezor-user-env) to help you set it up and run emulator for any Trezor model 🎉

docs/SUMMARY.md

@@ -88,4 +88,5 @@
     -   [development on Windows](./misc/development-on-windows.md)
     -   [device naming](./misc/device-naming.md)
     -   [review](./misc/review.md)
+    -   [suite setup troubleshooting](./misc/suite-setup-troubleshooting)
     -   [videos](./misc/videos.md)

docs/misc/development-on-windows.md

@@ -19,6 +19,8 @@ In WSL:
 
 Proceed with the [general readme instructions](../../README.md#trezor-suite-trezorsuite).
 
+See general [setup troubleshooting docs](./suite-setup-troubleshooting.md) if necessary.
+
 ## Connecting USB device
 
 On Windows, run `usbipd list`, find the bus id of the Trezor device, e.g. `2-1`.

docs/misc/suite-setup-troubleshooting.md

@@ -0,0 +1,39 @@
+# Suite setup troubleshooting
+
+This document is a guide to overcome common issues with Trezor Suite local dev environment setup.
+
+The setup happy path is described in the main [Suite README](https://github.com/trezor/trezor-suite).
+
+### bcrypto fails yarn install
+
+#### Issue
+
+On Linux, comamnd `yarn` fails with a similar error:
+
+```
+bcrypto@npm:5.4.0 couldn't be built successfully (exit code 1, logs can be found here: /tmp/something.log
+```
+
+And the mentioned logfile contains: `ModuleNotFoundError: No module named 'distutils'`
+
+#### Solution
+
+In trezor-suite root directory, run:
+
+```
+python3 -m venv .venv
+source .venv/bin/activate
+pip install setuptools
+yarn
+deactivate
+```
+
+When you need it next time in future, repeat the same, but **without** the first command (`python3 -m venv .venv`), because virtualenv has already been created.
+
+#### Explanation
+
+`bcrypto` is a native module that requires `node-gyp` to build, which in turn requires python `gyp`.
+However, `bcrypto` relies on the deprecated Python2 build method, and the built-in `distutils` package, which has been removed in Python 3.12.
+Installing `setuptools` via pip solves this, as it also provides legacy `distutils`...
+but on Linux Ubuntu you can't pip install globally, as it's managed by apt, and there is no apt package anymore which would solve it.
+Though you can install `setuptools` in a virtual environment (a.k.a. venv), and yarn then uses it.