Differences

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

--- getting_started [2025/08/30 14:55] – asie
+++ getting_started [2026/06/03 14:34] (current) – asie
@@ Line 1: / Line 1: @@
 ====== Installation ======
-First, select your preferred platform:
+The following platforms are supported as of writing:
-  * [[getting_started:windows|Windows]]
+  * Windows 10 or above,
-  * [[getting_started:linux|Linux]] (x86_64, AArch64)
+  * Linux with a recent kernel version (x86-64 and AArch64 architectures supported).
-Other platforms, like macOS, are not currently supported.
+Other platforms, such as macOS, are not currently supported. On such platforms, you may wish to set up a Linux container or virtual machine.
-The Wonderful toolchain can currently be installed on:
+===== Windows =====
-  * Linux
+  - Install [[https://www.msys2.org/|the MSYS2 environment]].
-  * Windows (via MSYS2)
+  - Download the [[https://wonderful.asie.pl/bootstrap/wf-bootstrap-windows-x86_64.exe|Installer (x86_64)]] and run it.
+    - 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.
-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.
+Once complete, follow to the [[getting_started:finish|post-installation guide]]. Manual installation instructions are available [[getting_started:windows|here]].
 ===== Linux =====
-To install Wonderful on your computer, you will need:
+  - 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%%''
-  * a Linux distribution released sometime in the last decade (maybe a bit more),
+  - Follow the instructions.
-  * 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]%%''.
-  - 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.
-  - Run ''%%source /opt/wonderful/bin/wf-env%%'' to configure the toolchain's environment variables.
-    - See ''Configuration -> Environment variables'' for more information.
-==== 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]%%'').
-  - 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.
-  - Run ''%%source /opt/wonderful/bin/wf-env%%'' to configure the toolchain's environment variables.
-    - See ''Configuration -> Environment variables'' for more information.
-==== Alternative options ====
-These are not recommended and are less tested, but have been used successfully by some users.
-=== 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.
-====== Configuration ======
-===== Environment variables =====
-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%%''.
+Once complete, follow to the [[getting_started:finish|post-installation guide]]. Manual installation instructions are available [[getting_started:linux|here]].
-  * 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.