# ALR скрипт сборки

ALR использует скрипты сборки, похожие на `PKGBUILD`'s *AUR*. Ниже описаны требования к содержимому.

---
- [Переопределение дистрибутива](#переопределение-дистрибутива)
  - [Похожие дистрибутивы](#похожие-дистрибутивы)
- [Переменные](#переменные)
  - [name](#name)
  - [version](#version)
  - [release](#release)
  - [epoch](#epoch)
  - [desc](#desc)
  - [homepage](#homepage)
  - [maintainer](#maintainer)
  - [architectures](#architectures)
  - [licenses](#licenses)
  - [provides](#provides) 
  - [conflicts](#conflicts)
  - [deps](#deps)
  - [build_deps](#build_deps) 
  - [opt_deps](#opt_deps) 
  - [replaces](#release) 
  - [sources](#sources)
  - [checksums](#checksums) 
  - [backup](#backup) 
  - [scripts](#scripts) 
- [Функции](#функции) 
  - [prepare](#prepare) 
  - [version](#version) 
  - [build](#build)
  - [package](#package)
- [Переменные окружения](#переменные-окружения)
  - [DISTRO_NAME](#distro_name) 
  - [DISTRO_PRETTY_NAME](#distro_pretty_name)
  - [DISTRO_ID](#distro_id)
  - [DISTRO_VERSION_ID](#distro_version_id)
  - [ARCH](#arch)
  - [NCPU](#ncpu)
- [Вспомогательные команды](#вспомогательные-команды)
  - [install-binary](#install-binary) 
  - [install-systemd](#install-systemd) 
  - [install-systemd-user](#install-systemd-user) 
  - [install-config](#install-config) 
  - [install-license](#install-license) 
  - [install-completion](#install-completion) 
  - [install-manual](#install-manual) 
  - [install-desktop](#install-desktop)
  - [install-library](#install-library) 
  - [git-version](#git-version)
---

## Переопределение дистрибутива

Использование ALR в различных дистрибутивах представляет собой некоторые проблемы. Например, некоторые дистрибутивы используют разные названия для своих пакетов. Это решается с помощью переопределений дистрибутива. Любая переменная или функция, используемая в скрипте сборки ALR, может быть переопределена в зависимости от дистрибутива и архитектуры CPU. Сделать это можно, добавляя наименование дистрибутива и/или архитектуры в конец имени. Например, ALR зависит от пакета `go`. `Go` имеет несколько разные названия на различных дистрибутивах. Для ALR я использую следующее для зависимостей:
```bash
deps=('golang')
deps_arch=('go' )
deps_opensuse=('go')
```
Добавление `arch` и `opensuse` в конец заставляет ALR использовать соответствующий массив в зависимости от дистрибутива. Если вы находитесь на *Arch Linux*, он будет использовать `deps_arch`. Если на *OpenSUSE*, он будет использовать `deps_opensuse`, а если на что-то другое, то будет использовать `deps`.

Имена проверяются в следующем порядке:
```sh
    $name_$architecture_$distro
    $name_$distro
    $name_$architecture
    $name
```
Обнаружение дистрибутива выполняется путем чтения файлов `/usr/lib/os-release` и `/etc/os-release`.

## Похожие дистрибутивы

Внутри файла `os-release` есть список "похожих" дистрибутивов. ALR учитывает это. Например, если скрипт содержит `deps_debian`, но не `deps_ubuntu`, сборки *Ubuntu* будут использовать `deps_debian`, поскольку *Ubuntu* основан на *Debian*.

Предпочтительна наибольшая спецификация, поэтому, если предоставлены как `deps_debian`, так и `deps_ubuntu`, *Ubuntu* и все основанные на нём дистрибутивы будут использовать `deps_ubuntu`, в то время как *Debian* и все основанные на нем дистрибутивы, которые не являются основанными на *Ubuntu*, будут использовать `deps_debian`.

Похожие дистрибутивы отключены при использовании переменной окружения alr_DISTRO.

## Переменные

Любые переменные, отмеченные (*), являются обязательными.
### name*

Переменная `name` содержит имя пакета, описанного в скрипте (должно совпадать с наименованием каталога в репозитории который содержит скрипт сборки пакета ALR).

### version*

Переменная `version` содержит версию пакета. Это должно быть то же самое, что и версия, используемая автором в upstream.

Сравнение версий выполняется с использованием алгоритма `rpmvercmp`.

### release*

Номер `release` предназначен для различения различных сборок одной и той же версии пакета, например, если скрипт изменяется, но версия остается прежней. `release` должен быть целым числом.

### epoch

Номер `epoch` заставляет пакет считаться более новым, чем версии с меньшим номером `epoch`. Он должен использоваться, если схема нумерации не может быть использована для определения, какой пакет новее. Его использование не рекомендуется, и он должен использоваться только в случае необходимости. Номер `epoch` должен быть положительным целым числом.

### desc

Поле `desc` содержит описание пакета. Оно не должно содержать переносов строк.

### homepage

Поле `homepage` содержит URL-адрес сайта проекта, упакованного данным скриптом.

### maintainer

Поле `maintainer` содержит имя и адрес электронной почты человека, поддерживающего пакет. Пример:
```text
Евгений Храмов <xpamych@yandex.ru>
```

Хотя ALR не требует установки этого поля, *Debian* отказался от неустановленных полей `maintainer` и может запретить их использование в пакетах .deb в будущем.

### architectures

Массив `architectures` содержит все архитектуры, которые поддерживает данный пакет. Они соответствуют списку `GOARCH` языка `Go`, за исключением некоторых отличий.

Архитектура `all` будет переведена на правильный термин для формата упаковки. Например, он будет изменен на `noarch`, если строится `.rpm`, или `any`, если строится пакет *Arch*.

Поскольку существует несколько вариантов архитектуры `arm`, должны использоваться следующие значения:
```sh
arm5: armv5
arm6: armv6
arm7: armv7
```
ALR попытается определить, какой вариант использует ваша система, проверяя существование различных функций `CPU`. Если это дает неправильный результат или если вы просто хотите собрать для другого варианта, переменная `alr_ARM_VARIANT` должна быть установлена в желаемый вариант `ARM`. Пример:
```sh
alr_ARM_VARIANT=arm5 alr install ...
```

### licenses

Массив `licenses` содержит лицензии, используемые этим пакетом. Для стандартизации названий лицензий значения должны быть идентификаторами `SPDX` такими как `Apache-2.0`, `MIT` и `GPL-3.0-only`. Если проект использует лицензию, которая не стандартизирована в `SPDX`, используйте значение `Custom`. Если проект имеет несколько нестандартных лицензий, включите `Custom` столько раз, сколько есть нестандартных лицензий.

### provides

Массив `provides` указывает, какие функции предоставляет пакет. Например, если два пакета собирают `ffmpeg` с разными флагами сборки, оба должны иметь `ffmpeg` в массиве `provides`.

### conflicts

Массив `conflicts` содержит имена пакетов, которые конфликтуют с пакетом, собранным данным скриптом. Если два различных пакета содержат исполняемый файл для `ffmpeg`, их нельзя установить одновременно, поэтому они конфликтуют. Массив `provides` также будет проверяться, поэтому этот массив обычно содержит те же значения, что и `provides`.

### deps

Массив `deps` содержит зависимости для пакета. Репозитории ALR будут проверены первыми, и если пакеты существуют там, они будут собраны и установлены. В противном случае они будут установлены из системных репозиториев вашим менеджером пакетов.

### build_deps

Массив `build_deps` содержит зависимости, которые необходимы для сборки пакета. Они будут установлены перед началом сборки. Аналогично массиву `deps`, сначала будут проверены репозитории ALR.

### opt_deps

Массив `opt_deps` содержит необязательные зависимости для пакета. Описание можно добавить после `": "`, но это не обязательно.
```sh
opt_deps_arch=(
'git: Управление репозиториями git'
'aria2: Менеджер загрузок'
)
```

### replaces

Массив `replaces` содержит пакеты, которые заменяются данным пакетом. Обычно, если менеджеры пакетов находят пакет с установленным полем `replaces`, они удаляют указанные пакеты и устанавливают этот вместо них. Это полезно только в том случае, если пакеты хранятся в репозитории для вашего менеджера пакетов.

### sources

Массив `sources` содержит URL-адреса, которые загружаются в `$srcdir` перед началом сборки.

Если предоставленный URL является архивом или сжатым файлом, он будет извлечен. Чтобы отключить это, добавьте параметр `~archive=false`. Пример:
Извлеченный:
```sh
https://example.com/archive.tar.gz
```
Не извлеченный:
```sh
https://example.com/archive.tar.gz?~archive=false
```
Если схема URL начинается с `git+`, источник будет загружен как git-репозиторий. Режим загрузки `git` поддерживает несколько параметров:

    ~rev: Укажите, какую ревизию репозитория нужно проверить.
    ~depth: Укажите, какая глубина должна использоваться при клонировании репозитория. Должна быть целым числом.
    ~name: Укажите имя директории, в которую должен быть клонирован git-репозиторий.
    ~recursive: Если установлено в true, вложенные модули будут клонироваться рекурсивно. По умолчанию false.
    #tag=v${version}: Укажите тег, версия которого необходима из репозитория.

Примеры:
```sh
git+https://gitea.elara.ws/Elara6331/itd?~rev=resource-loading&~depth=1

git+https://gitea.elara.ws/alr/alr?~rev=v0.0.1&~recursive=true
```

### checksums

Массив `checksums` должен быть такой же длины, как и массив [sources](#sources). Он содержит контрольные суммы для исходных файлов. Файлы проверяются на соответствие контрольным суммам, и сборка завершается неудачей, если они не совпадают.

По умолчанию ожидаются контрольные суммы в формате `sha256`. Чтобы изменить алгоритм, добавьте его перед хешем с двоеточием между ними. Например, `md5:bc0c6f5dcd06bddbca9a0163e4c9f2e1`. В настоящее время поддерживаются следующие алгоритмы: `sha256`, `sha224`, `sha512`, `sha384`, `sha1` и `md5`.

Чтобы пропустить проверку для определенного источника, установите соответствующую контрольную сумму в `SKIP`.

### backup

Массив `backup` содержит файлы, которые должны быть сохранены при обновлении и удалении. Точное поведение этого зависит от вашего менеджера пакетов. Все файлы в этом массиве должны быть полными путями назначения. Например, если существует конфигурационный файл под названием `config` в `/etc`, который вы хотите сохранить, вы должны установить его так:
```sh
backup=('/etc/config')
```

### scripts

Переменная `scripts` содержит ассоциативный массив Bash, который указывает расположение различных скриптов относительно скрипта сборки. Пример:
```sh
scripts=(
['preinstall']='preinstall.sh'
['postinstall']='postinstall.sh'
['preremove']='preremove.sh'
['postremove']='postremove.sh'
['preupgrade']='preupgrade.sh'
['postupgrade']='postupgrade.sh'
['pretrans']='pretrans.sh'
['posttrans']='posttrans.sh'
)
```
Примечание: Для данного синтаксиса кавычки обязательны из-за ограничений парсера `bash`.

Скрипты `preupgrade` и `postupgrade` доступны только в пакетах `.apk` и *Arch Linux*.

Скрипты `pretrans` и `posttrans` доступны только в пакетах `.rpm`.

Остальные скрипты доступны во всех пакетах.

## Функции

В этом разделе описаны функции, определяемые пользователем, которые могут быть добавлены в скрипты сборки. Любые функции, отмеченные (*), являются обязательными.

Все функции выполняются в директории `$srcdir`.

### version()

Функция `version()` обновляет переменную `version`. Это позволяет автоматически извлекать версию из исходных файлов. Это наиболее полезно для git-пакетов, которые обычно не требуют изменений, поэтому их переменная `version` остается неизменной.

Пример использования для `git`:
```sh
version() {
cd "$srcdir/itd"
printf "r%s.%s" "$(git rev-list --count HEAD)" "$(git rev-parse --short HEAD)"
}
```
Аналогом в AUR является функция `pkgver()`.

### prepare()

Функция `prepare()` предназначена для подготовки исходных файлов к сборке и упаковке. Это функция, в которой должны применяться патчи, например, с помощью команды `patch`, и где должны выполняться инструменты, такие как `go generate`.

### build()

Функция `build()` — это место, где фактически происходит сборка пакета. Используйте те же команды, которые использовались бы для ручной компиляции программного обеспечения. Часто эта функция состоит всего из одной строки:
```sh
build() {
make
}
```

### package()*

Функция `package()` — это место, куда помещаются собранные файлы в директорию, которая будет использоваться ALR для сборки пакета.

Все файлы, которые должны быть установлены в файловой системе, должны быть помещены в директорию `$pkgdir` в данной функции. Например, если у вас есть бинарный файл под названием `bin`, который должен быть помещен в `/usr/bin`, и конфигурационный файл под названием `bin.cfg`, который должен быть помещен в `/etc`, то функция `package()` может выглядеть так:
```sh
package() {
install -Dm755 bin ${pkgdir}/usr/bin/bin
install -Dm644 bin.cfg ${pkgdir}/etc/bin.cfg
}
```
## Переменные окружения

ALR предоставляет несколько значений в виде переменных окружения для использования в скриптах сборки.

### DISTRO_NAME

Переменная `DISTRO_NAME` — это имя дистрибутива, определенное в его файле `os-release`.

Например, в образе *Docker Fedora 36* оно установлено в `Fedora Linux`.

### DISTRO_PRETTY_NAME

Переменная `DISTRO_PRETTY_NAME` — это "красивое" имя дистрибутива, определенное в его файле `os-release`.

Например, в образе *Docker Fedora 36* оно установлено в `Fedora Linux 36 (Container Image)`.

### DISTRO_ID

Переменная `DISTRO_ID` — это идентификатор дистрибутива, определенный в его файле `os-release`. Это то же самое, что и то, что ALR использует для переопределений.

Например, в образе *Docker Fedora 36* оно установлено в `fedora`.

### DISTRO_ID_LIKE

Переменная `DISTRO_ID_LIKE` содержит идентификаторы похожих дистрибутивов для текущего, разделенные пробелами.

Например, в образе *Docker OpenSUSE Tumbleweed* она установлена в `opensuse suse`, а в образе *Docker CentOS 8* — в `rhel fedora`.

### DISTRO_VERSION_ID

Переменная `DISTRO_VERSION_ID` — это идентификатор версии дистрибутива, определенный в его файле `os-release`.

Например, в образе *Docker Fedora 36* она установлена в `36`, а в образе *Docker Debian Bullseye* — в `11`.

### ARCH

Переменная `ARCH` — это архитектура машины, на которой выполняется скрипт. Она использует ту же схему именования, что и значения в массиве `architectures`.

### NCPU

Переменная `NCPU` — это количество доступных на машине процессоров, на которой выполняется скрипт. Например, на четырёхъядерной машине с гипертредингом оно будет установлено в `8`.

## Вспомогательные команды

ALR предоставляет различные команды, чтобы помочь мейнтейнерам создавать правильные кросс-дистрибутивные пакеты. Эти команды должны использоваться, где это возможно, вместо выполнения задач вручную.

### install-binary

`install-binary` принимает 1-2 аргумента. Первый аргумент — это бинарный файл, который вы хотите установить. Второй — это имя файла, которое должно быть использовано.

Если аргумент имени файла не предоставлен, будет использовано имя входного файла.

Примеры:
```sh
install-binary ./itd
install-binary ./itd itd-2
```

### install-systemd

`install-systemd` устанавливает обычные системные службы *systemd* (см. [install-systemd-user](#install-systemd-user) для пользовательских служб).

Он принимает 1-2 аргумента. Первый аргумент — это служба, которую вы хотите установить. Второй — это имя файла, которое должно быть использовано.

Если аргумент имени файла не предоставлен, будет использовано имя входного файла.

Примеры:
```sh
install-systemd ./syncthing@.service
```

### install-systemd-user

`install-systemd-user` устанавливает пользовательские службы systemd (службы, предназначенные для запуска с флагом `--user`).

Он принимает 1-2 аргумента. Первый аргумент — это служба, которую вы хотите установить. Второй — это имя файла, которое должно быть использовано.

Если аргумент имени файла не предоставлен, будет использовано имя входного файла.

Примеры:
```sh
install-systemd-user ./itd.service infinitime-daemon.service
```

### install-config

`install-config` устанавливает конфигурационные файлы в директорию `/etc`.

Он принимает 1-2 аргумента. Первый аргумент — это конфигурация, которую вы хотите установить. Второй — это имя файла, которое должно быть использовано.

Если аргумент имени файла не предоставлен, будет использовано имя входного файла.

Примеры:
```sh
install-config ./itd.toml
install-config ./itd.example.toml itd.toml
```

### install-license

`install-license` устанавливает файл лицензии.

Он принимает 1-2 аргумента. Первый аргумент — это конфигурация, которую вы хотите установить. Второй — это имя файла, которое должно быть использовано.

Если аргумент имени файла не предоставлен, будет использовано имя входного файла.

Примеры:
```sh
install-license ./LICENSE itd/LICENSE
```

### install-completion

`install-completion` устанавливает файлы для автозавершения для командной строки.

В настоящее время поддерживаются `bash`, `zsh` и `fish`.

Завершения читаются из стандартного ввода, их можно либо передать через конвейер, либо получить из файлов.

Для этой функции требуются два аргумента. Первый — это имя оболочки, второй — это имя завершения.

Примеры:
```sh
./k9s completion fish | install-completion fish k9s
install-completion bash k9s <./k9s/completions/k9s.bash
```

### install-manual

`install-manual` устанавливает страницы `man`. Она принимает один аргумент, который является путем к странице `man`.

Путь установки будет определен на основе номера в конце имени файла. Если номер не может быть извлечен, будет возвращена ошибка.

Примеры:
```sh
install-manual ./man/strelaysrv.1
install-manual ./mdoc.7
```

### install-desktop

`install-desktop` устанавливает desktop-файлы для приложений. Он принимает 1-2 аргумента. Первый аргумент — это конфигурация, которую вы хотите установить. Второй — это имя файла, которое должно быть использовано.

Если аргумент имени файла не предоставлен, будет использовано имя входного файла.

Примеры:
```sh
install-desktop ./${name}/share/admc.desktop
install-desktop ./${name}/share/admc.desktop admc-app.desktop
```

### install-library

`install-library` устанавливает общие и статические библиотеки в правильное место.

Это самая важная вспомогательная функция, так как она содержит логику, чтобы определить, куда установить библиотеки в зависимости от целевого дистрибутива и архитектуры `CPU`. Она почти всегда должна использоваться для установки всех библиотек.

Он принимает 1-2 аргумента. Первый аргумент — это конфигурация, которую вы хотите установить. Второй — это имя файла, которое должно быть использовано.

Если аргумент имени файла не предоставлен, будет использовано имя входного файла.

Примеры:
```sh
install-library ./${name}/build/libadldap.so
```

### git-version

`git-version` возвращает номер версии на основе git-ревизии репозитория.

Если аргумент предоставлен, он будет использован как путь к репозиторию. В противном случае будет использован текущий каталог.

Номер версии будет содержать количество ревизий, точку и короткий хеш текущей ревизии. Например: `118.e4b8348`.

Конвенция AUR включает букву `r` в начале номера версии. Это опускается, так как некоторые дистрибутивы ожидают, что номер версии начнется с цифры.

Примеры:
```sh
git-version
git-version "$srcdir/alr"
```