# AGENTS.md - Coding Guidelines for AROS Example Projects

This document provides guidance for agentic coding systems working in with AROS (AROS Research OS) codebase.

## Build System

Use standard Makefile approach.

### Build Commands

Use cross-compiler available in path. The cross-compiler suite has prefix x86_64-aros-
Do not strip the binaries. Do not use x86_64-aros-strip

### Testing

Testing is performed manually on AROS systems or emulators (WinUAE, FS-UAE).

### Debugging

When user reports an error in program don't try to reason the root cause just from source code in project directory.
In addition:
- Look at the source code of available examples and validate with API documentation
- Add debug logging with bug() function and ask the use to paste back the debug log for you to analyze
- Always use bug() function for debug logging, never use printf() for debug logging

### Environment Information

- GCC cross-compiler toolchain for AROS target: x86_64-aros-gcc, x86_64-aros-g++, etc.
- Root of AROS SDK is at [INSERT-SDK-ROOT]
- AROS headers available in 'Development/include' subdirectory of the SDK
- Main includes for libraries can be found in 'Development/include/proto' subdirectory of the SDK
- AROS linker libraries available in 'Development/lib' subdirectory of the SDK
- AROS API documentation available at 'Autodocs' subdirectory of the SDK
- AROS examples available in 'Examples' subdirectory of the SDK

---

## Code Style Guidelines

### General

- **Use AROS libraries**: `exec`, `dos`, `graphics`, `intuition`, `MUI/ZUNE (muimaster)`
- **Programming languance**: C

### Includes

- **Order**: System includes first (`<exec/types.h>`, `<proto/...>`), then local includes (quoted)
- **Format**: Use angle brackets `<>` for system headers, quotes `""` for local headers
- **Debug header**: Always include debug support at the top after copyright:
  ```c
  #define DEBUG 0
  #include <aros/debug.h>
  ```
- **Guard headers**: Use header guards with uppercase and underscores:
  ```c
  #ifndef _FILENAME_H_
  #define _FILENAME_H_
  /* content */
  #endif /* _FILENAME_H_ */
  ```

### Formatting

- **Indentation**: Spaces (not tabs), 4 spaces per level
- **Line length**: No strict limit, but keep readable (~80-100 chars preferred)
- **Braces**: **BSD style** (opening brace on new line)
  ```c
  BOOL ReadArguments(int argc, char **argv)
  {
      if (argc)
      {
          return TRUE;
      }
  }
  ```
- Space after keywords: `if (`, `while (`, `for (`
- No space after function names: `ReadArgs()` not `ReadArgs ()`
- **Comments**: Use `//` for single-line, `/* */` for multi-line
- **Section separators**: Use comment blocks with asterisks for major sections:
  ```c
  /*********************************************************************************************/
  ```

### Types and Variables

- **Use AROS types**: `BOOL`, `STRPTR`, `IPTR`, `UWORD`, `LONG`, `VOID` instead of C types
- **Naming**: PascalCase for types/structs, snake_case for variables, UPPERCASE for macros
  ```c
  struct AslEditor_DATA { ... }
  static BOOL retval = FALSE;
  #define MSG_WINDOW_TITLE 1
  ```
- **Type declarations**: Declare variables at function start or closest scope
- **Strings**: Strings can be put directly in code as literals or you can use defines. `"` for string do not have to be escaped.

### Functions

- **Naming**: PascalCase with module prefix, double underscores for method-like functions
  ```c
  void Locale_Initialize(void);
  static IPTR AslStringify__OM_NEW(Class *cl, Object *obj, struct opSet *msg);
  ```
- **Parameters**: Pointer types on the same line, no trailing star
  ```c
  BOOL ReadArguments(int argc, char **argv);
  ```
- **Return early**: Use early returns to reduce nesting

### Naming Conventions

| Category | Convention | Example |
|----------|-----------|---------|
| Files | lowercase with underscores | `asl_editor.c` |
| Functions | PascalCase with prefix | `Prefs_Load()`, `Locale_Initialize()` |
| Macros | UPPERCASE with underscores | `DEBUG`, `ID_PREF` |
| Types/Structs | PascalCase with suffix | `struct AslPrefs` |
| Variables | snake_case or camelCase | `retval`, `pScreen` |
| Constants | UPPERCASE | `MSG_WINDOW_TITLE`, `PREFS_PATH_ENV` |

### MUI-Specific Code

- **Objects**: Use `Object *` type
- **Macros**: Use provided MUI macros for object creation
  ```c
  ApplicationObject, MUIA_Application_Title, title, End
  ```
- **Tags**: Use TAG_USER-based tag definitions for custom classes
  ```c
  #define MUIB_AsllsStringify (TAG_USER | 0x20000000)
  ```

### Version Information

Include version strings in applications:

```c
#define VERSION "$VER: Asl 41.1 (30.04.2023) AROS Dev Team"
```

### Documentation

- **Inline comments**: Explain "why", not "what"; keep brief
- **Function purposes**: Document complex functions with comment blocks above
- **FIXME comments**: Mark unfinished work with `// FIXME: Description`
  ```c
  // FIXME: We want some sanity checking here!
  ```

