Differences

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

--- getting_started [2024/11/14 14:53] – created asie
+++ getting_started [2025/08/15 06:19] (current) – asie
@@ Line 1: / Line 1: @@
-====== Getting Started ======
+====== Installation ======
 The Wonderful toolchain can currently be installed on:
@@ Line 23: / Line 23: @@
 ==== Installation instructions ====
-  - Create the ''/opt/wonderful'' directory: ''mkdir /opt/wonderful''. Other installation locations are not supported at this time.
+  - Create the ''/opt/wonderful'' directory: ''%%sudo 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''.
+    - On typical Linux installations, ''/opt'' can be only written to by the root user. This is why ''sudo'' is used here to elevate permissions.
-  - Extract the bootstrap to ''/opt/wonderful'': ''cd /opt/wonderful/ && tar xzvf [path_to_bootstrap_tar_gz]''.
+  - Give permissions to ''/opt/wonderful'' to your current user: ''%%sudo chown -R "$USER" /opt/wonderful%%''.
-  - Add ''/opt/wonderful/bin'' to ''PATH'': ''export PATH=/opt/wonderful/bin:$PATH''.
+    - This allows all subsequent commands, including ''wf-pacman'' updates, to be executed without elevated permissions.
-  - Export ''WONDERFUL_TOOLCHAIN'' to point to ''/opt/wonderful'': ''export WONDERFUL_TOOLCHAIN=/opt/wonderful''.
+  - Extract the bootstrap to ''/opt/wonderful'': ''%%cd /opt/wonderful/ && tar xzvf [path_to_bootstrap_tar_gz]%%''.
-  - Run ''wf-pacman -Syu'' (no sudo - you don’t need root!) to synchronize and update the toolchain’s package manager.
+  - 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 ====
@@ Line 61: / Line 63: @@
   - 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''.
+  - 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.
+  - 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]'').
+  - 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'').
+  - 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.
-  - 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 ''%%source /opt/wonderful/bin/wf-env%%'' to configure the toolchain's environment variables.
-  - Run ''wf-pacman -Syu'' to synchronize and update the toolchain’s package manager.
+    - See ''Configuration -> Environment variables'' for more information.
-==== Alternative: Windows (via WSL2) ====
+==== 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''
+  * 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%%''.
+  * 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.