suicmez/tests/codegen/README.md

# Codegen Tests

This directory contains test cases for the suicmez compiler's code generation (codegen) phase. Each test demonstrates different language features and their corresponding C output.

## Test Files

### Basic Tests

#### `test_executable.sui` / `test_executable.c`
**Purpose:** Simple executable test with basic integer arithmetic
**Features:**
- Basic function definitions
- Integer variables and operations
- Return statements

**Run:**
```bash
suicmez tests/codegen/test_executable.sui
gcc tests/codegen/test_executable.c -o test_executable
./test_executable
```

#### `test_array_simple.sui` / `test_array_simple.c`
**Purpose:** Test heap-allocated arrays with indexing
**Features:**
- Array literals: `[1, 2, 3]`
- Array indexing: `arr[0]`
- Arrays as pointers: `int*`
- C99 compound literals for array initialization

**Output:**
```
| int* arr = (int[]){1, 2, 3} | 
 0x...
| int x = arr[0] | 
 1
```

#### `test_enum_simple.sui` / `test_enum_simple.c`
**Purpose:** Test enum types with discriminant + union pattern
**Features:**
- Enum variants
- Discriminant field for pattern matching
- Union-based storage for variant data
- Proper struct ordering

**Generated Structures:**
```c
struct Color_Red { };
struct Color_Green { };
struct Color_Blue { };
struct Color_union {
    struct Color_Red red;
    struct Color_Green green;
    struct Color_Blue blue;
};
struct Color {
    int discriminant;
    struct Color_union data;
};
```

### Comprehensive Tests

#### `test_comprehensive.sui` / `test_comprehensive.c`
**Purpose:** Combined test of all major features
**Features:**
- Stack-allocated types: `int`, `float`, `bool`
- Heap-allocated types: arrays, strings
- Struct instantiation and field access
- Enum creation and initialization
- Function calls with multiple parameters
- Complex expressions

**Demonstrates:**
- Proper memory management distinctions
- Type conversions and initializations
- Debug output for each statement

**Run:**
```bash
suicmez tests/codegen/test_comprehensive.sui
gcc tests/codegen/test_comprehensive.c -o test_comprehensive
./test_comprehensive
```

**Sample Output:**
```
| int x = 10 | 
 10
| int y = 20 | 
 20
| int sum = add(x, y) | 
 30
| struct Point p = (struct Point){ .x = 5, .y = 15 } | 
 5
| int* arr = (int[]){1, 2, 3, 4, 5} | 
 0x7ffd6d57d0b0
| int first = arr[0] | 
 1
| char* msg = "hello" | 
 hello
```

#### `test_all_types.sui` / `test_all_types.c`
**Purpose:** Exhaustive test of all language types
**Features:**
- All primitive types: `int`, `float`, `bool`
- Strings with heap allocation
- Structs with multiple fields
- Enums with discriminant
- Arrays with indexing

**Run:**
```bash
suicmez tests/codegen/test_all_types.sui
gcc tests/codegen/test_all_types.c -o test_all_types
./test_all_types
```

## Memory Management Strategy

The codegen implements the following allocation strategy:

### Stack-Allocated (Copyable)
- `int`, `float`, `bool`, `char` - passed by value
- Structs (stored directly, not as pointers)
- Enums (stored directly with discriminant + union)

### Heap-Allocated (with Debug Visibility)
- **Arrays**: `int*` pointers created with C99 compound literals
  ```c
  int* arr = (int[]){1, 2, 3, 4, 5};
  ```
- **Strings**: `char*` pointers to string constants
  ```c
  char* msg = "hello";
  ```

## Debug Output Feature

Every statement generates debug output showing:
1. The executed statement
2. The resulting value (if applicable)

**Format:**
```c
int x = 10;
printf("| int x = 10 | \n %d\n", x);
```

**Output:**
```
| int x = 10 | 
 10
```

### Format Specifiers

The system automatically selects the correct format:
- `%d` - integers and booleans
- `%f` - floats
- `%s` - strings (char*)
- `%p` - pointers and arrays

## Compilation

All generated C code compiles with standard C99:
```bash
gcc -std=c99 <file>.c -o <executable>
```

## Running Tests Manually

```bash
# Generate C code from .sui file
suicmez tests/codegen/test_comprehensive.sui

# Compile the generated C code
gcc tests/codegen/test_comprehensive.c -o /tmp/test_comprehensive

# Run with debug output
/tmp/test_comprehensive
```

## Expected Behavior

All tests should:
1. ✅ Compile successfully with GCC
2. ✅ Generate valid C99 code
3. ✅ Execute without errors
4. ✅ Display debug output for each statement
5. ✅ Return correct exit codes

## Implementation Notes

- Structs are declared before enums in the output to avoid forward references
- Enum variant structs are generated before the union
- Array types use C99 compound literals for initialization
- All pointers are properly typed (not generic `void*`)
- Debug output uses `printf` with appropriate format specifiers