MultiversX tools on Windows / troublehooting

docs/sdk-and-tools/sdk-py/installing-mxpy.md

@@ -7,7 +7,9 @@ title: Installing mxpy
 
 This page describes how to install **mxpy** (the CLI tool). The recommended way to install **mxpy** is by using **pipx**. If you want to learn more about **pipx** you can check out [this page](https://pipx.pypa.io/stable/#overview-what-is-pipx).
 
-**mxpy** is currently supported on Linux and MacOS. Some of its features might work on Windows as well, although using **mxpy** on Windows is neither recommended, nor supported at this time.
+:::note
+If you'd like to use **mxpy** on Windows, we recommend installing it within the [Windows Subsystem for Linux (WSL)](https://learn.microsoft.com/en-us/windows/wsl/install). If you experience an issue, please follow the [troubleshooter](/sdk-and-tools/troubleshooting/multiplatform).
+:::
 
 [comment]: # (mx-context-auto)
 
@@ -28,22 +30,25 @@ You'll need **pipx** installed on your machine. For more details on how to insta
 In order to install **mxpy** using `pipx`, run the following command:
 
 ```sh
-pipx install multiversx-sdk-cli
+pipx install multiversx-sdk-cli --force
 ```
 
 This will simply install the latest version available.
 
 In case you want to install a specific version you should also specify the version.
+
 ```sh
-pipx install multiversx-sdk-cli==9.2.0
+pipx install multiversx-sdk-cli==9.5.1
 ```
 
 You can also install **mxpy** directly from a GitHub branch. Replace `branch_name` with your desired branch and run the following command:
+
 ```sh
 pipx install git+https://github.com/multiversx/mx-sdk-py-cli@branch_name
 ```
 
 To check that **mxpy** installed successfully you can run the following command:
+
 ```sh
 mxpy --version
 ```
@@ -53,6 +58,7 @@ mxpy --version
 ## **Upgrade mxpy using pipx**
 
 To upgrade **mxpy** to a newer version you can simply run the following command:
+
 ```sh
 pipx upgrade multiversx-sdk-cli
 ```
@@ -68,7 +74,7 @@ wget -O mxpy-up.py https://raw.githubusercontent.com/multiversx/mx-sdk-py-cli/ma
 python3 mxpy-up.py
 ```
 
-Running the above will create a Python virtual environment in `~/multiversx-sdk/mxpy-venv`, it will install the package [`multiversx-sdk-cli`](https://pypi.org/project/multiversx-sdk-cli) into this environment, and it will create the shortcut `~/multiversx-sdk/mxpy`. 
+Running the above will create a Python virtual environment in `~/multiversx-sdk/mxpy-venv`, it will install the package [`multiversx-sdk-cli`](https://pypi.org/project/multiversx-sdk-cli) into this environment, and it will create the shortcut `~/multiversx-sdk/mxpy`.
 
 The `mxpy` shortcut is not automatically added to your **`$PATH`** environment variable, so **you'll need to configure that manually** (see below).
 

docs/sdk-and-tools/troubleshooting/multiplatform.md

@@ -0,0 +1,50 @@
+---
+id: multiplatform
+title: MultiversX tools on multiple platforms
+---
+
+Generally speaking, the MultiversX tools should work on all platforms. However, platform-specific issues can occur. This page aims to be an entry point for troubleshooting platform-specific issues, in regards to the MultiversX toolset.
+
+:::note
+If you discover a platform-specific issue, please let us known, on the [corresponding GitHub repository](/sdk-and-tools/overview).
+
+If you are blocked by a platform-specific issue, please consider using a **devcontainer**, as described [here](/sdk-and-tools/devcontainers).
+:::
+
+## Linux
+
+All tools are expected to work on Linux. They are generally tested on Ubuntu-based distributions.
+
+## MacOS
+
+All tools are expected to work on MacOS. Though, even if the tests within the continous integration flows cover MacOS, some inconveniences might still occur.
+
+### Apple Silicon (M1, M2)
+
+As of February 2024, the Node can only be compiled using the AMD64 version of Go. Thus, dependent tools, such as [localnets](/developers/setup-local-testnet.md), the [Chain Simulator](/sdk-and-tools/chain-simulator.md) etc. will rely on the [Apple Rosetta binary translator](https://en.wikipedia.org/wiki/Rosetta_(software)).
+
+:::note
+As of February 2024, a native ARM64 version of the Node is in the works. This will allow the dependent tools to run natively on Apple Silicon.
+:::
+
+If you'd like to manually build a Go tool that only works on AMD64 (for now), download & extract the Go toolchain for AMD64. For example:
+
+```sh
+wget https://go.dev/dl/go1.20.7.darwin-amd64.tar.gz
+tar -xf go1.20.7.darwin-amd64.tar.gz
+```
+
+Then, export `GOPATH` and `GOENV` variables into your shell:
+
+```sh
+export GOPATH=/(path to extracted toolchain)/go
+export GOENV=/(path to extracted toolchain)/go/env
+```
+
+Afterwards, build the tools, as needed. The obtained binaries will be AMD64, and they will run on your ARM64 system.
+
+## Windows
+
+Some tools can be difficult to install or run **directly on Windows**. For example, when building smart contracts, the encountered issues might be harder to tackle, especially for beginners. 
+
+Therefore, we recommend using the [Windows Subsystem for Linux (WSL)](https://learn.microsoft.com/en-us/windows/wsl/install), instead of running the tools directly on Windows. 

sidebars.js

@@ -316,7 +316,8 @@ const sidebars = {
         items: [
           "sdk-and-tools/troubleshooting/troubleshooting",
           "sdk-and-tools/troubleshooting/rust-setup",
-          "sdk-and-tools/troubleshooting/ide-setup"
+          "sdk-and-tools/troubleshooting/ide-setup",
+          "sdk-and-tools/troubleshooting/multiplatform",
         ],
       }
     ],