diff --git a/docs/sdk-and-tools/sdk-py/installing-mxpy.md b/docs/sdk-and-tools/sdk-py/installing-mxpy.md index 0d38d8325..1b30e9508 100644 --- a/docs/sdk-and-tools/sdk-py/installing-mxpy.md +++ b/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). diff --git a/docs/sdk-and-tools/troubleshooting/multiplatform.md b/docs/sdk-and-tools/troubleshooting/multiplatform.md new file mode 100644 index 000000000..6043ae449 --- /dev/null +++ b/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. diff --git a/sidebars.js b/sidebars.js index d575cbf4c..6a43aebb5 100644 --- a/sidebars.js +++ b/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", ], } ],