diff --git a/documentation/content/ru/books/porters-handbook/_index.adoc b/documentation/content/ru/books/porters-handbook/_index.adoc index 1b6f7d092c..0395f5d5e7 100644 --- a/documentation/content/ru/books/porters-handbook/_index.adoc +++ b/documentation/content/ru/books/porters-handbook/_index.adoc @@ -1,68 +1,52 @@ --- title: Руководство FreeBSD по созданию портов authors: - author: The FreeBSD Documentation Project copyright: 2000-2020 The FreeBSD Documentation Project trademarks: ["freebsd", "sun", "unix", "general"] +next: books/porters-handbook/porting-why +add_single_page_link: true isIndex: true --- = Руководство FreeBSD по созданию портов :doctype: book :toc: macro -:toclevels: 2 +:toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :partnums: :source-highlighter: rouge :experimental: -:book: true -:pdf: false +:images-path: books/porters-handbook/ ifdef::env-beastie[] ifdef::backend-html5[] include::shared/authors.adoc[] include::shared/mirrors.adoc[] include::shared/releases.adoc[] include::shared/attributes/attributes-{{% lang %}}.adoc[] include::shared/{{% lang %}}/teams.adoc[] include::shared/{{% lang %}}/mailing-lists.adoc[] include::shared/{{% lang %}}/urls.adoc[] :chapters-path: content/{{% lang %}}/books/porters-handbook/ endif::[] ifdef::backend-pdf,backend-epub3[] :chapters-path: include::../../../../../shared/asciidoctor.adoc[] endif::[] endif::[] ifndef::env-beastie[] :chapters-path: include::../../../../../shared/asciidoctor.adoc[] endif::[] ''' -toc::[] +include::{chapters-path}toc.adoc[] include::{chapters-path}toc-tables.adoc[] include::{chapters-path}toc-examples.adoc[] - -include::{chapters-path}porting-why/chapter.adoc[leveloffset=+1] -include::{chapters-path}new-port/chapter.adoc[leveloffset=+1] -include::{chapters-path}quick-porting/chapter.adoc[leveloffset=+1] -include::{chapters-path}slow-porting/chapter.adoc[leveloffset=+1] -include::{chapters-path}makefiles/chapter.adoc[leveloffset=+1] -include::{chapters-path}special/chapter.adoc[leveloffset=+1] -include::{chapters-path}plist/chapter.adoc[leveloffset=+1] -include::{chapters-path}pkg-files/chapter.adoc[leveloffset=+1] -include::{chapters-path}testing/chapter.adoc[leveloffset=+1] -include::{chapters-path}upgrading/chapter.adoc[leveloffset=+1] -include::{chapters-path}security/chapter.adoc[leveloffset=+1] -include::{chapters-path}porting-dads/chapter.adoc[leveloffset=+1] -include::{chapters-path}porting-samplem/chapter.adoc[leveloffset=+1] -include::{chapters-path}keeping-up/chapter.adoc[leveloffset=+1] -include::{chapters-path}uses/chapter.adoc[leveloffset=+1] -include::{chapters-path}versions/chapter.adoc[leveloffset=+1] diff --git a/documentation/content/ru/books/porters-handbook/_index.adoc b/documentation/content/ru/books/porters-handbook/book.adoc similarity index 50% copy from documentation/content/ru/books/porters-handbook/_index.adoc copy to documentation/content/ru/books/porters-handbook/book.adoc index 1b6f7d092c..c10afd18bc 100644 --- a/documentation/content/ru/books/porters-handbook/_index.adoc +++ b/documentation/content/ru/books/porters-handbook/book.adoc @@ -1,68 +1,68 @@ --- title: Руководство FreeBSD по созданию портов authors: - author: The FreeBSD Documentation Project copyright: 2000-2020 The FreeBSD Documentation Project trademarks: ["freebsd", "sun", "unix", "general"] -isIndex: true +add_split_page_link: true --- -= Руководство FreeBSD по созданию портов += FreeBSD Porter's Handbook :doctype: book :toc: macro :toclevels: 2 :icons: font :sectnums: :sectnumlevels: 6 :partnums: :source-highlighter: rouge :experimental: :book: true :pdf: false ifdef::env-beastie[] ifdef::backend-html5[] include::shared/authors.adoc[] include::shared/mirrors.adoc[] include::shared/releases.adoc[] include::shared/attributes/attributes-{{% lang %}}.adoc[] include::shared/{{% lang %}}/teams.adoc[] include::shared/{{% lang %}}/mailing-lists.adoc[] include::shared/{{% lang %}}/urls.adoc[] :chapters-path: content/{{% lang %}}/books/porters-handbook/ endif::[] ifdef::backend-pdf,backend-epub3[] :chapters-path: include::../../../../../shared/asciidoctor.adoc[] endif::[] endif::[] ifndef::env-beastie[] :chapters-path: include::../../../../../shared/asciidoctor.adoc[] endif::[] ''' toc::[] include::{chapters-path}toc-tables.adoc[] include::{chapters-path}toc-examples.adoc[] -include::{chapters-path}porting-why/chapter.adoc[leveloffset=+1] -include::{chapters-path}new-port/chapter.adoc[leveloffset=+1] -include::{chapters-path}quick-porting/chapter.adoc[leveloffset=+1] -include::{chapters-path}slow-porting/chapter.adoc[leveloffset=+1] -include::{chapters-path}makefiles/chapter.adoc[leveloffset=+1] -include::{chapters-path}special/chapter.adoc[leveloffset=+1] -include::{chapters-path}plist/chapter.adoc[leveloffset=+1] -include::{chapters-path}pkg-files/chapter.adoc[leveloffset=+1] -include::{chapters-path}testing/chapter.adoc[leveloffset=+1] -include::{chapters-path}upgrading/chapter.adoc[leveloffset=+1] -include::{chapters-path}security/chapter.adoc[leveloffset=+1] -include::{chapters-path}porting-dads/chapter.adoc[leveloffset=+1] -include::{chapters-path}porting-samplem/chapter.adoc[leveloffset=+1] -include::{chapters-path}keeping-up/chapter.adoc[leveloffset=+1] -include::{chapters-path}uses/chapter.adoc[leveloffset=+1] -include::{chapters-path}versions/chapter.adoc[leveloffset=+1] +include::{chapters-path}porting-why/_index.adoc[leveloffset=+1] +include::{chapters-path}new-port/_index.adoc[leveloffset=+1] +include::{chapters-path}quick-porting/_index.adoc[leveloffset=+1] +include::{chapters-path}slow-porting/_index.adoc[leveloffset=+1] +include::{chapters-path}makefiles/_index.adoc[leveloffset=+1] +include::{chapters-path}special/_index.adoc[leveloffset=+1] +include::{chapters-path}plist/_index.adoc[leveloffset=+1] +include::{chapters-path}pkg-files/_index.adoc[leveloffset=+1] +include::{chapters-path}testing/_index.adoc[leveloffset=+1] +include::{chapters-path}upgrading/_index.adoc[leveloffset=+1] +include::{chapters-path}security/_index.adoc[leveloffset=+1] +include::{chapters-path}porting-dads/_index.adoc[leveloffset=+1] +include::{chapters-path}porting-samplem/_index.adoc[leveloffset=+1] +include::{chapters-path}keeping-up/_index.adoc[leveloffset=+1] +include::{chapters-path}uses/_index.adoc[leveloffset=+1] +include::{chapters-path}versions/_index.adoc[leveloffset=+1] diff --git a/documentation/content/ru/books/porters-handbook/chapters-order.adoc b/documentation/content/ru/books/porters-handbook/chapters-order.adoc index f7a766c744..80ccba6333 100644 --- a/documentation/content/ru/books/porters-handbook/chapters-order.adoc +++ b/documentation/content/ru/books/porters-handbook/chapters-order.adoc @@ -1,16 +1,16 @@ -porting-why/chapter.adoc -new-port/chapter.adoc -quick-porting/chapter.adoc -slow-porting/chapter.adoc -makefiles/chapter.adoc -special/chapter.adoc -plist/chapter.adoc -pkg-files/chapter.adoc -testing/chapter.adoc -upgrading/chapter.adoc -security/chapter.adoc -porting-dads/chapter.adoc -porting-samplem/chapter.adoc -keeping-up/chapter.adoc -uses/chapter.adoc -versions/chapter.adoc +porting-why/_index.adoc +new-port/_index.adoc +quick-porting/_index.adoc +slow-porting/_index.adoc +makefiles/_index.adoc +special/_index.adoc +plist/_index.adoc +pkg-files/_index.adoc +testing/_index.adoc +upgrading/_index.adoc +security/_index.adoc +porting-dads/_index.adoc +porting-samplem/_index.adoc +keeping-up/_index.adoc +uses/_index.adoc +versions/_index.adoc diff --git a/documentation/content/ru/books/porters-handbook/keeping-up/chapter.adoc b/documentation/content/ru/books/porters-handbook/keeping-up/_index.adoc similarity index 100% rename from documentation/content/ru/books/porters-handbook/keeping-up/chapter.adoc rename to documentation/content/ru/books/porters-handbook/keeping-up/_index.adoc diff --git a/documentation/content/ru/books/porters-handbook/makefiles/chapter.adoc b/documentation/content/ru/books/porters-handbook/makefiles/_index.adoc similarity index 98% rename from documentation/content/ru/books/porters-handbook/makefiles/chapter.adoc rename to documentation/content/ru/books/porters-handbook/makefiles/_index.adoc index 721539ccb6..a8cc2643e9 100644 --- a/documentation/content/ru/books/porters-handbook/makefiles/chapter.adoc +++ b/documentation/content/ru/books/porters-handbook/makefiles/_index.adoc @@ -1,2375 +1,2375 @@ --- title: Глава 5. Настройка файла Makefile prev: books/porters-handbook/slow-porting next: books/porters-handbook/special --- [[makefiles]] = Настройка файла Makefile :doctype: book :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :sectnumoffset: 5 :partnums: :source-highlighter: rouge :experimental: :gcc-plus-plus: g++ :images-path: books/porters-handbook/ ifdef::env-beastie[] ifdef::backend-html5[] :imagesdir: ../../../../images/{images-path} endif::[] ifndef::book[] include::shared/authors.adoc[] include::shared/mirrors.adoc[] include::shared/releases.adoc[] include::shared/attributes/attributes-{{% lang %}}.adoc[] include::shared/{{% lang %}}/teams.adoc[] include::shared/{{% lang %}}/mailing-lists.adoc[] include::shared/{{% lang %}}/urls.adoc[] toc::[] endif::[] ifdef::backend-pdf,backend-epub3[] include::../../../../../shared/asciidoctor.adoc[] endif::[] endif::[] ifndef::env-beastie[] toc::[] include::../../../../../shared/asciidoctor.adoc[] endif::[] Настройка файла [.filename]#Makefile# достаточно проста, и мы снова предполагаем, что перед тем, как начать, вы посмотрите на существующие примеры. К тому же в этом руководстве имеется <>, так что взгляните на него и, пожалуйста, следуйте порядку переменных и разделов в этом образце, чтобы облегчить чтение вашего порта другими людьми. Итак, расположим решаемые задачи в порядке их возникновения при создании вашего нового файла [.filename]#Makefile#: [[makefile-source]] == Оригинальные исходный код Находится ли он в каталоге `DISTDIR` в виде стандартного упакованного архиватором `gzip` tar-архива с именем типа [.filename]#foozolix-1.2.tar.gz#? Если это так, можно перейти к следующему шагу. Если нет, то вы должны попытаться переопределить некоторые из переменных `DISTVERSION`, `DISTNAME`, `EXTRACT_CMD`, `EXTRACT_BEFORE_ARGS`, `EXTRACT_AFTER_ARGS`, `EXTRACT_SUFX` или `DISTFILES` в зависимости от того, насколько необычен формат дистрибутивного файла. В худшем случае вы можете просто определить свою собственную цель `do-extract` для переопределения действий по умолчанию, хотя к этому нужно будет прибегать в очень редких случаях, если вообще придётся. [[makefile-naming]] == Именование В первой части [.filename]#Makefile# порта ему даётся название, указывается его номер версии и принадлежность к правильной категории. === `PORTNAME` и `PORTVERSION` В переменной `PORTNAME` вы должны указать основную часть имени вашего порта, а в переменной `PORTVERSION` - номер версии. [[makefile-naming-revepoch]] === `PORTREVISION` и `PORTEPOCH` ==== `PORTREVISION` Переменная `PORTREVISION` представляет собой монотонно увеличивающееся число, которое обнуляется при каждом увеличении значения переменной `PORTVERSION` (то есть каждый раз, когда создателями выпускается новый официальный релиз), и добавляется к имени пакета, если оно не равно нулю. Изменения в `PORTREVISION` используются автоматизированными инструментами (например, `pkg version`, см. man:pkg-version[8]) для определения факта появления нового пакета. Значение `PORTREVISION` должно увеличиваться каждый раз, когда в порте FreeBSD делаются изменения, которые как-либо меняют получаемый пакет. Сюда относятся только изменения, затрагивающие построение пакета с <> по умолчанию. Примеры случаев, когда значение `PORTREVISION` должно быть увеличено: * Добавление патчей для исправления уязвимостей, ошибок, или добавления новой функциональности в порт. * Изменения в файле [.filename]#Makefile# порта для включения и выключения параметров, определяемых при компиляции пакета. * Изменения в списке упаковки или в поведении пакета во время его установки (например, изменение скрипта, генерирующего начальные данные для пакета, такие, как ssh-ключи для хоста). * Увеличение версии динамической библиотеки, от которой зависит порт (в этом случае тот, кто попытается установить старый пакет после установки более новой версии библиотеки, не сможет этого сделать, потому что при этом будет делаться поиск старой библиотеки libfoo.x, а не libfoo.(x+1)). * Большие функциональные изменения в дистрибутивном файле порта, происходящие без объявлений, и приводящие к большим изменениям, то есть изменения в дистрибутиве требуют корректировки файла [.filename]#distinfo# без соответствующего изменения `PORTVERSION`, когда как команда `diff -ru` между новой и старой версиями показывает нетривиальные изменения в коде. Примеры изменений, которые не требуют увеличения переменной `PORTREVISION`: * Изменения стиля в скелете порта без функциональных изменений в пакете. * Изменения в переменной `MASTER_SITES` или другие функциональные изменения порта, которые не затрагивают получающегося пакета. * Тривиальные патчи к дистрибутивному файлу, такие, как исправления опечаток, которые не так уж важны, что пользователи пакета должны озаботиться обновлением. * Исправления, касающиеся этапа построения, которые делают возможным построение пакета, если ранее это было невозможно сделать (пока изменения не приводят к изменению работы на любых других платформах, на которых порт ранее строился). Так как `PORTREVISION` отражает содержимое пакета, то, если ранее пакет не строился, то нет нужды увеличивать `PORTREVISION` для отметки изменения. Правило, которому нужно приблизительно следовать, заключается в том, что нужно спрашивать себя, является ли вносимое в порт изменение таким, что от него выиграют все (в виде усовершенствования, исправления или благодаря тому, что новый пакет будет вообще работоспособным), и примите во внимание тот факт, что при этом все, кто регулярно обновляют своё дерево портов, будут обязаны это сделать. Если это так, то переменная `PORTREVISION` должна быть увеличена. ==== `PORTEPOCH` Время от времени разработчик программного обеспечения или создатель порта FreeBSD делают что-то не так и выпускают версию программы, номер которой меньше предыдущей версии. Примером этого является порт, название которого меняется с foo-20000801 на foo-1.0 (изначально это не считалось бы более новой версией, так как 20000801 численно больше, чем 1). [TIP] ==== Результат сравнения номера версии не всегда очевиден. Для выполнения сравнения двух строк с номером версии можно использовать `pkg version` (см. man:pkg-version[8]). Например: [source,shell] .... % pkg version -t 0.031 0.29 > .... Строка `>` в выводе команды означает, что версия 0.031 считается выше, чем версия 0.29, что может быть не очевидно для того, кто выполняет портирование. ==== В ситуациях, подобных этой, должно быть увеличено значение `PORTEPOCH`. Если значение `PORTEPOCH` не равно нулю, то оно добавляется к имени пакета, как описано в разделе выше. Значение `PORTEPOCH` никогда не должно уменьшаться или сбрасываться в ноль, потому что это приведёт к ошибке сравнения с пакетом с меньшим номером эпохи (то есть то, что пакет устарел, обнаружено не будет): номер новой версии (например, `1.0,1` в примере выше) останется меньше, чем номер предыдущей версии (20000801), однако суффикс `,1` интерпретируется различными автоматизированными утилитами особым образом, и окажется больше, чем предполагаемый суффикс `,0` более раннего пакета). Некорректное уменьшение или сброс `PORTEPOCH` приводит к печальным последствиям; если вы не поняли, о чём шла речь ранее, пожалуйста, всё же разберитесь с этим, либо спросите в списках рассылки. Предполагается, что в большинстве портов переменная `PORTEPOCH` использоваться не будет, но при корректном использовании `PORTVERSION` может появиться необходимость её иметь, если в будущих релизах программное обеспечение должно изменить структуру номера версии. Однако создателям портов для FreeBSD нужно быть внимательными, когда разработчик выпускает релиз без официального номера версии - эдакие "промежуточные" релизы. Имеется соблазн пометить релиз датой его выхода, что может вызвать проблемы, как и в примере выше, когда будет выпущен новый "официальный" релиз. Например, если промежуточный релиз помечен датой 20000917, а предыдущая версия программного обеспечения имела номер 1.2, то промежуточному релизу должно быть поставлено в соответствие значение `PORTVERSION`, равное 1.2.20000917 или что-то похожее, но не 20000917, так как последующий релиз, скажем, 1.3, должен иметь численно большее значение. ==== Пример использования переменных `PORTREVISION` и `PORTEPOCH` Выполнен коммит порта `gtkmumble`, версии `0.10`, в коллекцию портов. [.programlisting] .... PORTNAME= gtkmumble PORTVERSION= 0.10 .... Значение `PKGNAME` станет равным `gtkmumble-0.10`. Обнаружена брешь в безопасности, исправление которой потребовало создания локального патча для FreeBSD. Соответственно было увеличено значение переменной `PORTREVISION`. [.programlisting] .... PORTNAME= gtkmumble PORTVERSION= 0.10 PORTREVISION= 1 .... `PKGNAME` принимает значение `gtkmumble-0.10_1` Разработчиком выпущена новая версия с номером `0.2` (оказалось, что под номером `0.10` автор имел в виду `0.1.0`, а не "то, что будет выпущено после версии 0.9" - извините, теперь уже поздно). Так как новый младший номер версии `2` по значению меньше, чем номер предыдущей версии `10`, то должно быть увеличено значение `PORTEPOCH` для того, чтобы заставить распознавать вновь создаваемый пакет как "более новый". Так как это новый релиз программы, то `PORTREVISION` обнуляется (или удаляется из файла [.filename]#Makefile#). [.programlisting] .... PORTNAME= gtkmumble PORTVERSION= 0.2 PORTEPOCH= 1 .... `PKGNAME` принимает значение `gtkmumble-0.2,1` Следующий релиз имеет номер версии 0.3. Так как значение переменной `PORTEPOCH` никогда не уменьшается, что переменные, определяющие версии, теперь выглядят так: [.programlisting] .... PORTNAME= gtkmumble PORTVERSION= 0.3 PORTEPOCH= 1 .... `PKGNAME` принимает значение `gtkmumble-0.3,1` [NOTE] ==== Если значение `PORTEPOCH` этим обновлением было бы сброшено в `0`, то кто-нибудь, имеющий установленный пакет `gtkmumble-0.10_1`, не смог бы опознать пакет `gtkmumble-0.3` как более новый, так как `3` было бы меньше, чем `10`. Помните, что в первую очередь это касается `PORTEPOCH`. ==== === Переменные `PKGNAMEPREFIX` и `PKGNAMESUFFIX` Две необязательные переменные, `PKGNAMEPREFIX` и `PKGNAMESUFFIX`, объединяются со значениями `PORTNAME` и `PORTVERSION` для формирования `PKGNAME` в форме `${PKGNAMEPREFIX}${PORTNAME}${PKGNAMESUFFIX}-${PORTVERSION}`. Добейтесь того, чтобы это соответствовало нашим <>. В частности, в переменной `PORTVERSION` _не разрешается_ использование дефиса (`-`). Кроме того, если в имени пакета присутствует часть _language-_ или _-compiled.specifics_ (смотрите ниже), то используйте переменные `PKGNAMEPREFIX` и `PKGNAMESUFFIX`, соответственно. Не делайте их частью значения переменной `PORTNAME`. [[porting-pkgname]] === Соглашения по именованию пакетов Далее описаны некоторые соглашения, которым вы должны следовать в именовании ваших пакетов. Они были разработаны для облегчения просмотра каталога, так как имеется уже тысячи пакетов, а пользователи отвернутся от нас, если список не понравится их взору! Имя пакета должно иметь вид [.filename]#language_region-name-compiled.specifics-version.numbers#. Имя пакета определяется как `${PKGNAMEPREFIX}${PORTNAME}${PKGNAMESUFFIX}-${PORTVERSION}`. Вы должны задавать значения переменных в соответствии с этим форматом. . FreeBSD пытается поддерживать языки, на которых разговаривают её пользователи. Часть _language-_ должна быть двухсимвольным сокращением от названия языка по стандарту ISO-639, если порт специфичен для конкретного языка. Примерами являются `ja` для японского, `ru` для русского, `vi` для вьетнамского, `zh` для китайского, `ko` для корейского и `de` для немецкого языков. + Если ваш порт специфичен для конкретного региона внутри области использования языка, добавьте также двухсимвольный код страны. Примерами являются `en_US` для US English и `fr_CH` для Swiss French. + Часть _language-_ должна задаваться в переменной `PKGNAMEPREFIX`. . Первая буква части [.filename]#name# должна быть в нижнем регистре. (Оставшаяся часть названия может содержать буквы в верхнем регистре, так что принимайте решение сами, когда преобразуете имя программного пакета, содержащего в имени некоторое количество заглавных букв.) Существует традиция именовать модули для `Perl 5`, добавляя впереди `p5-` и преобразуя пару двоеточий в дефис; например, модуль `Data::Dumper` будет именоваться `p5-Data-Dumper`. . Убедитесь, что имя порта и версия четко отделены и размещаются в переменных `PORTNAME` и `PORTVERSION`. Единственная причина, по которой `PORTNAME` содержит версионную часть, это если полученный дистрибутив сам назван таким образом, как это сделано для портов [.filename]#textproc/libxml2# или [.filename]#japanese/kinput2-freewnn#. В противном случае `PORTNAME` не должен содержать никакой информации, указывающей на версию. То, что некоторые порты имеют одинаковый `PORTNAME`, является вполне нормальным, как для портов [.filename]#www/apache*#; в этом случае различные версии (и различные записи в индексе) отличаются по значениям `PKGNAMEPREFIX` и `PKGNAMESUFFIX`. . Если порт может быть построен с различными <> (обычно это часть имени каталога в семействе портов), то часть _-compiled.specifics_ должна определять вкомпилированные значения по умолчанию (дефис не обязателен). Примерами являются размеры бумаги и шрифтов. + Часть _-compiled.specifics_ должна задаваться в переменной `PKGNAMESUFFIX`. . Строка с номером версии должна следовать за дефисом (`-`) и являться списком разделенных двоеточием чисел и букв в нижнем регистре. В частности, не разрешается иметь еще один дефис внутри строки с обозначением номера версии. Единственным исключением является строчка `pl` (означающая "patchlevel"), которая может использоваться _только_ тогда, когда у программного обеспечения нет старшего и младшего номера версии. Если в номер версии программного обеспечения включена строчка типа "alpha", "beta", "rc" или "pre", возьмите из неё первую букву и поставьте её непосредственно после точки. Если после таких строк номер версии ещё продолжается, то после буквы должно следовать число без дополнительной разделяющей точки. + Смысл такого формата заключается в удобстве сортировки портов по номеру версии. В частности, следите за тем, чтобы компоненты номера версии разделялись точкой, и если там присутствует дата, то используйте формат `0.0.yyyy.mm.dd`, но не `dd.mm.yyyy` или не совместимый с проблемой Y2K `yy.mm.dd`. Добавление к версии префикса `0.0.` является важным, в случае если выпущен релиз с присвоением настоящей версии, которая в числовом представлении, конечно же, будет ниже, чем `yyyy`. Вот несколько (реальных) примеров того, как преобразовать имя из оригинального, придуманного авторами, к подходящему для имени пакета: [.informaltable] [cols="1,1,1,1,1,1", frame="none", options="header"] |=== | Имя дистрибутива | PKGNAMEPREFIX | PORTNAME | PKGNAMESUFFIX | PORTVERSION | Обоснование |mule-2.2.2 |(пусто) |mule |(пусто) |2.2.2 |Изменений не потребовалось |EmiClock-1.0.2 |(пусто) |emiclock |(пусто) |1.0.2 |Для отдельных программ имена с заглавными буквами запрещены |rdist-1.3alpha |(пусто) |rdist |(пусто) |1.3.a |Строчки типа `alpha` запрещены |es-0.9-beta1 |(пусто) |es |(пусто) |0.9.b1 |Строчки типа `beta` запрещены |mailman-2.0rc3 |(пусто) |mailman |(пусто) |2.0.r3 |Строчки типа `rc` запрещены |v3.3beta021.src |(пусто) |tiff |(пусто) |3.3 |Что это такое было вообще? |tvtwm |(пусто) |tvtwm |(пусто) |pl11 |Всегда требуется указание номера версии |piewm |(пусто) |piewm |(пусто) |1.0 |Всегда требуется указание номера версии |xvgr-2.10pl1 |(пусто) |xvgr |(пусто) |2.10.1 |`pl` разрешено только при отсутствии старшего/младшего номера версии |gawk-2.15.6 |ja- |gawk |(пусто) |2.15.6 |Версия на японском языке |psutils-1.13 |(пусто) |psutils |-letter |1.13 |Размер бумаги задается статически во время построения пакета |pkfonts |(пусто) |pkfonts |300 |1.0 |пакет для шрифтов 300dpi |=== Если в исходном коде абсолютно нет информации о номере версии и не похоже, что автор собирается выпускать другую версию, то в качестве номера версии задайте просто `1.0` (как в примере с `piewm` выше). В противном случае спросите автора программы или используйте дату (`0.0.yyyy.mm.dd`) в качестве номера версии. [[makefile-categories]] == Разделение по категориям === `CATEGORIES` В процессе создания пакета он помещается в каталог [.filename]#/usr/ports/packages/All#, а в одном или более подкаталогов из [.filename]#/usr/ports/packages# создаются на него ссылки. Имена этих подкаталогов определяются переменной `CATEGORIES`. Такая схема нужна для облегчения жизни пользователя, когда он сталкивается с массой пакетов на FTP-сервере или компакт-диске. Пожалуйста, посмотрите на <> и выберите те из них, которые более всего подходят к вашему порту. Этот список также определяет, куда в дереве портов будет помещен порт. Если вы укажете здесь более одной категории, то предполагается, что файлы порта будут помещены в подкаталог с именем первой категории. Посмотрите <> для получения подробной информации о том, как правильно выбрать категории. [[porting-categories]] === Текущий список категорий Вот текущий список категорий. Те, которые отмечены звёздочкой (`*`), являются _виртуальными_ категориями-они не имеют собственного подкаталога в дереве портов. Они используются только в качестве вторичных категорий, и только для поиска. [NOTE] ==== Для невиртуальных категорий имеется однострочное описание в `COMMENT` в [.filename]#Makefile# соответствующего подкаталога. ==== [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Категория | Описание | Примечания |[.filename]#accessibility# |Порты для помощи пользователям с ограниченными возможностями. | |[.filename]#afterstep*# |Порты, поддерживающие менеджер окон http://www.afterstep.org[AfterStep]. | |[.filename]#arabic# |Поддержка арабского языка. | |[.filename]#archivers# |Инструменты для работы с архивами. | |[.filename]#astro# |Приложения, связанные с астрономией. | |[.filename]#audio# |Поддержка работы со звуком. | |[.filename]#benchmarks# |Утилиты для измерения производительности системы. | |[.filename]#biology# |Программное обеспечение, связанное с биологией. | |[.filename]#cad# |Инструменты Систем Автоматизированного Проектирования. | |[.filename]#chinese# |Поддержка китайского языка. | |[.filename]#comms# |Коммуникационное программное обеспечение. |В основном программы для работы с последовательным портом. |[.filename]#converters# |Утилиты для преобразования символьных форматов. | |[.filename]#databases# |Базы данных. | |[.filename]#deskutils# |То, что было на столе до изобретения компьютеров. | |[.filename]#devel# |Утилиты для разработки программного обеспечения. |Не помещайте сюда библиотеки просто потому, что это библиотеки-если они подпадают под какую-то другую категорию, то их быть здесь не должно. |[.filename]#dns# |Программное обеспечение для работы DNS. | |[.filename]#docs*# |Мета-порты для документации FreeBSD. | |[.filename]#editors# |Редакторы общего назначения. |Специализированные редакторы относят к разделу для соответствующих инструментов (например, редактор математических формул попадает в категорию [.filename]#math#). |[.filename]#elisp*# |Порты для Emacs lisp. | |[.filename]#emulators# |Эмуляторы других операционных систем. |Эмуляторы терминалов сюда _не_ относятся-те, которые разработаны для X, должны быть в категории [.filename]#x11#, а текстовые в [.filename]#comms# или [.filename]#misc#, в зависимости от конкретного их предназначения. |[.filename]#finance# |Приложения для работы с деньгами, финансами и всем, что с этим связано. | |[.filename]#french# |Поддержка французского языка. | |[.filename]#ftp# |Клиенты и серверы FTP. |Если ваш порт понимает как FTP, так и HTTP, поместите его в категорию [.filename]#ftp# и укажите вторичную категорию [.filename]#www#. |[.filename]#games# |Игры. | |[.filename]#geography*# |Программное обеспечение, связанное с географией. | |[.filename]#german# |Поддержка немецкого языка. | |[.filename]#gnome*# |Порты Проекта http://www.gnome.org[GNOME]. | |[.filename]#gnustep*# |Программное обеспечение для окружения рабочего стола GNUstep. | |[.filename]#graphics# |Графические утилиты. | |[.filename]#hamradio*# |Программное обеспечение для любительского радио | |[.filename]#haskell*# |Программное обеспечение, связанное с языком Haskell. | |[.filename]#hebrew# |Поддержка иврита. | |[.filename]#hungarian# |Поддержка венгерского языка. | |[.filename]#ipv6*# |Программное обеспечение, связанное с IPv6. | |[.filename]#irc# |Утилиты для Internet Relay Chat. | |[.filename]#japanese# |Поддержка японского языка. | |[.filename]#java# |Программное обеспечение, связанное с языком Java(TM). |Категория [.filename]#java# ни в коем случае не должна быть единственной для порта. Оставьте для портов, непосредственно имеющих отношение к языку Java, портерам также рекомендуется не использовать [.filename]#java# как основную категорию порта. |[.filename]#kde*# |Порты проекта http://www.kde.org[KDE]. | |[.filename]#kld*# |Загружаемые модули ядра. | |[.filename]#korean# |Поддержка корейского языка. | |[.filename]#lang# |Языки программирования. | |[.filename]#linux*# |Linux приложения и утилиты. | |[.filename]#lisp*# |Программное обеспечение, связанное с языком Lisp. | |[.filename]#mail# |Программы для работы с почтой. | |[.filename]#math# |Программное обеспечение для численных вычислений и другие утилиты, связанные с математикой. | |[.filename]#mbone*# |Приложения для MBone. | |[.filename]#misc# |Различные утилиты |В общем, то, что не попадает в другие категории. Если это возможно, попробуйте найти более подходящую, чем `misc`, категорию для вашего порта, так как здесь порты теряются. |[.filename]#multimedia# |Программное обеспечение для работы с мультимедиа. | |[.filename]#net# |Различное сетевое программное обеспечение. | |[.filename]#net-im# |Программы мгновенного обмена сообщениями. | |[.filename]#net-mgmt# |Программное обеспечение для сетевого управления. | |[.filename]#net-p2p# |Приложения для пиринговых сетей. | |[.filename]#news# |Программное обеспечение для работы с конференциями USENET. | |[.filename]#palm# |Программная поддержка http://www.palm.com/[Palm(TM)]. | |[.filename]#parallel*# |Приложения, связанные с параллельными вычислениями. | |[.filename]#pear*# |Порты, относящиеся к технологии Pear PHP. | |[.filename]#perl5*# |Порты, которым для работы требуется Perl версии 5. | |[.filename]#plan9*# |Различные программы из http://www.cs.bell-labs.com/plan9dist/[Plan9]. | |[.filename]#polish# |Поддержка польского языка. | |[.filename]#ports-mgmt# |Порты для управления, установки и разработки портов и пакетов FreeBSD. | |[.filename]#portuguese# |Поддержка португальского языка. | |[.filename]#print# |Программное обеспечение для печати. |Инструменты для вёрстки (просмотрщики и тому подобное) тоже относятся сюда. |[.filename]#python*# |Программное обеспечение, связанное с языком http://www.python.org/[Python]. | |[.filename]#ruby*# |Программное обеспечение, связанное с языком http://www.ruby-lang.org/[Ruby]. | |[.filename]#rubygems*# |Порты для пакетов http://www.rubygems.org/[RubyGems]. | |[.filename]#russian# |Поддержка русского языка. | |[.filename]#scheme*# |Программное обеспечение, связанное с языком Scheme. | |[.filename]#science# |Научные программы, которые не подпадают под другие категории, скажем, [.filename]#astro#, [.filename]#biology# или [.filename]#math#. | |[.filename]#security# |Программы, обеспечивающие безопасность системы. | |[.filename]#shells# |Различные командные процессоры. | |[.filename]#sysutils# |Системные утилиты. | |[.filename]#spanish*# |Поддержка испанского языка. | |[.filename]#tcl*# |Порты, для работы которых нужен Tcl. | |[.filename]#textproc# |Утилиты для обработки текстов. |Инструменты для вёрстки помещаются в категорию [.filename]#print#, а не сюда. |[.filename]#tk*# |Порты, для работы которых нужен Tk. | |[.filename]#ukrainian# |Поддержка украинского языка. | |[.filename]#vietnamese# |Поддержка вьетнамского языка. | |[.filename]#windowmaker*# |Порты для поддержки менеджера окон WindowMaker. | |[.filename]#www# |Программное обеспечение, связанное со всемирной паутиной. |Поддержка языка HTML относится сюда же. |[.filename]#x11# |X Window System и иже с ними. |Эта категория предназначена только для программного обеспечения, которое поддерживает саму оконную систему. Не помещайте сюда обычные приложения для X: большинство из них должны быть перенесены в другие категории [.filename]#x11-*# (смотрите ниже). |[.filename]#x11-clocks# |Часы для X11. | |[.filename]#x11-drivers# |Драйверы X11. | |[.filename]#x11-fm# |Менеджеры файлов для X11. | |[.filename]#x11-fonts# |Шрифты для X11 и утилиты для работы с ними. | |[.filename]#x11-servers# |Серверы для X11. | |[.filename]#x11-themes# |Темы для X11. | |[.filename]#x11-toolkits# |Пакеты разработчика для X11. | |[.filename]#x11-wm# |Оконные менеджеры для X11. | |[.filename]#xfce*# |Порты, связанные с окружением рабочего стола http://www.xfce.org/[Xfce]. | |[.filename]#zope*# |Поддержка http://www.zope.org/[Zope]. | |=== [[choosing-categories]] === Выбор правильной категории Так как многие категории перекрываются, вам часто необходимо будет выбирать, какая их них должна быть основной для вашего порта. Есть несколько правил, по которым можно решить этот вопрос. Вот список приоритетов, в уменьшающейся степени предпочтения: * Первая категория должна быть физической категорий (смотрите <>). Это необходимо для создания пакетов. После этого виртуальные и физические категории могут смешиваться. * Сначала всегда идут категории, специфичные для языков. Например, если ваш порт устанавливает японские шрифты для X11, то строчка `CATEGORIES` должна иметь вид [.filename]#japanese x11-fonts#. * Более конкретные категории идут первыми перед более общими. В частности, редактор HTML должен быть описан как [.filename]#www editors#, а не наоборот. Кроме того, вы не должны указывать категорию [.filename]#net#, если порт относится к одной из категорий [.filename]#irc#, [.filename]#mail#, [.filename]#news#, [.filename]#security# или [.filename]#www#, так как [.filename]#net# включается автоматически. * [.filename]#x11# используется как вторичная категория только в случае, если в качестве основной категории указан естественный язык. В частности, вам не нужно указывать [.filename]#x11# в качестве категории для приложений X. * Режимы для редактора Emacs должны помещаться в ту же категорию, что и приложение, которое поддерживается этим режимом, а не в [.filename]#editors#. Например, режим Emacs для редактирования исходного кода некоторого языка программирования должен быть помещен в категорию [.filename]#lang#. * Порты, устанавливающие загружаемые модули ядра, должны содержать виртуальную категорию [.filename]#kld# в строке `CATEGORIES`. Это одно из действий, выполняемых автоматически с добавлением `kmod` в строке `USES`. * [.filename]#misc# не должна указываться вместе с любой другой невиртуальной категорией. Если вы указываете `misc` вместе с чем-то ещё в строке `CATEGORIES`, это значит, что вы можете спокойно удалить `misc` и просто поместить порт в этот другой подкаталог! * Если ваш порт решительным образом не подпадает ни под какую категорию, поместите его в [.filename]#misc#. Если вы не уверены в правильности выбора категории, пожалуйста, отметьте это в вашем сообщении man:send-pr[1], чтобы мы могли обсудить это до того, как включить порт в Коллекцию. Если вы являетесь коммиттером, пошлите замечание на адрес {freebsd-ports}, чтобы мы могли обсудить это. Зачастую новые порты помещаются не в ту категорию только для того, чтобы их оттуда сразу же удалили. Это приводит к излишнему и ненужному росту основного хранилища исходных текстов. [[proposing-categories]] === Предложение новой категории Поскольку со временем Коллекция Портов увеличилась, то в связи с этим были добавлены различные новые категории. Новые категории могут быть или _виртуальными_ категориями-которые не имеют соответствующего подкаталога в дереве портов-или _физическими_ категориями-у которых он есть. Следующий текст содержит обсуждение вопросов, возникающих при создании новой физической категории, чтобы вы могли понимать их, когда предложите новую категорию. В соответствие с существующей практикой мы избегаем создания новой физической категории, пока достаточно большое число портов логически ей не принадлежит или же порты, которые могли бы ей принадлежать, не являются логически обособленной группой, представляющей для всех ограниченный интерес (в частности, категории, относящиеся к естественным языкам); предпочтительно выполнение обоих условий. Основной причиной для этого является то, что такое изменение создает extref:{committers-guide}[изрядное количество работы, ports] и для коммиттеров, и для всех тех пользователей, которые отслеживают изменения в Коллекции Портов. В дополнение, предложенная категория создает естественное разногласие. (Пожалуй, потому что не существует четкого соглашения, является ли категория "слишком большой", или должны ли категории предоставлять себя для просмотра (и, таким образом, какое количество категорий было бы идеальным значением), и так далее.) Процедура: [.procedure] ==== . Предложите новую категорию на {freebsd-ports}. Вам следует включить для новой категории детальное обоснование, в том числе почему вы считаете, что существующие категории не являются достаточными, и список существующих портов, предложенных для перемещения. (Если есть новые порты, ожидающие в GNATS и попадающие в эту категорию, то укажите их тоже.) Если вы являетесь сопровождающим и/или отправителем, то укажите это соответственно, так как это может помочь вам в вашем деле. . Принимайте участие в обсуждении. . Если кажется, что для вашей идеи появилась поддержка, отправьте PR, который будет включать обоснование и список существующих портов, которые надо переместить. В идеале этот PR должен также включать патчи для следующего: ** [.filename]#Makefile#'ы для новых портов в результате репозиторного копирования ** [.filename]#Makefile# для категорий старых портов ** [.filename]#Makefile#'ы для портов, зависящих от старых портов ** (в дополнение, вы можете включить другие файлы, требующие изменений, согласно процедуре из Руководства Коммиттера.) . Поскольку это затрагивает инфраструктуру портов и охватывает не только выполнение репозиторного копирования, но также, возможно, и выполнение регрессивных тестов на кластере построения, то PR должна назначать себе {portmgr}. . Если этот PR одобрен, то коммиттеру нужно продолжить остальную часть процедуры, которая extref:{committers-guide}[изложена в Руководстве Коммиттера, ports]. ==== Предложение новой виртуальной категории должно быть схожим с вышеизложенным, но при этом затрагивать намного меньше, поскольку ни один из портов не будет перемещен в действительности. В этом случае единственными патчами, включенными в PR, будут те, что добавляют новую категорию в `CATEGORIES` каждого из затрагиваемых портов. [[proposing-reorg]] === Предложение реорганизации всех категорий Время от времени кто-нибудь предлагает произвести реорганизацию категорий либо до двухуровневой, либо другого типа на основе ключевых слов. На данный момент из этих предложений ничего не получилось, потому что, хотя они просты в реализации, но предполагаемая переделка всей коллекции портов по меньшей мере приводит в уныние. Пожалуйста, прочтите историю этих предложений в архивах рассылок перед тем, как присылать свои соображения; более того, вы должны быть готовы представить работающий прототип. [[makefile-distfiles]] == Дистрибутивные файлы Во второй части [.filename]#Makefile# задаётся, какие файлы и откуда должны быть сгружены для того, чтобы построить порт. === `DISTVERSION/DISTNAME` В переменной `DISTNAME` указывается имя порта так, как назвали его создатели программного обеспечения. Значение `DISTNAME` по умолчанию совпадает с `${PORTNAME}-${PORTVERSION}`, так что переопределяете её значение только в случае необходимости. `DISTNAME` используется только в двух местах. Во-первых, список дистрибутивных файлов (`DISTFILES`) по умолчанию состоит из `${DISTNAME}${EXTRACT_SUFX}`. И во-вторых, предполагается, что дистрибутивный файл будет распакован в подкаталог с именем `WRKSRC`, значение которого по умолчанию есть не что иное, как [.filename]#work/${DISTNAME}#. Названия некоторых дистрибутивов, которые не укладываются в `${PORTNAME}-${PORTVERSION}`-схему, могут быть автоматически обработаны посредством установки переменной `DISTVERSION`. `PORTVERSION` и `DISTNAME` будут унаследованы автоматически, но конечно же могут быть переопределены. Следующая таблица демонстрирует некоторые примеры: [.informaltable] [cols="1,1", frame="none", options="header"] |=== | DISTVERSION | PORTVERSION |0.7.1d |0.7.1.d |10Alpha3 |10.a3 |3Beta7-pre2 |3.b7.p2 |8:f_17 |8f.17 |=== [NOTE] ==== Значения переменных `PKGNAMEPREFIX` и `PKGNAMESUFFIX` не влияют на значение `DISTNAME`. Заметьте также, что если значение `WRKSRC` равно [.filename]#work/${PORTNAME}-${PORTVERSION}#, и в случае, когда оригинальный архив называется по имени, отличном от `${PORTNAME}-${PORTVERSION}${EXTRACT_SUFX}`, скорее всего, вы должны оставить `DISTNAME` как есть- лучше переопределить `DISTFILES`, чем задавать значения как `DISTNAME`, так и `WRKSRC` (и, возможно, ещё и `EXTRACT_SUFX`). ==== === `MASTER_SITES` Содержит часть с каталогом FTP/HTTP-URL, которая указывает на оригинальный архив на сервере `MASTER_SITES`. Не забудьте лидирующий слэш ([.filename]#/#)! Макрос команды `make` будет пытаться воспользоваться этой переменной для получения дистрибутивного файла с помощью программы `FETCH`, если он не будет найден в системе. Рекомендуется помещать в список много сайтов, предпочтительно с разных континентов. Это поможет при наличии проблем с мировой сетью. Мы даже планируем добавить поддержку автоматического определения ближайшего сайта и сгрузки файлов оттуда; наличие нескольких сайтов будет способствовать этому начинанию. Если оригинальный архив находится на одном из таких популярных серверов, как SourceForge, GNU или Perl CPAN, то указывайте эти сайты в простой форме при помощи `MASTER_SITE_*` (к примеру, `MASTER_SITE_SOURCEFORGE`, `MASTER_SITE_GNU` или `MASTER_SITE_PERL_CPAN`. Просто укажите в переменной `MASTER_SITES` одно из этих значений, а в переменной `MASTER_SITE_SUBDIR` задайте путь к архиву. Вот пример: [.programlisting] .... MASTER_SITES= ${MASTER_SITE_GNU} MASTER_SITE_SUBDIR= make .... Или можно использовать сокращенный формат: [.programlisting] .... MASTER_SITES= GNU/make .... Эти переменные определены в файле [.filename]#/usr/ports/Mk/bsd.sites.mk#. Всё время добавляются новые записи, так что обращайтесь к последней версии этого файла перед тем, как послать нам свой порт. Для популярных сайтов существует несколько _магических_ макросов с заранее известной структурой каталогов. Используйте для них сокращения, и система попытается угадать для вас правильный подкаталог. [.programlisting] .... MASTER_SITES= SF .... Если попытка угадать не удалась, то это может быть переписано следующим образом. [.programlisting] .... MASTER_SITES= SF/stardict/WyabdcRealPeopleTTS/${PORTVERSION} .... Что также можно записать в таком виде: [.programlisting] .... MASTER_SITES= SF MASTER_SITE_SUBDIR= stardict/WyabdcRealPeopleTTS/${PORTVERSION} .... .Популярные магические макросы для `MASTER_SITES` [cols="1,1", frame="none", options="header"] |=== | Макрос | Предполагаемый подкаталог |`APACHE_JAKARTA` |`/dist/jakarta/${PORTNAME:S,-,,/,}/source` |`BERLIOS` |`/${PORTNAME:L}` |`CHEESESHOP` |`/packages/source/source/${DISTNAME:C/(.).\*/\1/}/${DISTNAME:C/(.*)-[0-9].*/\1/}` |`DEBIAN` |`/debian/pool/main/${PORTNAME:C/^((lib)?.).*$/\1/}/${PORTNAME}` |`GCC` |`/pub/gcc/releases/${DISTNAME}` |`GNOME` |`/pub/GNOME/sources/${PORTNAME}/${PORTVERSION:C/^([0-9]+\.[0-9]+).*/\1/}` |`GNU` |`/gnu/${PORTNAME}` |`MOZDEV` |`/pub/mozdev/${PORTNAME:L}` |`PERL_CPAN` |`/pub/CPAN/modules/by-module/${PORTNAME:C/-.*//}` |`PYTHON` |`/ftp/python/${PYTHON_PORTVERSION:C/rc[0-9]//}` |`RUBYFORGE` |`/${PORTNAME:L}` |`SAVANNAH` |`/${PORTNAME:L}` |`SF` |`/project/${PORTNAME:L}/${PORTNAME:L}/${PORTVERSION}` |=== === `EXTRACT_SUFX` Если у вас имеется один дистрибутивный файл, и в его имени используется странное окончание для указания типа сжатия, задайте переменную `EXTRACT_SUFX`. К примеру, если дистрибутивный файл носит имя [.filename]#foo.tgz#, а не более привычное [.filename]#foo.tar.gz#, вы должны написать: [.programlisting] .... DISTNAME= foo EXTRACT_SUFX= .tgz .... Переменные `USE_BZIP2`, `USE_XZ` и `USE_ZIP` при необходимости автоматически устанавливают значение `EXTRACT_SUFX` в `.tar.bz2`, `.tar.xz` или `.zip`. Если ни одна из этих переменных не задана, то значение `EXTRACT_SUFX` по умолчанию устанавливается в `.tar.gz`. [NOTE] ==== Вам не нужно задавать значения `EXTRACT_SUFX` и `DISTFILES` одновременно. ==== === `DISTFILES` Иногда имена сгружаемых файлов не соответствуют имени порта. К примеру, файл может называться [.filename]#source.tar.gz# или подобным образом. В других случаях исходный код приложения может располагаться в нескольких отличающихся архивах, и все они должны быть сгружены. Если это ваш случай, то задайте в переменной `DISTFILES` список разделённых пробелами имён файлов, которые нужно сгрузить. [.programlisting] .... DISTFILES= source1.tar.gz source2.tar.gz .... Если переменная `DISTFILES` не задана явно, то её значением по умолчанию будет `${DISTNAME}${EXTRACT_SUFX}`. === `EXTRACT_ONLY` Если только некоторые из `DISTFILES` должны быть распакованы-к примеру, часть из них является исходным кодом, а другие представляют собой неупакованную документацию-перечислите имена файлов, которые должны быть распакованы, в `EXTRACT_ONLY`. [.programlisting] .... DISTFILES= source.tar.gz manual.html EXTRACT_ONLY= source.tar.gz .... Если _ни один_ из `DISTFILES` не должен распаковываться, то установите пустое значение переменной `EXTRACT_ONLY`. [.programlisting] .... EXTRACT_ONLY= .... [[porting-patchfiles]] === `PATCHFILES` Если вашему порту требуются некоторых дополнительные патчи, которые доступны по FTP или HTTP, задайте имена этих файлов в переменной `PATCHFILES`, а в переменной `PATCH_SITES` укажите URL того каталога, в котором они содержатся (формат такой же, как для `MASTER_SITES`). Если патч не относится к самому верху дерева исходных текстов (то есть `WRKSRC`), потому что он содержит некоторые дополнительные пути, установите соответственно значение переменной `PATCH_DIST_STRIP`. В частности, если все имена путей в патче имеют дополнительный путь `foozolix-1.0/` перед именем файла, то задайте `PATCH_DIST_STRIP=-p1`. Не волнуйтесь, если патчи упакованы; они будут распакованы автоматически, если имена файлов оканчиваются на [.filename]#.gz# или [.filename]#.Z#. Если патч распространяется вместе с какими-то другими файлами, такими, как документация, в виде tar-архива `gzip`, вы не можете просто использовать `PATCHFILES`. Если это ваш случай, добавьте имя и местоположение архива с патчем к `DISTFILES` и `MASTER_SITES`. Затем воспользуйтесь переменной `EXTRA_PATCHES` для указания этих файлов, и [.filename]#bsd.port.mk# автоматически применит эти патчи. В частности, _не копируйте_ файлы с патчами в каталог `PATCHDIR`-этот каталог может быть недоступным для записи. [NOTE] ==== Архив будет распакован вне исходного кода, как обычно, и к тому же его не нужно явно распаковывать, если это обычный архив `gzip` или `compress`. Если вы сделаете последнее, приложите дополнительные усилия для того, чтобы не перезаписать что-либо, уже существующее в этом каталоге. Также не забудьте добавить команду для удаления скопированного патча в цели `pre-clean`. ==== [[porting-master-sites-n]] === Несколько дистрибутивных файлов или патчей с различных серверов и подкаталогов (`MASTER_SITES:n`) (Этот раздел можно считать немного "повышенной трудности"; те, кто впервые знакомятся с этим текстом, могут пропустить этот раздел). В этом разделе находится информация о механизме сгрузки, известном как `MASTER_SITES:n` и `MASTER_SITES_NN`. Далее мы будем называть этот механизм `MASTER_SITES:n`. Сначала немного общей информации. В OpenBSD имеется полезная возможность, используемая в переменных `DISTFILES` и `PATCHFILES`, которая позволяет закреплять после имен файлов и патчей идентификаторы типа `:n`. Здесь `n` может быть из диапазона `[0-9]` и обозначать закреплённую группу. К примеру: [.programlisting] .... DISTFILES= alpha:0 beta:1 .... В OpenBSD дистрибутивный файл [.filename]#alpha# будет связан с переменной `MASTER_SITES0`, но не с нашей общей переменной `MASTER_SITES`, а файл [.filename]#beta# с переменной `MASTER_SITES1`. Этот очень интересная возможность, которая может уменьшить этот бесконечный поиск работающего сайта для сгрузки. Просто представьте себе 2 файла в `DISTFILES` и 20 сайтов в `MASTER_SITES`; сайты очень медленные, причём [.filename]#beta# находится на всех сайтах из `MASTER_SITES`, а [.filename]#alpha# может быть найден только на 20-м сайте. Будет неправильно проверять их все, если создатель знает об этом, не правда ли? Неподходящее начало для таких прекрасных выходных! Теперь, когда вы получили общее представление, просто представьте ещё большее количество `DISTFILES` и `MASTER_SITES`. Конечно, наш "магистр доступности дистрибутивов" представляет масштабы нагрузки на сеть, которую это даёт. В последующих разделах информация будет даваться вместе с реализацией этой идеи во FreeBSD. Мы несколько улучшили концепцию OpenBSD. ==== Упрощённая информация В этом разделе рассказывается, как быстро подготовить точную сгрузку нескольких дистрибутивных файлов и патчей с разных сайтов и каталогов. Мы описываем здесь случай упрощённого использования `MASTER_SITES:n`. Для большинства сценариев этого будет достаточно. Однако, если вам нужна дополнительная информация, обратитесь к следующему разделу. Некоторые приложения состоят из многих дистрибутивных файлов, которые должны быть сгружены с нескольких различных сайтов. К примеру, Ghostscript состоит из основной программы и большого числа файлов драйверов, которые используются в зависимости от принтера пользователя. Некоторые из этих файлов драйверов поставляются с основной программой, но при этом многие другие должны быть сгружены с множества различных сайтов. Чтобы это поддерживать, за каждой записью в `DISTFILES` может следовать символ двоеточия и "имя метки". За каждым сайтом, перечисленным в `MASTER_SITES`, тоже следует двоеточие и метка, которая указывает, какие файлы дистрибутива должны быть сгружены с этого сайта. Например, рассмотрим приложение, исходный код которого разделён на две части, [.filename]#source1.tar.gz# и [.filename]#source2.tar.gz#, которые должны быть сгружены с двух различных источников. Файл [.filename]#Makefile# порта будет содержать строчки типа <>. [[ports-master-sites-n-example-simple-use-one-file-per-site]] .Упрощённое использование `MASTER_SITES:n` с 1 файлом на каждом сайте [example] ==== [.programlisting] .... MASTER_SITES= ftp://ftp.example1.com/:source1 \ ftp://ftp.example2.com/:source2 DISTFILES= source1.tar.gz:source1 \ source2.tar.gz:source2 .... ==== Несколько дистрибутивных файлов могут иметь одну и ту же метку. Продолжая предыдущий пример, положим, что имеется и третий дистрибутивный файл, [.filename]#source3.tar.gz#, который должен быть сгружен с `ftp.example2.com`. Тогда файл [.filename]#Makefile# будет написан как <>. [[ports-master-sites-n-example-simple-use-more-than-one-file-per-site]] .Упрощённое использование `MASTER_SITES:n` с более чем 1 файлом на каждом сервере [example] ==== [.programlisting] .... MASTER_SITES= ftp://ftp.example1.com/:source1 \ ftp://ftp.example2.com/:source2 DISTFILES= source1.tar.gz:source1 \ source2.tar.gz:source2 \ source3.tar.gz:source2 .... ==== ==== Подробная информация Прекрасно, но пример из предыдущего раздела не показал вам всё, что вам нужно? В этом разделе мы подробно опишем, как работает механизм `MASTER_SITES:n` точной сгрузки и как вы можете изменить ваши порты, чтобы это использовать. . За элементами могут следовать символы `:n`, где _n_ это `[^:,]+`, то есть _n_ может теоретически быть любой алфавитно-цифровой строкой, но пока мы будем ограничивать их `[a-zA-Z_][0-9a-zA-Z_]+`. + Более того, совпадение строк чувствительно к регистру; другими словами, `n` отличается от `N`. + Однако следующие слова не могут использоваться для этих нужд, так как они имеют особое значение: `default`, `all` и `ALL` (они используются для своих нужд в <>). Кроме того, `DEFAULT` является специальным ключевым словом (посмотрите <>). . Элементы, за которыми следуют `:n`, принадлежат группе `n`, `:m` относится к группе `m` и так далее. [[porting-master-sites-n-DEFAULT-group]] . Элементы без таких суффиксов не относятся ни к какой группе, то есть они принадлежат к особой группе `DEFAULT`. Если вы укажете суффиксом любого элемента `DEFAULT`, вы просто выполните излишнюю работу, если только вы не хотите отнесения элемента как к группе `DEFAULT`, так и какой-то другой в одно и то же время (посмотрите на пункт <>). + Следующие примеры равнозначны, но первый более предпочтителен: + [.programlisting] .... MASTER_SITES= alpha .... + [.programlisting] .... MASTER_SITES= alpha:DEFAULT .... . Группы не являются эксклюзивными, элемент может принадлежать к нескольким отличающимся группам одновременно, а группа может либо иметь несколько различных элементов, либо не иметь их вовсе. Повторяющиеся элементы в одной и той же группе будут являться просто повторяющимися элементами. [[porting-master-sites-n-comma-operator]] . Если в хотите, чтобы элемент принадлежал к нескольким группам одновременно, вы можете использовать запятую (`,`). + Вместо того, чтобы повторять их несколько раз, каждый раз с разным постфиксом, мы можем перечислить несколько групп за раз в одном постфиксе. Например, `:m,n,o` определяет элемент, принадлежащий группам `m`, `n` и `o`. + Все следующие примеры имеют один смысл, но последний является предпочтительным: + [.programlisting] .... MASTER_SITES= alpha alpha:SOME_SITE .... + [.programlisting] .... MASTER_SITES= alpha:DEFAULT alpha:SOME_SITE .... + [.programlisting] .... MASTER_SITES= alpha:SOME_SITE,DEFAULT .... + [.programlisting] .... MASTER_SITES= alpha:DEFAULT,SOME_SITE .... . Все серверы внутри определённой группы сортируются в соответствии с `MASTER_SORT_AWK`. Все группы в `MASTER_SITES` и `PATCH_SITES` тоже сортируются. [[porting-master-sites-n-group-semantics]] . Семантика групп может использоваться в любой из следующих переменных `MASTER_SITES`, `PATCH_SITES`, `MASTER_SITE_SUBDIR`, `PATCH_SITE_SUBDIR`, `DISTFILES` и `PATCHFILES` в соответствии со следующим синтаксисом: .. Все элементы `MASTER_SITES`, `PATCH_SITES`, `MASTER_SITE_SUBDIR` и `PATCH_SITE_SUBDIR` должны заканчиваться символом прямого слэша `/`. Если какие-то элементы принадлежат каким-то группам, постфикс группы `:n` должен следовать сразу после завершающего символа `/`. Механизм `MASTER_SITES:n` опирается на наличие завершающего символа `/` во избежание совпадающих элементов, где `:n` является корректной частью элемента с вхождениями, где `:n` обозначает группу `n`. Для целей совместимости, так как завершающий символ `/` ранее не требовался в элементах `MASTER_SITE_SUBDIR` и `PATCH_SITE_SUBDIR`, если символ, сразу предшествующий постфиксу, не является символом `/`, то `:n` будет считаться корректной частью элемента, а не постфиксом группы, даже если за элементом следует `:n`. Посмотрите <> и <>. + [[ports-master-sites-n-example-detailed-use-master-site-subdir]] .Подробное использование `MASTER_SITES:n` в `MASTER_SITE_SUBDIR` [example] ==== [.programlisting] .... MASTER_SITE_SUBDIR= old:n new/:NEW .... *** Каталоги внутри группы `DEFAULT` -> old:n *** Каталоги внутри группы `NEW` -> new ==== + [[ports-master-sites-n-example-detailed-use-complete-example-master-sites]] .Подробное использование `MASTER_SITES:n` с запятыми, несколькими файлами, несколькими серверами и несколькими подкаталогами [example] ==== [.programlisting] .... MASTER_SITES= http://site1/%SUBDIR%/ http://site2/:DEFAULT \ http://site3/:group3 http://site4/:group4 \ http://site5/:group5 http://site6/:group6 \ http://site7/:DEFAULT,group6 \ http://site8/%SUBDIR%/:group6,group7 \ http://site9/:group8 DISTFILES= file1 file2:DEFAULT file3:group3 \ file4:group4,group5,group6 file5:grouping \ file6:group7 MASTER_SITE_SUBDIR= directory-trial:1 directory-n/:groupn \ directory-one/:group6,DEFAULT \ directory .... Предыдущий пример приводит к следующей точной сгрузке. Серверы перечислены в точном порядке их использования. *** [.filename]#file1# будет сгружаться с **** `MASTER_SITE_OVERRIDE` **** http://site1/directory-trial:1/ **** http://site1/directory-one/ **** http://site1/directory/ **** http://site2/ **** http://site7/ **** `MASTER_SITE_BACKUP` *** [.filename]#file2# будет сгружаться точно также, как [.filename]#file1#, так как они оба относятся к одной и той же группе **** `MASTER_SITE_OVERRIDE` **** http://site1/directory-trial:1/ **** http://site1/directory-one/ **** http://site1/directory/ **** http://site2/ **** http://site7/ **** `MASTER_SITE_BACKUP` *** [.filename]#file3# будет сгружен с **** `MASTER_SITE_OVERRIDE` **** http://site3/ **** `MASTER_SITE_BACKUP` *** [.filename]#file4# будет сгружаться с **** `MASTER_SITE_OVERRIDE` **** http://site4/ **** http://site5/ **** http://site6/ **** http://site7/ **** http://site8/directory-one/ **** `MASTER_SITE_BACKUP` *** [.filename]#file5# будет сгружен с **** `MASTER_SITE_OVERRIDE` **** `MASTER_SITE_BACKUP` *** [.filename]#file6# будет сгружаться с **** `MASTER_SITE_OVERRIDE` **** http://site8/ **** `MASTER_SITE_BACKUP` ==== . Как мне группировать одну из специальных переменных из [.filename]#bsd.sites.mk#, например, `MASTER_SITE_SOURCEFORGE`? + Посмотрите <>. + [[ports-master-sites-n-example-detailed-use-master-site-sourceforge]] .Подробное использование `MASTER_SITES:n` с `MASTER_SITE_SOURCEFORGE` [example] ==== [.programlisting] .... MASTER_SITES= http://site1/ ${MASTER_SITE_SOURCEFORGE:S/$/:sourceforge,TEST/} DISTFILES= something.tar.gz:sourceforge .... ==== + [.filename]#something.tar.gz# будет сгружаться со всех сайтов из `MASTER_SITE_SOURCEFORGE`. . Как мне использовать это с переменными `PATCH*`? + Все примеры выполнялись с переменными `MASTER*`, и они работают точно так же и для `PATCH*`, как это можно видеть в <>. + [[ports-master-sites-n-example-detailed-use-patch-sites]] .Упрощённое использование `MASTER_SITES:n` с `PATCH_SITES`. [example] ==== [.programlisting] .... PATCH_SITES= http://site1/ http://site2/:test PATCHFILES= patch1:test .... ==== ==== Что изменится для портов? А что не изменится? [lowerroman] . Все имеющиеся порты остаются без изменений. Код для механизма `MASTER_SITES:n` активируется, если только есть элементы, которые заканчиваются на `:n`, как и элементы в соответствии с вышеописанным синтаксисом, особенно как это показано в пункте <>. [[porting-master-sites-n-what-changes-in-port-targets]] . Цели порт остаются теми же самыми: `checksum`, `makesum`, `patch`, `configure`, `build` и так далее. С обычными исключениями для `do-fetch`, `fetch-list`, `master-sites` и `patch-sites`. ** `do-fetch`: использует новую группировку с постфиксами в `DISTFILES` и `PATCHFILES` с соответствующими элементами групп в `MASTER_SITES` и `PATCH_SITES`, которые используют группы из `MASTER_SITE_SUBDIR` и `PATCH_SITE_SUBDIR`. Посмотрите <>. ** `fetch-list`: работает так же, как старая цель `fetch-list` с тем исключением, что она группирует, как и `do-fetch`. ** `master-sites` и `patch-sites`: (несовместимы со старыми версиями) только возвращают элементы группы `DEFAULT`; на самом деле они выполняют цели `master-sites-default` и `patch-sites-default` соответственно. + -Более того, использование целей `master-sites-all` или `patch-sites-all` предпочтительно для непосредственной проверки `MASTER_SITES` или `PATCH_SITES`. Также работа прямой проверки в последующих версиях не гарантируется. Посмотрите <> для получения более дополнительной информации об этих новых целях. +Более того, использование целей `master-sites-all` или `patch-sites-all` предпочтительно для непосредственной проверки `MASTER_SITES` или `PATCH_SITES`. Также работа прямой проверки в последующих версиях не гарантируется. Посмотрите <> для получения более дополнительной информации об этих новых целях. . Новые цели построения портов .. Имеются цели `master-sites-_n_` и `patch-sites-_n_`, которые будут перечислять элементы соответствующей группы _n_ из `MASTER_SITES` и `PATCH_SITES` соответственно. К примеру, `master-sites-DEFAULT` и `patch-sites-DEFAULT` обе будут возвращать элементы группы `DEFAULT`, `master-sites-test` и `patch-sites-test` группы `test` и так далее. [[porting-master-sites-n-new-port-targets-master-sites-all]] .. Имеются новые цели `master-sites-all` и `patch-sites-all`, которые выполняют работу старых `master-sites` и `patch-sites`. Они возвращают элементы всех групп, как если бы они все принадлежали одной и той же группе с тем, что она перечисляет ровно столько `MASTER_SITE_BACKUP` и `MASTER_SITE_OVERRIDE`, как и группы, определённые в `DISTFILES` или `PATCHFILES`; соответственно для `master-sites-all` и `patch-sites-all`. === `DIST_SUBDIR` Не позволяйте вашему порту засорять [.filename]#/usr/ports/distfiles#. Если вашему порту требуется сгрузить много файлов, или он содержит имя файла, могущее вызвать конфликты с другими портами (например, [.filename]#Makefile#), то укажите в переменной `DIST_SUBDIR` имя порта (должны подойти `${PORTNAME}` или `${PKGNAMEPREFIX}${PORTNAME}`). Это изменит значение переменной `DISTDIR` со значения по умолчанию [.filename]#/usr/ports/distfiles# к значению [.filename]#/usr/ports/distfiles/DIST_SUBDIR#, и в результате всё, что требуется для порта, будет помещено в этот подкаталог. Он заглянет также в подкаталог с тем же именем на основном резервном сервере [.filename]#ftp.FreeBSD.org#. (Явное задание переменной `DISTDIR` в вашем файле `Makefile` этого не сделает, так что, пожалуйста, воспользуйтесь `DIST_SUBDIR`.) [NOTE] ==== Это не коснётся тех сайтов `MASTER_SITES`, которые вы указали в вашем файле [.filename]#Makefile#. ==== === `ALWAYS_KEEP_DISTFILES` Если ваш порт использует двоичные дистрибутивные файлы и обладает лицензией, требующей, чтобы исходный код предоставлялся вместе с пакетами, распространяемыми в двоичной форме, например GPL, то `ALWAYS_KEEP_DISTFILES` даст кластеру построения FreeBSD указание сохранять копию файлов, указанных в `DISTFILES`. Пользователям таких портов эти файлы в основном не нужны, поэтому хорошей идеей является добавление в `DISTFILES` исходных дистрибутивных файлов, только когда определена переменная `PACKAGE_BUILDING`. [[ports-master-sites-n-example-always-keep-distfiles]] .Использование `ALWAYS_KEEP_DISTFILES`. [example] ==== [.programlisting] .... .if defined(PACKAGE_BUILDING) DISTFILES+= foo.tar.gz ALWAYS_KEEP_DISTFILES= yes .endif .... ==== При добавлении дополнительных файлов в `DISTFILES` убедитесь, что вы их также добавляете в [.filename]#distinfo#. Кроме того, дополнительные файлы обычно распаковываются также в `WRKDIR`, что для некоторых портов может вызывать нежелательные подобные эффекты и требовать особую обработку. [[makefile-maintainer]] == `MAINTAINER` Укажите здесь ваш адрес электронной почты. Пожалуйста. _:-)_ Заметьте, что в качестве значения для `MAINTAINER` допустимо использование только одного адреса без поля комментария. Должен использоваться формат `user@hostname.domain`. Пожалуйста, не включайте никакого описательного текста, например, вашего настоящего имени в эту строку-это несколько сбивает с толку [.filename]#bsd.port.mk#. Сопровождающий ответственен за поддержание порта в актуальном состоянии и обеспечение правильной работы порта. За подробным описанием обязанностей сопровождающего порт обращайтесь к главе extref:{contributing}[The challenge for port maintainers, maintain-port]. Перед фиксацией в репозитории изменения в порте будут отправлены сопровождающему для просмотра и одобрения. Если сопровождающий порта не ответил на запрос пользователя об обновлении в течение двух недель (исключая большие праздники), то это можно считать тайм-аутом сопровождающего, и обновление может быть выполнено без явного подтверждения от сопровождающего. Если сопровождающий не отвечает в течение трёх месяцев, то считается, что он отсутствует, и как сопровождающий порта, о котором идёт речь, может быть заменён. Исключениями из этого правила является всё, что сопровождает {portmgr} или {security-officer}. Запрещено делать любые несанкционированные изменения в портах, которые ведут эти группы. Мы оставляем за собой право изменять сообщение сопровождающего для лучшего соответствия существующим политикам и стилю Коллекции Портов без явного одобрения со стороны отправителя. Также, крупные изменения в инфраструктуре могут повлечь изменения в порте без согласия сопровождающего. Такой вид изменений никогда не будет затрагивать функциональность порта. За {portmgr} оставляется право снять или назначить кого-либо сопровождающим по любой причине, а за {security-officer} оставляется право лишать или назначать права на сопровождение порта по соображениям информационной безопасности. [[makefile-comment]] == `COMMENT` Содержит однострочное описание порта. Пожалуйста, соблюдайте следующие правила: . Старайтесь делать строку COMMENT длиной не больше, чем 70 символов, так как эта строка будет использована командой `pkg info` (см. man:pkg-info[8]) для отображения однострочного описания порта; . _Не_ включайте сюда название пакета (или номер версии программного обеспечения); . Комментарий должен начинаться с заглавной буквы и не заканчиваться точкой; . Не начинайте комментарий с неопределённого артикля (A или An); . Имена пишутся с заглавной буквы (например, Apache, JavaScript, Perl); . Для перечислений используйте английскую Оксфордскую запятую (англ. Oxford comma) (например, green, red, and blue); . Используйте программу проверки орфографии. Вот пример: [.programlisting] .... COMMENT= Cat chasing a mouse all over the screen .... В файле [.filename]#Makefile# переменная COMMENT должна следовать сразу за переменной MAINTAINER. [[makefile-portscout]] == `PORTSCOUT` -Portscout являет собой автоматизированное средство проверки доступности дистрибутивных файлов для Коллекции Портов FreeBSD, подробное описание которого предоставляет <>. +Portscout являет собой автоматизированное средство проверки доступности дистрибутивных файлов для Коллекции Портов FreeBSD, подробное описание которого предоставляет crossref:keeping-up[distfile-survey, Portscout: сканер дистрибутивных файлов портов FreeBSD]. Переменная `PORTSCOUT` задаёт специальные условия, ограничивающие работу Portscout - сканера дистрибутивных файлов. Ситуации, при которых следует указывать переменную `PORTSCOUT`: * Когда должны игнорироваться дистрибутивные файлы для конкретных версий или младших ревизий. Например, чтобы исключить из проверок новых версий дистрибутивных файлов версию _8.2_ по причине того, что она является поломанной, добавьте следующее: + [.programlisting] .... PORTSCOUT= ignore:8.2 .... * Когда должны проверяться конкретные версии или старшие и младшие ревизии дистрибутивных файлов. Например, если следует ограничиться проверкой версии _0.6.4_, потому что более новые версии имеют проблемы совместимости с FreeBSD, добавьте: + [.programlisting] .... PORTSCOUT= limit:^0\.6\.4 .... * Когда URL, в которых указаны доступные версии, отличаются от URL их загрузки. Например, чтобы привязать проверку новых версий дистрибутивных файлов к странице загрузки для порта package:databases/pgtune[], добавьте: + [.programlisting] .... PORTSCOUT= site:http://pgfoundry.org/frs/?group_id=1000416 .... [[makefile-depend]] == Зависимости Многие порты зависят от других портов. Это очень удобная замечательная особенность большинства Unix-подобных операционных систем, включая FreeBSD. Множество портов могут использовать общую зависимость совместно, а не включать её в состав каждого порта или пакета, который в ней нуждается. Имеется семь переменных, которые вы можете использовать для обеспечения того, что всё требуемое находится на машине пользователя. Имеется также несколько предопределённых переменных, отражающих зависимости для общих случаев, плюс ещё несколько для управления поведением зависимостей. === `LIB_DEPENDS` Эта переменная указывает, от каких совместно используемых библиотек зависит порт. Это список пар lib:dir, где _lib_ - это имя библиотеки, _dir_ - это каталог, в котором можно ее найти в случае, если ее нет на машине. Например, [.programlisting] .... LIB_DEPENDS= libjpeg.so:${PORTSDIR}/graphics/jpeg .... проверит наличие библиотеки jpeg с любым номером версии и перейдет в подкаталог [.filename]#graphics/jpeg# вашего дерева портов для ее построения и установки, если библиотека отсутствует. Зависимость проверяется дважды, один раз внутри цели `build`, а затем из цели `install`. Кроме того, имя зависимости помещается в пакет, так что `pkg install` (см. man:pkg-install[8]) будет автоматически её устанавливать, если её нет на пользовательской системе. === `RUN_DEPENDS` В этой переменной перечисляются выполнимые файлы или файлы, от которых зависит работа порта. Это список пар вида path:dir:target, где _path_ - это имя программы или файла, а _dir_ - каталог, в котором можно найти порт в случае, если его нет в системе, и _target_ - это цель, которую нужно вызвать в этом каталоге. Если _path_ начинается со слэша (`/`), он воспринимается как файл и его существование проверяется командой `test -e`; в противном случае предполагается, что это выполнимый файл, и для определения того, имеется ли программа в пути поиска, используется команда `which -s`. Например, [.programlisting] .... RUN_DEPENDS= ${LOCALBASE}/news/bin/innd:${PORTSDIR}/news/inn \ xmlcatmgr:${PORTSDIR}/textproc/xmlcatmgr .... проверит существование файла или каталога [.filename]#/usr/local/news/bin/innd#, и если ничего не будет найдено, то построит и установит порт из подкаталога [.filename]#news/inn# дерева портов. Также будет выполнена проверка, присутствует ли в пути поиска исполняемый файл с именем `xmlcatmgr`, и перейдет в подкаталог [.filename]#textproc/xmlcatmgr# вашего дерева портов для его построения и установки, если он не будет найден. [NOTE] ==== В приведенном примере `innd` является выполнимым файлом; если выполнимый файл находится в месте, которое отсутствует в списке путей файлов, то вы должны указать полный путь к файлу. ==== [NOTE] ==== Официальным значением переменной поиска `PATH`, используемым в кластере построения портов является [.programlisting] .... /sbin:/bin:/usr/sbin:/usr/bin:/usr/local/sbin:/usr/local/bin .... ==== Зависимость проверяется внутри цели `install`. Кроме того, имя зависимости помещается в пакет, так что `pkg install` (см. man:pkg-install[8]) будет автоматически его устанавливать, если он не будет найден в пользовательской системе. Часть _target_ может быть опущена, если она совпадает с `DEPENDS_TARGET`. Довольно распространенной является ситуация, когда `RUN_DEPENDS` буквально такая же как `BUILD_DEPENDS`, особенно если переносимое программное обеспечение написано на языке сценариев, или если оно требует такое же окружение для исполнения, как и используемое во время построения. В этом случае, очень заманчивым или довольно естественным является присвоение одного другому: [.programlisting] .... RUN_DEPENDS= ${BUILD_DEPENDS} .... Тем не менее, подобные присвоения могут загрязнять зависимости времени исполнения содержимым, не заданным в `BUILD_DEPENDS` исходного порта. Такое случается из-за ленивого вычисления в man:make[1] присваиваемых переменных. Представьте [.filename]#Makefile# с переменными `USE_*`, которые обрабатываются в [.filename]#ports/Mk/bsd.*.mk# для пополнения первоначальных зависимостей построения. Например, `USES= gmake` добавляет package:devel/gmake[] в `BUILD_DEPENDS`. Для предотвращения загрязнения `RUN_DEPENDS` подобными дополнительными зависимостями проявляйте осторожность с присвоением с раскрытием, т.е. с раскрытием значения перед его присвоением переменной: [.programlisting] .... RUN_DEPENDS:= ${BUILD_DEPENDS} .... === `BUILD_DEPENDS` В этой переменной перечисляются выполнимые или обычные файлы, которые требуются порту для его построения. Как и `RUN_DEPENDS`, это список пар path:dir:target. Например, [.programlisting] .... BUILD_DEPENDS= unzip:${PORTSDIR}/archivers/unzip .... будет проверять наличие выполнимого фала с именем `unzip` и перейдет в подкаталог [.filename]#archivers/unzip# вашего дерева портов для его построения и установки, если последний не будет найден. [NOTE] ==== Под "построением" здесь понимается всё, от распаковки до компиляции. Зависимость проверяется из цели `extract`. Часть _target_ может быть опущена, если она совпадает с `DEPENDS_TARGET`. ==== === `FETCH_DEPENDS` В этой переменной перечисляются выполняемые файлы или просто файлы, которые требуются порту для сгрузки. Как и предыдущие две переменные, это список пар path:dir:target. Например, [.programlisting] .... FETCH_DEPENDS= ncftp2:${PORTSDIR}/net/ncftp2 .... будет проверять наличие выполняемого файла с именем `ncftp2` и перейдет в каталог [.filename]#net/ncftp2# вашего дерева портов для его построения и установки, если тот не будет найден. Зависимость проверяется при выполнении цели `fetch`. Часть _target_ может быть опущена, если она совпадает с `DEPENDS_TARGET`. === `EXTRACT_DEPENDS` В этой переменной указываются программы или файлы, которые требуются для распаковки порта. Как и в предыдущих случаях, это список пар вида path:dir:target. Например, [.programlisting] .... EXTRACT_DEPENDS= unzip:${PORTSDIR}/archivers/unzip .... будет проверять наличие программы с именем `unzip`, и перейдёт в подкаталог [.filename]#archivers/unzip# вашего дерева портов для её построения и установки, если такой программы не будет найдено. Зависимость проверяется внутри цели `extract`. Часть _target_ может быть опущена, если она совпадает с `DEPENDS_TARGET`. [NOTE] ==== Используйте эту переменную, только если распаковка не работает (по умолчанию предполагается использование `gzip`) и это не исправляется при помощи `USE_ZIP` или `USE_BZIP2`, которые описаны в <>. ==== === `PATCH_DEPENDS` Эта переменная указывает на программы или файлы, которые нужны порту для применения патчей. Как и в предыдущих случаях, это список пар вида path:dir:target. Например, [.programlisting] .... PATCH_DEPENDS= ${NONEXISTENT}:${PORTSDIR}/java/jfc:extract .... будет переходить в подкаталог [.filename]#java/jfc# вашего дерева портов для распаковки. Зависимость проверяется внутри цели `patch`. Часть _target_ может быть опущена, если она совпадает с `DEPENDS_TARGET`. [[uses-makefiles]] === `USES` Могут быть добавлены параметры для определения различных характерных особенностей и зависимостей, которыми обладает данный порт. Они указываются путём добавления в [.filename]#Makefile# этой строки: [.programlisting] .... USES= feature[:arguments] .... Для получения полного списка значений смотрите <>. [WARNING] ==== Значение `USES` нельзя присваивать после подключения [.filename]#bsd.port.pre.mk#. ==== [[use-vars]] === `USE_*` Для определения общих зависимостей, совместно используемых многими портами, предназначено несколько переменных. Их использование является необязательным, но помогает упростить избыточность файлов [.filename]#Makefile# порта. Каждый из них оформляется как `USE_*`. Эти переменные можно использовать только в [.filename]#Makefile# порта и [.filename]#ports/Mk/bsd.*.mk#. Они не предназначены для установки пользователями параметров - используйте для этих целей `PORT_OPTIONS`. [NOTE] ==== Установка любых `USE_*` в [.filename]#/etc/make.conf# _всегда_ является ошибочным действием. В частности, установка [.programlisting] .... USE_GCC=X.Y .... (где X.Y соответствует версии) добавит зависимость от gccXY к каждому порту, включая и сам `lang/gccXY`! ==== .Переменные `USE_*` [cols="1,1", frame="none", options="header"] |=== | Переменная | Значение |`USE_BZIP2` |tar-архивы порта упакованы при помощи `bzip2`. |`USE_ZIP` |tar-архивы порта упакованы при помощи `zip`. |`USE_GCC` |Для сборки порта требуется GCC (gcc или {gcc-plus-plus}). Некоторым портам подходит любая версия, для других требуются последние современные версии. Обычно используется со значением `any` (в этом случае используется встроенный GCC в тех версиях FreeBSD, в состав которых он всё ещё входит, или устанавливается порт `lang/gcc`, когда Clang является компилятором C/C++ по умолчанию) или `yes` (всегда используется стабильная современная версия GCC из порта `lang/gcc`). Также в значении переменной можно указать точную версию, например `4.7`. Минимально допустимую версию можно указать как `4.6+`. GCC из основной системы используется в случае, если его версия удовлетворяет запрошенной, иначе собирается подходящая версии компилятора из порта с соответствующей коррекцией переменных `CC` и `CXX`. |=== -Переменные, относящиеся к gmake и сценарию [.filename]#configure#, описаны в <>, а autoconf, automake и libtool описаны в <>. Переменные, связанные с Perl, описаны в <>. Переменные X11 перечислены в <>. <> работает с переменными GNOME и <> с KDE. <> описывает переменные Java, а <> содержит информацию об Apache, PHP и модулях PEAR. Python обсуждается в <>, а Ruby в <>. <> предоставляет переменные, используемые для приложений SDL, и, наконец, <> содержит информацию о приложении Xfce. +Переменные, относящиеся к gmake и сценарию [.filename]#configure#, описаны в crossref:special[building, Механизмы построения], а autoconf, automake и libtool описаны в crossref:special[using-autotools, Использование GNU Autotools]. Переменные, связанные с Perl, описаны в crossref:special[using-perl, Использование Perl]. Переменные X11 перечислены в crossref:special[using-x11, Использование X11]. crossref:special[using-gnome, Использование GNOME] работает с переменными GNOME и crossref:special[using-kde, Использование KDE] с KDE. crossref:special[using-java, Использование Java] описывает переменные Java, а crossref:special[using-php, Веб-приложения, Apache и PHP] содержит информацию об Apache, PHP и модулях PEAR. Python обсуждается в crossref:special[using-python, Использование Python], а Ruby в crossref:special[using-ruby, Использование Ruby]. crossref:special[using-sdl, Использование SDL] предоставляет переменные, используемые для приложений SDL, и, наконец, crossref:special[using-xfce, Использование Xfce] содержит информацию о приложении Xfce. === Минимальная версия зависимости Минимальная версия зависимости может быть указана в любой переменной `*_DEPENDS`, за исключением `LIB_DEPENDS`, с использованием следующего синтаксиса: [.programlisting] .... p5-Spiffy>=0.26:${PORTSDIR}/devel/p5-Spiffy .... Первое поле содержит название зависимого пакета, которое обязано совпадать с записью в базе данные пакетов, знак сравнения и версию пакета. Зависимость удовлетворяется, если на машине установлен p5-Spiffy-0.26 или новее. === Замечания касательно зависимостей Как уже отмечено выше, целью, которая вызывается по умолчанию в случае, когда это требует зависимость, является `DEPENDS_TARGET`. Она по умолчанию есть `install`. Это пользовательская переменная; она нигде не определена в файле [.filename]#Makefile# порта. Если вашему порту требуется особый метод обработки зависимости, воспользуйтесь частью `:target` переменной `*_DEPENDS` вместо того, чтобы переопределять `DEPENDS_TARGET`. Когда вы набираете команду `make clean`, эта операция также выполняется и над зависимостями этого порта. Если вы не хотите, чтобы это случилось, определите переменную `NOCLEANDEPENDS` в вашем окружении. Это может быть особенно нужным, если порт имеет нечто, что занимает много времени на построение, в своём списке зависимостей, например, KDE, GNOME или Mozilla. Чтобы безусловно зависеть от другого порта, укажите переменную `${NONEXISTENT}` в качестве первого поля переменной `BUILD_DEPENDS` или `RUN_DEPENDS`. Пользуйтесь этим, только когда вам нужно иметь исходный код другого порта. Вы можете сэкономить время на компиляции, указав также и цель. Например, [.programlisting] .... BUILD_DEPENDS= ${NONEXISTENT}:${PORTSDIR}/graphics/jpeg:extract .... всегда будет переходить в каталог с портом `jpeg` и распаковывать его. === Зацикленные зависимости фатальны [IMPORTANT] ==== Не помещайте зацикливающиеся зависимости в дерево портов! ==== Технология построения портов не защищена от зацикленных зависимостей. Если вы создадите такую, то у кого-нибудь и где-нибудь установка FreeBSD будет немедленно сломана, а у остальных сломается несколько позже. Это на самом деле очень трудно распознать; если вы сомневаетесь, то перед внесением изменений проверьте, что выполнили следующее: `cd /usr/ports; make index`. Этот процесс может быть достаточно медленным на старых машинах, хотя вы сможете спасти большое количество людей-включая себя-от грядущих бед. === Автоматические зависимости и проблемы, которые они вызывают Зависимости должны быть указаны либо явно, либо с использованием <>. Использование прочих методов, таких как автоматическое обнаружение зависимостей, усложняет индексирование, что вызывает проблемы в управлении портами и пакетами. .Некорректное объявление необязательной зависимости [example] ==== [.programlisting] .... .include .if exists(${LOCALBASE}/bin/foo) LIB_DEPENDS= libbar.so:${PORTSDIR}/foo/bar .endif .... ==== Проблема автоматического добавления зависимостей заключается в том, что файлы и настройки за пределами порта могут произвольно меняться. Пример: после построения индекса устанавливается набор портов. При этом один из них устанавливает проверяемый файл. На этом этапе индекс будет неправильным, потому что установленный порт неожиданно получит новую зависимость. Индекс может быть по прежнему неправильным даже после его перестроения, в случае если другие порты также определят дополнительные зависимости, основываясь на существовании других файлов. .Корректное объявление необязательной зависимости [example] ==== [.programlisting] .... OPTIONS_DEFINE= BAR BAR_DESC= Bar support .include .if ${PORT_OPTIONS:MBAR} LIB_DEPENDS= libbar.so:${PORTSDIR}/foo/bar .endif .... ==== Правильным способом является проверка переменных параметров. Этот способ не приводит к несоответствиям в индексе набора портов, поскольку параметры определены до построения индекса. При этом можно использовать простые скрипты для автоматизации построения, установки и обновления этих портов и соответствующих им пакетов. [[use-want]] === `USE_` и `WANT_` Переменные `USE_` задаются мейнтейнером порта для определения программного обеспечения, от которого этот порт зависит. Порт, для которого нужен Firefox, укажет [.programlisting] .... USE_FIREFOX= yes .... Некоторые переменные `USE_` могут принимать номера версий или другие параметры. Например, порт, который требует Apache 2.2, укажет [.programlisting] .... USE_APACHE= 22 .... В некоторых случаях для большего контроля над зависимостями используются переменные `WANT_`, которые позволяют указывать требования в более точной форме. Например, взгляните на порт package:mail/squirrelmail[]. Этому порту нужны несколько модулей PHP, которые перечислены в переменной `USE_PHP`: [.programlisting] .... USE_PHP= session mhash gettext mbstring pcre openssl xml .... Эти модули доступны в версиях CLI и web, поэтому версия web выбрана с переменной `WANT_`: [.programlisting] .... WANT_PHP_WEB= yes .... Имеющиеся переменные `USE_` и `WANT_` определены в файлах в [.filename]#/usr/ports/Mk#. [[makefile-masterdir]] == `MASTERDIR` Если вашему порту требуется построение довольно различающихся версий пакетов через переменную (задающую, например, разрешение, или размер бумаги), которая принимает различные значения, создайте для каждого пакета отдельный подкаталог, чтобы пользователям было легче определить, каким пакетом воспользоваться, но попробуйте использовать совместно между портами как можно больше файлов. В типичном случае вам потребуются только очень короткие файлы [.filename]#Makefile# во всех каталогах, кроме одного, если вы будете использовать переменные с умом. В отдельных файлах [.filename]#Makefile# вы можете использовать переменную `MASTERDIR` для указания каталога, в котором находятся все остальные файлы. Также используйте переменную как часть <>, чтобы пакеты имели разные имена. Продемонстрируем это на примере. Вот часть файла [.filename]#japanese/xdvi300/Makefile#: [.programlisting] .... PORTNAME= xdvi PORTVERSION= 17 PKGNAMEPREFIX= ja- PKGNAMESUFFIX= ${RESOLUTION} : # default RESOLUTION?= 300 .if ${RESOLUTION} != 118 && ${RESOLUTION} != 240 && \ ${RESOLUTION} != 300 && ${RESOLUTION} != 400 @${ECHO_MSG} "Error: invalid value for RESOLUTION: \"${RESOLUTION}\"" @${ECHO_MSG} "Possible values are: 118, 240, 300 (default) and 400." @${FALSE} .endif .... Порт package:japanese/xdvi300[] содержит также все обычные патчи, файлы для пакета и так далее. Если вы введете здесь команду `make`, она возьмет в качестве разрешения значение по умолчанию (300) и построит порт обычным образом. Для другого разрешения приведем _полный_[.filename]#xdvi118/Makefile#: [.programlisting] .... RESOLUTION= 118 MASTERDIR= ${.CURDIR}/../xdvi300 .include "${MASTERDIR}/Makefile" .... ([.filename]#xdvi240/Makefile# и [.filename]#xdvi400/Makefile# похожи). Задание `MASTERDIR` говорит [.filename]#bsd.port.mk#, что обычный набор подкаталогов типа `FILESDIR` и `SCRIPTDIR` находится в каталоге [.filename]#xdvi300#. Строчка `RESOLUTION=118` переопределят строку `RESOLUTION=300` в файле [.filename]#xdvi300/Makefile# и порт будет построен с разрешением 118. [[makefile-manpages]] == Страницы Справочника Если ваш порт определяет корнем для файлов Справочника каталог, отличный от `PREFIX`, вы можете использовать переменную `MANDIRS`, чтобы указать эти каталоги. Обратите внимание, что файлы страниц справочника следует размещать в [.filename]#pkg-plist# наряду с остальными файлами. `MANDIRS` предназначена для автоматического сжатия страниц справочника, так чтобы имена файлов оканчивались на [.filename]#.gz#. [[makefile-info]] == Файлы в формате info Если в вашем пакете нужна установка файлов GNU info, они должны быть перечислены в переменной `INFO` (без окончания `.info`), по записи на документ. Предполагается, что эти файлы устанавливаются в [.filename]#PREFIX/INFO_PATH#. Вы можете изменить `INFO_PATH`, если ваш пакет использует другое место для размещения. Однако, это не рекомендуется делать. Эти записи всего лишь содержат путь относительно [.filename]#PREFIX/INFO_PATH#. Например, package:lang/gcc34[] устанавливает файлы info в [.filename]#PREFIX/INFO_PATH/gcc34#, и в `INFO` будет что-то вроде этого: [.programlisting] .... INFO= gcc34/cpp gcc34/cppinternals gcc34/g77 ... .... Перед регистрацией пакета соответствующий код установки/удаления будет автоматически добавлен во временный [.filename]#pkg-plist#. [[makefile-options]] == Опции для Makefile Многие приложения могут быть построены в различных конфигурациях и с дополнительной функциональностью. Например, выбор естественного (человеческого) языка, GUI против командной строки или типа используемой базы данных. Пользователи могут нуждаться в различных конфигурациях, отличных от используемой по умолчанию, поэтому в системе портов предусмотрен механизм, позволяющий автору порта управлять сборкой того или иного варианта конфигурации. Правильная поддержка этих необязательных параметров облегчает пользователям жизнь и даёт два или более порта по цене одного. === Knobs ==== `WITH__*_` и `WITHOUT__*_` Эти переменные предназначены для установки системным администратором. Многие из них стандартизованы в файле http://svnweb.FreeBSD.org/ports/head/KNOBS?view=markup[ports/KNOBS]. При создании порта не давайте имя для knob, специфичное для данного приложения. На примере порта Avahi, используйте `WITHOUT_MDNS` вместо `WITHOUT_AVAHI_MDNS`. [NOTE] ==== Не стоит рассчитывать, что `WITH__*_` обязательно имеет соответствующую переменную `WITHOUT__*_`, и наоборот. В общем случае, предполагается значение по умолчанию. ==== [NOTE] ==== Если обратное не указано, то проверяется только факт установки самих переменных, но не их конкретное значение типа `YES` или `NO`. ==== .Основные переменные `WITH__*_` и `WITHOUT__*_` [cols="1,1", frame="none", options="header"] |=== | Переменная | Значение |`WITH_OPENSSL_BASE` |Использовать версию OpenSSL из базовой системы. |`WITH_OPENSSL_PORT` |Устанавливает версию OpenSSL из package:security/openssl[], даже если в базовой системе последняя версия. |=== ==== Наименование KNOBS Портеры должны использовать так называемые knobs для помощи конечным пользователям и для поддержания количества наименований knobs в небольшом количестве. Список популярных названий knobs можно найти в файле http://svnweb.FreeBSD.org/ports/head/KNOBS?view=markup[KNOBS] Названия knobs должны отражать, что это такое и что выполняет. Если у порта имеется библиотечный префикс в `PORTNAME`, то он должен присутствовать в названии knobs. === `OPTIONS` ==== Описание При установке порта переменные `OPTIONS_*` предоставляют пользователю окно диалога с отображением доступных параметров, с записью выбранных параметров в файл [.filename]#/var/db/ports/${UNIQUENAME}/options#. Эти опции повторно используются при следующем построении порта. Когда пользователь запускает `make config` (или запускает впервые `make build`), инфраструктура выполняет проверку существования файла [.filename]#/var/db/ports/${UNIQUENAME}/options#. Если этот файл не существует, то используются значения `OPTIONS_*` и отображается диалоговое окно, в котором эти параметры можно включить или выключить. Затем сохраняется файл опций [.filename]#options#, и выбранные переменные используются при построении порта. Если новая версия порта добавляет новые значения `OPTIONS`, то пользователю будет представлено окно диалога с сохраненными заполненными значениями старых `OPTIONS.` `make showconfig` отображает сохраненную конфигурацию. Для удаления сохраненной конфигурации используйте `make rmconfig`. ==== Синтаксис `OPTIONS_DEFINE` содержит список используемых `OPTIONS`. Они независимы друг от друга и не сгруппированы: [.programlisting] .... OPTIONS_DEFINE= OPT1 OPT2 .... Далее после определения следует описание `OPTIONS` (не является обязательным, но настоятельно рекомендуется): [.programlisting] .... OPT1_DESC= Describe OPT1 OPT2_DESC= Describe OPT2 OPT3_DESC= Describe OPT3 OPT4_DESC= Describe OPT4 OPT5_DESC= Describe OPT5 OPT6_DESC= Describe OPT6 .... [TIP] ==== [.filename]#ports/Mk/bsd.options.desc.mk# содержит описание множества наиболее используемых `OPTIONS`; переопределять их, как правило, не нужно. ==== [TIP] ==== При описании параметров старайтесь представить себя на месте пользователя: "Что это делает?" и "Для чего бы я захотел включить это?" Не делайте простое повторение названия. Например, описание параметра `NLS` как "include NLS support" ("включить поддержку NLS") не поможет пользователю, который уже видит название параметра, но может не знать, что это означает. Описав его как "Native Language Support via gettext utilities" ("Поддержка национального языка через утилиты gettext"), вы поможете пользователю гораздо больше. ==== `OPTIONS` можно группировать в виде переключателей, для которых разрешен выбор единственного варианта в каждой группе: [.programlisting] .... OPTIONS_SINGLE= SG1 OPTIONS_SINGLE_SG1= OPT3 OPT4 .... `OPTIONS` можно группировать в виде переключателей, для которых разрешен выбор единственного варианта (или ни одного) в каждой группе: [.programlisting] .... OPTIONS_RADIO= RG1 OPTIONS_RADIO_RG1= OPT7 OPT8 .... `OPTIONS` также можно группировать в виде списков со множественным выбором, для которых обязан быть включен _по крайней мере один_ из параметров: [.programlisting] .... OPTIONS_MULTI= MG1 OPTIONS_MULTI_MG1= OPT5 OPT6 .... `OPTIONS` также можно группировать в виде списков со множественным выбором, для которых могут быть включены любые параметры, включая отсутствие выбора: [.programlisting] .... OPTIONS_GROUP= GG1 OPTIONS_GROUP_GG1= OPT9 OPT10 .... По умолчанию `OPTIONS` находится в выключенном положении, если при этом оно также отсутствует в списке `OPTIONS_DEFAULT`: [.programlisting] .... OPTIONS_DEFAULT= OPT1 OPT3 OPT6 .... Определения `OPTIONS` обязаны быть до подключения [.filename]#bsd.port.options.mk#. Переменные `PORT_OPTIONS` могут быть проверены только после подключения [.filename]#bsd.port.options.mk#. Вместо этого также можно использовать подключение [.filename]#bsd.port.pre.mk#, что все еще широко используется в портах, написанных до появления [.filename]#bsd.port.options.mk#. Но имейте в виду, что некоторые переменные, обычно, это некоторые флаги `USE_*`, после подключения [.filename]#bsd.port.pre.mk# будут работать не так, как этого от них ожидают. [[ports-options-simple-use]] .Простое использование `OPTIONS` [example] ==== [.programlisting] .... OPTIONS_DEFINE= FOO BAR FOO_DESC= Enable option foo BAR_DESC= Support feature bar .include .if ${PORT_OPTIONS:MFOO} CONFIGURE_ARGS+=--with-foo .else CONFIGURE_ARGS+=--without-foo .endif .if ${PORT_OPTIONS:MBAR} RUN_DEPENDS+= bar:${PORTSDIR}/bar/bar .endif .include .... ==== [[ports-options-check-unset]] .Проверка незаданных значений `OPTIONS` [example] ==== [.programlisting] .... .if ! ${PORT_OPTIONS:MEXAMPLES} CONFIGURE_ARGS+=--without-examples .endif .... ==== [[ports-options-practical-use]] .Пример реального использования `OPTIONS` [example] ==== [.programlisting] .... OPTIONS_DEFINE= EXAMPLES OPTIONS_SINGLE= BACKEND OPTIONS_SINGLE_BACKEND= MYSQL PGSQL BDB OPTIONS_MULTI= AUTH OPTIONS_MULTI_AUTH= LDAP PAM SSL EXAMPLES_DESC= Install extra examples MYSQL_DESC= Use MySQL as backend PGSQL_DESC= Use PostgreSQL as backend BDB_DESC= Use Berkeley DB as backend LDAP_DESC= Build with LDAP authentication support PAM_DESC= Build with PAM support SSL_DESC= Build with OpenSSL support OPTIONS_DEFAULT= PGSQL LDAP SSL .include .if ${PORT_OPTIONS:MPGSQL} USE_PGSQL= yes CONFIGURE_ARGS+= --with-postgres .else CONFIGURE_ARGS+= --without-postgres .endif .if ${PORT_OPTIONS:MICU} LIB_DEPENDS+= libicuuc.so:${PORTSDIR}/devel/icu .endif .if ! ${PORT_OPTIONS:MEXAMPLES} CONFIGURE_ARGS+= --without-examples .endif # Проверка других параметров OPTIONS .include .... ==== ==== Параметры по умолчанию Следующие параметры по умолчанию всегда включены. * `DOCS` - построение и установка документации. * `NLS` - интернационализация. * `EXAMPLES` - построение и установка примеров использования. * `IPV6` - поддержка протокола IPv6. [NOTE] ==== Нет необходимости добавлять эти параметры в `OPTIONS_DEFAULT`. Тем не менее, чтобы отобразить их в окне диалога выбора параметров, они должны быть добавлены в `OPTIONS_DEFINE`. ==== === Функция автоматической активации При использовании сценария GNU configure, следите за тем, какие необязательные функции задействуются посредством автоматической активации. Отключайте явным образом те необязательные функции, которые вы не хотели бы использовать, через передачу соответствующих `--without-xxx` или `--disable-xxx` в переменной `CONFIGURE_ARGS`. .Неправильное управление опцией [example] ==== [.programlisting] .... .if ${PORT_OPTIONS:MFOO} LIB_DEPENDS+= libfoo.so:${PORTSDIR}/devel/foo CONFIGURE_ARGS+= --enable-foo .endif .... ==== В приведенном выше примере представьте себе библиотеку libfoo, установленную в системе. Пользователь не желает, чтобы приложение использовало libfoo, и поэтому он выключает соответствующую опцию в диалоге `make config`. Но сценарий configure приложения определяет наличие библиотеки в системе и включает ее поддержку в итоговый исполняемый файл. Теперь, когда пользователь решит удалить libfoo из системы, система портов позволит это сделать (т.к. зависимость от libfoo не была записана), но приложение перестанет работать. .Правильное управление опцией [example] ==== [.programlisting] .... .if ${PORT_OPTIONS:MFOO} LIB_DEPENDS+= libfoo.so:${PORTSDIR}/devel/foo CONFIGURE_ARGS+= --enable-foo .else CONFIGURE_ARGS+= --disable-foo .endif .... ==== Во втором примере библиотека libfoo отключена явным образом. Сценарий configure не включает соответствующие функции в приложении, несмотря на присутствие библиотеки в системе. [NOTE] ==== При определенных условиях сокращенный синтаксис записи условий может вызывать проблемы со сложными конструкциями. Если вы получаете ошибки, такие как `Malformed conditional`, то может быть использован альтернативный синтаксис. [.programlisting] .... .if !empty(VARIABLE:MVALUE) # as an alternative to .if ${VARIABLE:MVALUE} .... ==== === Вспомогательные макросы Существует несколько макросов, упрощающих запись условных значений, которые отличаются в зависимости от набора параметров. Если переменная `OPTIONS_SUB` имеет значение `yes`, то каждый из указанных в `OPTIONS_DEFINE` параметров будет добавлен в `PLIST_SUB`. Следующая запись: [.programlisting] .... OPTIONS_DEFINE= OPT1 OPTIONS_SUB= yes .... соответствует: [.programlisting] .... OPTIONS_DEFINE= OPT1 .include .if ${PORT_OPTIONS:MOPT1} PLIST_SUB+= OPT1="" .else PLIST_SUB+= OPT1="@comment " .endif .... `X_CONFIGURE_ENABLE` дописывает в `CONFIGURE_ARGS` строку `--enable-${X_CONFIGURE_ENABLE}` или `--disable-${X_CONFIGURE_ENABLE}` в соответствии с состоянием `X`. Следующая запись: [.programlisting] .... OPTIONS_DEFINE= OPT1 OPT1_CONFIGURE_ENABLE= test .... соответствует: [.programlisting] .... OPTIONS_DEFINE= OPT1 .include .if ${PORT_OPTIONS:MOPT1} CONFIGURE_ARGS+= --enable-test .else CONFIGURE_ARGS+= --disable-test .endif .... `X_CONFIGURE_WITH` дописывает в `CONFIGURE_ARGS` строку `--with-${X_CONFIGURE_WITH}` или `--without-${X_CONFIGURE_WITH}` в соответствии с состоянием `X`. Следующая запись: [.programlisting] .... OPTIONS_DEFINE= OPT1 OPT1_CONFIGURE_WITH= test .... соответствует: [.programlisting] .... OPTIONS_DEFINE= OPT1 .include .if ${PORT_OPTIONS:MOPT1} CONFIGURE_ARGS+= --with-test .else CONFIGURE_ARGS+= --without-test .endif .... Значение переменной `X_CONFIGURE_ON` будет дописано в `CONFIGURE_ARGS` в соответствии с состоянием `X`. Следующая запись: [.programlisting] .... OPTIONS_DEFINE= OPT1 OPT1_CONFIGURE_ON= --add-test .... соответствует: [.programlisting] .... OPTIONS_DEFINE= OPT1 .include .if ${PORT_OPTIONS:MOPT1} CONFIGURE_ARGS+= --add-test .endif .... Значение переменной `X_CONFIGURE_OFF` будет дописано в `CONFIGURE_ARGS` в соответствии с состоянием `X`. Следующая запись: [.programlisting] .... OPTIONS_DEFINE= OPT1 OPT1_CONFIGURE_OFF= --no-test .... соответствует: [.programlisting] .... OPTIONS_DEFINE= OPT1 .include .if ! ${PORT_OPTIONS:MOPT1} CONFIGURE_ARGS+= --no-test .endif .... Значение переменной `X_CMAKE_ON` будет дописано в `CMAKE_ARGS` в соответствии с состоянием `X`. Следующая запись: [.programlisting] .... OPTIONS_DEFINE= OPT1 OPT1_CMAKE_ON= -DTEST:BOOL=true .... соответствует: [.programlisting] .... OPTIONS_DEFINE= OPT1 .include .if ${PORT_OPTIONS:MOPT1} CMAKE_ARGS+= -DTEST:BOOL=true .endif .... Значение переменной `X_CMAKE_OFF` будет дописано в `CMAKE_ARGS` в соответствии с состоянием `X`. Следующая запись: [.programlisting] .... OPTIONS_DEFINE= OPT1 OPT1_CMAKE_OFF= -DTEST:BOOL=false .... соответствует: [.programlisting] .... OPTIONS_DEFINE= OPT1 .include .if ! ${PORT_OPTIONS:MOPT1} CMAKE_ARGS+= -DTEST:BOOL=false .endif .... Для любой из следующих переменных: * `ALL_TARGET` * `CATEGORIES` * `CFLAGS` * `CPPFLAGS` * `CXXFLAGS` * `CONFIGURE_ENV` * `DISTFILES` * `EXTRA_PATCHES` * `INSTALL_TARGET` * `LDFLAGS` * `MAKE_ARGS` * `MAKE_ENV` * `PATCH_SITES` * `PATCHFILES` * `PLIST_FILES` * `PLIST_DIRS` * `PLIST_DIRSTRY` * `USES` Значение переменной `X_ABOVEVARIABLE` будет дописано в `ABOVEVARIABLE` в соответствии с состоянием `X`. Следующая запись: [.programlisting] .... OPTIONS_DEFINE= OPT1 OPT1_USES= gmake OPT1_CFLAGS= -DTEST .... соответствует: [.programlisting] .... OPTIONS_DEFINE= OPT1 .include .if ${PORT_OPTIONS:MOPT1} USES+= gmake CFLAGS+= -DTEST .endif .... Если установлена `X_ABOVEVARIABLE_OFF`, то флаг `ABOVEVARIABLE` будет автоматически выставлен при выключенном параметре `X`. Например: [.programlisting] .... OPTIONS_DEFINE= OPT1 OPT1_USES_OFF=gmake .... соответствует: [.programlisting] .... OPTIONS_DEFINE= OPT1 .include .if ! ${PORT_OPTIONS:MOPT1} USES+= gmake .endif .... Для любого из следующих типов зависимости: * `PKG_DEPENDS` * `EXTRACT_DEPENDS` * `PATCH_DEPENDS` * `FETCH_DEPENDS` * `BUILD_DEPENDS` * `LIB_DEPENDS` * `RUN_DEPENDS` Значение переменной `X_ABOVEVARIABLE` будет дописано в `ABOVEVARIABLE` в соответствии с состоянием `X`. Следующая запись: [.programlisting] .... OPTIONS_DEFINE= OPT1 OPT1_LIB_DEPENDS= liba.so:${PORTSDIR}/devel/a .... соответствует: [.programlisting] .... OPTIONS_DEFINE= OPT1 .include .if ${PORT_OPTIONS:MOPT1} LIB_DEPENDS+= liba.so:${PORTSDIR}/devel/a .endif .... Если установлена `X_ABOVEVARIABLE_OFF`, то зависимость типа `ABOVEVARIABLE` будет добавлена при выключенном параметре `X`. Например: [.programlisting] .... OPTIONS_DEFINE= OPT1 OPT1_LIB_DEPENDS_OFF= liba.so:${PORTSDIR}/devel/a .... соответствует: [.programlisting] .... OPTIONS_DEFINE= OPT1 .include . if ! ${PORT_OPTIONS:MOPT1} LIB_DEPENDS+= liba.so:${PORTSDIR}/devel/a .endif .... [[makefile-wrkdir]] == Задание рабочего каталога Каждый порт распаковывается в рабочий каталог, который должен быть доступным для записи. В системе портов по умолчанию `DISTFILES` распаковываются в каталог с именем `${DISTNAME}`. Другими словами, если вы задали: [.programlisting] .... PORTNAME= foo PORTVERSION= 1.0 .... то дистрибутивные файлы порта содержат каталог верхнего уровня, [.filename]#foo-1.0#, и все файлы расположены в этом каталоге. Если это не ваш случай, то имеется несколько переменных, которые вы можете переопределить. === `WRKSRC` Эта переменная задаёт имя каталога, который создаётся при распаковке исходных файлов приложения. В нашем предыдущем примере если бы распаковка происходила в каталог с именем [.filename]#foo# (а не [.filename]#foo-1.0#), то вы должны написать: [.programlisting] .... WRKSRC= ${WRKDIR}/foo .... или, как вариант [.programlisting] .... WRKSRC= ${WRKDIR}/${PORTNAME} .... === `NO_WRKSUBDIR` Если порт вообще не распаковывается ни в какой каталог, то вы должны задать для этого переменную `NO_WRKSUBDIR`. [.programlisting] .... NO_WRKSUBDIR= yes .... [[conflicts]] == Разрешение конфликтов Для регистрации конфликта между пакетами и портами используются три различные переменные: `CONFLICTS`, `CONFLICTS_INSTALL` и `CONFLICTS_BUILD`. [NOTE] ==== -Переменные регистрации конфликта автоматически определяют переменную `IGNORE`, которая более подробно описана в <>. +Переменные регистрации конфликта автоматически определяют переменную `IGNORE`, которая более подробно описана в crossref:porting-dads[dads-noinstall, "Пометка неустанавливаемого порта как `BROKEN`, `FORBIDDEN` или `IGNORE` "]. ==== При удалении одного из конфликтующих портов целесообразно сохранить записи `CONFLICTS` в тех других портах в течении нескольких месяцев, чтобы позаботиться о тех пользователей, которые обновляются от случая к случаю. === `CONFLICTS_INSTALL` Если ваш пакет не может существовать вместе с другими (из-за конфликта файлов, несовместимости времени выполнения и так далее), перечислите имена остальных пакетов в переменной `CONFLICTS_INSTALL`. Здесь вы можете использовать шаблоны командного интерпретатора, такие как `*` и `?`. Имена пакетов должны выглядеть так же, как в [.filename]#/var/db/pkg#. Пожалуйста, убедитесь, что `CONFLICTS_INSTALL` не содержит пакет самого этого порта. В противном случае не будет работать установка с использованием переменной `FORCE_PKG_REGISTER`. Проверка CONFLICTS_INSTALL выполняется после процесса сборки и до процесса установки. === `CONFLICTS_BUILD` Если ваш порт не может быть собран, когда уже установлен другой, перечислите имена остальных портов в переменной `CONFLICTS_BUILD`. Здесь вы можете использовать шаблоны командного интерпретатора, такие как `*` и `?`. Имена пакетов должны выглядеть так же, как в [.filename]#/var/db/pkg#. Проверка CONFLICTS_BUILD выполняется до процесса сборки. Конфликты сборки в получаемом пакете не записываются. === `CONFLICTS` Если ваш порт не может быть собран, когда уже установлен другой, а получаемый пакет не может существовать вместе с другими, перечислите имена остальных пакетов в переменной `CONFLICTS`. Здесь вы можете использовать шаблоны командного интерпретатора, такие как `*` и `?`. Имена пакетов должны выглядеть так же, как в [.filename]#/var/db/pkg#. Пожалуйста, убедитесь, что `CONFLICTS` не содержит пакет самого этого порта. В противном случае не будет работать установка с использованием переменной `FORCE_PKG_REGISTER`. Проверка CONFLICTS выполняется до процессов сборки и установки. [[install]] == Установка файлов [[install-macros]] === Макросы `INSTALL_*` Используйте макросы, которые есть в файле [.filename]#bsd.port.mk# для обеспечения правильных прав доступа файлов в целях `*-install` порта. Устанавливайте права владения напрямую в [.filename]#pkg-plist# через соответствующие записи `@owner owner` и `@group group`. Эти операторы работают до момента их переопределения или до конца [.filename]#pkg-plist#, поэтому не забывайте их сбрасывать, когда они больше не нужны. По умолчанию владение устанавливается для `root:wheel`. * `INSTALL_PROGRAM` - это команда для установки бинарных выполнимых файлов. * `INSTALL_SCRIPT` - это команда для установки выполнимых скриптов. * `INSTALL_LIB` - это команда для установки динамических библиотек. * `INSTALL_KLD` - это команда для установки загружаемых модулей ядра. Некоторые архитектуры предпочитают, чтобы для модулей сохранялись отладочные сведения, по этой причине используйте эту команду вместо `INSTALL_PROGRAM`. * `INSTALL_DATA` - это команда для установки совместно используемых файлов данных. * `INSTALL_MAN` - это команда для установки страниц Справочника и другой документации (никаких файлов она не сжимает). В основе работы этих макросов лежит команда `install` со всеми соответствующими флагами. Смотрите пример их использования ниже. [[install-strip]] === Удаление отладочной информации в бинарных файлах и динамических библиотеках Не удаляйте отладочную информацию из бинарных файлов вручную, если вы это делали. Во всех двоичных файлах отладочная информация должна быть удалена, и макрос `INSTALL_PROGRAM` выполнит установку и удаление отладочной информации одновременно (обратитесь к следующему разделу). Макрос `INSTALL_LIB` делает то же самое для динамических библиотек. Если вам нужно удалить отладочную информацию из файла без использования макросов `INSTALL_PROGRAM` и `INSTALL_LIB`, то это можно сделать при помощи `${STRIP_CMD}`. Обычно это делается внутри цели `post-install`. К примеру: [.programlisting] .... post-install: ${STRIP_CMD} ${STAGEDIR}${PREFIX}/bin/xdl .... Удаление отладочной информации из нескольких файлов: [.programlisting] .... post-install: .for l in geometry media body track world ${STRIP_CMD} ${STAGEDIR}${PREFIX}/lib/lib${PORTNAME}-${l}.so.0 .endfor .... Для проверки того, удалена ли отладочная информация из файла, используйте man:file[1]. Для двоичных файлов man:file[1] печатает `stripped` или `not stripped`. Кроме того, man:strip[1] определяет, была ли уже удалена из программы отладочная информация, и в этом случае просто завершает свою работу. [[install-copytree]] === Установка целого дерева файлов Иногда должно быть установлено большое количество файлов с сохранением их иерархической организации. Например, копирование дерева каталогов целиком из `WRKSRC` в целевой каталог внутри `PREFIX`. Обратите внимание, что `PREFIX`, `EXAMPLESDIR`, `DATADIR` и другие переменные пути всегда должны предваряться `STAGEDIR`, чтобы не ломать staging (смотрите <>). Для этой ситуации существует два макроса. Преимущество от использования этих макросов вместо команды `cp` в том, что они гарантируют установку правильного владельца и прав на конечные файлы. Первый макрос, `COPYTREE_BIN`, делает все устанавливаемые файлы исполняемыми, что подходит для установки в [.filename]#PREFIX/bin#. Второй макрос, `COPYTREE_SHARE`, не устанавливает на файлы права исполнения, и, таким образом, подходит для установки файлов внутри каталога [.filename]#PREFIX/share#. [.programlisting] .... post-install: ${MKDIR} ${STAGEDIR}${EXAMPLESDIR} (cd ${WRKSRC}/examples && ${COPYTREE_SHARE} . ${STAGEDIR}${EXAMPLESDIR}) .... В этом примере устанавливается содержимое каталога [.filename]#examples# из установочных файлов производителя в надлежащее место для примеров вашего порта. [.programlisting] .... post-install: ${MKDIR} ${STAGEDIR}${DATADIR}/summer (cd ${WRKSRC}/temperatures && ${COPYTREE_SHARE} "June July August" ${STAGEDIR}${DATADIR}/summer) .... А в этом примере будут установлены данные летних месяцев в подкаталог [.filename]#summer# каталога [.filename]#DATADIR#. В качестве третьего параметра в макросе `COPYTREE_*` можно передать дополнительные параметры `find`. Например, чтобы в первом примере установить все файлы кроме файлов Makefile, можно использовать следующую команду. [.programlisting] .... post-install: ${MKDIR} ${STAGEDIR}${EXAMPLESDIR} (cd ${WRKSRC}/examples && \ ${COPYTREE_SHARE} . ${STAGEDIR}${EXAMPLESDIR} "! -name Makefile") .... Эти макросы не производят добавление устанавливаемых файлов в [.filename]#pkg-plist#. Они должны быть добавлены туда вручную. Необязательные файлы документации (`PORTDOCS`, смотрите <>) и примеров (`PORTEXAMPLES`) всегда должны предваряться в [.filename]#pkg-plist# префиксами `%%PORTDOCS%%` или `%%PORTEXAMPLES%%`. [[install-documentation]] === Установка дополнительной документации Если с вашим программным обеспечением поставляется некоторая документация, отличающаяся от стандартных страниц Справочника и файлов info, которая, как вы думаете, будет полезна пользователям, установите ее в каталог [.filename]#PREFIX/shared/doc#. Это может быть сделано, как и в предыдущем разделе, в цели `post-install`. Создайте для вашего порта новый каталог. Имя каталога должно соответствовать тому, что представляет из себя порт. Обычно это означает `PORTNAME`. Однако, если вы думаете, что пользователь захочет иметь разные версии порта, установленные одновременно, то вы можете использовать полное имя `PKGNAME`. -Поскольку устанавливаются только файлы, перечисленные в [.filename]#pkg-plist#, безопасным способом будет устанавливать документацию в `STAGEDIR` всегда (смотрите <>). Следовательно, блоки `.if` нужны только для файлов достаточно большого размера, установка которых влечёт значительные накладные расходы на операции ввода/вывода. +Поскольку устанавливаются только файлы, перечисленные в [.filename]#pkg-plist#, безопасным способом будет устанавливать документацию в `STAGEDIR` всегда (смотрите crossref:special[staging, Staging]). Следовательно, блоки `.if` нужны только для файлов достаточно большого размера, установка которых влечёт значительные накладные расходы на операции ввода/вывода. [.programlisting] .... post-install: ${MKDIR} ${STAGEDIR}${DOCSDIR} ${INSTALL_MAN} ${WRKSRC}/docs/xvdocs.ps ${STAGEDIR}${DOCSDIR} .... Вот несколько полезных переменных и то, как они преобразуются по умолчанию при использовании в [.filename]#Makefile#: * `DATADIR` преобразуется в [.filename]#PREFIX/shared/PORTNAME#. * `DATADIR_REL` преобразуется в [.filename]#share/PORTNAME#. * `DOCSDIR` преобразуется в [.filename]#PREFIX/shared/doc/PORTNAME#. * `DOCSDIR_REL` преобразуется в [.filename]#share/doc/PORTNAME#. * `EXAMPLESDIR` преобразуется в [.filename]#PREFIX/shared/examples/PORTNAME#. * `EXAMPLESDIR_REL` преобразуется в [.filename]#share/examples/PORTNAME#. [NOTE] ==== Параметр `DOCS` управляет установкой дополнительной документации в `DOCSDIR`. Это не относится к стандартным страницам справочника и страницам info. Все, что устанавливается в `DATADIR` и `EXAMPLESDIR`, соответственно управляется через параметры `DATA` и `EXAMPLES`. ==== Эти переменные экспортируются в `PLIST_SUB`. Их значения появятся там в виде имён путей относительно [.filename]#PREFIX#, если это возможно. То есть [.filename]#share/doc/PORTNAME# в списке сборки по умолчанию будет заменен на `%%DOCSDIR%%`, и так далее. (Дополнительную информацию о подстановке в [.filename]#pkg-plist# можно найти <>.) Все условно устанавливаемые файлы и каталоги с документацией должны быть перечислены в файле [.filename]#pkg-plist# с префиксом `%%PORTDOCS%%`, например: [.programlisting] .... %%PORTDOCS%%%%DOCSDIR%%/AUTHORS %%PORTDOCS%%%%DOCSDIR%%/CONTACT %%PORTDOCS%%@dirrm %%DOCSDIR%% .... В качестве альтернативы перечислению файлов документации в файле [.filename]#pkg-plist#, порт может указать в переменной `PORTDOCS` список имён файлов и глобальных шаблонов командного процессора для добавления в окончательный список сборки. Имена будут задаваться относительно `DOCSDIR`. Таким образом, порт, использующий `PORTDOCS` и нестандартное местоположение документации, должен задавать соответствующим образом и `DOCSDIR`. Если каталог указан в `PORTDOCS` или соответствует шаблону для этой переменной, то полное поддерево с входящими в него файлами и каталогами будет регистрироваться в окончательном списке сборки. Если параметр `DOCS` не задан, то файлы и каталоги, перечисленные в `PORTDOCS`, не будут установлены и добавлены в список сборки порта. Установка документации в `PORTDOCS`, как это показано выше, остаётся за самим портом. Типичный пример использования `PORTDOCS` выглядит следующим образом: [.programlisting] .... PORTDOCS= README.* ChangeLog docs/* .... [NOTE] ==== Эквивалентами `PORTDOCS` для файлов, устанавливаемых в `DATADIR` и `EXAMPLESDIR` являются `PORTDATA` и `PORTEXAMPLES` соответственно. Во время установки выводится содержимое [.filename]#pkg-message#. За подробной информацией обратитесь к <>. Файл [.filename]#pkg-message# не нужно добавлять в [.filename]#pkg-plist#. ==== [[install-subdirs]] === Подкаталоги внутри PREFIX Попробуйте поместить все файлы порта в правильных подкаталогах каталога `PREFIX`. Некоторые порты игнорируют все установки и помещают все в подкаталог с именем порта, что неправильно. Также многие порты помещают все, кроме бинарных файлов, файлов заголовков и страниц Справочника, в подкаталог каталога [.filename]#lib#, что не очень хорошо работает с подходом BSD. Многие файлы должны быть перемещены в одно из следующих местоположений: [.filename]#etc# (настроечные/конфигурационные файлы), [.filename]#libexec# (выполнимые файлы, запускаемые из других программ), [.filename]#sbin# (исполнимые файлы для администраторов/менеджеров системы), [.filename]#info# (документация в формате info для просмотрщика info) или [.filename]#share# (независимые от архитектуры файлы). Обратитесь к man:hier[7] для прояснения деталей; правила, покрывающие [.filename]#/usr#, достаточно хорошо подходят также и к [.filename]#/usr/local#. Исключением являются порты, имеющие дело с "новостями" USENET. Они могут использовать каталог [.filename]#PREFIX/news# для установки своих файлов. diff --git a/documentation/content/ru/books/porters-handbook/new-port/chapter.adoc b/documentation/content/ru/books/porters-handbook/new-port/_index.adoc similarity index 97% rename from documentation/content/ru/books/porters-handbook/new-port/chapter.adoc rename to documentation/content/ru/books/porters-handbook/new-port/_index.adoc index 43b61bce99..e4a0c67481 100644 --- a/documentation/content/ru/books/porters-handbook/new-port/chapter.adoc +++ b/documentation/content/ru/books/porters-handbook/new-port/_index.adoc @@ -1,56 +1,56 @@ --- title: Глава 2. Как самому сделать новый порт prev: books/porters-handbook/porting-why next: books/porters-handbook/quick-porting --- [[own-port]] = Making a New Port :doctype: book :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :sectnumoffset: 2 :partnums: :source-highlighter: rouge :experimental: :images-path: books/porters-handbook/ ifdef::env-beastie[] ifdef::backend-html5[] :imagesdir: ../../../../images/{images-path} endif::[] ifndef::book[] include::shared/authors.adoc[] include::shared/mirrors.adoc[] include::shared/releases.adoc[] include::shared/attributes/attributes-{{% lang %}}.adoc[] include::shared/{{% lang %}}/teams.adoc[] include::shared/{{% lang %}}/mailing-lists.adoc[] include::shared/{{% lang %}}/urls.adoc[] toc::[] endif::[] ifdef::backend-pdf,backend-epub3[] include::../../../../../shared/asciidoctor.adoc[] endif::[] endif::[] ifndef::env-beastie[] toc::[] include::../../../../../shared/asciidoctor.adoc[] endif::[] Итак, вы интересуетесь, как создать собственный порт или обновить существующий? Великолепно! -Ниже находятся некоторые указания по созданию нового порта для FreeBSD. Если вы хотите обновить существующий порт, вы должны прочесть их, а затем <>. +Ниже находятся некоторые указания по созданию нового порта для FreeBSD. Если вы хотите обновить существующий порт, вы должны прочесть их, а затем crossref:upgrading[port-upgrading, Обновление отдельного порта]. Если этот документ недостаточно подробен, вы должны обратиться к файлу [.filename]#/usr/ports/Mk/bsd.port.mk#, который включается в make-файл каждого порта. Он хорошо прокомментирован, и даже если вы не занимаетесь хакингом make-файлов каждодневно, из него вы сможете узнать много нового. Кроме того, конкретные вопросы можно задать, послав письмо на адрес {freebsd-ports}. [NOTE] ==== Только часть переменных (`_VAR_`), которые могут быть переопределены, описаны в этом документе. Большинство (если не все) описаны в начале файла [.filename]#/usr/ports/Mk/bsd.port.mk#; остальные, скорее всего, тоже там описаны. Заметьте, что в этом файле используется нестандартная настройка шага табуляции: Emacs и Vim должны распознать это при загрузке файла. Как man:vi[1], так и man:ex[1] могут быть настроены на использование правильного значения выдачей команды `:set tabstop=4` после загрузки файла. ==== Ищете, с чего бы начать попроще? Посмотрите на http://wiki.freebsd.org/WantedPorts[перечень запрошенных портов], есть ли там такие, над которыми вы можете работать. diff --git a/documentation/content/ru/books/porters-handbook/pkg-files/chapter.adoc b/documentation/content/ru/books/porters-handbook/pkg-files/_index.adoc similarity index 99% rename from documentation/content/ru/books/porters-handbook/pkg-files/chapter.adoc rename to documentation/content/ru/books/porters-handbook/pkg-files/_index.adoc index 5f98929394..7b641bf91b 100644 --- a/documentation/content/ru/books/porters-handbook/pkg-files/chapter.adoc +++ b/documentation/content/ru/books/porters-handbook/pkg-files/_index.adoc @@ -1,143 +1,143 @@ --- title: Глава 8. Файлы pkg-* prev: books/porters-handbook/plist next: books/porters-handbook/testing --- [[pkg-files]] -= Файлы [.filename]#pkg-*# += Файлы pkg-* :doctype: book :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :sectnumoffset: 8 :partnums: :source-highlighter: rouge :experimental: :images-path: books/porters-handbook/ ifdef::env-beastie[] ifdef::backend-html5[] :imagesdir: ../../../../images/{images-path} endif::[] ifndef::book[] include::shared/authors.adoc[] include::shared/mirrors.adoc[] include::shared/releases.adoc[] include::shared/attributes/attributes-{{% lang %}}.adoc[] include::shared/{{% lang %}}/teams.adoc[] include::shared/{{% lang %}}/mailing-lists.adoc[] include::shared/{{% lang %}}/urls.adoc[] toc::[] endif::[] ifdef::backend-pdf,backend-epub3[] include::../../../../../shared/asciidoctor.adoc[] endif::[] endif::[] ifndef::env-beastie[] toc::[] include::../../../../../shared/asciidoctor.adoc[] endif::[] Есть несколько приёмов работы с файлами [.filename]#pkg-*#, которые мы ещё не описали, но они иногда могут быть очень кстати. [[porting-message]] == [.filename]#pkg-message# Если вам нужно вывести сообщение для человека, устанавливающего приложение, то вы можете поместить сообщение в файл [.filename]#pkg-message#. Эта возможность часто оказывается полезной для вывода дополнительных шагов установки, которые нужно предпринять после выполнения команды `pkg install`, или для вывода информации о лицензировании. Если должны выводиться некоторые строки о knobs времени построения или предупреждения, используйте `ECHO_MSG`. Файл [.filename]#pkg-message# только для послеустановочных шагов. Также следует иметь в виду различие между `ECHO_MSG` и `ECHO_CMD`. Первое предназначено для вывода на экран информационного текста, а второе для конвейера команд: [.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 .... [NOTE] ==== Файл [.filename]#pkg-message# не нужно добавлять в [.filename]#pkg-plist#. ==== [[pkg-install]] == [.filename]#pkg-install# Если при установке бинарного пакета по команде `pkg add` или `pkg install` вашему порту нужно выполнить какие-то команды, то вы можете это сделать с помощью скрипта [.filename]#pkg-install#. Этот скрипт будет автоматически добавлен к пакету и будет дважды запускаться командой `pkg`: первый раз в виде `${SH} pkg-install ${PKGNAME} PRE-INSTALL`, а второй раз как `${SH} {PKGNAME} POST-INSTALL`. Для распознавания того, в каком режиме запущен скрипт, можно использовать параметр `$2`. Переменная окружения `PKG_PREFIX` будет принимать значение, соответствующее каталогу, в который устанавливается пакет. [NOTE] ==== Этот скрипт не запускается автоматически, если вы устанавливаете порт командой `make install`. Если же вам действительно необходимо его запустить, то запустите его явно из файла [.filename]#Makefile# порта строкой вида `PKG_PREFIX=${PREFIX} ${SH} $ {PKGINSTALL}${PKGNAME} PRE-INSTALL`. ==== [[pkg-deinstall]] == [.filename]#pkg-deinstall# Этот скрипт вызывается при удалении пакета. Этот скрипт будет дважды запускаться командой `pkg delete`. Первый раз как `${SH} pkg-deinstall ${PKGNAME} DEINSTALL`, а второй раз как `${SH} pkg-deinstall ${PKGNAME} POST-DEINSTALL`. [[pkg-names]] == Изменение имён файлов [.filename]#pkg-*# Все имена файлов [.filename]#pkg-\*# определяются с помощью переменных, так что вы можете изменить их, если это нужно, в вашем файле [.filename]#Makefile#. Это особенно полезно, если вы используете одни и те же файлы [.filename]#pkg-*# совместно между несколькими портами или пишете в один из вышеперечисленных файлов (в главе о <> объяснено, почему не рекомендуется осуществлять запись непосредственно в файлы [.filename]#pkg-*#. Вот список имён переменных и их значений по умолчанию. (Значение `PKGDIR` по умолчанию равно `${MASTERDIR}`.) [.informaltable] [cols="1,1", frame="none", options="header"] |=== | Переменная | Значение по умолчанию |`DESCR` |`${PKGDIR}/pkg-descr` |`PLIST` |`${PKGDIR}/pkg-plist` |`PKGINSTALL` |`${PKGDIR}/pkg-install` |`PKGDEINSTALL` |`${PKGDIR}/pkg-deinstall` |`PKGMESSAGE` |`${PKGDIR}/pkg-message` |=== Пожалуйста, изменяйте значения этих переменных, а не переопределяйте `PKG_ARGS`. Если вы измените значение переменных `PKG_ARGS`, то эти файлы при установке из порта будут установлены в каталог [.filename]#/var/db/pkg# некорректно. [[using-sub-files]] == Использование `SUB_FILES` и `SUB_LIST` Переменные `SUB_FILES` и `SUB_LIST` подходят для задания в файлах порта динамических значений, таких как `PREFIX` установки в [.filename]#pkg-message#. В переменной `SUB_FILES` указывается перечень файлов для автоматического изменения. Каждый _file_ из перечня `SUB_FILES` обязан иметь соответствующий [.filename]#file.in#, присутствующий в `FILESDIR`. Измененная версия будет создана в `WRKDIR`. Файлы, определенные в качестве значения `USE_RC_SUBR` (или устаревшего `USE_RCORDER`), автоматически добавляются в `SUB_FILES`. Для файлов [.filename]#pkg-message#, [.filename]#pkg-install# и [.filename]#pkg-deinstall# устанавливается соответствующая переменная Makefile, указывающая на обработанную версию. Переменная `SUB_LIST` содержит перечень пар `VAR=VALUE`. В каждом файле из `SUB_FILES` для каждой пары будет произведена замена `%%VAR%%` на `VALUE`. Некоторые общие пары определяются автоматически: `PREFIX`, `LOCALBASE`, `DATADIR`, `DOCSDIR`, `EXAMPLESDIR`, `WWWDIR` и `ETCDIR`. Любая строка, начинающаяся с `@comment`, будет удалена из конечного файла после подстановки переменной. В следующем примере в [.filename]#pkg-message# будет сделана замена `%%ARCH%%` на системную архитектуру: [.programlisting] .... SUB_FILES= pkg-message SUB_LIST= ARCH=${ARCH} .... Обратите внимание, что в этом примере в `FILESDIR` обязательно существование файла [.filename]#pkg-message.in#. Пример хорошего [.filename]#pkg-message.in#: [.programlisting] .... Now it is time to configure this package. Copy %%PREFIX%%/shared/examples/putsy/%%ARCH%%.conf into your home directory as .putsy.conf and edit it. .... diff --git a/documentation/content/ru/books/porters-handbook/plist/chapter.adoc b/documentation/content/ru/books/porters-handbook/plist/_index.adoc similarity index 99% rename from documentation/content/ru/books/porters-handbook/plist/chapter.adoc rename to documentation/content/ru/books/porters-handbook/plist/_index.adoc index db57d34ca3..1f84971b10 100644 --- a/documentation/content/ru/books/porters-handbook/plist/chapter.adoc +++ b/documentation/content/ru/books/porters-handbook/plist/_index.adoc @@ -1,170 +1,170 @@ --- -title: Глава 7. Продвинутые практики [.filename]#pkg-plist# +title: Глава 7. Продвинутые практики pkg-plist prev: books/porters-handbook/special next: books/porters-handbook/pkg-files --- [[plist]] -= Продвинутые практики [.filename]#pkg-plist# += Продвинутые практики pkg-plist :doctype: book :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :sectnumoffset: 7 :partnums: :source-highlighter: rouge :experimental: :images-path: books/porters-handbook/ ifdef::env-beastie[] ifdef::backend-html5[] :imagesdir: ../../../../images/{images-path} endif::[] ifndef::book[] include::shared/authors.adoc[] include::shared/mirrors.adoc[] include::shared/releases.adoc[] include::shared/attributes/attributes-{{% lang %}}.adoc[] include::shared/{{% lang %}}/teams.adoc[] include::shared/{{% lang %}}/mailing-lists.adoc[] include::shared/{{% lang %}}/urls.adoc[] toc::[] endif::[] ifdef::backend-pdf,backend-epub3[] include::../../../../../shared/asciidoctor.adoc[] endif::[] endif::[] ifndef::env-beastie[] toc::[] include::../../../../../shared/asciidoctor.adoc[] endif::[] [[plist-sub]] == Изменение содержимого [.filename]#pkg-plist# в зависимости от make-переменных Некоторые порты, в частности, порты `p5-`, должны менять содержимое своих файлов [.filename]#pkg-plist# в зависимости от того, с какими параметрами они были отконфигурированы (или в зависимости от версии языка `perl` в случае портов `p5-`). Чтобы облегчить этот процесс, любые вхождения ключевых слов `%%OSREL%%`, `%%PERL_VER%%` и `%%PERL_VERSION%%` в файле [.filename]#pkg-plist# будут заменяться соответствующими значениями. Значением `%%OSREL%%` является номер версии операционной системы (например, `4.9`). `%%PERL_VERSION%%` и `%%PERL_VER%%` обозначают полный номер версии `perl` (например, `5.8.9`). Некоторые другие `%%VARS%%`, имеющие отношение к файлам документации порта, описаны в <>. Если вам нужно сделать другие подстановки, вы можете указать в переменной `PLIST_SUB` список пар `VAR=VALUE`, и все вхождения `%%VAR%%` в файле [.filename]#pkg-plist# будут заменяться на значение _VALUE_. Например, если у вас имеется порт, который устанавливает много файлов в каталог, зависящий от версии, вы можете задать нечто типа [.programlisting] .... OCTAVE_VERSION= 2.0.13 PLIST_SUB= OCTAVE_VERSION=${OCTAVE_VERSION} .... в файле [.filename]#Makefile# и использовать `%%OCTAVE_VERSION%%` везде, где нужно указать номер версии в файле [.filename]#pkg-plist#. Таким образом, при обновлении порта вам не нужно будет менять десятки (а в некоторых случаях и сотни) строк в файле [.filename]#pkg-plist#. Если ваш порт устанавливает файлы в соответствии с установленными в порту опциями, то обычным способом управления является добавление префиксов `%%TAG%%` для строк [.filename]#pkg-plist# с добавлением этого `TAG` в переменную `PLIST_SUB` внутри [.filename]#Makefile# со специальным значением `@comment`, которое указывает пакетным инструментам игнорировать эти строки: [.programlisting] .... .if defined(WITH_X11) PLIST_SUB+= X11="" .else PLIST_SUB+= X11="@comment " .endif .... и в самом [.filename]#pkg-plist#: [.programlisting] .... %%X11%%bin/foo-gui .... Эта подстановка будет сделана между выполнением целей `pre-install` и `do-install`, посредством чтения файла [.filename]#PLIST# и записью в файл [.filename]#TMPPLIST# (по умолчанию это файл [.filename]#WRKDIR/.PLIST.mktmp#). Так что если ваш порт строит [.filename]#PLIST# на лету, делайте это во время или до выполнения цели `pre-install`. Кроме того, если вашему порту требуется отредактировать получающийся файл, делайте это в цели `post-install` изменением файла [.filename]#TMPPLIST#. Другой способ изменения списка сборки порта основан на определении значений переменных `PLIST_FILES`, `PLIST_DIRS` и `PLIST_DIRSTRY`. Каждое из них рассматривается как перечень путей для записи в [.filename]#TMPPLIST# содержимого [.filename]#PLIST#. Имена, перечисленные в `PLIST_FILES`, `PLIST_DIRS` и `PLIST_DIRSTRY` подвергаются подстановке `%%VAR%%`, как описано выше. За исключением этого, имена из `PLIST_FILES` будут появляться в окончательном варианте перечня сборки без изменений, тогда как `@dirrm` и `@dirrmtry` будут соответственно предшествовать именам из `PLIST_DIRS` и `PLIST_DIRSTRY`. Для того чтобы изменения вступили в силу, `PLIST_FILES`, `PLIST_DIRS` и `PLIST_DIRSTRY` должны задаваться до того, как будет записываться [.filename]#TMPPLIST#, то есть в цели `pre-install` или ещё раньше. [[plist-cleaning]] == Пустые каталоги [[plist-dir-cleaning]] === Очистка пустых каталогов Заставьте ваш порты удалять пустые каталоги при удалении. Обычно это достигается добавлением строк `@dirrm` для всех каталогов, которые создаются этим портом. Вам нужно удалить подкаталоги до того, как вы сможете удалить родительские каталоги. [.programlisting] .... : lib/X11/oneko/pixmaps/cat.xpm lib/X11/oneko/sounds/cat.au : @dirrm lib/X11/oneko/pixmaps @dirrm lib/X11/oneko/sounds @dirrm lib/X11/oneko .... Однако, иногда `@dirrm` будет выдавать ошибки, потому что другие порты используют тот же самый подкаталог. Вы можете использовать `@dirrmtry` для удаления только пустых каталогов без выдачи предупреждений. [.programlisting] .... @dirrmtry share/doc/gimp .... Эта команда не выведет никаких сообщений об ошибках и не вызовет аварийного завершения работы `pkg delete` (см. man:pkg-delete[8]), даже если каталог [.filename]#${PREFIX}/shared/doc/gimp# не пуст из-за того, что другие порты установили сюда какие-то файлы. [[plist-dir-empty]] === Создание пустых каталогов Пустым каталогам, создаваемым во время установки порта, нужно особое внимание. Они не будут созданы при установке пакета, потому что пакеты содержат только файлы, а `pkg add` и `pkg install` создают для них каталоги по мере надобности. Чтобы убедиться, что пустой каталог создается при установке пакета, добавьте эту строку в [.filename]#pkg-plist# перед соответствующей строкой `@dirrm`: [.programlisting] .... @exec mkdir -p %D/shared/foo/templates .... [[plist-config]] == Конфигурационные файлы Если ваш порт устанавливает конфигурационные файлы в каталог [.filename]#PREFIX/etc# (или куда-то еще), _не_ делайте их простого перечисления в файле [.filename]#pkg-plist#. Это приведёт к тому, что по команде `pkg delete` или при новой установке файлы, тщательно отредактированные и настроенные пользователем, будут уничтожены. Вместо этого установите файл(ы) с примерами с расширением [.filename]#filename.sample#. Затем скопируйте файл с примером на место настоящего файла конфигурации, если таковой ещё не существует. При деинсталляции удаляйте файл конфигурации только в том случае, если он идентичен файлу с расширением [.filename]#.sample#. Вам нужно управлять этим в [.filename]#Makefile# и в [.filename]#pkg-plist# (для установки из пакета). Пример части [.filename]#Makefile#: [.programlisting] .... post-install: @if [ ! -f ${PREFIX}/etc/orbit.conf ]; then \ ${CP} -p ${PREFIX}/etc/orbit.conf.sample ${STAGEDIR}${PREFIX}/etc/orbit.conf ; \ fi .... Добавьте по три строки в [.filename]#pkg-plist# для каждого конфигурационного файла, как показано ниже: [.programlisting] .... @unexec if cmp -s %D/etc/orbit.conf.sample %D/etc/orbit.conf; then rm -f %D/etc/orbit.conf; fi etc/orbit.conf.sample @exec if [ ! -f %D/etc/orbit.conf ] ; then cp -p %D/%F %B/orbit.conf; fi .... Данные строки являются упорядоченными. На этапе удаления файл с примером сравнивается с рабочим конфигурационным файлом. Полное совпадение означает отсутствие каких-либо изменений в рабочем файле со стороны пользователя, и следовательно этот файл может быть безопасно удалён. Так как файл с примером всё ещё должен существовать для сравнения, строка `@unexec` следует перед именем файла с примером конфигурации. На этапе установки, если рабочий файл конфигурации отсутствует, он копируется из файла с примером. Файл с примером обязательно должен быть установлен до операции копирования, поэтому строка `@exec` следует после имени файла с примером конфигурации. Для получения дополнительного отладочного вывода на экран можно временно удалить параметр `-s` из команды man:cmp[1]. Для получения дополнительной инфорации по использованию `%D` и прочих маркеров подстановки обратитесь к странице Справочника man:pkg-create[8]. Если существует действительно стоящая причина не устанавливать рабочий файл конфигурации по умолчанию, уберите строку `@exec` из [.filename]#pkg-plist# и добавьте <>, указывающее на то, что пользователь обязан скопировать и отредактировать этот файл перед тем, как программное обеспечение начнёт работать. [[plist-dynamic]] == Динамический или статический список упаковки _Статический список упаковки_ - это список упаковки, который доступен в Коллекции Портов или как файл [.filename]#pkg-plist# (с подстановкой переменных или без неё), или как встроенный в [.filename]#Makefile# посредством `PLIST_FILES`, `PLIST_DIRS` и `PLIST_DIRSTRY`. Даже если содержимое является автоматически порождаемым при помощи инструмента или в результате выполнения цели в Makefile _до_ включения в Коллекцию Портов коммиттером, то список всё ещё будет считаться статическим, поскольку его можно узнать без необходимости скачивания или компиляции дистрибутива. _Динамический список упаковки_ это список упаковки, который получается во время компиляции порта и строится на основе устанавливаемых файлов и каталогов. Узнать такой список невозможно до того, как исходный код портируемого приложения будет скачен и скомпилирован, или после запуска `make clean`. Хотя использование динамических список упаковки не запрещено, сопровождающие должны использовать статические списки упаковки везде, где это возможно, поскольку это позволяет пользователям выполнять man:grep[1] по доступным портам для обнаружения, например, который порт устанавливает определенный файл. Динамические списки должны быть использованы в основном для сложных портов, для которых изменения в списке упаковки кардинальным образом основаны на необязательных возможностях порта (и, таким образом, делая сопровождение статических списков упаковки невозможным), или портов, которые изменяют список упаковки на основе версии используемого им программного обеспечения (например, порты, которые порождают документы при помощи Javadoc). [[plist-autoplist]] == Автоматическое создание списка упаковки Первым делом убедитесь, что ваш порт практически полностью завершён и осталось создать только [.filename]#pkg-plist#. После этого вы можете запустить `make makeplist` для автоматического создания [.filename]#pkg-plist#. Содержимое этого файла должно быть дважды перепроверено. Пользовательские конфигурационные файлы должны быть удалены или быть установлены как [.filename]#filename.sample#. Файл [.filename]#info/dir# включать в список не нужно, но должны быть добавлены соответствующие строчки [.filename]#install-info#, так, как это описано в разделе о <>. Все библиотеки, устанавливаемые портом, должны быть перечислены так, как это описано в разделе о <>. diff --git a/documentation/content/ru/books/porters-handbook/porting-dads/chapter.adoc b/documentation/content/ru/books/porters-handbook/porting-dads/_index.adoc similarity index 99% rename from documentation/content/ru/books/porters-handbook/porting-dads/chapter.adoc rename to documentation/content/ru/books/porters-handbook/porting-dads/_index.adoc index 1960a211a4..28f6049c6a 100644 --- a/documentation/content/ru/books/porters-handbook/porting-dads/chapter.adoc +++ b/documentation/content/ru/books/porters-handbook/porting-dads/_index.adoc @@ -1,419 +1,419 @@ --- title: Глава 12. Что делать нужно, и что делать нельзя prev: books/porters-handbook/security next: books/porters-handbook/porting-samplem --- [[porting-dads]] = Что делать нужно, и что делать нельзя :doctype: book :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :sectnumoffset: 12 :partnums: :source-highlighter: rouge :experimental: :freebsd-version: __FreeBSD_version :freebsd: __FreeBSD__ :images-path: books/porters-handbook/ ifdef::env-beastie[] ifdef::backend-html5[] :imagesdir: ../../../../images/{images-path} endif::[] ifndef::book[] include::shared/authors.adoc[] include::shared/mirrors.adoc[] include::shared/releases.adoc[] include::shared/attributes/attributes-{{% lang %}}.adoc[] include::shared/{{% lang %}}/teams.adoc[] include::shared/{{% lang %}}/mailing-lists.adoc[] include::shared/{{% lang %}}/urls.adoc[] toc::[] endif::[] ifdef::backend-pdf,backend-epub3[] include::../../../../../shared/asciidoctor.adoc[] endif::[] endif::[] ifndef::env-beastie[] toc::[] include::../../../../../shared/asciidoctor.adoc[] endif::[] [[dads-intro]] == Введение Вот список часто встречающихся действий, которые нужно и которые нельзя делать во время процесса портирования. Проверьте порт по этому списку, и также проверьте порты в http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query[базе сообщений PR], которые присланы другими людьми. Присылайте любые комментарии о портах, которые вы проверили, так, как это описано в статье о extref:{contributing}[Сообщениях об ошибках и общих замечаниях, CONTRIB-GENERAL]. Проверка портов в базе сообщений PR позволит нам быстрее коммиттить их и удостовериться, что вы знаете, что делаете. [[porting-wrkdir]] == `WRKDIR` Не пишите ничего в файлы вне каталога `WRKDIR`. Каталог `WRKDIR` является единственным местом, которое гарантированно будет доступно для записи во время построения порта (обратитесь к главе об extref:{handbook}ports[установке портов с CDROM, PORTS-CD] за примером построения портов из дерева, доступного только для чтения). Если вам нужно изменить какой-либо из файлов [.filename]##pkg-*##, сделайте это, <>, но не перезаписывая их. [[porting-wrkdirprefix]] == `WRKDIRPREFIX` Добейтесь того, чтобы ваш порт принимал во внимание значение переменной `WRKDIRPREFIX`. Большинство портов об этом не заботятся. В частности, если вы обращаетесь к каталогу `WRKDIR` другого порта, заметьте, что его правильным местоположением является [.filename]#WRKDIRPREFIXPORTSDIR/subdir/name/work#, а не [.filename]#PORTSDIR/subdir/work# или [.filename]#.CURDIR/../../subdir/name/work# мли что-то подобное. Кроме того, если вы сами задаете `WRKDIR`, то должны поставить перед ним знак `${WRKDIRPREFIX}${.CURDIR}`. [[porting-versions]] == Различение операционных систем и версий ОС Вы можете встретиться с кодом, который требует модификаций или условной компиляции в зависимости от того, с какой версией FreeBSD Unix он работает. Предпочтительным способом отделения кода для версий FreeBSD является использование макросов {freebsd-version} и {freebsd}, определённых в http://svnweb.freebsd.org/base/head/sys/sys/param.h?view=markup[sys/param.h]. Если этот файл не подключен, добавьте код [.programlisting] .... #include .... в нужном месте файла [.filename]#.c#. {freebsd} определён во всех версиях FreeBSD в качестве старшего номера версии системы. Например, в FreeBSD 9.x {freebsd} определён со значением `9`. [.programlisting] .... #if __FreeBSD__ >= 9 # if __FreeBSD_version >= 901000 /* здесь особый код для версий 9.1+ */ # endif #endif .... [[dads-after-port-mk]] == Написание чего-либо после [.filename]#bsd.port.mk# Не пишите ничего после строки `.include `. Этой строки можно избежать, включив в где-то в середину вашего файла [.filename]#Makefile# файл [.filename]#bsd.port.pre.mk#, и файл [.filename]#bsd.port.post.mk# в конец. [NOTE] ==== Вам нужно включить либо пару файлов [.filename]#bsd.port.pre.mk#/[.filename]#bsd.port.post.mk#, либо только [.filename]#bsd.port.mk#; не используйте оба этих метода одновременно. ==== В файле [.filename]#bsd.port.pre.mk# определяются лишь несколько переменных, которые могут быть использованы в тестах из файла [.filename]#Makefile#, в файле [.filename]#bsd.port.post.mk# заданы остальные. Вот некоторые важные переменные, определенные в файле [.filename]#bsd.port.pre.mk# (это не полный список, для выяснения полного списка прочтите, пожалуйста, сам файл [.filename]#bsd.port.mk#). [.informaltable] [cols="1,1", frame="none", options="header"] |=== | Переменная | Описание |`ARCH` |Архитектура машины в виде, получаемом по команде `uname -m` (например, `i386`) |`OPSYS` |Тип операционной системы, получаемый по команде `uname -s` (например, `FreeBSD`) |`OSREL` |Версия релиза операционной системы (например, `2.1.5` или `2.2.7`) |`OSVERSION` |Версия операционной системы в виде числа, та же, что и <>. |`LOCALBASE` |Корень дерева "local" (например, `/usr/local`) |`PREFIX` |Куда, собственно, устанавливается порт (обратитесь к <>). |=== [NOTE] ==== Если вы задаете переменную `MASTERDIR`, делайте это до подключения [.filename]#bsd.port.pre.mk#. ==== Вот несколько примеров того, что вы можете написать после [.filename]#bsd.port.pre.mk#: [.programlisting] .... # no need to compile lang/perl5 if perl5 is already in system .if ${OSVERSION} > 300003 BROKEN= perl is in system .endif .... Вы не забываете об использовании табуляции вместо пробелов после `BROKEN=`:-). [[dads-sh-exec]] == Использование выражения `exec` в сценариях обёртках Если порт устанавливает сценарий на языке shell, который служит для запуска другой программы, и если запуск этой программы является последним действием сценария, убедитесь, что запуск программы производится с использованием выражения `exec`, например: [.programlisting] .... #!/bin/sh exec %%LOCALBASE%%/bin/java -jar %%DATADIR%%/foo.jar "$@" .... Выражение `exec` заменяет процесс сценария на указанную программу. Если `exec` опущен, то процесс сценария во время работы программы остается в памяти, бесполезно потребляя системные ресурсы. [[dads-rational]] == Поступайте разумно Файл [.filename]#Makefile# должен выполнять действия просто и небеспричинно. Если вы можете сделать что-то на несколько строк короче или более читабельно, сделайте это. В качестве примеров можно привести использование конструкций `.if` утилиты make вместо соответствующей конструкции `if` командного процессора, ненужность переопределения цели `do-extract` при возможности переопределения `EXTRACT*` и использование `GNU_CONFIGURE` вместо `CONFIGURE_ARGS += --prefix=${PREFIX}`. Если вы обнаружите, что для выполнения чего-то приходится писать много нового кода, то, пожалуйста, просмотрите файл [.filename]#bsd.port.mk# на предмет того, не содержит ли он решение именно вашей проблемы. Хотя его трудно читать, имеется много проблем, выглядящих сложными, для которых файл [.filename]#bsd.port.mk# уже содержит быстрое решение. [[dads-cc]] == Работа как с `CC`, так и `CXX` Порт должен принимать во внимание как переменную `CC`, так и `CXX`. Под этим мы подразумеваем, что порт ни в коем случае не должен устанавливать значения этих переменных, переопределяя имеющиеся значения; вместо этого можно добавлять нужные значения к уже имеющимся. Это связано с тем, что параметры построения, относящиеся ко всем портам, могут быть заданы глобально. Если порты не учитывают значения этих переменных, добавьте строку `NO_PACKAGE=ignores either cc or cxx` в файл [.filename]#Makefile#. Далее следует пример файла [.filename]#Makefile#, использующего как переменную `CC`, так и `CXX`. Обратите внимание на использование символов `?=`: [.programlisting] .... CC?= gcc .... [.programlisting] .... CXX?= g++ .... Вот пример, в котором не принимаются во внимание ни `CC`, ни `CXX`: [.programlisting] .... CC= gcc .... [.programlisting] .... CXX= g++ .... В системах FreeBSD обе переменные `CC` и `CXX` могут быть определены в файле [.filename]#/etc/make.conf#. В первом примере задаётся значение, если оно ранее не было определено в [.filename]#/etc/make.conf#, что сохраняет любые определения, данные на уровне системы в целом. Второй пример переопределяет всё, что было задано ранее. [[dads-cflags]] == Использование `CFLAGS` Порт должен учитывать переменную `CFLAGS`. Под этим мы подразумеваем, что порт ни в коем случае не должен устанавливать значения этой переменной, переопределяя имеющиеся значения; вместо этого можно добавлять нужные значения к уже имеющимся. Это связано с тем, что параметры построения, относящиеся ко всем портам, могут быть заданы глобально. Если порты не учитывают значения этой переменной, добавьте строку `NO_PACKAGE=ignores cflags` в файл [.filename]#Makefile#. Далее следует пример файла [.filename]#Makefile#, использующего переменную `CFLAGS`. Обратите внимание на использование символов `+=`: [.programlisting] .... CFLAGS+= -Wall -Werror .... А вот пример, в котором не учитывается значение переменной `CFLAGS`: [.programlisting] .... CFLAGS= -Wall -Werror .... В системе FreeBSD переменная `CFLAGS` определена в файле [.filename]#/etc/make.conf#. В первом примере к переменной `CFLAGS` добавляются дополнительные флаги, при этом сохраняются все определения, данные ранее на уровне системы. Во втором примере всё, что было задано ранее, игнорируется. Из сторонних файлов [.filename]#Makefile# следует удалить флаги оптимизации. Общесистемные флаги оптимизации находятся в системной переменной `CFLAGS`. Пример из немодифицированного [.filename]#Makefile#: [.programlisting] .... CFLAGS= -O3 -funroll-loops -DHAVE_SOUND .... При использовании системных флагов оптимизации [.filename]#Makefile# станет похожим на следующий пример: [.programlisting] .... CFLAGS+= -DHAVE_SOUND .... [[dads-pthread]] == Библиотеки потоков Во FreeBSD библиотека потоков обязана быть скомпонована с исполняемыми файлами с использованием специального флага `-pthread`. Если порт настаивает на прямой компоновке с `-lpthread`, создайте патч для использования `-pthread`. [NOTE] ==== Если построение порта заканчивается ошибкой `unrecognized option '-pthread'`, то может быть желательно использование `cc` в качестве компоновщика через установку `CONFIGURE_ENV` в `LD=${CC}`. Параметр `-pthread` напрямую командой `ld` не поддерживается. ==== [[dads-feedback]] == Пожелания Посылайте подходящие изменения/патчи автору/сопровождающему для включения в следующий релиз. Это только сделает вашу работу гораздо легче при выходе следующего релиза. [[dads-readme]] == [.filename]#README.html# [.filename]#README.html# не является частью порта и генерируется при помощи `make readme`. Не включайте этот файл в патчи или коммиты. [NOTE] ==== Если не удается выполнить `make readme`, убедитесь, что значение по умолчанию `ECHO_MSG` не изменено внутри порта. ==== [[dads-noinstall]] == Пометка неустанавливаемого порта как `BROKEN`, `FORBIDDEN` или `IGNORE` В некоторых случаях пользователи не должны допускаться к установке порта. Для того, чтобы сообщить пользователю, что порт не следует устанавливать, имеется несколько `make`-переменных, которые могут быть использованы в файле [.filename]#Makefile# порта. Значения следующих `make`-переменных будут причиной, возвращаемой пользователям, по которой порт отказывает в установке. Пожалуйста, используйте корректные `make`-переменные, так как каждая переменная make передает абсолютно различный смысл как для пользователей, так и для автоматизированных систем, которые полагаются на файлы [.filename]#Makefile#, таких как <>, <> и <>. [[dads-noinstall-variables]] === Переменные * `BROKEN` предназначена для портов, которые в настоящее время не компилируются, не устанавливаются или не удаляются правильно. Следует использовать, когда проблема считается временной. + В особых случаях кластер построения будет продолжать попытки собрать их, чтобы показать, решена ли основная проблема. (Однако, как правило, кластер запускается без этой возможности.) + В частности, используйте `BROKEN`, когда порт: ** не компилируется ** не выполняет процесс своей конфигурации или установки ** устанавливает файлы вовне [.filename]#${LOCALBASE}# ** не удаляет полностью все свои файлы при деинсталляции (тем не менее, это может быть допустимо, и подходит для портов, оставляющих после себя файлы, измененные пользователем) * `FORBIDDEN` используется для портов, которые содержат уязвимости в информационной безопасности или являются потенциально вредными в плане обеспечения информационной безопасности системы FreeBSD при установке данного порта (например: заведомо небезопасная программа или программа, которая предоставляет легко взламываемые сервисы). Порты должны помечаться как `FORBIDDEN`, как только в конкретном программном обеспечении обнаружилась уязвимость, но обновление выпущено не было. В идеальном случае порты должны обновляться максимально быстро после обнаружения уязвимости, чтобы уменьшить число уязвимых хостов FreeBSD (нам нравится иметь репутацию безопасной системы), однако иногда случается значительный временной разрыв между обнаружением уязвимости и выходом обновлённого релиза уязвимого программного обеспечения. Не помечайте порт как `FORBIDDEN`, если причина не вызвана соображениями информационной безопасности. * `IGNORE` предназначена для портов, которые не должны строиться по какой-либо другой причине. Следует использовать для портов, в случае когда проблема считается структурной. Кластер построения ни при каких условиях не будет строить порты, помеченные как `IGNORE`. В частности, используйте `IGNORE`, когда порт: ** компилируется, но работает неправильно ** не работает на установленной версии FreeBSD ** имеет дистрибутивный файл, который не может быть автоматически извлечен из-за лицензионных ограничений ** не работает с каким-либо другим портом, установленным в настоящее время (например, порт зависит от package:www/apache20[], но установлен package:www/apache22[]) + [NOTE] ==== Если порт будет конфликтовать с уже установленным портом (например, если они устанавливают файл в то же место, но с иным функциональным назначением), то <>. `CONFLICTS` сам установит значение `IGNORE`. ==== * Если порт нужно пометить как `IGNORE` только на некоторых архитектурах, для этого есть две другие удобные переменные, которые автоматически установят для вас значения: `ONLY_FOR_ARCHS` и `NOT_FOR_ARCHS`. Примеры: + [.programlisting] .... ONLY_FOR_ARCHS= i386 amd64 .... + [.programlisting] .... NOT_FOR_ARCHS= ia64 sparc64 .... + Собственное сообщение `IGNORE` можно задать с использованием `ONLY_FOR_ARCHS_REASON` и `NOT_FOR_ARCHS_REASON`. Отдельно для каждой архитектуры это возможно с использованием `ONLY_FOR_ARCHS_REASON_ARCH` и `NOT_FOR_ARCHS_REASON_ARCH`. * Если порт загружает и устанавливает исполняемые файлы i386, то следует установить `IA32_BINARY_PORT`. Если эта переменная установлена, будет выполнена проверка доступности каталога [.filename]#/usr/lib32# для библиотек версии IA32 и поддержки IA32 в ядре. При невыполнении любого из этих условий будет автоматически установлена переменная `IGNORE`. [[dads-noinstall-notes]] === Замечания по реализации Строки не следует брать в кавычки. Также построение строки должно несколько различаться из-за способа отображения информации пользователю. Примеры: [.programlisting] .... BROKEN= fails to link with base -lcrypto .... [.programlisting] .... IGNORE= unsupported on recent versions .... получаемые в результате следующего вывода `make describe`: [.programlisting] .... ===> foobar-0.1 is marked as broken: fails to link with base -lcrypto. .... [.programlisting] .... ===> foobar-0.1 is unsupported on recent versions. .... [[dads-deprecated]] == Пометка порта на удаление с `DEPRECATED` или `EXPIRATION_DATE` Помните, что `BROKEN` и `FORBIDDEN` будут использованы как временное средство, если порт не является работающим. Постоянно неработоспособные порты должны полностью удаляться из дерева. В подходящих ситуациях пользователи могут быть оповещены о предстоящем удалении через переменные `DEPRECATED` и `EXPIRATION_DATE`. Первое - это просто строка, сообщающая причину запланированного удаления порта; вторая является строкой в формате ISO 8601 (YYYY-MM-DD). Обе будут показаны пользователю. Переменную `DEPRECATED` можно установить без использования `EXPIRATION_DATE` (в частности, при рекомендации новой версии порта), но обратный порядок не имеет никакого смысла. Не существует устоявшейся политики, как долго следует продолжать уведомления. Текущая практика дает около месяца для решения проблем безопасности и два месяца для проблем построения. Это также дает немного времени на исправление проблем любым заинтересованным коммиттерам. [[dads-dot-error]] == Избегайте использования конструкции `.error` Правильным способом подать сигнал для [.filename]#Makefile# о том, что порт не может быть установлен из-за какого-то внешнего фактора (например, пользователь указал недопустимую комбинацию опций построения), является установка непустого значения для `IGNORE`. Это значение будет сформатировано и показано пользователю во время `make install`. -Использование для этих целей `.error` является распространенной ошибкой. Проблема в том, что в этой ситуации будут повреждены многие инструменты автоматизации, работающие с деревом портов. Наибольшим образом это распространено при попытке построить [.filename]#/usr/ports/INDEX# (смотрите <>). Тем не менее, даже более простые команды, такие как `make maintainer`, в этом случае также вернут ошибку. Это не является приемлемым. +Использование для этих целей `.error` является распространенной ошибкой. Проблема в том, что в этой ситуации будут повреждены многие инструменты автоматизации, работающие с деревом портов. Наибольшим образом это распространено при попытке построить [.filename]#/usr/ports/INDEX# (смотрите crossref:testing[make-describe, Запуск `make describe`]). Тем не менее, даже более простые команды, такие как `make maintainer`, в этом случае также вернут ошибку. Это не является приемлемым. [[dot-error-breaks-index]] .Как избегать использования `.error` [example] ==== Из следующих двух вариантов строки файла [.filename]#Makefile# первый приведёт к неудачному завершению работы `make index`, а второй - нет: [.programlisting] .... .error "option is not supported" .... [.programlisting] .... IGNORE=option is not supported .... ==== [[dads-sysctl]] == Использование [.filename]#sysctl# Использование [.filename]#sysctl# не рекомендуется, кроме как при выполнении целей. Это вызвано тем, что вычисление любых `makevar`, таких как во время команды `make index`, с необходимостью запуска этой команды, еще больше замедляет весь процесс. man:sysctl[8] следует всегда использовать через переменную `SYSCTL`, поскольку она содержит полностью заданный путь, и при необходимости может быть переопределена. [[dads-rerolling-distfiles]] == Меняющиеся дистрибутивные файлы Иногда авторы программного обеспечения меняют содержимое выпущенных дистрибутивных файлов без смены названия. Вы должны проверять, что изменения являются официальными и произведены автором. В прошлом бывало, что дистрибутивный файл молча изменялся на сайтах загрузки с намерением нанести вред или скомпрометировать безопасность конечного пользователя. Отложите старый файл с дистрибутивом в сторону, загрузите новый, распакуйте его и сравните содержимое при помощи man:diff[1]. Если вы не видите ничего подозрительного, то можете обновить файл [.filename]#distinfo#. Убедитесь, что вы подытожили различия в вашем PR или описании коммита, чтобы другие люди были в курсе, что вы позаботились о том, что ничего плохого не случилось. Возможно вы также захотите связаться с автором этого программного обеспечения для подтверждения изменений. [[dads-avoiding-linuxisms]] == Избегание линуксизмов Не используйте [.filename]#/proc#, если доступны любые другие источники получения информации, например, `setprogname(argv[0])` в `main()` и man:getprogname[3], в случае если вы хотите "знать своё имя". Не полагайтесь на поведение, не регламентированное POSIX. Не выполняйте запись временных меток в критических путях выполнения приложения, если можно обойтись без этого. Получение временных меток может быть медленным, в зависимости от степени точности используемых часов в операционной системе. Если временные метки действительно нужны, определите степень требуемой точности и используйте тот API, в котором документируется получение достаточной точности. Ряд простых системных вызовов (например, man:gettimeofday[2], man:getpid[2]) работают намного быстрее в Linux(R) по сравнению с любой другой операционной системой из-за кеширования и используемой оптимизации vsyscall. Не полагайтесь на их дешевизну в критичных к производительности приложениях. В целом, старайтесь избегать системных вызовов там, где это возможно. Не полагайтесь на специфичное для Linux(R) поведение сокета. В частности, отличаются размеры буфера сокета по умолчанию (выполните вызов man:setsockopt[2] с `SO_SNDBUF` и `SO_RCVBUF`, и в то время как в Linux(R) при заполнении буфера сокета man:send[2] блокируется, FreeBSD возвращает ошибку и устанавливает `ENOBUFS` в качестве значения errno. Если требуется рассчитывать на нестандартное поведение, инкапсулируйте это должным образом в общий для всех API с проверкой поведения на этапе конфигурации, и если требуемое поведение не найдено, прекращайте выполнение. Используйте http://www.freebsd.org/cgi/man.cgi[страницы справочника] для проверки, относится ли функция к интерфейсу POSIX (ищите раздел "STANDARDS" на странице справочника). Не рассчитывайте на то, что в качестве [.filename]#/bin/sh# используется bash. Убедитесь, что командная строка, переданная в man:system[3], будет работать в POSIX-совместимой оболочке. Список основных bash-измов расположен https://wiki.ubuntu.com/DashAsBinSh[здесь]. Проверьте, что используемые заголовочные файлы включены в POSIX или список, рекомендуемый страницей справочника, т.к. например, забыть подключить [.filename]#sys/types.h# - не такая уж проблема в Linux(R), однако это не так во FreeBSD. Компилируйте многопоточные приложения с ключом "-pthread", а не "-lpthread" или как-либо ещё. [[dads-misc]] == Разное Файлы [.filename]#pkg-descr# и [.filename]#pkg-plist# должны проверяться дважды. Если вы пересматриваете порт и думаете, что его можно описать иначе, сделайте это. Пожалуйста, не создавайте дополнительных копий лицензии GNU General Public License в нашей системе. Будьте внимательны с юридическими вопросами! Не делайте из нас нелегальных распространителей ПО! diff --git a/documentation/content/ru/books/porters-handbook/porting-samplem/chapter.adoc b/documentation/content/ru/books/porters-handbook/porting-samplem/_index.adoc similarity index 100% rename from documentation/content/ru/books/porters-handbook/porting-samplem/chapter.adoc rename to documentation/content/ru/books/porters-handbook/porting-samplem/_index.adoc diff --git a/documentation/content/ru/books/porters-handbook/porting-why/chapter.adoc b/documentation/content/ru/books/porters-handbook/porting-why/_index.adoc similarity index 100% rename from documentation/content/ru/books/porters-handbook/porting-why/chapter.adoc rename to documentation/content/ru/books/porters-handbook/porting-why/_index.adoc diff --git a/documentation/content/ru/books/porters-handbook/quick-porting/chapter.adoc b/documentation/content/ru/books/porters-handbook/quick-porting/_index.adoc similarity index 98% rename from documentation/content/ru/books/porters-handbook/quick-porting/chapter.adoc rename to documentation/content/ru/books/porters-handbook/quick-porting/_index.adoc index 87e1275c42..bebfdd67ee 100644 --- a/documentation/content/ru/books/porters-handbook/quick-porting/chapter.adoc +++ b/documentation/content/ru/books/porters-handbook/quick-porting/_index.adoc @@ -1,243 +1,243 @@ --- title: Глава 3. Быстрое портирование prev: books/porters-handbook/new-port next: books/porters-handbook/slow-porting --- [[quick-porting]] = Быстрое портирование :doctype: book :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :sectnumoffset: 3 :partnums: :source-highlighter: rouge :experimental: :images-path: books/porters-handbook/ ifdef::env-beastie[] ifdef::backend-html5[] :imagesdir: ../../../../images/{images-path} endif::[] ifndef::book[] include::shared/authors.adoc[] include::shared/mirrors.adoc[] include::shared/releases.adoc[] include::shared/attributes/attributes-{{% lang %}}.adoc[] include::shared/{{% lang %}}/teams.adoc[] include::shared/{{% lang %}}/mailing-lists.adoc[] include::shared/{{% lang %}}/urls.adoc[] toc::[] endif::[] ifdef::backend-pdf,backend-epub3[] include::../../../../../shared/asciidoctor.adoc[] endif::[] endif::[] ifndef::env-beastie[] toc::[] include::../../../../../shared/asciidoctor.adoc[] endif::[] В этом разделе описано, как создать новый порт на скорую руку. Во многих случаях этого бывает не достаточно, так что вам нужно будет прочитать документ дальше. Во-первых, скачайте оригинальный tar-файл и поместите его в каталог `DISTDIR`, который по умолчанию есть не что иное, как [.filename]#/usr/ports/distfiles#. [NOTE] ==== Здесь предполагается, что программное обеспечение компилируется без проблем как есть, то есть для работы приложения на вашей системе FreeBSD не потребовалось абсолютно никаких изменений. Если требовалось что-то изменить, то вам придется обратиться также и к следующему разделу. ==== [NOTE] ==== Перед началом портирования рекомендуется установить переменную man:make[1] `DEVELOPER` в [.filename]#/etc/make.conf#. [source,shell] .... # echo DEVELOPER=yes >> /etc/make.conf .... Эта настройка включает "режим разработчика", в котором отображаются предупреждения при использовании устаревших конструкций и задействуются некоторые дополнительные проверки при вызове команды `make`. ==== [[porting-makefile]] == Создание файла [.filename]#Makefile# Минимальный [.filename]#Makefile# будет выглядеть примерно так: [.programlisting] .... # $FreeBSD$ PORTNAME= oneko PORTVERSION= 1.1b CATEGORIES= games MASTER_SITES= ftp://ftp.cs.columbia.edu/archives/X11R5/contrib/ MAINTAINER= youremail@example.com COMMENT= Cat chasing a mouse all over the screen .include .... [NOTE] ==== В некоторых случаях в заголовке [.filename]#Makefile# существующего порта могут содержаться дополнительные строки, такие как название порта и дата его создания. Эта дополнительная информация была объявлена устаревшей и находится в процессе удаления. ==== Посмотрим, сможете ли вы его понять. Не обращайте внимание на содержимое строчки `$FreeBSD$`, она будет заполнена автоматически системой Subversion, когда порт будет импортирован в наше дерево портов. Вы можете найти более подробный пример в разделе <>. [[porting-desc]] == Создание информационных файлов Имеется два информационных файла, которые требуются для любого порта, вне зависимости от того, является ли он пакетом или нет. Это [.filename]#pkg-descr# и [.filename]#pkg-plist#. Префикс [.filename]#pkg-# отличает их от других файлов. === [.filename]#pkg-descr# Это более подробное краткое описание порта. От одного до нескольких абзацев, кратко описывающих, что представляет собой порт, будет достаточно. [NOTE] ==== Это _не_ руководство и не подробнейшее описание того, как использовать или компилировать порт! _Пожалуйста, будьте внимательны при копировании текста из [.filename]#README# или страниц справочника_; слишком часто они не являются кратким описанием порта или имеют неудобный формат (например, страницы справочника выровнены пробелами, что особенно плохо смотрится с моноширинными шрифтами). ==== Хорошо составленный [.filename]#pkg-descr# описывает порт достаточно полно, чтобы пользователю не приходилось сверяться с документацией или посещать вебсайт для понимания того, что делает данное программное обеспечение, чем оно может быть полезно или какие хорошие функции у него имеются. Упоминание про определённые требования, такие как используемый графический инструментарий, тяжёлые зависимости, окружение для запуска или используемый язык программирования помогут пользователям определиться, будет ли этот порт для них работать. Включите сюда URL официальной домашней страницы Интернет. Перед _одним_ из сайтов (выберите основной) добавьте `WWW:` (с последующим единичным пробелом) для того, чтобы вспомогательные утилиты работали правильно. Если URI является корнем сайта или каталогом, то значение должно быть дополнено косой чертой. [NOTE] ==== Если указанная для порта веб-страница не доступна, попытайтесь сперва поискать, был ли официальный сайт перемещён, переименован или размещён в другом месте. ==== Следующий пример показывает, как должен выглядеть ваш [.filename]#pkg-descr#: [.programlisting] .... This is a port of oneko, in which a cat chases a poor mouse all over the screen. : (etc.) WWW: http://www.oneko.org/ .... === [.filename]#pkg-plist# Здесь перечисляются все файлы, устанавливаемые портом. Его также называют "списком для упаковки", потому что пакет генерируется упаковкой файлов, которые здесь указаны. Имена путей указываются относительно установочного префикса (обычно [.filename]#/usr/local#). Если порт во время установки создает каталоги, убедитесь, что добавлены строки `@dirrm` для удаления каталогов при удалении пакета. Вот маленький пример: [.programlisting] .... bin/oneko man/man1/oneko.1.gz lib/X11/app-defaults/Oneko lib/X11/oneko/cat1.xpm lib/X11/oneko/cat2.xpm lib/X11/oneko/mouse.xpm @dirrm lib/X11/oneko .... Обратитесь к странице справочной системы по команде man:pkg-create[8] с подробным описанием формата списка упаковки. [NOTE] ==== Рекомендуется, чтобы имена файлов в этом списке были отсортированы в алфавитном порядке. Это позволит значительно облегчить сверку изменений при обновлении порта. ==== [NOTE] ==== Создание списка упаковки вручную может оказаться весьма трудоёмкой задачей. Если порт устанавливает большое количество файлов, раздел об <> может помочь сэкономить время. ==== Существует только одно исключение, когда у порта может отсутствовать [.filename]#pkg-plist#. Если порт устанавливает лишь несколько файлов, а возможно, и каталогов, то они могут быть перечислены в переменных `PLIST_FILES` и `PLIST_DIRS`, соответственно, внутри файла [.filename]#Makefile# порта. К примеру, мы можем обойтись без файла [.filename]#pkg-plist# у приведённого выше порта [.filename]#oneko#, добавив следующие строки в [.filename]#Makefile#: [.programlisting] .... PLIST_FILES= bin/oneko \ man/man1/oneko.1.gz \ lib/X11/app-defaults/Oneko \ lib/X11/oneko/cat1.xpm \ lib/X11/oneko/cat2.xpm \ lib/X11/oneko/mouse.xpm PLIST_DIRS= lib/X11/oneko .... Конечно, переменная `PLIST_DIRS` не должна задаваться, если порт не устанавливает никаких каталогов. [NOTE] ==== -Несколько портов могут совместно использовать общий каталог. В этом случае `PLIST_DIRS` следует заменить на `PLIST_DIRSTRY`, так чтобы каталог удалялся только если он пуст, а иначе игнорировался. Использование `PLIST_DIRS` и `PLIST_DIRSTRY` аналогично `@dirrm` и `@dirrmtry` в [.filename]#pkg-plist#, описание которых входит в <>. +Несколько портов могут совместно использовать общий каталог. В этом случае `PLIST_DIRS` следует заменить на `PLIST_DIRSTRY`, так чтобы каталог удалялся только если он пуст, а иначе игнорировался. Использование `PLIST_DIRS` и `PLIST_DIRSTRY` аналогично `@dirrm` и `@dirrmtry` в [.filename]#pkg-plist#, описание которых входит в crossref:plist[plist-dir-cleaning,Очистка пустых каталогов]. ==== Обратной стороной такого способа перечисления файлов и каталогов порта является невозможность использования последовательностей команд, описанных в man:pkg-create[8]. Поэтому он подходит для простых портов, что делает их ещё более простыми. Одновременно с этим положительным моментом является уменьшение количества файлов в коллекции портов. Пожалуйста, подумайте над использованием этой техники, прежде чем создавать [.filename]#pkg-plist#. -Далее мы увидим, как можно использовать файлы [.filename]#pkg-plist# и `PLIST_FILES` выполнения <>. +Далее мы увидим, как можно использовать файлы [.filename]#pkg-plist# и `PLIST_FILES` выполнения crossref:plist[plist,более сложных задач]. [[porting-checksum]] == Создание файла с контрольной суммой Просто введите команду `make makesum`. Правила утилиты make автоматически сгенерируют файл [.filename]#distinfo#. Если у извлекаемого файла регулярно меняется контрольная сумма и вы не сомневаетесь в надежности источника (т.е. он получен из CD производителя, либо ежедневно обновляется документация), то вы должны указать эти файлы в переменной `IGNOREFILES`. Тогда контрольная сумма при выполнении `make makesum` для этого файла создаваться не будет, а вместо этого для него будет установлено значение `IGNORE`. [[porting-testing]] == Тестирование порта Вы должны удостовериться, что правила построения порта выполняют именно то, что вы хотите, включая создание пакета для порта. Вот те важные вещи, которые вы должны проверить. * [.filename]#pkg-plist# не содержит ничего сверх того, что устанавливается портом * [.filename]#pkg-plist# содержит абсолютно все, что устанавливается портом * Порт может быть установлен с помощью указания цели `install`. Это позволяет убедиться в правильной работе сценария установки. * Порт может быть правильным образом удалён с помощью указания цели `deinstall`. Это позволяет убедиться в правильной работе сценария удаления. * Следует убедиться, что `make package` можно запустить из-под обычного пользователя (то есть, не из-под `root`). Если это не так, в [.filename]#Makefile# порта должно быть добавлено `NEED_ROOT=yes`. [.procedure] ==== *Procedure: Рекомендуемый порядок проверки* . `make stage` . `make check-orphans` . `make package` . `make install` . `make deinstall` . `pkg add package-filename` . `make package` (из-под пользователя) ==== Убедитесь, что на любом из этапов не выдается никаких предупреждений. Основательное автоматизированное тестирование может быть выполнено при помощи package:ports-mgmt/tinderbox[] или package:ports-mgmt/poudriere[] из Коллекции Портов. Эти приложения используют `jails`, в которых проверяются все перечисленные выше этапы без изменения состояния основной системы. [[porting-portlint]] == Проверка вашего порта утилитой `portlint` Будьте добры, пользуйтесь утилитой `portlint` для проверки того, что ваш порт соответствует нашим рекомендациям. Программа package:ports-mgmt/portlint[] является частью Коллекции Портов. В частности, вы можете захотеть проверить, правильно ли сформирован файл <> и соответствующим ли образом именован <>. [[porting-submitting]] == Посылка нового порта -Перед посылкой нового порта прочитайте раздел о том, что <> делать. +Перед посылкой нового порта прочитайте раздел о том, что crossref:porting-dads[porting-dads,можно и нельзя] делать. Когда вы наконец довольны своим первым портом, единственное, что осталось сделать, это включить его в основное дерево портов FreeBSD и осчастливить этим всех остальных. Нам не нужен ни каталог [.filename]#work#, ни пакет [.filename]#pkgname.tgz#, так что удалите их прямо сейчас. Затем получите файл man:shar[1]. Предполагая, что порт называется oneko, перейдите в каталог выше, где находится каталог `oneko`, и наберите: `shar find oneko > oneko.shar` Включите [.filename]#oneko.shar# в сообщение об ошибке и пошлите его с помощью man:send-pr[1]. Обратитесь к разделу extref:{contributing}[Сообщения об ошибках и общие замечания, CONTRIB-GENERAL] для получения подробной информации о man:send-pr[1]). Укажите в сообщении категорию `ports` и класс `change-request`. _Не_ указывайте, что сообщение имеет статус `confidential`! Добавьте краткое описание программы в поле "Description" отправляемого PR (например, содержимое `COMMENT` в сокращённом варианте) и сам файл в виде архива [.filename]#.shar# в поле "Fix". [NOTE] ==== Хорошее описание в заголовке сообщения о проблеме значительно облегчает работу коммиттеров портов. Для новых портов мы предпочитаем нечто вроде "New port: <категория>/<название порта> <краткое описание порта>". Следование этой схеме упрощает и ускоряет начало работы по добавлению нового порта. ==== Повторим ещё раз, что __не нужно включать ни оригинальный файл с дистрибутивом, ни каталог [.filename]#work#, ни пакет, построенный вами командой ``make package``__; для новых портов используйте man:shar[1], но не man:diff[1]. После отправки порта, пожалуйста, потерпите. Время, необходимое для включения нового порта во FreeBSD, может занимать от нескольких дней до нескольких месяцев. http://www.FreeBSD.org/cgi/query-pr-summary.cgi?category=ports[ Здесь] можно увидеть список ожидающих PR для портов. После рассмотрения нового порта мы при необходимости вам ответим, а затем включим порт в наше дерево. Ваше имя также будет добавлено в список extref:{contributors}[Дополнительных контрибуторов проекта FreeBSD, contrib-additional] и другие файлы. diff --git a/documentation/content/ru/books/porters-handbook/security/chapter.adoc b/documentation/content/ru/books/porters-handbook/security/_index.adoc similarity index 100% rename from documentation/content/ru/books/porters-handbook/security/chapter.adoc rename to documentation/content/ru/books/porters-handbook/security/_index.adoc diff --git a/documentation/content/ru/books/porters-handbook/slow-porting/chapter.adoc b/documentation/content/ru/books/porters-handbook/slow-porting/_index.adoc similarity index 99% rename from documentation/content/ru/books/porters-handbook/slow-porting/chapter.adoc rename to documentation/content/ru/books/porters-handbook/slow-porting/_index.adoc index 1d7cbc61e7..2cadd40028 100644 --- a/documentation/content/ru/books/porters-handbook/slow-porting/chapter.adoc +++ b/documentation/content/ru/books/porters-handbook/slow-porting/_index.adoc @@ -1,197 +1,197 @@ --- title: Глава 4. Медленное портирование prev: books/porters-handbook/quick-porting next: books/porters-handbook/makefiles --- [[slow-porting]] = Медленное портирование :doctype: book :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :sectnumoffset: 4 :partnums: :source-highlighter: rouge :experimental: :images-path: books/porters-handbook/ ifdef::env-beastie[] ifdef::backend-html5[] :imagesdir: ../../../../images/{images-path} endif::[] ifndef::book[] include::shared/authors.adoc[] include::shared/mirrors.adoc[] include::shared/releases.adoc[] include::shared/attributes/attributes-{{% lang %}}.adoc[] include::shared/{{% lang %}}/teams.adoc[] include::shared/{{% lang %}}/mailing-lists.adoc[] include::shared/{{% lang %}}/urls.adoc[] toc::[] endif::[] ifdef::backend-pdf,backend-epub3[] include::../../../../../shared/asciidoctor.adoc[] endif::[] endif::[] ifndef::env-beastie[] toc::[] include::../../../../../shared/asciidoctor.adoc[] endif::[] Итак, все оказалось не так уж и просто, и порт потребовал некоторых модификаций для того, чтобы заставить его работать. В этом разделе мы расскажем, шаг за шагом, как его модифицировать, чтобы он работал с нашей системой портов. [[slow-work]] == Как всё это работает Во-первых, когда пользователь дает в своем каталоге с портом команду `make`, происходит целая череда событий. Во время чтения этого текста может оказаться полезным иметь файл [.filename]#bsd.port.mk# открытым в другом окне, что сильно поможет в их понимании. Но не волнуйтесь сильно, если вы не до конца понимаете, что делается в [.filename]#bsd.port.mk#, не так уж много людей его понимает... _:->_ [.procedure] ==== . Запускается цель `fetch`. Цель `fetch` отвечает за то, что архив исходных текстов имеется в наличии локально в каталоге `DISTDIR`. Если цель `fetch` не может найти требуемые файлы в каталоге `DISTDIR`, то они будут искаться по указателю URL `MASTER_SITES`, который устанавливается в Makefile, а также на наших FTP зеркалах, куда мы по возможности помещаем дистрибутивные файлы для архива. Затем она попытается сгрузить указанный файл с помощью `FETCH`, полагая, что запрашивающая машина имеет прямое подключение к Интернет. Если файл скачается удачно, то он будет помещен в каталог `DISTDIR` для последующего использования и обработки. . Выполняется цель `extract`. Она ищет дистрибутивный файл порта (как правило, tar-архив `gzip`) в каталоге `DISTDIR` и распаковывает его во временный каталог, задаваемый переменной `WRKDIR` (по умолчанию [.filename]#work#). . Выполняется цель `patch`. Во-первых, применяются все патчи, заданные переменной `PATCHFILES`. Во-вторых, если какие-либо файлы с патчами, носящие имена [.filename]#patch-*#, имеются в подкаталоге `PATCHDIR` (по умолчанию это каталог [.filename]#files#), то они применяются в этот момент в алфавитном порядке. . Запускается цель `configure`. Здесь может выполняться любая из многих различных вещей. .. Если существует скрипт [.filename]#scripts/configure#, то он запускается. .. Если задана переменная `HAS_CONFIGURE` или `GNU_CONFIGURE`, то запускается скрипт [.filename]#WRKSRC/configure#. . Выполняется цель `build`. Она отвечает за переход в собственный рабочий каталог порта (`WRKSRC`) и его построение. -. Выполняется цель `stage`. Конечный набор построенных файлов помещается во временный каталог (`STAGEDIR`, смотрите <>). Иерархия этого каталога отражает иерархию каталогов системы, в которую данный пакет будет устанавливаться. +. Выполняется цель `stage`. Конечный набор построенных файлов помещается во временный каталог (`STAGEDIR`, смотрите crossref:special[staging,Staging]). Иерархия этого каталога отражает иерархию каталогов системы, в которую данный пакет будет устанавливаться. . Выполняется цель `install`. В систему копируются файлы, перечисленные в pkg-plist порта. ==== Выше перечислены стандартные действия. Кроме того, вы сами можете определить цели `pre-_что-то_` или `post-_что-то_`, или создать скрипты с такими именами в подкаталоге [.filename]#scripts#, и они будут запущены до или после выполнения действий по умолчанию. Например, если у вас есть цель `post-extract`, определённая в вашем файле [.filename]#Makefile# и файл [.filename]#pre-build# в подкаталоге [.filename]#scripts#, то после выполнения обычных действий по распаковке, будет вызвана цель `post-extract` а скрипт [.filename]#pre-build# будет выполнен перед запуском стандартных правил построения. Рекомендуется использовать цели из [.filename]#Makefile#, если действия достаточно просты, потому что в дальнейшем будет проще определить, какие нестандартные действия требует порт. Действия по умолчанию выполняются целями `do-_что-то_` из [.filename]#bsd.port.mk#. Например, команды для распаковки порта находятся в цели `do-extract`. Если вам не хватает цели по умолчанию, вы можете ее исправить, переопределив цель `do-_something_` в вашем файле [.filename]#Makefile#. [NOTE] ==== "Основные" цели (к примеру, `extract`, `configure` и так далее) не делают ничего больше, чем проверяют успешность завершения всех предыдущих шагов и вызывают настоящие цели или скрипты, и их не нужно менять. Если вам нужно изменить распаковку, исправляйте `do-extract`, но никогда не меняйте способ работы `extract`! Кроме того, цель `post-deinstall` является недействительной и не выполняется инфраструктурой портов. ==== Теперь, когда вы представляете, что происходит, когда пользователь набирает команду `make install`, давайте пройдемся через шаги, рекомендуемые для создания настоящего порта. [[slow-sources]] == Получение исходного кода Получите оригинальные исходные тексты (обычно) в виде упакованного tar-архива ([.filename]#foo.tar.gz# или [.filename]#foo.tar.bz2#) и скопируйте его в каталог `DISTDIR`. Всегда используйте исходные тексты _основной ветки разработки_ везде, где это возможно. Вам потребуется задать значение переменной `MASTER_SITES` так, чтобы оно указывало на местоположение оригинального tar-архива. В файле [.filename]#bsd.sites.mk# вы найдёте краткие обозначения для большинства популярных сайтов. Пожалуйста, используйте эти сайты-и соответствующие определения-везде, где это возможно, чтобы избежать проблем повторения одной и той же информации в базе источников. Так как эти сайты со временем меняются, для всех причастных поддержка становится настоящим кошмаром. Если вы не можете найти FTP/HTTP сайт с хорошим подключением к сети, или находите только сайты, которые имеют раздражающе нестандартные форматы, то можете захотеть поместить копию на надежный сервер FTP или HTTP, который вам доступен (например, ваша домашняя страница). Если вы не можете найти доступного и надёжного места для помещения дистрибутивного файла, то мы сами сможем разместить его на сервере `ftp.FreeBSD.org`; однако это наименее рекомендуемое решение. Дистрибутивный файл должен быть помещён в каталог [.filename]#~/public_distfiles/# одного из пользователей машины `freefall`. Попросите того, кто коммиттил ваш порт, сделать это. Этот человек также задаст переменной `MASTER_SITES` значение `MASTER_SITE_LOCAL`, а в переменной `MASTER_SITE_SUBDIR` укажет своё имя пользователя с машины `freefall`. Если дистрибутивные файлы вашего порта постоянно меняются по неизвестным причинам без изменения версий со стороны автора, остаётся только поместить дистрибутив на вашу домашнюю Web-страницу и указать её первой в списке `MASTER_SITES`. Если можете, попытайтесь договориться с автором порта об этом; это действительно помогает в достижении некоторого управления исходным кодом. Размещение собственной версии поможет избежать появления ошибок у пользователей типа `checksum mismatch`, а также уменьшит нагрузку на людей, сопровождающих наш FTP-сервер. Также, если у порта имеется только один основной сервер, то рекомендуется поместить архивную копию на свой сайт и указать его в списке `MASTER_SITES` вторым. Если вашему порту требуются дополнительные `патчи`, доступные в Интернет, скачайте также и их, поместив в каталог `DISTDIR`. Не волнуйтесь, если они находятся не на том же сайте, откуда взят дистрибутивный архив, мы умеем обрабатывать такие ситуации (смотрите описание <> ниже). [[slow-modifying]] == Модификация порта Распакуйте копию дистрибутивного файла в отдельный каталог и внесите изменения, которые необходимы для того, чтобы порт компилировался нормально в текущей версии FreeBSD. _Тщательно отслеживайте_ все, что вы делаете, этот процесс вам предстоит автоматизировать. Все, включая удаление, добавление или модификацию в файлах должны будут выполняться автоматически с помощью скриптов или файлов патчей, когда вы завершите работу над портом. Если вашему порту во время компиляции, установки и настройки требуется довольно много взаимодействовать с пользователем, то посмотрите на один из классических скриптов Configure Лэрри Уолла (Larry Wall) и сделайте сами что-либо подобное. Предназначение новой коллекции портов - это сделать каждое приложение в стиле "plug-and-play" настолько, насколько это вообще возможно для конечного пользователя при минимальном использовании дискового пространства. [NOTE] ==== Если явно не указано обратное, то патчи, скрипты и другие файлы, которые вы создали и предоставили для Коллекции Портов FreeBSD, неявно подпадают под стандартные условия лицензии BSD. ==== [[slow-patch]] == Создание патчей Файлы, которые добавлялись или изменялись в процессе создания порта, могут быть выявлены программой man:diff[1], а результат работы этой программы может быть в дальнейшем передан программе man:patch[1]. Такое действие с обычным файлом подразумевает сохранение копии файла с первоначальным содержимым перед внесением каких-либо изменений. [source,shell] .... % cp file file.orig .... Патчи сохраняются в виде файлов с именем [.filename]#patch-*#, где _*_ обозначает путь к файлу, к которому применяется патч, такой как [.filename]#patch-Imakefile# или [.filename]#patch-src-config.h#. После того как файл был изменён, используется man:diff[1] для получения разницы между первоначальной и изменённой версиями. Параметр `-u` указывает man:diff[1] выводить разницу в "унифицированном" формате, который также является предпочтительным. [source,shell] .... % diff -u file.orig file > patch-pathname-file .... Для порождении патчей для новых добавляемых файлов используется параметр `-N`, который заставляет man:diff[1] трактовать несуществующие прежде файлы как если бы они существовали, но имели пустое содержимое: [source,shell] .... % diff -u -N newfile.orig newfile > patch-pathname-newfile .... Файлы с патчами помещаются в каталоге `PATCHDIR` (как правило, это [.filename]#files/#), откуда они будут взяты автоматически. Все патчи обязаны быть сделаны относительно каталога `WRKSRC` (как правило, это каталог, в который распаковывается исходный архив и где будет выполняться построение). Для упрощения внесения изменений и обновлений избегайте наличия более чем одного патча для одного и того же файла (например, патчей [.filename]#patch-file# и [.filename]#patch-file2#, оба меняющих файл [.filename]#WRKSRC/foobar.c#). Обратите внимание, что если путь к изменяемому файлу содержит символ подчеркивания (`_`), то патч должен содержать в своем имени два подчеркивания вместо одного. Например, для применения патча на файл с именем [.filename]#src/freeglut_joystick.c# соответствующий патч следует назвать [.filename]#patch-src-freeglut__joystick.c#. Пожалуйста, используйте для именования патчей только символы `[-+._a-zA-Z0-9]`. Не используйте любые другие символы, кроме этих. Не называйте патчи как [.filename]#patch-aa# или [.filename]#patch-ab#, всегда ссылайтесь на путь и название файла в названиях самих патчей. Существует альтернативный упрощённый способ создания патчей для существующих файлов. Первые шаги те же самые: создание копии неизменённого файла с расширением [.filename]#.orig# и внесение изменений. После этого используйте `make makepatch`, чтобы обновить файлы с патчами в каталоге [.filename]#files# данного порта. Не помещайте строки RCS в патчи. Subversion будет изменять их при помещении файлов в дерево портов, и когда мы будем их оттуда извлекать, они будут уже другие, поэтому применение патчей окончится неудачей. Строчки RCS предваряются знаком доллара (`$`), и обычно начинаются с `$Id` или `$RCS`. Использование параметра рекурсии (`-r`) с командой man:diff[1] для генерации патчей - это хорошо, но всё же, пожалуйста, смотрите на получающиеся патчи, чтобы убедиться в отсутствии ненужного мусора. В частности, diff-разниц между двумя резервными копиями файлов, файлы [.filename]#Makefile#, когда как порт использует `Imake` или GNU-версию программы `configure`, и так далее, не нужны, и должны быть удалены. Если было необходимо отредактировать файл [.filename]#configure.in# и запустить `autoconf` для перегенерации `configure`, не нужно включать файлы diff для `configure` (они частенько вырастают до нескольких тысяч строк!). Вместо этого задайте `USE_AUTOTOOLS=autoconf:261` и включите diff-файл для [.filename]#configure.in#. Старайтесь минимизировать в патчах объём нефункциональных изменений с пустыми символами. В мире Открытого Исходного Кода является распространенным совместное использование проектами больших объемов кодовой базы, но с различными стилями и правилами отступов. При копировании работающей функциональной части из одного проекта для исправления похожей области в другом, будьте аккуратны, пожалуйста: получаемый однострочный патч может указаться полон нефункциональных изменений. Это не только увеличивает размер репозитория Subversion, но также усложняет поиск того, что конкретно вызвало проблему и что вообще поменялось. Если нужно удалить файл, сделайте это при выполнении цели `post-extract`, вместо того чтобы оформлять это как часть патча. Простые перемещения могут быть выполнены непосредственно из [.filename]#Makefile# порта с использованием man:sed[1] в режиме in-place. Это удобно, когда при изменении используется значение переменной: [.programlisting] .... post-patch: @${REINPLACE_CMD} -e 's|for Linux|for FreeBSD|g' ${WRKSRC}/README .... Довольно часто в исходных файлах портируемого программного обеспечения используется конвенция CR/LF. Это может стать причиной проблем с дальнейшей упаковкой, предупреждениями компилятора или выполнением скриптов (таких как `/bin/sh^M not found`). Для быстрого преобразования всех файлов из CR/LF просто в LF добавьте в [.filename]#Makefile# порта эту запись: [.programlisting] .... USES= dos2unix .... Может быть задан точный список преобразуемых файлов: [.programlisting] .... USES= dos2unix DOS2UNIX_FILES= util.c util.h .... Используйте `DOS2UNIX_REGEX`, чтобы преобразовать группу файлов в разных подкаталогах. Его параметром является регулярное выражение, совместимое с man:find[1]. Подробнее о формате в man:re_format[7]. Такой вариант удобен для преобразования всех файлов заданного расширения. Для примера, преобразуем все исходные файлы, не затрагивая двоичные файлы: [.programlisting] .... USES= dos2unix DOS2UNIX_REGEX= .*\.([ch]|cpp) .... Другим вариантом является использование `DOS2UNIX_GLOB`, который вызывает `find` для каждого из перечисленных в нём элементов. [.programlisting] .... USES= dos2unix DOS2UNIX_GLOB= *.c *.cpp *.h .... [[slow-configure]] == Конфигурирование Поместите все дополнительные команды, требуемые для настройки, в ваш скрипт [.filename]#configure# и сохраните его в подкаталоге [.filename]#scripts#. Как отмечено выше, вы можете сделать это целями в файле [.filename]#Makefile# и/или скриптами с именами [.filename]#pre-configure# или [.filename]#post-configure#. [[slow-user-input]] == Обработка пользовательского ввода Если для построения, конфигурации или установки вашего порта требуется некоторый ввод со стороны пользователя, то вы должны задать переменную `IS_INTERACTIVE` в вашем файле [.filename]#Makefile#. В случае "ночного построения" это позволит пропустить ваш порт, если пользователь в своем окружении задал переменную `BATCH` (и если пользователь установил переменную `INTERACTIVE`, то будут строиться _только_ порты, которые требуют взаимодействия с пользователем. Это сэкономит значительное количество времени на части машин, которые постоянно строят порты (смотрите ниже). При наличии разумных ответов на задаваемые вопросы, подходящих по умолчанию, также рекомендуется проверять переменную `PACKAGE_BUILDING` и выключать интерактивный скрипт, если он есть. Это позволит нам строить пакеты для помещения на компакт-диски и FTP-серверы. diff --git a/documentation/content/ru/books/porters-handbook/special/chapter.adoc b/documentation/content/ru/books/porters-handbook/special/_index.adoc similarity index 99% rename from documentation/content/ru/books/porters-handbook/special/chapter.adoc rename to documentation/content/ru/books/porters-handbook/special/_index.adoc index c46eb9a002..ac01c34875 100644 --- a/documentation/content/ru/books/porters-handbook/special/chapter.adoc +++ b/documentation/content/ru/books/porters-handbook/special/_index.adoc @@ -1,2531 +1,2531 @@ --- title: Глава 6. Особые соглашения prev: books/porters-handbook/makefiles next: books/porters-handbook/plist --- [[special]] = Особые соглашения :doctype: book :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :sectnumoffset: 6 :partnums: :source-highlighter: rouge :experimental: :images-path: books/porters-handbook/ ifdef::env-beastie[] ifdef::backend-html5[] :imagesdir: ../../../../images/{images-path} endif::[] ifndef::book[] include::shared/authors.adoc[] include::shared/mirrors.adoc[] include::shared/releases.adoc[] include::shared/attributes/attributes-{{% lang %}}.adoc[] include::shared/{{% lang %}}/teams.adoc[] include::shared/{{% lang %}}/mailing-lists.adoc[] include::shared/{{% lang %}}/urls.adoc[] toc::[] endif::[] ifdef::backend-pdf,backend-epub3[] include::../../../../../shared/asciidoctor.adoc[] endif::[] endif::[] ifndef::env-beastie[] toc::[] include::../../../../../shared/asciidoctor.adoc[] endif::[] Имеется ещё несколько вещей, которые вы должны иметь в виду при создании порта. Этот раздел описывает наиболее часто встречающиеся из них. [[staging]] == Staging -[.filename]#bsd.port.mk# ожидает от портов работу с "каталогом сборки". Это означает, что порт должен устанавливать файлы не напрямую в назначенные каталоги (то есть, например, под `PREFIX`), а в отдельный каталог, из которого затем собирается пакет. Во многих случаях привилегии root для этого не требуются, что делает возможным сборку пакетов из-под непривилегированного пользователя. В режиме staging порт собирается и устанавливается в каталог сборки `STAGEDIR`. Пакет создается из каталога сборки и затем устанавливается в систему. В инструментарии automake такая концепция именуется `DESTDIR`; в прочем, в FreeBSD `DESTDIR` имеет собственное значение (смотрите <>). +[.filename]#bsd.port.mk# ожидает от портов работу с "каталогом сборки". Это означает, что порт должен устанавливать файлы не напрямую в назначенные каталоги (то есть, например, под `PREFIX`), а в отдельный каталог, из которого затем собирается пакет. Во многих случаях привилегии root для этого не требуются, что делает возможным сборку пакетов из-под непривилегированного пользователя. В режиме staging порт собирается и устанавливается в каталог сборки `STAGEDIR`. Пакет создается из каталога сборки и затем устанавливается в систему. В инструментарии automake такая концепция именуется `DESTDIR`; в прочем, в FreeBSD `DESTDIR` имеет собственное значение (смотрите crossref:testing[porting-prefix, `PREFIX` и `DESTDIR`]). Если для порта всё ещё требуются системные привилегии при выполнении цели `package`, то в [.filename]#Makefile# должна быть добавлена следующая строка: [.programlisting] .... NEED_ROOT= yes .... Метапорты, то есть порты, которые не устанавливают файлы непосредственно, а только зависят от других портов, должны по возможности избегать распаковки man:mtree[8] в каталог сборки. Это основная иерархия каталогов пакета, и эти пустые каталоги будут выглядеть лишними. Для предотвращения распаковки man:mtree[8] добавьте эту строку: [.programlisting] .... NO_MTREE= yes .... Staging задействуется посредством добавления переменной `STAGEDIR` слева от путей, которые используются в целях `pre-install`, `do-install` и `post-install` (смотрите примеры в книге). Обычно сюда относятся `PREFIX`, `ETCDIR`, `DATADIR`, `EXAMPLESDIR`, `MANPREFIX`, `DOCSDIR` и так далее. Каталоги должны создаваться при выполнении цели `post-install`. Избегайте использования абсолютных путей, когда это возможно. При создании символический ссылки `STAGEDIR` должен ставиться только для пути назначения. Например: [.programlisting] .... ${LN} -sf libfoo.so.42 ${STAGEDIR}${PREFIX}/lib/libfoo.so .... Первоначальный путь [.filename]#${PREFIX}/lib/libfoo.so.42# выглядит нормально, но по факту может быть неправильным. Абсолютные пути могут указывать на неподходящее место, например, когда удалённая файловая система смонтирована по NFS как непривилегированная точка монтирования. Относительные пути реже подвержены проблемам и часто намного короче. Порты, устанавливающие модули ядра, должны предварять путь установки (по умолчанию [.filename]#/boot/modules#) переменной `STAGEDIR`. [[porting-shlibs]] == Динамические библиотеки Если ваш порт устанавливает одну или несколько динамических библиотек, определите переменную `USE_LDCONFIG`, которая приведёт к запуску из [.filename]#bsd.port.mk# команды `${LDCONFIG} -m` относительно каталога, в который устанавливается новая библиотека (как правило, это [.filename]#PREFIX/lib#), во время выполнения цели `post-install` для её регистрации в кэше динамических библиотек. Эта переменная, если она определена, также приведёт к добавлению соответствующей пары команд `@exec /sbin/ldconfig -m` и `@unexec /sbin/ldconfig -R` в ваш файл [.filename]#pkg-plist#, так что пользователь, устанавливающий пакет, сможет сразу же использовать динамическую библиотеку, а удаление пакета не приведёт к тому, что система будет предполагать, что библиотека всё ещё имеется в наличии. [.programlisting] .... USE_LDCONFIG= yes .... Если нужно, вы можете переопределить каталог по умолчанию, задав значение `USE_LDCONFIG`, в котором должны быть перечислены каталоги, в которые устанавливаются динамические библиотеки. Например, если ваш порт устанавливает динамические библиотеки в каталоги [.filename]#PREFIX/lib/foo# и [.filename]#PREFIX/lib/bar#, то вы можете в файле [.filename]#Makefile# указать следующее: [.programlisting] .... USE_LDCONFIG= ${PREFIX}/lib/foo ${PREFIX}/lib/bar .... Будьте добры перепроверить, т.к. часто это вовсе не является необходимым и может быть решено иначе с помощью `-rpath` или установки `LD_RUN_PATH` во время компоновки (для примера смотрите package:lang/moscow_ml[]), или с помощью сценария-обёртки, который выставляет `LD_LIBRARY_PATH` перед запуском исполняемого файла как это делает package:www/seamonkey[]. При установке 32-разрядных библиотек на 64-разрядной системе используйте вместо этого `USE_LDCONFIG32`. Постарайтесь сохранять номера версий динамических библиотек в формате [.filename]#libfoo.so.0#. Наш компоновщик позаботится только о старшем (первом) номере. Если при обновлении порта увеличивается старший номер версии библиотеки, то для всех портов, компонуемых с затронутой библиотекой, следует увеличить значение `PORTREVISION` для форсирования перекомпиляции с новой версией библиотеки. [[porting-restrictions]] == Порты с ограничениями на распространение или с правовым обременением Лицензии бывают разных видов, и некоторые накладывают ограничение на то, как приложение может быть оформлено в виде пакета, может ли оно продаваться для извлечения коммерческой выгоды, и так далее. [IMPORTANT] ==== На вас, как на человека, портирующего приложение, ложится обязанность прочесть лицензионные соглашения на программное обеспечение и удостовериться, что проект FreeBSD не будет являться их нарушителем, если будет заниматься распространением исходного кода или в бинарном виде по FTP/HTTP или на CD-ROM. Если у вас возникли сомнения, то, пожалуйста, обратитесь в {freebsd-ports}. ==== В подобных ситуациях можно использовать переменные, описываемые в последующих разделах. === `NO_PACKAGE` Эта переменная указывает, что мы не можем создавать для приложения двоичный пакет. К примеру, лицензия не позволяет бинарное распространение или она может запрещать распространение пакетов, созданных из изменённых исходников. Однако файлы `DISTFILES` могут свободно зеркалироваться по FTP/HTTP. Они также могут распространяться, используя CD-ROM (или на похожих носителях), если не установлена переменная `NO_CDROM`. `NO_PACKAGE` должна также использоваться, если двоичный пакет, как правило, бесполезен, а приложение должно всегда компилироваться из исходного кода. К примеру, если в приложение во время компиляции жёстко включается конфигурационная информация, привязанная к конкретной системе, то задайте переменную `NO_PACKAGE`. Значением переменной `NO_PACKAGE` должна быть строка, описывающая причину, по которой пакет не должен создаваться. === `NO_CDROM` Эта переменная указывает на то, что, хотя мы имеем право создавать бинарные пакеты, мы не можем помещать эти пакеты или файлы `DISTFILES` порта на CD-ROM (или на похожие носители) для перепродажи. Однако бинарные пакеты и файлы `DISTFILES` порта будут оставаться доступными посредством FTP/HTTP. Если эта переменная устанавливается вместе с `NO_PACKAGE`, то только файлы порта `DISTFILES` будут доступны, и только посредством FTP/HTTP. В качестве значения `NO_CDROM` должна указываться строка, описывающая причины, по которым порт не может распространяться на CD-ROM. К примеру, это применяется, если лицензионное соглашение приложения предполагает только его "некоммерческое" использование. === `NOFETCHFILES` Файлы, определенные в переменной `NOFETCHFILES`, не будут извлекаться ни из одного из `MASTER_SITES`. Примером такого файла является файл, поставляемый на CD-ROM. Инструменты, проверяющие доступность этих файлов на `MASTER_SITES`, должны игнорировать эти файлы и не сообщать о них. === `RESTRICTED` Задайте эту переменную, если лицензия на приложение не позволяет ни зеркалировать файлы `DISTFILES`, ни распространять бинарный пакет через FTP/HTTP или на CD-ROM. Ни `NO_CDROM`, ни `NO_PACKAGE` не стоит устанавливать вместе с `RESTRICTED`, так как последняя переменная подразумевает первые две. В качестве значения `RESTRICTED` должна указываться строка, описывающая причины, по которым порт нельзя распространять. Обычно это означает, что порт использует закрытое программное обеспечение, а пользователь должен вручную сгрузить файлы `DISTFILES`, возможно, после заполнения регистрационной формы или подтверждения соглашения с условиями EULA. === `RESTRICTED_FILES` Если заданы `RESTRICTED` или `NO_CDROM`, то значение этой переменной по умолчанию соответствует `${DISTFILES} ${PATCHFILES}`, в противном случае она пуста. Если ограничены в распространении лишь некоторые из дистрибутивных файлов, то в этой переменной задаётся их список. === `LEGAL_TEXT` Если порт имеет правовое обременение, которое не покрывается перечисленными выше переменными, то переменной `LEGAL_TEXT` следует присвоить строку с описанием данного обременения. Например, если было получено особое разрешение для FreeBSD на распространение двоичного файла, то эта переменная должна содержать соответствующее указание. === [.filename]#/usr/ports/LEGAL# и `LEGAL` Порт, содержащий любую из перечисленных выше переменных, также должен быть добавлен в [.filename]#/usr/ports/LEGAL#. Первый столбец содержит шаблон совпадения с дистрибутивными файлами, имеющими ограничения на распространение. Второй столбец содержит корень порта. Третий столбец содержит вывод `make -VLEGAL`. === Примеры использования Предпочтительным способом реализации утверждения "архивы исходных текстов для этого порта должны загружаться самостоятельно" является следующее: [.programlisting] .... .if !exists(${DISTDIR}/${DISTNAME}${EXTRACT_SUFX}) IGNORE= may not be redistributed because of licensing reasons. Please visit some-website to accept their license and download ${DISTFILES} into ${DISTDIR} .endif .... Это одновременно и информирует пользователя, и устанавливает нужные метаданные на пользовательской машине для использования автоматическими программами. Обратите внимание, что данная кляуза должна предшествовать подключению файла [.filename]#bsd.port.pre.mk#. [[building]] == Механизмы построения [[parallel-builds]] === Параллельное построение портов Инфраструктура портов FreeBSD поддерживает параллельное построение с использованием множественных подпроцессов `make`, что позволяет системам SMP задействовать всю доступную мощность CPU, тем самым делая построение портов более быстрым и эффективным. Это достигается путём передачи флага `-jX` команде man:make[1]. Такое построение портов является поведением по умолчанию. К сожалению, не все порты поддерживают параллельную сборку достаточно хорошо, и поэтому может потребоваться выключить этот механизм явным образом путём добавления переменной `MAKE_JOBS_UNSAFE=yes`. Эта переменная используется в случае, когда известно, что порт ломается с `-jX`. [[using-make]] === `make`, `gmake` и `imake` Если ваш порт использует GNU make, то установите `USES= gmake`. .Переменные для портов, использующих gmake [cols="1,1", frame="none", options="header"] |=== | Переменная | Значение |`USES= gmake` |Для сборки порта требуется `gmake`. |`GMAKE` |Полный путь к команде `gmake`, если отсутствует в `PATH`. |=== Если ваш порт является приложением X, которое создает файлы [.filename]#Makefile# из [.filename]#Imakefile#, используя imake, то установите `USES= imake`. Это заставит стадию конфигурирования автоматически выполнить `xmkmf -a`. Если флаг `-a` представляет для вашего порта проблему, то установите `XMKMF=xmkmf`. Если порт использует imake, но не понимает цель `install.man`, то следует установить `NO_INSTALL_MANPAGES=yes`. Если исходный [.filename]#Makefile# вашего порта имеет что-нибудь помимо `all` в качестве основной цели построения, то задайте соответствующее значение `ALL_TARGET`. То же касается `install` и `INSTALL_TARGET`. [[using-configure]] === Сценарий `configure` Если ваш порт использует сценарий `configure` для получения файлов [.filename]#Makefile# из файлов [.filename]#Makefile.in#, то установите `GNU_CONFIGURE=yes`. Если вы хотите дать дополнительные параметры сценарию `configure` (аргументом по умолчанию является `--prefix=${PREFIX} --infodir=${PREFIX}/${INFO_PATH} --mandir=${MANPREFIX}/man --build=${CONFIGURE_TARGET}`), установите эти параметры в `CONFIGURE_ARGS`. Дополнительные переменные окружения можно передать, используя переменную `CONFIGURE_ENV`. .Переменные для портов, использующих `configure` [cols="1,1", frame="none", options="header"] |=== | Переменная | Значение |`GNU_CONFIGURE` |Порт использует сценарий `configure` для подготовки построения. |`HAS_CONFIGURE` |То же, что и `GNU_CONFIGURE`, кроме того, что цель configure по умолчанию не добавляется в `CONFIGURE_ARGS`. |`CONFIGURE_ARGS` |Дополнительные параметры, передаваемые сценарию `configure`. |`CONFIGURE_ENV` |Дополнительные переменные окружения, задаваемые для запуска сценария `configure`. |`CONFIGURE_TARGET` |Переопределить цель configure по умолчанию. Значением по умолчанию является `${MACHINE_ARCH}-portbld-freebsd${OSREL}`. |=== [[using-cmake]] === Использование `cmake` Если порт использует CMake, определите `USES= cmake` или `USES= cmake:outsource` для построения во внешнем каталоге (см. ниже). .Переменные для портов, использующих `cmake` [cols="1,1", frame="none", options="header"] |=== | Переменная | Значение |`CMAKE_ARGS` |Специфичные для порта флаги CMake, передаваемые `cmake`. |`CMAKE_BUILD_TYPE` |Тип построения (предопределённые профили построения CMake). По умолчанию `Release`, `Debug` при использовании `WITH_DEBUG`. |`CMAKE_ENV` |Переменные окружения для передачи `cmake`. По умолчанию `${CONFIGURE_ENV}`. |`CMAKE_SOURCE_PATH` |Путь к каталогу с исходным кодом. По умолчанию `${WRKSRC}`. |=== .Переменные построения `cmake`, устанавливаемые пользователем [cols="1,1", frame="none", options="header"] |=== | Переменная | Значение |`CMAKE_VERBOSE` |Разрешает подробный вывод сообщений при построении. Значение по умолчанию не задано, если не заданы `BATCH` или `PACKAGE_BUILDING`. |`CMAKE_NOCOLOR` |Запрещает цветной вывод сообщений при построении. Значение по умолчанию не задано, если не заданы `BATCH` или `PACKAGE_BUILDING`. |=== CMake поддерживает следующие профили построения: `Debug`, `Release`, `RelWithDebInfo` и `MinSizeRel`. Профили `Debug` и `Release` учитывают системные флаги `\*FLAGS`; `RelWithDebInfo` и `MinSizeRel` соответственно определяют `CFLAGS` со значением `-O2 -g` и `-Os -DNDEBUG`. Значение `CMAKE_BUILD_TYPE` экспортируется в нижнем регистре в `PLIST_SUB` и должно использоваться, если порт устанавливает файлы `*.cmake` в зависимости от типа построения (для примера посмотрите на package:deskutils/strigi[]). Следует учитывать, что некоторые проекты могут определять собственные профили построения и/или форсировать конкретный тип построения через установку `CMAKE_BUILD_TYPE` в файлах [.filename]#CMakeLists.txt#. Для того чтобы порт для такого проекта учитывал `CFLAGS` и `WITH_DEBUG`, из этих файлов должны быть удалены значения `CMAKE_BUILD_TYPE`. Большинство проектов, основанных на CMake, поддерживают метод внешнего (out-of-source) построения. Для порта внешнее построение можно запросить с использованием суффикса `:outsource`. В этом случае `CONFIGURE_WRKSRC`, `BUILD_WRKSRC` и `INSTALL_WRKSRC` будут иметь значение `${WRKDIR}/.build` для каталога, содержащего файлы, получаемые на этапах конфигурации и построения; при этом каталог с исходным кодом будет оставаться без изменений. [[using-cmake-example]] .Пример для `USES= cmake` [example] ==== Следующий отрывок демонстрирует использование CMake для порта. `CMAKE_SOURCE_PATH` обычно не требуется, но может быть установлен, когда исходный код не находится в верхнем каталоге или если порт используется для построения части проекта. [.programlisting] .... USES= cmake:outsource CMAKE_SOURCE_PATH= ${WRKSRC}/subproject .... ==== [[using-scons]] === Использование `scons` Если ваш порт использует SCons, определите `USE_SCONS=yes`. .Переменные для портов, использующих `scons` [cols="1,1", frame="none", options="header"] |=== | Переменная | Значение |`SCONS_ARGS` |Специфичные для порта флаги SCons, передаваемые окружению SCons. |`SCONS_BUILDENV` |Переменные для установки в системном окружении. |`SCONS_ENV` |Переменные для установки в окружении SCons. |`SCONS_TARGET` |Последний параметр для передачи SCons, похожий на `MAKE_TARGET`. |=== Для того, чтобы сторонний [.filename]#SConstruct# соответствовал всему, что передается SCons в переменной `SCONS_ENV` (самое главное, это `CC/CXX/CFLAGS/CXXFLAGS`), примените патч к [.filename]#SConstruct#, так чтобы переменная построения `Environment` выглядела следующим образом: [.programlisting] .... env = Environment(**ARGUMENTS) .... В дальнейшем ее можно изменить при помощи `env.Append` и `env.Replace`. [[using-autotools]] == Использование GNU Autotools [[using-autotools-introduction]] === Введение Различные инструменты GNU autotools предоставляют механизм абстракции для построения частей программного обеспечения на широком наборе операционных систем и аппаратных архитектур. Внутри Коллекции Портов отдельный порт может использовать эти инструменты при помощи простых конструкций: [.programlisting] .... USE_AUTOTOOLS= tool:version[:operation] ... .... К моменту написания _tool_ может быть одним из `libtool`, `libltdl`, `autoconf`, `autoheader`, `automake` или `aclocal`. _version_ указывает конкретную версию используемого инструмента (смотрите `devel/{automake,autoconf,libtool}[0-9]+` для получения действительных версий). _operation_ является необязательным расширением и указывает на способ использования инструмента. Одновременно может быть указано несколько инструментов, добавляя их все на одной строке или используя конструкцию Makefile `+=`. В заключение, существует специальный инструмент по называнию `autotools`, который является удобной функцией при установке всех доступных версий autotools для возможности проведения кросс-разработки. Это также может быть достигнуто путем установки порта `devel/autotools`. [[using-libtool]] === `libtool` Динамические библиотеки, использующие инфраструктуру построения GNU, обычно используют libtool для настройки компиляции и установки динамических библиотек в соответствии с особенностями данной операционной системы. В типичной практике используется копирование встроенного в приложение `libtool`. Если вам нужно использовать внешнюю команду `libtool`, то вы можете использовать версию, поставляемую Коллекцией Портов: [.programlisting] .... USE_AUTOTOOLS= libtool:version[:env] .... При отсутствии дополнительных операций, `libtool:version` сообщает инфраструктуре построения о применении патча к сценарию configure с установленной в системе копией `libtool`. Означает использование `GNU_CONFIGURE`. Более того, некоторые переменные make и оболочки shell будут назначены для дальнейшего использования этим портом. Подробности смотрите в [.filename]#bsd.autotools.mk#. При использовании операции `:env` будет настроено только окружение. Наконец, `LIBTOOLFLAGS` и `LIBTOOLFILES` можно установить по желанию, чтобы переопределить наиболее вероятные аргументы для `libtool` и файлы, предназначенные для изменения. Большинству портов это скорее всего не понадобится. Для дальнейших подробностей смотрите [.filename]#bsd.autotools.mk#. [[using-libltdl]] === `libltdl` Некоторые порты задействуют пакет с библиотекой `libltdl`, которая является частью комплекта `libtool`. Использование этой библиотеки не вызывает автоматическое использование самой `libtool`, и, таким образом, обеспечивается отдельная конструкция. [.programlisting] .... USE_AUTOTOOLS= libltdl:version .... Всё, что в настоящее время она делает, это добавление `LIB_DEPENDS` для подходящего порта `libltdl`, потому она предоставляется как удобная функция для помощи в устранении всяких зависимостей от портов autotools вне инфраструктуры `USE_AUTOTOOLS`. Для этого инструмента не существует необязательных операций. [[using-autoconf]] === `autoconf` и `autoheader` Вместо сценария configure некоторые порты содержат шаблон autoconf в файле [.filename]#configure.ac#. Вы можете использовать следующие присвоения, чтобы позволить `autoconf` создать сценарий configure, а `autoheader` создать заголовки шаблона для использования в сценарии configure. [.programlisting] .... USE_AUTOTOOLS= autoconf:version[:env] .... и [.programlisting] .... USE_AUTOTOOLS= autoheader:version .... которые также подразумевают использование `autoconf:version`. Аналогично команде `libtool` включение необязательной операции `:env` всего лишь настраивает окружение для дальнейшего использования. Без этого выполняется наложение патчей и переконфигурирование порта. Дополнительные необязательные переменные `AUTOCONF_ARGS` и `AUTOHEADER_ARGS` можно переопределить в [.filename]#Makefile# порта, если указано явным образом. Как и с эквивалентами `libtool`, большинству портов это вряд ли понадобится. [[using-automake]] === `automake` и `aclocal` Некоторые пакеты содержат только файлы [.filename]#Makefile.am#. Они должны быть преобразованы в файлы [.filename]#Makefile.in# с использованием automake и дальнейшей обработкой `configure` для получения настоящего [.filename]#Makefile#. Аналогично, иногда пакеты не поставляются с вложенными файлами [.filename]#aclocal.m4#, снова требуемых для построения программного обеспечения. Их можно получить командой `aclocal`, которая просматривает [.filename]#configure.ac# или [.filename]#configure.in#. `aclocal` имеет похожую связь с `automake`, как у `autoheader` с `autoconf`, что описано в предыдущей главе. `aclocal` подразумевает использование `automake`, таким образом, мы имеем: [.programlisting] .... USE_AUTOTOOLS= automake:version[:env] .... и [.programlisting] .... USE_AUTOTOOLS= aclocal:version .... которые также подразумевают использование `automake:version`. Также как и для `libtool` и `autoconf`, подключение необязательной операции `:env` всего лишь устанавливает окружение для дальнейшего пользования. Без этого выполняется реконфигурирование этого порта. Как и в случае с `autoconf` и `autoheader`, обе команды `automake` и `aclocal` соответственно имеют необязательные переменные `AUTOMAKE_ARGS` и `ACLOCAL_ARGS`, которые при необходимости можно переопределить в [.filename]#Makefile# порта. [[using-gettext]] == Использование GNU `gettext` === Простой вариант использования -Если для вашего порта требуется `gettext`, добавьте `USES= gettext`, и ваш порт унаследует зависимость от package:devel/gettext[]. <> содержит перечень других значений для использования `gettext`. +Если для вашего порта требуется `gettext`, добавьте `USES= gettext`, и ваш порт унаследует зависимость от package:devel/gettext[]. crossref:makefiles[uses-makefiles, `USES`] содержит перечень других значений для использования `gettext`. Довольно распространенным случаем является использование в порте `gettext` и `configure`. Как правило, GNU `configure` способен находить `gettext` автоматически. Если он все же не сможет это сделать, то подсказки для размещения `gettext` можно передать через переменные окружения `CPPFLAGS` и `LDFLAGS`: [.programlisting] .... USES= gettext CPPFLAGS+= -I${LOCALBASE}/include LDFLAGS+= -L${LOCALBASE}/lib GNU_CONFIGURE= yes .... Конечно же, этот код можно записать в более компактном виде, если передавать флаги в `configure` не требуется: [.programlisting] .... USES= gettext GNU_CONFIGURE= yes .... === Оптимальное использование Некоторые программные продукты позволяют отключать NLS, к примеру, передавая параметр `--disable-nls` сценарию `configure`. В этом случае ваш порт должен использовать `gettext`, в зависимости от значения `NLS`. Для портов небольшой или средней сложности вы можете полагаться на следующую идиому: [.programlisting] .... GNU_CONFIGURE= yes .include .if ${PORT_OPTIONS:MNLS} USES+= gettext PLIST_SUB+= NLS="" .else CONFIGURE_ARGS+= --disable-nls PLIST_SUB+= NLS="@comment " .endif .include .... Следующий пункт в вашем списке дел разобраться, чтобы файлы каталога сообщения включались в список упаковки по условию. Часть, входящая в [.filename]#Makefile#, уже обеспечена этой идиомой. Остальное объясняется в главе <>. Вкратце, каждое вхождение `%%NLS%%` в [.filename]#pkg-plist# будет заменено на "`@comment`", если NLS выключен, или пустой строкой, если включен. В результате строки, предваряемые `%%NLS%%`, станут комментариями в итоговом листе упаковки, если NLS выключен; иначе, префикс будет просто удален. Всё, что вам нужно, это вставить `%%NLS%%` перед каждым путем к файлу каталога сообщений в [.filename]#pkg-plist#. Например: [.programlisting] .... %%NLS%%share/locale/fr/LC_MESSAGES/foobar.mo %%NLS%%share/locale/no/LC_MESSAGES/foobar.mo .... В особо сложных случаях вам понадобиться использовать более продвинутые техники, чем данный рецепт, такие как <>. === Управление каталогами сообщений Существует момент, который следует учитывать при установке файлов каталогов сообщений. Целевые каталоги для размещения, расположенные под [.filename]#LOCALBASE/shared/locale#, редко когда должны создаваться и удаляться портом. Для наиболее популярных языков имеются собственные каталоги, перечисленные в [.filename]#PORTSDIR/Templates/BSD.local.dist#. Каталоги для множества других языков управляются с помощью порта package:devel/gettext[]. Обратите внимание на его [.filename]#pkg-plist# и посмотрите, куда данный порт собирается установить файлы каталогов сообщений для единственного в своем роде языка. [[using-perl]] == Использование Perl Если `MASTER_SITES` установлена в значение `MASTER_SITE_PERL_CPAN`, то предпочтительным значением `MASTER_SITE_SUBDIR` является имя иерархии верхнего уровня. Например, рекомендуемым значением для `p5-Module-Name` является `Module`. Иерархию верхнего уровня можно посмотреть на сайте http://cpan.org/modules/by-module/[cpan.org]. Это поддерживает порт в рабочем состоянии при изменении модуля автором. Исключением этого правила является отсутствие соответствующего каталога или файла с дистрибутивом в этом каталоге. В качестве `MASTER_SITE_SUBDIR` в этом случае разрешается использовать id автора. В качестве значения все из настраиваемых knobs ниже принимают `YES` или строку с версией вида `5.8.0+`. `YES` означает, что данный порт можно использовать с любой из поддерживаемых версий Perl. Если порт работает только с некоторыми версиями Perl, то это можно обозначить при помощи строки с версией, указывающей на минимальную версию (пример: `5.7.3+`), максимальную версию (пример: `5.8.0-`) или точную версию (пример: `5.8.3`). .Переменные для портов, использующих Perl [cols="1,1", frame="none", options="header"] |=== | Переменная | Значение |`USE_PERL5` |Perl 5 используется для построения и работы. |`USE_PERL5_BUILD` |Perl 5 используется для построения. |`USE_PERL5_RUN` |Perl 5 используется во время работы. |`PERL` |Полный путь к интерпретатору Perl 5, либо в системе, либо установленному из портов, но без номера версии. Используйте это, если вам нужно заменить строки "`#!`" в скриптах. |`PERL_CONFIGURE` |Конфигурация при помощи MakeMaker языка Perl. Влечёт `USE_PERL5`. |`PERL_MODBUILD` |Конфигурация, построение и установка с использованием Module::Build. Влечёт `PERL_CONFIGURE`. |=== [NOTE] ==== Порты для модулей Perl, которые не имеют официального вебсайта, должны указывать `cpan.org` в строке WWW в файле [.filename]#pkg-descr#. Предпочтительная форма URL `http://search.cpan.org/dist/Module-Name/` (включая завершающий слэш). ==== [NOTE] ==== Не используйте `${SITE_PERL}` в объявлении зависимостей. Использование этой конструкции подразумевает наличие подключенного [.filename]#bsd.perl.mk#, что не всегда так. Порты, зависимые от этого порта, получат неправильные зависимости, если файлы этого порта будут перемещены при последующем обновлении. Правильный способ объявления зависимостей для модулей Perl показан в примере ниже. ==== [[use-perl-dependency-example]] .Пример зависимости Perl [example] ==== [.programlisting] .... p5-IO-Tee>=0.64:${PORTSDIR}/devel/p5-IO-Tee .... ==== Для портов Perl, которые устанавливают страницы справочника, в [.filename]#pkg-plist# можно использовать макрос `PERL5_MANx` (где _x_ принимает значение от `1` до `9`). Например, [.programlisting] .... lib/perl5/5.14/man/man3/AnyEvent::I3.3.gz .... можно заменить на [.programlisting] .... %%PERL5_MAN3%%/AnyEvent::I3.3.gz .... [[using-x11]] == Использование X11 [[x11-variables]] === Компоненты X.Org X.Org является реализацией X11, доступной в Коллекции Портов. Если ваше приложение зависит от компонентов X, установите в переменную `USE_XORG` в перечень требуемых компонентов. К настоящему времени доступными компонентами являются: `bigreqsproto compositeproto damageproto dmx dmxproto dri2proto evieproto fixesproto fontcacheproto fontenc fontsproto fontutil glproto ice inputproto kbproto libfs oldx pciaccess pixman printproto randrproto recordproto renderproto resourceproto scrnsaverproto sm trapproto videoproto x11 xau xaw xaw6 xaw7 xbitmaps xcmiscproto xcomposite xcursor xdamage xdmcp xevie xext xextproto xf86bigfontproto xf86dgaproto xf86driproto xf86miscproto xf86rushproto xf86vidmodeproto xfixes xfont xfontcache xft xi xinerama xineramaproto xkbfile xkbui xmu xmuu xorg-server xp xpm xprintapputil xprintutil xproto xproxymngproto xrandr xrender xres xscrnsaver xt xtrans xtrap xtst xv xvmc xxf86dga xxf86misc xxf86vm`. Всегда актуальный перечень можно найти в [.filename]#/usr/ports/Mk/bsd.xorg.mk#. Проект Mesa является попыткой обеспечить свободную реализацию OpenGL. Вы можете указать зависимость от различных компонентов этого проекта при помощи переменной `USE_GL`. Действительные опции: `glut, glu, glw, glew, gl` и `linux`. Для обратной совместимости значение `yes` соответствует `glu`. [[use-xorg-example]] .Пример для USE_XORG [example] ==== [.programlisting] .... USE_XORG= xrender xft xkbfile xt xaw USE_GL= glu .... ==== .Переменные для портов, использующих X [cols="1,1", frame="none"] |=== |`USES= imake` |Используется `imake`. |`XMKMF` |Задаёт маршрут до `xmkmf`, если он отсутствует в `PATH`. По умолчанию это `xmkmf -a`. |=== [[using-x11-vars]] .Использование переменных X11 в порте [example] ==== [.programlisting] .... # Использовать некоторые библиотеки X11 USE_XORG= x11 xpm .... ==== [[porting-motif]] === Порты, которым требуется Motif Если вашему порту требуется Motif, задайте переменную `USES= motif` в файле [.filename]#Makefile#. Реализация Motif, используемая по умолчанию, находится в package:x11-toolkits/open-motif[]. Пользователи вместо этого могут выбрать package:x11-toolkits/lesstif[] через установку переменной `WANT_LESSTIF`. Переменная `MOTIFLIB` будет установлена в [.filename]#bsd.port.mk#, чтобы ссылаться на соответствующую библиотеку Motif. Пожалуйста, измените исходные тексты вашего порта на использование `${MOTIFLIB}` везде, где упоминается библиотека Motif, в первоначальном [.filename]#Makefile# или [.filename]#Imakefile#. Существует два общих случая: * Если порт обращается к библиотеке Motif как `-lXm` в своих файлах [.filename]#Makefile# или [.filename]#Imakefile#, просто подставьте вместо этих обращений `${MOTIFLIB}`. * Если порт использует `XmClientLibs` в своем файле [.filename]#Imakefile#, измените это обращение на `${MOTIFLIB} ${XTOOLLIB} ${XLIB}`. Заметьте, что переменная `MOTIFLIB` (как правило) раскрывается в `-L/usr/local/lib -lXm` или `/usr/local/lib/libXm.a`, так что нет нужды впереди добавлять `-L` или `-l`. === Шрифты для X11 Если ваш порт устанавливает шрифты для X Window System, поместите их в каталог [.filename]#LOCALBASE/lib/X11/fonts/local#. === Получение поддельного `DISPLAY`, используя Xvfb Некоторые приложения для успешной компиляции требуют наличие работающего дисплея X11. Это создает проблему для машин, которые работают в режиме headless. При использовании следующего канонического хака инфраструктура построения запустит сервер X в виртуальном фреймбуфере. Затем переменная работающего `DISPLAY` передается при построении. [.programlisting] .... USES= display .... [[desktop-entries]] === Элементы рабочего стола Элементы рабочего стола (http://standards.freedesktop.org/desktop-entry-spec/latest/[стандарта Freedesktop]) предоставляют способ автоматической настройки функций рабочего стола при установке новой программы, не требуя вмешательства пользователя. Например, новые программы автоматически отображаются в меню приложений совместимых окружений рабочего стола. Элементы рабочего стола изначально появились в окружении рабочего стола GNOME, но в настоящее время являются стандартом и также работают с KDE и Xfce. Такая небольшая автоматизация предоставляет реальное удобство для пользователя, и посему элементы рабочего стола приветствуются в приложениях, которые можно использовать в окружении рабочего стола. ==== Использование предопределенных файлов [.filename]#.desktop# Порты, включающие предопределенные файлы [.filename]#*.desktop#, должны включать эти файлы в [.filename]#pkg-plist# и устанавливать их в каталог [.filename]#$LOCALBASE/shared/applications#. Для установки этих файлов используется <>. [[updating-desktop-database]] ==== Обновление базы данных рабочего стола Если в файле порта [.filename]#portname.desktop# имеется запись MimeType, то база данных рабочего стола олжна быть обновлена после установки и удаления. Для этого укажите `USES`= desktop-file-utils. [[desktop-entries-macro]] ==== Создание элементов рабочего стола с использованием `DESKTOP_ENTRIES` Элементы рабочего стола можно легко создавать для приложений, используя переменную `DESKTOP_ENTRIES`. Будет автоматически создан, установлен и добавлен в [.filename]#pkg-plist# файл с названием [.filename]#name.desktop#. Синтаксис: [.programlisting] .... DESKTOP_ENTRIES= "NAME" "COMMENT" "ICON" "COMMAND" "CATEGORY" StartupNotify .... Перечень возможных категорий доступен на http://standards.freedesktop.org/menu-spec/latest/apa.html[вебсайте Freedesktop]. `StartupNotify` отобразит, поддерживает ли приложение _уведомления о запуске_. Как правило, это графический индикатор часы вместо указателя мыши, меню или панель, которые уведомляют пользователя о загрузке программы. Программа, поддерживающая уведомления о запуске, очистит этот индикатор после запуска. Программы, несовместимые с уведомлениями о запуске, не будут очищать индикатор (возможно, вызывая путаницу и приводя пользователей в бешенство), и поэтому должны иметь `StartupNotify` в выключенном состоянии `false`; тогда индикатор не будет отображаться совсем. Пример: [.programlisting] .... DESKTOP_ENTRIES= "ToME" "Roguelike game based on JRR Tolkien's work" \ "${DATADIR}/xtra/graf/tome-128.png" \ "tome -v -g" "Application;Game;RolePlaying;" \ false .... [[using-gnome]] == Использование GNOME Для задания того, какие компоненты GNOME использует конкретный порт, проект FreeBSD/GNOME использует собственный набор переменных. На странице проекта FreeBSD/GNOME размещён http://www.FreeBSD.org/gnome/docs/porting/[ исчерпывающий список этих переменных]. [[using-qt]] == Использование Qt [[qt-common]] === Порты, для которых требуется Qt .Переменные для портов, использующих Qt [cols="1,1", frame="none"] |=== |`USE_QT4` |Указывает инструменты и библиотеки в качестве зависимостей для портов, которые используют Qt 4. Для получения подробностей смотрите <>. |`QT_PREFIX` |Устанавливается в значение, содержащее путь к установленному Qt (переменная только для чтения). |`MOC` |Устанавливается в значение, содержащее путь к `moc` (переменная только для чтения). По умолчанию устанавливается в соответствии со значением `USE_QT_VER`. |`QTCPPFLAGS` |Дополнительные флаги компилятора для инструментального пакета Qt, передаваемые через переменную `CONFIGURE_ENV`. По умолчанию устанавливается в соответствии со значением `USE_QT_VER`. |`QTCFGLIBS` |Дополнительные флаги компоновки для инструментального пакета Qt, передаваемые через переменную `CONFIGURE_ENV`. По умолчанию устанавливается в соответствии со значением `USE_QT_VER`. |`QTNONSTANDARD` |Подавляет изменение `CONFIGURE_ENV`, `CONFIGURE_ARGS`, `CPPFLAGS` и `MAKE_ENV`. |=== .Дополнительные переменные для портов, использующих Qt 4.x [cols="1,1", frame="none"] |=== |`UIC` |Устанавливает путь к `uic` (переменная только для чтения). |`QMAKE` |Устанавливает путь к `qmake` (переменная только для чтения). |`QMAKESPEC` |Устанавливает путь к конфигурационному файлу для `qmake` (переменная только для чтения). |`QMAKEFLAGS` |Дополнительные флаги для `qmake`. |`QT_INCDIR` |Устанавливает каталоги для заголовков Qt 4 (переменная только для чтения). |`QT_LIBDIR` |Устанавливает путь к библиотекам Qt 4 (переменная только для чтения). |`QT_PLUGINDIRC` |Устанавливает путь к плагинам Qt 4 (переменная только для чтения). |=== При заданной переменной `USE_QT4` применяются следующие настройки: [.programlisting] .... CONFIGURE_ARGS+= --with-qt-includes=${QT_INCDIR} \ --with-qt-libraries=${QT_LIBDIR} \ --with-extra-libs=${LOCALBASE}/lib \ --with-extra-includes=${LOCALBASE}/include CONFIGURE_ENV+= MOC="${MOC}" UIC="${UIC}" LIBS="${QTCFGLIBS}" \ QMAKE="${QMAKE}" QMAKESPEC="${QMAKESPEC}" QTDIR="${QT_PREFIX}" MAKE_ENV+= QMAKESPEC="${QMAKESPEC}" PLIST_SUB+= QT_INCDIR_REL=${QT_INCDIR_REL} \ QT_LIBDIR_REL=${QT_LIBDIR_REL} \ QT_PLUGINDIR_REL=${QT_PLUGINDIR_REL} .... [[qt4-components]] === Выбор компонентов В переменной `USE_QT4` должны указываться зависимости от отдельных инструментов и библиотек Qt 4. К каждому компоненту можно добавить суффикс, `_build` или `_run`, отражающий, когда должна быть применена зависимость, во время сборки или выполнения, соответственно. Если суффикс отсутствует, зависимость от компонента будет и для времени сборки, и для времени выполнения. Обычно, компоненты библиотек должны указываться без суффиксов, компоненты инструментов - с суффиксом `_build`, а компоненты плагинов - с суффиксом `_run`. Наиболее общие используемые компоненты перечислены ниже (все доступные компоненты перечислены в `_USE_QT4_ALL` в файле [.filename]#/usr/ports/Mk/bsd.qt.mk#): .Доступные библиотечные компоненты Qt 4 [cols="1,1", frame="none", options="header"] |=== | Название | Описание |`corelib` |основная библиотека (можно опустить, если порт не использует ничего, кроме `corelib`) |`gui` |библиотека графического пользовательского интерфейса |`network` |сетевая библиотека |`opengl` |библиотека OpenGL |`qt3support` |библиотека совместимости с Qt 3 |`qtestlib` |библиотека модульного тестирования |`script` |библиотека сценариев |`sql` |библиотека SQL |`xml` |библиотека XML |=== Вы можете определить, от каких библиотек зависит приложение, запустив `ldd` на основной исполняемый файл после успешной компиляции. .Доступные компоненты инструментов Qt 4 [cols="1,1", frame="none", options="header"] |=== | Название | Описание |`moc` |мета-объектный компилятор (нужен при построении почти для каждого приложения Qt) |`qmake` |генератор Makefile / утилита построения |`rcc` |компилятор ресурсов (нужен, если приложение идет вместе с файлами [.filename]#*.rc# или [.filename]#*.qrc#) |`uic` |компилятор пользовательского интерфейса (нужен, если приложение идет вместе с файлами [.filename]#*.ui#, созданными при помощи Qt Designer, - на практике каждое приложение Qt с GUI) |=== .Доступные компоненты плагинов Qt 4 [cols="1,1", frame="none", options="header"] |=== | Название | Описание |`iconengines` |плагин для движка иконок SVG (если приложение поставляется с иконками SVG) |`imageformats` |плагины для графических форматов GIF, JPEG, MNG и SVG (если приложение поставляется с графическими файлами) |=== [[qt4-components-example]] .Выбор компонентов Qt 4 [example] ==== В этом примере портированное приложение использует библиотеку графического пользовательского интерфейса Qt 4, основную библиотеку Qt 4, все инструменты генерации кода Qt 4 и генератор Makefile Qt 4. Поскольку библиотека `gui` подразумевает зависимость от основной библиотеки, указывать `corelib` нет необходимости. Инструменты генерации кода Qt 4 `moc`, `uic` и `rcc`, а также генератор Makefile `qmake` нужны только для времени построения, поэтому они указаны с суффиксом `_build`: [.programlisting] .... USE_QT4= gui moc_build qmake_build rcc_build uic_build .... ==== [[using-qmake]] === Использование `qmake` .Переменные для портов, использующих `qmake` [cols="1,1", frame="none", options="header"] |=== | Название | Описание |`QMAKE_ARGS` |Спефицичные для порта флаги QMake для передачи программе `qmake`. |`QMAKE_ENV` |Переменные окружения, устанавливаемые для программы `qmake`. По умолчанию соответствует значению `${CONFIGURE_ENV}`. |`QMAKE_PRO` |Название файла проекта [.filename]#.pro#. По умолчанию имеет пустое значение (с использованием автоопределения). |=== Если вместе с приложением вместо [.filename]#configure# поставляется файл [.filename]#.pro#, вы можете использовать следующее: [.programlisting] .... USES= qmake USE_QT4= qmake_build .... `USES=qmake` указывает порту на использование `qmake` в процессе конфигурации. Обратите внимание, что `USES=qmake` не подразумевает зависимость от Qt 4 `qmake`. Для этого в значении `USE_QT4` должен присутствовать компонент `qmake_build`. Приложения Qt часто пишутся в кроссплатформенной манере, и X11/Unix часто не является для них платформой разработки, что в свою очередь часто приводит к соответствующим упущенным моментам: * _Отсутствующие дополнительные пути для заголовочных файлов._ Многие приложения идут с поддержкой иконки в системном трее, но пренебрегают смотреть на наличие заголовочных файлов и/или библиотеками в каталогах X11. Вы можете сообщить `qmake`, чтобы она добавила каталоги в пути поиска заголовочных файлов и библиотек через командную строку. К примеру: + [.programlisting] .... QMAKE_ARGS+= INCLUDEPATH+=${LOCALBASE}/include \ LIBS+=-L${LOCALBASE}/lib .... * _Фиктивные пути установки._ Иногда данные, такие как иконки и файлы .desktop, устанавливаются по умолчанию в каталоги, которые не просматриваются XDG-совместимыми приложениями. Примером является package:editors/texmaker[] - взгляните на [.filename]#patch-texmaker.pro# из каталога [.filename]#files# этого порта, который можно взять в качестве шаблона исправления этого непосредственно в файле проекта `qmake`. [[using-kde]] == Использование KDE [[kde4-variables]] === Задание переменных KDE 4 Если ваше приложение зависит от KDE 4.x, присвойте `USE_KDE4` список требуемых компонентов. Для переопределения типа зависимости компонента могут быть использованы суффиксы `_build` и `_run` (например, `baseapps_run`). Если суффикс не задан, будет использован тип зависимости по умолчанию. Если вы хотите использовать оба типа, добавьте компонент дважды с обоими суффиксами (например, `automoc4_build automoc4_run`). Основные наиболее используемые компоненты перечислены ниже (актуальные компоненты задокументированы в начале файла [.filename]#/usr/ports/Mk/bsd.kde4.mk#): .Доступные компоненты KDE 4 [cols="1,1", frame="none", options="header"] |=== | Название | Описание |`kdehier` |Иерархия основных каталогов KDE |`kdelibs` |KDE Developer Platform |`kdeprefix` |Если установлено, то порт будет установлен в `${KDE4_PREFIX}` вместо `${LOCALBASE}` |`sharedmime` |База данных MIME типов для портов KDE |`automoc4` |automoc для пакетов Qt 4 |`akonadi` |Сервер хранения KDE-Pim |`soprano` |Фреймворк Qt 4 RDF |`strigi` |Поисковые даемон рабочего стола |`libkcddb` |Библиотека KDE CDDB |`libkcompactdisc` |Библиотека KDE для взаимодействия с аудио-CD |`libkdeedu` |Библиотеки, используемые для образовательных приложений |`libkdcraw` |Библиотека KDE LibRaw |`libkexiv2` |Библиотека KDE Exiv2 |`libkipi` | KDE Image Plugin Interface |`libkonq` |Основная библиотека Konqueror |`libksane` |Библиотека KDE SANE ("Scanner Access Now Easy") |`pimlibs` |Библиотеки KDE-Pim |`kate` |Тектовый редактор |`marble` |Виртуальный глобус |`okular` |Универсальный просмотрщик документов |`korundum` |Привязка Ruby к KDE |`perlkde` |Привязка Perl к KDE |`pykde4` |Привязка Python к KDE |`pykdeuic4` |Компилятор пользовательского интерфейса PyKDE |`smokekde` |Библиотеки KDE SMOKE |=== Порты KDE 4.x устанавливаются в `KDE4_PREFIX`, что в настоящее время соответствует [.filename]#/usr/local/kde4#. Это достигается путем указания компонента `kdeprefix`, который определяет значение по умолчанию для `PREFIX`. Тем не менее, порты учитывают любые `PREFIX`, установленные через переменную окружения `MAKEFLAGS` и/или параметры `make`. [[kde4-components-example]] .Пример `USE_KDE4` [example] ==== Это простой пример для порта KDE 4. `USES= cmake:outsource` указывает порту использовать CMake, конфигурационный инструмент, широко применяемый в проектах KDE 4 (подробное описание даёт <>). `USE_KDE4` добавляет зависимость от библиотек KDE и заставляет порты использовать `automoc4` во время сборки. Требуемые компоненты KDE и другие зависимости можно определить в журнале configure. `USE_KDE4` не подразумевает `USE_QT4`. Если порт требует какой-либо из компонентов Qt 4, их следует указать в `USE_QT4`. [.programlisting] .... USES= cmake:outsource USE_KDE4= kdelibs kdeprefix automoc4 USE_QT4= moc_build qmake_build rcc_build uic_build .... ==== [[using-java]] == Использование Java [[java-variables]] === Задание переменных Если вашему порту необходимо наличие Java(TM) Development Kit (JDK(TM)) для построения, работы или даже распаковки дистрибутивного файла, то в нём должна быть задана переменная `USE_JAVA`. В Коллекции Портов присутствуют несколько JDK различных разработчиков и разных версий. Если ваш порт должен использовать одну из этих версий, то вы должны указать, какую именно. Самой последней версией и версией по умолчанию является package:java/openjdk6[]. .Переменные, которые которые могут задаваться портами, использующими Java [cols="1,1", frame="none", options="header"] |=== | Переменная | Значение |`USE_JAVA` |Должна быть определена для того, что последующие переменные вступили в действие. |`JAVA_VERSION` |Список версий Java, перечисленных через пробел, подходящих для порта. Опциональный знак `"+"` позволяет вам указать диапазон версий (возможные значения: `1.5[+] 1.6[+] 1.7[+]`). |`JAVA_OS` |Список операционных систем, перечисленных через пробел, порты JDK для которых подходят для порта (возможные значения: `native linux`). |`JAVA_VENDOR` |Список разработчиков портов JDK, перечисленных через пробел, которые подходят для порта (возможные значения: `freebsd bsdjava sun openjdk`). |`JAVA_BUILD` |Если задана, то означает, что выбранный порт JDK должен быть добавлен к зависимостям порта для его построения. |`JAVA_RUN` |Если задана, то означает, что выбранный порт JDK должен быть добавлен в зависимостям порта для его работы. |`JAVA_EXTRACT` |Если задана, то означает, что выбранный порт JDK должен быть добавлен в зависимостям порта для распаковки его дистрибутивных файлов. |=== Ниже перечисляются все значения, которые принимают переменные после задания переменной `USE_JAVA`: .Переменные, доступные в портах, использующих Java [cols="1,1", frame="none", options="header"] |=== | Переменная | Значение |`JAVA_PORT` |Название порта JDK (к примеру, `'java/openjdk6'`). |`JAVA_PORT_VERSION` |Полное наименовании версии порта JDK (к примеру, `'1.6.0'`). Если вам нужны только первые две цифры номера версии, используйте `${JAVA_PORT_VERSION:C/^([0-9])\.([0-9])(.*)$/\1.\2/}`. |`JAVA_PORT_OS` |Операционная система, используемая портом JDK (к примеру, `'native'`). |`JAVA_PORT_VENDOR` |Разработчик порта JDK (к примеру, `'openjdk'`). |`JAVA_PORT_OS_DESCRIPTION` |Описание операционной системы, используемой портом JDK (к примеру, `'Native'`). |`JAVA_PORT_VENDOR_DESCRIPTION` |Описание разработчика порта JDK (к примеру, `'OpenJDK BSD Porting Team'`). |`JAVA_HOME` |Маршрут к установочному каталогу JDK (к примеру, [.filename]#'/usr/local/openjdk6'#). |`JAVAC` |Маршрут к используемому компилятору Java (к примеру, [.filename]#'/usr/local/openjdk6/bin/javac'#. |`JAR` |Маршрут к используемой утилите `jar` (к примеру, [.filename]#'/usr/local/openjdk6/bin/jar'# или [.filename]#'/usr/local/bin/fastjar'#). |`APPLETVIEWER` |Маршрут к утилите `appletviewer` (к примеру, [.filename]#'/usr/local/openjdk6/bin/appletviewer'#). |`JAVA` |Маршрут к выполняемому файлу `java`. Используйте его для запуска Java-программ (к примеру, [.filename]#'/usr/local/openjdk6/bin/java'#). |`JAVADOC` |Маршрут к вспомогательной программе `javadoc`. |`JAVAH` |Маршрут к программе `javah`. |`JAVAP` |Маршрут к программе `javap`. |`JAVA_KEYTOOL` |Маршрут к вспомогательной программе `keytool`. |`JAVA_N2A` |Маршрут к утилите `native2ascii`. |`JAVA_POLICYTOOL` |Маршрут к программе `policytool`. |`JAVA_SERIALVER` |Маршрут к вспомогательной программе `serialver`. |`RMIC` |Маршрут к генератору каркаса программ RMI, утилите `rmic`. |`RMIREGISTRY` |Маршрут к программе регистрации RMI, `rmiregistry`. |`RMID` |Маршрут к программе-даемону RMI `rmid`. |`JAVA_CLASSES` |Маршрут к архиву, который содержит файлы классов JDK, [.filename]#${JAVA_HOME}/jre/lib/rt.jar#. |=== Вы можете воспользоваться make-целью `java-debug` для получения информации, необходимой для отладки вашего порта. При её выполнении будут выданы значения многих упомянутых выше переменных. Кроме того, для единообразия установки всех портов Java определены следующие константы: .Константы, определённые для портов, использующих Java [cols="1,1", frame="none", options="header"] |=== | Константа | Значение |`JAVASHAREDIR` |Корневой каталог для всего, что связано с Java. По умолчанию: [.filename]#${PREFIX}/shared/java#. |`JAVAJARDIR` |Каталог, в который должны устанавливаться JAR-файлы. По умолчанию: [.filename]#${JAVASHAREDIR}/classes#. |`JAVALIBDIR` |Каталог, в который устанавливаются JAR-файлы из других портов. По умолчанию: [.filename]#${LOCALBASE}/shared/java/classes#. |=== -Соответствующие записи определяются в обоих переменных `PLIST_SUB` (описана в <>) и `SUB_LIST`. +Соответствующие записи определяются в обоих переменных `PLIST_SUB` (описана в crossref:plist[plist-sub,Изменение содержимого pkg-plist в зависимости от make-переменных]) и `SUB_LIST`. [[java-building-with-ant]] === Построение с Ant Если построение порта производится с использованием Apache Ant, то необходимо определить `USE_ANT`. Таким образом Ant становится подкомандой make. Если в порте не определена цель `do-build`, то будет установлена цель по умолчанию, которая просто запускает Ant в соответствии со значением `MAKE_ENV`, `MAKE_ARGS` и `ALL_TARGET`. Это похоже на механизм `USES= gmake`, который описан в <>. [[java-best-practices]] === Практические рекомендации При портировании Java-библиотеки ваш порт должен устанавливать JAR-файл(ы) в каталог [.filename]#${JAVAJARDIR}#, а все остальные данные в каталог [.filename]#${JAVASHAREDIR}/${PORTNAME}# (за исключением документации, о которой пойдёт речь ниже). Для уменьшения размера упакованного файла вы можете сослаться на JAR-файл(ы) непосредственно в файле [.filename]#Makefile#. Просто воспользуйтесь следующей директивой (в которой [.filename]#myport.jar# является именем JAR-файла, устанавливаемого как часть порта): [.programlisting] .... PLIST_FILES+= %%JAVAJARDIR%%/myport.jar .... При портировании Java-приложения порт обычно устанавливает всё в один каталог (в том числе все свои JAR-зависимости). В этом отношении настоятельно рекомендуется использование [.filename]#${JAVASHAREDIR}/${PORTNAME}#. На усмотрение создателя порта остаётся решение вопроса о том, устанавливать ли дополнительные JAR-зависимости в этот каталог или напрямую использовать уже установленные (из каталога [.filename]#${JAVAJARDIR}#). При портировании приложения Java(TM), для запуска сервиса которого требуется сервер приложений, такой как package:www/tomcat7[], для производителя в порядке вещей является распространение файла [.filename]#.war#. Файл [.filename]#.war# - это Веб-приложение АРхивированное и оно распаковывается при вызове данным приложением. Избегайте добавлять файлы [.filename]#.war# в [.filename]#pkg-plist#. Это не является наилучшим решением. Сервер приложений производит расширение архива [.filename]#war# без должной его очистки при удалении порта. Более подходящим способом работы с этим файлом будет распаковать архив, установить файлы и добавить их в [.filename]#pkg-plist#. [.programlisting] .... TOMCATDIR= ${LOCALBASE}/apache-tomcat-7.0 WEBAPPDIR= myapplication post-extract: @${MKDIR} ${WRKDIR}/${PORTDIRNAME} @${TAR} xf ${WRKDIR}/myapplication.war -C ${WRKDIR}/${PORTDIRNAME} do-install: cd ${WRKDIR} && \ ${INSTALL} -d -o ${WWWOWN} -g ${WWWGRP} ${TOMCATDIR}/webapps/${PORTDIRNAME} @cd ${WRKDIR}/${PORTDIRNAME} && ${COPYTREE_SHARE} \* ${WEBAPPDIR}/${PORTDIRNAME} .... Вне зависимости от типа вашего порта (библиотека это или приложение), дополнительная документация должна устанавливаться <>, что и для других портов. Известно, что в зависимости от используемой версии JDK утилита JavaDoc генерирует различные наборы файлов. Для портов, которые не привязаны к использованию определённой версии JDK, таким образом становится проблематичным определить список файлов для упаковки ([.filename]#pkg-plist#). Это одна из причин, по которой создателям портов настоятельно рекомендуется использовать макрос `PORTDOCS`. Более того, даже если вы сможете угадать набор файлов, который будет сгенерирован утилитой `javadoc`, размер получающегося файла [.filename]#pkg-plist# голосует за использование `PORTDOCS`. -Значением по умолчанию для переменной `DATADIR` является [.filename]#${PREFIX}/shared/${PORTNAME}#. Хорошей идеей является переопределение для Java-портов значения `DATADIR` как [.filename]#${JAVASHAREDIR}/${PORTNAME}#. На самом деле `DATADIR` автоматически добавляется к `PLIST_SUB` (это описано в <>), так что вы сможете использовать `%%DATADIR%%` непосредственно в [.filename]#pkg-plist#. +Значением по умолчанию для переменной `DATADIR` является [.filename]#${PREFIX}/shared/${PORTNAME}#. Хорошей идеей является переопределение для Java-портов значения `DATADIR` как [.filename]#${JAVASHAREDIR}/${PORTNAME}#. На самом деле `DATADIR` автоматически добавляется к `PLIST_SUB` (это описано в crossref:plist[plist-sub,Изменение содержимого pkg-plist в зависимости от make-переменных]), так что вы сможете использовать `%%DATADIR%%` непосредственно в [.filename]#pkg-plist#. Что касается выбора между построением портов Java из исходных текстов или их прямой установкой из бинарных дистрибутивов, то на момент создания этого текста определённой политики на этот счёт не существует. Однако участники http://www.freebsd.org/java/[Проекта FreeBSD Java] рекомендуют создателям портов строить их из исходных текстов, если эта задача является несложной. Все возможности, которые были описаны в этом разделе, реализованы в файле [.filename]#bsd.java.mk#. Если вы предположите, что вашему порту требуется менее тривиальная поддержка Java, пожалуйста, взгляните сначала на http://svnweb.FreeBSD.org/ports/head/Mk/bsd.java.mk?view=markup[журнал изменений bsd.java.mk в Subversion], так как для документирования последних изменений требуется какое-то время. Затем, если вы думаете, что не хватающая вам поддержка окажется полезной для многих других портов Java, обсудите ваш вопрос в freebsd-java. Хотя в базе сообщений об ошибках для соответствующих PR имеется категория `java`, она относится к работе над портированием JDK, которые проводит Проект FreeBSD Java. Таким образом, вы должны относить свой Java-порт, как и любой другой, к категории `ports`, если решаемый вами вопрос не относится ни к реализации JDK, ни к [.filename]#bsd.java.mk#. -Похожим образом определена политика по отношению к `CATEGORIES` порта Java, которая подробно описана в <>. +Похожим образом определена политика по отношению к `CATEGORIES` порта Java, которая подробно описана в crossref:makefiles[makefile-categories, Разделение по категориям]. [[using-php]] == Веб-приложения, Apache и PHP [[using-apache]] === Apache .Переменные для портов, использующих Apache [cols="1,1", frame="none"] |=== |`USE_APACHE` |Порт требует Apache. Возможные значения: `yes` (берёт любую версию), `22`, `24`, `22-24`, `22+` и так далее. Версия по умолчанию `22`. Более подробная информация содержится в файле [.filename]#ports/Mk/bsd.apache.mk# и на странице http://wiki.freebsd.org/Apache/[wiki.freebsd.org/Apache/]. |`APXS` |Полный путь к исполняемому файлу `apxs`. Может быть переопределен в вашем порту. |`HTTPD` |Полный путь к исполняемому файлу `httpd`. Может быть переопределен в вашем порту. |`APACHE_VERSION` |Версия установленного Apache (переменная только для чтения). Эта переменная доступна только после подключения [.filename]#bsd.port.pre.mk#. Возможные значения: `22`, `24`. |`APACHEMODDIR` |Каталог для модулей Apache. Значение переменной автоматически подставляется в [.filename]#pkg-plist#. |`APACHEINCLUDEDIR` |Каталог для заголовков Apache. Значение переменной автоматически подставляется в [.filename]#pkg-plist#. |`APACHEETCDIR` |Каталог для конфигурационных файлов Apache. Значение переменной автоматически подставляется в [.filename]#pkg-plist#. |=== .Используемые переменные при портировании модулей Apache [cols="1,1", frame="none"] |=== |`MODULENAME` |Название модуля. Значением по умолчанию является `PORTNAME`. Пример: `mod_hello` |`SHORTMODNAME` |Краткое название модуля. Наследуется автоматически от `MODULENAME`, но может быть переопределено. Пример: `hello` |`AP_FAST_BUILD` |Использовать `apxs` для компиляции и установки модуля. |`AP_GENPLIST` |Также автоматически создает [.filename]#pkg-plist#. |`AP_INC` |Добавляет каталог к пути поиска заголовков во время компиляции. |`AP_LIB` |Добавляет каталог к пути поиска библиотек во время компиляции. |`AP_EXTRAS` |Дополнительные флаги, передаваемые `apxs`. |=== [[web-apps]] === Веб-приложения Веб-приложения следует устанавливать в [.filename]#PREFIX/www/appname#. Для вашего удобства этот путь одинаково доступен в [.filename]#Makefile# и [.filename]#pkg-plist# как переменная `WWWDIR`, а путь относительно `PREFIX` доступен в [.filename]#Makefile# как `WWWDIR_REL`. Пользователь и группа процесса веб-сервера доступны как `WWWOWN` и `WWWGRP`, в случае если вам нужно изменить владельца для некоторых файлов. Значением по умолчанию и для владельца, и для группы является `www`. Если вы хотите использовать в вашем порте другие значения, воспользуйтесь для этого нотацией `WWWOWN?= myuser`, чтобы позволить пользователю легко переопределить их. Не добавляйте зависимость от Apache, если веб-приложение явным образом не нуждается в Apache. Учитывайте, что пользователи могут пожелать запустить ваше веб-приложение на другом веб-сервере помимо Apache. [[php-variables]] === PHP .Переменные для портов, использующих PHP [cols="1,1", frame="none"] |=== |`USE_PHP` |Порт требует PHP. Значение `yes` добавляет зависимость от PHP. Вместо этого может быть указан перечень требуемых расширений PHP. Пример: `pcre xml gettext` |`DEFAULT_PHP_VER` |Выбирает старший номер версии, с которым будет установлен PHP как зависимость в случае, когда PHP еще не установлен. По умолчанию `5`. Возможные значения: `4`, `5` |`IGNORE_WITH_PHP` |Порт не работает с PHP данной версии. Возможные значения: `4`, `5` |`USE_PHPIZE` |Порт будет построен как расширение PHP. |`USE_PHPEXT` |Порт будет считаться расширением PHP, включая установку и регистрацию в реестре расширений. |`USE_PHP_BUILD` |Установить PHP как зависимость времени построения. |`WANT_PHP_CLI` |Хочет CLI (командная строка) версию PHP. |`WANT_PHP_CGI` |Хочет CGI версию PHP. |`WANT_PHP_MOD` |Хочет PHP как модуль Apache. |`WANT_PHP_SCR` |Хочет CLI или CGI версию PHP. |`WANT_PHP_WEB` |Хочет модуль Apache или CGI версию PHP. |=== === Модули PEAR Портирование модулей PEAR является очень простым процессом. Используйте переменные `FILES`, `TESTS`, `DATA`, `SQLS`, `SCRIPTFILES`, `DOCS` and `EXAMPLES` для перечисления файлов, которые вы хотите установить. Все перечисленные файлы будут автоматически установлены в подходящие места и добавлены в [.filename]#pkg-plist#. Подключите [.filename]#${PORTSDIR}/devel/pear/bsd.pear.mk# на последней строке [.filename]#Makefile#. [[pear-makefile]] .Пример Makefile для классов PEAR [example] ==== [.programlisting] .... PORTNAME= Date PORTVERSION= 1.4.3 CATEGORIES= devel www pear MAINTAINER= example@domain.com COMMENT= PEAR Date and Time Zone Classes BUILD_DEPENDS= ${PEARDIR}/PEAR.php:${PORTSDIR}/devel/pear-PEAR RUN_DEPENDS:= ${BUILD_DEPENDS} FILES= Date.php Date/Calc.php Date/Human.php Date/Span.php \ Date/TimeZone.php TESTS= test_calc.php test_date_methods_span.php testunit.php \ testunit_date.php testunit_date_span.php wknotest.txt \ bug674.php bug727_1.php bug727_2.php bug727_3.php \ bug727_4.php bug967.php weeksinmonth_4_monday.txt \ weeksinmonth_4_sunday.txt weeksinmonth_rdm_monday.txt \ weeksinmonth_rdm_sunday.txt DOCS= TODO _DOCSDIR= . .include .include "${PORTSDIR}/devel/pear/bsd.pear.mk" .include .... ==== [[using-python]] == Использование Python Коллекция Портов поддерживает параллельную установку множества версий Python. Следует убедиться, что в портах используется правильный интерпретатор `python` в соответствии с переменной `PYTHON_VERSION`, установленной пользователем. По большей части это означает замену пути к исполняемому файлу `python` в сценариях на значение переменной `PYTHON_CMD`. Порты, устанавливающие файлы под каталог `PYTHON_SITELIBDIR`, должны использовать префикс вида `pyXY-`, таким образом названия пакетов будут включать в себя версию Python, с которой они установлены. [.programlisting] .... PKGNAMEPREFIX= ${PYTHON_PKGNAMEPREFIX} .... .Переменные для портов, которые используют Python [cols="1,1", frame="none"] |=== |`USE_PYTHON` |Для этого порта нужен Python. Минимальная требуемая версия может быть указана с таким значением как `2.6+`. Также можно указан диапазон версий с разделением двух версий через -, например: `2.6-2.7` |`USE_PYDISTUTILS` |Использовать дистрибутивные утилиты (distutils) Python для конфигурации, компиляции и установки. Необходимо, если порт использует [.filename]#setup.py#. Переопределяет цели `do-build` и `do-install` и также может переопределять `do-configure`, если не определена `GNU_CONFIGURE`. |`PYTHON_PKGNAMEPREFIX` |Используется как `PKGNAMEPREFIX` для отличия пакетов, использующих разные версии Python. Пример: `py24-` |`PYTHON_SITELIBDIR` |Местонахождение дерева site-packages, которое содержит путь установки Python (обычно, `LOCALBASE`). Переменная `PYTHON_SITELIBDIR` может быть очень полезной при установке модулей Python. |`PYTHONPREFIX_SITELIBDIR` |Вариант PYTHON_SITELIBDIR без PREFIX. По возможности всегда используйте `%%PYTHON_SITELIBDIR%%` в [.filename]#pkg-plist#. Значением по умолчанию для `%%PYTHON_SITELIBDIR%%` является `lib/python%%PYTHON_VERSION%%/site-packages`. |`PYTHON_CMD` |Командная строка интерпретатора Python, включая номер версии. |`PYNUMERIC` |Строка зависимости для расширения numeric. |`PYNUMPY` |Строка зависимости для нового расширения numeric, numpy (PYNUMERIC объявлен устаревшим вышестоящим производителем). |`PYXML` |Строка зависимости для расширения XML (не нужно для Python 2.0 и выше, т.к. включено в основной дистрибутив). |=== Полный перечень доступных переменных можно найти в [.filename]#/usr/ports/Mk/bsd.python.mk#. Некоторые приложения на Python заявляют о поддержке `DESTDIR` (требуется для staging), которая не работает (в частности, у Mailman до версии 2.1.16). Ограничение можно обойти путём перекомпиляции сценариев. Например, это можно выполнить в цели `post-build`. С учётом того, что после установки предполагаемое место размещения сценариев Python будет находиться в `PYTHONPREFIX_SITELIBDIR`, можно применить следующее решение: [.programlisting] .... (cd ${STAGEDIR}${PREFIX} \ && ${PYTHON_CMD} ${PYTHON_LIBDIR}/compileall.py \ -d ${PREFIX} -f ${PYTHONPREFIX_SITELIBDIR:S;${PREFIX}/;;}) .... Эта команда перекомпилирует исходный текст с заменой путей на относительные к каталогу сборки, а также дописывает значение `PREFIX` перед именем файла, записанного в выходном файле с промежуточным представлением, с использованием `-d`. `-f` требуется для безусловной перекомпиляции, `:S;${PREFIX}/;;` удаляет префиксы из значения переменной `PYTHONPREFIX_SITELIBDIR`, чтобы сделать его относительным к `PREFIX`. Для этого требуется Python 2.7 или выше. Это не работает с Python 2.6. [[using-tcl]] == Использование Tcl/Tk В Коллекции Портов поддерживается одновременная установка множественных версий Tcl/Tk. Порты должны пытаться поддерживать по крайней мере версию Tcl/Tk, используемую по умолчанию, и выше с помощью переменных `USE_TCL` и `USE_TK`. Желаемую версию `tcl` можно указать в переменной `WITH_TCL_VER`. .Наиболее востребованные переменные для портов, которые используют Tcl/Tk [cols="1,1", frame="none"] |=== |`USE_TCL` |Порт зависит от библиотеки Tcl (не оболочки). Минимальную требуемую версию можно указать с использованием таких значений, как 84+. Отдельные неподдерживаемые версии указываются в переменной `INVALID_TCL_VER`. |`USE_TCL_BUILD` |Tcl нужен для порта только на время сборки. |`USE_TCL_WRAPPER` |Эту новую переменную следует использовать для портов, для которых требуется оболочка Tcl и не требуется конкретная версия `tclsh`. Обертка `tclsh` устанавливается в систему. Пользователь может указать желаемую оболочку `tcl` для использования. |`WITH_TCL_VER` |Определяемые пользователем переменные, которые устанавливают желаемую версию Tcl. |`UNIQUENAME_WITH_TCL_VER` |Подобно `WITH_TCL_VER`, но для каждого порта. |`USE_TCL_THREADS` |Требует многопоточную сборку Tcl/Tk. |`USE_TK` |Порт зависит от библиотеки Tk (не от предпочитаемой оболочки). Подразумевает `USE_TCL` с тем же значением. Для большей информации смотрите описание переменной `USE_TCL`. |`USE_TK_BUILD` |Аналогично `USE_TCL_BUILD`. |`USE_TK_WRAPPER` |Аналогично `USE_TCL_WRAPPER`. |`WITH_TK_VER` |Аналогично `WITH_TCL_VER`, подразумевает `WITH_TCL_VER` той же версии. |=== Полный перечень доступных переменных находится в [.filename]#/usr/ports/Mk/bsd.tcl.mk#. [[using-emacs]] == Использование Emacs Этот раздел ещё предстоит написать. [[using-ruby]] == Использование Ruby .Полезные переменные для портов, использующих Ruby [cols="1,1", frame="none", options="header"] |=== | Переменная | Описание |`USE_RUBY` |Порт требует Ruby. |`USE_RUBY_EXTCONF` |Порт использует для конфигурации [.filename]#extconf.rb#. |`USE_RUBY_SETUP` |Порт использует для конфигурации [.filename]#setup.rb#. |`RUBY_SETUP` |Устанавливает альтернативное имя для [.filename]#setup.rb#. Распространенным значением является [.filename]#install.rb#. |=== Следующая таблица отражает некоторые переменные, доступные авторам портов через инфраструктуру портов. Эти переменные должны использоваться для установки файлов в правильное месторасположение. Используйте их в [.filename]#pkg-plist# как можно больше. Эти переменные не должны переопределяться в самом порте. .Отобранные переменные только для чтения для портов, использующих Ruby [cols="1,1,1", frame="none", options="header"] |=== | Переменная | Описание | Примерное значение |`RUBY_PKGNAMEPREFIX` |Используется как `PKGNAMEPREFIX` для различия пакетов от разных версий Ruby. |`ruby18-` |`RUBY_VERSION` |Полная версия Ruby в форме `x.y.z`. |`1.8.2` |`RUBY_SITELIBDIR` |Путь для установки архитектуронезависимых библиотек. |`/usr/local/lib/ruby/site_ruby/1.8` |`RUBY_SITEARCHLIBDIR` |Путь для установки архитектурозависимых библиотек. |`/usr/local/lib/ruby/site_ruby/1.8/amd64-freebsd6` |`RUBY_MODDOCDIR` |Путь для установки документации модуля. |`/usr/local/shared/doc/ruby18/patsy` |`RUBY_MODEXAMPLESDIR` |Путь для установки примеров модуля. |`/usr/local/shared/examples/ruby18/patsy` |=== Полный перечень доступных переменных находится в [.filename]#/usr/ports/Mk/bsd.ruby.mk#. [[using-sdl]] == Использование SDL Переменная `USE_SDL` используется для автоматической настройки зависимостей для портов, использующих библиотеки на основе SDL, такие как package:devel/sdl12[] или package:graphics/sdl_image[]. Для версии 1.2 на данный момент распознаются следующие SDL-библиотеки: * sdl: package:devel/sdl12[] * console: package:devel/sdl_console[] * gfx: package:graphics/sdl_gfx[] * image: package:graphics/sdl_image[] * mixer: package:audio/sdl_mixer[] * mm: package:devel/sdlmm[] * net: package:net/sdl_net[] * pango: package:x11-toolkits/sdl_pango[] * sound: package:audio/sdl_sound[] * ttf: package:graphics/sdl_ttf[] Для версии 2.0 на данный момент распознаются следующие SDL-библиотеки: * sdl: package:devel/sdl20[] * gfx: package:graphics/sdl2_gfx[] * image: package:graphics/sdl2_image[] * mixer: package:audio/sdl2_mixer[] * net: package:net/sdl2_net[] * ttf: package:graphics/sdl2_ttf[] Таким образом, если порт имеет зависимость от package:net/sdl_net[] и package:audio/sdl_mixer[], то строка будет следующей: [.programlisting] .... USE_SDL= net mixer .... Зависимость от порта package:devel/sdl12[], который требуется для package:net/sdl_net[] и package:audio/sdl_mixer[], будет также автоматически добавлен. Если вы используете `USE_SDL` с элементами SDL 1.2, то он автоматически: * Добавляет зависимость от sdl12-config к `BUILD_DEPENDS` * Добавляет переменную `SDL_CONFIG` к `CONFIGURE_ENV` * Добавляет зависимости от указанных библиотек к `LIB_DEPENDS` Если вы используете `USE_SDL` с элементами SDL 2.0, то он автоматически: * Добавляет зависимость от sdl2-config к `BUILD_DEPENDS` * Добавляет переменную `SDL2_CONFIG` к `CONFIGURE_ENV` * Добавляет зависимости от указанных библиотек к `LIB_DEPENDS` Для проверки наличия библиотеки SDL вы можете делать это при помощи переменной `WANT_SDL`: [.programlisting] .... WANT_SDL= yes .include .if ${HAVE_SDL:Mmixer}!="" USE_SDL+= mixer .endif .include .... [[using-wx]] == Использование wxWidgets Эта глава описывает статус библиотек wxWidgets в дереве портов и их интеграцию с системой портов. [[wx-introduction]] === Введение Существует множество версий библиотек wxWidgets, конфликтующих между собой (устанавливают файлы под тем же именем). В дереве портов эта проблема решена путем установки каждой версии под собственным названием с использованием номера версии в качестве суффикса. Очевидным недостатком этого является необходимость изменения каждого приложения для нахождения искомой версии. К счастью, большинство приложений для определения нужного компилятора и флагов компоновки вызывают сценарий `wx-config`. Для каждой доступной версии этот сценарий имеет своё имя. Большинство приложений учитывают переменную окружения или принимают аргумент configure для указания, какой сценарий `wx-config` следует вызывать. На все остальные приходится накладывать патч. [[wx-version]] === Выбор версии Для того, чтобы заставить ваш порт использовать конкретную версию wxWidgets, существует две доступные для определения переменные (если определена только одна, то вторая примет значение по умолчанию): [[wx-ver-sel-table]] .Переменные для выбора версии wxWidgets [cols="1,1,1", frame="none", options="header"] |=== | Переменная | Описание | Значение по умолчанию |`USE_WX` |Перечень версий, которые порт может использовать |Все доступные версии |`USE_WX_NOT` |Перечень версий, которые порт не может использовать |Нет |=== Перечень доступных версий wxWidgets и соответствующих им портов в дереве: .Доступные версии wxWidgets [cols="1,1", frame="none", options="header"] |=== | Версия | Порт |`2.4` |package:x11-toolkits/wxgtk24[] |`2.6` |package:x11-toolkits/wxgtk26[] |`2.8` |package:x11-toolkits/wxgtk28[] |=== [NOTE] ==== Версии начиная с `2.5` также поставляются с Unicode и устанавливается подчиненным портом с названием как как у обычного, но с суффиксом `-unicode`, но этим можно управлять при помощи переменных (смотрите <>). ==== Переменные в <> можно установить в одну или более следующих комбинаций, разделенных пробелами: .Определение версии для wxWidgets [cols="1,1", frame="none", options="header"] |=== | Описание | Пример |Единичная версия |`2.4` |Восходящий диапазон |`2.4+` |Нисходящий диапазон |`2.6-` |Полный диапазон (обязан быть восходящим) |`2.4-2.6` |=== Кроме того, существует несколько переменных для выбора предпочитаемых версий из перечня доступных. Они могут быть установлены в несколько версий, первая из которых будет иметь наибольший приоритет. .Переменные для выбора предпочитаемых версий wxWidgets [cols="1,1", frame="none", options="header"] |=== | Название | Предназначение |`WANT_WX_VER` |порт |`WITH_WX_VER` |пользователь |=== [[wx-components]] === Выбор компонентов Существуют другие приложения, которые, хотя и не являются библиотеками wxWidgets, но в тоже время относятся к ним. Эти приложения можно указать в переменной `WX_COMPS`. Доступны следующие компоненты: .Доступные компоненты wxWidgets [cols="1,1,1", frame="none", options="header"] |=== | Название | Описание | Ограничение версии |`wx` |основная библиотека |нет |`contrib` |сторонние библиотеки |`нет` |`python` |wxPython (привязки к Python) |`2.4-2.6` |`mozilla` |wxMozilla |`2.4` |`svg` |wxSVG |`2.6` |=== Тип добавляемой зависимости при выборе каждого компонента может быть указан вручную путем добавления суффикса, отделенного точкой с запятой. Если таковой отсутствует, но будет использовано значение по умолчанию (смотрите <>). Доступные типы зависимости: .Доступные типы зависимости wxWidgets [cols="1,1", frame="none", options="header"] |=== | Название | Описание |`build` |Компонент требуется для построения, эквивалентен `BUILD_DEPENDS` |`run` |Компонент требуется для запуска, эквивалентен `RUN_DEPENDS` |`lib` |Компонент требуется для построения и запуска, эквивалентен `LIB_DEPENDS` |=== Значения по умолчанию для компонентов подробно рассматриваются в следующей таблице: [[wx-def-dep-types]] .Типы зависимости wxWidgets, используемые по умолчанию [cols="1,1", frame="none", options="header"] |=== | Компонент | Тип зависимости |`wx` |`lib` |`contrib` |`lib` |`python` |`run` |`mozilla` |`lib` |`svg` |`lib` |=== [[wx-components-example]] .Выбор компонентов wxWidgets [example] ==== Следующий фрагмент относится к порту, в котором используется wxWidgets версии `2.4` с его сторонними библиотеками. [.programlisting] .... USE_WX= 2.4 WX_COMPS= wx contrib .... ==== [[wx-unicode]] === Unicode Библиотека wxWidgets поддерживает Unicode начиная с версии `2.5`. В дереве портов доступны обе версии и могут быть выбраны с использованием следующих переменных: [[wx-unicode-var-table]] .Переменные для выбора версии wxWidgets с Unicode [cols="1,1,1", frame="none", options="header"] |=== | Переменная | Описание | Предназначение |`WX_UNICODE` |Порт работает _только_ с версией Unicode |порт |`WANT_UNICODE` |Порт работает с обеими версиями, но предпочитает версию с Unicode |порт |`WITH_UNICODE` |Порт будет использовать версию Unicode |пользователь |`WITHOUT_UNICODE` |Порт будет использовать обычную версию, если это поддерживается (когда `WX_UNICODE` не определена) |пользователь |=== [WARNING] ==== Не используйте `WX_UNICODE` для портов, которые могут использовать обе версии. Если вы хотите, чтобы порт по умолчанию использовал Unicode, определите вместо этого `WANT_UNICODE`. ==== [[wx-version-detection]] === Обнаружение установленных версий Для обнаружения установленной версии вам необходимо задать переменную `WANT_WX`. Если вы не присвоите ей определенную версию, то компоненты получат суффикс версии. Переменная `HAVE_WX` будет заполнена после обнаружения. [[wx-ver-det-example]] .Обнаружение установленных версий и компонентов wxWidgets [example] ==== Следующий фрагмент может быть использован в порту, который использует wxWidgets, в случае если он установлен или выбран соответствующий параметр. [.programlisting] .... WANT_WX= yes .include .if defined(WITH_WX) || !empty(PORT_OPTIONS:MWX) || !empty(HAVE_WX:Mwx-2.4) USE_WX= 2.4 CONFIGURE_ARGS+= --enable-wx .endif .... Следующий фрагмент может быть использован в порту, который задействует поддержку wxPython, в случае если он установлен или выбран соответствующий параметр, в дополнение к wxWidgets, обе версии `2.6`. [.programlisting] .... USE_WX= 2.6 WX_COMPS= wx WANT_WX= 2.6 .include .if defined(WITH_WXPYTHON) || !empty(PORT_OPTIONS:MWXPYTHON) || !empty(HAVE_WX:Mpython) WX_COMPS+= python CONFIGURE_ARGS+= --enable-wxpython .endif .... ==== [[wx-defined-variables]] === Переменные для определения Следующие переменные доступны в порту (после определения одной из переменных из <>). .Переменные, определенные для портов, использующих wxWidgets [cols="1,1", frame="none", options="header"] |=== | Название | Описание |`WX_CONFIG` |Путь к сценарию wxWidgets `wx-config` (с другим именем) |`WXRC_CMD` |Путь к программе wxWidgets `wxrc` (с другим именем) |`WX_VERSION` |Версия wxWidgets, которая будет использоваться (например, `2.6`) |`WX_UNICODE` |Если не определена, но Unicode будет использоваться, то она будет определена |=== [[wx-premk]] === Обработка в [.filename]#bsd.port.pre.mk# Если вам нужно использовать переменные для запуска команд сразу после подключения [.filename]#bsd.port.pre.mk#, то вам нужно определить `WX_PREMK`. [IMPORTANT] ==== Если вы определите `WX_PREMK`, то версия, зависимости, компоненты и заданные переменные не изменяться, в случае вы изменили переменные порта wxWidgets после подключения [.filename]#bsd.port.pre.mk#. ==== [[wx-premk-example]] .Использование переменных wxWidgets в командах [example] ==== Следующий фрагмент иллюстрирует использование переменной `WX_PREMK` посредством запуска сценария `wx-config` для получения строки с полной версией с присвоением ее переменной и передачей в программу. [.programlisting] .... USE_WX= 2.4 WX_PREMK= yes .include .if exists(${WX_CONFIG}) VER_STR!= ${WX_CONFIG} --release PLIST_SUB+= VERSION="${VER_STR}" .endif .... ==== [NOTE] ==== Переменные wxWidgets можно безопасно использовать в командах внутри целей без необходимости в использовании `WX_PREMK`. ==== [[wx-additional-config-args]] === Дополнительные параметры `configure` Некоторые сценарии GNU `configure` не могут найти wxWidgets только с установленной переменной окружения `WX_CONFIG`, требуя дополнительные параметры. Для их передачи можно использовать переменную `WX_CONF_ARGS`. .Допустимые значения `WX_CONF_ARGS` [cols="1,1", frame="none", options="header"] |=== | Возможное значение | Получаемый параметр |`absolute` |`--with-wx-config=${WX_CONFIG}` |`relative` |`--with-wx=${LOCALBASE} --with-wx-config=${WX_CONFIG:T}` |=== [[using-lua]] == Использование Lua Эта глава описывает статус библиотек Lua в дереве портов и их интеграцию в систему портов. [[lua-introduction]] === Введение Существует множество версий библиотек Lua и соответствующих интерпретаторов, конфликтующих между собой (устанавливают файлы под тем же именем). В дереве портов эта проблема решена путем установки каждой версии в собственное место с использованием номера версии в качестве суффикса. Очевидным недостатком этого является необходимость изменения каждого приложения для нахождения искомой версии. Но это решается добавлением некоторых дополнительных флагов для компилятора и компоновщика. [[lua-version]] === Выбор версии Для того, чтобы заставить ваш порт использовать конкретную версию Lua, существует две доступные для определения переменные (если определена только одна, то вторая примет значение по умолчанию): [[lua-ver-sel-table]] .Переменные для выбора версии Lua [cols="1,1,1", frame="none", options="header"] |=== | Переменная | Описание | Значение по умолчанию |`USE_LUA` |Перечень версий, которые порт может использовать |Все доступные версии |`USE_LUA_NOT` |Перечень версий, которые порт не может использовать |Пусто |=== Перечень доступных версий Lua и соответствующих портов в дереве: .Доступные версии Lua [cols="1,1", frame="none", options="header"] |=== | Версия | Порт |`4.0` |package:lang/lua4[] |`5.0` |package:lang/lua50[] |`5.1` |package:lang/lua[] |=== Переменные из <> могут иметь комбинации из одного или нескольких значений, разделенных пробелом: .Определение версии Lua [cols="1,1", frame="none", options="header"] |=== | Описание | Пример |Единичная версия |`4.0` |Восходящий диапазон |`5.0+` |Нисходящий диапазон |`5.0-` |Полный диапазон (обязан быть восходящим) |`5.0-5.1` |=== Кроме того, существует несколько переменных для выбора предпочитаемых версий из перечня доступных. Они могут быть установлены в несколько версий, первая из которых будет иметь наибольший приоритет. .Переменные для выбора предпочитаемых версий Lua [cols="1,1", frame="none", options="header"] |=== | Название | Предназначение |`WANT_LUA_VER` |порт |`WITH_LUA_VER` |пользователь |=== [[lua-version-example]] .Выбор версии Lua [example] ==== Следующий фрагмент взят из порта, который использует Lua версий `5.0` или `5.1`, по умолчанию `5.0`. Значение может быть переопределено пользователем с использованием переменной `WITH_LUA_VER`. [.programlisting] .... USE_LUA= 5.0-5.1 WANT_LUA_VER= 5.0 .... ==== [[lua-components]] === Выбор компонентов Существуют другие приложения, которые хотя и не являются библиотеками Lua, но относятся к ним. Эти приложения можно указать в переменной `LUA_COMPS`. Доступны следующие компоненты: .Доступные компоненты Lua [cols="1,1,1", frame="none", options="header"] |=== | Название | Описание | Ограничение версии |`lua` |Основная библиотека |нет |`tolua` |Библиотека доступа к коду C/C++ |4.0-5.0 |`ruby` |Привязка к Ruby |4.0-5.0 |=== [NOTE] ==== Есть и другие компоненты, но они относятся к модулям для интерпретатора и не используются приложениями (только другими модулями). ==== Тип зависимости можно выбрать для каждого компонента через добавление суффикса, отделенного точкой с запятой. В случае отсутствия будет использован тип по умолчанию (смотрите <>). Доступные следующие типы: .Доступные типы зависимости Lua [cols="1,1", frame="none", options="header"] |=== | Название | Описание |`build` |Компонент требуется для построения, эквивалентен `BUILD_DEPENDS` |`run` |Компонент требуется для запуска, эквивалентен `RUN_DEPENDS` |`lib` |Компонент требуется для построения и запуска, эквивалентен `LIB_DEPENDS` |=== Значения по умолчанию для компонентов подробно рассматриваются в следующей таблице: [[lua-def-dep-types]] .Типы зависимости Lua, используемые по умолчанию [cols="1,1", frame="none", options="header"] |=== | Компонент | Тип зависимости |`lua` |`lib` для `4.0-5.0` (динамическая) и `build` для `5.1` (статическая) |`tolua` |`build` (статическая) |`ruby` |`lib` (динамическая) |=== [[lua-components-example]] .Выбор компонентов Lua [example] ==== Следующий фрагмент соответствует порту, использующему Lua версии `4.0` и привязку к Ruby. [.programlisting] .... USE_LUA= 4.0 LUA_COMPS= lua ruby .... ==== [[lua-version-detection]] === Обнаружение установленных версий Для обнаружения установленной версии вам необходимо задать переменную `WANT_LUA`. Если вы не присвоите ей определенную версию, то компоненты получат суффикс версии. Переменная `HAVE_LUA` будет заполнена после обнаружения. [[lua-ver-det-example]] .Обнаружение установленных версий и компонентов Lua [example] ==== Следующий фрагмент можно использовать для порта, использующего Lua, если она установлена, или был выбран соответствующий параметр. [.programlisting] .... WANT_LUA= yes .include .if defined(WITH_LUA5) || !empty(PORT_OPTIONS:MLUA5) || !empty(HAVE_LUA:Mlua-5.[01]) USE_LUA= 5.0-5.1 CONFIGURE_ARGS+= --enable-lua5 .endif .... Следующий фрагмент можно использовать для порта, который включает поддержку tolua, если такой компонент установлен, или был выбран соответствующий параметр в дополнение к Lua, оба имеют версию `4.0`. [.programlisting] .... USE_LUA= 4.0 LUA_COMPS= lua WANT_LUA= 4.0 .include .if defined(WITH_TOLUA) || !empty(PORT_OPTIONS:MTOLUA) || !empty(HAVE_LUA:Mtolua) LUA_COMPS+= tolua CONFIGURE_ARGS+= --enable-tolua .endif .... ==== [[lua-defined-variables]] === Переменные для определения Следующие переменные доступны в порту (после определения одной из переменных из <>). .Переменные, определенные для портов, использующих Lua [cols="1,1", frame="none", options="header"] |=== | Название | Описание |`LUA_VER` |Версия Lua, которая будет использоваться (например, `5.1`) |`LUA_VER_SH` |Старший номер версии динамической библиотеки Lua (например, `1`) |`LUA_VER_STR` |Версия Lua без точки (например, `51`) |`LUA_PREFIX` |Префикс, в который установлена Lua (и компоненты) |`LUA_SUBDIR` |Каталог под [.filename]#${PREFIX}/bin#, [.filename]#${PREFIX}/share# и [.filename]#${PREFIX}/lib#, в который установлена Lua |`LUA_INCDIR` |Каталог, в который установлены заголовочные файлы Lua и tolua |`LUA_LIBDIR` |Каталог, в который установлены библиотеки Lua и tolua |`LUA_MODLIBDIR` |Каталог, в который установлены модули библиотеки Lua ([.filename]#.so#) |`LUA_MODSHAREDIR` |Каталог, в который установлены модули Lua ([.filename]#.lua#) |`LUA_PKGNAMEPREFIX` |Префикс с именем пакета, используемый модулями Lua |`LUA_CMD` |Путь к интерпретатору Lua |`LUAC_CMD` |Путь к компилятору Lua |`TOLUA_CMD` |Путь к программе tolua |=== [[lua-variables-example]] .Указание для порта, где искать Lua [example] ==== Следующий фрагмент показывает, как сообщить порту, который использует сценарий configure, где расположены заголовочные файлы и библиотеки Lua. [.programlisting] .... USE_LUA= 4.0 GNU_CONFIGURE= yes CONFIGURE_ENV= CPPFLAGS="-I${LUA_INCDIR}" LDFLAGS="-L${LUA_LIBDIR}" .... ==== [[lua-premk]] === Обработка в [.filename]#bsd.port.pre.mk# Если вам нужно использовать переменные для запуска команд сразу после подключения [.filename]#bsd.port.pre.mk#, для этого вам нужно определить переменную `LUA_PREMK`. [IMPORTANT] ==== Если вы задаете `LUA_PREMK`, то версия, зависимости, компоненты и уже заданные переменные не будут изменены, в случае если вы изменили переменные порта Lua после подключения [.filename]#bsd.port.pre.mk#. ==== [[lua-premk-example]] .Использование переменных Lua в командах [example] ==== Следующий фрагмент иллюстрирует использование `LUA_PREMK` посредством запуска интерпретатора Lua для того, чтобы получить строку с полной версией, сохранить ее в переменную и передать программе. [.programlisting] .... USE_LUA= 5.0 LUA_PREMK= yes .include .if exists(${LUA_CMD}) VER_STR!= ${LUA_CMD} -v CFLAGS+= -DLUA_VERSION_STRING="${VER_STR}" .endif .... ==== [NOTE] ==== Переменные Lua можно безопасно использовать в командах внутри целей без необходимости в использовании `LUA_PREMK`. ==== [[using-iconv]] == Использование `iconv` После 10-08-2013 (link:https://svnweb.freebsd.org/changeset/base/254273[r254273]) в составе FreeBSD 10-CURRENT и более новых версий имеется собственный `iconv`. В более ранних версиях дополнительной зависимостью выступал package:converters/libiconv[]. Для программного обеспечения, которому нужен `iconv`, определите `USES=iconv`. Версии FreeBSD до 10-CURRENT от 13-08-2013 (link:https://svnweb.freebsd.org/changeset/base/254273[r254273]) не имеют собственного `iconv`. На этих более ранных версиях будет автоматически добавлена зависимость от package:converters/libiconv[]. Когда порт задаёт `USES=iconv`, становятся доступными следующие переменные: [.informaltable] [cols="1,1,1,1", frame="none", options="header"] |=== | Имя переменной | Назначение | Значение до FreeBSD 10-CURRENT 254273 (13-08-2013) | Значение после FreeBSD 10-CURRENT 254273 (13-08-2013) |`ICONV_CMD` |Каталог размещения двоичного файла `iconv` |`${LOCALBASE}/bin/iconv` |[.filename]#/usr/bin/iconv# |`ICONV_LIB` |Аргумент `ld` для компоновки с [.filename]#libiconv# (если нужно) |`-liconv` |(пусто) |`ICONV_PREFIX` |Каталог размещения реализации `iconv` (используется для сценариев конфигурации) |`${LOCALBASE}` |[.filename]#/usr# |`ICONV_CONFIGURE_ARG` |Параметр предварительно собранной конфигурации для сценариев конфигурации |`--with-libiconv-prefix=${LOCALBASE}` |(пусто) |`ICONV_CONFIGURE_BASE` |Параметр предварительно собранной конфигурации для сценариев конфигурации |`--with-libiconv=${LOCALBASE}` |(пусто) |=== В следующих двух примерах демонстрируется автоматическое присвоение переменным правильных значений для систем, использующих package:converters/libiconv[] или собственный `iconv`. [[iconv-simple-use]] .Простое использование `iconv` [example] ==== [.programlisting] .... USES= iconv LDFLAGS+= -L${LOCALBASE}/lib ${ICONV_LIB} .... ==== [[iconv-configure-use]] .Использование `iconv` с `configure` [example] ==== [.programlisting] .... USES= iconv CONFIGURE_ARGS+=${ICONV_CONFIGURE_ARG} .... ==== Как показано выше, `ICONV_LIB` имеет пустое значение с собственным `iconv`. Эту особенность можно использовать для обнаружения собственного `iconv` с соответствующими действиями. Иногда в программе параметр `ld` или путь поиска жёстко заданы в [.filename]#Makefile# или сценарии конфигурации. Для решения этой проблемы можно использовать следующий подход: [[iconv-reinplace]] .Исправление жёстко заданного `-liconv` [example] ==== [.programlisting] .... USES= iconv post-patch: @${REINPLACE_CMD} -e 's/-liconv/${ICONV_LIB}/' ${WRKSRC}/Makefile .... ==== В некоторых случаях необходимо установить альтернативные значения или выполнить операции в случае использования собственного `iconv`. Перед проверкой значения `ICONV_LIB` обязан быть подключён [.filename]#bsd.port.pre.mk#: [[iconv-conditional]] .Проверка доступности собственного `iconv` [example] ==== [.programlisting] .... USES= iconv .include post-patch: .if empty(ICONV_LIB) # обнаружен собственный iconv @${REINPLACE_CMD} -e 's|iconv||' ${WRKSRC}/Config.sh .endif .include .... ==== [[using-xfce]] == Использование Xfce Переменная `USE_XFCE` используется для автоматической конфигурации зависимостей для портов, использующих библиотеки или приложения на основе Xfce, такие как package:x11-toolkits/libxfce4gui[] и package:x11-wm/xfce4-panel[]. В настоящее время распознаются следующие библиотеки и приложения Xfce: * libexo: package:x11/libexo[] * libgui: package:x11-toolkits/libxfce4gui[] * libutil: package:x11/libxfce4util[] * libmcs: package:x11/libxfce4mcs[] * mcsmanager: package:sysutils/xfce4-mcs-manager[] * panel: package:x11-wm/xfce4-panel[] * thunar: package:x11-fm/thunar[] * wm: package:x11-wm/xfce4-wm[] * xfdev: package:dev/xfce4-dev-tools[] Распознаются следующие дополнительные параметры: * configenv: Используйте, если ваш порт требует специально измененного значения `CONFIGURE_ENV` для поиска требуемых для порта библиотек. + [.programlisting] .... -I${LOCALBASE}/include -L${LOCALBASE}/lib .... + добавляется в CPPFLAGS к `CONFIGURE_ENV`. Следовательно, если у порта имеется зависимость от package:sysutils/xfce4-mcs-manager[], и порт требует специальных CPPFLAGS в своем окружении configure, то синтаксис будет следующим: [.programlisting] .... USE_XFCE= mcsmanager configenv .... [[using-mozilla]] == Использование Mozilla .Переменные для портов, использующих Mozilla [cols="1,1", frame="none"] |=== |`USE_GECKO` |Один из бэкэндов Gecko, с которым может работать порт. Возможные значения: `libxul` ([.filename]#libxul.so#), `seamonkey` ([.filename]#libgtkembedmoz.so#, устаревший, больше не должен использоваться). |`USE_FIREFOX` |Для запуска порта требуется Firefox. Возможные значения: `yes` (версия по умолчанию), `40`, `36`, `35`. По умолчанию устанавливает зависимость от версии `40`. |`USE_FIREFOX_BUILD` |Для построения порта требуется Firefox. Возможные значения: смотрите USE_FIREFOX. Автоматически устанавливает USE_FIREFOX с присвоением того же значения. |`USE_SEAMONKEY` |Для запуска порта требуется SeaMonkey. Возможные значения: `yes` (версия по умолчанию), `20`, `11` (устарело, больше не должно использоваться). По умолчанию устанавливает зависимость от версии `20`. |`USE_SEAMONKEY_BUILD` |Для построения порта требуется SeaMonkey. Возможные значения: смотрите USE_SEAMONKEY. Автоматически устанавливает USE_SEAMONKEY с присвоением того же значения. |`USE_THUNDERBIRD` |Для запуска порта требуется Thunderbird. Возможные значения: `yes` (версия по умолчанию), `31`, `30` (устарело, больше не должно использоваться). По умолчанию устанавливает зависимость от версии `31`. |`USE_THUNDERBIRD_BUILD` |Для построения порта требуется Thunderbird. Возможные значения: смотрите USE_THUNDERBIRD. Автоматически устанавливает USE_THUNDERBIRD с присвоением того же значения. |=== Полный перечень доступных переменных можно получить в файле [.filename]#/usr/ports/Mk/bsd.gecko.mk#. [[using-databases]] == Использование баз данных .Переменные для портов, использующих базы данных [cols="1,1", frame="none", options="header"] |=== | Переменная | Значение |`USE_BDB` |Если переменная установлена в `yes`, добавляет зависимость от порта package:databases/db41[]. Также переменной можно присвоить значения: 2, 3, 40, 41, 42, 43, 44, 46, 47, 48 или 51. Вы можете объявить диапазон принимаемых значений, `USE_BDB`=42+ будет искать установленную версию с наибольшим номером, и, если ничего не установлено, вернется к 42. |`USE_MYSQL` |Если переменная установлена в `yes`, добавляет зависимость от порта package:databases/mysql55-client[]. Как связанная переменная, `WANT_MYSQL_VER` может быть установлена в значение 323, 40, 41, 50, 51, 52, 55 или 60. |`USE_PGSQL` |Если установлена в `yes`, добавляет зависимость от порта package:databases/postgresql90-client[]. Как связанная переменная, `WANT_PGSQL_VER` может быть установлена в значение 83, 84, 90, 91 или 92. Вы можете указать максимальное и минимальное значения; `WANT_PGSQL_VER=90+` сделает порт зависимым от минимальной версии 9.0. |`USE_SQLITE` |Если переменная имеет значение `yes`, добавляет зависимость от порта package:databases/sqlite3[]. Переменная может принимать значения: 3, 2. |=== Подробнее смотрите в http://svnweb.FreeBSD.org/ports/head/Mk/bsd.database.mk?view=markup[bsd.database.mk]. [[rc-scripts]] == Запуск и остановка служб (сценарии `rc`) Сценарии [.filename]#rc.d# используются для запуска служб при запуске системы и дают администратору стандартный способ остановки, запуска и перезапуска службы. Порты интегрируются в системную инфраструктуру [.filename]#rc.d#. Подробности по её использованию можно найти в extref:{handbook}config-tuning/[главе rc.d Руководства, configtuning-rcd]. Подробное объяснение доступных команд находится в man:rc[8] и man:rc.subr[8]. Наконец, есть extref:{rc-scripting}[статья]о практических аспектах написания сценариев [.filename]#rc.d#. Установить можно один или более сценариев [.filename]#rc.d#: [.programlisting] .... USE_RC_SUBR= doormand .... Сценарии обязаны размещаться в подкаталоге [.filename]#files# с обязательным добавлением суффикса `.in` к имени файла. Для этого файла будут использоваться стандартные расширения `SUB_LIST`. Также особенно приветствуется использование расширений `%%PREFIX%%` и `%%LOCALBASE%%`. Подробнее о `SUB_LIST` в <>. Начиная с FreeBSD 6.1-RELEASE локальные сценарии [.filename]#rc.d# (включая установленные из портов) включены в общий man:rcorder[8] основной системы. Пример простого сценария [.filename]#rc.d#: [.programlisting] .... #!/bin/sh # $FreeBSD$ # # PROVIDE: doormand # REQUIRE: LOGIN # KEYWORD: shutdown # # Add the following lines to /etc/rc.conf.local or /etc/rc.conf # to enable this service: # # doormand_enable (bool): Set to NO by default. # Set it to YES to enable doorman. # doormand_config (path): Set to %%PREFIX%%/etc/doormand/doormand.cf # by default. . /etc/rc.subr name=doormand rcvar=doormand_enable load_rc_config $name : ${doormand_enable:="NO"} : ${doormand_config="%%PREFIX%%/etc/doormand/doormand.cf"} command=%%PREFIX%%/sbin/${name} pidfile=/var/run/${name}.pid command_args="-p $pidfile -f $doormand_config" run_rc_command "$1" .... Если нет стоящей причины запускать службы раньше всех портов, сценарии должны использовать [.programlisting] .... REQUIRE: LOGIN .... Если служба работает под определенным пользователем (отличным от root), то это делается принудительно. В сценарий выше включена конструкция [.programlisting] .... KEYWORD: shutdown .... потому что вымышленный порт, который мы используем в качестве примера, запускает службу, и она должна корректно завершиться при выключении системы. Если сценарий не запускает постоянную службу, то это не является необходимым. Для необязательных элементов конфигурации присвоение переменной по умолчанию в стиле "=" является более предпочтительным по сравнению со стилем ":=", используемым здесь, поскольку первый устанавливает значение по умолчанию только если переменная не установлена, а последний устанавливает её, если переменная не установлена _или_ обнулена. Пользователь вполне может написать в своем файле [.filename]#rc.conf.local# что-нибудь типа [.programlisting] .... doormand_flags="" .... и тогда произойдет неуместная подстановка переменной с использованием ":=", что переопределит намерения пользователя. Переменная `_enable` является обязательной; значением по умолчанию должно быть ":". === Контрольный список перед внесением изменений Перед тем, как отсылать порт со сценарием [.filename]#rc.d#, и тем более перед его коммитом, сверьтесь со следующим контрольным списком, чтобы убедиться, что порт для этого готов. Большинство из этих проверок умеет выполнять порт package:devel/rclint[], но это не является заменой надлежащему просмотру. [.procedure] ==== . Если это новый файл, заканчивается ли он на [.filename]#.sh#? Если это так, то имя файла должно быть изменено на [.filename]#file.in#, поскольку файлы [.filename]#rc.d# не могут оканчиваться на такое расширение. . Присутствует ли в файле тег `$FreeBSD$`? . Соответствуют ли друг другу имя файла (без [.filename]#.in#), строка `PROVIDE` и ``$``__name__? Имя файла, совпадающее с `PROVIDE`, упрощает отладку, особенно для проблем, связанных с man:rcorder[8]. Соответствие имени файла и ``$``__name__ также упрощает понимание, какие переменные имеют отношение к сценарию в [.filename]#rc.conf[.local]#. Последнее также является тем, что вы могли бы назвать "политикой" для всех новых сценариев, включая те, что входят в базовую систему. . Содержит ли строка `REQUIRE` значение LOGIN? Это условие обязательно для сценариев, работающих не из-под суперпользователя. Если сценарий запускается из-под суперпользователя, то стоит ли его запускать до `LOGIN`? Если нет, то его следует запускать после, так чтобы мы могли свободно сгруппировать локальные сценарии в той точке man:rcorder[8], когда почти все сценарии в базовой системе уже стартовали. . Запускает ли сценарий постоянную службу? Если да, то он должен иметь `KEYWORD: shutdown`. . Убедитесь в том, что в сценарии отсутствует `KEYWORD: FreeBSD`. Это перестало быть нужным и нежелательно уже много лет. Это также служит индикатором того, что новый сценарий был скопирован со старого, поэтому особое внимание должно быть уделено при проверке. . Если сценарий использует интерпретируемый язык, такой как `perl`, `python` или `ruby`, то убедитесь, что значение `command_interpreter` установлено должным образом. В противном случае + [source,shell] .... # service name stop .... + возможно будет работать неправильно. Смотрите man:service[8] для дополнительной информации. . Все ли вхождения [.filename]#/usr/local# были заменены на `%%PREFIX%%`? . Идет ли присвоение переменным значений по умолчанию после `load_rc_config`? . Используются ли пустые строки при присвоении значений по умолчанию? Такие присвоения должны быть удалены, но перепроверьте, что эти параметры задокументированы в комментариях в начале файла. . Действительно ли в сценариях используются значения, присвоенные переменным? . Являются ли параметры по умолчанию, перечисленные в __name__``_flags``, обязательными? Если это так, то их следует поместить в `command_args`. Параметр `-d` здесь - это как красный флаг (прошу прощения за каламбур), поскольку обычно он применяется для "демонизации" процесса и поэтому на самом деле обязательный. . Никогда не включайте переменную __name__``_flags`` в `command_args` (и наоборот; в прочем, такая ошибка встречается реже). . Запускает ли сценарий какой-либо код безусловно? Это нехорошо. Обычно такие вещи могут/должны помещаться в `start_precmd`. . Все логические условия должны использовать функцию `checkyesno`. Не пишите самописных проверок для `[Yy][Ee][Ss]`, и так далее. . Если в сценарии выполняется цикл (например, ожидание чего-либо перед стартом), используется ли счетчик для завершения цикла? Мы не хотим бесконечного ожидания загрузки в случае возникновения ошибки. . Создает ли сценарий файлы или каталоги, которым нужны особые права доступа? Например, файл [.filename]#pid#, который должен принадлежать пользователю, из-под которого запускается процесс. Вместо традиционных команд man:touch[1]/man:chown[8]/man:chmod[1] подумайте об использовании man:install[1] с подходящими аргументами командной строки, для того чтобы выполнить всю процедуру за один шаг. ==== [[users-and-groups]] == Добавление пользователей и групп Некоторые порты требуют в установленной системе наличие определенного пользователя. Выберите свободный UID в диапазоне от 50 до 999 и зарегистрируйте его в [.filename]#ports/UIDs# (для пользователей) и/или в [.filename]#ports/GIDs# (для групп). Удостоверьтесь, что не используете UID, уже используемый системой или другими портами. Пожалуйста, включите в патч изменение для этих двух файлов, если вам требуется создать нового пользователя или группу для вашего порта. Затем вы сможете использовать в вашем [.filename]#Makefile# переменные `USERS` и `GROUPS`, и пользователь автоматически создастся при установке порта. [.programlisting] .... USERS= pulse GROUPS= pulse pulse-access pulse-rt .... Текущий перечень зарезервированных UID и GID находится в [.filename]#ports/UIDs# и [.filename]#ports/GIDs#. [[requiring-kernel-sources]] == Порты, требующие наличия исходных текстов ядра Некоторым портам (таким как загружаемые модули ядра) для компиляции нужны файлы с исходными текстами ядра. Ниже указан корректный способ определения, установлены ли они пользователем: [.programlisting] .... USES= kmod .... Кроме этой проверки, `kmod` заботится о большинстве пунктов, которые должны учитываться в этих портах. diff --git a/documentation/content/ru/books/porters-handbook/testing/chapter.adoc b/documentation/content/ru/books/porters-handbook/testing/_index.adoc similarity index 92% rename from documentation/content/ru/books/porters-handbook/testing/chapter.adoc rename to documentation/content/ru/books/porters-handbook/testing/_index.adoc index 98b7c82e1f..a40e23725e 100644 --- a/documentation/content/ru/books/porters-handbook/testing/chapter.adoc +++ b/documentation/content/ru/books/porters-handbook/testing/_index.adoc @@ -1,130 +1,130 @@ --- title: Глава 9. Тестирование вашего порта prev: books/porters-handbook/pkg-files next: books/porters-handbook/upgrading --- [[testing]] = Тестирование вашего порта :doctype: book :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :sectnumoffset: 9 :partnums: :source-highlighter: rouge :experimental: :images-path: books/porters-handbook/ ifdef::env-beastie[] ifdef::backend-html5[] :imagesdir: ../../../../images/{images-path} endif::[] ifndef::book[] include::shared/authors.adoc[] include::shared/mirrors.adoc[] include::shared/releases.adoc[] include::shared/attributes/attributes-{{% lang %}}.adoc[] include::shared/{{% lang %}}/teams.adoc[] include::shared/{{% lang %}}/mailing-lists.adoc[] include::shared/{{% lang %}}/urls.adoc[] toc::[] endif::[] ifdef::backend-pdf,backend-epub3[] include::../../../../../shared/asciidoctor.adoc[] endif::[] endif::[] ifndef::env-beastie[] toc::[] include::../../../../../shared/asciidoctor.adoc[] endif::[] [[make-describe]] == Запуск `make describe` Некоторые утилиты FreeBSD для сопровождения портов, например, man:portupgrade[1], опираются на базу данных с именем [.filename]#/usr/ports/INDEX#, в которой отслеживаются такие характеристики портов, как их зависимости. Файл [.filename]#INDEX# создаётся при помощи [.filename]#ports/Makefile# верхнего уровня по команде `make index`, спускающейся в подкаталог каждого порта и выполняющей в нём `make describe`. Таким образом, если выполнение `make describe` с каким-либо портом завершится неудачно, то никому не удастся создать [.filename]#INDEX#, при этом много людей вскоре станут несчастны. [NOTE] ==== -Возможность генерировать этот файл очень важна вне зависимости от того, какие параметры присутствуют в [.filename]#make.conf#, поэтому, пожалуйста, избегайте, таких вещей, как использование декларации `.error`, когда (к примеру) требования к зависимости не было удовлетворено. (Смотрите <>.) +Возможность генерировать этот файл очень важна вне зависимости от того, какие параметры присутствуют в [.filename]#make.conf#, поэтому, пожалуйста, избегайте, таких вещей, как использование декларации `.error`, когда (к примеру) требования к зависимости не было удовлетворено. (Смотрите crossref:porting-dads[dads-dot-error, Избегайте использования конструкции `.error`].) ==== Если `make describe` выдаёт строчку, а не ошибку, то для вас это пройдёт безболезненно. Обратитесь к файлу [.filename]#bsd.port.mk#, чтобы выяснить значение выдаваемых строк. Заметьте также, что запуск последней версии `portlint` (как указано в следующем разделе) приведёт к автоматическому запуску команды `make describe`. [[testing-portlint]] == Portlint -Проверьте свою работу командой <> перед тем, как её отослать или перенести в дерево портов. `portlint` предупреждает вас о многих распространённых ошибках, как функциональных, так и стилистических. Для нового (или скопированного внутри хранилища) порта самым подходящим является запуск `portlint -A`; для уже существующего порта достаточно будет запустить `portlint -C`. +Проверьте свою работу командой crossref:quick-porting[porting-portlint,`portlint`] перед тем, как её отослать или перенести в дерево портов. `portlint` предупреждает вас о многих распространённых ошибках, как функциональных, так и стилистических. Для нового (или скопированного внутри хранилища) порта самым подходящим является запуск `portlint -A`; для уже существующего порта достаточно будет запустить `portlint -C`. Так как для обнаружения ошибок `portlint` использует эвристические методы, то им могут выдаваться и ошибочные предупреждения. Кроме того, время от времени нечто, отмечаемое как некорректность, из-за ограничений механизма создания портов не может быть сделано никак иначе. Если вы сомневаетесь, то лучше всего спросить в {freebsd-ports}. [[testing-porttools]] == Port Tools Программа package:ports-mgmt/porttools[] входит в состав Коллекции Портов. `port` является сценарием переднего плана, который может упростить вам задачу тестирования. Если вы хотите проверить новый порт или обновить существующий, то вы можете использовать `port test` для проверки вашего порта, включая проверку <>. Эта команда также находит и отображает любые файлы, которые невключенные в [.filename]#pkg-plist#. Смотрите следующий пример: [source,shell] .... # port test /usr/ports/net/csup .... [[porting-prefix]] == `PREFIX` и `DESTDIR` Переменная `PREFIX` определяет, куда будет установлен порт. По умолчанию это [.filename]#/usr/local#, но может меняться пользователем на собственный путь, такой как [.filename]#/opt#. В вашем порту значение этой переменной должно учитываться. Если пользователь установил переменную `DESTDIR`, то она определяет полное альтернативное окружение, обычно, это jail или установленная система, смонтированная в месте, отличном от [.filename]#/#. На самом деле порт устанавливается в [.filename]#DESTDIR/PREFIX# и регистрируется в базе данных пакетов в [.filename]#DESTDIR/var/db/pkg#. Поскольку управление `DESTDIR` производится автоматически инфраструктурой портов с помощью man:chroot[8], вам не нужны никакие изменения или проявление особой осторожности при написании портов, совместымых с `DESTDIR`. Значение переменной `PREFIX` будет установлено в `LOCALBASE` (по умолчанию [.filename]#/usr/local#). Если задана переменная `USE_LINUX_PREFIX`, то `PREFIX` примет значение `LINUXBASE` (по умолчанию [.filename]#/compat/linux#). Избегание явно прописываемых путей [.filename]#/usr/local# в исходном коде сделает порт гораздо более гибким и способным удовлетворить потребности других серверов. Часто этого можно добиться простой заменой строк [.filename]#/usr/local# в различных файлах [.filename]#Makefile# внутри порта на `${PREFIX}`. Эта переменная автоматически передаётся далее на каждом этапе построения и установки. Проверьте, что ваше приложение не устанавливает чего-либо в каталог [.filename]#/usr/local# вместо `PREFIX`. Наличие явно указанных путей можно быстро проверить следующим образом: [source,shell] .... # make clean; make package PREFIX=/var/tmp/`make -V PORTNAME` .... Если что-то было установлено за пределами `PREFIX`, то процесс создания пакета сообщит об отсутствии файлов. -Это также стоит проверить с использованием поддержки каталога сборки (смотрите <>): +Это также стоит проверить с использованием поддержки каталога сборки (смотрите crossref:special[staging, Staging]): [source,shell] .... # make stage && make check-orphans && make package .... Эти проверки не найдут явно указанных путей внутри файлов порта и не проверят корректность использования `LOCALBASE` в качестве ссылки на файлы из других портов. Порт, временно установленный в [.filename]#/var/tmp/`make -V PORTNAME`#, следует проверять на работоспособность, чтобы убедиться в отсутствии проблем с путями. Переменная `PREFIX` не должна задаваться явно в файле [.filename]#Makefile# порта. Пользователи при установке порта могут задать в `PREFIX` свое собственное место, и порт должен учитывать это значение. Обратитесь к программам/файлам из других портов с переменными, перечисленными выше, без указания явных маршрутов. Например, если ваш порт требует, чтобы макрос `PAGER` являлся полным путем утилиты `less`, не используйте строковый путь [.filename]#/usr/local/bin/less#. Вместо этого используйте `${LOCALBASE}`: [.programlisting] .... -DPAGER=\"${LOCALBASE}/bin/less\" .... Путь с использованием `LOCALBASE` имеет больше шансов оставаться работоспособным, если системный администратор переместил всё дерево [.filename]#/usr/local# куда-то в другое место. [[testing-tinderbox]] == Tinderbox Если вы алчный контрибутор портов, то вы можете захотеть взглянуть на Tinderbox. Это мощная система построения и тестирования портов. Tinderbox можно установить, используя порт package:ports-mgmt/tinderbox[]. Обязательно прочитайте поставляемую документацию, поскольку конфигурация не является тривиальной. Для получения подробностей посетите http://tinderbox.marcuscom.com/[вебсайт Tinderbox]. [[testing-poudriere]] == Poudriere Если вы контрибутор портов, подумайте об установке poudriere. Это мощная система для построения и тестирования портов. Poudriere можно установить из package:ports-mgmt/poudriere[]. Для получения подробной информации посетите http://fossil.etoilebsd.net/poudriere[вебсайт Poudriere]. diff --git a/documentation/content/ru/books/porters-handbook/upgrading/chapter.adoc b/documentation/content/ru/books/porters-handbook/upgrading/_index.adoc similarity index 98% rename from documentation/content/ru/books/porters-handbook/upgrading/chapter.adoc rename to documentation/content/ru/books/porters-handbook/upgrading/_index.adoc index 8996df3362..6314418994 100644 --- a/documentation/content/ru/books/porters-handbook/upgrading/chapter.adoc +++ b/documentation/content/ru/books/porters-handbook/upgrading/_index.adoc @@ -1,178 +1,178 @@ --- title: Глава 10. Обновление отдельного порта prev: books/porters-handbook/testing next: books/porters-handbook/security --- [[port-upgrading]] = Обновление отдельного порта :doctype: book :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :sectnumoffset: 10 :partnums: :source-highlighter: rouge :experimental: :images-path: books/porters-handbook/ ifdef::env-beastie[] ifdef::backend-html5[] :imagesdir: ../../../../images/{images-path} endif::[] ifndef::book[] include::shared/authors.adoc[] include::shared/mirrors.adoc[] include::shared/releases.adoc[] include::shared/attributes/attributes-{{% lang %}}.adoc[] include::shared/{{% lang %}}/teams.adoc[] include::shared/{{% lang %}}/mailing-lists.adoc[] include::shared/{{% lang %}}/urls.adoc[] toc::[] endif::[] ifdef::backend-pdf,backend-epub3[] include::../../../../../shared/asciidoctor.adoc[] endif::[] endif::[] ifndef::env-beastie[] toc::[] include::../../../../../shared/asciidoctor.adoc[] endif::[] Если вы заметите, что ваш порт устарел по сравнению с последней авторской версией, первым делом вы должны получить самую последнюю версия порта. Вы можете найти их в каталоге [.filename]#ports/ports-current# на зеркальных FTP-серверах FreeBSD. Однако если вы работаете с достаточно большим количеством портов, наверное, будет проще использовать Subversion или man:portsnap[8] для поддержания всей коллекции портов в актуальном состоянии, как это описано в extref:{handbook}ports/[Руководстве, ports-using]. К тому же это даст возможность отслеживать все зависимости портов. На следующем шаге необходимо выяснить, нет ожидает ли уже это обновление своей очереди. Для этого у вас есть две возможности. Существует интерфейс к http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query[базе данных сообщений о проблемах FreeBSD (PR)] (известной также как `GNATS`) с поисковыми возможностями. Выберите из выпадающего списка `ports` и введите название порта. Однако иногда люди забывают поместить название порта в поле Synopsis в точном виде. В таком случае вы можете воспользоваться <> (которая известна также как `portsmon`). В рамках этой системы делается попытка классифицировать PR, касающиеся портов, по имени порта. Для поиска PR, относящихся к определённому порту, используйте механизм http://portsmon.FreeBSD.org/portoverview.py[Просмотра по одному порту]. Если таких отложенных PR не существует, то на следующем этапе следует послать сообщение электронной почты человеку, поддерживающему порт, который выдаётся по команде `make maintainer`. Этот человек может уже работать над обновлением, или иметь причину не обновлять порт прямо сейчас (например, из-за проблем со стабильностью функционирования новой версии); вам нет нужды дублировать их работу. Заметьте, что неподдерживаемые порты перечисляются с адресом сопровождающего `ports@FreeBSD.org`, который является всего лишь адресом общего списка рассылки, так что отправка туда сообщений, скорее всего, в данном случае не поможет. Если сопровождающий просит вас выполнить обновление, либо сопровождающий отсутствует, то у вас появляется шанс помочь FreeBSD, приготовив обновление самим! Пожалуйста, делайте это с использованием команды man:diff[1] в основной системе. Чтобы создать подходящий `diff` для одного патча, скопируйте файл, который нужно пропатчить, в _something.orig_, сохраните ваши изменения в _something_, а затем создайте ваше патч: [source,shell] .... % diff -u something.orig something > something.diff .... В противном случае, вам следует воспользоваться методом `svn diff` (<>), либо скопировать содержимое порта в отдельный каталог и применить результат рекурсивной команды man:diff[1] между новым и старым каталогами порта (например, если каталог с модифицированным портом называется [.filename]#superedit#, а оригинальный, совпадающий с находящимся в нашем дереве портов, [.filename]#superedit.bak#, то сохраните результат выполнения команды `diff -ruN superedit.bak superedit`). Подойдёт как унифицированный, так и контекстный дифф, однако коммиттеры портов обычно предпочитают унифицированный формат. Отметьте использование опции `-N`-это одобряемый способ заставить diff корректно работать в случае добавления новых файлов или удаления старых. Перед тем, как посылать нам diff-файл, пожалуйста, проверьте его, чтобы убедиться в значимости всех внесённых изменений. (В частности, убедитесь, что вы очистили рабочие каталоги командой `make clean`). Для упрощения повторяющихся операций с файлами заплаток вы можете воспользоваться скриптом [.filename]#/usr/ports/Tools/scripts/patchtool.py#. Перед тем, как его запускать, пожалуйста, прочтите [.filename]#/usr/ports/Tools/scripts/README.patchtool#. Если порт никем не поддерживается, а вы активно его используете, пожалуйста, подумайте над тем, чтобы добровольно стать его сопровождающим. Во FreeBSD имеется более 4000 портов без поддержки, и это как раз та область, где всегда нужны добровольцы. (Детальное описание обязанностей сопровождающего можно найти в разделе extref:{developers-handbook}[Руководства Разработчика, POLICIES-MAINTAINER].) Лучше всего послать нам diff-файл, включив его в посылку по команде man:send-pr[1] (категория `ports`). Если вы сопровождаете порт, обязательно поместите текст `[maintainer update]` в начале строки описания и задайте в поле "Class" вашего PR строчку `maintainer-update`. В противном случае в поле "Class" вашего PR должно быть указано `change-request`. Будьте добры, в сообщении отметьте все добавленные или удалённые файлы, так как они будут непосредственно указаны man:svn[1] при выполнении операции коммита. Если diff-файл имеет размер, превышающий 20КБ, сожмите его и обработайте утилитой uuencode; в противном случае просто включите его как есть в PR. Прежде чем пользоваться man:send-pr[1] просмотрите раздел о extref:{problem-reports}[Написании сообщений о проблемах, pr-writing] в статье о Сообщениях об ошибках. Он содержит гораздо больше информации о том, как писать полезные сообщения о проблемах. [IMPORTANT] ==== Если обновление вызвано соображениями информационной безопасности или наличием серьёзных ошибок в имеющемся порте, пожалуйста, оповестите {portmgr} о необходимости немедленного перепостроения и повторного распространения пакета данного порта. В противном случае ничего не подозревающие пользователи `pkg` будут продолжать устанавливать старую версию по команде `pkg install` в течение ещё нескольких недель. ==== [NOTE] ==== Повторяем еще раз - для посылки обновлений существующих портов используйте утилиту man:diff[1], а не man:shar[1]! Это поможет понять коммиттерам портов, что именно было изменено. ==== -Теперь, когда вы проделали всё это, прочитайте о том, как поддерживать актуальное состояние, в <>. +Теперь, когда вы проделали всё это, прочитайте о том, как поддерживать актуальное состояние, в crossref:keeping-up[keeping-up, Актуализация]. [[svn-diff]] == Использование Subversion для создания патчей По возможности присылайте исправления в формате man:svn[1] diff. В таком виде их проще использовать по сравнению с разницей между "старым и новым" каталогами. Так проще увидеть изменения и обновить их в случае, если что-нибудь изменилось в Коллекции Портов с тех пор, как вы начали работу, либо если коммиттер просит что-то исправить. [source,shell] .... % cd ~/my_wrkdir <.> % svn co https://svn0.us-west.FreeBSD.org/ports/head/dns/pdnsd <.> % cd ~/my_wrkdir/pdnsd .... <.> Это может быть где угодно; место, в котором производится построение портов, не привязано к [.filename]#/usr/ports/#. <.> https://svn0.us-west.FreeBSD.org/[svn0.us-west.FreeBSD.org] - это общедоступный сервер Subversion. Выберите ближайшее зеркало и проверьте сертификат зеркалирующего сервера на наличие в перечне extref:{handbook}mirrors/[зеркалирующих сайтов Subversion, svn-mirrors]. Находясь в рабочем каталоге, вносите любые изменения, которые обычно делают для порта. При добавлении или удалении файла используйте `svn` для отслеживания этих изменений: [source,shell] .... % svn add new_file % svn remove deleted_file .... -Убедитесь, что вы проверяете порт в соответствии с рекомендуемым порядком проверки, описанным в <> и <>. +Убедитесь, что вы проверяете порт в соответствии с рекомендуемым порядком проверки, описанным в crossref:quick-porting[porting-testing, Тестирование порта] и crossref:quick-porting[porting-portlint, Проверка вашего порта утилитой `portlint`]. [source,shell] .... % svn status % svn update <.> .... <.> Эта команда попытается выполнить слияние различий между вашим патчем и текущей версией репозитория; внимательно проверьте полученный вывод. Буква перед названием каждого файла означает тип изменения, сделанного с этим файлом. Для получения полного списка смотрите <>. [[table-svn-up]] .Префиксы файлов для Subversion Update [cols="1,1", frame="none"] |=== |U |Файл обновлен без проблем. |G |Файл обновлен без проблем (вы увидите это только при работе с удаленным репозиторием). |M |Файл с локальными изменениями, слияние выполнено без конфликтов. |C |Файл с локальными изменениями, слияние выполнено с конфликтами. |=== Если в результате выполнения `svn update` отображается `C`, то это означает, что что-то изменилось в репозитории Subversion и man:svn[1] не смогла выполнить слияние локальных изменений с полученными из репозитория. В любом случае никогда не помешает просмотреть изменения, поскольку man:svn[1] ничего не знает о том, каким должен быть порт, поэтому эта команда может (и, вероятно, будет) делать слияние тех изменений, которые не имеют смысла. Последним шагом является создание унифицированного man:diff[1] для полученных изменений: [source,shell] .... % svn diff > ../`basename ${PWD}`.diff .... [NOTE] ==== Информация о любых удаляемых файлов должна быть явным образом указана в PR, поскольку необходимость в удалении файла для коммиттера может быть неочевидна. ==== Присылайте свои патчи в соответствии с руководством, описанном в <>. [[moved-and-updating-files]] == Файлы [.filename]#UPDATING# и [.filename]#MOVED# Если при обновлении порта требуются специальные шаги, такие как изменение файлов конфигурации или запуск специальной программы, то вам следует это задокументировать в файле [.filename]#/usr/ports/UPDATING#. Формат записи в этом файле приводится ниже: [.programlisting] .... YYYYMMDD: AFFECTS: users of portcategory/portname AUTHOR: Your name Special instructions .... Если вы включаете точные инструкции portmaster или portupgrade, пожалуйста, убедитесь в правильном экранировании символов внутри командной оболочки. Файл [.filename]#/usr/ports/MOVED# содержит записи об удалённых или перемещённых портах. Каждая строка в этом файле состоит из полей: название порта, место, куда он был перемещён, дата и причина перемещения. Если порт был удалён, то поле, указывающее новое место, может оставаться незаполненным. Поля должны разделяться символом `|` (pipe), как это показано ниже: [.programlisting] .... old name|new name (blank for deleted)|date of move|reason .... Дату следует вводить в формате `YYYY-MM-DD`. Новые записи следует добавлять в конец файла в хронологическом порядке. Если порт был перемещён, но в дальнейшем восстановлен на прежнем месте, удалите в этом файле строку, содержащую информацию о перемещении. Полученные изменения можно проверить командой `Tools/scripts/MOVEDlint.awk`. diff --git a/documentation/content/ru/books/porters-handbook/uses/chapter.adoc b/documentation/content/ru/books/porters-handbook/uses/_index.adoc similarity index 55% rename from documentation/content/ru/books/porters-handbook/uses/chapter.adoc rename to documentation/content/ru/books/porters-handbook/uses/_index.adoc index 2862084668..b9944e68d9 100644 --- a/documentation/content/ru/books/porters-handbook/uses/chapter.adoc +++ b/documentation/content/ru/books/porters-handbook/uses/_index.adoc @@ -1,1685 +1,1922 @@ --- title: Глава 15. Значения USES prev: books/porters-handbook/keeping-up next: books/porters-handbook/versions --- [[uses]] = Значения `USES` :doctype: book :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :sectnumoffset: 15 :partnums: :source-highlighter: rouge :experimental: :c-plus-plus: c++ :images-path: books/porters-handbook/ ifdef::env-beastie[] ifdef::backend-html5[] :imagesdir: ../../../../images/{images-path} endif::[] ifndef::book[] include::shared/authors.adoc[] include::shared/mirrors.adoc[] include::shared/releases.adoc[] include::shared/attributes/attributes-{{% lang %}}.adoc[] include::shared/{{% lang %}}/teams.adoc[] include::shared/{{% lang %}}/mailing-lists.adoc[] include::shared/{{% lang %}}/urls.adoc[] toc::[] endif::[] ifdef::backend-pdf,backend-epub3[] include::../../../../../shared/asciidoctor.adoc[] endif::[] endif::[] ifndef::env-beastie[] toc::[] include::../../../../../shared/asciidoctor.adoc[] endif::[] [[uses-intro]] == An Introduction to `USES` -`USES` macros make it easy to declare requirements and settings for a port. They can add dependencies, change building behavior, add metadata to packages, and so on, all by selecting simple, preset values. +`USES` macros make it easy to declare requirements and settings for a port. +They can add dependencies, change building behavior, add metadata to packages, and so on, all by selecting simple, preset values. -Each section in this chapter describes a possible value for `USES`, along with its possible arguments. Arguments are appeneded to the value after a colon (`:`). Multiple arguments are separated by commas (`,`). +Each section in this chapter describes a possible value for `USES`, along with its possible arguments. +Arguments are appended to the value after a colon (`:`). +Multiple arguments are separated by commas (`,`). [[uses-intro-ex1]] .Using Multiple Values [example] ==== - [.programlisting] .... USES= bison perl .... - ==== [[uses-intro-ex2]] .Adding an Argument [example] ==== - [.programlisting] .... USES= tar:xz .... - ==== [[uses-intro-ex3]] .Adding Multiple Arguments [example] ==== - [.programlisting] .... USES= drupal:7,theme .... - ==== [[uses-intro-ex4]] .Mixing it All Together [example] ==== - [.programlisting] .... USES= pgsql:9.3+ cpe python:2.7,build .... - ==== [[uses-7z]] == `7z` Possible arguments: (none), `p7zip`, `partial` -Extract using man:7z[1] instead of man:bsdtar[1] and sets `EXTRACT_SUFX=.7z`. The `p7zip` option forces a dependency on the `7z` from package:archivers/p7zip[] if the one from the base system is not able to extract the files. `EXTRACT_SUFX` is not changed if the `partial` option is used, this can be used if the main distribution file does not have a [.filename]#.7z# extension. +Extract using man:7z[1] instead of man:bsdtar[1] and sets `EXTRACT_SUFX=.7z`. +The `p7zip` option forces a dependency on the `7z` from package:archivers/p7zip[] if the one from the base system is not able to extract the files. +`EXTRACT_SUFX` is not changed if the `partial` option is used, this can be used if the main distribution file does not have a [.filename]#.7z# extension. [[uses-ada]] == `ada` Possible arguments: (none), `5`, `6` -Depends on an Ada-capable compiler, and sets `CC` accordingly. Defaults to use gcc 5 from ports. Use the `:__X__` version option to force building with a different version. +Depends on an Ada-capable compiler, and sets `CC` accordingly. +Defaults to use gcc 5 from ports. +Use the `:_X_` version option to force building with a different version. [[uses-autoreconf]] == `autoreconf` Possible arguments: (none), `build` -Runs `autoreconf`. It encapsulates the `aclocal`, `autoconf`, `autoheader`, `automake`, `autopoint`, and `libtoolize` commands. Each command applies to [.filename]#${AUTORECONF_WRKSRC}/configure.ac# or its old name, [.filename]#${AUTORECONF_WRKSRC}/configure.in#. If [.filename]#configure.ac# defines subdirectories with their own [.filename]#configure.ac# using `AC_CONFIG_SUBDIRS`, `autoreconf` will recursively update those as well. The `:build` argument only adds build time dependencies on those tools but does not run `autoreconf`. A port can set `AUTORECONF_WRKSRC` if `WRKSRC` does not contain the path to [.filename]#configure.ac#. +Runs `autoreconf`. +It encapsulates the `aclocal`, `autoconf`, `autoheader`, `automake`, `autopoint`, and `libtoolize` commands. +Each command applies to [.filename]#${AUTORECONF_WRKSRC}/configure.ac# or its old name, [.filename]#${AUTORECONF_WRKSRC}/configure.in#. +If [.filename]#configure.ac# defines subdirectories with their own [.filename]#configure.ac# using `AC_CONFIG_SUBDIRS`, `autoreconf` will recursively update those as well. +The `:build` argument only adds build time dependencies on those tools but does not run `autoreconf`. +A port can set `AUTORECONF_WRKSRC` if `WRKSRC` does not contain the path to [.filename]#configure.ac#. [[uses-blaslapack]] == `blaslapack` Possible arguments: (none), `atlas`, `netlib` (default), `gotoblas`, `openblas` Adds dependencies on Blas / Lapack libraries. [[uses-bdb]] == `bdb` Possible arguments: (none), `48`, `5` (default), `6` -Add dependency on the Berkeley DB library. Default to package:databases/db5[]. It can also depend on package:databases/db48[] when using the `:48` argument or package:databases/db6[] with `:6`. It is possible to declare a range of acceptable values, `:48+` finds the highest installed version, and falls back to 4.8 if nothing else is installed. `INVALID_BDB_VER` can be used to specify versions which do not work with this port. The framework exposes the following variables to the port: +Add dependency on the Berkeley DB library. +Default to package:databases/db5[]. +It can also depend on package:databases/db48[] when using the `:48` argument or package:databases/db6[] with `:6`. +It is possible to declare a range of acceptable values, `:48+` finds the highest installed version, and falls back to 4.8 if nothing else is installed. +`INVALID_BDB_VER` can be used to specify versions which do not work with this port. +The framework exposes the following variables to the port: `BDB_LIB_NAME`:: -The name of the Berkeley DB library. For example, when using package:databases/db5[], it contains `db-5.3`. +The name of the Berkeley DB library. +For example, when using package:databases/db5[], it contains `db-5.3`. `BDB_LIB_CXX_NAME`:: -The name of the Berkeley DBC++ library. For example, when using package:databases/db5[], it contains `db_cxx-5.3`. +The name of the Berkeley DBC++ library. +For example, when using package:databases/db5[], it contains `db_cxx-5.3`. `BDB_INCLUDE_DIR`:: -The location of the Berkeley DB include directory. For example, when using package:databases/db5[], it will contain `${LOCALBASE}/include/db5`. +The location of the Berkeley DB include directory. +For example, when using package:databases/db5[], it will contain `${LOCALBASE}/include/db5`. `BDB_LIB_DIR`:: -The location of the Berkeley DB library directory. For example, when using package:databases/db5[], it contains `${LOCALBASE}/lib`. +The location of the Berkeley DB library directory. +For example, when using package:databases/db5[], it contains `${LOCALBASE}/lib`. `BDB_VER`:: -The detected Berkeley DB version. For example, if using `USES=bdb:48+` and Berkeley DB 5 is installed, it contains `5`. +The detected Berkeley DB version. +For example, if using `USES=bdb:48+` and Berkeley DB 5 is installed, it contains `5`. [IMPORTANT] ==== -package:databases/db48[] is deprecated and unsupported. It must not be used by any port. +package:databases/db48[] is deprecated and unsupported. +It must not be used by any port. ==== [[uses-bison]] == `bison` Possible arguments: (none), `build`, `run`, `both` Uses package:devel/bison[] By default, with no arguments or with the `build` argument, it implies `bison` is a build-time dependency, `run` implies a run-time dependency, and `both` implies both run-time and build-time dependencies. [[uses-cabal]] == `cabal` [IMPORTANT] ==== -Ports should not be created for Haskell libraries, see <> for more information. +Ports should not be created for Haskell libraries, see crossref:special[haskell-libs,Haskell Libraries] for more information. ==== Possible arguments: (none), `hpack` -Sets default values and targets used to build Haskell software using Cabal. A build dependency on the Haskell compiler port (GHC) is added. If `hpack` argument is given, a build dependency on package:devel/hs-hpack[] is added and `hpack` is invoked at configuration step to generate .cabal file. +Sets default values and targets used to build Haskell software using Cabal. +A build dependency on the Haskell compiler port (GHC) is added. +If `hpack` argument is given, a build dependency on package:devel/hs-hpack[] is added and `hpack` is invoked at configuration step to generate. +cabal file. The framework provides the following variables: `USE_CABAL`:: -If the software uses Haskell dependencies, list them in this variable. Each item should be present on Hackage and be listed in form `packagename-_0.1.2_`. Dependencies can have revisions, which are specified after the `_` symbol. Automatic generation of dependency list is supported, see <>. +If the software uses Haskell dependencies, list them in this variable. +Each item should be present on Hackage and be listed in form `packagename-_0.1.2_`. +Dependencies can have revisions, which are specified after the `_` symbol. +Automatic generation of dependency list is supported, see crossref:special[using-cabal,Building Haskell Applications with `cabal`]. `CABAL_FLAGS`:: -List of flags to be passed to `cabal-install` during the configuring and building stage. The flags are passed verbatim. +List of flags to be passed to `cabal-install` during the configuring and building stage. +The flags are passed verbatim. `EXECUTABLES`:: -List of executable files installed by the port. Default value: `${PORTNAME}`. Items from this list are automatically added to pkg-plist. +List of executable files installed by the port. +Default value: `${PORTNAME}`. +Items from this list are automatically added to pkg-plist. `SKIP_CABAL_PLIST`:: If defined, do not add items from `${EXECUTABLES}` to pkg-plist. `opt_USE_CABAL`:: Adds items to `${USE_CABAL}` depending on `opt` option. `opt_EXECUTABLES`:: Adds items to `${EXECUTABLES}` depending on `opt` option. `opt_CABAL_FLAGS`:: -If `opt` is enabled, append the value to `${CABAL_FLAGS}`. Otherwise, append `-value` to disable the flag. +If `opt` is enabled, append the value to `${CABAL_FLAGS}`. +Otherwise, append `-value` to disable the flag. `FOO_DATADIR_VARS`:: For an executable named `FOO` list Haskell packages, whose data files should be accessible by the executable. [[uses-cargo]] == `cargo` Possible arguments: (none) -Uses Cargo for configuring, building, and testing. It can be used to port Rust applications that use the Cargo build system. For more information see <>. +Uses Cargo for configuring, building, and testing. +It can be used to port Rust applications that use the Cargo build system. +For more information see crossref:special[using-cargo,Building Rust Applications with `cargo`]. [[uses-charsetfix]] == `charsetfix` Possible arguments: (none) -Prevents the port from installing [.filename]#charset.alias#. This must be installed only by package:converters/libiconv[]. `CHARSETFIX_MAKEFILEIN` can be set to a path relative to `WRKSRC` if [.filename]#charset.alias# is not installed by [.filename]#${WRKSRC}/Makefile.in#. +Prevents the port from installing [.filename]#charset.alias#. +This must be installed only by package:converters/libiconv[]. +`CHARSETFIX_MAKEFILEIN` can be set to a path relative to `WRKSRC` if [.filename]#charset.alias# is not installed by [.filename]#${WRKSRC}/Makefile.in#. [[uses-cmake]] == `cmake` -Possible arguments: (none), `insource`, `noninja`, `run` +Possible arguments: (none), `insource`, `noninja`, `run`, `testing` -Uses CMake for configuring and building. +Use CMake for configuring the port and generating a build system. -By default an out-of-source build is performed, leaving the sources in `WRKSRC` free from build artifacts. With the `insource` argument, an in-source build will be performed instead. Setting it should be the exception when a regular out-of-source build does not work. +By default an out-of-source build is performed, leaving the sources in `WRKSRC` free from build artifacts. +With the `insource` argument, an in-source build will be performed instead. +This argument should be an exception, used only when a regular out-of-source build does not work. -By default Ninja is used for the build. In some cases this does not work correctly. With the `noninja` argument, the build will fallback to using regular `make` for builds. It should only be used if a Ninja-based build does not work. +By default Ninja (package:devel/ninja[]) is used for the build. +In some cases this does not work correctly. +With the `noninja` argument, the build will use regular `make` for builds. +This argument should only be used if a Ninja-based build does not work. With the `run` argument, a run dependency is registered in addition to a build dependency. -For more information see <>. +With the `testing` argument, a test-target is added that uses CTest. +When running tests the port will be re-configured for testing and re-built. + +For more information see crossref:special[using-cmake,Using `cmake`]. [[uses-compiler]] == `compiler` -Possible arguments: (none), `env` (default, implicit), `{c-plus-plus}17-lang`, `{c-plus-plus}14-lang`, `{c-plus-plus}11-lang`, `gcc-{c-plus-plus}11-lib`, `{c-plus-plus}11-lib`, `{c-plus-plus}0x`, `c11`, `openmp`, `nestedfct`, `features` +Possible arguments: (none), `env` (default, implicit), `{c-plus-plus}17-lang`, `{c-plus-plus}14-lang`, `{c-plus-plus}11-lang`, `gcc-{c-plus-plus}11-lib`, `{c-plus-plus}11-lib`, `{c-plus-plus}0x`, `c11`, `nestedfct`, `features` -Determines which compiler to use based on any given wishes. Use `{c-plus-plus}17-lang` if the port needs a {c-plus-plus}17-capable compiler, `{c-plus-plus}14-lang` if the port needs a {c-plus-plus}14-capable compiler, `{c-plus-plus}11-lang` if the port needs a {c-plus-plus}11-capable compiler, `gcc-{c-plus-plus}11-lib` if the port needs the `g++` compiler with a {c-plus-plus}11 library, or `{c-plus-plus}11-lib` if the port needs a {c-plus-plus}11-ready standard library. If the port needs a compiler understanding {c-plus-plus}0X, C11, OpenMP, or nested functions, the corresponding parameters should be used. +Determines which compiler to use based on any given wishes. +Use `{c-plus-plus}17-lang` if the port needs a {c-plus-plus}17-capable compiler, `{c-plus-plus}14-lang` if the port needs a {c-plus-plus}14-capable compiler, `{c-plus-plus}11-lang` if the port needs a {c-plus-plus}11-capable compiler, `gcc-{c-plus-plus}11-lib` if the port needs the `g++` compiler with a {c-plus-plus}11 library, or `{c-plus-plus}11-lib` if the port needs a {c-plus-plus}11-ready standard library. +If the port needs a compiler understanding {c-plus-plus}0X, C11 or nested functions, the corresponding parameters should be used. -Use `features` to request a list of features supported by the default compiler. After including [.filename]#bsd.port.pre.mk# the port can inspect the results using these variables: +Use `features` to request a list of features supported by the default compiler. +After including [.filename]#bsd.port.pre.mk# the port can inspect the results using these variables: * `COMPILER_TYPE`: the default compiler on the system, either gcc or clang * `ALT_COMPILER_TYPE`: the alternative compiler on the system, either gcc or clang. Only set if two compilers are present in the base system. * `COMPILER_VERSION`: the first two digits of the version of the default compiler. * `ALT_COMPILER_VERSION`: the first two digits of the version of the alternative compiler, if present. * `CHOSEN_COMPILER_TYPE`: the chosen compiler, either gcc or clang * `COMPILER_FEATURES`: the features supported by the default compiler. It currently lists the {c-plus-plus} library. [[uses-cpe]] == `cpe` Possible arguments: (none) -Include Common Platform Enumeration (CPE) information in package manifest as a CPE 2.3 formatted string. See the http://scap.nist.gov/specifications/cpe/[CPE specification] for details. To add CPE information to a port, follow these steps: +Include Common Platform Enumeration (CPE) information in package manifest as a CPE 2.3 formatted string. +See the http://scap.nist.gov/specifications/cpe/[CPE specification] for details. +To add CPE information to a port, follow these steps: [.procedure] -==== . Search for the official CPE entry for the software product either by using the NVD's http://web.nvd.nist.gov/view/cpe/search[CPE search engine] or in the http://static.nvd.nist.gov/feeds/xml/cpe/dictionary/official-cpe-dictionary_v2.3.xml[official CPE dictionary] (warning, very large XML file). _Do not ever make up CPE data._ . Add `cpe` to `USES` and compare the result of `make -V CPE_STR` to the CPE dictionary entry. Continue one step at a time until `make -V CPE_STR` is correct. . If the product name (second field, defaults to `PORTNAME`) is incorrect, define `CPE_PRODUCT`. . If the vendor name (first field, defaults to `CPE_PRODUCT`) is incorrect, define `CPE_VENDOR`. . If the version field (third field, defaults to `PORTVERSION`) is incorrect, define `CPE_VERSION`. . If the update field (fourth field, defaults to empty) is incorrect, define `CPE_UPDATE`. . If it is still not correct, check [.filename]#Mk/Uses/cpe.mk# for additional details, or contact the {ports-secteam}. . Derive as much as possible of the CPE name from existing variables such as `PORTNAME` and `PORTVERSION`. Use variable modifiers to extract the relevant portions from these variables rather than hardcoding the name. . _Always_ run `make -V CPE_STR` and check the output before committing anything that changes `PORTNAME` or `PORTVERSION` or any other variable which is used to derive `CPE_STR`. -==== [[uses-cran]] == `cran` Possible arguments: (none), `auto-plist`, `compiles` -Uses the Comprehensive R Archive Network. Specify `auto-plist` to automatically generate [.filename]#pkg-plist#. Specify `compiles` if the port has code that need to be compiled. +Uses the Comprehensive R Archive Network. +Specify `auto-plist` to automatically generate [.filename]#pkg-plist#. +Specify `compiles` if the port has code that need to be compiled. [[uses-desktop-file-utils]] == `desktop-file-utils` Possible arguments: (none) -Uses update-desktop-database from package:devel/desktop-file-utils[]. An extra post-install step will be run without interfering with any post-install steps already in the port [.filename]#Makefile#. A line with <> will be added to the plist. +Uses update-desktop-database from package:devel/desktop-file-utils[]. +An extra post-install step will be run without interfering with any post-install steps already in the port [.filename]#Makefile#. +A line with <> will be added to the plist. [[uses-desthack]] == `desthack` Possible arguments: (none) Changes the behavior of GNU configure to properly support `DESTDIR` in case the original software does not. [[uses-display]] == `display` Possible arguments: (none), _ARGS_ -Set up a virtual display environment. If the environment variable `DISPLAY` is not set, then Xvfb is added as a build dependency, and `CONFIGURE_ENV` is extended with the port number of the currently running instance of Xvfb. The _ARGS_ parameter defaults to `install` and controls the phase around which to start and stop the virtual display. +Set up a virtual display environment. +If the environment variable `DISPLAY` is not set, then Xvfb is added as a build dependency, and `CONFIGURE_ENV` is extended with the port number of the currently running instance of Xvfb. +The _ARGS_ parameter defaults to `install` and controls the phase around which to start and stop the virtual display. [[uses-dos2unix]] == `dos2unix` Possible arguments: (none) -The port has files with line endings in DOS format which need to be converted. Several variables can be set to control which files will be converted. The default is to convert _all_ files, including binaries. See <> for examples. +The port has files with line endings in DOS format which need to be converted. +Several variables can be set to control which files will be converted. +The default is to convert _all_ files, including binaries. +See crossref:slow-porting[slow-patch-automatic-replacements,Simple Automatic Replacements] for examples. * `DOS2UNIX_REGEX`: match file names based on a regular expression. * `DOS2UNIX_FILES`: match literal file names. * `DOS2UNIX_GLOB`: match file names based on a glob pattern. * `DOS2UNIX_WRKSRC`: the directory from which to start the conversions. Defaults to `${WRKSRC}`. [[uses-drupal]] == `drupal` Possible arguments: `7`, `module`, `theme` -Automate installation of a port that is a Drupal theme or module. Use with the version of Drupal that the port is expecting. For example, `USES=drupal:7,module` says that this port creates a Drupal 6 module. A Drupal 7 theme can be specified with `USES=drupal:7,theme`. +Automate installation of a port that is a Drupal theme or module. +Use with the version of Drupal that the port is expecting. +For example, `USES=drupal:7,module` says that this port creates a Drupal 6 module. +A Drupal 7 theme can be specified with `USES=drupal:7,theme`. + +[[uses-eigen]] +== `eigen` + +Possible arguments: 2, 3, build (default), run + +Add dependency on package:math/eigen[]. [[uses-fakeroot]] == `fakeroot` Possible arguments: (none) -Changes some default behavior of build systems to allow installing as a user. See https://wiki.debian.org/FakeRoot[] for more information on `fakeroot`. +Changes some default behavior of build systems to allow installing as a user. +See https://wiki.debian.org/FakeRoot[] for more information on `fakeroot`. [[uses-fam]] == `fam` Possible arguments: (none), `fam`, `gamin` -Uses a File Alteration Monitor as a library dependency, either package:devel/fam[] or package:devel/gamin[]. End users can set WITH_FAM_SYSTEM to specify their preference. +Uses a File Alteration Monitor as a library dependency, either package:devel/fam[] or package:devel/gamin[]. +End users can set WITH_FAM_SYSTEM to specify their preference. [[uses-firebird]] == `firebird` Possible arguments: (none), `25` Add a dependency to the client library of the Firebird database. [[uses-fonts]] == `fonts` Possible arguments: (none), `fc`, `fcfontsdir` (default), `fontsdir`, `none` -Adds a runtime dependency on tools needed to register fonts. Depending on the argument, add a `<> ${FONTSDIR}` line, `<> ${FONTSDIR}` line, `<> ${FONTSDIR}` line, or no line if the argument is `none`, to the plist. `FONTSDIR` defaults to [.filename]#${PREFIX}/shared/fonts/${FONTNAME}# and `FONTNAME` to `${PORTNAME}`. Add `FONTSDIR` to `PLIST_SUB` and `SUB_LIST` +Adds a runtime dependency on tools needed to register fonts. +Depending on the argument, add a `crossref:plist[plist-keywords-fc,@fc] ${FONTSDIR}` line, `crossref:plist[plist-keywords-fcfontsdir,@fcfontsdir] ${FONTSDIR}` line, `crossref:plist[plist-keywords-fontsdir,@fontsdir] ${FONTSDIR}` line, or no line if the argument is `none`, to the plist. +`FONTSDIR` defaults to [.filename]#${PREFIX}/share/fonts/${FONTNAME}# and `FONTNAME` to `${PORTNAME}`. +Add `FONTSDIR` to `PLIST_SUB` and `SUB_LIST` [[uses-fortran]] == `fortran` Possible arguments: `gcc` (default) Uses the GNU Fortran compiler. [[uses-fuse]] == `fuse` Possible arguments: `2` (default), `3` The port will depend on the FUSE library and handle the dependency on the kernel module depending on the version of FreeBSD. [[uses-gem]] == `gem` Possible arguments: (none), `noautoplist` -Handle building with RubyGems. If `noautoplist` is used, the packing list is not generated automatically. +Handle building with RubyGems. +If `noautoplist` is used, the packing list is not generated automatically. [[uses-gettext]] == `gettext` Possible arguments: (none) -Deprecated. Will include both <> and <>. +Deprecated. +Will include both <> and <>. [[uses-gettext-runtime]] == `gettext-runtime` Possible arguments: (none), `lib` (default), `build`, `run` -Uses package:devel/gettext-runtime[]. By default, with no arguments or with the `lib` argument, implies a library dependency on [.filename]#libintl.so#. `build` and `run` implies, respectively a build-time and a run-time dependency on [.filename]#gettext#. +Uses package:devel/gettext-runtime[]. +By default, with no arguments or with the `lib` argument, implies a library dependency on [.filename]#libintl.so#. +`build` and `run` implies, respectively a build-time and a run-time dependency on [.filename]#gettext#. [[uses-gettext-tools]] == `gettext-tools` Possible arguments: (none), `build` (default), `run` -Uses package:devel/gettext-tools[]. By default, with no argument, or with the `build` argument, a build time dependency on [.filename]#msgfmt# is registered. With the `run` argument, a run-time dependency is registered. +Uses package:devel/gettext-tools[]. +By default, with no argument, or with the `build` argument, a build time dependency on [.filename]#msgfmt# is registered. +With the `run` argument, a run-time dependency is registered. [[uses-ghostscript]] == `ghostscript` Possible arguments: _X_, `build`, `run`, `nox11` -A specific version _X_ can be used. Possible versions are `7`, `8`, `9`, and `agpl` (default). `nox11` indicates that the `-nox11` version of the port is required. `build` and `run` add build- and run-time dependencies on Ghostscript. The default is both build- and run-time dependencies. +A specific version _X_ can be used. Possible versions are `7`, `8`, `9`, and `agpl` (default). +`nox11` indicates that the `-nox11` version of the port is required. +`build` and `run` add build- and run-time dependencies on Ghostscript. +The default is both build- and run-time dependencies. [[uses-gl]] == `gl` Possible arguments: (none) -Provides an easy way to depend on GL components. The components should be listed in `USE_GL`. The available components are: +Provides an easy way to depend on GL components. +The components should be listed in `USE_GL`. +The available components are: `egl`:: add a library dependency on [.filename]#libEGL.so# from package:graphics/libglvnd[] `gbm`:: Add a library dependency on [.filename]#libgbm.so# from package:graphics/mesa-libs[] `gl`:: Add a library dependency on [.filename]#libGL.so# from package:graphics/libglvnd[] `glesv2`:: Add a library dependency on [.filename]#libGLESv2.so# from package:graphics/libglvnd[] `glew`:: Add a library dependency on [.filename]#libGLEW.so# from package:graphics/glew[] `glu`:: Add a library dependency on [.filename]#libGLU.so# from package:graphics/libGLU[] `glut`:: Add a library dependency on [.filename]#libglut.so# from package:graphics/freeglut[] `opengl`:: Add a library dependency on [.filename]#libOpenGL.so# from package:graphics/libglvnd[] [[uses-gmake]] == `gmake` Possible arguments: (none) Uses package:devel/gmake[] as a build-time dependency and sets up the environment to use `gmake` as the default `make` for the build. [[uses-gnome]] == `gnome` Possible arguments: (none) -Provides an easy way to depend on GNOME components. The components should be listed in `USE_GNOME`. The available components are: +Provides an easy way to depend on GNOME components. +The components should be listed in `USE_GNOME`. +The available components are: * `atk` * `atkmm` * `cairo` * `cairomm` * `dconf` * `esound` * `evolutiondataserver3` * `gconf2` * `gconfmm26` * `gdkpixbuf` * `gdkpixbuf2` * `glib12` * `glib20` * `glibmm` * `gnomecontrolcenter3` * `gnomedesktop3` * `gnomedocutils` * `gnomemenus3` * `gnomemimedata` * `gnomeprefix` * `gnomesharp20` * `gnomevfs2` * `gsound` * `gtk-update-icon-cache` * `gtk12` * `gtk20` * `gtk30` * `gtkhtml3` * `gtkhtml4` * `gtkmm20` * `gtkmm24` * `gtkmm30` * `gtksharp20` * `gtksourceview` * `gtksourceview2` * `gtksourceview3` * `gtksourceviewmm3` * `gvfs` * `intlhack` * `intltool` * `introspection` * `libartlgpl2` * `libbonobo` * `libbonoboui` * `libgda5` * `libgda5-ui` * `libgdamm5` * `libglade2` * `libgnome` * `libgnomecanvas` * `libgnomekbd` * `libgnomeprint` * `libgnomeprintui` * `libgnomeui` * `libgsf` * `libgtkhtml` * `libgtksourceviewmm` * `libidl` * `librsvg2` * `libsigc++12` * `libsigc++20` * `libwnck` * `libwnck3` * `libxml++26` * `libxml2` * `libxslt` * `metacity` * `nautilus3` * `orbit2` * `pango` * `pangomm` * `pangox-compat` * `py3gobject3` * `pygnome2` * `pygobject` * `pygobject3` * `pygtk2` * `pygtksourceview` * `referencehack` * `vte` * `vte3` -The default dependency is build- and run-time, it can be changed with `:build` or `:run`. For example: +The default dependency is build- and run-time, it can be changed with `:build` or `:run`. +For example: [.programlisting] .... USES= gnome USE_GNOME= gnomemenus3:build intlhack .... -See <> for more information. +See crossref:special[using-gnome,Using GNOME] for more information. [[uses-go]] == `go` [IMPORTANT] ==== -Ports should not be created for Go libs, see <> for more information. +Ports should not be created for Go libs, see crossref:special[go-libs,Go Libraries] for more information. ==== Possible arguments: (none), `modules`, `no_targets`, `run` -Sets default values and targets used to build Go software. A build dependency on the Go compiler port selected via `GO_PORT` is added. By default the build is performed in GOPATH mode. If Go software uses modules, the modules-aware mode can be switched on with `modules` argument. `no_targets` will setup build environment like `GO_ENV`, `GO_BUILDFLAGS` but skip creating `post-extract` and `do-{build,install,test}` targets. `run` will also add a run dependency on what is in `GO_PORT`. +Sets default values and targets used to build Go software. +A build dependency on the Go compiler port selected via `GO_PORT` is added. +By default the build is performed in GOPATH mode. +If Go software uses modules, the modules-aware mode can be switched on with `modules` argument. +`no_targets` will setup build environment like `GO_ENV`, `GO_BUILDFLAGS` but skip creating `post-extract` and `do-{build,install,test}` targets. +`run` will also add a run dependency on what is in `GO_PORT`. The build process is controlled by several variables: +`GO_MODULE`:: +The name of the application module as specified by the `module` directive in `go.mod`. +In most cases, this is the only required variable for ports that use Go modules. + `GO_PKGNAME`:: -The name of the Go package when building in GOPATH mode. This is the directory that will be created in `${GOPATH}/src`. If not set explicitly and `GH_SUBDIR` or `GL_SUBDIR` is present, `GO_PKGNAME` will be inferred from it. It is not needed when building in modules-aware mode. +The name of the Go package when building in GOPATH mode. +This is the directory that will be created in `${GOPATH}/src`. +If not set explicitly and `GH_SUBDIR` or `GL_SUBDIR` is present, `GO_PKGNAME` will be inferred from it. +It is not needed when building in modules-aware mode. `GO_TARGET`:: -The packages to build. The default value is `${GO_PKGNAME}`. `GO_TARGET` can also be a tuple in the form `package:path` where path can be either a simple filename or a full path starting with `${PREFIX}`. +The packages to build. +The default value is `${GO_PKGNAME}`. +`GO_TARGET` can also be a tuple in the form `package:path` where path can be either a simple filename or a full path starting with `${PREFIX}`. `GO_TESTTARGET`:: -The packages to test. The default value is `./...` (the current package and all subpackages). +The packages to test. +The default value is `./...` (the current package and all subpackages). `CGO_CFLAGS`:: Additional `CFLAGS` values to be passed to the C compiler by `go`. `CGO_LDFLAGS`:: Additional `LDFLAGS` values to be passed to the C compiler by `go`. `GO_BUILDFLAGS`:: Additional build arguments to be passed to `go build`. `GO_TESTFLAGS`:: Additional build arguments to be passed to `go test`. `GO_PORT`:: -The Go compiler port to use. By default this is package:lang/go[] but can be set to package:lang/go-devel[] in `make.conf` for testing with future Go versions. +The Go compiler port to use. +By default this is package:lang/go[] but can be set to package:lang/go-devel[] in `make.conf` for testing with future Go versions. + - [WARNING] ==== - This variable must not be set by individual ports! ==== -See <> for usage examples. +See crossref:special[using-go,Building Go Applications] for usage examples. [[uses-gperf]] == `gperf` Possible arguments: (none) Add a buildtime dependency on package:devel/gperf[] if `gperf` is not present in the base system. [[uses-grantlee]] == `grantlee` Possible arguments: `5`, `selfbuild` -Handle dependency on Grantlee. Specify `5` to depend on the Qt5 based version, package:devel/grantlee5[]. `selfbuild` is used internally by package:devel/grantlee5[] to get their versions numbers. +Handle dependency on Grantlee. +Specify `5` to depend on the Qt5 based version, package:devel/grantlee5[]. +`selfbuild` is used internally by package:devel/grantlee5[] to get their versions numbers. [[uses-groff]] == `groff` Possible arguments: `build`, `run`, `both` Registers a dependency on package:textproc/groff[] if not present in the base system. [[uses-gssapi]] == `gssapi` Possible arguments: (none), `base` (default), `heimdal`, `mit`, `flags`, `bootstrap` -Handle dependencies needed by consumers of the GSS-API. Only libraries that provide the Kerberos mechanism are available. By default, or set to `base`, the GSS-API library from the base system is used. Can also be set to `heimdal` to use package:security/heimdal[], or `mit` to use package:security/krb5[]. +Handle dependencies needed by consumers of the GSS-API. +Only libraries that provide the Kerberos mechanism are available. +By default, or set to `base`, the GSS-API library from the base system is used. +Can also be set to `heimdal` to use package:security/heimdal[], or `mit` to use package:security/krb5[]. When the local Kerberos installation is not in `LOCALBASE`, set `HEIMDAL_HOME` (for `heimdal`) or `KRB5_HOME` (for `krb5`) to the location of the Kerberos installation. These variables are exported for the ports to use: * `GSSAPIBASEDIR` * `GSSAPICPPFLAGS` * `GSSAPIINCDIR` * `GSSAPILDFLAGS` * `GSSAPILIBDIR` * `GSSAPILIBS` * `GSSAPI_CONFIGURE_ARGS` -The `flags` option can be given alongside `base`, `heimdal`, or `mit` to automatically add `GSSAPICPPFLAGS`, `GSSAPILDFLAGS`, and `GSSAPILIBS` to `CFLAGS`, `LDFLAGS`, and `LDADD`, respectively. For example, use `base,flags`. +The `flags` option can be given alongside `base`, `heimdal`, or `mit` to automatically add `GSSAPICPPFLAGS`, `GSSAPILDFLAGS`, and `GSSAPILIBS` to `CFLAGS`, `LDFLAGS`, and `LDADD`, respectively. +For example, use `base,flags`. -The `bootstrap` option is a special prefix only for use by package:security/krb5[] and package:security/heimdal[]. For example, use `bootstrap,mit`. +The `bootstrap` option is a special prefix only for use by package:security/krb5[] and package:security/heimdal[]. +For example, use `bootstrap,mit`. [[uses-gssapi-ex1]] .Typical Use [example] ==== - [.programlisting] .... OPTIONS_SINGLE= GSSAPI OPTIONS_SINGLE_GSSAPI= GSSAPI_BASE GSSAPI_HEIMDAL GSSAPI_MIT GSSAPI_NONE GSSAPI_BASE_USES= gssapi GSSAPI_BASE_CONFIGURE_ON= --with-gssapi=${GSSAPIBASEDIR} ${GSSAPI_CONFIGURE_ARGS} GSSAPI_HEIMDAL_USES= gssapi:heimdal GSSAPI_HEIMDAL_CONFIGURE_ON= --with-gssapi=${GSSAPIBASEDIR} ${GSSAPI_CONFIGURE_ARGS} GSSAPI_MIT_USES= gssapi:mit GSSAPI_MIT_CONFIGURE_ON= --with-gssapi=${GSSAPIBASEDIR} ${GSSAPI_CONFIGURE_ARGS} GSSAPI_NONE_CONFIGURE_ON= --without-gssapi .... ==== [[uses-horde]] == `horde` Possible arguments: (none) -Add buildtime and runtime dependencies on package:devel/pear-channel-horde[]. Other Horde dependencies can be added with `USE_HORDE_BUILD` and `USE_HORDE_RUN`. See <> for more information. +Add buildtime and runtime dependencies on package:devel/pear-channel-horde[]. +Other Horde dependencies can be added with `USE_HORDE_BUILD` and `USE_HORDE_RUN`. +See crossref:special[php-horde,Horde Modules] for more information. [[uses-iconv]] == `iconv` Possible arguments: (none), `lib`, `build`, `patch`, `translit`, `wchar_t` -Uses `iconv` functions, either from the port package:converters/libiconv[] as a build-time and run-time dependency, or from the base system on 10-CURRENT after a native `iconv` was committed in link:https://svnweb.freebsd.org/changeset/base/254273[r254273]. By default, with no arguments or with the `lib` argument, implies `iconv` with build-time and run-time dependencies. `build` implies a build-time dependency, and `patch` implies a patch-time dependency. If the port uses the `WCHAR_T` or `//TRANSLIT` iconv extensions, add the relevant arguments so that the correct iconv is used. For more information see <>. +Uses `iconv` functions, either from the port package:converters/libiconv[] as a build-time and run-time dependency, or from the base system. +By default, with no arguments or with the `lib` argument, implies `iconv` with build-time and run-time dependencies. +`build` implies a build-time dependency, and `patch` implies a patch-time dependency. +If the port uses the `WCHAR_T` or `//TRANSLIT` iconv extensions, add the relevant arguments so that the correct iconv is used. +For more information see crossref:special[using-iconv,Using `iconv`]. [[uses-imake]] == `imake` Possible arguments: (none), `env`, `notall`, `noman` -Add package:devel/imake[] as a build-time dependency and run `xmkmf -a` during the `configure` stage. If the `env` argument is given, the `configure` target is not set. If the `-a` flag is a problem for the port, add the `notall` argument. If `xmkmf` does not generate a `install.man` target, add the `noman` argument. +Add package:devel/imake[] as a build-time dependency and run `xmkmf -a` during the `configure` stage. +If the `env` argument is given, the `configure` target is not set. +If the `-a` flag is a problem for the port, add the `notall` argument. +If `xmkmf` does not generate a `install.man` target, add the `noman` argument. [[uses-kde]] == `kde` Possible arguments: `5` -Add dependency on KDE components. See <> for more information. +Add dependency on KDE components. +See crossref:special[using-kde,Using KDE] for more information. [[uses-kmod]] == `kmod` Possible arguments: (none), `debug` Fills in the boilerplate for kernel module ports, currently: * Add `kld` to `CATEGORIES`. * Set `SSP_UNSAFE`. * Set `IGNORE` if the kernel sources are not found in `SRC_BASE`. * Define `KMODDIR` to [.filename]#/boot/modules# by default, add it to `PLIST_SUB` and `MAKE_ENV`, and create it upon installation. If `KMODDIR` is set to [.filename]#/boot/kernel#, it will be rewritten to [.filename]#/boot/modules#. This prevents breaking packages when upgrading the kernel due to [.filename]#/boot/kernel# being renamed to [.filename]#/boot/kernel.old# in the process. -* Handle cross-referencing kernel modules upon installation and deinstallation, using <>. +* Handle cross-referencing kernel modules upon installation and deinstallation, using crossref:plist[plist-keywords-kld,`@kld`]. * If the `debug` argument is given, the port can install a debug version of the module into [.filename]#KERN_DEBUGDIR#/[.filename]#KMODDIR#. By default, `KERN_DEBUGDIR` is copied from `DEBUGDIR` and set to [.filename]#/usr/lib/debug#. The framework will take care of creating and removing any required directories. [[uses-lha]] == `lha` Possible arguments: (none) Set `EXTRACT_SUFX` to `.lzh` [[uses-libarchive]] == `libarchive` Possible arguments: (none) -Registers a dependency on package:archivers/libarchive[]. Any ports depending on libarchive must include `USES=libarchive`. +Registers a dependency on package:archivers/libarchive[]. +Any ports depending on libarchive must include `USES=libarchive`. [[uses-libedit]] == `libedit` Possible arguments: (none) -Registers a dependency on package:devel/libedit[]. Any ports depending on libedit must include `USES=libedit`. +Registers a dependency on package:devel/libedit[]. +Any ports depending on libedit must include `USES=libedit`. [[uses-libtool]] == `libtool` Possible arguments: (none), `keepla`, `build` -Patches `libtool` scripts. This must be added to all ports that use `libtool`. The `keepla` argument can be used to keep [.filename]#.la# files. Some ports do not ship with their own copy of libtool and need a build time dependency on package:devel/libtool[], use the `:build` argument to add such dependency. +Patches `libtool` scripts. This must be added to all ports that use `libtool`. +The `keepla` argument can be used to keep [.filename]#.la# files. +Some ports do not ship with their own copy of libtool and need a build time dependency on package:devel/libtool[], use the `:build` argument to add such dependency. [[uses-linux]] == `linux` Possible arguments: `c6`, `c7` -Ports Linux compatibility framework. Specify `c6` to depend on CentOS 6 packags. Specify `c7` to depend on CentOS 7 packages. The available packages are: +Ports Linux compatibility framework. +Specify `c6` to depend on CentOS 6 packags. +Specify `c7` to depend on CentOS 7 packages. The available packages are: * `allegro` * `alsa-plugins-oss` * `alsa-plugins-pulseaudio` * `alsalib` * `atk` * `avahi-libs` * `base` * `cairo` * `cups-libs` * `curl` * `cyrus-sasl2` * `dbusglib` * `dbuslibs` * `devtools` * `dri` * `expat` * `flac` * `fontconfig` * `gdkpixbuf2` * `gnutls` * `graphite2` * `gtk2` * `harfbuzz` * `jasper` * `jbigkit` * `jpeg` * `libasyncns` * `libaudiofile` * `libelf` * `libgcrypt` * `libgfortran` * `libgpg-error` * `libmng` * `libogg` * `libpciaccess` * `libsndfile` * `libsoup` * `libssh2` * `libtasn1` * `libthai` * `libtheora` * `libv4l` * `libvorbis` * `libxml2` * `mikmod` * `naslibs` * `ncurses-base` * `nspr` * `nss` * `openal` * `openal-soft` * `openldap` * `openmotif` * `openssl` * `pango` * `pixman` * `png` * `pulseaudio-libs` * `qt` * `qt-x11` * `qtwebkit` * `scimlibs` * `sdl12` * `sdlimage` * `sdlmixer` * `sqlite3` * `tcl85` * `tcp_wrappers-libs` * `tiff` * `tk85` * `ucl` * `xorglibs` [[uses-localbase]] == `localbase` Possible arguments: (none), `ldflags` -Ensures that libraries from dependencies in `LOCALBASE` are used instead of the ones from the base system. Specify `ldflags` to add `-L${LOCALBASE}/lib` to `LDFLAGS` instead of `LIBS`. Ports that depend on libraries that are also present in the base system should use this. It is also used internally by a few other `USES`. +Ensures that libraries from dependencies in `LOCALBASE` are used instead of the ones from the base system. +Specify `ldflags` to add `-L${LOCALBASE}/lib` to `LDFLAGS` instead of `LIBS`. +Ports that depend on libraries that are also present in the base system should use this. +It is also used internally by a few other `USES`. [[uses-lua]] == `lua` -Possible arguments: (none), `_XY_+`, `_XY_`, `build`, `run` +Possible arguments: (none), `_XY_`, `_XY_+`, `-_XY_`, `_XY_-_ZA_`, `module`, `flavors`, `build`, `run`, `env` -Adds a dependency on Lua. By default this is a library dependency, unless overridden by the `build` or `run` option. The default version is 5.2, unless set by the `_XY_` parameter (for example, `51` or `52+`). +Adds a dependency on Lua. +By default this is a library dependency, unless overridden by the `build` and/or `run` option. +The `env` option prevents the addition of any dependency, while still defining all the usual variables. + +The default version is set by the usual `DEFAULT_VERSIONS` mechanism, unless a version or range of versions is specified as an argument, for example, `51` or `51-53`. + +Applications using Lua are normally built for only a single Lua version. +However, library modules intended to be loaded by Lua code should use the `module` option to build with multiple flavors. + +For more information see crossref:special[using-lua,Using Lua]. [[uses-lxqt]] == `lxqt` Possible arguments: (none) -Handle dependencies for the LXQt Desktop Environment. Use `USE_LXQT` to select the components needed for the port. See <> for more information. +Handle dependencies for the LXQt Desktop Environment. +Use `USE_LXQT` to select the components needed for the port. +See crossref:special[using-lxqt,Using LXQt] for more information. [[uses-makeinfo]] == `makeinfo` Possible arguments: (none) Add a build-time dependency on `makeinfo` if it is not present in the base system. [[uses-makeself]] == `makeself` Possible arguments: (none) Indicates that the distribution files are makeself archives and sets the appropriate dependencies. [[uses-mate]] == `mate` Possible arguments: (none) -Provides an easy way to depend on MATE components. The components should be listed in `USE_MATE`. The available components are: +Provides an easy way to depend on MATE components. +The components should be listed in `USE_MATE`. +The available components are: * `autogen` * `caja` * `common` * `controlcenter` * `desktop` * `dialogs` * `docutils` * `icontheme` * `intlhack` * `intltool` * `libmatekbd` * `libmateweather` * `marco` * `menus` * `notificationdaemon` * `panel` * `pluma` * `polkit` * `session` * `settingsdaemon` -The default dependency is build- and run-time, it can be changed with `:build` or `:run`. For example: +The default dependency is build- and run-time, it can be changed with `:build` or `:run`. +For example: [.programlisting] .... USES= mate USE_MATE= menus:build intlhack .... [[uses-meson]] == `meson` Possible arguments: (none) -Provide support for Meson based projects. For more information see <>. +Provide support for Meson based projects. +For more information see crossref:special[using-meson,Using `meson`]. [[uses-metaport]] == `metaport` Possible arguments: (none) Sets the following variables to make it easier to create a metaport: `MASTER_SITES`, `DISTFILES`, `EXTRACT_ONLY`, `NO_BUILD`, `NO_INSTALL`, `NO_MTREE`, `NO_ARCH`. [[uses-mysql]] == `mysql` Possible arguments: (none), `_version_`, `client` (default), `server`, `embedded` -Provide support for MySQL. If no version is given, try to find the current installed version. Fall back to the default version, MySQL-5.6. The possible versions are `55`, `55m`, `55p`, `56`, `56p`, `56w`, `57`, `57p`, `80`, `100m`, `101m`, and `102m`. The `m` and `p` suffixes are for the MariaDB and Percona variants of MySQL. `server` and `embedded` add a build- and run-time dependency on the MySQL server. When using `server` or `embedded`, add `client` to also add a dependency on [.filename]#libmysqlclient.so#. A port can set `IGNORE_WITH_MYSQL` if some versions are not supported. +Provide support for MySQL +If no version is given, try to find the current installed version. +Fall back to the default version, MySQL-5.6. +The possible versions are `55`, `55m`, `55p`, `56`, `56p`, `56w`, `57`, `57p`, `80`, `100m`, `101m`, and `102m`. +The `m` and `p` suffixes are for the MariaDB and Percona variants of MySQL. +`server` and `embedded` add a build- and run-time dependency on the MySQL server. +When using `server` or `embedded`, add `client` to also add a dependency on [.filename]#libmysqlclient.so#. +A port can set `IGNORE_WITH_MYSQL` if some versions are not supported. The framework sets `MYSQL_VER` to the detected MySQL version. [[uses-mono]] == `mono` Possible arguments: (none), `nuget` Adds a dependency on the Mono (currently only C#) framework by setting the appropriate dependencies. -Specify `nuget` when the port uses nuget packages. `NUGET_DEPENDS` needs to be set with the names and versions of the nuget packages in the format `_name=version_`. An optional package origin can be added using `_name=version:origin_`. +Specify `nuget` when the port uses nuget packages. +`NUGET_DEPENDS` needs to be set with the names and versions of the nuget packages in the format `_name_=_version_`. +An optional package origin can be added using `_name_=_version_:_origin_`. The helper target, `buildnuget`, will output the content of the `NUGET_DEPENDS` based on the provided [.filename]#packages.config#. [[uses-motif]] == `motif` Possible arguments: (none) -Uses package:x11-toolkits/open-motif[] as a library dependency. End users can set `WANT_LESSTIF` for the dependency to be on package:x11-toolkits/lesstif[] instead of package:x11-toolkits/open-motif[]. +Uses package:x11-toolkits/open-motif[] as a library dependency. +End users can set `WANT_LESSTIF` for the dependency to be on package:x11-toolkits/lesstif[] instead of package:x11-toolkits/open-motif[]. [[uses-ncurses]] == `ncurses` Possible arguments: (none), `base`, `port` Uses ncurses, and causes some useful variables to be set. [[uses-ninja]] == `ninja` Possible arguments: (none) Uses ninja to build the port. [[uses-objc]] == `objc` Possible arguments: (none) Add objective C dependencies (compiler, runtime library) if the base system does not support it. [[uses-openal]] == `openal` Possible arguments: `al`, `soft` (default), `si`, `alut` -Uses OpenAL. The backend can be specified, with the software implementation as the default. The user can specify a preferred backend with `WANT_OPENAL`. Valid values for this knob are `soft` (default) and `si`. +Uses OpenAL. +The backend can be specified, with the software implementation as the default. +The user can specify a preferred backend with `WANT_OPENAL`. +Valid values for this knob are `soft` (default) and `si`. [[uses-pathfix]] == `pathfix` Possible arguments: (none) -Look for [.filename]#Makefile.in# and [.filename]#configure# in `PATHFIX_WRKSRC` (defaults to `WRKSRC`) and fix common paths to make sure they respect the FreeBSD hierarchy. For example, it fixes the installation directory of ``pkgconfig``'s [.filename]#.pc# files to [.filename]#${PREFIX}/libdata/pkgconfig#. If the port uses `USES=autoreconf`, [.filename]#Makefile.am# will be added to `PATHFIX_MAKEFILEIN` automatically. +Look for [.filename]#Makefile.in# and [.filename]#configure# in `PATHFIX_WRKSRC` (defaults to `WRKSRC`) and fix common paths to make sure they respect the FreeBSD hierarchy. +For example, it fixes the installation directory of `pkgconfig`'s [.filename]#.pc# files to [.filename]#${PREFIX}/libdata/pkgconfig#. +If the port uses `USES=autoreconf`, [.filename]#Makefile.am# will be added to `PATHFIX_MAKEFILEIN` automatically. -If the port <> it will look for [.filename]#CMakeLists.txt# in `PATHFIX_WRKSRC`. If needed, that default filename can be changed with `PATHFIX_CMAKELISTSTXT`. +If the port <> it will look for [.filename]#CMakeLists.txt# in `PATHFIX_WRKSRC`. +If needed, that default filename can be changed with `PATHFIX_CMAKELISTSTXT`. [[uses-pear]] == `pear` Possible arguments: `env` -Adds a dependency on package:devel/pear[]. It will setup default behavior for software using the PHP Extension and Application Repository. Using the `env` arguments only sets up the PEAR environment variables. See <> for more information. +Adds a dependency on package:devel/pear[]. +It will setup default behavior for software using the PHP Extension and Application Repository. +Using the `env` arguments only sets up the PEAR environment variables. +See crossref:special[php-pear,PEAR Modules] for more information. [[uses-perl5]] == `perl5` Possible arguments: (none) Depends on Perl. The configuration is done using `USE_PERL5`. `USE_PERL5` can contain the phases in which to use Perl, can be `extract`, `patch`, `build`, `run`, or `test`. -`USE_PERL5` can also contain `configure`, `modbuild`, or `modbuildtiny` when [.filename]#Makefile.PL#, [.filename]#Build.PL#, or Module::Build::Tiny's flavor of [.filename]#Build.PL# is required. +`USE_PERL5` can also contain `configure`, `modbuild`, or `modbuildtiny` when [.filename]#Makefile.PL#, [.filename]#Build.PL#, +or Module::Build::Tiny's flavor of [.filename]#Build.PL# is required. -`USE_PERL5` defaults to `build run`. When using `configure`, `modbuild`, or `modbuildtiny`, `build` and `run` are implied. +`USE_PERL5` defaults to `build run`. +When using `configure`, `modbuild`, or `modbuildtiny`, `build` and `run` are implied. -See <> for more information. +See crossref:special[using-perl,Using Perl] for more information. [[uses-pgsql]] == `pgsql` Possible arguments: (none), `_X.Y_`, `_X.Y_+`, `_X.Y_-`, `_X.Y_-_Z.A_` -Provide support for PostgreSQL. Port maintainer can set version required. Minimum and maximum versions or a range can be specified; for example, `9.0-`, `8.4+`, `8.4-9.2.` +Provide support for PostgreSQL. +Port maintainer can set version required. +Minimum and maximum versions or a range can be specified; for example, `9.0-`, `8.4+`, `8.4-9.2.` -By default, the added dependency will be the client, but if the port requires additional components, this can be done using `WANT_PGSQL=_component[:target]_`; for example, `WANT_PGSQL=server:configure pltcl plperl`. The available components are: +By default, the added dependency will be the client, but if the port requires additional components, +this can be done using `WANT_PGSQL=_component[:target]_`; +for example, `WANT_PGSQL=server:configure pltcl plperl`. +The available components are: * `client` * `contrib` * `docs` * `pgtcl` * `plperl` * `plpython` * `pltcl` * `server` [[uses-php]] == `php` Possible arguments: (none), `phpize`, `ext`, `zend`, `build`, `cli`, `cgi`, `mod`, `web`, `embed`, `pecl`, `flavors`, `noflavors` -Provide support for PHP. Add a runtime dependency on the default PHP version, package:lang/php56[]. +Provide support for PHP. +Add a runtime dependency on the default PHP version, package:lang/php56[]. `phpize`:: -Use to build a PHP extension. Enables flavors. +Use to build a PHP extension. +Enables flavors. `ext`:: -Use to build, install and register a PHP extension. Enables flavors. +Use to build, install and register a PHP extension. +Enables flavors. `zend`:: -Use to build, install and register a Zend extension. Enables flavors. +Use to build, install and register a Zend extension. +Enables flavors. `build`:: Set PHP also as a build-time dependency. `cli`:: Needs the CLI version of PHP. `cgi`:: Needs the CGI version of PHP. `mod`:: Needs the Apache module for PHP. `web`:: Needs the Apache module or the CGI version of PHP. `embed`:: Needs the embedded library version of PHP. `pecl`:: -Provide defaults for fetching PHP extensions from the PECL repository. Enables flavors. +Provide defaults for fetching PHP extensions from the PECL repository. +Enables flavors. `flavors`:: -Enable automatic <> generation. Flavors will be generated for all PHP versions, except the ones present in <>. +Enable automatic crossref:flavors[flavors-auto-php,PHP flavors] generation. +Flavors will be generated for all PHP versions, except the ones present in <>. `noflavors`:: -Disable automatic PHP flavors generation. _Must only_ be used with extensions provided by PHP itself. +Disable automatic PHP flavors generation. +_Must only_ be used with extensions provided by PHP itself. Variables are used to specify which PHP modules are required, as well as which version of PHP are supported. `USE_PHP`:: -The list of required PHP extensions at run-time. Add `:build` to the extension name to add a build-time dependency. Example: `pcre xml:build gettext` +The list of required PHP extensions at run-time. +Add `:build` to the extension name to add a build-time dependency. +Example: `pcre xml:build gettext` + [[uses-php-ignore]] `IGNORE_WITH_PHP`:: -The port does not work with PHP of the given version. For possible values look at the content of `_ALL_PHP_VERSIONS` in [.filename]#Mk/Uses/php.mk#. +The port does not work with PHP of the given version. +For possible values look at the content of `_ALL_PHP_VERSIONS` in [.filename]#Mk/Uses/php.mk#. When building a PHP or Zend extension with `:ext` or `:zend`, these variables can be set: `PHP_MODNAME`:: -The name of the PHP or Zend extension. Default value is `${PORTNAME}`. +The name of the PHP or Zend extension. +Default value is `${PORTNAME}`. `PHP_HEADER_DIRS`:: -A list of subdirectories from which to install header files. The framework will always install the header files that are present in the same directory as the extension. +A list of subdirectories from which to install header files. +The framework will always install the header files that are present in the same directory as the extension. `PHP_MOD_PRIO`:: -The priority at which to load the extension. It is a number between `00` and `99`. +The priority at which to load the extension. +It is a number between `00` and `99`. + -For extensions that do not depend on any extension, the priority is automatically set to `20`, for extensions that depend on another extension, the priority is automatically set to `30`. Some extensions may need to be loaded before every other extension, for example package:www/php56-opcache[]. Some may need to be loaded after an extension with a priority of `30`. In that case, add `PHP_MOD_PRIO=_XX_` in the port's Makefile. For example: +For extensions that do not depend on any extension, the priority is automatically set to `20`, for extensions that depend on another extension, the priority is automatically set to `30`. +Some extensions may need to be loaded before every other extension, for example package:www/php56-opcache[]. +Some may need to be loaded after an extension with a priority of `30`. +In that case, add `PHP_MOD_PRIO=_XX_` in the port's Makefile. For example: + [.programlisting] .... USES= php:ext USE_PHP= wddx PHP_MOD_PRIO= 40 .... These variables are available to use in `PKGNAMEPREFIX` or `PKGNAMESUFFIX`: `PHP_PKGNAMEPREFIX`:: -Contains `php__XY__-` where _XY_ is the current flavor's PHP version. Use with PHP extensions and modules. +Contains `php_XY_-` where _XY_ is the current flavor's PHP version. +Use with PHP extensions and modules. `PHP_PKGNAMESUFFIX`:: -Contains `-php__XY__` where _XY_ is the current flavor's PHP version. Use with PHP applications. +Contains `-php_XY_` where _XY_ is the current flavor's PHP version. +Use with PHP applications. `PECL_PKGNAMEPREFIX`:: -Contains `php__XY__-pecl-` where _XY_ is the current flavor's PHP version. Use with PECL modules. +Contains `php_XY_-pecl-` where _XY_ is the current flavor's PHP version. +Use with PECL modules. [IMPORTANT] ==== -With flavors, all PHP extensions, PECL extensions, PEAR modules _must have_ a different package name, so they must all use one of these three variables in their `PKGNAMEPREFIX` or `PKGNAMESUFFIX`. +With flavors, all PHP extensions, PECL extensions, PEAR modules _must have_ a different package name, +so they must all use one of these three variables in their `PKGNAMEPREFIX` or `PKGNAMESUFFIX`. ==== [[uses-pkgconfig]] == `pkgconfig` Possible arguments: (none), `build` (default), `run`, `both` -Uses package:devel/pkgconf[]. With no arguments or with the `build` argument, it implies `pkg-config` as a build-time dependency. `run` implies a run-time dependency and `both` implies both run-time and build-time dependencies. +Uses package:devel/pkgconf[]. +With no arguments or with the `build` argument, it implies `pkg-config` as a build-time dependency. +`run` implies a run-time dependency and `both` implies both run-time and build-time dependencies. [[uses-pure]] == `pure` Possible arguments: (none), `ffi` -Uses package:lang/pure[]. Largely used for building related pure ports. With the `ffi` argument, it implies package:devel/pure-ffi[] as a run-time dependency. +Uses package:lang/pure[]. +Largely used for building related pure ports. +With the `ffi` argument, it implies package:devel/pure-ffi[] as a run-time dependency. [[uses-pyqt]] == `pyqt` Possible arguments: (none), `4`, `5` -Uses PyQt. If the port is part of PyQT itself, set `PYQT_DIST`. Use `USE_PYQT` to select the components the port needs. The available components are: +Uses PyQt. If the port is part of PyQT itself, set `PYQT_DIST`. +Use `USE_PYQT` to select the components the port needs. +The available components are: * `core` * `dbus` * `dbussupport` * `demo` * `designer` * `designerplugin` * `doc` * `gui` * `multimedia` * `network` * `opengl` * `qscintilla2` * `sip` * `sql` * `svg` * `test` * `webkit` * `xml` * `xmlpatterns` These components are only available with PyQT4: * `assistant` * `declarative` * `help` * `phonon` * `script` * `scripttools` These components are only available with PyQT5: * `multimediawidgets` * `printsupport` * `qml` * `serialport` * `webkitwidgets` * `widgets` The default dependency for each component is build- and run-time, to select only build or run, add `_build` or `_run` to the component name. For example: [.programlisting] .... USES= pyqt USE_PYQT= core doc_build designer_run .... [[uses-python]] == `python` Possible arguments: (none), `_X.Y_`, `_X.Y+_`, `_-X.Y_`, `_X.Y-Z.A_`, `patch`, `build`, `run`, `test` -Uses Python. A supported version or version range can be specified. If Python is only needed at build time, run time or for the tests, it can be set as a build, run or test dependency with `build`, `run`, or `test`. If Python is also needed during the patch phase, use `patch`. See <> for more information. +Uses Python. A supported version or version range can be specified. +If Python is only needed at build time, run time or for the tests, it can be set as a build, run or test dependency with `build`, `run`, or `test`. +If Python is also needed during the patch phase, use `patch`. +See crossref:special[using-python, Using Python] for more information. -`PYTHON_NO_DEPENDS=yes` can be used when the variables exported by the framework are needed but a dependency on Python is not. It can happen when using with <>, and the goal is only to fix the shebangs but not add a dependency on Python. +`PYTHON_NO_DEPENDS=yes` can be used when the variables exported by the framework are needed but a dependency on Python is not. +It can happen when using with <>, and the goal is only to fix the shebangs but not add a dependency on Python. [[uses-qmail]] == `qmail` Possible arguments: (none), `build`, `run`, `both`, `vars` -Uses package:mail/qmail[]. With the `build` argument, it implies `qmail` as a build-time dependency. `run` implies a run-time dependency. Using no argument or the `both` argument implies both run-time and build-time dependencies. `vars` will only set QMAIL variables for the port to use. +Uses package:mail/qmail[]. With the `build` argument, it implies `qmail` as a build-time dependency. +`run` implies a run-time dependency. +Using no argument or the `both` argument implies both run-time and build-time dependencies. +`vars` will only set QMAIL variables for the port to use. [[uses-qmake]] == `qmake` Possible arguments: (none), `norecursive`, `outsource`, `no_env`, `no_configure` -Uses QMake for configuring. For more information see <>. +Uses QMake for configuring. For more information see crossref:special[using-qmake,Using `qmake`]. [[uses-qt]] == `qt` Possible arguments: `5`, `no_env` -Add dependency on Qt components. `no_env` is passed directly to `USES= qmake`. See <> for more information. +Add dependency on Qt components. +`no_env` is passed directly to `USES= qmake`. +See crossref:special[using-qt,Using Qt] for more information. [[uses-qt-dist]] == `qt-dist` Possible arguments: (none) or `5` and (none) or one of `3d`, `activeqt`, `androidextras`, `base`, `canvas3d`, `charts`, `connectivity`, `datavis3d`, `declarative`, `doc`, `gamepad`, `graphicaleffects`, `imageformats`, `location`, `macextras`, `multimedia`, `networkauth`, `purchasing`, `quickcontrols2`, `quickcontrols`, `remoteobjects`, `script`, `scxml`, `sensors`, `serialbus`, `serialport`, `speech`, `svg`, `tools`, `translations`, `virtualkeyboard`, `wayland`, `webchannel`, `webengine`, `websockets`, `webview`, `winextras`, `x11extras`, `xmlpatterns` -Provides support for building Qt 5 components. It takes care of setting up the appropriate configuration environment for the port to build. +Provides support for building Qt 5 components. +It takes care of setting up the appropriate configuration environment for the port to build. [[qt5-dist-example]] .Building Qt 5 Components [example] ==== - The port is Qt 5's `networkauth` component, which is part of the `networkauth` distribution file. [.programlisting] .... PORTNAME= networkauth DISTVERSION= ${QT5_VERSION} USES= qt-dist:5 .... ==== If `PORTNAME` does not match the component name, it can be passed as an argument to `qt-dist`. [[qt5-dist-example-explicit]] .Building Qt 5 Components with Different Names [example] ==== - The port is Qt 5's `gui` component, which is part of the `base` distribution file. [.programlisting] .... PORTNAME= gui DISTVERSION= ${QT5_VERSION} USES= qt-dist:5,base .... ==== [[uses-readline]] == `readline` Possible arguments: (none), `port` -Uses readline as a library dependency, and sets `CPPFLAGS` and `LDFLAGS` as necessary. If the `port` argument is used or if readline is not present in the base system, add a dependency on package:devel/readline[] +Uses readline as a library dependency, and sets `CPPFLAGS` and `LDFLAGS` as necessary. +If the `port` argument is used or if readline is not present in the base system, add a dependency on package:devel/readline[] [[uses-samba]] == `samba` Possible arguments: `build`, `env`, `lib`, `run` -Handle dependency on Samba. `env` will not add any dependency and only set up the variables. `build` and `run` will add build-time and run-time dependency on [.filename]#smbd#. `lib` will add a dependency on [.filename]#libsmbclient.so#. The variables that are exported are: +Handle dependency on Samba. +`env` will not add any dependency and only set up the variables. +`build` and `run` will add build-time and run-time dependency on [.filename]#smbd#. `lib` will add a dependency on [.filename]#libsmbclient.so#. +The variables that are exported are: `SAMBAPORT`:: The origin of the default Samba port. `SAMBAINCLUDES`:: The location of the Samba header files. `SAMBALIBS`:: The directory where the Samba shared libraries are available. [[uses-scons]] == `scons` Possible arguments: (none) -Provide support for the use of package:devel/scons[]. See <> for more information. +Provide support for the use of package:devel/scons[]. +See crossref:special[using-scons,Using `scons`] for more information. [[uses-shared-mime-info]] == `shared-mime-info` Possible arguments: (none) -Uses update-mime-database from package:misc/shared-mime-info[]. This uses will automatically add a post-install step in such a way that the port itself still can specify there own post-install step if needed. It also add an <> entry to the plist. +Uses update-mime-database from package:misc/shared-mime-info[]. +This uses will automatically add a post-install step in such a way that the port itself still can specify there own post-install step if needed. +It also add an crossref:plist[plist-keywords-shared-mime-info,`@shared-mime-info`] entry to the plist. [[uses-shebangfix]] == `shebangfix` Possible arguments: (none) -A lot of software uses incorrect locations for script interpreters, most notably [.filename]#/usr/bin/perl# and [.filename]#/bin/bash#. The shebangfix macro fixes shebang lines in scripts listed in `SHEBANG_REGEX`, `SHEBANG_GLOB`, or `SHEBANG_FILES`. +A lot of software uses incorrect locations for script interpreters, most notably [.filename]#/usr/bin/perl# and [.filename]#/bin/bash#. +The shebangfix macro fixes shebang lines in scripts listed in `SHEBANG_REGEX`, `SHEBANG_GLOB`, or `SHEBANG_FILES`. `SHEBANG_REGEX`:: -Contains _one_ extended regular expressions, and is used with the `-iregex` argument of man:find[1]. See <>. +Contains _one_ extended regular expressions, and is used with the `-iregex` argument of man:find[1]. +See <>. `SHEBANG_GLOB`:: -Contains a list of patterns used with the `-name` argument of man:find[1]. See <>. +Contains a list of patterns used with the `-name` argument of man:find[1]. +See <>. `SHEBANG_FILES`:: -Contains a list of files or man:sh[1] globs. The shebangfix macro is run from `${WRKSRC}`, so `SHEBANG_FILES` can contain paths that are relative to `${WRKSRC}`. It can also deal with absolute paths if files outside of `${WRKSRC}` require patching. See <>. +Contains a list of files or man:sh[1] globs. +The shebangfix macro is run from `${WRKSRC}`, so `SHEBANG_FILES` can contain paths that are relative to `${WRKSRC}`. +It can also deal with absolute paths if files outside of `${WRKSRC}` require patching. +See <>. Currently Bash, Java, Ksh, Lua, Perl, PHP, Python, Ruby, Tcl, and Tk are supported by default. There are three configuration variables: `SHEBANG_LANG`:: The list of supported interpreters. -`interp_CMD`:: -The path to the command interpreter on FreeBSD. The default value is `${LOCALBASE}/bin/_interp_`. +`_interp__CMD`:: +The path to the command interpreter on FreeBSD. +The default value is `${LOCALBASE}/bin/_interp_`. -`interp_OLD_CMD`:: -The list of wrong invocations of interpreters. These are typically obsolete paths, or paths used on other operating systems that are incorrect on FreeBSD. They will be replaced by the correct path in `interp_CMD`. +`_interp__OLD_CMD`:: +The list of wrong invocations of interpreters. +These are typically obsolete paths, or paths used on other operating systems that are incorrect on FreeBSD. +They will be replaced by the correct path in `_interp__CMD`. + [NOTE] ==== -These will _always_ be part of `interp_OLD_CMD`: `"/usr/bin/env _interp_" /bin/_interp_ /usr/bin/_interp_ /usr/local/bin/_interp_`. +These will _always_ be part of `_interp__OLD_CMD`: `"/usr/bin/env _interp_" /bin/_interp_ /usr/bin/_interp_ /usr/local/bin/_interp_`. ==== + [TIP] ==== - -`interp_OLD_CMD` contain multiple values. Any entry with spaces must be quoted. See <>. +`_interp__OLD_CMD` contain multiple values. +Any entry with spaces must be quoted. +See <>. ==== [IMPORTANT] ==== -The fixing of shebangs is done during the `patch` phase. If scripts are created with incorrect shebangs during the `build` phase, the build process (for example, the [.filename]#configure# script, or the [.filename]#Makefiles#) must be patched or given the right path (for example, with `CONFIGURE_ENV`, `CONFIGURE_ARGS`, `MAKE_ENV`, or `MAKE_ARGS`) to generate the right shebangs. +The fixing of shebangs is done during the `patch` phase. +If scripts are created with incorrect shebangs during the `build` phase, the build process (for example, the [.filename]#configure# script, or the [.filename]#Makefiles#) must be patched or given the right path (for example, with `CONFIGURE_ENV`, `CONFIGURE_ARGS`, `MAKE_ENV`, or `MAKE_ARGS`) to generate the right shebangs. -Correct paths for supported interpreters are available in `interp_CMD`. +Correct paths for supported interpreters are available in `_interp__CMD`. ==== [TIP] ==== - When used with <>, and the aim is only to fix the shebangs but a dependency on Python itself is not wanted, use `PYTHON_NO_DEPENDS=yes`. ==== [[uses-shebangfix-ex-lua]] .Adding Another Interpreter to `USES=shebangfix` [example] ==== - -To add another interpreter, set `SHEBANG_LANG`. For example: +To add another interpreter, set `SHEBANG_LANG`. +For example: [.programlisting] .... SHEBANG_LANG= lua .... ==== [[uses-shebangfix-ex-ksh]] .Specifying all the Paths When Adding an Interpreter to `USES=shebangfix` [example] ==== - -If it was not already defined, and there were no default values for `interp_OLD_CMD` and `interp_CMD` the Ksh entry could be defined as: +If it was not already defined, and there were no default values for `_interp__OLD_CMD` and `_interp__CMD` the Ksh entry could be defined as: [.programlisting] .... SHEBANG_LANG= ksh ksh_OLD_CMD= "/usr/bin/env ksh" /bin/ksh /usr/bin/ksh ksh_CMD= ${LOCALBASE}/bin/ksh .... ==== [[uses-shebangfix-ex-strange]] .Adding a Strange Location for an Interpreter [example] ==== - -Some software uses strange locations for an interpreter. For example, an application might expect Python to be located in [.filename]#/opt/bin/python2.7#. The strange path to be replaced can be declared in the port [.filename]#Makefile#: +Some software uses strange locations for an interpreter. +For example, an application might expect Python to be located in [.filename]#/opt/bin/python2.7#. +The strange path to be replaced can be declared in the port [.filename]#Makefile#: [.programlisting] .... python_OLD_CMD= /opt/bin/python2.7 .... ==== [[uses-shebangfix-ex-regex]] .`USES=shebangfix` with `SHEBANG_REGEX` [example] ==== - To fix all the files in `${WRKSRC}/scripts` ending in [.filename]#.pl#, [.filename]#.sh#, or [.filename]#.cgi# do: [.programlisting] .... USES= shebangfix SHEBANG_REGEX= ./scripts/.*\.(sh|pl|cgi) .... [NOTE] -**** -`SHEBANG_REGEX` is used by running `find -E`, which uses modern regular expressions also known as extended regular expressions. See man:re_format[7] for more information. -**** +====== +`SHEBANG_REGEX` is used by running `find -E`, which uses modern regular expressions also known as extended regular expressions. +See man:re_format[7] for more information. +====== + ==== [[uses-shebangfix-ex-glob]] .`USES=shebangfix` with `SHEBANG_GLOB` [example] ==== To fix all the files in `${WRKSRC}` ending in [.filename]#.pl# or [.filename]#.sh#, do: [.programlisting] .... USES= shebangfix SHEBANG_GLOB= *.sh *.pl .... + ==== [[uses-shebangfix-ex-files]] .`USES=shebangfix` with `SHEBANG_FILES` [example] ==== To fix the files [.filename]#script/foobar.pl# and [.filename]#script/*.sh# in `${WRKSRC}`, do: [.programlisting] .... USES= shebangfix SHEBANG_FILES= scripts/foobar.pl scripts/*.sh .... + ==== [[uses-sqlite]] == `sqlite` Possible arguments: (none), `2`, `3` -Add a dependency on SQLite. The default version used is 3, but version 2 is also possible using the `:2` modifier. +Add a dependency on SQLite. +The default version used is 3, but version 2 is also possible using the `:2` modifier. [[uses-ssl]] == `ssl` Possible arguments: (none), `build`, `run` -Provide support for OpenSSL. A build- or run-time only dependency can be specified using `build` or `run`. These variables are available for the port's use, they are also added to `MAKE_ENV`: +Provide support for OpenSSL. +A build- or run-time only dependency can be specified using `build` or `run`. +These variables are available for the port's use, they are also added to `MAKE_ENV`: `OPENSSLBASE`:: Path to the OpenSSL installation base. `OPENSSLDIR`:: Path to OpenSSL's configuration files. `OPENSSLLIB`:: Path to the OpenSSL libraries. `OPENSSLINC`:: Path to the OpenSSL includes. `OPENSSLRPATH`:: If defined, the path the linker needs to use to find the OpenSSL libraries. [TIP] ==== - -If a port does not build with an OpenSSL flavor, set the `BROKEN_SSL` variable, and possibly the `BROKEN_SSL_REASON_flavor`: +If a port does not build with an OpenSSL flavor, set the `BROKEN_SSL` variable, and possibly the `BROKEN_SSL_REASON__flavor_`: [.programlisting] .... BROKEN_SSL= libressl BROKEN_SSL_REASON_libressl= needs features only available in OpenSSL .... ==== [[uses-tar]] == `tar` Possible arguments: (none), `Z`, `bz2`, `bzip2`, `lzma`, `tbz`, `tbz2`, `tgz`, `txz`, `xz` Set `EXTRACT_SUFX` to `.tar`, `.tar.Z`, `.tar.bz2`, `.tar.bz2`, `.tar.lzma`, `.tbz`, `.tbz2`, `.tgz`, `.txz` or `.tar.xz` respectively. [[uses-tcl]] == `tcl` Possible arguments: _version_, `wrapper`, `build`, `run`, `tea` -Add a dependency on Tcl. A specific version can be requested using _version_. The version can be empty, one or more exact version numbers (currently `84`, `85`, or `86`), or a minimal version number (currently `84+`, `85+` or `86+`). To only request a non version specific wrapper, use `wrapper`. A build- or run-time only dependency can be specified using `build` or `run`. To build the port using the Tcl Extension Architecture, use `tea`. After including [.filename]#bsd.port.pre.mk# the port can inspect the results using these variables: +Add a dependency on Tcl. A specific version can be requested using _version_. +The version can be empty, one or more exact version numbers (currently `84`, `85`, or `86`), or a minimal version number (currently `84+`, `85+` or `86+`). +To only request a non version specific wrapper, use `wrapper`. +A build- or run-time only dependency can be specified using `build` or `run`. +To build the port using the Tcl Extension Architecture, use `tea`. +After including [.filename]#bsd.port.pre.mk# the port can inspect the results using these variables: * `TCL_VER`: chosen major.minor version of Tcl * `TCLSH`: full path of the Tcl interpreter * `TCL_LIBDIR`: path of the Tcl libraries * `TCL_INCLUDEDIR`: path of the Tcl C header files * `TK_VER`: chosen major.minor version of Tk * `WISH`: full path of the Tk interpreter * `TK_LIBDIR`: path of the Tk libraries * `TK_INCLUDEDIR`: path of the Tk C header files [[uses-terminfo]] == `terminfo` Possible arguments: (none) -Adds <> to the [.filename]#plist#. Use when the port installs [.filename]#*.terminfo# files in [.filename]#${PREFIX}/shared/misc#. +Adds crossref:plist[plist-keywords-terminfo,`@terminfo`] to the [.filename]#plist#. +Use when the port installs [.filename]#*.terminfo# files in [.filename]#${PREFIX}/share/misc#. [[uses-tk]] == `tk` Same as arguments for `tcl` -Small wrapper when using both Tcl and Tk. The same variables are returned as when using Tcl. +Small wrapper when using both Tcl and Tk. +The same variables are returned as when using Tcl. [[uses-uidfix]] == `uidfix` Possible arguments: (none) -Changes some default behavior (mostly variables) of the build system to allow installing this port as a normal user. Try this in the port before using <> or patching. +Changes some default behavior (mostly variables) of the build system to allow installing this port as a normal user. +Try this in the port before using <> or patching. [[uses-uniquefiles]] == `uniquefiles` Possible arguments: (none), `dirs` -Make files or directories 'unique', by adding a prefix or suffix. If the `dirs` argument is used, the port needs a prefix (and only a prefix) based on `UNIQUE_PREFIX` for standard directories `DOCSDIR`, `EXAMPLESDIR`, `DATADIR`, `WWWDIR`, `ETCDIR`. These variables are available for ports: +Make files or directories 'unique', by adding a prefix or suffix. +If the `dirs` argument is used, the port needs a prefix (and only a prefix) based on `UNIQUE_PREFIX` for standard directories `DOCSDIR`, `EXAMPLESDIR`, `DATADIR`, `WWWDIR`, `ETCDIR`. +These variables are available for ports: * `UNIQUE_PREFIX`: The prefix to be used for directories and files. Default: `${PKGNAMEPREFIX}`. * `UNIQUE_PREFIX_FILES`: A list of files that need to be prefixed. Default: empty. * `UNIQUE_SUFFIX`: The suffix to be used for files. Default: `${PKGNAMESUFFIX}`. * `UNIQUE_SUFFIX_FILES`: A list of files that need to be suffixed. Default: empty. [[uses-varnish]] == `varnish` Possible arguments: `4`, `5` -Handle dependencies on Varnish Cache. `4` will add a dependency on package:www/varnish4[]. `5` will add a dependency on package:www/varnish5[]. +Handle dependencies on Varnish Cache. +`4` will add a dependency on package:www/varnish4[]. +`5` will add a dependency on package:www/varnish5[]. [[uses-webplugin]] == `webplugin` Possible arguments: (none), `ARGS` -Automatically create and remove symbolic links for each application that supports the webplugin framework. `ARGS` can be one of: +Automatically create and remove symbolic links for each application that supports the webplugin framework. +`ARGS` can be one of: * `gecko`: support plug-ins based on Gecko * `native`: support plug-ins for Gecko, Opera, and WebKit-GTK * `linux`: support Linux plug-ins * `all` (default, implicit): support all plug-in types * (individual entries): support only the browsers listed These variables can be adjusted: * `WEBPLUGIN_FILES`: No default, must be set manually. The plug-in files to install. * `WEBPLUGIN_DIR`: The directory to install the plug-in files to, default [.filename]#PREFIX/lib/browser_plugins/WEBPLUGIN_NAME#. Set this if the port installs plug-in files outside of the default directory to prevent broken symbolic links. * `WEBPLUGIN_NAME`: The final directory to install the plug-in files into, default `PKGBASE`. [[uses-xfce]] == `xfce` Possible arguments: (none), `gtk2` -Provide support for Xfce related ports. See <> for details. +Provide support for Xfce related ports. +See crossref:special[using-xfce,Using Xfce] for details. -The `gtk2` argument specifies that the port requires GTK2 support. It adds additional features provided by some core components, for example, package:x11/libxfce4menu[] and package:x11-wm/xfce4-panel[]. +The `gtk2` argument specifies that the port requires GTK2 support. +It adds additional features provided by some core components, for example, package:x11/libxfce4menu[] and package:x11-wm/xfce4-panel[]. [[uses-xorg]] == `xorg` Possible arguments: (none) -Provides an easy way to depend on X.org components. The components should be listed in `USE_XORG`. The available components are: +Provides an easy way to depend on X.org components. +The components should be listed in `USE_XORG`. +The available components are: + [[using-x11-components]] .Available X.Org Components [cols="1,1", frame="none", options="header"] |=== | Name | Description |`dmx` |DMX extension library |`fontenc` |The fontenc Library |`fontutil` |Create an index of X font files in a directory |`ice` |Inter Client Exchange library for X11 |`libfs` |The FS library |`pciaccess` |Generic PCI access library |`pixman` |Low-level pixel manipulation library |`sm` |Session Management library for X11 |`x11` |X11 library |`xau` |Authentication Protocol library for X11 |`xaw` |X Athena Widgets library |`xaw6` |X Athena Widgets library |`xaw7` |X Athena Widgets library |`xbitmaps` |X.Org bitmaps data |`xcb` |The X protocol C-language Binding (XCB) library |`xcomposite` |X Composite extension library |`xcursor` |X client-side cursor loading library |`xdamage` |X Damage extension library |`xdmcp` |X Display Manager Control Protocol library |`xext` |X11 Extension library |`xfixes` |X Fixes extension library |`xfont` |X font library |`xfont2` |X font library |`xft` |Client-sided font API for X applications |`xi` |X Input extension library |`xinerama` |X11 Xinerama library |`xkbfile` |XKB file library |`xmu` |X Miscellaneous Utilities libraries |`xmuu` |X Miscellaneous Utilities libraries |`xorg-macros` |X.Org development aclocal macros |`xorg-server` |X.Org X server and related programs |`xorgproto` |xorg protocol headers |`xpm` |X Pixmap library |`xpresent` |X Present Extension library |`xrandr` |X Resize and Rotate extension library |`xrender` |X Render extension library |`xres` |X Resource usage library |`xscrnsaver` |The XScrnSaver library |`xshmfence` |Shared memory 'SyncFence' synchronization primitive |`xt` |X Toolkit library |`xtrans` |Abstract network code for X |`xtst` |X Test extension |`xv` |X Video Extension library |`xvmc` |X Video Extension Motion Compensation library |`xxf86dga` |X DGA Extension |`xxf86vm` |X Vidmode Extension |=== [[uses-xorg-cat]] == `xorg-cat` Possible arguments: `app`, `data`, `doc`, `driver`, `font`, `lib`, `proto`, `util`, `xserver` and (none) or one off `autotools` (default), `meson` -Provide support for building Xorg components. It takes care of setting up common dependencies and an appropriate configuration environment needed. This is intended only for Xorg components. +Provide support for building Xorg components. +It takes care of setting up common dependencies and an appropriate configuration environment needed. +This is intended only for Xorg components. The category has to match upstream categories. -The second argument is the build system to use. autotools is the default, but meson is also supported. +The second argument is the build system to use. +autotools is the default, but meson is also supported. [[uses-zip]] == `zip` Possible arguments: (none), `infozip` -Indicates that the distribution files use the ZIP compression algorithm. For files using the InfoZip algorithm the `infozip` argument must be passed to set the appropriate dependencies. +Indicates that the distribution files use the ZIP compression algorithm. +For files using the InfoZip algorithm the `infozip` argument must be passed to set the appropriate dependencies. diff --git a/documentation/content/ru/books/porters-handbook/versions/chapter.adoc b/documentation/content/ru/books/porters-handbook/versions/_index.adoc similarity index 100% rename from documentation/content/ru/books/porters-handbook/versions/chapter.adoc rename to documentation/content/ru/books/porters-handbook/versions/_index.adoc