From eb29e66be36be28e0b066b982d44eb3449cc1af0 Mon Sep 17 00:00:00 2001 From: dx3mod Date: Tue, 2 Jul 2024 16:38:46 +0300 Subject: [PATCH] =?UTF-8?q?=D0=94=D0=BE=D0=B1=D0=B0=D0=B2=D0=BB=D0=B5?= =?UTF-8?q?=D0=BD=D0=B0=20=D1=81=D1=82=D1=80=D0=B0=D0=BD=D0=B8=D1=87=D0=BA?= =?UTF-8?q?=D0=B0=20=D0=BF=D1=80=D0=BE=20Dune?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/.vitepress/config.ts | 4 +- docs/index.md | 3 +- docs/tools/dune.md | 128 ++++++++++++++++---------------------- 3 files changed, 58 insertions(+), 77 deletions(-) diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index 08c84d2..4e0fff3 100644 --- a/docs/.vitepress/config.ts +++ b/docs/.vitepress/config.ts @@ -18,7 +18,9 @@ export default defineConfig({ { text: "Тулчейн", collapsed: false, - items: [{ text: "Система сборки Dune", link: "/tools/dune" }] + items: [ + { text: "Система сборки Dune", link: "/tools/dune" }, + { text: "Пакетный менеджер OPAM", link: "/tools/opam" }], } ], diff --git a/docs/index.md b/docs/index.md index 7ad17eb..739aa82 100644 --- a/docs/index.md +++ b/docs/index.md @@ -17,7 +17,8 @@ ::: details Тулчейн -- [Система сборки Dune](./tools/dune.md) (в процессе) +- [Система сборки Dune](./tools/dune.md) +- [Пакетный менеджер OPAM](./tools/opam.md) ::: diff --git a/docs/tools/dune.md b/docs/tools/dune.md index 6216be7..d1b346b 100644 --- a/docs/tools/dune.md +++ b/docs/tools/dune.md @@ -1,8 +1,12 @@ # Система сборки Dune -**Dune** - самое популярное решение для сборки OCaml-проектов, оно глубоко интегрировано в экосистему языка, -обладает современным функционалом (на подобие инкрементальной сборки, параллельности) и позволяет собирать -как исполняемые программы, так и библиотеки, вызывать тесты. +**Dune** - самое популярное решение для сборки OCaml-проектов, оно глубоко интегрировано в экосистему языка, обладает современным функционалом (на подобие инкрементальной сборки, параллельности) и позволяет собирать как исполняемые программы, так и библиотеки, вызывать тесты. + +- [Quick start](https://dune.readthedocs.io/en/stable/quick-start.html) + +Стоит понимать, Dune не занимается управлением пакетами (сторонних библиотек), она способна только их подключать. +Для управления же используется пакетный менеджер [OPAM](./opam.md). + ## Базовые понятия @@ -13,100 +17,74 @@ Проект содержит один или более компонент любого типа, которые могут зависеть друг от друга. -Эти компоненты могут быть объеденины в пакеты для [OPAM](./opam.md). -Для их последующего распространения. - - +Эти компоненты могут быть объеденины в пакеты для их последующего распространения. -## Работа с Dune +## Автоматическое форматирование -### Создание проекта - -Для создания проекта можно воспользоваться командой `dune init`: +Для этого у вас должен быть установлен [`ocamlformat`](https://github.com/ocaml-ppx/ocamlformat). ```sh -$ dune init project demo +$ opam install ocamlformat ``` -- где `demo` название проекта (название может содержать только буквы английского алфавита, цифры и символ нижнего подчёркивания) - -### Типичная структура - -``` -demo/ -├── bin -│   ├── dune -│   └── main.ml -├── demo.opam -├── dune-project -├── lib -│   └── dune -└── test - ├── dune - └── test_demo.ml +После чего в корень проекта добавьте файл `.ocamlformat`: +```sh +$ touch .ocamlformat ``` -#### `dune-project` - -Корневой файл конфигурации проекта, в нём описываются пакеты -и другая информация. Для сборки проекта на самом деле достаточна иметь только первую строчку, указывающая версию, если нам не нужен OPAM-файл. - -```dune_project -(lang dune 3.16) - -(name demo) - -(generate_opam_files true) - -(source - (github username/reponame)) - -(authors "Author Name") +Этого достаточно, чтобы использовалось автоформатирование командами: +```sh +$ dune fmt # или dune build @fmt +``` -(maintainers "Maintainer Name") +Для настройки профиля и версии смотрите [документацию](https://dune.readthedocs.io/en/stable/howto/formatting.html). -(license LICENSE) +## Чтения файлов в тестах -(documentation https://url/to/documentation) +Распространённый кейс, когда в тестах вы читаете какой-нибудь файл. Если вы попробуете это сделать, то получите ошибку о том, что файл не найден, ибо этот файл не находится в каталоге `_build`. -(package - (name demo) - (synopsis "A short synopsis") - (description "A longer description") - (depends ocaml dune) - (tags - (topics "to describe" your project))) +Пример каталога с тестом: +``` +test/ +├── data.test.txt +├── dune +└── test_demo.ml ``` -#### `bin`, `lib`, `test` +```ocaml +(* test_demo.ml *) +let () = open_in "data.test.txt" |> In_channel.input_all |> print_endline +``` -Всё это компоненты, для них можно видеть характерный файл `dune`. +```sh +$ dune runtest +File "test/dune", line 2, characters 7-16: +2 | (name test_demo)) + ^^^^^^^^^ +Fatal error: exception Sys_error("data.test.txt: No such file or directory") # [!code focus] +``` -##### `bin` +Для исправления этого в файле `dune` вы должны указать зависимости в поле `deps`. ```dune -(executable - (public_name demo) - (name main) - (libraries demo)) +(test + (name test_demo) + (deps data.test.txt)) // [!code ++] ``` -##### `lib` +Подробнее смотрите в [Dependency Specification](https://dune.readthedocs.io/en/stable/concepts/dependency-spec.html). -```dune -(library - (name demo)) -``` +## Зависимости при установки + +Dune умеет в установку скомпилированных артефактов в систему, но помимо бинарника надо иногда иметь и сторонние ресурсы. Например, HTML-странички в случае веб-сайта. -##### `test` +Для этого существует *строфа* `install` в `dune` файле. Пример: ```dune -(test - (name test_demo)) +(install + (files hello.txt) + (section share) + (package mypackage)) ``` +В этом примере файл `hello.txt` будет установлен по пути `/share/mypackage`. - - - \ No newline at end of file +За подробностями читайте [мануал](https://dune.readthedocs.io/en/stable/reference/dune/install.html). \ No newline at end of file