Getting Started

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. You may also want to visit our Discord server to chat with fellow Wonderful users - an IRC bridge may be provided in the future, if user demand exists.

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: mkdir /opt/wonderful. Other installation locations are not supported at this time.
2. Give permissions to /opt/wonderful to the correct user: chown -R [user] /opt/wonderful.
3. Extract the bootstrap to /opt/wonderful: cd /opt/wonderful/ && tar xzvf [path_to_bootstrap_tar_gz].
4. Add /opt/wonderful/bin to PATH: export PATH=/opt/wonderful/bin:$PATH.
5. Export WONDERFUL_TOOLCHAIN to point to /opt/wonderful: export WONDERFUL_TOOLCHAIN=/opt/wonderful.
6. Run wf-pacman -Syu (no sudo - you don’t need root!) to synchronize and update the toolchain’s package manager.

• 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. Add /opt/wonderful/bin to PATH (f.e. export PATH=/opt/wonderful/bin:$PATH).
7. Export WONDERFUL_TOOLCHAIN to point to /opt/wonderful (f.e. export WONDERFUL_TOOLCHAIN=/opt/wonderful). It is a good idea to add these exports to the end of ~/.profile - this way, they will be automatically applied every time you restart the shell.
8. Run wf-pacman -Syu to synchronize and update the toolchain’s package manager.

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.