python-cc 0.0.5__tar.gz → 0.0.6__tar.gz

python_cc-0.0.6/AGENTS.md

@@ -0,0 +1,258 @@
+# AGENTS.md
+
+This file is for humans and AI agents working in this repository.
+
+## Project Summary
+
+`pcc` is a C compiler implemented in Python on top of `pycparser`, `llvmlite`, and a lightweight fake-libc layer. Most fixes in this repository are not parser bugs; they are semantic bugs that only show up when expressions are combined, lowered to LLVM IR, and then exercised by real programs.
+
+The fastest way to get useful results is:
+
+1. Reproduce with a tiny C program when possible.
+2. Compare against a native compiler built from the same source.
+3. Add one small regression test and one realistic integration confirmation.
+
+
+## Environment Rules
+
+- Use `uv run ...` for Python entrypoints. Do not rely on bare `python`; local `pyenv` state may not match the repository.
+- For reproducible runs, prefer unsetting `LC_ALL`:
+
+```bash
+env -u LC_ALL uv run pytest -q
+env -u LC_ALL uv run python - <<'PY'
+print("ok")
+PY
+env -u LC_ALL uv run pcc hello.c
+```
+
+- While debugging one failure, prefer `-n0` so xdist does not hide ordering or temp-file problems.
+- Use `rg` / `rg --files` for source discovery.
+- Do not leave temporary `.c` files inside real project directories. Directory-based source collection can accidentally compile them.
+
+
+## Repository Map
+
+- `pcc/pcc.py`
+  Command-line entrypoint.
+- `pcc/project.py`
+  Directory collection, `--sources-from-make`, and translation-unit selection.
+- `pcc/evaluater/c_evaluator.py`
+  Preprocessing, parsing, IR generation, LLVM parsing, optimization, and execution.
+- `pcc/codegen/c_codegen.py`
+  Main semantic lowering logic. Most tricky C correctness bugs land here.
+- `utils/fake_libc_include/`
+  Fake libc headers. Bugs here usually look like host ABI or declaration mismatches.
+- `tests/`
+  Fast regression coverage. Add small tests here for every semantic fix.
+- `projects/lua-5.5.0/`
+  Real-program stress target. Very effective for catching interactions missed by unit tests.
+
+
+## Source Collection Modes
+
+The repository has multiple ways to compile projects. Be explicit about which one you are debugging.
+
+- Single-file mode:
+  Compile exactly one `.c` file.
+- Merged directory mode:
+  The default directory path behavior. It concatenates selected `.c` files into one large translation unit.
+- `--separate-tus`:
+  Compile each `.c` as its own translation unit, then link at the LLVM/module layer.
+- `--sources-from-make GOAL`:
+  Use `make -nB GOAL` to discover which `.c` files belong to a target.
+
+For Lua, these are the most useful entrypoints:
+
+```bash
+env -u LC_ALL uv run pcc projects/lua-5.5.0/onelua.c -- projects/lua-5.5.0/testes/math.lua
+env -u LC_ALL uv run pcc --sources-from-make lua projects/lua-5.5.0 -- projects/lua-5.5.0/testes/math.lua
+env -u LC_ALL uv run pcc --separate-tus --sources-from-make lua projects/lua-5.5.0 -- projects/lua-5.5.0/testes/math.lua
+```
+
+
+## Debugging Playbook
+
+### 1. Make the failure deterministic
+
+Do not start by reading all of `c_codegen.py`. First make the failure repeatable.
+
+Examples:
+
+- fix the random seed
+- replace filesystem/time input with constants
+- run with `-n0`
+- isolate one test file instead of a whole suite
+
+If the failure is random, your first job is to remove randomness from the reproduction, not to guess the cause.
+
+
+### 2. Compare `pcc` against native from the same source
+
+When the bug appears in a real program:
+
+1. Compile the same source with `pcc`
+2. Compile the same source with the system C compiler
+3. Compare behavior, not assumptions
+
+This separates "the program is odd" from "the compiler lowered it incorrectly".
+
+
+### 3. Shrink the reproducer in stages
+
+A productive sequence is:
+
+1. failing integration test
+2. smaller script or input
+3. small C harness that calls the same internal code path
+4. pure C expression or arithmetic reproducer
+
+Do not stop at step 1 if the failure is deep in semantics. The time you spend shrinking the reproducer is usually returned many times over during diagnosis.
+
+
+### 4. Test hypotheses by substitution, not only by inspection
+
+If a large function is suspect:
+
+- copy it into a temporary harness
+- replace one helper at a time with the real implementation
+- reintroduce branches incrementally
+
+This is often faster than staring at 500 lines of codegen or IR.
+
+
+### 5. Separate data-layout bugs from expression-semantics bugs
+
+When a real program fails, two common classes are:
+
+- ABI/layout bugs
+  `sizeof`, `offsetof`, fake libc declarations, struct or union layout
+- expression-semantics bugs
+  signedness, promotions, comparisons, shifts, division/remainder, aggregate copy, control flow
+
+If layout is suspicious, build a dedicated probe with `sizeof` and `offsetof` and compare native vs `pcc`. Once layout matches, move on.
+
+
+### 6. Prefer downstream-sensitive regression tests
+
+A good regression test does not just check "the bits look right right now". It checks an expression in a context where the next operation would be wrong if semantic metadata were lost.
+
+Good examples:
+
+- unsigned expression followed by `%` with a signed constant
+- unsigned expression followed by `>>`
+- unsigned expression used in `<`, `>`, `/`, `%`
+
+This matters because LLVM uses the same integer types for signed and unsigned values. The compiler must preserve signedness intent itself.
+
+
+## Signedness Model
+
+This repository lowers both `int` and `unsigned int` to LLVM `i32`. Therefore signedness is tracked separately in `pcc/codegen/c_codegen.py`.
+
+Important helpers:
+
+- `_tag_unsigned`
+- `_clear_unsigned`
+- `_is_unsigned_val`
+- `_convert_int_value`
+- `_usual_arithmetic_conversion`
+- `_shift_operand_conversion`
+
+When you add or change an expression form, ask:
+
+1. Does this produce an integer result?
+2. If yes, should the result remain unsigned?
+3. Will that result later feed `%`, `/`, `>>`, comparisons, or another arithmetic conversion?
+
+The classic failure mode in this repository is:
+
+- the immediate value bits are correct
+- but the returned IR value is no longer marked unsigned
+- so a later operator uses `sdiv`, `srem`, `ashr`, or signed comparison
+
+This class of bug is easy to miss with toy tests and shows up quickly in Lua, libc-heavy code, and control-flow-heavy programs.
+
+
+## Common Pitfalls
+
+- Prefix operators on unsigned values:
+  `++x` / `--x` must preserve unsignedness on the expression result.
+- Bitwise operators on unsigned values:
+  `&`, `|`, `^`, `~`, shifts, and compound assignments must preserve unsignedness where C requires it.
+- Assignment expressions:
+  The stored value and the expression result are both semantically meaningful.
+- Temporary probe files:
+  Putting `foo_tmp.c` inside a project directory can accidentally change project collection behavior.
+- Fake libc changes:
+  These can fix or break real programs without touching parser or codegen.
+
+
+## Testing Policy
+
+For every semantic bug fix:
+
+1. Add a focused regression test in `tests/`.
+2. Confirm the original realistic reproducer is fixed.
+3. Run the full suite before finishing.
+
+Useful commands:
+
+```bash
+env -u LC_ALL uv run pytest tests/test_unsigned_loads.py -q -n0
+env -u LC_ALL uv run pytest tests/test_lua.py -q -n0
+env -u LC_ALL uv run pytest -q
+```
+
+
+## Definition of Done
+
+Before you stop, confirm all of the following:
+
+- the smallest reproducer passes
+- the original integration scenario passes
+- any temporary debug edits and probe files are removed
+- a regression test exists
+- the full suite is green
+
+
+## Platform-Specific Gotchas (macOS)
+
+- No `/dev/full` — Lua's `files.lua` tests `/dev/full` for write failure. On macOS this device doesn't exist. The test harness patches it out in a temporary copy.
+- Makefile flags — Lua's Makefile uses `-DLUA_USE_LINUX` and `-Wl,-E`. On macOS, override with `MYCFLAGS=-std=c99 -DLUA_USE_MACOSX`, `MYLDFLAGS=`, `MYLIBS=`.
+- `-ldl` — Not needed on macOS (dlopen is in libc), but harmless. The linker warns but still works.
+
+
+## LLVM Version Mismatch
+
+`llvmlite` bundles its own LLVM version, which may be newer than the system `clang`. This matters when pcc writes IR to a file and compiles with `cc -c`:
+
+- LLVM O2 optimizer can emit attributes the system clang doesn't understand: `nuw`, `nneg`, `range()`, `initializes()`, `dead_on_unwind`.
+- For this reason, the test path currently does **not** run LLVM optimization passes. The JIT path (via `evaluate()`) does run O2 and works fine because llvmlite's own LLVM parses its own output.
+- If you need to compile optimized IR with the system compiler, strip these attributes with regex post-processing.
+
+
+## IR Fix Centralization
+
+All IR text-level fixes belong in `postprocess_ir_text()` in `pcc/codegen/c_codegen.py`, **not** in test helpers. This function is used by both the JIT path (`evaluate()`) and the test compilation path. Fixes that only exist in test code will not help `uv run pcc`.
+
+Current fixes in `postprocess_ir_text`:
+- `bitcast int → ptr` → `inttoptr`
+- Python `<ir.Constant>` repr leak → `zeroinitializer`
+- `alloca/load/store void` → removed
+- duplicate switch case values → deduplicated
+- dead code after terminators → removed
+- consecutive empty labels → `br`/`unreachable` inserted
+
+
+## Packaging
+
+- The wheel must include `utils/fake_libc_include/`. Without it, preprocessing fails on install.
+- PyPI package name is `python-cc` (not `pcc`, which is taken).
+- GitHub Actions uses Trusted Publisher (OIDC). The PyPI project name must match `pyproject.toml`'s `name` field exactly.
+
+
+## Additional Reading
+
+- `docs/investigations/lua-sort-random-pivot-signedness.md`
+  Detailed report for a representative real-world debugging session that started as a flaky Lua `sort.lua` failure and ended as an unsigned-expression codegen fix.

