diff --git a/earth_doc/book_daria/book.typ b/earth_doc/book_daria/book.typ new file mode 100644 index 0000000..24d3cec --- /dev/null +++ b/earth_doc/book_daria/book.typ @@ -0,0 +1,89 @@ +#import "../head.typ": * + +#set page(footer: context {align(center, counter(page).display("1"))}) +#set text(size: 1.2em) +#set par(first-line-indent: 16pt) + +#align(center, heading(depth: 1)[Архитектура и стиль кода в prototype1 (Дарье)]) + +Для компиляции используется только сборочная система make. +Генерировать makefile с помощью shell-скрипта разрешено, просто в данный момент это не +практикуется. +Другие сборочные системы, вроде Cmake, Meson, скрипты на питоне, и.т.д. +есть мерзость. _Ты можешь обнаружить в корне репозитория `CmakeLists.txt` - он не +обязателен для компиляции, он лишь для тех, чья среда разработки требует cmake._ + +Ни одна строка кода не должна быть написана на C++. Дарья не требует +для функционирования компилятор C++. То, что почти все зависимости Дарьи +требуют компилятор C++ - очень досадное обстоятельство, но не причина отказываться +от них, ибо аналогов у них нет. Мы молчаливо осуждаем тех, кто написал компилятор +glsl на C++. Допускается использовать python, rust, haskell +для написания скриптов, вспомогательных для разработки Дарьи, но не обязательных +для запуска Дарьи. Допускается написание самых высших уровней Дарьи на +haskell и rust. Самые высшие уровни Дарьи это те, что лишь используют мощь +моего игрового движка для исключительно творческих целей. Сам же движок Дарьи +пишется на чистом C99. Я не называю ни одну зависимость Дарьи святой. +Тем не менее аналогов им я не знаю. Как бы тебе не был противен C, прийдётся +уж им пользоваться, на нём основан linux, без линукса Дарья не запускается. Нижние +уровни Дарьи декларируют фреймворк, сглаживающий большинство недостатков C. + +Во всех файлах на C используется `snake_case` для именования функций, +`UpperCamelCase` для именования типов. Имя пространства имён не имеет +такого правила наименования, поскольку если оно встречается в имени +функции, используется правило наименования для функции, если внутри имени типа, +используется правило для типов. Имя пространства имён дописывается перед +именем символа, внутреннего для пространства имён, без всякого разделителя. +Пространств имён у меня не много. В Дарье есть система инстанциации шаблонов +для C. К имени шаблона справа дописываются аргументы инстанциации (но есть исключения). +`VecU64`, `OptionVkFormat`, `ResultTextureDataR8OrSpanU8` значат буквально то, +что они значат. + +Я не морочусь с тонной объектных файлов при компиляции, ибо пишу код +исключительно в `.h` файлах, где декларация объединена с определением. +Если я компилирую исполняемый бинарник, код с функцией `main` имеет расширение +`.c`, он вбирает все те заголовочные файлы, что ему нужны. В заголовочных файлах +используются "хедер-гуарды". При компиляции весь весь код со всех файлов, +нужных исполняемой программе какбы склеивается воедино. Поэтому нельзя одно и то же +имя дважды в двух разных заголовках, используемых одной программой, даже если чисто +логически они независимы. + +В корне репозитория находится главный `Makefile`, плюс необязательны +для сборки `shell.nix` для +людей нетрадиционной сексуальной ориентации, которые захотят воспользоваться +Дарьей. Весь остальной код лежит в папке `src` в обнимку с тестами. В процессе +компиляции дарья создаст папку `out`, куда будут помещены скомпилированные `cc` +исполняемые файлы и папку `gen`, куда будет помещён код на C, +сгенерированный самой Дарьей для последующей компиляции. Поскольку в Дарье +присутствует кодген, весь исходный код (и генерируемый код тоже) разграничен на уровни. +Уровни обозначают порядок компиляции. На низших уровнях сгенерированно кода цель +компиляции только одна - сам этот код. На низших уровнях исходного кода +есть цель для генерации кода генерируемого соответсвующего себе уровня, +а так же тесты исходного кода этого уровня и любого кода с предыдущих уровней. +Да, уровни располагаются в одном порядке. В их именазаложена числовая нумерация. +Есть, правда, исключения из этого правила, для уровней, у которых +нет исходного (только генерируемый код) и генерируемый код генерируется не Дарьей, +а зависимостью Дарьи. + +Вот какие уровни есть в данный момент: + +`l_wl_protocls` (написан не мной, не нумеруется), `l1`, `l1_4`, `l1_5`, `l2` + +Весь код хранится в папках `src/<имя уровня>` и `gen/<имя уровня>`. +Код с более высокого уровня может использовать код с более низкого уровня. +Сгенерированный код с какого-то уровня может использовать исходный код +с этого же уровня, но исходный код не может использовать генерированный +код своего уровня. Тем не менее код, +генерирующий другой код, может быть осведомлён о существовании и содердании +более высоких слоёв, но только если он находится в специальной папке +`gen/l1vi` + +Разберём что делает каждый уровень, что есть в данный момент в Дарье: + +- `l_wl_protocols` -- из-за странного способа дистрибуции wayland-lib мы должны сами + генерировать код для неё. +- `l1` -- самый первый уровень. Тут определены все утилиты, которые не +потребовали кодгена. Так же исходный код `l` определяет типы и функции, +полезные при любой генерации кода. В утилитах `l1` так же есть +обёртки над базовыми обёртками над системными вызовами линукса. +Первый уроведь определяет самые главные шаблоны: `Vec`, `Option`, +`Span`, `MutSpan`, `ResultOr`, \ No newline at end of file