Fix Build Errors

Goal

Systematically diagnose and resolve build errors (compiler, linker, configuration) in an S32DS project.

Tools Used

• search_actions - call FIRST to discover available actions; the returned catalog includes each action's input schema
• execute_action - invoke any discovered action via execute_action(action_name="X", params={...}); the static start_tool action brings the IDE up if it is not running
• The waitForJob action (via execute_action) - blocks until a named async job completes

Before You Start

Call search_actions(query="...") first to discover all available actions, their descriptions, and input schemas (a parameterless search_actions() browses everything). Use the returned catalog to determine correct action names and required/optional parameters before calling execute_action.

Guardrails

Scope

• Only edit files in the target project that are implicated by the Problems view. Never modify generated folders (generate/, board/) or unrelated projects.

Resource limits

• Cap the fix/rebuild loop (about 10 iterations). If errors are not converging, stop and report the remaining errors instead of looping indefinitely.

Refuse-and-escalate

• If an error stems from missing generated code, route to s32ds-safe-code-regen instead of hand-editing generated output.
• If the root cause is unclear, stop and ask the user rather than guessing edits that could introduce regressions.

Prerequisites

• Project must exist and be open in the workspace

• Read s32ds-analyze-project skill first if unfamiliar with the project structure

• Read s32ds-build-and-debug skill to understand the build workflow

Decision Tree

START -> execute_action(action_name="getProblems", params={"severity": "error"})
  │
  ├─ No errors found?
  │    -> Project may need rebuild: execute_action(action_name="buildProject", params={...}) first
  │
  ├─ Errors reference generated files (e.g. under generate/, board/, etc.)?
  │    -> .mex file exists in project?
  │         YES -> Run "Update Code and Build" (see s32ds-safe-code-regen skill)
  │         NO  -> Generated code is stale/missing - check SDK attachment
  │
  ├─ Compiler errors (file.c / file.h references)?
  │    -> Go to Error Catalog: Compiler Errors section
  │
  ├─ Linker errors ("undefined reference", "multiple definition")?
  │    -> Go to Error Catalog: Linker Errors section
  │
  └─ Configuration errors (nature/builder/toolchain issues)?
       -> Go to Error Catalog: Configuration Errors section

Steps

1. Get Project Context

• Tool: execute_action(action_name="getProjectInfo", params={"projectName": "<name>"})
• Purpose: Understand toolchain, natures, builders, active build config
• Key fields to note:
  • natures - confirms CDT/C/C++ project type
  • buildConfigs - active configuration (Debug/Release)
  • builders - what build system is configured
  • mcuInfo - target MCU (affects available peripherals and headers)

2. Check for .mex Files

• Tool: Use file system search to check if .mex files exist anywhere in the project
• Purpose: Determines if project uses S32 Configuration Tools for code generation
• Decision:
  • If .mex files exist: Generated code depends on config tool output. Errors in generated files require Update Code and Build, NOT manual edits
  • If no .mex files: Project uses manually written or SDK-provided code only

3. Retrieve All Errors

• Tool: execute_action(action_name="getProblems", params={"projectName": "<name>", "severity": "error"})
• Purpose: Get the full error list with file paths, line numbers, and messages
• Categorize errors into:
  • Compiler errors (source file references, syntax, type errors)
  • Linker errors ("undefined reference", "multiple definition", memory overflow)
  • Configuration errors (missing toolchain, bad paths, nature issues)

4. Read Problematic Source Files

