Skip to content

Commit 081efb3

Browse files
dx3moddx3mod
committed
Секция про публикацию пакета перенесена в рецепты
1 parent 83e008d commit 081efb3

File tree

3 files changed

+78
-74
lines changed

3 files changed

+78
-74
lines changed

‎docs/.vitepress/config.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,7 @@ export default defineConfig({
3232
{ text: "Конструкторы", link: "/constructor" },
3333
{ text: "Параметры выполнения", link: "/runparams" },
3434
{ text: "Performance", link: "/performance" },
35+
{ text: "Публикация пакета", link: "/publish-package" },
3536
],
3637
},
3738
{

‎docs/recipes/publish-package.md‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
# Публикация пакета
2+
3+
Центральный репозиторий пакетов для OCaml называется [opam-repository](https://github.com/ocaml/opam-repository) и является GitHub-репозиторием, содержащий файлы манифестов.
4+
5+
Чтобы опубликовать ваш проект в opam-репозитории и сделать его общедоступным вам потребуется:
6+
7+
1. Во-первых манифест проекта, файл [`<название-проекта>.opam`](https://opam.ocaml.org/doc/Packaging.html#Creating-a-package-definition-file). Самый простой и современный способ его получить &mdash; использовать [Dune](../tools/dune.md);
8+
2. Во-вторых GitHub-аккаунт для работы с репозиторием и [настроенные SSH-ключи](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent)
9+
1. ```sh
10+
$ ssh-keygen -t ed25519 -C "your_email@example.com"
11+
$ eval "$(ssh-agent -s)"
12+
$ ssh-add ~/.ssh/id_ed25519
13+
```
14+
2. Добавьте содержимое `~/.ssh/id_ed25519.pub` в настройки пользователя
15+
3. Ну и Git само собой...
16+
17+
> [!NOTE] Документация
18+
>
19+
> - https://opam.ocaml.org/doc/Packaging.html#Creating-a-package-definition-file
20+
> - https://github.com/ocaml/opam-repository/blob/master/CONTRIBUTING.md
21+
22+
> [!TIP] Рекомендации и возможные ошибки
23+
> Чётко указывайте версии зависимостей, в том числе для пакетов-компаньонов вашего проекта.
24+
> Отнеситесь к этому достаточно дотошно, иначе потратите много времени.
25+
26+
> [!NOTE] Принцип
27+
>
28+
> Если кратко, то внесение проекта в opam-репозиторий происходит посредством добавления файла манифеста в дерево репозитория.
29+
> Например, манифест проекта с название `xyz` и версией `1.2.3` будет располагаться по пути `packages/xyz/xyz.1.2.3/opam`.
30+
>
31+
> У такого манифеста должно быть указано поле `url` с информацией откуда достать исходный код проекта:
32+
>
33+
> ```opam
34+
> url {
35+
> src: "https://address/of/project.1.0.tar.gz"
36+
> checksum: "md5=3ffed1987a040024076c08f4a7af9b21"
37+
> }
38+
> ```
39+
40+
### opam-publish
41+
42+
К счастью, для автоматизации процесса публикации существует специальная утилита `opam-publish`, которая является плагином к `opam`.
43+
44+
<!-- Достаточно создать тег для фиксации последней версии проекта и выполнить команду `opam publish`. -->
45+
46+
> [!TIP] Установка
47+
> Рекомендуется установить утилиту в отдельный switch, так как она требовательна к версиям зависимостей и может сделать downgrade многих установленных пакетов.
48+
>
49+
> ```sh
50+
> $ opam switch create publish 5.2.0
51+
> $ opam install opam-publish
52+
> ```
53+
54+
Для публикации пакета с помощью утилиты необходимо создать тег и сделать его доступным из Интернета.
55+
Пример из документации:
56+
57+
```sh
58+
$ git tag -a 0.1
59+
$ git push origin 0.1
60+
61+
$ opam publish
62+
```
63+
64+
После чего утилита попросит ввести GitHub-токен, она сделает форк opam-репозитория и создаст pull-request (PR), где начнется автоматизированное тестирования на сборку платформой [ocaml-ci](https://ocaml.ci.dev/).
65+
66+
> [!NOTE] Исправление ошибок
67+
>
68+
> ```sh
69+
> $ git tag -f tag
70+
> $ git push -f origin tag
71+
> ```
72+
73+
### Принятие
74+
75+
После того как вы исправите все свои косяки, ваш PR сольют с репозиторием и вы сможете установить
76+
пакет обычным `opam install`.

‎docs/tools/opam.md‎

Lines changed: 1 addition & 74 deletions
Original file line numberDiff line numberDiff line change
@@ -52,80 +52,7 @@ $ opam switch create . --deps-only
5252

5353
## Публикация пакета
5454

55-
Центральный репозиторий пакетов для OCaml называется [opam-repository](https://github.com/ocaml/opam-repository) и является GitHub-репозиторием, содержащий файлы манифестов.
56-
57-
Чтобы опубликовать ваш проект в opam-репозитории и сделать его общедоступным вам потребуется:
58-
59-
1. Во-первых манифест проекта, файл [`<название-проекта>.opam`](https://opam.ocaml.org/doc/Packaging.html#Creating-a-package-definition-file). Самый простой и современный способ его получить &mdash; использовать [Dune](./dune.md);
60-
2. Во-вторых GitHub-аккаунт для работы с репозиторием и [настроенные SSH-ключи](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent)
61-
1. ```sh
62-
$ ssh-keygen -t ed25519 -C "your_email@example.com"
63-
$ eval "$(ssh-agent -s)"
64-
$ ssh-add ~/.ssh/id_ed25519
65-
```
66-
2. Добавьте содержимое `~/.ssh/id_ed25519.pub` в настройки пользователя
67-
3. Ну и Git само собой...
68-
69-
> [!NOTE] Документация
70-
>
71-
> - https://opam.ocaml.org/doc/Packaging.html#Creating-a-package-definition-file
72-
> - https://github.com/ocaml/opam-repository/blob/master/CONTRIBUTING.md
73-
74-
> [!TIP] Рекомендации и возможные ошибки
75-
> Чётко указывайте версии зависимостей, в том числе для пакетов-компаньонов вашего проекта.
76-
> Отнеситесь к этому достаточно дотошно, иначе потратите много времени.
77-
78-
> [!NOTE] Принцип
79-
>
80-
> Если кратко, то внесение проекта в opam-репозиторий происходит посредством добавления файла манифеста в дерево репозитория.
81-
> Например, манифест проекта с название `xyz` и версией `1.2.3` будет располагаться по пути `packages/xyz/xyz.1.2.3/opam`.
82-
>
83-
> У такого манифеста должно быть указано поле `url` с информацией откуда достать исходный код проекта:
84-
>
85-
> ```opam
86-
> url {
87-
> src: "https://address/of/project.1.0.tar.gz"
88-
> checksum: "md5=3ffed1987a040024076c08f4a7af9b21"
89-
> }
90-
> ```
91-
92-
### opam-publish
93-
94-
К счастью, для автоматизации процесса публикации существует специальная утилита `opam-publish`, которая является плагином к `opam`.
95-
96-
<!-- Достаточно создать тег для фиксации последней версии проекта и выполнить команду `opam publish`. -->
97-
98-
> [!TIP] Установка
99-
> Рекомендуется установить утилиту в отдельный switch, так как она требовательна к версиям зависимостей и может сделать downgrade многих установленных пакетов.
100-
>
101-
> ```sh
102-
> $ opam switch create publish 5.2.0
103-
> $ opam install opam-publish
104-
> ```
105-
106-
Для публикации пакета с помощью утилиты необходимо создать тег и сделать его доступным из Интернета.
107-
Пример из документации:
108-
109-
```sh
110-
$ git tag -a 0.1
111-
$ git push origin 0.1
112-
113-
$ opam publish
114-
```
115-
116-
После чего утилита попросит ввести GitHub-токен, она сделает форк opam-репозитория и создаст pull-request (PR), где начнется автоматизированное тестирования на сборку платформой [ocaml-ci](https://ocaml.ci.dev/).
117-
118-
> [!NOTE] Исправление ошибок
119-
>
120-
> ```sh
121-
> $ git tag -f tag
122-
> $ git push -f origin tag
123-
> ```
124-
125-
### Принятие
126-
127-
После того как вы исправите все свои косяки, ваш PR сольют с репозиторием и вы сможете установить
128-
пакет обычным `opam install`.
55+
Смотрите [тут](../recipes/publish-package.md).
12956

13057
## Зависимости
13158

0 commit comments

Comments
 (0)