44 lines
3.2 KiB
Markdown
44 lines
3.2 KiB
Markdown
|
|
|||
|
|
# AGENTS.md
|
|||
|
|
|
|||
|
|
## Правила для агентов и участников проекта КВС
|
|||
|
|
|
|||
|
|
КВС — русскоязычный ассемблер x86-64, написанный на Python, генерирующий ELF-файлы.
|
|||
|
|
|
|||
|
|
### Ограничения
|
|||
|
|
|
|||
|
|
1. **Никаких регулярных выражений (`re`).**
|
|||
|
|
Разбор строк — только посимвольно, через циклы и сравнения. Это делает код переносимым на другие языки без изменений логики.
|
|||
|
|
|
|||
|
|
2. **Минимум ООП.**
|
|||
|
|
- Существующие классы (`Pass1`, `Pass2`, `Parser`) **не переписывать** без явной команды. Они работают — не трогай.
|
|||
|
|
- Новые классы **не создавать**. Код пишется процедурно: функции принимают данные, возвращают данные.
|
|||
|
|
|
|||
|
|
3. **Изоляция логики важнее DRY.**
|
|||
|
|
Если модуль может быть автономным — он должен быть автономным. Допустимо дублирование кода ради независимости модуля от других. Пример: `kvs_pass2_encoder_mutsize.py` содержит копии функций из `kvs_pass2_encoder_fixsize.py`, чтобы не импортировать их и оставаться полностью самостоятельным.
|
|||
|
|
|
|||
|
|
4. **Русские названия везде, кроме ELF.**
|
|||
|
|
Внутри компилятора — русские имена секций, директив, регистров. В ELF-файле — стандартные латинские имена (`.text`, `.data`, `.bss`).
|
|||
|
|
|
|||
|
|
### Структура проекта
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
kvs_lexer.py — лексер (исходник → токены)
|
|||
|
|
kvs_parser.py — парсер (токены → AST)
|
|||
|
|
kvs_pass1.py — первый проход (размеры секций, адреса меток)
|
|||
|
|
kvs_pass2.py — второй проход (AST + pass1 → CSV с байтами)
|
|||
|
|
kvs_builder.py — сборщик ELF (CSV + pass1 → исполняемый файл)
|
|||
|
|
kvs_data.py — общие константы и данные
|
|||
|
|
kvs_build.py — главный сборочный скрипт (вызывает всё по порядку)
|
|||
|
|
kvs_pass2_encoder_fixsize.py — кодировщик инструкций фиксированного размера
|
|||
|
|
kvs_pass2_encoder_mutsize.py — кодировщик инструкций переменного размера + диспетчер
|
|||
|
|
kvs_pass2_encoder.py — реэкспорт из fixsize + mutsize (совместимость)
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### Стиль
|
|||
|
|
|
|||
|
|
- Комментарии и документация на русском.
|
|||
|
|
- Имена функций — `snake_case`, осмысленные.
|
|||
|
|
- Размеры инструкций — явные числа, никаких `suffix`-трюков.
|
|||
|
|
- Каждая директива резервирования — отдельная ветка `if`, а не словарь.
|