From 306be6b82de78c176b6eb868c02f1cd9f105beb7 Mon Sep 17 00:00:00 2001 From: samsonium Date: Mon, 19 Oct 2026 04:05:00 +0300 Subject: [PATCH] feat: add first two book topics --- docs/ru/book/00_introduction.md | 43 +++++++++++++++++++++++++++ docs/ru/book/01_getting-started.md | 47 ++++++++++++++++++++++++++++++ 2 files changed, 90 insertions(+) create mode 100644 docs/ru/book/00_introduction.md create mode 100644 docs/ru/book/01_getting-started.md diff --git a/docs/ru/book/00_introduction.md b/docs/ru/book/00_introduction.md new file mode 100644 index 0000000..8a11ee6 --- /dev/null +++ b/docs/ru/book/00_introduction.md @@ -0,0 +1,43 @@ +# Вступление + +Добро пожаловать в небольшую книжку по основам языка FZLang и спасибо, что решились попробовать этот язык программирования. + +Для начала, стоит рассказать, что это за язык и как будет идти обучение в этой "книжке". + +## Что такое FZLang + +FZLang - это язык программирования с собственным тулчейном, включающим в себя компилятор и виртуальную машину. +Компилятор позволяет проверить и скомпилировать исходный код программы, чтобы сохранить в переносимый файл, а виртуальная машина - выполнить программу, написанную на FZLang. + +Изначально, этот проект задумывался как самоучитель по компиляторостроению. +Мне (Samsonium) было интересно разобрать: + +- Почему между компилятором и интерпретатором есть значимая разница? +- Как программа, под названием "компилятор" понимает, что я хочу сделать? +- Как устроено исполнение скомпилированной программы? Да и как, вообще, происходит процесс "перевода" с человеческого на машинный? + +Я занимаюсь программированием уже более 10 лет, но за всё время так и не удосужился об этом разузнать! + +Поэтому, этот проект был рождён как поле для экспериментов, разрабатывая который я стану лучше понимать устройство того, на чём строится весь мир программистов. +Однако, по ходу разработки у языка стала появлятся своя форма, а также философия. + +Сейчас, я бы описал философию языка так: "быть удобным, как инструмент, но всегда стараться оставаться предсказуемым". +Полагаю, любое комьюнити желает своему языку того же, но мне это помогло сделать определённый выбор в ключевых точках развития. + +### Как в FZLang устроена работа с памятью + +Изначально вопрос появился после внедрения стеков виртуальной машины, и звучал он так: "сборщик мусора или что-то другое?". +Изучить работу сборщика было, конечно, интересно. +Однако мне, человеку, выбравшему Java как первый язык, была знакома его "тяжесть" и "скорость" работы. +Конечно же, отдельное "спасибо" за это можно сказать его сборщику мусора. + +Поэтому, вместо GC я решил посмотреть в сторону RAII и, в итоге, получил хорошую формулу гуляния объекта в программе: +если объект подан как аргумент, то происходит "заимствование" его во вложенное окружение, и если объект возвращается, то происходит перемещение объекта в родительское окружение. +Такой подход позволяет не делать GC, а ещё, что самое важное, получить детерминированное время жизни объекта, а значит, детерминированную память (настолько, насколько это возможно). + +Короче говоря, FZLang обзавёлся scope-based RAII. + +--- + +Далее: [Начало работы](./01_getting-started.md) + diff --git a/docs/ru/book/01_getting-started.md b/docs/ru/book/01_getting-started.md new file mode 100644 index 0000000..fd30a64 --- /dev/null +++ b/docs/ru/book/01_getting-started.md @@ -0,0 +1,47 @@ +# Начало работы + +Для того, чтобы начать работу с FZLang, достаточно установить себе на компьютер два исполяемых файла: + +- `fzc` - компилятор +- `fz` - виртуальная машина + +Для того, чтобы скомпилировать программу, достаточно выполнить программу `fzc`, указав в качестве аргументов пути к файлам с исходным кодом. +Если программа успешно скомпилировалась, то её можно запустить через программу `fz`, также указав путь скомпилированному файлу. +Без указания компилятору пути к выходному файлу, скомпилированная программа будет сохранена как `a.fzb`. + +## Настройки компилятора + +Чтобы посмотреть о доступных настройках компилятора, выполните `fzc --help` (или `fzc -h`). +На данный момент, справка выглядит так: + +``` +Usage: fzc [flags] +Available flags: + -h --help Print help + -v --verbose Display compilation info (tokens, AST, consts table, etc) + -V --version Print compiler version + -o --out Set compiled file name +``` + +Флаг `-h` (`--help`) просто выводит ту же справку. Флаги `-v` / `--verbose` делает подробный вывод компиляции: + +- Какие лексемы были прочитаны; +- Какое синтаксическое дерево было собрано; +- Какие значения были записаны в таблицу констант; +- Какие опкоды были записаны в программу. + +Флаги `-V` / `--version` выводят версию компилятора. Флаги `-o`, `--out` позволяют задать путь выходного файла. + +## Настройки виртуальной машины + +У виртуальной машины есть всего два флага: `--help` (`-h`) и `-d`. + +- `--help` (или `-h`) выводит справку; +- `-d <путь к файлу>` выводит список опкодов с нумерацией. С помощью этого флага вы можете посмотреть, как вашу программу будет читать ВМ. + +--- + +Далее: [Первая программа](./02_first-program.md) + +Назад: [Вступление](./00_introduction.md) +