====== 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 [[https://discord.gg/CR7MCZNurp|our Discord server]] to chat with fellow Wonderful users - an IRC bridge may be provided in the future, if user demand exists.

===== Linux =====

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.

==== Downloads ====

  * [[https://wonderful.asie.pl/bootstrap/wf-bootstrap-x86_64.tar.gz|Bootstrap (x86_64)]]
  * [[https://wonderful.asie.pl/bootstrap/wf-bootstrap-aarch64.tar.gz|Bootstrap (AArch64)]]

==== Installation instructions ====

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

==== Troubleshooting ====

  * 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).

===== Windows (via MSYS2) =====

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.

==== Installation instructions (Installer) ====

Required files:

  * [[https://wonderful.asie.pl/bootstrap/wf-bootstrap-windows-x86_64.exe|Installer (x86_64)]]

  - Install [[https://www.msys2.org/|the MSYS2 environment]].
  - 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.)
  - 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.

==== Installation instructions (Manual) ====

Required files:

  * [[https://wonderful.asie.pl/bootstrap/wf-bootstrap-windows-x86_64.tar.gz|Bootstrap (x86_64, .tar.gz)]]

  - Install [[https://www.msys2.org/|the MSYS2 environment]].
  - From the Start Menu, launch the MSYS UCRT64 shell. This shell is used to interact with the toolchain (make, wf-wswantool, etc).
  - Install some useful packages: ''pacman -S base-devel ca-certificates''.
  - Create the ''/opt/wonderful'' directory: ''mkdir /opt/wonderful''. Other installation locations are not supported at this time.
  - Extract the bootstrap to ''/opt/wonderful'' (f.e. ''cd /opt/wonderful/ && tar xzvf [path_to_bootstrap_tar_gz]'').
  - Add ''/opt/wonderful/bin'' to PATH (f.e. ''export PATH=/opt/wonderful/bin:$PATH'').
  - 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.
  - Run ''wf-pacman -Syu'' to synchronize and update the toolchain’s package manager.

==== Alternative: Windows (via WSL2) ====

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''

===== macOS =====

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