{python_cc-0.0.5 → python_cc-0.0.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-cc
-Version: 0.0.5
+Version: 0.0.6
 Summary: Pcc is a c compiler built on python and llvm.
 Project-URL: Homepage, https://github.com/jiamo/pcc
 License-Expression: MIT
@@ -16,9 +16,10 @@ Pcc
 
 What is this?
 --------------------
-Pcc is a C compiler based on ply + pycparser + llvmlite + llvm.
-We can run C programs like Python: `pcc test.c` to run C code.
-Pcc was inspired by: https://github.com/eliben/pykaleidoscope.
+Pcc is a C compiler written in Python, built on cpp + ply + pycparser + llvmlite + llvm.
+Run C programs like Python scripts: `pcc test.c`. Powerful enough to compile and run the full [Lua 5.5.0](https://github.com/lua/lua) interpreter (~30k lines of C).
+
+Inspired by: https://github.com/eliben/pykaleidoscope.
 
 Notice
 --------------------
@@ -41,6 +42,26 @@ pcc --llvmdump test.c              # dump LLVM IR
 pcc myproject/ -- arg1 arg2        # pass args to compiled program
 ```
 
+Use as a Python library:
+
+```python
+from pcc.evaluater.c_evaluator import CEvaluator
+
+pcc = CEvaluator()
+
+# Run main()
+pcc.evaluate(r'''
+#include <stdio.h>
+int main() { printf("Hello from pcc!\n"); return 0; }
+''')
+
+# Call any C function directly
+ret = pcc.evaluate(r'''
+int add(int a, int b) { return a + b; }
+''', entry="add", args=[3, 7])
+print(ret)  # 10
+```
+
 Development
 --------------------
 
@@ -53,16 +74,61 @@ uv run pytest    # run all 500+ tests
 
 Multi-file projects: put `.c` and `.h` files in a directory, one `.c` must contain `main()`. Pcc auto-discovers all `.c` files, merges them, and compiles.
 
-Lua Compilation Goal
+Compiling Lua 5.5.0
 --------------------
 
-The target is to compile and run [Lua 5.5.0](https://github.com/lua/lua) using pcc.
+Pcc can compile the entire [Lua 5.5.0](https://github.com/lua/lua) interpreter (~30k lines of C) and run Lua scripts directly.
+
+For one representative script (`math.lua`), these are the important cases:
+
+```bash
+git clone https://github.com/jiamo/pcc && cd pcc
+uv sync
+
+# 1) Canonical Lua tree in default directory mode: fails
+#    Reason: directory mode merges every .c into one TU, and projects/lua-5.5.0
+#    contains both onelua.c and the individual source files.
+uv run pcc projects/lua-5.5.0 -- projects/lua-5.5.0/testes/math.lua
 
+# 2) Explicit amalgamation mode: works
+uv run pcc projects/lua-5.5.0/onelua.c -- projects/lua-5.5.0/testes/math.lua
+
+# 3) Canonical Lua tree, but collect only the sources used by `make -nB lua`: works
+uv run pcc --sources-from-make lua projects/lua-5.5.0 -- projects/lua-5.5.0/testes/math.lua
+
+# 4) Same make-derived source list, but compile as separate translation units: works
+uv run pcc --separate-tus --sources-from-make lua projects/lua-5.5.0 -- projects/lua-5.5.0/testes/math.lua
+
+# 5) Same separate-TU path, but compile translation units in parallel: works
+uv run pcc --separate-tus --sources-from-make lua --jobs 2 projects/lua-5.5.0 -- projects/lua-5.5.0/testes/math.lua
+
+# 6) Canonical Lua tree with raw --separate-tus: fails
+#    Reason: onelua.c and the individual source files become separate TUs with
+#    duplicate external definitions at link semantics.
+uv run pcc --separate-tus projects/lua-5.5.0 -- projects/lua-5.5.0/testes/math.lua
+
+# Run all 130+ Lua tests (pcc vs native, pcc vs makefile, makefile baseline)
+uv run pytest tests/test_lua.py -v
 ```
-projects/lua-5.5.0/         - Lua 5.5.0 source code + Makefile
+
+```
+projects/lua-5.5.0/         - canonical Lua 5.5.0 source tree, includes onelua.c and the standard multi-file sources
 projects/lua-5.5.0/testes/  - Lua test suite
 ```
 
+Use `projects/lua-5.5.0/onelua.c` when you want Lua's official amalgamation build.
+Use `--sources-from-make lua` when you want `pcc` to follow the same source list
+that Lua's makefile uses for the `lua` target.
+Use `--separate-tus` when you want normal multi-file C semantics: each `.c`
+file is compiled as its own translation unit instead of being merged into one
+big source string first.
+
+In other words:
+
+- default directory mode: merge all selected `.c` files into one TU
+- `--sources-from-make lua`: keep directory mode, but let `make -nB lua` choose which `.c` files participate
+- `--separate-tus`: compile each selected `.c` as a separate TU, then link them together
+
 ### Test Structure
 
 Tests in `tests/test_lua.py` compare three builds:
@@ -131,55 +197,4 @@ Built-in typedefs: `size_t`, `ssize_t`, `ptrdiff_t`, `va_list`, `FILE`, `time_t`
 Supported C Features
 --------------------
 
-### Types
-`int`, `double`, `float`, `char`, `void`, `unsigned`/`signed`/`long`/`short` (all combinations),
-`size_t`, `int8_t`..`uint64_t`,
-pointers (multi-level), arrays (multi-dim),
-structs (named, anonymous, nested, with array/pointer/function-pointer members, pointer-to-struct),
-unions, enums (with constant expressions), typedef (scalar, struct, pointer, function pointer),
-`static` local variables, `const`/`volatile` qualifiers
-
-### Operators
-- Arithmetic: `+` `-` `*` `/` `%`
-- Bitwise: `&` `|` `^` `<<` `>>`
-- Comparison: `<` `>` `<=` `>=` `==` `!=` (including pointer comparison)
-- Logical: `&&` `||` (short-circuit evaluation)
-- Unary: `-x` `+x` `!x` `~x` `sizeof` `&x` `*p`
-- Increment/Decrement: `++x` `x++` `--x` `x--` (int and pointer, including struct members)
-- Assignment: `=` `+=` `-=` `*=` `/=` `%=` `<<=` `>>=` `&=` `|=` `^=` (including pointer `+=`/`-=`)
-- Ternary: `a ? b : c`
-- Pointer: `p + n`, `p - n`, `p - q`, `p++`, `p[i]`
-- Struct access: `.` and `->` (including nested `a.b.c` and `s->fn(args)`)
-- Chained: `a = b = c = 5`
-
-### Control Flow
-`if` / `else` / `else if`, `while`, `do-while`, `for` (all variants including `for(;;)`),
-`switch` / `case` / `default`, `goto` / `label`, `break`, `continue`, `return`
-
-### Functions
-Definitions, forward declarations, mutual recursion, void functions, variadic (`...`),
-pointer/array arguments, `static` local variables, function pointers (declaration, assignment,
-calling, as parameters, in structs, typedef'd), callback patterns
-
-### Libc Functions (133 total, auto-declared on first use)
-
-| Header | Functions |
-|--------|-----------|
-| stdio.h | printf, fprintf, sprintf, snprintf, puts, putchar, getchar, fopen, fclose, fread, fwrite, fseek, ftell, fgets, fputs, scanf, sscanf, ... |
-| stdlib.h | malloc, calloc, realloc, free, abs, labs, atoi, atol, atof, strtol, strtod, rand, srand, exit, abort, qsort, bsearch, getenv, system, ... |
-| string.h | strlen, strcmp, strncmp, strcpy, strncpy, strcat, strncat, strchr, strrchr, strstr, memset, memcpy, memmove, memcmp, memchr, strtok, ... |
-| ctype.h | isalpha, isdigit, isalnum, isspace, isupper, islower, isprint, ispunct, isxdigit, toupper, tolower, ... |
-| math.h | sin, cos, tan, asin, acos, atan, atan2, exp, log, log2, log10, pow, sqrt, cbrt, hypot, ceil, floor, round, trunc, fmod, fabs, ... |
-| time.h | time, clock, difftime |
-| unistd.h | sleep, usleep, read, write, open, close, getpid, getppid |
-| setjmp.h | setjmp, longjmp |
-| signal.h | signal, raise |
-
-### Literals
-Decimal, hex (`0xFF`), octal (`077`), char (`'a'`, `'\n'`), string (`"hello\n"`), double (`3.14`)
-
-### Other
-C comments (`/* */`, `//`), array initializer lists (1D and multi-dim),
-string escape sequences (`\n \t \\ \0 \r`), implicit type promotion (int/char/double/pointer),
-array-to-pointer decay, `NULL` pointer support, opaque/forward-declared structs,
-two-pass codegen (types first, functions second)
+Supports all C99 features needed to compile real-world projects like Lua 5.5.0: all types (int, float, double, char, void, structs, unions, enums, typedefs, pointers, arrays, function pointers), all operators, all control flow (if/else, for, while, do-while, switch, goto), variadic functions, preprocessor directives, and 133 libc functions auto-declared from stdio.h, stdlib.h, string.h, math.h, etc.

python_cc-0.0.6/README.md

@@ -0,0 +1,187 @@
+Pcc
+====================
+
+What is this?
+--------------------
+Pcc is a C compiler written in Python, built on cpp + ply + pycparser + llvmlite + llvm.
+Run C programs like Python scripts: `pcc test.c`. Powerful enough to compile and run the full [Lua 5.5.0](https://github.com/lua/lua) interpreter (~30k lines of C).
+
+Inspired by: https://github.com/eliben/pykaleidoscope.
+
+Notice
+--------------------
+1. Some code skeleton comes from pykaleidoscope.
+2. ply and pycparser are embedded into this project for debug use.
+
+Install
+--------------------
+
+```bash
+pip install python-cc
+```
+
+This gives you the `pcc` command:
+
+```bash
+pcc hello.c                        # compile and run
+pcc myproject/                     # compile all .c files in directory
+pcc --llvmdump test.c              # dump LLVM IR
+pcc myproject/ -- arg1 arg2        # pass args to compiled program
+```
+
+Use as a Python library:
+
+```python
+from pcc.evaluater.c_evaluator import CEvaluator
+
+pcc = CEvaluator()
+
+# Run main()
+pcc.evaluate(r'''
+#include <stdio.h>
+int main() { printf("Hello from pcc!\n"); return 0; }
+''')
+
+# Call any C function directly
+ret = pcc.evaluate(r'''
+int add(int a, int b) { return a + b; }
+''', entry="add", args=[3, 7])
+print(ret)  # 10
+```
+
+Development
+--------------------
+
+Requires Python 3.13+ and [uv](https://docs.astral.sh/uv/).
+
+```bash
+uv sync          # install dependencies
+uv run pytest    # run all 500+ tests
+```
+
+Multi-file projects: put `.c` and `.h` files in a directory, one `.c` must contain `main()`. Pcc auto-discovers all `.c` files, merges them, and compiles.
+
+Compiling Lua 5.5.0
+--------------------
+
+Pcc can compile the entire [Lua 5.5.0](https://github.com/lua/lua) interpreter (~30k lines of C) and run Lua scripts directly.
+
+For one representative script (`math.lua`), these are the important cases:
+
+```bash
+git clone https://github.com/jiamo/pcc && cd pcc
+uv sync
+
+# 1) Canonical Lua tree in default directory mode: fails
+#    Reason: directory mode merges every .c into one TU, and projects/lua-5.5.0
+#    contains both onelua.c and the individual source files.
+uv run pcc projects/lua-5.5.0 -- projects/lua-5.5.0/testes/math.lua
+
+# 2) Explicit amalgamation mode: works
+uv run pcc projects/lua-5.5.0/onelua.c -- projects/lua-5.5.0/testes/math.lua
+
+# 3) Canonical Lua tree, but collect only the sources used by `make -nB lua`: works
+uv run pcc --sources-from-make lua projects/lua-5.5.0 -- projects/lua-5.5.0/testes/math.lua
+
+# 4) Same make-derived source list, but compile as separate translation units: works
+uv run pcc --separate-tus --sources-from-make lua projects/lua-5.5.0 -- projects/lua-5.5.0/testes/math.lua
+
+# 5) Same separate-TU path, but compile translation units in parallel: works
+uv run pcc --separate-tus --sources-from-make lua --jobs 2 projects/lua-5.5.0 -- projects/lua-5.5.0/testes/math.lua
+
+# 6) Canonical Lua tree with raw --separate-tus: fails
+#    Reason: onelua.c and the individual source files become separate TUs with
+#    duplicate external definitions at link semantics.
+uv run pcc --separate-tus projects/lua-5.5.0 -- projects/lua-5.5.0/testes/math.lua
+
+# Run all 130+ Lua tests (pcc vs native, pcc vs makefile, makefile baseline)
+uv run pytest tests/test_lua.py -v
+```
+
+```
+projects/lua-5.5.0/         - canonical Lua 5.5.0 source tree, includes onelua.c and the standard multi-file sources
+projects/lua-5.5.0/testes/  - Lua test suite
+```
+
+Use `projects/lua-5.5.0/onelua.c` when you want Lua's official amalgamation build.
+Use `--sources-from-make lua` when you want `pcc` to follow the same source list
+that Lua's makefile uses for the `lua` target.
+Use `--separate-tus` when you want normal multi-file C semantics: each `.c`
+file is compiled as its own translation unit instead of being merged into one
+big source string first.
+
+In other words:
+
+- default directory mode: merge all selected `.c` files into one TU
+- `--sources-from-make lua`: keep directory mode, but let `make -nB lua` choose which `.c` files participate
+- `--separate-tus`: compile each selected `.c` as a separate TU, then link them together
+
+### Test Structure
+
+Tests in `tests/test_lua.py` compare three builds:
+
+| Build | Method |
+|-------|--------|
+| **pcc** | `onelua.c` → pcc preprocess/parse/codegen → LLVM IR → cc compile+link |
+| **native** | `onelua.c` → `cc -O0` single-file compile |
+| **makefile** | `make` with project Makefile (separate compilation of each .c, static lib + link) |
+
+```bash
+# Run all Lua tests (~25s with auto workers)
+uv run pytest tests/test_lua.py -v
+
+# Individual file compilation through pcc pipeline
+uv run pytest tests/test_lua.py::test_lua_source_compile -v
+# pcc vs native (same onelua.c, test pcc as C compiler)
+uv run pytest tests/test_lua.py::test_pcc_runtime_matches_native -v
+# pcc vs Makefile-built lua (official reference)
+uv run pytest tests/test_lua.py::test_pcc_runtime_matches_makefile -v
+# Lua test suite with Makefile-built binary (baseline)
+uv run pytest tests/test_lua.py::test_makefile_lua_test_suite -v
+```
+
+Note: `heavy.lua` is excluded from automated tests (runs ~2 min+, may timeout). Run manually:
+```bash
+# Build Makefile lua, then run heavy.lua directly
+cd projects/lua-5.5.0 && make CC=cc CWARNS= MYCFLAGS="-std=c99 -DLUA_USE_MACOSX" MYLDFLAGS= MYLIBS=
+./lua testes/heavy.lua
+```
+
+Add C test cases
+--------------------
+
+```bash
+# Single file: add to c_tests/ with expected return value
+echo '// EXPECT: 42
+int main(){ return 42; }' > c_tests/mytest.c
+
+# Multi-file project: create a directory with main.c
+mkdir c_tests/myproject
+# ... add .c and .h files, main.c must have: // EXPECT: N
+
+# Run all C file tests
+uv run pytest tests/test_c_files.py -v
+```
+
+Preprocessor
+--------------------
+
+```c
+#include <stdio.h>          // system headers: 133 libc functions auto-declared
+#include "mylib.h"          // user headers: read and inline file content
+#define MAX_SIZE 100        // object-like macro
+#define MAX(a,b) ((a)>(b)?(a):(b))  // function-like macro
+#define DEBUG               // flag for conditional compilation
+#ifdef / #ifndef / #if / #elif / #else / #endif  // conditional compilation
+#if defined(X) && (VERSION >= 3)  // expression evaluation with defined()
+#undef NAME                 // undefine macro
+```
+
+Built-in macros: `NULL`, `EOF`, `EXIT_SUCCESS`, `EXIT_FAILURE`, `RAND_MAX`, `INT_MAX`, `INT_MIN`, `LLONG_MAX`, `CHAR_BIT`, `true`, `false`, `__STDC__`
+
+Built-in typedefs: `size_t`, `ssize_t`, `ptrdiff_t`, `va_list`, `FILE`, `time_t`, `clock_t`, `pid_t`
+
+Supported C Features
+--------------------
+
+Supports all C99 features needed to compile real-world projects like Lua 5.5.0: all types (int, float, double, char, void, structs, unions, enums, typedefs, pointers, arrays, function pointers), all operators, all control flow (if/else, for, while, do-while, switch, goto), variadic functions, preprocessor directives, and 133 libc functions auto-declared from stdio.h, stdlib.h, string.h, math.h, etc.