• Tool: read_file on each file referenced in errors
• Purpose: Understand the code context around each error
• Tips:
  • Read 20-30 lines around the error line for context
  • Check #include statements at the top of the file
  • Look for conditional compilation (#ifdef) that might exclude needed code

5. Apply Fixes Based on Error Type

• Compiler errors: Edit source files directly with replace_in_file
• Linker errors: May require build configuration changes or adding source files
• Generated code errors: Do NOT edit generated files - fix the .mex configuration or run Update Code
• Missing SDK headers: Verify SDK attachment with execute_action(action_name="getProjectSdks", params={"projectName": "<name>"})

6. Rebuild and Verify

• Tool: execute_action(action_name="buildProject", params={"projectName": "<name>"})
• Then: execute_action(action_name="waitForJob", params={"jobName": "Build", "timeoutMs": 120000})
• Then: execute_action(action_name="getProblems", params={"projectName": "<name>", "severity": "error"})
• Expected: Error count should decrease or reach zero
• If new errors appear: Some fixes may expose previously hidden errors (e.g., fixing a header include reveals type errors in newly-visible code)

7. Iterate If Needed

• Repeat steps 3-6 until all errors are resolved
• If stuck on a specific error, search documentation:
  • semantic_search(query="<error message or concept>", corpus="all")

Error Catalog

Compiler Errors

Error Pattern	Likely Cause	Fix
fatal error: <file>.h: No such file or directory	Missing include path or SDK not attached	Verify SDK: execute_action(action_name="getProjectSdks", params={"projectName": "<name>"}). Check include paths in project settings
error: implicit declaration of function '<name>'	Missing #include for the function's header	Add the correct #include statement
error: undefined reference to type '<name>'	Missing include or typedef not in scope	Add include or check conditional compilation flags
error: incompatible types	Wrong type passed to function or assigned	Check function signature and fix the type mismatch
error: expected ';' before ...	Syntax error - missing semicolon, brace, or paren	Check the line above the error for the actual missing character
error: redefinition of '<name>'	Same symbol defined in multiple places	Remove duplicate or guard with #ifndef
warning treated as error	-Werror flag promotes warnings to errors	Fix the underlying warning, or adjust compiler flags if appropriate

Linker Errors

Error Pattern	Likely Cause	Fix
undefined reference to '<function>'	Function declared but not defined; source file not in build	Add the .c file containing the definition to the build, or link the correct library
multiple definition of '<symbol>'	Same symbol defined in multiple .c files (not static)	Make one definition, use extern in headers, or add static for file-local
region '<name>' overflowed by N bytes	Code/data exceeds available flash/RAM	Optimize code size (-Os), reduce static allocations, check linker script regions
cannot find -l<library>	Library not in linker search path	Add library path to linker settings or verify SDK installation
undefined reference to '_exit' / '_sbrk'	Missing newlib/syscalls stubs	Ensure the project links nosys specs or provides stubs

Configuration Errors

Error Pattern	Likely Cause	Fix
Program "arm-none-eabi-gcc" not found in PATH	Toolchain not configured or not installed	Check S32DS toolchain installation, verify PATH in build environment
make: *** No rule to make target '<file>'	Source file referenced in build but deleted/moved	Remove stale reference from build configuration or restore the file
Build configuration not found	Active config deleted or corrupted	Check buildConfigs in project info, recreate if needed

Common Patterns

• Pattern: Errors only in generated code -> Never edit generated files manually. Run "Update Code and Build" or fix the .mex configuration. See the s32ds-safe-code-regen skill for the correct workflow.
• Pattern: Hundreds of errors after SDK update -> SDK version mismatch. Check execute_action(action_name="getProjectSdks", params={"projectName": "<name>"}) and compare with expected version. May need to re-attach correct SDK version.
• Pattern: Errors disappear after clean+rebuild -> Stale object files. See the s32ds-clean-and-rebuild skill workflow.
• Pattern: Errors only in Release but not Debug -> Different optimization levels expose different warnings-as-errors or undefined behavior. Compare compiler flags between configurations.
• Pattern: "file not found" after project import -> Include paths may be relative and broken. Check project includes against actual file locations.

Related Skills

• s32ds-build-and-debug - complete build + debug workflow (read BEFORE building)
• s32ds-clean-and-rebuild - when stale artifacts cause phantom errors
• s32ds-analyze-project - understand project structure before fixing
• s32ds-check-sdk-compatibility - when errors stem from SDK version mismatch
• s32ds-safe-code-regen - when errors are in generated code (.mex projects)

Notes

• Always check if errors are in generated code before editing - generated files will be overwritten on next code generation
• The getProblems action (via execute_action) returns markers from the last successful build; if no build has run, it may show stale results
• Some projects use -Werror which turns all warnings into errors - check compiler flags
• Multicore projects may have separate build configurations per core - ensure you're building the correct one
• After fixing linker "undefined reference" errors, the fix often requires adding a .c file to the build, not editing existing code

Anti-Patterns (Do NOT)

• Do NOT manually edit files under generate/, board/, or other generated directories - they will be overwritten
• Do NOT assume a single rebuild will reveal all errors - fix iteratively as later errors may be masked
• Do NOT change linker scripts without understanding memory map implications for the target MCU
• Do NOT ignore warnings in the error list - they often indicate the root cause of subsequent errors
• Do NOT skip the .mex check - building without code generation on a .mex project guarantees errors