69 lines
5.7 KiB
Markdown
69 lines
5.7 KiB
Markdown
```markdown
|
||
# AGENTS.md
|
||
|
||
## Правила для агентов и участников проекта КВС
|
||
|
||
КВС — русскоязычный ассемблер x86-64, написанный на Python, генерирующий ELF-файлы.
|
||
|
||
### Ограничения
|
||
|
||
1. **Никаких регулярных выражений (`re`).**
|
||
Разбор строк — только посимвольно, через циклы и сравнения. Это делает код переносимым на другие языки без изменений логики.
|
||
|
||
2. **Минимум ООП.**
|
||
- Классы **не создавать**. Код пишется процедурно: функции принимают данные, возвращают данные.
|
||
|
||
3. **Изоляция логики важнее DRY.**
|
||
Если модуль может быть автономным — он должен быть автономным. Допустимо дублирование кода ради независимости модуля от других. Пример: кодировщики фиксированного и переменного размера содержат копии функций, чтобы не импортировать их и оставаться полностью самостоятельными.
|
||
|
||
4. **Русские названия везде, кроме ELF.**
|
||
- Внутри компилятора — русские имена секций, директив, регистров, инструкций.
|
||
- В ELF-файле — стандартные латинские имена (`.text`, `.data`, `.bss`).
|
||
- Имена файлов, переменных и функций в коде — **английские** (кроме русифицированных скриптов верхнего уровня).
|
||
|
||
### Структура проекта
|
||
|
||
```
|
||
квс_сборка.py — Главный сборочный скрипт (запускает все проходы по порядку)
|
||
квс_лексер.py — Лексер (исходник → токены)
|
||
квс_парсер.py — Парсер (токены → AST)
|
||
квс_проход1.py — Первый проход: генерация CSV с заглушками для неизвестных меток
|
||
квс_проход2.py — Второй проход: разрешение меток (замена заглушек на реальные адреса)
|
||
квс_проход3.py — Третий проход: подстановка констант в команды
|
||
квс_проход4.py — Четвёртый проход: перекодирование инструкций с подставленными значениями
|
||
квс_проход5.py — Пятый проход: генерация корректных таблиц секций для совместимости с toolchain
|
||
квс_проход6.py — Шестой проход: постобработка и сортировка CSV для визуального анализа
|
||
квс_финсбор.py — Сборщик ELF (CSV → исполняемый файл)
|
||
kvs_data.py — Общие константы и данные (регистры, инструкции, функции)
|
||
kvs_encoder.py — Фасад кодировщика (реэкспорт из fixsize + mutsize)
|
||
kvs_encoder_fixsize.py — Кодировщик инструкций фиксированного размера
|
||
kvs_encoder_mutsize.py — Кодировщик инструкций переменного размера + диспетчер
|
||
```
|
||
|
||
### Русификация
|
||
|
||
**Русифицированы (пользовательская часть):**
|
||
- Имена скриптов верхнего уровня: `квс_*.py` (кроме `квс_финсбор.py`, `квс_сборка.py`)
|
||
- Комментарии и документация в большинстве файлов
|
||
- Пользовательский синтаксис: инструкции, регистры, директивы
|
||
|
||
**Остались на английском:**
|
||
- Имена файлов: `kvs_data.py`, `kvs_encoder.py`, `kvs_encoder_fixsize.py`, `kvs_encoder_mutsize.py`
|
||
- Внутренние имена переменных, констант и функций внутри этих файлов
|
||
- Технические идентификаторы в коде (ключи словарей, имена функций)
|
||
|
||
### Стиль
|
||
|
||
- Комментарии и документация — на русском (в русифицированных файлах).
|
||
- Имена функций — `snake_case`, осмысленные.
|
||
- Размеры инструкций — явные числа, никаких `suffix`-трюков.
|
||
- Каждая директива резервирования — отдельная ветка `if`, а не словарь.
|
||
- Для файлов, оставшихся на английском (`kvs_*.py`), комментарии допустимы на русском или английском — по усмотрению автора.
|
||
|
||
### Важно
|
||
|
||
- `kvs_build.py` переименован в `квс_сборка.py` — используйте актуальное имя.
|
||
- `kvs_builder.py` переименован в `квс_финсбор.py`.
|
||
- Все проходы (`kvs_pass*.py`) переименованы в `квс_проход*.py`.
|
||
- Кодировщики и `kvs_data.py` **не переименованы** — их имена остались на английском.
|
||
``` |