Как читать репозиторий и как участвовать

Репозиторий — github.com/digitable-lol/flang. Всё ниже сверено с веткой main на выпуске 0.7.29. Компилятор в нём один, и он написан на самом flang; второй реализации на JavaScript, о которой говорили ранние версии этого курса, в дереве больше нет.

Что где лежит

Карта корня — docs/repository-layout.ru.md; главное из неё:

bootstrap/      компилятор, уже переведённый в C99, и его Makefile: «make -C bootstrap» собирает двоичный
flang/          язык: self/ (компилятор), stdlib/, core/, proof/, concurrency/, ct/, src/emit/ (рантаймы целей), test/
docs/examples/  программы на flang по наборам: leetcode, rosetta, crypto, db, io, wal, web и другие
docs/flang/     контракты языка — по SPEC.md на слой
docs/guide/     руководства: как писать, ограничения, настройки, установленная библиотека
docs/editors/   языковой сервер, подсветка для Vim и VS Code
packaging/      формула Homebrew, плагин asdf, страница man, проверки установки
fspec/          бизнес-правила, записанные доказанными спецификациями
scripts/        проверки дерева, сборка выпуска, журнал изменений

Внутри flang/:

• flang/self/ — компилятор: лексер, разбор, типы, завершаемость, ядро доказательств, вычислитель и по модулю кодогенерации на каждую цель (emit-c.flang, emit-go.flang и так далее);
• flang/stdlib/ — стандартная библиотека на flang: списки, строки, числа, множества, словари, JSON, UTF-8, даты, драйверы postgres и sqlite, сеть (http, tls-client, redis), криптография (aes, sha256, hmac, rsa, ecdsa), Юникод. Её же использует установленный flang: в готовой сборке она лежит в share/flang/stdlib;
• flang/proof/ — проверка доказательств: независимая программа на C flang/proof/checker/checker.c и вторая, на Lean 4, flang/proof/checker/second/;
• flang/src/emit/ — рантаймы десяти целевых языков. Они копируются в вывод flang emit как есть;
• flang/test/ — проверки, написанные на flang.

Маршрут чтения

1. README.md — что значит «формально доказуемо» в этом языке и чего это не значит, установка, первая программа.
2. docs/flang/SPEC.md — спецификация, около 2000 строк. Обязательны разделы о двух классах функций, о типах и о семантике значений (таблица «Семантика, которая обязана совпадать у всех слоёв»).
3. docs/guide/limits.ru.md — чего язык сегодня не умеет и что делать вместо этого. Короткий и честный список.
4. flang/stdlib/optional.flang — около 200 строк, читается как образец стиля: тип «Возможно» от «А», функции с примерами и постусловиями.
5. flang/self/interpret.flang, первые сто строк — типы машины вычислителя: кадры, стопка, счётчики (глава «Интерпретатор»).
6. docs/trust-gaps.ru.md — чему доверяет компилятор: какие звенья между исходником и работающей программой проверены, а какие приняты на слово.
7. docs/flang/self/SPEC.md — как устроен компилятор на самом языке и какие формы вычислитель пока не считает.

Файлы, которые не стоит читать целиком: flang/self/parser.flang (8368 строк), flang/self/totality.flang (5329), flang/self/interpret.flang (4499). В них ходят с конкретным вопросом.

Искать по дереву стоит с grep -a: AGENTS.md объясняет, что файл с нулевым байтом часть утилит молча считает двоичным и пропускает, отвечая так же, как на честное «совпадений нет».

Сборка

git clone https://github.com/digitable-lol/flang && cd flang
make -C bootstrap -j8
bootstrap/flang --version

Нужны только компилятор C99 и make. В bootstrap/ лежит компилятор, уже переведённый в C, поэтому один make даёт рабочий bootstrap/flang. У нас сборка выпуска 0.7.29 заняла 173 секунды при пике памяти около 2,3 ГиБ.

Важная деталь: правка в flang/self/ в собранный двоичный сама не попадает. Чтобы она туда доехала, компилятор должен заново перевести свои исходники в C (sh scripts/bootstrap-reprint.sh), и это занимает часы на одном ядре. bootstrap/ правят только этим скриптом, не руками.

