diff options
Diffstat (limited to 'documentation/content/ru/books/porters-handbook/pkg-files/_index.adoc')
| -rw-r--r-- | documentation/content/ru/books/porters-handbook/pkg-files/_index.adoc | 228 |
1 files changed, 202 insertions, 26 deletions
diff --git a/documentation/content/ru/books/porters-handbook/pkg-files/_index.adoc b/documentation/content/ru/books/porters-handbook/pkg-files/_index.adoc index f68daf0dd9..dc1f0d89a5 100644 --- a/documentation/content/ru/books/porters-handbook/pkg-files/_index.adoc +++ b/documentation/content/ru/books/porters-handbook/pkg-files/_index.adoc @@ -1,22 +1,24 @@ --- -title: Глава 8. Файлы pkg-* -prev: books/porters-handbook/plist +description: 'Хитрости с файлами pkg-*' next: books/porters-handbook/testing -showBookMenu: true -weight: 8 params: - path: "/books/porters-handbook/pkg-files/" + path: /books/porters-handbook/pkg-files/ +prev: books/porters-handbook/plist +showBookMenu: true +tags: ["pkg", "pkg-message", "UCL", "pkg-install", "pkg-deinstall"] +title: 'Глава 9. Файлы pkg-*' +weight: 9 --- [[pkg-files]] -= Файлы pkg-* += pkg-* :doctype: book :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 -:sectnumoffset: 8 +:sectnumoffset: 9 :partnums: :source-highlighter: rouge :experimental: @@ -49,48 +51,212 @@ endif::[] Есть несколько приёмов работы с файлами [.filename]#pkg-*#, которые мы ещё не описали, но они иногда могут быть очень кстати. [[porting-message]] -== [.filename]#pkg-message# +== pkg-message Если вам нужно вывести сообщение для человека, устанавливающего приложение, то вы можете поместить сообщение в файл [.filename]#pkg-message#. Эта возможность часто оказывается полезной для вывода дополнительных шагов установки, которые нужно предпринять после выполнения команды `pkg install`, или для вывода информации о лицензировании. -Если должны выводиться некоторые строки о knobs времени построения или предупреждения, используйте `ECHO_MSG`. Файл [.filename]#pkg-message# только для послеустановочных шагов. Также следует иметь в виду различие между `ECHO_MSG` и `ECHO_CMD`. Первое предназначено для вывода на экран информационного текста, а второе для конвейера команд: +[IMPORTANT] +==== +* Файл [.filename]#pkg-message# должен содержать только информацию, _критически важную_ для настройки и работы в FreeBSD, а также уникальную для данного порта. +* Информация по настройке должна отображаться только при первоначальной установке. Инструкции по обновлению должны показываться только при обновлении с соответствующей версии. +* Не обрамляйте сообщения ни пробелами, ни строками символов (такими как `----------`, `**********` или `==========`). Оставьте форматирование man:pkg[8]. +* Коммиттеры имеют полное право ограничивать существующие сообщения диапазонами установки или обновления, используя спецификации формата UCL. +* Пожалуйста, убедитесь, что используете соответствующие инструменты для управления службами. +** Используйте `service имя start` для запуска службы вместо `/usr/local/etc/rc.d/имя start` +** Используйте `sysrc name_enable=YES` для изменения параметров в rc.conf + +==== + +pkg-message поддерживает два формата: + +raw:: +Обычный текстовый файл. Его сообщение отображается только при установке. + +UCL:: +Если файл начинается с символа "`[`", то он считается файлом в формате UCL. Формат UCL описан на странице https://github.com/vstakhov/libucl[libucl's GitHub page]. + +[NOTE] +==== +Не добавляйте запись для [.filename]#pkg-message# в [.filename]#pkg-plist#. +==== + +[[porting-message-ucl]] +=== UCL в pkg-message + +Формат следующий. Это должен быть массив объектов. Сами объекты могут содержать следующие ключевые слова: + +`message`:: +Отображаемое сообщение. Этот ключевой параметр является обязательным. + +`type`:: +Когда сообщение должно быть отображено. + +`maximum_version`:: +Только если `type` имеет значение `upgrade`. Отображается, если обновление выполняется с версии строго ниже указанной. + +`minimum_version`:: +Только если `type` имеет значение `upgrade`. Отображается, если обновление выполняется с версии, строго большей, чем указанная. + +Ключевые слова `maximum_version` и `minimum_version` можно комбинировать. + +Ключевое слово `type` может иметь три значения: + +`install`:: +Сообщение должно отображаться только при установке пакета. + +`remove`:: +Сообщение должно отображаться только при удалении пакета. + +`upgrade`:: +сообщение должно отображаться только во время обновления пакета. + +[IMPORTANT] +==== +Для сохранения совместимости с файлами [.filename]#pkg-message#, не использующими UCL, первая строка UCL [.filename]#pkg-message# _ДОЛЖНА быть_ одиночным символом "`[`", а последняя строка _ДОЛЖНА быть_ одиночным символом "`]`". +==== + +[[porting-message-ucl-short-ex]] +.Короткие строки UCL +[example] +==== + +Сообщение ограничено двойными кавычками `"`, это используется для простых однострочных строк: [.programlisting] .... -update-etc-shells: - @${ECHO_MSG} "updating /etc/shells" - @${CP} /etc/shells /etc/shells.bak - @( ${GREP} -v ${PREFIX}/bin/bash /etc/shells.bak; \ - ${ECHO_CMD} ${PREFIX}/bin/bash) >/etc/shells - @${RM} /etc/shells.bak +[ +{ type: install + message: "Simple message" +} +] .... -[NOTE] ==== -Файл [.filename]#pkg-message# не нужно добавлять в [.filename]#pkg-plist#. + +[[porting-message-ucl-multiline-ex]] +.Многострочные строки UCL +[example] +==== + +Многострочные строки используют стандартную нотацию heredoc. Разделитель многострочной строки _должен_ начинаться сразу после символов `<<` без пробелов и _должен_ состоять только из заглавных букв. Чтобы завершить многострочную строку, добавьте строку-разделитель на отдельной строке без пробелов. Сообщение из раздела crossref:pkg-files[porting-message-ucl-short-ex,Короткие строки UCL] может быть записано как: + +[.programlisting] +.... +[ +{ type: install + message: <<EOM +Simple message +EOM +} +] +.... + +==== + +[[porting-message-ucl-ex2]] +.Показать сообщение при установке/удалении +[example] +==== + +Когда сообщение нужно отображать только при установке или удалении, укажите тип: + +[.programlisting] +.... +[ +{ + type: remove + message: "package being removed." +} +{ type: install, message: "package being installed."} +] +.... + +==== + +[[porting-message-ucl-ex3]] +.Показать сообщение при обновлении +[example] +==== + +При обновлении порта отображаемое сообщение может быть ещё более адаптировано к потребностям порта. + +[.programlisting] +.... +[ +{ + type: upgrade + message: "Package is being upgraded." +} +{ + type: upgrade + maximum_version: "1.0" + message: "Upgrading from before 1.0 need to do this." +} +{ + type: upgrade + minimum_version: "1.0" + message: "Upgrading from after 1.0 should do that." +} +{ + type: upgrade + maximum_version: "3.0" + minimum_version: "1.0" + message: "Upgrading from > 1.0 and < 3.0 remove that file." +} +] +.... + +[IMPORTANT] +**** +При отображении сообщения во время обновления важно ограничить случаи, когда оно показывается пользователю. Чаще всего это делается с помощью `maximum_version`, чтобы ограничить его использование обновлениями до определенной версии, когда требуется выполнить конкретное действие. +**** + ==== [[pkg-install]] -== [.filename]#pkg-install# +== pkg-install, pkg-pre-install и pkg-post-install -Если при установке бинарного пакета по команде `pkg add` или `pkg install` вашему порту нужно выполнить какие-то команды, то вы можете это сделать с помощью скрипта [.filename]#pkg-install#. Этот скрипт будет автоматически добавлен к пакету и будет дважды запускаться командой `pkg`: первый раз в виде `${SH} pkg-install ${PKGNAME} PRE-INSTALL`, а второй раз как `${SH} {PKGNAME} POST-INSTALL`. Для распознавания того, в каком режиме запущен скрипт, можно использовать параметр `$2`. Переменная окружения `PKG_PREFIX` будет принимать значение, соответствующее каталогу, в который устанавливается пакет. +Если порту необходимо выполнять команды при установке бинарного пакета с помощью `pkg add` или `pkg install`, используйте [.filename]#pkg-install#. Он запускается дважды через `pkg`: первый раз как `${SH} pkg-install ${PKGNAME} PRE-INSTALL` перед установкой пакета и второй раз как `${SH} pkg-install ${PKGNAME} POST-INSTALL` после его установки. Переменная `$2` может быть проверена, чтобы определить, в каком режиме выполняется скрипт. Переменная окружения `PKG_PREFIX` устанавливается равной имени каталога установки пакета. + +Если используется [.filename]#pkg-pre-install# или [.filename]#pkg-post-install#, скрипт выполняется только один раз (до или после установки пакета), с единственным аргументом `${PKGNAME}`. Использование [.filename]#pkg-pre-install.lua# или [.filename]#pkg-post-install.lua# запускает скрипт на Lua вместо shell-скрипта. Скрипты на Lua, выполняемые `pkg`, предоставляют некоторые расширения и несколько ограничений, которые описаны в man:pkg-lua-script[5]. [NOTE] ==== -Этот скрипт не запускается автоматически, если вы устанавливаете порт командой `make install`. Если же вам действительно необходимо его запустить, то запустите его явно из файла [.filename]#Makefile# порта строкой вида `PKG_PREFIX=${PREFIX} ${SH} $ {PKGINSTALL}${PKGNAME} PRE-INSTALL`. +Использование [.filename]#pkg-pre-install# (или [.filename]#pkg-pre-install.lua#) и [.filename]#pkg-post-install# (или [.filename]#pkg-post-install.lua#) предпочтительнее, чем использование [.filename]#pkg-install#. +==== + +Эти скрипты автоматически добавляются в список упаковки. + +[IMPORTANT] +==== +Эти скрипты предназначены для упрощения настройки пакетов после установки. Они _не должны_ использоваться для запуска служб, остановки служб или выполнения любых других команд, которые изменяют текущую работающую систему. ==== [[pkg-deinstall]] -== [.filename]#pkg-deinstall# +== pkg-deinstall, pkg-pre-deinstall и pkg-post-deinstall -Этот скрипт вызывается при удалении пакета. +Эти скрипты выполняются при удалении пакета. -Этот скрипт будет дважды запускаться командой `pkg delete`. Первый раз как `${SH} pkg-deinstall ${PKGNAME} DEINSTALL`, а второй раз как `${SH} pkg-deinstall ${PKGNAME} POST-DEINSTALL`. +Скрипт [.filename]#pkg-deinstall# выполняется дважды командой `pkg delete`. Первый раз как `${SH} pkg-deinstall ${PKGNAME} DEINSTALL` до удаления порта и второй раз как `${SH} pkg-deinstall ${PKGNAME} POST-DEINSTALL` после удаления порта. Переменная `$2` может быть проверена для определения режима, в котором выполняется скрипт. Переменная окружения `PKG_PREFIX` устанавливается в каталог установки пакета. + +Если используется [.filename]#pkg-pre-deinstall# или [.filename]#pkg-post-deinstall#, скрипт выполняется только один раз (до или после удаления пакета) с единственным аргументом `${PKGNAME}`. Использование [.filename]#pkg-pre-deinstall.lua# или [.filename]#pkg-post-deinstall.lua# запустит скрипт на Lua вместо shell-скрипта. Скрипты на Lua, выполняемые `pkg`, предоставляют некоторые расширения и ограничения, которые описаны в man:pkg-lua-script[5]. + +[NOTE] +==== +Использование [.filename]#pkg-pre-deinstall# (или [.filename]#pkg-pre-deinstall.lua#) и [.filename]#pkg-post-deinstall# (или [.filename]#pkg-post-deinstall.lua#) предпочтительнее, чем использование [.filename]#pkg-deinstall#. +==== + +Эти скрипты автоматически добавляются в список упаковки. + +[IMPORTANT] +==== +Эти скрипты предназначены для упрощения очистки после удаления пакетов. Они _не должны_ использоваться для запуска служб, остановки служб или выполнения любых других команд, которые изменяют текущую работающую систему. +==== [[pkg-names]] == Изменение имён файлов [.filename]#pkg-*# -Все имена файлов [.filename]#pkg-\*# определяются с помощью переменных, так что вы можете изменить их, если это нужно, в вашем файле [.filename]#Makefile#. Это особенно полезно, если вы используете одни и те же файлы [.filename]#pkg-*# совместно между несколькими портами или пишете в один из вышеперечисленных файлов (в главе о <<porting-wrkdir,"записи в каталоги, отличные от ``WRKDIR``">> объяснено, почему не рекомендуется осуществлять запись непосредственно в файлы [.filename]#pkg-*#. +Все имена файлов [.filename]#pkg-\*# определяются с помощью переменных, так что вы можете изменить их, если это нужно, в вашем файле [.filename]#Makefile#. Это особенно полезно, если вы используете одни и те же файлы [.filename]#pkg-*# совместно между несколькими портами или пишете в один из вышеперечисленных файлов (в главе о crossref:porting-dads[porting-wrkdir,"записи в каталоги, отличные от ``WRKDIR``"] объяснено, почему не рекомендуется осуществлять запись непосредственно в файлы [.filename]#pkg-*#). Вот список имён переменных и их значений по умолчанию. (Значение `PKGDIR` по умолчанию равно `${MASTERDIR}`.) @@ -109,15 +275,25 @@ update-etc-shells: |`PKGINSTALL` |`${PKGDIR}/pkg-install` +|`PKGPREINSTALL` +|`${PKGDIR}/pkg-pre-install` + +|`PKGPOSTINSTALL` +|`${PKGDIR}/pkg-post-install` + |`PKGDEINSTALL` |`${PKGDIR}/pkg-deinstall` +|`PKGPREDEINSTALL` +|`${PKGDIR}/pkg-pre-deinstall` + +|`PKGPOSTDEINSTALL` +|`${PKGDIR}/pkg-post-deinstall` + |`PKGMESSAGE` |`${PKGDIR}/pkg-message` |=== -Пожалуйста, изменяйте значения этих переменных, а не переопределяйте `PKG_ARGS`. Если вы измените значение переменных `PKG_ARGS`, то эти файлы при установке из порта будут установлены в каталог [.filename]#/var/db/pkg# некорректно. - [[using-sub-files]] == Использование `SUB_FILES` и `SUB_LIST` |