Merge pull request #3139 from pareenaverma/content_review

Update the gcc baremetal cross-compile instructions

Author: pareenaverma

content/install-guides/gcc/arm-gnu.md

@@ -19,9 +19,11 @@ weight: 4
 
 ## Before you begin
 
-Arm GNU Toolchain is a community-supported, pre-built GNU compiler toolchain for Arm-based CPUs.
+Arm GNU Toolchain is a community-supported, pre-built GNU compiler toolchain for Arm-based CPUs. This guide covers installing the toolchain directly from the [Arm GNU Toolchain downloads page](https://developer.arm.com/downloads/-/arm-gnu-toolchain-downloads), which is the recommended approach for bare-metal and embedded targets such as `arm-none-eabi`.
 
-There are many versions of the [Arm GNU Toolchain](https://developer.arm.com/Tools%20and%20Software/GNU%20Toolchain) available. In general, the latest version is recommended for use, as this will contain the latest optimization improvements, as well as support for the latest Arm IP.
+If you need a cross-compiler targeting Arm Linux (for example `aarch64-linux-gnu` or `arm-linux-gnueabihf`), see the [Cross-compiler](../cross) install guide instead, which installs those toolchains via the Linux package manager.
+
+There are many versions of the [Arm GNU Toolchain](https://developer.arm.com/Tools%20and%20Software/GNU%20Toolchain) available. In general, the latest version is recommended, as this will contain the latest optimization improvements and support for the latest Arm IP.
 
 However there are reasons you may wish to use earlier compiler versions, so older versions are also available.
 
@@ -45,18 +47,6 @@ Download the correct toolchain variant for your development needs from the [Arm
 
 ## How do I install the Arm GNU Toolchain on Linux?
 
-### Use package installer
-
-Many Linux distributions make the toolchain available with their package installers. However they may not be the latest versions or desired variant.
-```command
-sudo apt update
-sudo apt install gcc-arm-none-eabi
-```
-
-If the installed version does not meet your needs, you can install another Arm GNU Toolchain version.
-
-### Manual install {#manual}
-
 Unpack the downloaded file to the install directory. The exact file name will depend on the flavor selected.
 
 ```console
@@ -148,7 +138,7 @@ Double-click on the installer, such as  `arm-gnu-toolchain-15.2.rel1-mingw-w64-i
 To install silently from the command line, use similar to the following:
 
 ```console
- msiexec /i arm-gnu-toolchain-<version>--mingw-w64-i686-arm-none-eabi.msi EULA=1 /quiet
+ msiexec /i arm-gnu-toolchain-<version>-mingw-w64-i686-arm-none-eabi.msi EULA=1 /quiet
 ```
 
 The zip package is a backup to Windows installer for those who cannot run the installer. You can unzip the package and then run the tools directly.
@@ -161,12 +151,12 @@ To use the Arm GNU Toolchain in conjunction with [Arm Development Studio](https:
 
 ## Get started
 
-To verify the installation is correct enter:
+To verify the installation is correct, enter:
 ```console
 arm-none-eabi-gcc -v
 ```
 
-Additional examples are included in the toolchain installation at:
+Additional examples are included in the toolchain installation. If you installed to `$HOME` using the example above, you can find them at:
 ```console
-${install_dir}/share/gcc-arm-none-eabi/samples
+$HOME/arm-gnu-toolchain-15.2.rel1-aarch64-arm-none-eabi/share/doc/gcc-arm-none-eabi/examples
 ```

content/install-guides/gcc/cross.md

@@ -18,51 +18,46 @@ weight: 3
 ---
 GCC is available on all Linux distributions and can be installed using the package manager.
 
-This covers `gcc` and `g++` for compiling C and C++ as a cross-compiler targeting the Arm architecture.
+This covers `gcc` and `g++` for compiling C and C++ as a cross-compiler targeting the Arm Linux architecture. For bare-metal and embedded targets such as `arm-none-eabi`, see the [Arm GNU Toolchain](../arm-gnu) install guide.
 
 ## Before you begin
 
-GCC is often used to cross-compile software for Arm microcontrollers and embedded devices which have firmware and other low-level software. The executables are `arm-none-eabi-gcc` and `arm-none-eabi-g++`.
-
-GCC is also used to cross compile Linux applications. Applications can be compiled for 32-bit or 64-bit Linux systems.
+GCC is used to cross-compile Linux applications targeting Arm. Applications can be compiled for 32-bit or 64-bit Arm Linux systems.
 
 The executables for 32-bit are `arm-linux-gnueabihf-gcc` and `arm-linux-gnueabihf-g++`.
 
 The executables for 64-bit are `aarch64-linux-gnu-gcc` and `aarch64-linux-gnu-g++`.
 
-Software can be compiled on an `x86` or `Arm` host machine.
+Software can be compiled on an `x86_64` or `Arm` host machine.
 
 ## How do I download a GCC cross compiler targeting Arm?
 
-The Linux package manager will download the required files so there are no special download instructions.
+The Linux package manager downloads the required files. No manual download is needed.
 
 ## How do I install a GCC cross compiler on Linux?
 
 You can install a GCC cross compiler with Arm as a target architecture using Linux package managers.
 
 ### Installing on Debian based distributions such as Ubuntu
 
-Use the `apt` command to install software packages on any Debian based Linux distribution.
+Use the `apt` command to install the cross-compilers for 32-bit and 64-bit Arm Linux targets.
 
 ```bash { target="ubuntu:latest" }
 sudo apt update
-sudo apt install gcc-arm-none-eabi -y
 sudo apt install gcc-arm-linux-gnueabihf -y
 sudo apt install gcc-aarch64-linux-gnu -y
 ```
 
+The GCC version installed is tied to your Ubuntu release. For example, Ubuntu 24.04 LTS provides GCC 13 and Ubuntu 25.10 provides GCC 15. This is normal Ubuntu packaging behaviour.
+
 ### Installing on Fedora
 
 Fedora uses the `dnf` package manager.
 
-To install the most common development tools use the commands below.
-
 - If the machine has `sudo` you can use it:
 
   ```bash { target="fedora:latest" }
   sudo dnf update -y
-  sudo dnf install arm-none-eabi-gcc-cs -y
-  sudo dnf install arm-none-eabi-newlib -y
   sudo dnf install gcc-aarch64-linux-gnu -y
   sudo dnf install gcc-arm-linux-gnu -y
   ```
@@ -71,35 +66,28 @@ To install the most common development tools use the commands below.
 
   ```console
   dnf update -y
-  dnf install arm-none-eabi-gcc-cs -y
-  dnf install arm-none-eabi-newlib -y
   dnf install gcc-aarch64-linux-gnu -y
   dnf install gcc-arm-linux-gnu -y
   ```
 
-## How do I install a GCC cross compiler on macOS?
-
-You can install a GCC cross compiler with Arm as a target architecture using Homebrew, a package manager for macOS (and Linux).
-
-```console
-brew install arm-none-eabi-gcc
-```
+On Fedora, only building kernels is currently supported. Support for cross-building user space programs is not currently provided, as that would massively multiply the number of packages.
 
 ## Setting up product license {#license}
 
 GCC is open source and freely available for use.
 
 ## Get started {#start}
 
-To confirm the installation is successful, enter:
+To confirm the installations are successful, enter:
 
-```bash
-arm-none-eabi-gcc --version
+```bash { target="ubuntu:latest" }
+aarch64-linux-gnu-gcc --version
+arm-linux-gnueabihf-gcc --version
 ```
 
-To compile an example program, create a text file named `hello-world-embedded.c` with the contents below.
+To cross-compile an example program, create a text file named `hello-world.c` with the contents below.
 
-```C { file_name="hello-world-embedded.c" }
+```C { file_name="hello-world.c" }
 #include <stdio.h>
 
 int main()
@@ -109,20 +97,14 @@ int main()
 }
 ```
 
-To compile hello-world as a bare-metal application:
-
-```bash { target="ubuntu:latest" }
-arm-none-eabi-gcc --specs=rdimon.specs hello-world-embedded.c -o hello-world.elf
-```
-
-To cross-compile hello-world as a 32-bit Linux application. On Fedora, only building kernels is currently supported. Support for cross-building user space programs is not currently provided as that would massively multiply the number of packages.
+To cross-compile for a 64-bit Arm Linux target. On Fedora, only building kernels is currently supported, so these examples apply to Ubuntu.
 
 ```bash { target="ubuntu:latest" }
-arm-linux-gnueabihf-gcc  hello-world-embedded.c -o hello-world.elf
+aarch64-linux-gnu-gcc hello-world.c -o hello-world-aarch64.elf
 ```
 
-To cross-compile hello-world as a 64-bit Linux application. On Fedora, only building kernels is currently supported. Support for cross-building user space programs is not currently provided as that would massively multiply the number of packages.
+To cross-compile for a 32-bit Arm Linux target:
 
 ```bash { target="ubuntu:latest" }
-aarch64-linux-gnu-gcc hello-world-embedded.c -o hello-world.elf
+arm-linux-gnueabihf-gcc hello-world.c -o hello-world-arm.elf
 ```