# Standalone Build Migration

## Goal

`GW` is currently built through S32 Design Studio managed build output in `GW/Debug_FLASH`.
That works, but it leaves the project dependent on generated makefiles and Eclipse project refresh.

The long-term target is:

- source and build settings live in the repository
- toolchain and SDK paths come from environment variables
- VS Code and CI use the same build entry point
- adding a new source or header does not require an S32DS build first

## Build Directory Policy

The standalone build directory is now kept inside `GW`:

- S32DS managed build: `GW/Debug_FLASH`
- standalone CMake build: `GW/Debug_STANDALONE`

This is the better layout for this project because:

- all firmware build outputs stay next to the `GW` project
- the directory purpose is obvious from the project tree
- it matches the existing S32DS convention
- it avoids scattering build products across the repository root

## Phase 1

Phase 1 adds a standalone CMake build definition without removing the current S32DS flow.

Files added:

- `GW/CMakeLists.txt`
- `GW/cmake/toolchain-arm-none-eabi.cmake`

This standalone build currently mirrors the existing S32DS build assumptions:

- target MCU: `S32K344`
- compiler family: `arm-none-eabi`
- linker script: `Project_Settings/Linker_Files/linker_flash.ld`
- RTD / Platform SDK: `SW32K3_RTD_4_4_0_9_0_D2103`

## Required Environment Variables

Set these before configuring the standalone build:

- `ARM_GCC_BIN_DIR`
  - directory that contains `arm-none-eabi-gcc`
- `S32_SDK_PATH`
  - directory that contains `SW32K3_RTD_4_4_0_9_0_D2103`

Example on the current machine:

```powershell
setx ARM_GCC_BIN_DIR "C:\NXP\S32DS.3.4\S32DS\build_tools\gcc_v9.2\gcc-9.2-arm32-eabi\bin"
setx S32_SDK_PATH "C:\NXP\S32DS.3.4\S32DS\software\PlatformSDK_S32K3_2021_03"
```

Optional:

- `ARM_GCC_SYSROOT`
  - only needed if `arm-none-eabi-gcc -print-sysroot` does not return the correct value

## Configure and Build

This requires `cmake` to be installed and available on `PATH`.

```powershell
$env:ARM_GCC_BIN_DIR="C:\NXP\S32DS.3.4\S32DS\build_tools\gcc_v9.2\gcc-9.2-arm32-eabi\bin"
$env:S32_SDK_PATH="C:\NXP\S32DS.3.4\S32DS\software\PlatformSDK_S32K3_2021_03"
$toolchain = (Resolve-Path "GW/cmake/toolchain-arm-none-eabi.cmake").Path.Replace('\\','/')
$make = (Get-Command mingw32-make).Source.Replace('\\','/')

cmake -S GW -B GW/Debug_STANDALONE -G "MinGW Makefiles" -DCMAKE_TOOLCHAIN_FILE="$toolchain" -DCMAKE_MAKE_PROGRAM="$make"
cmake --build GW/Debug_STANDALONE -- -j4
```

On the current machine, `MinGW Makefiles` works with `mingw32-make.exe`.
If `ninja` exists on another machine, the configure step can switch to `-G Ninja`.

## VS Code Tasks

The workspace now includes standalone tasks in `.vscode/tasks.json`.

- `GW Configure (Standalone)`
- `GW Build (Standalone)`
- `GW Clean (Standalone)`
- `GW Rebuild (Standalone)`

`Ctrl+Shift+B` now runs `GW Rebuild (Standalone)` by default.

## Why This Helps

Compared with `GW/Debug_FLASH/makefile`:

- source discovery is now repository-driven
- include directories are collected from the repository tree instead of stale generated makefiles
- linker options are explicit in version-controlled files

## Current Validation Snapshot

The current standalone build has been validated against the existing S32DS `Debug_FLASH` output on this machine.

- `arm-none-eabi-size` result matches exactly
- both builds generate `GW.elf`, `GW.map`, and `GW.srec`
- file hashes differ, so binary layout or metadata is still not bit-for-bit identical

Observed size comparison:

```text
text    data     bss     dec     hex
187040  5292   152948  345280  544c0
```

## Known Gaps In Phase 1

Phase 1 is intentionally conservative. It still needs validation in these areas:

- every compile option exactly matches S32DS output
- no source file needs a unique option beyond the current common set
- no generated source folder is missing from the standalone source list
- final `GW.elf`, `GW.map`, and `GW.srec` match the S32DS build closely enough

## Phase 2

After the standalone build configures successfully, the next step is to compare it against the current S32DS build:

1. compare source lists
2. compare compiler flags
3. compare linker flags
4. compare output size and section layout
5. decide whether `GW/Debug_FLASH` can stop being the default build path