First, select your preferred platform:

• Windows
• Linux (x86_64, AArch64)

Other platforms, like macOS, are not currently supported.

The Wonderful toolchain can currently be installed on:

• Linux
• Windows (via MSYS2)

Once you’re done following this tutorial, feel free to install the necessary tools for the target of your choice by following the target-specific instructions.

To install Wonderful on your computer, you will need:

• a Linux distribution released sometime in the last decade (maybe a bit more),
• a CPU architecture compatible with x86_64 or AArch64,
• the following command-line tools provided by your distribution: bash, git, make.

• Bootstrap (x86_64)
• Bootstrap (AArch64)

1. Create the /opt/wonderful directory: sudo mkdir /opt/wonderful. Other installation locations are not supported at this time.
   1. On typical Linux installations, /opt can be only written to by the root user. This is why sudo is used here to elevate permissions.
2. Give permissions to /opt/wonderful to your current user: sudo chown -R "$USER" /opt/wonderful.
   1. This allows all subsequent commands, including wf-pacman updates, to be executed without elevated permissions.
3. Extract the bootstrap to /opt/wonderful: cd /opt/wonderful/ && tar xzvf [path_to_bootstrap_tar_gz].
4. Run /opt/wonderful/bin/wf-pacman -Syu wf-tools (no sudo - you don’t need root!) to synchronize and update the toolchain’s package manager.
5. Run source /opt/wonderful/bin/wf-env to configure the toolchain's environment variables.
   1. See Configuration → Environment variables for more information.

• If you run into error setting certificate file: /etc/ssl/certs/ca-certificates.crt while trying to use wf-pacman, you may need to install your distribution’s SSL certificates package (f.e. ca-certificates on Debian).

To install Wonderful on your computer, you will need:

• a recent version of Windows - Windows 10 and above are supported,
• a CPU architecture compatible with x86_64.

Required files:

• Installer (x86_64)

1. Install the MSYS2 environment.
2. Install the Wonderful toolchain from the above installer. (If you’ve installed MSYS2 to a different directory than C:\msys64, adjust it in the Wonderful installer to match.)
3. Run Wonderful Toolchain Shell from the Start menu.

This approach is a little experimental, so if it doesn’t work for you, feel free to try the Manual steps below.

Required files:

• Bootstrap (x86_64, .tar.gz)

1. Install the MSYS2 environment.
2. From the Start Menu, launch the MSYS UCRT64 shell. This shell is used to interact with the toolchain (make, wf-wswantool, etc).
3. Install some useful packages: pacman -S base-devel ca-certificates.
4. Create the /opt/wonderful directory: mkdir /opt/wonderful. Other installation locations are not supported at this time.
5. Extract the bootstrap to /opt/wonderful (f.e. cd /opt/wonderful/ && tar xzvf [path_to_bootstrap_tar_gz]).
6. Run /opt/wonderful/bin/wf-pacman -Syu wf-tools (no sudo - you don’t need root!) to synchronize and update the toolchain’s package manager.
7. Run source /opt/wonderful/bin/wf-env to configure the toolchain's environment variables.
   1. See Configuration → Environment variables for more information.

These are not recommended and are less tested, but have been used successfully by some users.

Since WSL2 is compatible with Linux, one can follow the Linux installation instructions to get Wonderful running on top of Windows this way.

• If you run into error: could not open file: /etc/mtab: No such file or directory while trying to use wf-pacman, the following command can create the missing file: sudo ln -s /proc/self/mounts /etc/mtab

Native macOS support is currently not available. For the time being, it is recommended to use a Linux virtual machine.

To make accessing Wonderful easy, you may want to pre-populate the environment variables in your shell on launch:

• For bash, add source /opt/wonderful/bin/wf-env to your ~/.profile.
• For fish, add . /opt/wonderful/bin/wf-env.fish to your Fish configuration.
• For zsh, add source /opt/wonderful/bin/wf-env to your ~/.zprofile.

Alternatively, you may want to alias wf-env to allow them to be easily added when needed:

• For bash, add alias wf-env='source /opt/wonderful/bin/wf-env' to your ~/.profile.
• For fish, add alias wf-env . /opt/wonderful/bin/wf-env.fish to your Fish configuration.
• For zsh, add alias wf-env='source /opt/wonderful/bin/wf-env' to your ~/.zprofile.

If you want to access toolchain components (like ia16-elf-gcc or arm-none-eabi-objdump) directly, you may wish to add the -a argument.