Проверки

sh flang/test/обход.sh                   # проверки, написанные на flang
bootstrap/flang test flang/stdlib/       # примеры стандартной библиотеки
sh scripts/bootstrap-reprint.sh --check  # bootstrap/ совпадает с исходниками
git config core.hooksPath .githooks      # хук перед push: быстрые проверки

Первая команда на выпуске 0.7.29 у нас прошла чисто за 96 секунд:

$ sh flang/test/обход.sh
…
обходчик: чисто — проверок 211, сошлись все 211

Обходчик сверяет не только число, но и список имён проверок с flang/test/ledger.txt: файл, упавший целиком, дал бы ноль проверок и ноль отказов и без такой сверки выглядел бы чистым.

Гонять проверки дерева нужно двоичным bootstrap/flang из того же клона. Установленный flang видит вторую копию библиотеки — свою, в share/flang/stdlib, — и на части проверок отвечает FLANG_IMPORT_AMBIGUOUS: имя «UTF-8» носит больше одного модуля; двоичный, скопированный в другой каталог, не находит библиотеку вовсе (FLANG_IMPORT_NOT_FOUND).

Вторая команда долгая: примеров в библиотеке тысячи, и у нас прогон не уложился в 30 минут. Для правки одного модуля достаточно bootstrap/flang test flang/stdlib/<модуль>.flang.

Хук .githooks/pre-push прогоняет проверки, которые идут секунды, и прямо пишет, чего не прогонял; долгие — сборка, полный набор проверок, перепроверка доказательств — идут в CI.

Что говорят CONTRIBUTING.md и AGENTS.md

CONTRIBUTING.md — по-английски, для того, кто пришлёт правку: как собрать, что прогнать, что должна включать правка языка. AGENTS.md (лежит в .ai/, в корне — ссылка на него) — по-русски, для тех, кто работает в дереве постоянно: порядок работы и ошибки, которые уже стоили дорого. Из обоих стоит унести несколько правил.

Правка языка приходит вместе со спецификацией. Изменение формы — это раздел docs/flang/SPEC.md в том же изменении, проверка типов или завершаемости на него и одинаковое поведение вычислителя и всех целей кодогенерации.

Сгенерированное руками не правят. bootstrap/** получается только повторным переводом компилятора; CHANGELOG.md и changelog.json печатаются из тегов и тем коммитов.

Число в тексте — только снятое прогоном. Не «стало быстрее», а «83,30 с → 76,53 с». В дереве это проверяют автоматически: число рядом с путём к файлу пересчитывается, код FLANG_* в прозе обязан существовать в исходниках, ссылка на файл обязана вести в существующий файл.

Коды и тексты диагностик — наблюдаемое поведение. На версиях 0.x форма JSON и коды диагностик — то, на что можно опираться; синтаксис — нет.

Имена. Параметр или привязка пусть не короче трёх букв и не обрубок слова; правила — docs/guide/naming.ru.md.

Как прислать правку

1. Форк, ветка от dev: правки принимаются в dev, выпуски собираются в main (так устроены последние слитые запросы на слияние).
2. Примеры пишите прямо в функциях — их прогоняет тот же flang test.
3. Сообщение коммита — по-английски, по правилу Conventional Commits: fix(cli): …, заголовок не длиннее 72 знаков, только ASCII. Хук commit-msg и CI другое сообщение не принимают (docs/commit-messages.md).
4. В описании запроса скажите, что прогнали и чего прогнать не смогли.

Об ошибке без правки — issue в том же репозитории: текст программы и дословный вывод команды с кодом возврата.

Лицензия

BSD 2-Clause, файл LICENSE в корне; русская редакция без юридической силы — LICENSE-RU.md. Присылая правку, вы соглашаетесь выпустить её на тех же условиях.

Что дальше

Всё до сих пор было про устройство. Следующая глава — про применение: «Факт-чекинг», режим, ради которого программы и поделены на два класса.