Differences

This shows you the differences between two versions of the page.

--- getting_started [2025/08/14 09:14] – [Installation instructions (Manual)] asie
+++ getting_started [2026/06/03 14:34] (current) – asie
@@ Line 1: / Line 1: @@
-====== Getting Started ======
+====== Installation ======
-The Wonderful toolchain can currently be installed on:
+The following platforms are supported as of writing:
-  * Linux
+  * Windows 10 or above,
-  * Windows (via MSYS2)
+  * Linux with a recent kernel version (x86-64 and AArch64 architectures supported).
-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.
+Other platforms, such as macOS, are not currently supported. On such platforms, you may wish to set up a Linux container or virtual machine.
-===== Linux =====
+===== Windows =====
-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: ''%%sudo mkdir /opt/wonderful%%''. Other installation locations are not supported at this time.
-    - On typical Linux installations, ''/opt'' can be only written to by the root user. This is why ''sudo'' is used here to elevate permissions.
-  - Give permissions to ''/opt/wonderful'' to your current user: ''%%sudo chown -R "$USER" /opt/wonderful%%''.
-    - This allows all subsequent commands, including ''wf-pacman'' updates, to be executed without elevated permissions.
-  - 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.)
+  - Download the [[https://wonderful.asie.pl/bootstrap/wf-bootstrap-windows-x86_64.exe|Installer (x86_64)]] and run it.
-  - Run ''Wonderful Toolchain Shell'' from the Start menu.
+    - If you've changed the MSYS2 installation directory, make sure to also change it in Wonderful's installer.
+  - Run ''Wonderful Toolchain Shell'' from the Start Menu.
+    - Remember to use this option to launch the Wonderful shell! Using the default MSYS2 shells will not initialize environment variables correctly, leading to programs and toolchains not working correctly.
-This approach is a little experimental, so if it doesn’t work for you, feel free to try the Manual steps below.
+Once complete, follow to the [[getting_started:finish|post-installation guide]]. Manual installation instructions are available [[getting_started:windows|here]].
-==== Installation instructions (Manual) ====
+===== Linux =====
-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%%''
+  - Download the [[https://wonderful.asie.pl/bootstrap/wf-installer.sh|Installer]] script.
+  - Run it from your shell: ''%%chmod +x wf-installer.sh && ./wf-installer.sh%%''
+  - Follow the instructions.
-===== macOS =====
+Once complete, follow to the [[getting_started:finish|post-installation guide]]. Manual installation instructions are available [[getting_started:linux|here]].
-Native macOS support is currently not available. For the time being, it is recommended to use a Linux virtual machine.