diff options
Diffstat (limited to 'ru_RU.KOI8-R/books/porters-handbook/makefiles/chapter.xml')
| -rw-r--r-- | ru_RU.KOI8-R/books/porters-handbook/makefiles/chapter.xml | 4315 |
1 files changed, 4315 insertions, 0 deletions
diff --git a/ru_RU.KOI8-R/books/porters-handbook/makefiles/chapter.xml b/ru_RU.KOI8-R/books/porters-handbook/makefiles/chapter.xml new file mode 100644 index 0000000000..12e66950df --- /dev/null +++ b/ru_RU.KOI8-R/books/porters-handbook/makefiles/chapter.xml @@ -0,0 +1,4315 @@ +<?xml version="1.0" encoding="koi8-r"?> +<!-- + The FreeBSD Russian Documentation Project + + $FreeBSD$ + + Original revision: r43840 +--> + +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="makefiles"> + + <title>Настройка файла Makefile</title> + + <para>Настройка файла <filename>Makefile</filename> достаточно проста, и + мы снова предполагаем, что перед тем, как начать, вы посмотрите на + существующие примеры. К тому же в этом руководстве имеется <link linkend="porting-samplem">примерный Makefile</link>, так что взгляните + на него и, пожалуйста, следуйте порядку переменных и разделов в этом + образце, чтобы облегчить чтение вашего порта другими людьми.</para> + + <para>Итак, расположим решаемые задачи в порядке их возникновения при + создании вашего нового файла <filename>Makefile</filename>:</para> + + <sect1 xml:id="makefile-source"> + <title>Оригинальные исходный код</title> + + <para>Находится ли он в каталоге <varname>DISTDIR</varname> в виде + стандартного упакованного архиватором <command>gzip</command> + tar-архива с именем типа + <filename>foozolix-1.2.tar.gz</filename>? Если это так, + можно перейти к следующему шагу. Если нет, то вы должны попытаться + переопределить некоторые из переменных + <varname>DISTVERSION</varname>, <varname>DISTNAME</varname>, + <varname>EXTRACT_CMD</varname>, + <varname>EXTRACT_BEFORE_ARGS</varname>, + <varname>EXTRACT_AFTER_ARGS</varname>, + <varname>EXTRACT_SUFX</varname> или <varname>DISTFILES</varname> в + зависимости от того, насколько необычен формат дистрибутивного + файла.</para> + + <para>В худшем случае вы можете просто определить свою собственную цель + <buildtarget>do-extract</buildtarget> для переопределения действий по + умолчанию, хотя к этому нужно будет прибегать в очень редких случаях, + если вообще придётся.</para> + </sect1> + + <sect1 xml:id="makefile-naming"> + <title>Именование</title> + + <para>В первой части <filename>Makefile</filename> порта ему даётся + название, указывается его номер версии и принадлежность к правильной + категории.</para> + + <sect2> + <title><varname>PORTNAME</varname> и + <varname>PORTVERSION</varname></title> + + <para>В переменной <varname>PORTNAME</varname> вы должны указать + основную часть имени вашего порта, а в переменной + <varname>PORTVERSION</varname> - номер версии.</para> + </sect2> + + <sect2 xml:id="makefile-naming-revepoch"> + <title><varname>PORTREVISION</varname> и + <varname>PORTEPOCH</varname></title> + + <sect3> + <title><varname>PORTREVISION</varname></title> + + <para>Переменная <varname>PORTREVISION</varname> представляет собой + монотонно увеличивающееся число, которое обнуляется при каждом + увеличении значения переменной <varname>PORTVERSION</varname> (то + есть каждый раз, когда создателями выпускается новый официальный + релиз), и добавляется к имени пакета, если оно не равно нулю. + Изменения в <varname>PORTREVISION</varname> используются + автоматизированными инструментами (например, + <command>pkg version</command>, см. &man.pkg-version.8;) + для определения факта появления нового пакета.</para> + + <para>Значение <varname>PORTREVISION</varname> должно увеличиваться + каждый раз, когда в порте FreeBSD делаются изменения, которые + как-либо меняют получаемый пакет. Сюда относятся только + изменения, затрагивающие построение пакета с <link + linkend="makefile-options">параметрами</link> по + умолчанию.</para> + + <para>Примеры случаев, когда значение <varname>PORTREVISION</varname> + должно быть увеличено:</para> + + <itemizedlist> + <listitem> + <para>Добавление патчей для исправления уязвимостей, + ошибок, или добавления новой функциональности в порт.</para> + </listitem> + + <listitem> + <para>Изменения в файле <filename>Makefile</filename> порта для + включения и выключения параметров, определяемых при компиляции + пакета.</para> + </listitem> + + <listitem> + <para>Изменения в списке упаковки или в поведении пакета во + время его установки (например, изменение скрипта, генерирующего + начальные данные для пакета, такие, как ssh-ключи для + хоста).</para> + </listitem> + + <listitem> + <para>Увеличение версии динамической библиотеки, от которой + зависит порт (в этом случае тот, кто попытается установить + старый пакет после установки более новой версии библиотеки, + не сможет этого сделать, потому что при этом будет делаться + поиск старой библиотеки libfoo.x, а не libfoo.(x+1)).</para> + </listitem> + + <listitem> + <para>Большие функциональные изменения в дистрибутивном файле + порта, происходящие без объявлений, и приводящие к большим + изменениям, то есть изменения в дистрибутиве требуют + корректировки файла <filename>distinfo</filename> без + соответствующего изменения <varname>PORTVERSION</varname>, + когда как команда <command>diff -ru</command> между новой + и старой версиями показывает нетривиальные изменения в + коде.</para> + </listitem> + </itemizedlist> + + <para>Примеры изменений, которые не требуют увеличения переменной + <varname>PORTREVISION</varname>:</para> + + <itemizedlist> + <listitem> + <para>Изменения стиля в скелете порта без функциональных изменений + в пакете.</para> + </listitem> + + <listitem> + <para>Изменения в переменной <varname>MASTER_SITES</varname> или + другие функциональные изменения порта, которые не затрагивают + получающегося пакета.</para> + </listitem> + + <listitem> + <para>Тривиальные патчи к дистрибутивному файлу, такие, как + исправления опечаток, которые не так уж важны, что пользователи + пакета должны озаботиться обновлением.</para> + </listitem> + + <listitem> + <para>Исправления, касающиеся этапа построения, которые делают + возможным построение пакета, если ранее это было невозможно + сделать (пока изменения не приводят к изменению работы на любых + других платформах, на которых порт ранее строился). Так как + <varname>PORTREVISION</varname> отражает содержимое пакета, + то, если ранее пакет не строился, то нет нужды увеличивать + <varname>PORTREVISION</varname> для отметки изменения.</para> + </listitem> + </itemizedlist> + + <para>Правило, которому нужно приблизительно следовать, заключается в + том, что нужно спрашивать себя, является ли вносимое в порт + изменение таким, что от него выиграют все (в виде + усовершенствования, исправления или благодаря тому, что новый + пакет будет вообще работоспособным), и примите во внимание тот + факт, что при этом все, кто регулярно обновляют своё дерево портов, + будут обязаны это сделать. Если это так, то переменная + <varname>PORTREVISION</varname> должна быть увеличена.</para> + </sect3> + + <sect3> + <title><varname>PORTEPOCH</varname></title> + + <para>Время от времени разработчик программного обеспечения или + создатель порта &os; делают что-то не так и выпускают версию + программы, номер которой меньше предыдущей версии. Примером этого + является порт, название которого меняется с foo-20000801 на foo-1.0 + (изначально это не считалось бы более новой версией, так как + 20000801 численно больше, чем 1).</para> + + <tip> + <para>Результат сравнения номера версии не всегда очевиден. + Для выполнения сравнения двух строк с номером версии можно + использовать <command>pkg version</command> + (см. &man.pkg-version.8;). Например:</para> + + <screen>&prompt.user; <userinput>pkg_version -t 0.031 0.29</userinput> +></screen> + + <para>Для пользователей <application>pkgng</application>:</para> + + <screen>&prompt.user; <userinput>pkg version -t 0.031 0.29</userinput> +></screen> + + <para>Строка <literal>></literal> в выводе команды означает, + что версия 0.031 считается выше, чем версия 0.29, что может + быть не очевидно для того, кто выполняет портирование.</para> + </tip> + + <para>В ситуациях, подобных этой, должно быть увеличено значение + <varname>PORTEPOCH</varname>. Если значение + <varname>PORTEPOCH</varname> не равно нулю, то оно добавляется к + имени пакета, как описано в разделе выше. Значение + <varname>PORTEPOCH</varname> никогда не должно уменьшаться или + сбрасываться в ноль, потому что это приведёт к ошибке сравнения с + пакетом с меньшим номером эпохи (то есть то, что пакет устарел, + обнаружено не будет): номер новой версии (например, + <literal>1.0,1</literal> в примере выше) останется меньше, чем + номер предыдущей версии (20000801), однако суффикс + <literal>,1</literal> интерпретируется различными + автоматизированными утилитами особым образом, и окажется больше, + чем предполагаемый суффикс <literal>,0</literal> более раннего + пакета).</para> + + <para>Некорректное уменьшение или сброс <varname>PORTEPOCH</varname> + приводит к печальным последствиям; если вы не поняли, о чём шла + речь ранее, пожалуйста, всё же разберитесь с этим, либо спросите + в списках рассылки.</para> + + <para>Предполагается, что в большинстве портов переменная + <varname>PORTEPOCH</varname> использоваться не будет, но при + корректном использовании <varname>PORTVERSION</varname> может + появиться необходимость её иметь, если в будущих релизах + программное обеспечение должно изменить структуру номера версии. + Однако создателям портов для &os; нужно быть внимательными, когда + разработчик выпускает релиз без официального номера версии — + эдакие <quote>промежуточные</quote> релизы. Имеется соблазн + пометить релиз датой его выхода, что может вызвать проблемы, как и + в примере выше, когда будет выпущен новый + <quote>официальный</quote> релиз.</para> + + <para>Например, если промежуточный релиз помечен датой 20000917, а + предыдущая версия программного обеспечения имела номер 1.2, то + промежуточному релизу должно быть поставлено в соответствие + значение <varname>PORTVERSION</varname>, равное 1.2.20000917 или + что-то похожее, но не 20000917, так как последующий релиз, скажем, + 1.3, должен иметь численно большее значение.</para> + </sect3> + + <sect3> + <title>Пример использования переменных + <varname>PORTREVISION</varname> и + <varname>PORTEPOCH</varname></title> + + <para>Выполнен коммит порта <literal>gtkmumble</literal>, версии + <literal>0.10</literal>, в коллекцию портов.</para> + + <programlisting>PORTNAME= gtkmumble +PORTVERSION= 0.10</programlisting> + + <para>Значение <varname>PKGNAME</varname> станет равным + <literal>gtkmumble-0.10</literal>.</para> + + <para>Обнаружена брешь в безопасности, исправление которой + потребовало создания + локального патча для &os;. Соответственно было увеличено + значение переменной <varname>PORTREVISION</varname>.</para> + + <programlisting>PORTNAME= gtkmumble +PORTVERSION= 0.10 +PORTREVISION= 1</programlisting> + + <para><varname>PKGNAME</varname> принимает значение + <literal>gtkmumble-0.10_1</literal></para> + + <para>Разработчиком выпущена новая версия с номером + <literal>0.2</literal> (оказалось, что под номером + <literal>0.10</literal> автор имел в виду + <literal>0.1.0</literal>, а не <quote>то, что будет выпущено после + версии 0.9</quote> - извините, теперь уже поздно). Так как новый + младший номер версии <literal>2</literal> по значению меньше, чем + номер предыдущей версии <literal>10</literal>, то должно быть + увеличено значение <varname>PORTEPOCH</varname> для того, чтобы + заставить распознавать вновь создаваемый пакет как <quote>более + новый</quote>. Так как это новый релиз программы, то + <varname>PORTREVISION</varname> обнуляется (или удаляется из + файла <filename>Makefile</filename>).</para> + + <programlisting>PORTNAME= gtkmumble +PORTVERSION= 0.2 +PORTEPOCH= 1</programlisting> + + <para><varname>PKGNAME</varname> принимает значение + <literal>gtkmumble-0.2,1</literal></para> + + <para>Следующий релиз имеет номер версии 0.3. Так как значение + переменной <varname>PORTEPOCH</varname> никогда не уменьшается, что + переменные, определяющие версии, теперь выглядят так:</para> + + <programlisting>PORTNAME= gtkmumble +PORTVERSION= 0.3 +PORTEPOCH= 1</programlisting> + + <para><varname>PKGNAME</varname> принимает значение + <literal>gtkmumble-0.3,1</literal></para> + + <note> + <para>Если значение <varname>PORTEPOCH</varname> этим обновлением + было бы сброшено в <literal>0</literal>, то кто-нибудь, имеющий + установленный пакет <literal>gtkmumble-0.10_1</literal>, не + смог бы опознать пакет <literal>gtkmumble-0.3</literal> как + более новый, так как <literal>3</literal> было бы меньше, чем + <literal>10</literal>. Помните, что в первую очередь это + касается <varname>PORTEPOCH</varname>.</para> + </note> + </sect3> + </sect2> + + <sect2> + <title>Переменные <varname>PKGNAMEPREFIX</varname> + и <varname>PKGNAMESUFFIX</varname></title> + + <para>Две необязательные переменные, <varname>PKGNAMEPREFIX</varname> и + <varname>PKGNAMESUFFIX</varname>, объединяются со значениями + <varname>PORTNAME</varname> и + <varname>PORTVERSION</varname> для формирования + <varname>PKGNAME</varname> в форме + <literal>${PKGNAMEPREFIX}${PORTNAME}${PKGNAMESUFFIX}-${PORTVERSION}</literal>. + Добейтесь того, чтобы это соответствовало нашим <link linkend="porting-pkgname">рекомендациям по правильному выбору + названий для пакетов</link>. В частности, в переменной + <varname>PORTVERSION</varname> <emphasis>не разрешается</emphasis> + использование дефиса (<literal>-</literal>). Кроме того, если в + имени пакета присутствует часть <replaceable>language-</replaceable> + или <replaceable>-compiled.specifics</replaceable> (смотрите ниже), + то используйте переменные <varname>PKGNAMEPREFIX</varname> и + <varname>PKGNAMESUFFIX</varname>, соответственно. Не делайте их + частью значения переменной <varname>PORTNAME</varname>.</para> + </sect2> + + <sect2 xml:id="porting-pkgname"> + <title>Соглашения по именованию пакетов</title> + + <para>Далее описаны некоторые соглашения, которым вы должны следовать + в именовании ваших пакетов. Они были разработаны для облегчения + просмотра каталога, так как имеется уже тысячи пакетов, а + пользователи отвернутся от нас, если список не понравится их + взору!</para> + + <para>Имя пакета должно иметь вид + <filename>language_region-name-compiled.specifics-version.numbers</filename>.</para> + + <para>Имя пакета определяется как + <literal>${PKGNAMEPREFIX}${PORTNAME}${PKGNAMESUFFIX}-${PORTVERSION}</literal>. + Вы должны задавать значения переменных в соответствии с этим + форматом.</para> + + <orderedlist> + <listitem> + <para>&os; пытается поддерживать языки, на которых разговаривают + её пользователи. Часть <replaceable>language-</replaceable> + должна быть двухсимвольным сокращением от названия языка по + стандарту ISO-639, если порт специфичен для конкретного языка. + Примерами являются <literal>ja</literal> для японского, + <literal>ru</literal> для русского, <literal>vi</literal> для + вьетнамского, <literal>zh</literal> для китайского, + <literal>ko</literal> для корейского и <literal>de</literal> для + немецкого языков.</para> + + <para>Если ваш порт специфичен для конкретного региона внутри + области использования языка, добавьте также двухсимвольный код + страны. Примерами являются <literal>en_US</literal> для US + English и <literal>fr_CH</literal> для Swiss French.</para> + + <para>Часть <replaceable>language-</replaceable> должна задаваться + в переменной <varname>PKGNAMEPREFIX</varname>.</para> + </listitem> + + <listitem> + <para>Первая буква части <filename>name</filename> должна быть в + нижнем регистре. (Оставшаяся часть названия может содержать + буквы в верхнем регистре, так что принимайте решение сами, когда + преобразуете имя программного пакета, содержащего в имени + некоторое количество заглавных букв.) Существует традиция + именовать модули для <literal>Perl 5</literal>, добавляя впереди + <literal>p5-</literal> и преобразуя пару двоеточий в + дефис; например, модуль <literal>Data::Dumper</literal> будет + именоваться <literal>p5-Data-Dumper</literal>.</para> + </listitem> + + <listitem> + <para>Убедитесь, что имя порта и версия четко отделены и + размещаются в переменных <varname>PORTNAME</varname> и + <varname>PORTVERSION</varname>. Единственная причина, по + которой <varname>PORTNAME</varname> содержит версионную часть, + это если полученный дистрибутив сам назван таким образом, как + это сделано для портов <filename>textproc/libxml2</filename> + или <filename>japanese/kinput2-freewnn</filename>. В противном + случае <varname>PORTNAME</varname> не должен содержать никакой + информации, указывающей на версию. То, что некоторые порты + имеют одинаковый <varname>PORTNAME</varname>, является вполне + нормальным, как для портов <filename>www/apache*</filename>; + в этом случае различные версии (и различные записи в индексе) + отличаются по значениям <varname>PKGNAMEPREFIX</varname> + и <varname>PKGNAMESUFFIX</varname>.</para> + </listitem> + + <listitem> + <para>Если порт может быть построен с различными <link linkend="makefile-masterdir">статически заданными значениями по + умолчанию</link> (обычно это часть имени каталога в семействе + портов), то часть <replaceable>-compiled.specifics</replaceable> + должна определять вкомпилированные значения по умолчанию (дефис + не обязателен). Примерами являются размеры бумаги и + шрифтов.</para> + + <para>Часть <replaceable>-compiled.specifics</replaceable> должна + задаваться в переменной <varname>PKGNAMESUFFIX</varname>.</para> + </listitem> + + <listitem> + <para>Строка с номером версии должна следовать за дефисом + (<literal>-</literal>) и являться списком разделенных двоеточием + чисел и букв в нижнем регистре. В частности, не разрешается + иметь еще один дефис внутри строки с обозначением номера версии. + Единственным исключением является строчка <literal>pl</literal> + (означающая <quote>patchlevel</quote>), которая может + использоваться <emphasis>только</emphasis> тогда, когда у + программного обеспечения нет старшего и младшего номера версии. + Если в номер версии программного обеспечения включена строчка + типа <quote>alpha</quote>, <quote>beta</quote>, + <quote>rc</quote> или <quote>pre</quote>, возьмите из неё первую + букву и поставьте её непосредственно после точки. Если после + таких строк номер версии ещё продолжается, то после буквы должно + следовать число без дополнительной разделяющей точки.</para> + + <para>Смысл такого формата заключается в удобстве сортировки портов + по номеру версии. В частности, следите за тем, чтобы компоненты + номера версии разделялись точкой, и если там присутствует дата, + то используйте формат + <literal>0.0.yyyy.mm.dd</literal>, но не + <literal>dd.mm.yyyy</literal> + или не совместимый с проблемой Y2K + <literal>yy.mm.dd</literal>. + Добавление к версии префикса <literal>0.0.</literal> является + важным, в случае если выпущен релиз с присвоением настоящей + версии, которая в числовом представлении, конечно же, будет + ниже, чем + <literal>yyyy</literal>.</para> + </listitem> + </orderedlist> + + <para>Вот несколько (реальных) примеров того, как преобразовать имя из + оригинального, придуманного авторами, к подходящему для имени + пакета:</para> + + <informaltable frame="none" pgwide="1"> + <tgroup cols="6"> + <thead> + <row> + <entry>Имя дистрибутива</entry> + + <entry><varname>PKGNAMEPREFIX</varname></entry> + + <entry><varname>PORTNAME</varname></entry> + + <entry><varname>PKGNAMESUFFIX</varname></entry> + + <entry><varname>PORTVERSION</varname></entry> + + <entry>Обоснование</entry> + </row> + </thead> + + <tbody> + <row> + <entry>mule-2.2.2</entry> + <entry>(пусто)</entry> + <entry>mule</entry> + <entry>(пусто)</entry> + <entry>2.2.2</entry> + <entry>Изменений не потребовалось</entry> + </row> + + <row> + <entry>EmiClock-1.0.2</entry> + <entry>(пусто)</entry> + <entry>emiclock</entry> + <entry>(пусто)</entry> + <entry>1.0.2</entry> + <entry>Для отдельных программ имена с заглавными буквами + запрещены</entry> + </row> + + <row> + <entry>rdist-1.3alpha</entry> + <entry>(пусто)</entry> + <entry>rdist</entry> + <entry>(пусто)</entry> + <entry>1.3.a</entry> + <entry>Строчки типа <literal>alpha</literal> запрещены</entry> + </row> + + <row> + <entry>es-0.9-beta1</entry> + <entry>(пусто)</entry> + <entry>es</entry> + <entry>(пусто)</entry> + <entry>0.9.b1</entry> + <entry>Строчки типа <literal>beta</literal> запрещены</entry> + </row> + + <row> + <entry>mailman-2.0rc3</entry> + <entry>(пусто)</entry> + <entry>mailman</entry> + <entry>(пусто)</entry> + <entry>2.0.r3</entry> + <entry>Строчки типа <literal>rc</literal> запрещены</entry> + </row> + + <row> + <entry>v3.3beta021.src</entry> + <entry>(пусто)</entry> + <entry>tiff</entry> + <entry>(пусто)</entry> + <entry>3.3</entry> + <entry>Что это такое было вообще?</entry> + </row> + + <row> + <entry>tvtwm</entry> + <entry>(пусто)</entry> + <entry>tvtwm</entry> + <entry>(пусто)</entry> + <entry>pl11</entry> + <entry>Всегда требуется указание номера версии</entry> + </row> + + <row> + <entry>piewm</entry> + <entry>(пусто)</entry> + <entry>piewm</entry> + <entry>(пусто)</entry> + <entry>1.0</entry> + <entry>Всегда требуется указание номера версии</entry> + </row> + + <row> + <entry>xvgr-2.10pl1</entry> + <entry>(пусто)</entry> + <entry>xvgr</entry> + <entry>(пусто)</entry> + <entry>2.10.1</entry> + <entry><literal>pl</literal> разрешено только при отсутствии + старшего/младшего номера версии</entry> + </row> + + <row> + <entry>gawk-2.15.6</entry> + <entry>ja-</entry> + <entry>gawk</entry> + <entry>(пусто)</entry> + <entry>2.15.6</entry> + <entry>Версия на японском языке</entry> + </row> + + <row> + <entry>psutils-1.13</entry> + <entry>(пусто)</entry> + <entry>psutils</entry> + <entry>-letter</entry> + <entry>1.13</entry> + <entry>Размер бумаги задается статически во время построения + пакета</entry> + </row> + + <row> + <entry>pkfonts</entry> + <entry>(пусто)</entry> + <entry>pkfonts</entry> + <entry>300</entry> + <entry>1.0</entry> + <entry>пакет для шрифтов 300dpi</entry> + </row> + </tbody> + </tgroup> + </informaltable> + + <para>Если в исходном коде абсолютно нет информации о номере версии и + не похоже, что автор собирается выпускать другую версию, то в + качестве номера версии задайте просто <literal>1.0</literal> (как в + примере с <literal>piewm</literal> выше). В противном случае + спросите автора программы или используйте дату + (<literal>0.0.yyyy.mm.dd</literal>) + в качестве номера версии.</para> + </sect2> + </sect1> + + <sect1 xml:id="makefile-categories"> + <title>Разделение по категориям</title> + + <sect2> + <title><varname>CATEGORIES</varname></title> + + <para>В процессе создания пакета он помещается в каталог + <filename>/usr/ports/packages/All</filename>, а в одном или более + подкаталогов из <filename>/usr/ports/packages</filename> + создаются на него ссылки. Имена этих подкаталогов определяются + переменной <varname>CATEGORIES</varname>. Такая схема нужна для + облегчения жизни пользователя, когда он сталкивается с массой + пакетов на FTP-сервере или компакт-диске. Пожалуйста, посмотрите на + <link linkend="porting-categories">текущий список категорий</link> + и выберите те из них, + которые более всего подходят к вашему порту.</para> + + <para>Этот список также определяет, куда в дереве портов будет помещен + порт. Если вы укажете здесь более одной категории, то + предполагается, что файлы порта будут помещены в подкаталог с именем + первой категории. Посмотрите <link linkend="choosing-categories">ниже</link> для получения + подробной информации о том, как правильно выбрать категории.</para> + </sect2> + + <sect2 xml:id="porting-categories"> + <title>Текущий список категорий</title> + + <para>Вот текущий список категорий. Те, которые отмечены + звёздочкой (<literal>*</literal>), являются + <emphasis>виртуальными</emphasis> категориями—они не имеют + собственного подкаталога в дереве портов. Они используются только в + качестве вторичных категорий, и только для поиска.</para> + + <note> + <para>Для невиртуальных категорий имеется однострочное описание + в <varname>COMMENT</varname> в <filename>Makefile</filename> + соответствующего подкаталога.</para> + </note> + + <informaltable frame="none" pgwide="1"> + <tgroup cols="3"> + <thead> + <row> + <entry>Категория</entry> + + <entry>Описание</entry> + + <entry>Примечания</entry> + </row> + </thead> + + <tbody> + <row> + <entry><filename>accessibility</filename></entry> + <entry>Порты для помощи пользователям с ограниченными + возможностями.</entry> + <entry/> + </row> + + <row> + <entry><filename>afterstep*</filename></entry> + <entry>Порты, поддерживающие менеджер окон <link xlink:href="http://www.afterstep.org">AfterStep</link>.</entry> + <entry/> + </row> + + <row> + <entry><filename>arabic</filename></entry> + <entry>Поддержка арабского языка.</entry> + <entry/> + </row> + + <row> + <entry><filename>archivers</filename></entry> + <entry>Инструменты для работы с архивами.</entry> + <entry/> + </row> + + <row> + <entry><filename>astro</filename></entry> + <entry>Приложения, связанные с астрономией.</entry> + <entry/> + </row> + + <row> + <entry><filename>audio</filename></entry> + <entry>Поддержка работы со звуком.</entry> + <entry/> + </row> + + <row> + <entry><filename>benchmarks</filename></entry> + <entry>Утилиты для измерения производительности системы.</entry> + <entry/> + </row> + + <row> + <entry><filename>biology</filename></entry> + <entry>Программное обеспечение, связанное с биологией.</entry> + <entry/> + </row> + + <row> + <entry><filename>cad</filename></entry> + <entry>Инструменты Систем Автоматизированного + Проектирования.</entry> + <entry/> + </row> + + <row> + <entry><filename>chinese</filename></entry> + <entry>Поддержка китайского языка.</entry> + <entry/> + </row> + + <row> + <entry><filename>comms</filename></entry> + <entry>Коммуникационное программное обеспечение.</entry> + <entry>В основном программы для работы с последовательным + портом.</entry> + </row> + + <row> + <entry><filename>converters</filename></entry> + <entry>Утилиты для преобразования символьных форматов.</entry> + <entry/> + </row> + + <row> + <entry><filename>databases</filename></entry> + <entry>Базы данных.</entry> + <entry/> + </row> + + <row> + <entry><filename>deskutils</filename></entry> + <entry>То, что было на столе до изобретения компьютеров.</entry> + <entry/> + </row> + + <row> + <entry><filename>devel</filename></entry> + <entry>Утилиты для разработки программного обеспечения.</entry> + <entry>Не помещайте сюда библиотеки просто потому что это + библиотеки—если они подпадают под какую-то другую + категорию, то их быть здесь не должно.</entry> + </row> + + <row> + <entry><filename>dns</filename></entry> + <entry>Программное обеспечение для работы с DNS.</entry> + <entry/> + </row> + + <row> + <entry><filename>docs*</filename></entry> + <entry>Мета-порты для документации &os;.</entry> + <entry/> + </row> + + <row> + <entry><filename>editors</filename></entry> + <entry>Редакторы общего назначения.</entry> + <entry>Специализированные редакторы относят к разделу для + соответствующих инструментов (например, редактор + математических формул попадает в + категорию <filename>math</filename>).</entry> + </row> + + <row> + <entry><filename>elisp*</filename></entry> + <entry>Порты для Emacs lisp.</entry> + <entry/> + </row> + + <row> + <entry><filename>emulators</filename></entry> + <entry>Эмуляторы других операционных систем.</entry> + <entry>Эмуляторы терминалов сюда <emphasis>не</emphasis> + относятся—те, которые разработаны для X, должны быть в + категории <filename>x11</filename>, а текстовые в + <filename>comms</filename> или <filename>misc</filename>, в + зависимости от конкретного их предназначения.</entry> + </row> + + <row> + <entry><filename>finance</filename></entry> + <entry>Приложения для работы с деньгами, финансами и всем, что + с этим связано.</entry> + <entry/> + </row> + + <row> + <entry><filename>french</filename></entry> + <entry>Поддержка французского языка.</entry> + <entry/> + </row> + + <row> + <entry><filename>ftp</filename></entry> + <entry>Клиенты и серверы FTP.</entry> + <entry>Если ваш порт понимает как FTP, + так и HTTP, поместите его в категорию + <filename>ftp</filename> и укажите вторичную категорию + <filename>www</filename>.</entry> + </row> + + <row> + <entry><filename>games</filename></entry> + <entry>Игры.</entry> + <entry/> + </row> + + <row> + <entry><filename>geography*</filename></entry> + <entry>Программное обеспечение, связанное с географией.</entry> + <entry/> + </row> + + <row> + <entry><filename>german</filename></entry> + <entry>Поддержка немецкого языка.</entry> + <entry/> + </row> + + <row> + <entry><filename>gnome*</filename></entry> + <entry>Порты Проекта <link xlink:href="http://www.gnome.org">GNOME</link>.</entry> + <entry/> + </row> + + <row> + <entry><filename>gnustep*</filename></entry> + <entry>Программное обеспечение для окружения рабочего + стола GNUstep.</entry> + <entry/> + </row> + + <row> + <entry><filename>graphics</filename></entry> + <entry>Графические утилиты.</entry> + <entry/> + </row> + + <row> + <entry><filename>hamradio*</filename></entry> + <entry>Программное обеспечение для любительского радио</entry> + <entry/> + </row> + + <row> + <entry><filename>haskell*</filename></entry> + <entry>Программное обеспечение, связанное с языком + Haskell.</entry> + <entry/> + </row> + + <row> + <entry><filename>hebrew</filename></entry> + <entry>Поддержка иврита.</entry> + <entry/> + </row> + + <row> + <entry><filename>hungarian</filename></entry> + <entry>Поддержка венгерского языка.</entry> + <entry/> + </row> + + <row> + <entry><filename>ipv6*</filename></entry> + <entry>Программное обеспечение, связанное с IPv6.</entry> + <entry/> + </row> + + <row> + <entry><filename>irc</filename></entry> + <entry>Утилиты для работы с Internet Relay Chat.</entry> + <entry/> + </row> + + <row> + <entry><filename>japanese</filename></entry> + <entry>Поддержка японского языка.</entry> + <entry/> + </row> + + <row> + <entry><filename>java</filename></entry> + <entry>Программное обеспечение, связанное с языком + Java™.</entry> + <entry>Категория <filename>java</filename> ни в коем случае + не должна быть единственной для порта. Оставьте для портов, + непосредственно имеющих отношение к языку Java, портерам + также рекомендуется не использовать + <filename>java</filename> как основную категорию + порта.</entry> + </row> + + <row> + <entry><filename>kde*</filename></entry> + <entry>Порты проекта + <link xlink:href="http://www.kde.org">KDE</link>.</entry> + <entry/> + </row> + + <row> + <entry><filename>kld*</filename></entry> + <entry>Загружаемые модули ядра.</entry> + <entry/> + </row> + + <row> + <entry><filename>korean</filename></entry> + <entry>Поддержка корейского языка.</entry> + <entry/> + </row> + + <row> + <entry><filename>lang</filename></entry> + <entry>Языки программирования.</entry> + <entry/> + </row> + + <row> + <entry><filename>linux*</filename></entry> + <entry>Linux приложения и утилиты.</entry> + <entry/> + </row> + + <row> + <entry><filename>lisp*</filename></entry> + <entry>Программное обеспечение, связанное с языком + Lisp.</entry> + <entry/> + </row> + + <row> + <entry><filename>mail</filename></entry> + <entry>Программы для работы с электронной почтой.</entry> + <entry/> + </row> + + <row> + <entry><filename>math</filename></entry> + <entry>Программное обеспечение для численных вычислений и + другие утилиты, связанные с математикой.</entry> + <entry/> + </row> + + <row> + <entry><filename>mbone*</filename></entry> + <entry>Приложения для MBone.</entry> + <entry/> + </row> + + <row> + <entry><filename>misc</filename></entry> + <entry>Различные утилиты</entry> + <entry>В основном то, что не попадает в + другие категории. Если это возможно, попробуйте найти + более подходящую, чем <literal>misc</literal>, категорию для + вашего порта, так как здесь порты теряются.</entry> + </row> + + <row> + <entry><filename>multimedia</filename></entry> + <entry>Программное обеспечение для работы с + мультимедиа.</entry> + <entry/> + </row> + + <row> + <entry><filename>net</filename></entry> + <entry>Различное сетевое программное обеспечение.</entry> + <entry/> + </row> + + <row> + <entry><filename>net-im</filename></entry> + <entry>Программы мгновенного обмена сообщениями.</entry> + <entry/> + </row> + + <row> + <entry><filename>net-mgmt</filename></entry> + <entry>Программное обеспечение для сетевого управления.</entry> + <entry/> + </row> + + <row> + <entry><filename>net-p2p</filename></entry> + <entry>Приложения для пиринговых сетей.</entry> + <entry/> + </row> + + <row> + <entry><filename>news</filename></entry> + <entry>Программное обеспечение для работы с конференциями + USENET.</entry> + <entry/> + </row> + + <row> + <entry><filename>palm</filename></entry> + <entry>Программная поддержка <link xlink:href="http://www.palm.com/">Palm™</link>.</entry> + <entry/> + </row> + + <row> + <entry><filename>parallel*</filename></entry> + <entry>Приложения, связанные с параллельными + вычислениями.</entry> + <entry/> + </row> + + <row> + <entry><filename>pear*</filename></entry> + <entry>Порты, относящиеся к технологии Pear PHP.</entry> + <entry/> + </row> + + <row> + <entry><filename>perl5*</filename></entry> + <entry>Порты, которым для работы требуется + <application>Perl</application> версии 5.</entry> + <entry/> + </row> + + <row> + <entry><filename>plan9*</filename></entry> + <entry>Различные программы из <link xlink:href="http://www.cs.bell-labs.com/plan9dist/"> + Plan9</link>.</entry> + <entry/> + </row> + + <row> + <entry><filename>polish</filename></entry> + <entry>Поддержка польского языка.</entry> + <entry/> + </row> + + <row> + <entry><filename>ports-mgmt</filename></entry> + <entry>Порты для управления, установки и разработки + портов и пакетов &os;.</entry> + <entry/> + </row> + + <row> + <entry><filename>portuguese</filename></entry> + <entry>Поддержка португальского языка.</entry> + <entry/> + </row> + + <row> + <entry><filename>print</filename></entry> + <entry>Программное обеспечение для печати.</entry> + <entry>Инструменты для вёрстки (просмотрщики и тому подобное) + тоже относятся сюда.</entry> + </row> + + <row> + <entry><filename>python*</filename></entry> + <entry>Программное обеспечение, связанное с языком <link xlink:href="http://www.python.org/">Python</link>.</entry> + <entry/> + </row> + + <row> + <entry><filename>ruby*</filename></entry> + <entry>Программное обеспечение, связанное с языком <link xlink:href="http://www.ruby-lang.org/">Ruby</link>.</entry> + <entry/> + </row> + + <row> + <entry><filename>rubygems*</filename></entry> + <entry>Порты для пакетов <link xlink:href="http://www.rubygems.org/">RubyGems</link>.</entry> + <entry/> + </row> + + <row> + <entry><filename>russian</filename></entry> + <entry>Поддержка русского языка.</entry> + <entry/> + </row> + + <row> + <entry><filename>scheme*</filename></entry> + <entry>Программное обеспечение, связанное с языком + Scheme.</entry> + <entry/> + </row> + + <row> + <entry><filename>science</filename></entry> + <entry>Научные программы, которые не подпадают под другие + категории, скажем, <filename>astro</filename>, + <filename>biology</filename> или + <filename>math</filename>.</entry> + <entry/> + </row> + + <row> + <entry><filename>security</filename></entry> + <entry>Программы, обеспечивающие безопасность системы.</entry> + <entry/> + </row> + + <row> + <entry><filename>shells</filename></entry> + <entry>Различные командные процессоры.</entry> + <entry/> + </row> + + <row> + <entry><filename>sysutils</filename></entry> + <entry>Системные утилиты.</entry> + <entry/> + </row> + + <row> + <entry><filename>spanish*</filename></entry> + <entry>Поддержка испанского языка.</entry> + <entry/> + </row> + + <row> + <entry><filename>tcl*</filename></entry> + <entry>Порты, для работы которых нужен Tcl.</entry> + <entry/> + </row> + + <row> + <entry><filename>textproc</filename></entry> + <entry>Утилиты для обработки текстов.</entry> + <entry>Инструменты для вёрстки помещаются в категорию + <filename>print</filename>, а не сюда.</entry> + </row> + + <row> + <entry><filename>tk*</filename></entry> + <entry>Порты, для работы которых нужен Tk.</entry> + <entry/> + </row> + + <row> + <entry><filename>ukrainian</filename></entry> + <entry>Поддержка украинского языка.</entry> + <entry/> + </row> + + <row> + <entry><filename>vietnamese</filename></entry> + <entry>Поддержка вьетнамского языка.</entry> + <entry/> + </row> + + <row> + <entry><filename>windowmaker*</filename></entry> + <entry>Порты, поддерживающие менеджер окон WindowMaker.</entry> + <entry/> + </row> + + <row> + <entry><filename>www</filename></entry> + <entry>Программное обеспечение, связанное с World Wide + Web.</entry> + <entry>Поддержка языка HTML относится сюда же.</entry> + </row> + + <row> + <entry><filename>x11</filename></entry> + <entry>X Window System и иже с ними.</entry> + <entry>Эта категория + предназначена только для программного обеспечения, которое + поддерживает саму оконную систему. Не помещайте сюда + обычные приложения для X: большинство из них должны быть + перенесены в другие категории <filename>x11-*</filename> + (смотрите ниже).</entry> + </row> + + <row> + <entry><filename>x11-clocks</filename></entry> + <entry>Часы для X11.</entry> + <entry/> + </row> + + <row> + <entry><filename>x11-drivers</filename></entry> + <entry>Драйверы X11.</entry> + <entry/> + </row> + + <row> + <entry><filename>x11-fm</filename></entry> + <entry>Менеджеры файлов для X11.</entry> + <entry/> + </row> + + <row> + <entry><filename>x11-fonts</filename></entry> + <entry>Шрифты для X11 и утилиты для работы с ними.</entry> + <entry/> + </row> + + <row> + <entry><filename>x11-servers</filename></entry> + <entry>Серверы для X11.</entry> + <entry/> + </row> + + <row> + <entry><filename>x11-themes</filename></entry> + <entry>Темы для X11.</entry> + <entry/> + </row> + + <row> + <entry><filename>x11-toolkits</filename></entry> + <entry>Пакеты разработчика для X11.</entry> + <entry/> + </row> + + <row> + <entry><filename>x11-wm</filename></entry> + <entry>Оконные менеджеры для X11.</entry> + <entry/> + </row> + + <row> + <entry><filename>xfce*</filename></entry> + <entry>Порты, связанные с окружением рабочего стола + <link xlink:href="http://www.xfce.org/">Xfce</link>.</entry> + <entry/> + </row> + + <row> + <entry><filename>zope*</filename></entry> + <entry>Поддержка <link xlink:href="http://www.zope.org/">Zope</link>.</entry> + <entry/> + </row> + </tbody> + </tgroup> + </informaltable> + </sect2> + + <sect2 xml:id="choosing-categories"> + <title>Выбор правильной категории</title> + + <para>Так как многие категории перекрываются, вам часто необходимо + будет выбирать, какая их них должна быть основной для вашего порта. + Есть несколько правил, по которым можно решить этот вопрос. Вот + список приоритетов, в уменьшающейся степени предпочтения:</para> + + <itemizedlist> + <listitem> + <para>Первая категория должна быть физической категорий (смотрите + <link linkend="porting-categories">выше</link>). Это + необходимо для создания пакетов. После этого виртуальные + и физические категории могут смешиваться.</para> + </listitem> + + <listitem> + <para>Сначала всегда идут категории, специфичные для языков. + Например, если ваш порт устанавливает японские шрифты для X11, + то строчка <varname>CATEGORIES</varname> должна иметь вид + <filename>japanese x11-fonts</filename>.</para> + </listitem> + + <listitem> + <para>Более конкретные категории идут первыми перед более + общими. В частности, редактор HTML должен быть описан как + <filename>www editors</filename>, а не наоборот. Кроме того, вы + не должны указывать категорию <filename>net</filename>, если порт + относится к одной из категорий <filename>irc</filename>, + <filename>mail</filename>, + <filename>news</filename>, <filename>security</filename> или + <filename>www</filename>, так как <filename>net</filename> + включается автоматически.</para> + </listitem> + + <listitem> + <para><filename>x11</filename> используется как вторичная категория + только в случае, если в качестве основной категории указан + естественный язык. В частности, вам не нужно указывать + <filename>x11</filename> в качестве категории для + приложений X.</para> + </listitem> + + <listitem> + <para>Режимы для редактора <application>Emacs</application> должны + помещаться в ту же категорию, что и приложение, которое + поддерживается этим режимом, а не в <filename>editors</filename>. + Например, режим <application>Emacs</application> для + редактирования исходного кода некоторого языка программирования + должен быть помещен в категорию <filename>lang</filename>.</para> + </listitem> + + <listitem> + <para>Порты, устанавливающие загружаемые модули ядра, должны + содержать виртуальную категорию <filename>kld</filename> в + строке <varname>CATEGORIES</varname>. Это одно из действий, + выполняемых автоматически с добавлением + <literal>kmod</literal> в строке <varname>USES</varname>. + </para> + </listitem> + + <listitem> + <para><filename>misc</filename> + не должна указываться вместе с любой другой невиртуальной + категорией. Если вы указываете <literal>misc</literal> + вместе с чем-то ещё в строке <varname>CATEGORIES</varname>, + это значит, что вы можете спокойно удалить + <literal>misc</literal> и просто поместить порт в этот + другой подкаталог!</para> + </listitem> + + <listitem> + <para>Если ваш порт решительным образом не подпадает ни под какую + категорию, поместите его в <filename>misc</filename>.</para> + </listitem> + </itemizedlist> + + <para>Если вы не уверены в правильности выбора категории, пожалуйста, + отметьте это в вашем сообщении через &man.send-pr.1;, чтобы мы + могли обсудить это до того, как включить порт в Коллекцию. Если вы + являетесь коммиттером, пошлите замечание на адрес &a.ports;, чтобы мы + могли обсудить это. Зачастую новые порты помещаются не в ту + категорию только для того, чтобы их оттуда сразу же удалили. + Это приводит к излишнему и ненужному росту основного хранилища + исходных текстов.</para> + </sect2> + + <sect2 xml:id="proposing-categories"> + <title>Предложение новой категории</title> + + <para>Поскольку со временем Коллекция Портов увеличилась, то в связи + с этим были добавлены различные новые категории. Новые категории + могут быть или <emphasis>виртуальными</emphasis> категориями— + которые не имеют соответствующего подкаталога в дереве портов— + или <emphasis>физическими</emphasis> категориями—у которых + он есть. Следующий текст содержит обсуждение вопросов, возникающих + при создании новой физической категории, чтобы вы могли понимать + их, когда предложите новую категорию.</para> + + <para>В соответствие с существующей практикой мы избегаем создания + новой физической категории, пока достаточно большое число портов + логически ей не принадлежит или же порты, которые могли бы ей + принадлежать, не являются логически обособленной группой, + представляющей для всех ограниченный интерес (в частности, + категории, относящиеся к естественным языкам); предпочтительно + выполнение обоих условий.</para> + + <para>Основной причиной для этого является то, что такое изменение + создает <link xlink:href="&url.articles.committers-guide;/#ports">изрядное + количество работы</link> и для коммиттеров, и для всех тех + пользователей, которые отслеживают изменения в Коллекции Портов. + В дополнение, предложенная категория создает естественное + разногласие. (Пожалуй, потому что не существует четкого соглашения, + является ли категория <quote>слишком большой</quote>, или должны + ли категории предоставлять себя для просмотра (и, таким образом, + какое количество категорий было бы идеальным значением), и так + далее.)</para> + + <para>Процедура:</para> + + <procedure> + <step> + <para>Предложите новую категорию на &a.ports;. Вам следует + включить для новой категории детальное обоснование, в том числе + почему вы считаете, что существующие категории не являются + достаточными, и список существующих портов, предложенных для + перемещения. (Если есть новые порты, ожидающие в + <application>GNATS</application> и попадающие в эту категорию, + то укажите их тоже.) Если вы являетесь сопровождающим и/или + отправителем, то укажите это соответственно, так как это может + помочь вам в вашем деле.</para> + </step> + + <step> + <para>Принимайте участие в обсуждении.</para> + </step> + + <step> + <para>Если кажется, что для вашей идеи появилась поддержка, + отправьте PR, который будет включать обоснование и список + существующих портов, которые надо переместить. В идеале + этот PR должен также включать патчи для следующего:</para> + + <itemizedlist> + <listitem> + <para><filename>Makefile</filename>'ы для новых портов в + результате репозиторного копирования</para> + </listitem> + + <listitem> + <para><filename>Makefile</filename> для категорий старых + портов</para> + </listitem> + + <listitem> + <para><filename>Makefile</filename>'ы для портов, зависящих + от старых портов</para> + </listitem> + + <listitem> + <para>(в дополнение, вы можете включить другие файлы, + требующие изменений, согласно процедуре из Руководства + Коммиттера.)</para> + </listitem> + </itemizedlist> + </step> + + <step> + <para>Поскольку это затрагивает инфраструктуру портов и + охватывает не только выполнение репозиторного копирования, но + также, возможно, и выполнение регрессивных тестов на кластере + построения, то PR должна назначать себе &a.portmgr;.</para> + </step> + + <step> + <para>Если этот PR одобрен, то коммиттеру нужно продолжить + остальную часть процедуры, которая <link xlink:href="&url.articles.committers-guide;/article.html#PORTS"> + изложена в Руководстве Коммиттера</link>.</para> + </step> + </procedure> + + <para>Предложение новой виртуальной категории должно быть схожим + с вышеизложенным, но при этом затрагивать намного меньше, + поскольку ни один из портов не будет перемещен в действительности. + В этом случае единственными патчами, включенными в PR, будут + те, что добавляют новую категорию в <varname>CATEGORIES</varname> + каждого из затрагиваемых портов.</para> + </sect2> + + <sect2 xml:id="proposing-reorg"> + <title>Предложение реорганизации всех категорий</title> + + <para>Время от времени кто-нибудь предлагает произвести реорганизацию + категорий либо до двухуровневой, либо другого типа на основе + ключевых слов. На данный момент из этих предложений ничего не + получилось, потому что, хотя они просты в реализации, но + предполагаемая переделка всей коллекции портов по меньшей мере + приводит в уныние. Пожалуйста, прочтите историю этих предложений + в архивах рассылок перед тем, как присылать свои соображения; + более того, вы должны быть готовы представить работающий + прототип.</para> + </sect2> + </sect1> + + <sect1 xml:id="makefile-distfiles"> + <title>Дистрибутивные файлы</title> + + <para>Во второй части <filename>Makefile</filename> задаётся, какие + файлы и откуда должны быть сгружены для того, чтобы построить + порт.</para> + + <sect2> + <title><varname>DISTVERSION/DISTNAME</varname></title> + + <para>В переменной <varname>DISTNAME</varname> указывается имя порта + так, как назвали его создатели программного обеспечения. Значение + <varname>DISTNAME</varname> по умолчанию совпадает с + <literal>${PORTNAME}-${PORTVERSION}</literal>, так что + переопределяете её значение только в случае необходимости. + <varname>DISTNAME</varname> используется только в двух местах. + Во-первых, список дистрибутивных файлов + (<varname>DISTFILES</varname>) по умолчанию состоит из + <varname>${DISTNAME}</varname><varname>${EXTRACT_SUFX}</varname>. И + во-вторых, предполагается, что дистрибутивный файл будет распакован в + подкаталог с именем <varname>WRKSRC</varname>, значение которого по + умолчанию есть не что иное, как + <filename>work/${DISTNAME}</filename>.</para> + + <para>Названия некоторых дистрибутивов, которые не укладываются в + <literal>${PORTNAME}-${PORTVERSION}</literal>-схему, могут быть + автоматически обработаны посредством установки переменной + <varname>DISTVERSION</varname>. <varname>PORTVERSION</varname> и + <varname>DISTNAME</varname> будут унаследованы автоматически, но + конечно же могут быть переопределены. Следующая таблица + демонстрирует некоторые примеры:</para> + + <informaltable frame="none" pgwide="0"> + <tgroup cols="2"> + <thead> + <row> + <entry><varname>DISTVERSION</varname></entry> + <entry><varname>PORTVERSION</varname></entry> + </row> + </thead> + + <tbody> + <row> + <entry>0.7.1d</entry> + <entry>0.7.1.d</entry> + </row> + + <row> + <entry>10Alpha3</entry> + <entry>10.a3</entry> + </row> + + <row> + <entry>3Beta7-pre2</entry> + <entry>3.b7.p2</entry> + </row> + + <row> + <entry>8:f_17</entry> + <entry>8f.17</entry> + </row> + </tbody> + </tgroup> + </informaltable> + + <note> + <para>Значения переменных <varname>PKGNAMEPREFIX</varname> + и <varname>PKGNAMESUFFIX</varname> не влияют на значение + <varname>DISTNAME</varname>. Заметьте также, что если значение + <varname>WRKSRC</varname> равно + <filename>work/${PORTNAME}-${PORTVERSION}</filename>, + и в случае, когда оригинальный архив называется по имени, отличном + от <varname>${PORTNAME}-${PORTVERSION}${EXTRACT_SUFX}</varname>, + скорее всего, вы должны оставить <varname>DISTNAME</varname> + как есть— лучше переопределить <varname>DISTFILES</varname>, + чем задавать значения как + <varname>DISTNAME</varname>, так и <varname>WRKSRC</varname> + (и, возможно, ещё и <varname>EXTRACT_SUFX</varname>).</para> + </note> + </sect2> + + <sect2> + <title><varname>MASTER_SITES</varname></title> + + <para>Содержит часть с каталогом FTP/HTTP-URL, которая указывает на + оригинальный архив на сервере <varname>MASTER_SITES</varname>. Не + забудьте лидирующий слэш (<filename>/</filename>)!</para> + + <para>Макрос команды <command>make</command> будет пытаться + воспользоваться этой переменной для получения дистрибутивного файла + с помощью программы <varname>FETCH</varname>, если он не будет найден + в системе.</para> + + <para>Рекомендуется помещать в список много сайтов, предпочтительно с + разных континентов. Это поможет при наличии проблем с мировой сетью. + Мы даже планируем добавить поддержку автоматического определения + ближайшего сайта и сгрузки файлов оттуда; наличие нескольких сайтов + будет способствовать этому начинанию.</para> + + <para>Если оригинальный архив находится на одном из таких популярных + серверов, как SourceForge, GNU или Perl CPAN, то указывайте эти + сайты в простой форме при помощи + <varname>MASTER_SITE_<replaceable>*</replaceable></varname> + (к примеру, <varname>MASTER_SITE_SOURCEFORGE</varname>, + <varname>MASTER_SITE_GNU</varname> или + <varname>MASTER_SITE_PERL_CPAN</varname>. Просто укажите в переменной + <varname>MASTER_SITES</varname> одно из этих значений, а в + переменной <varname>MASTER_SITE_SUBDIR</varname> задайте путь к + архиву. Вот пример:</para> + + <programlisting>MASTER_SITES= ${MASTER_SITE_GNU} +MASTER_SITE_SUBDIR= make</programlisting> + + <para>Или можно использовать сокращенный формат:</para> + + <programlisting>MASTER_SITES= GNU/make</programlisting> + + <para>Эти переменные определены в файле + <filename>/usr/ports/Mk/bsd.sites.mk</filename>. Всё время + добавляются новые записи, так что обращайтесь к последней версии + этого файла перед тем, как послать нам свой порт.</para> + + <para>Для популярных сайтов существует несколько + <emphasis>магических</emphasis> макросов с заранее известной + структурой каталогов. Используйте для них сокращения, и система + попытается угадать для вас правильный подкаталог.</para> + + <programlisting>MASTER_SITES= SF</programlisting> + + <para>Если попытка угадать не удалась, то это может быть переписано + следующим образом.</para> + + <programlisting>MASTER_SITES= SF/stardict/WyabdcRealPeopleTTS/${PORTVERSION}</programlisting> + + <para>Что также можно записать в таком виде:</para> + + <programlisting>MASTER_SITES= SF +MASTER_SITE_SUBDIR= stardict/WyabdcRealPeopleTTS/${PORTVERSION}</programlisting> + + <table frame="none"> + <title>Популярные магические макросы для + <varname>MASTER_SITES</varname></title> + + <tgroup cols="2"> + <thead> + <row> + <entry>Macro</entry> + + <entry>Assumed subdirectory</entry> + </row> + </thead> + + <tbody> + <row> + <entry><varname>BERLIOS</varname></entry> + + <entry><varname>/${PORTNAME:L}</varname></entry> + </row> + + <row> + <entry><varname>CHEESESHOP</varname></entry> + + <entry><varname>/packages/source/source/${DISTNAME:C/(.).*/\1/}/${DISTNAME:C/(.*)-[0-9].*/\1/}</varname></entry> + </row> + + <row> + <entry><varname>DEBIAN</varname></entry> + + <entry><varname>/debian/pool/main/${PORTNAME:C/^((lib)?.).*$/\1/}/${PORTNAME}</varname></entry> + </row> + + <row> + <entry><varname>GCC</varname></entry> + + <entry><varname>/pub/gcc/releases/${DISTNAME}</varname></entry> + </row> + + <row> + <entry><varname>GNOME</varname></entry> + + <entry><varname>/pub/GNOME/sources/${PORTNAME}/${PORTVERSION:C/^([0-9]+\.[0-9]+).*/\1/}</varname></entry> + </row> + + <row> + <entry><varname>GNU</varname></entry> + + <entry><varname>/gnu/${PORTNAME}</varname></entry> + </row> + + <row> + <entry><varname>MOZDEV</varname></entry> + + <entry><varname>/pub/mozdev/${PORTNAME:L}</varname></entry> + </row> + + <row> + <entry><varname>PERL_CPAN</varname></entry> + + <entry><varname>/pub/CPAN/modules/by-module/${PORTNAME:C/-.*//}</varname></entry> + </row> + + <row> + <entry><varname>PYTHON</varname></entry> + + <entry><varname>/ftp/python/${PYTHON_PORTVERSION:C/rc[0-9]//}</varname></entry> + </row> + + <row> + <entry><varname>RUBYFORGE</varname></entry> + + <entry><varname>/${PORTNAME:L}</varname></entry> + </row> + + <row> + <entry><varname>SAVANNAH</varname></entry> + + <entry><varname>/${PORTNAME:L}</varname></entry> + </row> + + <row> + <entry><varname>SF</varname></entry> + + <entry><varname>/project/${PORTNAME:L}/${PORTNAME:L}/${PORTVERSION}</varname></entry> + </row> + </tbody> + </tgroup> + </table> + </sect2> + + <sect2> + <title><varname>EXTRACT_SUFX</varname></title> + + <para>Если у вас имеется один дистрибутивный файл, и в его имени + используется странное окончание для указания типа сжатия, задайте + переменную <varname>EXTRACT_SUFX</varname>.</para> + + <para>К примеру, если дистрибутивный файл носит имя + <filename>foo.tgz</filename>, а не более привычное + <filename>foo.tar.gz</filename>, вы должны написать:</para> + + <programlisting>DISTNAME= foo +EXTRACT_SUFX= .tgz</programlisting> + + <para>Переменные <varname>USE_BZIP2</varname>, + <varname>USE_XZ</varname> и + <varname>USE_ZIP</varname> при необходимости автоматически + устанавливают значение <varname>EXTRACT_SUFX</varname> в + <literal>.tar.bz2</literal>, <literal>.tar.xz</literal> или + <literal>.zip</literal>. Если ни одна из этих + переменных не задана, то значение <varname>EXTRACT_SUFX</varname> + по умолчанию устанавливается в <literal>.tar.gz</literal>.</para> + + <note> + <para>Вам не нужно задавать значения <varname>EXTRACT_SUFX</varname> + и <varname>DISTFILES</varname> одновременно.</para> + </note> + </sect2> + + <sect2> + <title><varname>DISTFILES</varname></title> + + <para>Иногда имена сгружаемых файлов не соответствуют имени порта. К + примеру, файл может называться <filename>source.tar.gz</filename> или + подобным образом. В других случаях исходный код приложения может + располагаться в нескольких отличающихся архивах, и все они должны + быть сгружены.</para> + + <para>Если это ваш случай, то задайте в переменной + <varname>DISTFILES</varname> список разделённых пробелами имён + файлов, которые нужно сгрузить.</para> + + <programlisting>DISTFILES= source1.tar.gz source2.tar.gz</programlisting> + + <para>Если переменная <varname>DISTFILES</varname> не задана явно, то + её значением по умолчанию будет + <literal>${DISTNAME}${EXTRACT_SUFX}</literal>.</para> + </sect2> + + <sect2> + <title><varname>EXTRACT_ONLY</varname></title> + + <para>Если только некоторые из <varname>DISTFILES</varname> должны быть + распакованы—к примеру, часть из них является исходным кодом, а + другие представляют собой неупакованную + документацию—перечислите имена файлов, которые должны быть + распакованы, в <varname>EXTRACT_ONLY</varname>.</para> + + <programlisting>DISTFILES= source.tar.gz manual.html +EXTRACT_ONLY= source.tar.gz</programlisting> + + <para>Если <emphasis>ни один</emphasis> из <varname>DISTFILES</varname> + не должен распаковываться, то установите пустое значение + переменной <varname>EXTRACT_ONLY</varname>.</para> + + <programlisting>EXTRACT_ONLY=</programlisting> + </sect2> + + <sect2 xml:id="porting-patchfiles"> + <title><varname>PATCHFILES</varname></title> + + <para>Если вашему порту требуются некоторых дополнительные патчи, + которые доступны по FTP или HTTP, задайте имена этих файлов в + переменной <varname>PATCHFILES</varname>, а в переменной + <varname>PATCH_SITES</varname> укажите URL того каталога, в котором + они содержатся (формат такой же, как + для <varname>MASTER_SITES</varname>).</para> + + <para>Если патч не относится к самому верху дерева исходных текстов + (то есть <varname>WRKSRC</varname>), потому что он содержит некоторые + дополнительные пути, установите соответственно значение переменной + <varname>PATCH_DIST_STRIP</varname>. В частности, если все имена + путей в патче имеют дополнительный путь + <literal>foozolix-1.0/</literal> перед именем файла, то задайте + <literal>PATCH_DIST_STRIP=-p1</literal>.</para> + + <para>Не волнуйтесь, если патчи упакованы; они будут распакованы + автоматически, если имена файлов оканчиваются на + <filename>.gz</filename> или <filename>.Z</filename>.</para> + + <para>Если патч распространяется вместе с какими-то другими файлами, + такими, как документация, в виде tar-архива <command>gzip</command>, + вы не можете просто + использовать <varname>PATCHFILES</varname>. Если это ваш случай, + добавьте имя и местоположение архива с патчем к + <varname>DISTFILES</varname> и <varname>MASTER_SITES</varname>. + Затем воспользуйтесь переменной <varname>EXTRA_PATCHES</varname> для + указания этих файлов, и <filename>bsd.port.mk</filename> автоматически + применит эти патчи. В частности, <emphasis>не копируйте</emphasis> + файлы с патчами в каталог <varname>PATCHDIR</varname>—этот + каталог может быть недоступным для записи.</para> + + <note> + <para>Архив будет распакован вне исходного кода, как + обычно, и к тому же его не нужно явно распаковывать, если + это обычный архив <command>gzip</command> или + <command>compress</command>. Если вы сделаете последнее, + приложите дополнительные усилия для того, чтобы не перезаписать + что-либо, уже существующее в этом каталоге. Также не забудьте + добавить команду для удаления скопированного патча в цели + <buildtarget>pre-clean</buildtarget>.</para> + </note> + </sect2> + + <sect2 xml:id="porting-master-sites-n"> + <title>Несколько дистрибутивных файлов или патчей с различных серверов + и подкаталогов (<literal>MASTER_SITES:n</literal>)</title> + + <para>(Этот раздел можно считать немного <quote>повышенной + трудности</quote>; те, кто впервые знакомятся с этим текстом, могут + пропустить этот раздел).</para> + + <para>В этом разделе находится информация о механизме сгрузки, + известном как <literal>MASTER_SITES:n</literal> и + <literal>MASTER_SITES_NN</literal>. Далее мы будем называть этот + механизм <literal>MASTER_SITES:n</literal>.</para> + + <para>Сначала немного общей информации. В OpenBSD имеется полезная + возможность, используемая в переменных <varname>DISTFILES</varname> и + <varname>PATCHFILES</varname>, которая позволяет закреплять после + имен файлов и патчей идентификаторы типа <literal>:n</literal>. Здесь + <literal>n</literal> может быть из диапазона <literal>[0-9]</literal> + и обозначать закреплённую группу. К примеру:</para> + + <programlisting>DISTFILES= alpha:0 beta:1</programlisting> + + <para>В OpenBSD дистрибутивный файл <filename>alpha</filename> будет + связан с переменной <varname>MASTER_SITES0</varname>, но не с нашей + общей переменной <varname>MASTER_SITES</varname>, а файл + <filename>beta</filename> с переменной + <varname>MASTER_SITES1</varname>.</para> + + <para>Этот очень интересная возможность, которая может уменьшить этот + бесконечный поиск работающего сайта для сгрузки.</para> + + <para>Просто представьте себе 2 файла в <varname>DISTFILES</varname> и + 20 сайтов в <varname>MASTER_SITES</varname>; сайты очень медленные, + причём <filename>beta</filename> находится на всех сайтах из + <varname>MASTER_SITES</varname>, а <filename>alpha</filename> + может быть найден только на 20-м сайте. Будет неправильно проверять + их все, если создатель знает об этом, не правда ли? Неподходящее + начало для таких прекрасных выходных!</para> + + <para>Теперь, когда вы получили общее представление, просто представьте + ещё большее количество <varname>DISTFILES</varname> и + <varname>MASTER_SITES</varname>. Конечно, наш <quote>магистр + доступности дистрибутивов</quote> представляет масштабы нагрузки + на сеть, которую это даёт.</para> + + <para>В последующих разделах информация будет даваться вместе с + реализацией этой идеи во &os;. Мы несколько улучшили концепцию + OpenBSD.</para> + + <sect3> + <title>Упрощённая информация</title> + + <para>В этом разделе рассказывается, как быстро подготовить точную + сгрузку нескольких дистрибутивных файлов и патчей с разных сайтов + и каталогов. Мы описываем здесь случай упрощённого использования + <literal>MASTER_SITES:n</literal>. Для большинства сценариев этого + будет достаточно. Однако, если вам нужна дополнительная + информация, обратитесь к следующему разделу.</para> + + <para>Некоторые приложения состоят из многих дистрибутивных + файлов, которые должны быть сгружены с нескольких различных сайтов. + К примеру, <application>Ghostscript</application> состоит из + основной программы и большого числа файлов драйверов, которые + используются в зависимости от принтера пользователя. Некоторые из + этих файлов драйверов поставляются с основной программой, но при + этом многие другие должны быть сгружены с множества различных + сайтов.</para> + + <para>Чтобы это поддерживать, за каждой записью в + <varname>DISTFILES</varname> может следовать символ двоеточия и + <quote>имя метки</quote>. За каждым сайтом, перечисленным в + <varname>MASTER_SITES</varname>, тоже следует двоеточие и метка, + которая указывает, какие файлы дистрибутива должны быть сгружены + с этого сайта.</para> + + <para>Например, рассмотрим приложение, исходный код которого разделён + на две части, <filename>source1.tar.gz</filename> и + <filename>source2.tar.gz</filename>, которые должны быть сгружены с + двух различных источников. Файл <filename>Makefile</filename> + порта будет содержать строчки типа <xref linkend="ports-master-sites-n-example-simple-use-one-file-per-site"/>.</para> + + <example xml:id="ports-master-sites-n-example-simple-use-one-file-per-site"> + + <title>Упрощённое использование <literal>MASTER_SITES:n</literal> + с 1 файлом на каждом сайте</title> + + <programlisting>MASTER_SITES= ftp://ftp.example1.com/:source1 \ + ftp://ftp.example2.com/:source2 +DISTFILES= source1.tar.gz:source1 \ + source2.tar.gz:source2</programlisting> + </example> + + <para>Несколько дистрибутивных файлов могут иметь одну и ту же метку. + Продолжая предыдущий пример, положим, что имеется и третий + дистрибутивный файл, <filename>source3.tar.gz</filename>, который + должен быть сгружен с <systemitem>ftp.example2.com</systemitem>. Тогда + файл <filename>Makefile</filename> будет написан как <xref linkend="ports-master-sites-n-example-simple-use-more-than-one-file-per-site"/>.</para> + + <example xml:id="ports-master-sites-n-example-simple-use-more-than-one-file-per-site"> + <title>Упрощённое использование <literal>MASTER_SITES:n</literal> с + более чем 1 файлом на каждом сервере</title> + + <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</programlisting> + </example> + </sect3> + + <sect3> + <title>Подробная информация</title> + + <para>Прекрасно, но пример из предыдущего раздела не показал вам всё, + что вам нужно? В этом разделе мы подробно опишем, как работает + механизм <literal>MASTER_SITES:n</literal> точной сгрузки и как + вы можете изменить ваши порты, чтобы это использовать.</para> + + <orderedlist> + <listitem> + <para>За элементами могут следовать символы + <literal>:n</literal>, где + <replaceable>n</replaceable> это <literal>[^:,]+</literal>, то + есть <replaceable>n</replaceable> может теоретически быть + любой алфавитно-цифровой строкой, но пока мы будем ограничивать + их <literal>[a-zA-Z_][0-9a-zA-Z_]+</literal>.</para> + + <para>Более того, совпадение строк чувствительно к регистру; + другими словами, <literal>n</literal> отличается от + <literal>N</literal>.</para> + + <para>Однако следующие слова не могут использоваться для этих + нужд, так как они имеют особое значение: + <literal>default</literal>, <literal>all</literal> и + <literal>ALL</literal> (они используются для своих нужд в <xref linkend="porting-master-sites-n-what-changes-in-port-targets"/>). + Кроме того, <literal>DEFAULT</literal> является специальным + ключевым словом (посмотрите <xref linkend="porting-master-sites-n-DEFAULT-group"/>).</para> + </listitem> + + <listitem> + <para>Элементы, за которыми следуют <literal>:n</literal>, + принадлежат группе <literal>n</literal>, + <literal>:m</literal> относится к группе <literal>m</literal> и + так далее.</para> + </listitem> + + <listitem xml:id="porting-master-sites-n-DEFAULT-group"> + <para>Элементы без таких суффиксов не относятся ни к какой + группе, то есть они принадлежат к особой группе + <literal>DEFAULT</literal>. Если вы укажете суффиксом любого + элемента <literal>DEFAULT</literal>, вы просто выполните + излишнюю работу, если только вы не хотите отнесения элемента + как к группе <literal>DEFAULT</literal>, так и какой-то другой + в одно и то же время (посмотрите на пункт <xref linkend="porting-master-sites-n-comma-operator"/>).</para> + + <para>Следующие примеры равнозначны, но первый более + предпочтителен:</para> + + <programlisting>MASTER_SITES= alpha</programlisting> + + <programlisting>MASTER_SITES= alpha:DEFAULT</programlisting> + </listitem> + + <listitem> + <para>Группы не являются эксклюзивными, элемент может + принадлежать к нескольким отличающимся группам одновременно, а + группа может либо иметь несколько различных элементов, либо не + иметь их вовсе. Повторяющиеся элементы в одной и той же группе + будут являться просто повторяющимися элементами.</para> + </listitem> + + <listitem xml:id="porting-master-sites-n-comma-operator"> + <para>Если в хотите, чтобы элемент принадлежал к нескольким + группам одновременно, вы можете использовать + запятую (<literal>,</literal>).</para> + + <para>Вместо того, чтобы повторять их несколько раз, каждый раз с + разным постфиксом, мы можем перечислить несколько групп за раз + в одном постфиксе. Например, <literal>:m,n,o</literal> + определяет элемент, принадлежащий группам <literal>m</literal>, + <literal>n</literal> и <literal>o</literal>.</para> + + <para>Все следующие примеры имеют один смысл, но последний + является предпочтительным:</para> + + <programlisting>MASTER_SITES= alpha alpha:SOME_SITE</programlisting> + + <programlisting>MASTER_SITES= alpha:DEFAULT alpha:SOME_SITE</programlisting> + + <programlisting>MASTER_SITES= alpha:SOME_SITE,DEFAULT</programlisting> + + <programlisting>MASTER_SITES= alpha:DEFAULT,SOME_SITE</programlisting> + </listitem> + + <listitem> + <para>Все серверы внутри определённой группы сортируются в + соответствии с <varname>MASTER_SORT_AWK</varname>. Все группы + в <varname>MASTER_SITES</varname> и + <varname>PATCH_SITES</varname> тоже сортируются.</para> + </listitem> + + <listitem xml:id="porting-master-sites-n-group-semantics"> + <para>Семантика групп может использоваться в любой из следующих + переменных <varname>MASTER_SITES</varname>, + <varname>PATCH_SITES</varname>, + <varname>MASTER_SITE_SUBDIR</varname>, + <varname>PATCH_SITE_SUBDIR</varname>, + <varname>DISTFILES</varname> и + <varname>PATCHFILES</varname> в соответствии со следующим + синтаксисом:</para> + + <orderedlist> + <listitem> + <para>Все элементы <varname>MASTER_SITES</varname>, + <varname>PATCH_SITES</varname>, + <varname>MASTER_SITE_SUBDIR</varname> и + <varname>PATCH_SITE_SUBDIR</varname> должны заканчиваться + символом прямого слэша <literal>/</literal>. Если какие-то + элементы принадлежат каким-то группам, постфикс группы + <literal>:n</literal> должен + следовать сразу после завершающего символа + <literal>/</literal>. Механизм + <literal>MASTER_SITES:n</literal> опирается на наличие + завершающего символа <literal>/</literal> во избежание + совпадающих элементов, где <literal>:n</literal> является + корректной частью элемента с вхождениями, где + <literal>:n</literal> обозначает группу + <literal>n</literal>. Для целей совместимости, так как + завершающий символ <literal>/</literal> ранее не + требовался в элементах + <varname>MASTER_SITE_SUBDIR</varname> и + <varname>PATCH_SITE_SUBDIR</varname>, если символ, сразу + предшествующий постфиксу, не является символом + <literal>/</literal>, то <literal>:n</literal> будет + считаться корректной частью элемента, а не постфиксом + группы, даже если за элементом следует + <literal>:n</literal>. Посмотрите <xref linkend="ports-master-sites-n-example-detailed-use-master-site-subdir"/> + и <xref linkend="ports-master-sites-n-example-detailed-use-complete-example-master-sites"/>.</para> + + <example xml:id="ports-master-sites-n-example-detailed-use-master-site-subdir"> + <title>Подробное использование + <literal>MASTER_SITES:n</literal> в + <varname>MASTER_SITE_SUBDIR</varname></title> + + <programlisting>MASTER_SITE_SUBDIR= old:n new/:NEW</programlisting> + + <itemizedlist> + <listitem> + <para>Каталоги внутри группы + <literal>DEFAULT</literal> -> old:n</para> + </listitem> + + <listitem> + <para>Каталоги внутри группы + <literal>NEW</literal> -> new</para> + </listitem> + </itemizedlist> + </example> + + <example xml:id="ports-master-sites-n-example-detailed-use-complete-example-master-sites"> + <title>Подробное использование + <literal>MASTER_SITES:n</literal> с запятыми, + несколькими файлами, несколькими серверами и + несколькими подкаталогами</title> + + <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</programlisting> + + <para>Предыдущий пример приводит к следующей точной + сгрузке. Серверы перечислены в точном порядке их + использования.</para> + + <itemizedlist> + <listitem> + <para><filename>file1</filename> будет сгружаться + с</para> + + <itemizedlist> + <listitem> + <para><varname>MASTER_SITE_OVERRIDE</varname></para> + </listitem> + + <listitem> + <para>http://site1/directory-trial:1/</para> + </listitem> + + <listitem> + <para>http://site1/directory-one/</para> + </listitem> + + <listitem> + <para>http://site1/directory/</para> + </listitem> + + <listitem> + <para>http://site2/</para> + </listitem> + + <listitem> + <para>http://site7/</para> + </listitem> + + <listitem> + <para><varname>MASTER_SITE_BACKUP</varname></para> + </listitem> + </itemizedlist> + </listitem> + + <listitem> + <para><filename>file2</filename> будет сгружаться точно + также, как <filename>file1</filename>, так как они + оба относятся к одной и той же группе</para> + + <itemizedlist> + <listitem> + <para><varname>MASTER_SITE_OVERRIDE</varname></para> + </listitem> + + <listitem> + <para>http://site1/directory-trial:1/</para> + </listitem> + + <listitem> + <para>http://site1/directory-one/</para> + </listitem> + + <listitem> + <para>http://site1/directory/</para> + </listitem> + + <listitem> + <para>http://site2/</para> + </listitem> + + <listitem> + <para>http://site7/</para> + </listitem> + + <listitem> + <para><varname>MASTER_SITE_BACKUP</varname></para> + </listitem> + </itemizedlist> + </listitem> + + <listitem> + <para><filename>file3</filename> будет сгружен с</para> + + <itemizedlist> + <listitem> + <para><varname>MASTER_SITE_OVERRIDE</varname></para> + </listitem> + + <listitem> + <para>http://site3/</para> + </listitem> + + <listitem> + <para><varname>MASTER_SITE_BACKUP</varname></para> + </listitem> + </itemizedlist> + </listitem> + + <listitem> + <para><filename>file4</filename> будет сгружаться + с</para> + + <itemizedlist> + <listitem> + <para><varname>MASTER_SITE_OVERRIDE</varname></para> + </listitem> + + <listitem> + <para>http://site4/</para> + </listitem> + + <listitem> + <para>http://site5/</para> + </listitem> + + <listitem> + <para>http://site6/</para> + </listitem> + + <listitem> + <para>http://site7/</para> + </listitem> + + <listitem> + <para>http://site8/directory-one/</para> + </listitem> + + <listitem> + <para><varname>MASTER_SITE_BACKUP</varname></para> + </listitem> + </itemizedlist> + </listitem> + + <listitem> + <para><filename>file5</filename> будет сгружен с</para> + + <itemizedlist> + <listitem> + <para><varname>MASTER_SITE_OVERRIDE</varname></para> + </listitem> + + <listitem> + <para><varname>MASTER_SITE_BACKUP</varname></para> + </listitem> + </itemizedlist> + </listitem> + + <listitem> + <para><filename>file6</filename> будет сгружаться + с</para> + + <itemizedlist> + <listitem> + <para><varname>MASTER_SITE_OVERRIDE</varname></para> + </listitem> + + <listitem> + <para>http://site8/</para> + </listitem> + + <listitem> + <para><varname>MASTER_SITE_BACKUP</varname></para> + </listitem> + </itemizedlist> + </listitem> + </itemizedlist> + </example> + </listitem> + </orderedlist> + </listitem> + + <listitem> + <para>Как мне сгруппировать одну из специальных переменных из + <filename>bsd.sites.mk</filename>, например, + <varname>MASTER_SITE_SOURCEFORGE</varname>?</para> + + <para>Посмотрите <xref linkend="ports-master-sites-n-example-detailed-use-master-site-sourceforge"/>.</para> + + <example xml:id="ports-master-sites-n-example-detailed-use-master-site-sourceforge"> + <title>Подробное использование + <literal>MASTER_SITES:n</literal> с + <varname>MASTER_SITE_SOURCEFORGE</varname></title> + + <programlisting>MASTER_SITES= http://site1/ ${MASTER_SITE_SOURCEFORGE:S/$/:sourceforge,TEST/} +DISTFILES= something.tar.gz:sourceforge</programlisting> + </example> + + <para><filename>something.tar.gz</filename> будет сгружаться со + всех сайтов из + <varname>MASTER_SITE_SOURCEFORGE</varname>.</para> + </listitem> + + <listitem> + <para>Как мне использовать это с переменными + <varname>PATCH*</varname>?</para> + + <para>Все примеры выполнялись с переменными + <varname>MASTER*</varname>, и они работают точно также и для + <varname>PATCH*</varname>, как это можно видеть в <xref linkend="ports-master-sites-n-example-detailed-use-patch-sites"/>.</para> + + <example xml:id="ports-master-sites-n-example-detailed-use-patch-sites"> + <title>Упрощённое использование + <literal>MASTER_SITES:n</literal> с + <varname>PATCH_SITES</varname>.</title> + + <programlisting>PATCH_SITES= http://site1/ http://site2/:test +PATCHFILES= patch1:test</programlisting> + </example> + </listitem> + </orderedlist> + </sect3> + + <sect3> + <title>Что изменится для портов? А что не изменится?</title> + + <orderedlist numeration="lowerroman"> + <listitem> + <para>Все имеющиеся порты остаются без изменений. Код для + механизма <literal>MASTER_SITES:n</literal> активируется, если + только есть элементы, которые заканчиваются на + <literal>:n</literal>, как и + элементы в соответствии с вышеописанным синтаксисом, особенно + как это показано в пункте <xref linkend="porting-master-sites-n-group-semantics"/>.</para> + </listitem> + + <listitem xml:id="porting-master-sites-n-what-changes-in-port-targets"> + <para>Цели порт остаются теми же самыми: + <buildtarget>checksum</buildtarget>, + <buildtarget>makesum</buildtarget>, + <buildtarget>patch</buildtarget>, + <buildtarget>configure</buildtarget>, + <buildtarget>build</buildtarget> и так далее. С обычными + исключениями для <buildtarget>do-fetch</buildtarget>, + <buildtarget>fetch-list</buildtarget>, + <buildtarget>master-sites</buildtarget> и + <buildtarget>patch-sites</buildtarget>.</para> + + <itemizedlist> + <listitem> + <para><buildtarget>do-fetch</buildtarget>: использует новую + группировку с постфиксами в <varname>DISTFILES</varname> и + <varname>PATCHFILES</varname> с соответствующими элементами + групп в <varname>MASTER_SITES</varname> и + <varname>PATCH_SITES</varname>, которые используют группы + из <varname>MASTER_SITE_SUBDIR</varname> и + <varname>PATCH_SITE_SUBDIR</varname>. Посмотрите <xref linkend="ports-master-sites-n-example-detailed-use-complete-example-master-sites"/>.</para> + </listitem> + + <listitem> + <para><buildtarget>fetch-list</buildtarget>: работает также, + как старая цель <buildtarget>fetch-list</buildtarget> с тем + исключением, что она группирует, как и + <buildtarget>do-fetch</buildtarget>.</para> + </listitem> + + <listitem> + <para><buildtarget>master-sites</buildtarget> и + <buildtarget>patch-sites</buildtarget>: + (несовместимы со старыми версиями) только возвращают + элементы группы <literal>DEFAULT</literal>; на самом деле + они выполняют цели + <buildtarget>master-sites-default</buildtarget> и + <buildtarget>patch-sites-default</buildtarget> + соответственно.</para> + + <para>Более того, использование целей + <buildtarget>master-sites-all</buildtarget> или + <buildtarget>patch-sites-all</buildtarget> предпочтительно + для непосредственной проверки + <buildtarget>MASTER_SITES</buildtarget> или + <buildtarget>PATCH_SITES</buildtarget>. Также работа прямой + проверки в последующих версиях не гарантируется. + Посмотрите <xref linkend="porting-master-sites-n-new-port-targets-master-sites-all"/> + для получения более дополнительной информации об этих новых + целях.</para> + </listitem> + </itemizedlist> + </listitem> + + <listitem> + <para>Новые цели построения портов</para> + + <orderedlist> + <listitem> + <para>Имеются цели + <buildtarget>master-sites-<replaceable>n</replaceable></buildtarget> + и + <buildtarget>patch-sites-<replaceable>n</replaceable></buildtarget>, + которые будут перечислять элементы соответствующей группы + <replaceable>n</replaceable> из + <varname>MASTER_SITES</varname> и + <varname>PATCH_SITES</varname> соответственно. К примеру, + <buildtarget>master-sites-DEFAULT</buildtarget> и + <buildtarget>patch-sites-DEFAULT</buildtarget> обе будут + возвращать элементы группы <literal>DEFAULT</literal>, + <buildtarget>master-sites-test</buildtarget> и + <buildtarget>patch-sites-test</buildtarget> группы + <literal>test</literal> и так далее.</para> + </listitem> + + <listitem xml:id="porting-master-sites-n-new-port-targets-master-sites-all"> + <para>Имеются новые цели + <buildtarget>master-sites-all</buildtarget> и + <buildtarget>patch-sites-all</buildtarget>, которые выполняют + работу старых <buildtarget>master-sites</buildtarget> и + <buildtarget>patch-sites</buildtarget>. Они возвращают + элементы всех групп, как если бы они все принадлежали одной + и той же группе с тем, что она перечисляет ровно столько + <varname>MASTER_SITE_BACKUP</varname> и + <varname>MASTER_SITE_OVERRIDE</varname>, как и группы, + определённые в <varname>DISTFILES</varname> или + <varname>PATCHFILES</varname>; соответственно для + <buildtarget>master-sites-all</buildtarget> и + <buildtarget>patch-sites-all</buildtarget>.</para> + </listitem> + </orderedlist> + </listitem> + </orderedlist> + </sect3> + </sect2> + + <sect2> + <title><varname>DIST_SUBDIR</varname></title> + + <para>Не позволяйте вашему порту засорять + <filename>/usr/ports/distfiles</filename>. Если вашему порту + требуется сгрузить много файлов, или он содержит имя файла, + могущее вызвать конфликты с другими портами (например, + <filename>Makefile</filename>), то укажите в переменной + <varname>DIST_SUBDIR</varname> имя порта (должны подойти + <literal>${PORTNAME}</literal> или + <literal>${PKGNAMEPREFIX}${PORTNAME}</literal>). Это изменит + значение переменной <varname>DISTDIR</varname> со значения по + умолчанию <filename>/usr/ports/distfiles</filename> к значению + <filename>/usr/ports/distfiles/DIST_SUBDIR</filename>, + и в результате всё, что требуется для порта, будет помещено в этот + подкаталог.</para> + + <para>Он заглянет также в подкаталог с тем же именем на + основном резервном сервере <filename>ftp.FreeBSD.org</filename>. + (Явное задание переменной <varname>DISTDIR</varname> в вашем файле + <varname>Makefile</varname> этого не сделает, так что, пожалуйста, + воспользуйтесь <varname>DIST_SUBDIR</varname>.)</para> + + <note> + <para>Это не коснётся тех сайтов <varname>MASTER_SITES</varname>, + которые вы указали в вашем файле + <filename>Makefile</filename>.</para> + </note> + </sect2> + + <sect2> + <title><varname>ALWAYS_KEEP_DISTFILES</varname></title> + + <para>Если ваш порт использует двоичные дистрибутивные файлы и + обладает лицензией, требующей, чтобы исходный код предоставлялся + вместе с пакетами, распространяемыми в двоичной форме, например + GPL, то <varname>ALWAYS_KEEP_DISTFILES</varname> даст кластеру + построения &os; указание сохранять копию файлов, указанных в + <varname>DISTFILES</varname>. Пользователям таких портов эти + файлы в основном не нужны, поэтому хорошей идеей является + добавление в <varname>DISTFILES</varname> исходных + дистрибутивных файлов, только когда определена переменная + <varname>PACKAGE_BUILDING</varname>.</para> + + <example xml:id="ports-master-sites-n-example-always-keep-distfiles"> + <title>Использование <varname>ALWAYS_KEEP_DISTFILES</varname>.</title> + <programlisting>.if defined(PACKAGE_BUILDING) +DISTFILES+= <replaceable>foo.tar.gz</replaceable> +ALWAYS_KEEP_DISTFILES= yes +.endif</programlisting> + </example> + + <para>При добавлении дополнительных файлов в <varname>DISTFILES</varname> + убедитесь, что вы их также добавляете в <filename>distinfo</filename>. + Кроме того, дополнительные файлы обычно распаковываются также в + <varname>WRKDIR</varname>, что для некоторых портов может вызывать + нежелательные подобные эффекты и требовать особую обработку.</para> + </sect2> + </sect1> + + <sect1 xml:id="makefile-maintainer"> + <title><varname>MAINTAINER</varname></title> + + <para>Укажите здесь ваш адрес электронной почты. Пожалуйста. + <!-- smiley --><emphasis>:-)</emphasis></para> + + <para>Заметьте, что в качестве значения для + <varname>MAINTAINER</varname> допустимо использование только одного + адреса без поля комментария. Должен использоваться формат + <literal>user@hostname.domain</literal>. Пожалуйста, не включайте + никакого описательного текста, например, вашего настоящего имени в + эту строку—это несколько сбивает с толку + <filename>bsd.port.mk</filename>.</para> + + <para>Сопровождающий ответственен за поддержание порта в актуальном + состоянии и обеспечение правильной работы порта. За подробным + описанием обязанностей сопровождающего порт обращайтесь к главе + <link xlink:href="&url.articles.contributing-ports.en;/maintain-port.html">The + challenge for port maintainers</link>.</para> + + <para>Перед фиксацией в репозитории изменения в порте будут отправлены + сопровождающему для просмотра и одобрения. + Если сопровождающий порта не ответил на запрос пользователя об + обновлении в течение двух недель (исключая большие праздники), + то это можно считать тайм-аутом сопровождающего, и обновление может + быть выполнено без явного подтверждения от сопровождающего. Если + сопровождающий не отвечает в течение трёх месяцев, то считается, что + он отсутствует, и как сопровождающий порта, о котором идёт речь, может + быть заменён. Исключениями из этого правила является всё, что + сопровождает &a.portmgr; или &a.security-officer;. Запрещено делать + любые несанкционированные изменения в портах, которые ведут эти + группы.</para> + + <para>Мы оставляем за собой право изменять сообщение сопровождающего + для лучшего соответствия существующим политикам и стилю Коллекции + Портов без явного одобрения со стороны отправителя. Также, + крупные изменения в инфраструктуре могут повлечь изменения в порте + без согласия сопровождающего. Такой вид изменений никогда не будет + затрагивать функциональность порта.</para> + + <para>За &a.portmgr; оставляется право снять или назначить кого-либо + сопровождающим по любой причине, а за the &a.security-officer; + оставляется право лишать или назначать права на сопровождение порта + по соображениям информационной безопасности.</para> + </sect1> + + <sect1 xml:id="makefile-comment"> + <title><varname>COMMENT</varname></title> + + <para>Содержит однострочное описание порта. Пожалуйста, соблюдайте + следующие правила:</para> + + <orderedlist> + <listitem> + <para>Старайтесь делать строку COMMENT длиной не больше, чем 70 + символов, так как эта строка будет использована командой + <command>pkg info</command> (см. &man.pkg-info.8;) для + отображения однострочного описания порта;</para> + </listitem> + + <listitem> + <para><emphasis>Не</emphasis> включайте сюда название пакета + (или номер версии программного обеспечения);</para> + </listitem> + + <listitem> + <para>Комментарий должен начинаться с заглавной буквы и не + заканчиваться точкой;</para> + </listitem> + + <listitem> + <para>Не начинайте комментарий с неопределённого артикля (A + или An);</para> + </listitem> + + <listitem> + <para>Имена пишутся с заглавной буквы (например, Apache, + JavaScript. Perl);</para> + </listitem> + + <listitem> + <para>Для перечислений используйте английскую Оксфордскую + запятую (англ. Oxford comma) (например, green, + red<emphasis>,</emphasis> and blue);</para> + </listitem> + + <listitem> + <para>Используйте программу проверки орфографии.</para> + </listitem> + </orderedlist> + + <para>Вот пример:</para> + + <programlisting>Cat chasing a mouse all over the screen</programlisting> + + <para>В файле <filename>Makefile</filename> переменная COMMENT должна + следовать сразу за переменной MAINTAINER.</para> + </sect1> + + <sect1 xml:id="makefile-portscout"> + <title><varname>PORTSCOUT</varname></title> + + <para><application>Portscout</application> являет собой + автоматизированное средство проверки доступности дистрибутивных + файлов для Коллекции Портов &os;, подробное описание которого + предоставляет <xref linkend="distfile-survey"/>.</para> + + <para>Переменная <varname>PORTSCOUT</varname> задаёт специальные + условия, ограничивающие работу <application>Portscout</application> + - сканера дистрибутивных файлов.</para> + + <para>Ситуации, при которых следует указывать переменную + <varname>PORTSCOUT</varname>:</para> + + <itemizedlist> + <listitem> + <para>Когда должны игнорироваться дистрибутивные файлы для + конкретных версий или младших ревизий. Например, чтобы + исключить из проверок новых версий дистрибутивных файлов + версию <replaceable>8.2</replaceable> по причине того, что + она является поломанной, добавьте следующее:</para> + + <programlisting>PORTSCOUT= ignore:8.2</programlisting> + + </listitem> + <listitem> + <para>Когда должны проверяться конкретные версии или старшие + и младшие ревизии дистрибутивных файлов. Например, если + следует ограничиться проверкой версии + <replaceable>0.6.4</replaceable>, потому что более новые + версии имеют проблемы совместимости с &os;, добавьте:</para> + + <programlisting>PORTSCOUT= limit:^0\.6\.4</programlisting> + + </listitem> + <listitem> + <para>Когда URL, в которых указаны доступные версии, отличаются + от URL их загрузки. Например, чтобы привязать проверку новых + версий дистрибутивных файлов к странице загрузки для порта + <package role="port">databases/pgtune</package>, + добавьте:</para> + + <programlisting>PORTSCOUT= site:http://pgfoundry.org/frs/?group_id=1000416</programlisting> + </listitem> + </itemizedlist> + </sect1> + + <sect1 xml:id="makefile-depend"> + <title>Зависимости</title> + + <para>Многие порты зависят от других портов. Это очень удобная + замечательная особенность большинства Unix-подобных операционных + систем, включая &os;. Множество портов могут использовать общую + зависимость совместно, а не включать её в состав каждого порта или + пакета, который в ней нуждается. Имеется семь переменных, + которые вы можете использовать для обеспечения того, что всё + требуемое находится на машине пользователя. Имеется также несколько + предопределённых переменных, отражающих зависимости для общих + случаев, плюс ещё несколько для управления поведением + зависимостей.</para> + + <sect2> + <title><varname>LIB_DEPENDS</varname></title> + + <para>Эта переменная указывает, от каких совместно используемых + библиотек зависит порт. Это список пар + <replaceable>lib</replaceable>:<replaceable>dir</replaceable> + где <replaceable>lib</replaceable> - это имя библиотеки, + <replaceable>dir</replaceable> - это каталог, в котором можно ее + найти в случае, если ее нет на машине. Например,</para> + + <programlisting>LIB_DEPENDS= libjpeg.so:${PORTSDIR}/graphics/jpeg</programlisting> + + <para>проверит наличие библиотеки jpeg с любым номером версии и + перейдет в подкаталог <filename>graphics/jpeg</filename> вашего + дерева портов для ее построения и установки, если библиотека + отсутствует.</para> + + <para>Зависимость проверяется дважды, один раз внутри цели + <buildtarget>build</buildtarget>, а затем из цели + <buildtarget>install</buildtarget>. Кроме того, имя зависимости + помещается в пакет, так что <command>pkg install</command> + (см. &man.pkg-install.8;) будет + автоматически её устанавливать, если её нет на пользовательской + системе.</para> + </sect2> + + <sect2> + <title><varname>RUN_DEPENDS</varname></title> + + <para>В этой переменной перечисляются выполнимые файлы или файлы, от + которых зависит работа порта. Это список пар вида + <replaceable>path</replaceable>:<replaceable>dir</replaceable><optional>:target</optional> + где <replaceable>path</replaceable> - это имя программы или файла, + а <replaceable>dir</replaceable> - каталог, в котором можно найти + порт в случае, если его нет в системе, и + <replaceable>target</replaceable> - это цель, которую нужно вызвать + в этом каталоге. Если <replaceable>path</replaceable> начинается + со слэша (<literal>/</literal>), он воспринимается как файл и его + существование проверяется командой <command>test -e</command>; в + противном случае предполагается, что это выполнимый файл, и + для определения того, имеется ли программа в пути поиска, + используется команда <command>which -s</command>.</para> + + <para>Например,</para> + + <programlisting>RUN_DEPENDS= ${LOCALBASE}/news/bin/innd:${PORTSDIR}/news/inn \ + xmlcatmgr:${PORTSDIR}/textproc/xmlcatmgr</programlisting> + + <para>проверит существование файла или каталога + <filename>/usr/local/news/bin/innd</filename>, и если ничего + не будет найдено, то построит и установит порт из подкаталога + <filename>news/inn</filename> дерева портов. Также будет + выполнена проверка, присутствует ли в пути поиска исполняемый + файл с именем <command>xmlcatmgr</command>, и перейдет в + подкаталог <filename>textproc/xmlcatmgr</filename> вашего дерева + портов для его построения и установки, если он не будет + найден.</para> + + <note> + <para>В приведенном примере <command>innd</command> является + выполнимым файлом; если выполнимый файл находится в месте, + которое отсутствует в списке путей файлов, то вы должны указать + полный путь к файлу.</para> + </note> + + <note> + <para>Официальным значением переменной поиска <envar>PATH</envar>, + используемым в кластере построения портов является</para> + + <programlisting>/sbin:/bin:/usr/sbin:/usr/bin:/usr/local/sbin:/usr/local/bin</programlisting> + </note> + + <para>Зависимость проверяется внутри цели + <buildtarget>install</buildtarget>. Кроме того, имя зависимости + помещается в пакет, так что <command>pkg install</command> + (см. &man.pkg-install.8;) + будет автоматически его устанавливать, если он не будет найден + в пользовательской системе. Часть + <replaceable>target</replaceable> может быть опущена, если она + совпадает с <varname>DEPENDS_TARGET</varname>.</para> + + <para>Довольно распространенной является ситуация, когда + <varname>RUN_DEPENDS</varname> буквально такая же как + <varname>BUILD_DEPENDS</varname>, особенно если переносимое + программное обеспечение написано на языке сценариев, или если + оно требует такое же окружение для исполнения, как и используемое + во время построения. В этом случае, очень заманчивым или довольно + естественным является присвоение одного другому:</para> + + <programlisting>RUN_DEPENDS= ${BUILD_DEPENDS}</programlisting> + + <para>Тем не менее, подобные присвоения могут загрязнять зависимости + времени исполнения содержимым, не заданным в + <varname>BUILD_DEPENDS</varname> исходного порта. + Такое случается из-за ленивого вычисления в &man.make.1; + присваиваемых переменных. Представьте <filename>Makefile</filename> + с переменными <varname>USE_<replaceable>*</replaceable></varname>, + которые обрабатываются в <filename>ports/Mk/bsd.*.mk</filename> + для пополнения первоначальных зависимостей построения. Например, + <literal>USES= gmake</literal> добавляет + <package role="port">devel/gmake</package> в + <varname>BUILD_DEPENDS</varname>. Для предотвращения загрязнения + <varname>RUN_DEPENDS</varname> подобными дополнительными + зависимостями проявляйте осторожность с присвоением с раскрытием, + т.е. с раскрытием значения перед его присвоением переменной:</para> + + <programlisting>RUN_DEPENDS:= ${BUILD_DEPENDS}</programlisting> + </sect2> + + <sect2> + <title><varname>BUILD_DEPENDS</varname></title> + + <para>В этой переменной перечисляются выполнимые или обычные файлы, + которые требуются порту для его построения. Как и + <varname>RUN_DEPENDS</varname>, это список пар + <replaceable>path</replaceable>:<replaceable>dir</replaceable><optional>:target</optional> + Например,</para> + + <programlisting>BUILD_DEPENDS= unzip:${PORTSDIR}/archivers/unzip</programlisting> + + <para>будет проверять + наличие выполнимого фала с именем <command>unzip</command> и + перейдет в подкаталог <filename>archivers/unzip</filename> вашего + дерева портов для его построения и установки, если последний не + будет найден.</para> + + <note> + <para>Под <quote>построением</quote> здесь понимается всё, от + распаковки до компиляции. Зависимость проверяется из цели + <buildtarget>extract</buildtarget>. Часть + <replaceable>target</replaceable> может быть опущена, если она + совпадает с <varname>DEPENDS_TARGET</varname>.</para> + </note> + </sect2> + + <sect2> + <title><varname>FETCH_DEPENDS</varname></title> + + <para>В этой переменной перечисляются выполняемые файлы или просто + файлы, которые требуются порту для сгрузки. Как и предыдущие две + переменные, это список пар + <replaceable>path</replaceable>:<replaceable>dir</replaceable><optional>:target</optional> + Например,</para> + + <programlisting>FETCH_DEPENDS= ncftp2:${PORTSDIR}/net/ncftp2</programlisting> + + <para>будет проверять + наличие выполняемого файла с именем <command>ncftp2</command> и + перейдет в каталог <filename>net/ncftp2</filename> вашего дерева + портов для его построения и установки, если тот не будет + найден.</para> + + <para>Зависимость проверяется при выполнении цели + <buildtarget>fetch</buildtarget>. Часть + <replaceable>target</replaceable> может быть опущена, если она + совпадает с <varname>DEPENDS_TARGET</varname>.</para> + </sect2> + + <sect2> + <title><varname>EXTRACT_DEPENDS</varname></title> + + <para>В этой переменной указываются программы или файлы, которые + требуются для распаковки порта. Как и в предыдущих случаях, это + список пар вида + <replaceable>path</replaceable>:<replaceable>dir</replaceable><optional>:target</optional>. + Например,</para> + + <programlisting>EXTRACT_DEPENDS= unzip:${PORTSDIR}/archivers/unzip</programlisting> + + <para>будет проверять + наличие программы с именем <command>unzip</command>, и перейдёт в + подкаталог <filename>archivers/unzip</filename> вашего дерева + портов для её построения и установки, если такой программы не будет + найдено.</para> + + <para>Зависимость проверяется внутри цели + <buildtarget>extract</buildtarget>. Часть + <replaceable>target</replaceable> может быть опущена, если она + совпадает с <varname>DEPENDS_TARGET</varname>.</para> + + <note> + <para>Используйте эту переменную, только если распаковка не + работает (по умолчанию предполагается использование + <command>gzip</command>) и это не исправляется при помощи + <varname>USE_ZIP</varname> или <varname>USE_BZIP2</varname>, + которые описаны в <xref linkend="use-vars"/>.</para> + </note> + </sect2> + + <sect2> + <title><varname>PATCH_DEPENDS</varname></title> + + <para>Эта переменная указывает на программы или файлы, которые нужны + порту для применения патчей. Как и в предыдущих случаях, это + список пар вида + <replaceable>path</replaceable>:<replaceable>dir</replaceable><optional>:target</optional>. + Например,</para> + + <programlisting>PATCH_DEPENDS= ${NONEXISTENT}:${PORTSDIR}/java/jfc:extract</programlisting> + + <para>будет + переходить в подкаталог <filename>java/jfc</filename> вашего дерева + портов для распаковки.</para> + + <para>Зависимость проверяется внутри цели + <buildtarget>patch</buildtarget>. Часть + <replaceable>target</replaceable> может быть опущена, если она + совпадает с <varname>DEPENDS_TARGET</varname>.</para> + </sect2> + + <sect2 xml:id="uses"> + <title><varname>USES</varname></title> + + <para>Могут быть добавлены параметры для определения различных + характерных особенностей и зависимостей, которыми + обладает данный порт. Они указываются путём добавления + в <filename>Makefile</filename> этой строки:</para> + + <programlisting>USES= feature[:arguments]</programlisting> + + <para>Для получения полного списка значений смотрите + <xref linkend="uses-values"/>.</para> + + <warning> + <para>Значение <varname>USES</varname> нельзя присваивать + после подключения <filename>bsd.port.pre.mk</filename>.</para> + </warning> + </sect2> + + <sect2 xml:id="use-vars"> + <title><varname>USE_<replaceable>*</replaceable></varname></title> + + <para>Для определения общих зависимостей, совместно используемых + многими портами, предназначено несколько переменных. Их + использование является необязательным, но помогает упростить + избыточность файлов <filename>Makefile</filename> порта. + Каждый из них оформляется как + <varname>USE_<replaceable>*</replaceable></varname>. Эти + переменные можно использовать только в <filename>Makefile</filename> + порта и <filename>ports/Mk/bsd.*.mk</filename>. Они не + предназначены для установки пользователями параметров — + используйте для этих целей <varname>PORT_OPTIONS</varname>.</para> + + <note> + <para>Установка любых <varname>USE_<replaceable>*</replaceable></varname> + в <filename>/etc/make.conf</filename> <emphasis>всегда</emphasis> + является ошибочным действием. В частности, установка</para> + + <programlisting>USE_GCC=X.Y</programlisting> + + <para>(где X.Y соответствует версии) добавит зависимость + от gccXY к каждому порту, включая и сам + <literal>lang/gccXY</literal>!</para> + </note> + + <table frame="none"> + <title>Переменные + <varname>USE_<replaceable>*</replaceable></varname></title> + + <tgroup cols="2"> + <thead> + <row> + <entry>Переменная</entry> + + <entry>Значение</entry> + </row> + </thead> + + <tbody> + <row> + <entry><varname>USE_BZIP2</varname></entry> + + <entry>tar-архивы порта упакованы при помощи + <command>bzip2</command>.</entry> + </row> + + <row> + <entry><varname>USE_ZIP</varname></entry> + + <entry>tar-архивы порта упакованы при помощи + <command>zip</command>.</entry> + </row> + + <row> + <entry><varname>USE_GCC</varname></entry> + + <entry>Для сборки порта требуется GCC + (<command>gcc</command> или <command>g++</command>). + Некоторым портам подходит любая версия, для других + требуются последние современные версии. Обычно + используется со значением <literal>any</literal> (в + этом случае используется встроенный GCC в тех + версиях &os;, в состав которых он всё ещё входит, + или устанавливается порт + <literal>lang/gcc</literal>, когда Clang является + компилятором C/C++ по умолчанию) или + <literal>yes</literal> (всегда используется + стабильная современная версия GCC из порта + <literal>lang/gcc</literal>). Также в значении + переменной можно указать точную версию, например + <literal>4.7</literal>. Минимально допустимую + версию можно указать как <literal>4.6+</literal>. + GCC из основной системы используется в случае, если + его версия удовлетворяет запрошенной, иначе + собирается подходящая версии компилятора из порта с + соответствующей коррекцией переменных + <varname>CC</varname> и <varname>CXX</varname>. + </entry> + </row> + + </tbody> + </tgroup> + </table> + + <para>Переменные, относящиеся к <application>gmake</application> + и сценарию <filename>configure</filename>, описаны в + <xref linkend="building"/>, а <application>autoconf</application>, + <application>automake</application> и + <application>libtool</application> описаны в + <xref linkend="using-autotools"/>. Переменные, связанные с + <application>Perl</application>, описаны в <xref linkend="using-perl"/>. Переменные X11 перечислены в <xref linkend="using-x11"/>. <xref linkend="using-gnome"/> + работает с переменными GNOME и <xref linkend="using-kde"/> с KDE. + <xref linkend="using-java"/> описывает переменные Java, а <xref linkend="using-php"/> содержит информацию об + <application>Apache</application>, <application>PHP</application> + и модулях PEAR. <application>Python</application> обсуждается в + <xref linkend="using-python"/>, а <application>Ruby</application> + в <xref linkend="using-ruby"/>. <xref linkend="using-sdl"/> + предоставляет переменные, используемые для приложений + <application>SDL</application>, и, наконец, + <xref linkend="using-xfce"/> содержит информацию о приложении + <application>Xfce</application>.</para> + </sect2> + + <sect2> + <title>Минимальная версия зависимости</title> + + <para>Минимальная версия зависимости может быть указана в любой + переменной <varname>*_DEPENDS</varname>, за исключением + <varname>LIB_DEPENDS</varname>, с использованием следующего + синтаксиса:</para> + + <programlisting>p5-Spiffy>=0.26:${PORTSDIR}/devel/p5-Spiffy</programlisting> + + <para>Первое поле содержит название зависимого пакета, которое + обязано совпадать с записью в базе данные пакетов, знак сравнения + и версию версию пакета. Зависимость удовлетворяется если на машине + установлен p5-Spiffy-0.26 или новее.</para> + </sect2> + + <sect2> + <title>Замечания касательно зависимостей</title> + + <para>Как уже отмечено выше, целью, которая вызывается по умолчанию + в случае, когда это требует зависимость, является + <buildtarget>DEPENDS_TARGET</buildtarget>. Она по умолчанию есть + <literal>install</literal>. Это пользовательская переменная; она + нигде не определена в файле <filename>Makefile</filename> порта. + Если вашему порту требуется особый метод обработки зависимости, + воспользуйтесь частью <literal>:target</literal> переменной + <varname>*_DEPENDS</varname> вместо того, чтобы переопределять + <varname>DEPENDS_TARGET</varname>.</para> + + <para>Когда вы набираете команду <command>make clean</command>, + эта операция также выполняется и над зависимостями этого порта. + Если вы не хотите, чтобы это случилось, определите переменную + <varname>NOCLEANDEPENDS</varname> в вашем окружении. + Это может быть особенно нужным, если порт имеет нечто, что занимает + много времени на построение, в своём списке зависимостей, например, + KDE, GNOME или Mozilla.</para> + + <para>Чтобы безусловно зависеть от другого порта, укажите переменную + <varname>${NONEXISTENT}</varname> в качестве первого поля + переменной <varname>BUILD_DEPENDS</varname> или + <varname>RUN_DEPENDS</varname>. Пользуйтесь этим, только когда вам + нужно иметь исходный код другого порта. Вы можете сэкономить время + на компиляции, указав также и цель. Например,</para> + + <programlisting>BUILD_DEPENDS= ${NONEXISTENT}:${PORTSDIR}/graphics/jpeg:extract</programlisting> + + <para>всегда будет переходить в каталог с портом + <literal>jpeg</literal> и распаковывать его.</para> + </sect2> + + <sect2> + <title>Зацикленные зависимости фатальны</title> + + <important> + <para>Не помещайте зацикливающиеся зависимости в дерево + портов!</para> + </important> + + <para>Технология построения портов не защищена от зацикленных + зависимостей. Если вы создадите такую, то у кого-нибудь и + где-нибудь установка &os; будет немедленно сломана, а у остальных + сломается несколько позже. Это на самом деле очень трудно + распознать; если вы сомневаетесь, то перед внесением изменений + проверьте, что выполнили следующее: <command>cd /usr/ports; make + index</command>. Этот процесс может быть достаточно медленным на + старых машинах, хотя мы сможете спасти большое количество + людей—включая себя—от грядущих бед.</para> + </sect2> + + <sect2> + <title>Автоматические зависимости и проблемы, которые они + вызывают</title> + + <para>Зависимости должны быть указаны либо явно, либо с + использованием <link linkend="makefile-options">фреймворка + OPTIONS</link>. Использование прочих методов, таких как + автоматическое обнаружение зависимостей, усложняет индексирование, + что вызывает проблемы в управлении портами и пакетами.</para> + + <example> + <title>Некорректное объявление необязательной зависимости</title> + + <programlisting>.include <bsd.port.pre.mk> + +.if exists(${LOCALBASE}/bin/foo) +LIB_DEPENDS= libbar.so:${PORTSDIR}/foo/bar +.endif</programlisting> + </example> + + <para>Проблема автоматического добавления зависимостей + заключается в том, что файлы и настройки за пределами порта + могут произвольно меняться. Пример: после построения + индекса устанавливается набор портов. При этом один из + них устанавливает проверяемый файл. На этом этапе индекс + будет неправильным, потому что установленный порт неожиданно + получит новую зависимость. Индекс может быть по прежнему + неправильным даже после его перестроения, в случае если + другие порты также определят дополнительные зависимости, + основываясь на существовании других файлов.</para> + + <example> + <title>Корректное объявление необязательной зависимости</title> + + <programlisting>OPTIONS_DEFINE= BAR +BAR_DESC= Bar support + +.include <bsd.port.options.mk> + +.if ${PORT_OPTIONS:MBAR} +LIB_DEPENDS= libbar.so:${PORTSDIR}/foo/bar +.endif</programlisting> + </example> + + <para>Правильным способом является проверка переменных параметров. + Этот способ не приводит к несоответствиям в индексе набора + портов, поскольку параметры определены до построения индекса. + При этом можно использовать простые скрипты для автоматизации + построения, установки и обновления этих портов и соответствующих + им пакетов.</para> + </sect2> + + <sect2 xml:id="use-want"> + <title><varname>USE_</varname> и + <varname>WANT_</varname></title> + + <para>Переменные <varname>USE_</varname> задаются мейнтейнером + порта для определения программного обеспечения, от которого + этот порт зависит. Порт, для которого нужен Firefox, + укажет</para> + + <programlisting>USE_FIREFOX= yes</programlisting> + + <para>Некоторые переменные <varname>USE_</varname> могут + принимать номера версий или другие параметры. Например, + порт, который требует Apache 2.2, укажет</para> + + <programlisting>USE_APACHE= 22</programlisting> + + <para>В некоторых случаях для большего контроля над + зависимостями используются переменные <varname>WANT_</varname>, + которые позволяют указывать требования в более точной форме. + Например, взгляните на порт + <package role="port">mail/squirrelmail</package>. Этому порту + нужны несколько модулей PHP, которые перечислены в переменной + <varname>USE_PHP</varname>:</para> + + <programlisting>USE_PHP= session mhash gettext mbstring pcre openssl xml</programlisting> + + <para>Эти модули доступны в версиях CLI и web, поэтому версия + web выбрана с переменной <varname>WANT_</varname>:</para> + + <programlisting>WANT_PHP_WEB= yes</programlisting> + + <para>Имеющиеся переменные <varname>USE_</varname> и + <varname>WANT_</varname> определены в файлах в + <filename class="directory">/usr/ports/Mk</filename>.</para> + </sect2> + </sect1> + + <sect1 xml:id="makefile-masterdir"> + <title><varname>MASTERDIR</varname></title> + + <para>Если вашему порту требуется построение довольно различающихся + версий пакетов через переменную (задающую, например, разрешение, + или размер бумаги), которая принимает различные значения, создайте для + каждого пакета отдельный подкаталог, чтобы пользователям было легче + определить, каким пакетом воспользоваться, но попробуйте использовать + совместно между портами как можно больше файлов. В типичном случае вам + потребуются только очень короткие файлы <filename>Makefile</filename> + во всех каталогах, кроме одного, если вы будете использовать переменные + с умом. В отдельных файлах <filename>Makefile</filename> вы можете + использовать переменную <varname>MASTERDIR</varname> для указания + каталога, в котором находятся все остальные файлы. Также используйте + переменную как часть <link linkend="porting-pkgname"><varname>PKGNAMESUFFIX</varname></link>, чтобы + пакеты имели разные имена.</para> + + <para>Продемонстрируем это на примере. Вот часть файла + <filename>japanese/xdvi300/Makefile</filename>:</para> + + <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 + </programlisting> + + <para>Порт <package role="port">japanese/xdvi300</package> содержит + также все обычные патчи, файлы для пакета и так далее. Если вы введете + здесь команду <command>make</command>, она возьмет в качестве разрешения + значение по умолчанию (300) и построит порт обычным образом.</para> + + <para>Для другого разрешения приведем <emphasis>полный</emphasis> + <filename>xdvi118/Makefile</filename>:</para> + + <programlisting>RESOLUTION= 118 +MASTERDIR= ${.CURDIR}/../xdvi300 + +.include "${MASTERDIR}/Makefile"</programlisting> + + <para>(<filename>xdvi240/Makefile</filename> и + <filename>xdvi400/Makefile</filename> похожи). Задание + <varname>MASTERDIR</varname> говорит <filename>bsd.port.mk</filename>, + что обычный набор подкаталогов типа <varname>FILESDIR</varname> и + <varname>SCRIPTDIR</varname> находится в каталоге + <filename>xdvi300</filename>. Строчка + <literal>RESOLUTION=118</literal> переопределят строку + <literal>RESOLUTION=300</literal> в файле + <filename>xdvi300/Makefile</filename> и порт будет построен с + разрешением 118.</para> + </sect1> + + <sect1 xml:id="makefile-manpages"> + <title>Страницы Справочника</title> + + <para>Если ваш порт определяет корнем для файлов Справочника каталог, + отличный от <varname>PREFIX</varname>, вы можете использовать + переменную <varname>MANDIRS</varname>, чтобы указать эти каталоги. + Обратите внимание, что файлы страниц справочника следует размещать + в <filename>pkg-plist</filename> наряду с остальными файлами. + <varname>MANDIRS</varname> предназначена для автоматического + сжатия страниц справочника, так чтобы имена файлов оканчивались + на <filename>.gz</filename>.</para> + </sect1> + + <sect1 xml:id="makefile-info"> + <title>Файлы в формате info</title> + + <para>Если в вашем пакете нужна установка файлов GNU info, они должны + быть перечислены в переменной <varname>INFO</varname> (без окончания + <literal>.info</literal>), по записи на документ. Предполагается, + что эти файлы устанавливаются в + <filename>PREFIX/INFO_PATH</filename>. + Вы можете изменить <varname>INFO_PATH</varname>, если ваш пакет + использует другое место для размещения. Однако, это не рекомендуется + делать. Эти записи всего лишь содержат путь относительно + <filename>PREFIX/INFO_PATH</filename>. + Например, <package role="port">lang/gcc34</package> устанавливает + файлы info в + <filename>PREFIX/INFO_PATH/gcc34</filename>, + и в <varname>INFO</varname> будет что-то вроде этого:</para> + + <programlisting>INFO= gcc34/cpp gcc34/cppinternals gcc34/g77 ...</programlisting> + + <para>Перед регистрацией пакета соответствующий код установки/удаления будет + автоматически добавлен во временный <filename>pkg-plist</filename>.</para> + </sect1> + + <sect1 xml:id="makefile-options"> + <title>Опции для Makefile</title> + + <para>Многие приложения могут быть построены в различных + конфигурациях и с дополнительной функциональностью. Например, + выбор естественного (человеческого) языка, GUI против командной + строки или типа используемой базы данных. Пользователи могут + нуждаться в различных конфигурациях, отличных от используемой по + умолчанию, поэтому в системе портов предусмотрен механизм, + позволяющий автору порта управлять сборкой того или иного + варианта конфигурации. + Правильная поддержка этих необязательных параметров облегчает + пользователям жизнь и даёт два или более порта по цене одного.</para> + + <sect2> + <title>Knobs</title> + + <sect3> + <title><varname>WITH_<replaceable>*</replaceable></varname> + и + <varname>WITHOUT_<replaceable>*</replaceable></varname></title> + + <para>Эти переменные предназначены для установки системным + администратором. Многие из них стандартизованы в файле + <link xlink:href="http://svnweb.FreeBSD.org/ports/head/KNOBS?view=markup"><filename>ports/KNOBS</filename></link>.</para> + + <para>При создании порта не давайте имя для knob, специфичное + для данного приложения. На примере порта Avahi, используйте + <varname>WITHOUT_MDNS</varname> вместо + <varname>WITHOUT_AVAHI_MDNS</varname>.</para> + + <note> + <para>Не стоит рассчитывать, что + <varname>WITH_<replaceable>*</replaceable></varname> + обязательно имеет соответствующую переменную + <varname>WITHOUT_<replaceable>*</replaceable></varname>, + и наоборот. В общем случае, предполагается значение по + умолчанию.</para> + </note> + + <note> + <para>Если обратное не указано, то проверяется только факт + установки самих переменных, но не их конкретное значение типа + <literal>YES</literal> или <literal>NO</literal>.</para> + </note> + + <table frame="none"> + <title>Основные переменные + <varname>WITH_<replaceable>*</replaceable></varname> + и <varname>WITHOUT_<replaceable>*</replaceable></varname></title> + + <tgroup cols="2"> + <thead> + <row> + <entry>Переменная</entry> + + <entry>Значение</entry> + </row> + </thead> + + <tbody> + <row> + <entry><varname>WITH_OPENSSL_BASE</varname></entry> + + <entry>Использовать версию OpenSSL из базовой системы.</entry> + </row> + + <row> + <entry><varname>WITH_OPENSSL_PORT</varname></entry> + + <entry>Устанавливает версию OpenSSL из + <package role="port">security/openssl</package>, + даже если в базовой системе последняя версия.</entry> + </row> + </tbody> + </tgroup> + </table> + + </sect3> + + <sect3> + <title>Наименование KNOBS</title> + <para>Портеры должны использовать так называемые + knobs для помощи конечным пользователям и для поддержания + количества наименований knobs в небольшом количестве. + Список популярных названий knobs можно найти в файле <link xlink:href="http://svnweb.FreeBSD.org/ports/head/KNOBS?view=markup"><filename>KNOBS</filename></link> + </para> + + <para>Названия knobs должны отражать, что это такое и что + выполняет. Если у порта имеется библиотечный префикс в + <varname>PORTNAME</varname>, то он должен присутствовать в + названии knobs.</para> + </sect3> + </sect2> + + <sect2> + <title><varname>OPTIONS</varname></title> + + <sect3> + <title>Описание</title> + <para>При установке порта переменные <varname>OPTIONS_*</varname> + предоставляют пользователю окно диалога с отображением + доступных параметров, с записью выбранных параметров в файл + <filename>/var/db/ports/${UNIQUENAME}/options</filename>. + Эти опции повторно используются при следующем построении + порта.</para> + + <para>Когда пользователь запускает <command>make config</command> + (или запускает впервые <command>make build</command>), + инфраструктура выполняет проверку существования файла + <filename>/var/db/ports/${UNIQUENAME}/options</filename>. + Если этот файл не существует, то используются значения + <varname>OPTIONS_*</varname> и отображается диалоговое окно, + в котором эти параметры можно включить или выключить. + Затем сохраняется файл опций <filename>options</filename>, + и выбранные переменные используются при построении порта.</para> + + <para>Если новая версия порта добавляет новые значения + <varname>OPTIONS</varname>, то пользователю будет представлено + окно диалога с сохраненными заполненными значениями старых + <varname>OPTIONS.</varname></para> + + <para><command>make showconfig</command> отображает + сохраненную конфигурацию. Для удаления + сохраненной конфигурации используйте + <command>make rmconfig</command>.</para> + </sect3> + + <sect3> + <title>Синтаксис</title> + + <para><varname>OPTIONS_DEFINE</varname> содержит список + используемых <varname>OPTIONS</varname>. Они независимы + друг от друга и не сгруппированы:</para> + + <programlisting>OPTIONS_DEFINE= OPT1 OPT2</programlisting> + + <para>Далее после определения следует описание + <varname>OPTIONS</varname> (не является обязательным, + но настоятельно рекомендуется):</para> + + <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</programlisting> + + <tip> + <para><filename>ports/Mk/bsd.options.desc.mk</filename> + содержит описание множества наиболее используемых + <varname>OPTIONS</varname>; переопределять их, как + правило, не нужно.</para> + </tip> + + <tip> + <para>При описании параметров старайтесь представить себя + на месте пользователя: <quote>Что это делает?</quote> + и <quote>Для чего бы я захотел включить это?</quote> + Не делайте простое повторение названия. Например, + описание параметра <literal>NLS</literal> как + <quote>include NLS support</quote> (<quote>включить + поддержку NLS</quote>) не поможет пользователю, который + уже видит название параметра, но может не знать, что + это означает. Описав его как <quote>Native Language + Support via gettext utilities</quote> (<quote>Поддержка + национального языка через утилиты gettext</quote>), + вы поможете пользователю гораздо больше.</para> + </tip> + + <para><varname>OPTIONS</varname> можно группировать в виде + переключателей, для которых разрешен выбор единственного + варианта в каждой группе:</para> + + <programlisting>OPTIONS_SINGLE= SG1 +OPTIONS_SINGLE_SG1= OPT3 OPT4</programlisting> + + <para><varname>OPTIONS</varname> можно группировать в виде + переключателей, для которых разрешен выбор единственного + варианта (или ни одного) в каждой группе:</para> + + <programlisting>OPTIONS_RADIO= RG1 +OPTIONS_RADIO_RG1= OPT7 OPT8</programlisting> + + <para><varname>OPTIONS</varname> также можно группировать + в виде списков со множественным выбором, для которых + обязан быть включен <emphasis>по крайней мере + один</emphasis> из параметров:</para> + + <programlisting>OPTIONS_MULTI= MG1 +OPTIONS_MULTI_MG1= OPT5 OPT6</programlisting> + + <para><varname>OPTIONS</varname> также можно группировать + в виде списков со множественным выбором, для которых + могут быть включены любые параметры, включая отсутствие + выбора:</para> + + <programlisting>OPTIONS_GROUP= GG1 +OPTIONS_GROUP_GG1= OPT9 OPT10</programlisting> + + <para>По умолчанию <varname>OPTIONS</varname> находится в + выключенном положении, если при этом оно также отсутствует + в списке <varname>OPTIONS_DEFAULT</varname>:</para> + + <programlisting>OPTIONS_DEFAULT= OPT1 OPT3 OPT6</programlisting> + + <para>Определения <varname>OPTIONS</varname> обязаны появиться + до подключения <filename>bsd.port.options.mk</filename>. + Переменные <varname>PORT_OPTIONS</varname> + могут быть проверены только после + подключения <filename>bsd.port.options.mk</filename>. + Вместо этого также можно использовать подключение + <filename>bsd.port.pre.mk</filename>, что все еще широко + используется в портах, написанных до появления + <filename>bsd.port.options.mk</filename>. Но имейте в виду, + что некоторые переменные, обычно, это некоторые флаги + <varname>USE_*</varname>, + после подключения <filename>bsd.port.pre.mk</filename> будут + работать не так, как этого от них ожидают.</para> + + <example xml:id="ports-options-simple-use"> + <title>Простое использование <varname>OPTIONS</varname></title> + + <programlisting>OPTIONS_DEFINE= FOO BAR +FOO_DESC= Enable option foo +BAR_DESC= Support feature bar + +.include <bsd.port.options.mk> + +.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 <bsd.port.mk></programlisting> + </example> + + <example xml:id="ports-options-check-unset"> + <title>Проверка незаданных значений + <varname>OPTIONS</varname></title> + + <programlisting>.if ! ${PORT_OPTIONS:MEXAMPLES} +CONFIGURE_ARGS+=--without-examples +.endif</programlisting> + </example> + + <example xml:id="ports-options-practical-use"> + <title>Пример реального использования + <varname>OPTIONS</varname></title> + + <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 <bsd.port.options.mk> + +.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 <bsd.port.mk></programlisting> + </example> + </sect3> + + <sect3> + <title>Параметры по умолчанию</title> + <para>Следующие параметры по умолчанию всегда включены.</para> + <itemizedlist> + <listitem> + <para><literal>DOCS</literal> — построение и установка + документации.</para> + </listitem> + <listitem> + <para><literal>NLS</literal> — интернационализация.</para> + </listitem> + <listitem> + <para><literal>EXAMPLES</literal> — построение и + установка примеров использования.</para> + </listitem> + <listitem> + <para><literal>IPV6</literal> — поддержка протокола + IPv6.</para> + </listitem> + </itemizedlist> + <note> + <para>Нет необходимости добавлять эти параметры в + <varname>OPTIONS_DEFAULT</varname>. Тем не менее, чтобы + отобразить их в окне диалога выбора параметров, они должны + быть добавлены в <varname>OPTIONS_DEFINE</varname>.</para> + </note> + </sect3> + </sect2> + + <sect2> + <title>Функция автоматической активации</title> + + <para>При использовании сценария GNU configure, следите за тем, + какие необязательные функции задействуются посредством + автоматической активации. Отключайте явным образом те + необязательные функции, которые вы не хотели бы использовать, + через передачу соответствующих <literal>--without-xxx</literal> + или <literal>--disable-xxx</literal> в переменной + <varname>CONFIGURE_ARGS</varname>.</para> + + <example> + <title>Неправильное управление опцией</title> + + <programlisting>.if ${PORT_OPTIONS:MFOO} +LIB_DEPENDS+= libfoo.so:${PORTSDIR}/devel/foo +CONFIGURE_ARGS+= --enable-foo +.endif</programlisting> + </example> + + <para>В приведенном выше примере представьте себе библиотеку libfoo, + установленную в системе. Пользователь не желает, чтобы приложение + использовало libfoo, и поэтому он выключает соответствующую опцию + в диалоге <literal>make config</literal>. Но сценарий configure + приложения определяет наличие библиотеки в системе и включает ее + поддержку в итоговый исполняемый файл. Теперь, когда пользователь + решит удалить libfoo из системы, система портов позволит это + сделать (т.к. зависимость от libfoo не была записана), но + приложение перестанет работать.</para> + + <example> + <title>Правильное управление опцией</title> + + <programlisting>.if ${PORT_OPTIONS:MFOO} +LIB_DEPENDS+= libfoo.so:${PORTSDIR}/devel/foo +CONFIGURE_ARGS+= --enable-foo +.else +CONFIGURE_ARGS+= --disable-foo +.endif</programlisting> + </example> + + <para>Во втором примере библиотека libfoo отключена явным образом. + Сценарий configure не включает соответствующие функции в приложении, + несмотря на присутствие библиотеки в системе.</para> + + <note> + <para>При определенных условиях сокращенный синтаксис записи + условий может вызывать проблемы со сложными конструкциями. + Если вы получаете ошибки, такие как <literal>Malformed + conditional</literal>, то может быть использован + альтернативный синтаксис.</para> + + <programlisting>.if !empty(VARIABLE:MVALUE) +# as an alternative to +.if ${VARIABLE:MVALUE}</programlisting> + </note> + </sect2> + + <sect2> + <title>Вспомогательные макросы</title> + + <para>Существует несколько макросов, упрощающих запись условных + значений, которые отличаются в зависимости от набора + параметров.</para> + + <para>Если переменная <varname>OPTIONS_SUB</varname> имеет + значение <literal>yes</literal>, то каждый из указанных в + <varname>OPTIONS_DEFINE</varname> параметров будет добавлен + в <varname>PLIST_SUB</varname>. Следующая запись:</para> + + <programlisting>OPTIONS_DEFINE= OPT1 +OPTIONS_SUB= yes</programlisting> + + <para>соответствует:</para> + + <programlisting>OPTIONS_DEFINE= OPT1 + +.include <bsd.port.options.mk> + +.if ${PORT_OPTIONS:MOPT1} +PLIST_SUB+= OPT1="" +.else +PLIST_SUB+= OPT1="@comment " +.endif</programlisting> + + <para><varname>X_CONFIGURE_ENABLE</varname> дописывает в + <varname>CONFIGURE_ARGS</varname> строку + <literal>--enable-${X_CONFIGURE_ENABLE}</literal> или + <literal>--disable-${X_CONFIGURE_ENABLE}</literal> в + соответствии с состоянием <varname>X</varname>. Следующая + запись:</para> + + <programlisting>OPTIONS_DEFINE= OPT1 +OPT1_CONFIGURE_ENABLE= test</programlisting> + + <para>соответствует:</para> + + <programlisting>OPTIONS_DEFINE= OPT1 + +.include <bsd.port.options.mk> + +.if ${PORT_OPTIONS:MOPT1} +CONFIGURE_ARGS+= --enable-test +.else +CONFIGURE_ARGS+= --disable-test +.endif</programlisting> + + <para><varname>X_CONFIGURE_WITH</varname> дописывает в + <varname>CONFIGURE_ARGS</varname> строку + <literal>--with-${X_CONFIGURE_WITH}</literal> или + <literal>--without-${X_CONFIGURE_WITH}</literal> в + соответствии с состоянием <varname>X</varname>. Следующая + запись:</para> + + <programlisting>OPTIONS_DEFINE= OPT1 +OPT1_CONFIGURE_WITH= test</programlisting> + + <para>соответствует:</para> + + <programlisting>OPTIONS_DEFINE= OPT1 + +.include <bsd.port.options.mk> + +.if ${PORT_OPTIONS:MOPT1} +CONFIGURE_ARGS+= --with-test +.else +CONFIGURE_ARGS+= --without-test +.endif</programlisting> + + <para>Значение переменной <varname>X_CONFIGURE_ON</varname> + будет дописано в <varname>CONFIGURE_ARGS</varname> в + соответствии с состоянием <varname>X</varname>. Следующая + запись:</para> + + <programlisting>OPTIONS_DEFINE= OPT1 +OPT1_CONFIGURE_ON= --add-test</programlisting> + + <para>соответствует:</para> + + <programlisting>OPTIONS_DEFINE= OPT1 + +.include <bsd.port.options.mk> + +.if ${PORT_OPTIONS:MOPT1} +CONFIGURE_ARGS+= --add-test +.endif</programlisting> + + <para>Значение переменной <varname>X_CONFIGURE_OFF</varname> + будет дописано в <varname>CONFIGURE_ARGS</varname> в + соответствии с состоянием <varname>X</varname>. Следующая + запись:</para> + + <programlisting>OPTIONS_DEFINE= OPT1 +OPT1_CONFIGURE_OFF= --no-test</programlisting> + + <para>соответствует:</para> + + <programlisting>OPTIONS_DEFINE= OPT1 +.include <bsd.port.options.mk> +.if ! ${PORT_OPTIONS:MOPT1} +CONFIGURE_ARGS+= --no-test +.endif</programlisting> + + <para>Значение переменной <varname>X_CMAKE_ON</varname> будет + дописано в <varname>CMAKE_ARGS</varname> в соответствии с + состоянием <varname>X</varname>. Следующая запись:</para> + + <programlisting>OPTIONS_DEFINE= OPT1 +OPT1_CMAKE_ON= -DTEST:BOOL=true</programlisting> + + <para>соответствует:</para> + + <programlisting>OPTIONS_DEFINE= OPT1 + +.include <bsd.port.options.mk> + +.if ${PORT_OPTIONS:MOPT1} +CMAKE_ARGS+= -DTEST:BOOL=true +.endif</programlisting> + + <para>Значение переменной <varname>X_CMAKE_OFF</varname> будет + дописано в <varname>CMAKE_ARGS</varname> в соответствии с + состоянием <varname>X</varname>. Следующая запись:</para> + + <programlisting>OPTIONS_DEFINE= OPT1 +OPT1_CMAKE_OFF= -DTEST:BOOL=false</programlisting> + + <para>соответствует:</para> + + <programlisting>OPTIONS_DEFINE= OPT1 + +.include <bsd.port.options.mk> + +.if ! ${PORT_OPTIONS:MOPT1} +CMAKE_ARGS+= -DTEST:BOOL=false +.endif</programlisting> + + <para>Для любой из следующих переменных:</para> + + <itemizedlist> + <listitem> + <para><varname>ALL_TARGET</varname></para> + </listitem> + + <listitem> + <para><varname>CATEGORIES</varname></para> + </listitem> + + <listitem> + <para><varname>CFLAGS</varname></para> + </listitem> + + <listitem> + <para><varname>CPPFLAGS</varname></para> + </listitem> + + <listitem> + <para><varname>CXXFLAGS</varname></para> + </listitem> + + <listitem> + <para><varname>CONFIGURE_ENV</varname></para> + </listitem> + + <listitem> + <para><varname>DISTFILES</varname></para> + </listitem> + + <listitem> + <para><varname>EXTRA_PATCHES</varname></para> + </listitem> + + <listitem> + <para><varname>INSTALL_TARGET</varname></para> + </listitem> + + <listitem> + <para><varname>LDFLAGS</varname></para> + </listitem> + + <listitem> + <para><varname>MAKE_ARGS</varname></para> + </listitem> + + <listitem> + <para><varname>MAKE_ENV</varname></para> + </listitem> + + <listitem> + <para><varname>PATCH_SITES</varname></para> + </listitem> + + <listitem> + <para><varname>PATCHFILES</varname></para> + </listitem> + + <listitem> + <para><varname>PLIST_FILES</varname></para> + </listitem> + + <listitem> + <para><varname>PLIST_DIRS</varname></para> + </listitem> + + <listitem> + <para><varname>PLIST_DIRSTRY</varname></para> + </listitem> + + <listitem> + <para><varname>USES</varname></para> + </listitem> + </itemizedlist> + + <para>Значение переменной <varname>X_ABOVEVARIABLE</varname> + будет дописано в <varname>ABOVEVARIABLE</varname> в + соответствии с состоянием <varname>X</varname>. Следующая + запись:</para> + + <programlisting>OPTIONS_DEFINE= OPT1 +OPT1_USES= gmake +OPT1_CFLAGS= -DTEST</programlisting> + + <para>соответствует:</para> + + <programlisting>OPTIONS_DEFINE= OPT1 + +.include <bsd.port.options.mk> + +.if ${PORT_OPTIONS:MOPT1} +USES+= gmake +CFLAGS+= -DTEST +.endif</programlisting> + + <para>Если установлена <varname>X_ABOVEVARIABLE_OFF</varname>, + то флаг <literal>ABOVEVARIABLE</literal> будет автоматически + выставлен при выключенном параметре <literal>X</literal>. + Например:</para> + + <programlisting>OPTIONS_DEFINE= OPT1 +OPT1_USES_OFF=gmake</programlisting> + + <para>соответствует:</para> + + <programlisting>OPTIONS_DEFINE= OPT1 + +.include <bsd.port.options.mk> + +.if ! ${PORT_OPTIONS:MOPT1} +USES+= gmake +.endif</programlisting> + + <para>Для любого из следующих типов зависимости:</para> + + <itemizedlist> + <listitem> + <para><varname>PKG_DEPENDS</varname></para> + </listitem> + + <listitem> + <para><varname>EXTRACT_DEPENDS</varname></para> + </listitem> + + <listitem> + <para><varname>PATCH_DEPENDS</varname></para> + </listitem> + + <listitem> + <para><varname>FETCH_DEPENDS</varname></para> + </listitem> + + <listitem> + <para><varname>BUILD_DEPENDS</varname></para> + </listitem> + + <listitem> + <para><varname>LIB_DEPENDS</varname></para> + </listitem> + + <listitem> + <para><varname>RUN_DEPENDS</varname></para> + </listitem> + </itemizedlist> + + <para>Значение переменной <varname>X_ABOVEVARIABLE</varname> + будет дописано в <varname>ABOVEVARIABLE</varname> в + соответствии с состоянием <varname>X</varname>. Следующая + запись:</para> + + <programlisting>OPTIONS_DEFINE= OPT1 +OPT1_LIB_DEPENDS= liba.so:${PORTSDIR}/devel/a</programlisting> + + <para>соответствует:</para> + + <programlisting>OPTIONS_DEFINE= OPT1 + +.include <bsd.port.options.mk> + +.if ${PORT_OPTIONS:MOPT1} +LIB_DEPENDS+= liba.so:${PORTSDIR}/devel/a +.endif</programlisting> + + <para>Если установлена <varname>X_ABOVEVARIABLE_OFF</varname>, + то зависимость типа <literal>ABOVEVARIABLE</literal> будет + добавлена при выключенном параметре <literal>X</literal>. + Например:</para> + + <programlisting>OPTIONS_DEFINE= OPT1 +OPT1_LIB_DEPENDS_OFF= liba.so:${PORTSDIR}/devel/a</programlisting> + + <para>соответствует:</para> + + <programlisting>OPTIONS_DEFINE= OPT1 + +.include <bsd.port.options.mk> + +. if ! ${PORT_OPTIONS:MOPT1} +LIB_DEPENDS+= liba.so:${PORTSDIR}/devel/a +.endif</programlisting> + </sect2> + </sect1> + + <sect1 xml:id="makefile-wrkdir"> + <title>Задание рабочего каталога</title> + + <para>Каждый порт распаковывается в рабочий каталог, который должен быть + доступным для записи. В системе портов по умолчанию + <varname>DISTFILES</varname> распаковываются в каталог с именем + <literal>${DISTNAME}</literal>. Другими словами, если вы + задали:</para> + + <programlisting>PORTNAME= foo +PORTVERSION= 1.0</programlisting> + + <para>то дистрибутивные файлы порта содержат каталог верхнего уровня, + <filename>foo-1.0</filename>, и все файлы расположены в этом + каталоге.</para> + + <para>Если это не ваш случай, то имеется несколько переменных, которые + вы можете переопределить.</para> + + <sect2> + <title><varname>WRKSRC</varname></title> + + <para>Эта переменная задаёт имя каталога, который создаётся при + распаковке исходных файлов приложения. В нашем предыдущем + примере если бы распаковка происходила в каталог с именем + <filename>foo</filename> (а не + <filename>foo-1.0</filename>), то вы должны написать:</para> + + <programlisting>WRKSRC= ${WRKDIR}/foo</programlisting> + + <para>или, как вариант</para> + + <programlisting>WRKSRC= ${WRKDIR}/${PORTNAME}</programlisting> + </sect2> + + <sect2> + <title><varname>NO_WRKSUBDIR</varname></title> + + <para>Если порт вообще не распаковывается ни в какой каталог, то вы + должны задать переменную <varname>NO_WRKSUBDIR</varname> для указания + на этот факт.</para> + + <programlisting>NO_WRKSUBDIR= yes</programlisting> + </sect2> + </sect1> + + <sect1 xml:id="conflicts"> + <title>Разрешение конфликтов</title> + + <para>Для регистрации конфликта между пакетами и портами используются + три различные переменные: <varname>CONFLICTS</varname>, + <varname>CONFLICTS_INSTALL</varname> и + <varname>CONFLICTS_BUILD</varname>.</para> + + <note> + <para>Переменные регистрации конфликта автоматически определяют + переменную <varname>IGNORE</varname>, которая более подробно + описана в <xref linkend="dads-noinstall"/>.</para> + </note> + + <para>При удалении одного из конфликтующих портов целесообразно + сохранить записи <varname>CONFLICTS</varname> в тех других портах + в течении нескольких месяцев, чтобы позаботиться о тех пользователей, + которые обновляются от случая к случаю.</para> + + <sect2> + <title><varname>CONFLICTS_INSTALL</varname></title> + + <para>Если ваш пакет не может существовать вместе с другими + (из-за конфликта файлов, несовместимости времени выполнения и так + далее), перечислите имена остальных пакетов в переменной + <varname>CONFLICTS_INSTALL</varname>. Здесь вы можете использовать + шаблоны командного интерпретатора, такие как <literal>*</literal> + и <literal>?</literal>. Имена пакетов должны выглядеть так же, + как в <filename>/var/db/pkg</filename>. Пожалуйста, убедитесь, + что <varname>CONFLICTS_INSTALL</varname> не содержит пакет самого + этого порта. В противном случае не будет работать установка с + использованием переменной <varname>FORCE_PKG_REGISTER</varname>. + Проверка CONFLICTS_INSTALL выполняется после процесса сборки и + до процесса установки.</para> + </sect2> + + <sect2> + <title><varname>CONFLICTS_BUILD</varname></title> + + <para>Если ваш порт не может быть собран, когда уже установлен + другой, перечислите имена остальных портов в переменной + <varname>CONFLICTS_BUILD</varname>. Здесь вы можете использовать + шаблоны командного интерпретатора, такие как <literal>*</literal> + и <literal>?</literal>. Имена пакетов должны выглядеть так же, + как в <filename>/var/db/pkg</filename>. Проверка CONFLICTS_BUILD + выполняется до процесса сборки. Конфликты сборки в получаемом + пакете не записываются.</para> + </sect2> + + <sect2> + <title><varname>CONFLICTS</varname></title> + + <para>Если ваш порт не может быть собран, когда уже установлен + другой, а получаемый пакет не может существовать вместе с другими, + перечислите имена остальных пакетов в переменной + <varname>CONFLICTS</varname>. Здесь вы можете использовать шаблоны + командного интерпретатора, такие как <literal>*</literal> и + <literal>?</literal>. Имена пакетов должны выглядеть так же, как + в <filename>/var/db/pkg</filename>. Пожалуйста, убедитесь, что + <varname>CONFLICTS</varname> не содержит пакет самого этого порта. + В противном случае не будет работать установка с использованием + переменной <varname>FORCE_PKG_REGISTER</varname>. Проверка + CONFLICTS выполняется до процессов сборки и установки.</para> + </sect2> + </sect1> + + <sect1 xml:id="install"> + <title>Установка файлов</title> + + <sect2 xml:id="install-macros"> + <title>Макросы INSTALL_*</title> + + <para>Используйте макросы, которые есть в файле + <filename>bsd.port.mk</filename> для обеспечения правильных прав + доступа файлов в целях <buildtarget>*-install</buildtarget> + порта. Устанавливайте права владения напрямую в + <filename>pkg-plist</filename> через соответствующие записи + <literal>@owner owner</literal> и + <literal>@group group</literal>. Эти операторы работают до + момента их переопределения или до конца + <filename>pkg-plist</filename>, поэтому не забывайте их + сбрасывать, когда они больше не нужны. По умолчанию владение + устанавливается для <literal>root:wheel</literal>.</para> + + <itemizedlist> + <listitem> + <para><varname>INSTALL_PROGRAM</varname> - это команда для + установки бинарных выполнимых файлов.</para> + </listitem> + + <listitem> + <para><varname>INSTALL_SCRIPT</varname> - это команда для установки + выполнимых скриптов.</para> + </listitem> + + <listitem> + <para><varname>INSTALL_LIB</varname> - это команда для установки + динамических библиотек.</para> + </listitem> + + <listitem> + <para><varname>INSTALL_KLD</varname> - это команда для установки + загружаемых модулей ядра. Некоторые архитектуры предпочитают, + чтобы для модулей сохранялись отладочные сведения, по этой + причине используйте эту команду вместо + <varname>INSTALL_PROGRAM</varname>.</para> + </listitem> + + <listitem> + <para><varname>INSTALL_DATA</varname> - это команда для установки + совместно используемых файлов данных.</para> + </listitem> + + <listitem> + <para><varname>INSTALL_MAN</varname> - это команда для установки + страниц Справочника и другой документации (никаких файлов она не + сжимает).</para> + </listitem> + </itemizedlist> + + <para>В основе работы этих макросов лежит команда + <command>install</command> со всеми соответствующими флагами. + Смотрите пример их использования ниже.</para> + </sect2> + + <sect2 xml:id="install-strip"> + <title>Удаление отладочной информации в бинарных файлах и + динамических библиотеках</title> + + <para>Не удаляйте отладочную информацию из бинарных файлов вручную, + если вы это делали. Во всех двоичных файлах отладочная информация + должна быть удалена, и макрос <varname>INSTALL_PROGRAM</varname> + выполнит установку и удаление отладочной информации одновременно + (обратитесь к следующему разделу). Макрос + <varname>INSTALL_LIB</varname> делает то же самое для + динамических библиотек.</para> + + <para>Если вам нужно удалить отладочную информацию из файла без + использования макросов <varname>INSTALL_PROGRAM</varname> и + <varname>INSTALL_LIB</varname>, то это можно сделать при помощи + <varname>${STRIP_CMD}</varname>. Обычно это делается внутри цели + <literal>post-install</literal>. К примеру:</para> + + <programlisting>post-install: + ${STRIP_CMD} ${STAGEDIR}${PREFIX}/bin/xdl</programlisting> + + <para>Удаление отладочной информации из нескольких + файлов:</para> + + <programlisting>post-install: + .for l in geometry media body track world + ${STRIP_CMD} ${STAGEDIR}${PREFIX}/lib/lib${PORTNAME}-${l}.so.0 + .endfor</programlisting> + + <para>Для проверки того, удалена ли отладочная информация из + файла, используйте &man.file.1;. Для двоичных файлов + &man.file.1; печатает <literal>stripped</literal> или + <literal>not stripped</literal>. Кроме того, &man.strip.1; + определяет, была ли уже удалена из программы отладочная + информация, и в этом случае просто завершает свою работу.</para> + </sect2> + + <sect2 xml:id="install-copytree"> + <title>Установка целого дерева файлов</title> + + <para>Иногда должно быть установлено большое количество файлов + с сохранением их иерархической организации. Например, копирование + дерева каталогов целиком из <varname>WRKSRC</varname> в целевой + каталог внутри <varname>PREFIX</varname>. Обратите внимание, + что <varname>PREFIX</varname>, <varname>EXAMPLESDIR</varname>, + <varname>DATADIR</varname> и другие переменные пути всегда + должны предваряться <varname>STAGEDIR</varname>, чтобы не + ломать staging (смотрите <xref linkend="staging"/>).</para> + + <para>Для этой ситуации существует два макроса. Преимущество от + использования этих макросов вместо команды <command>cp</command> + в том, что они гарантируют установку правильного владельца и прав + на конечные файлы. Первый макрос, <varname>COPYTREE_BIN</varname>, + делает все устанавливаемые файлы исполняемыми, что подходит для + установки в <filename>PREFIX/bin</filename>. + Второй макрос, <varname>COPYTREE_SHARE</varname>, не устанавливает + на файлы права исполнения, и, таким образом, подходит для установки + файлов внутри каталога + <filename>PREFIX/share</filename>.</para> + + <programlisting>post-install: + ${MKDIR} ${STAGEDIR}${EXAMPLESDIR} + (cd ${WRKSRC}/examples && ${COPYTREE_SHARE} . ${STAGEDIR}${EXAMPLESDIR})</programlisting> + + <para>В этом примере устанавливается содержимое каталога + <filename>examples</filename> из установочных файлов производителя + в надлежащее место для примеров вашего порта.</para> + + <programlisting>post-install: + ${MKDIR} ${STAGEDIR}${DATADIR}/summer + (cd ${WRKSRC}/temperatures && ${COPYTREE_SHARE} "June July August" ${STAGEDIR}${DATADIR}/summer)</programlisting> + + <para>А в этом примере будут установлены данные летних месяцев в + подкаталог <filename>summer</filename> каталога + <filename>DATADIR</filename>.</para> + + <para>В качестве третьего параметра в макросе + <varname>COPYTREE_*</varname> можно передать дополнительные + параметры <command>find</command>. Например, чтобы в первом + примере установить все файлы кроме файлов Makefile, можно + использовать следующую команду.</para> + + <programlisting>post-install: + ${MKDIR} ${STAGEDIR}${EXAMPLESDIR} + (cd ${WRKSRC}/examples && \ + ${COPYTREE_SHARE} . ${STAGEDIR}${EXAMPLESDIR} "! -name Makefile")</programlisting> + + <para>Эти макросы не производят добавление устанавливаемых + файлов в <filename>pkg-plist</filename>. Они должны быть + добавлены туда вручную. Необязательные файлы документации + (<varname>PORTDOCS</varname>, смотрите + <xref linkend="install-documentation"/>) и примеров + (<varname>PORTEXAMPLES</varname>) всегда должны предваряться + в <filename>pkg-plist</filename> префиксами + <literal>%%PORTDOCS%%</literal> или + <literal>%%PORTEXAMPLES%%</literal>.</para> + </sect2> + + <sect2 xml:id="install-documentation"> + <title>Установка дополнительной документации</title> + + <para>Если с вашим программным обеспечением поставляется некоторая + документация, отличающаяся от стандартных страниц Справочника и + файлов info, которая, как вы думаете, будет полезна пользователям, + установите ее в каталог + <filename>PREFIX/share/doc</filename>. Это может + быть сделано, как и в предыдущем разделе, в цели + <buildtarget>post-install</buildtarget>.</para> + + <para>Создайте для вашего порта новый каталог. Имя каталога должно + соответствовать тому, что представляет из себя порт. Обычно это + означает <varname>PORTNAME</varname>. Однако, если + вы думаете, что пользователь захочет иметь разные версии порта, + установленные одновременно, то вы можете использовать полное имя + <varname>PKGNAME</varname>.</para> + + <para>Поскольку устанавливаются только файлы, перечисленные в + <filename>pkg-plist</filename>, безопасным способом будет + устанавливать документацию в <varname>STAGEDIR</varname> + всегда (смотрите <xref linkend="staging"/>). Следовательно, + блоки <literal>.if</literal> нужны только для файлов + достаточно большого размера, установка которых влечёт + значительные накладные расходы на операции ввода/вывода.</para> + + <programlisting>post-install: + ${MKDIR} ${STAGEDIR}${DOCSDIR} + ${INSTALL_MAN} ${WRKSRC}/docs/xvdocs.ps ${STAGEDIR}${DOCSDIR}</programlisting> + + <para>Вот несколько полезных переменных и то, как они преобразуются по + умолчанию при использовании в <filename>Makefile</filename>:</para> + + <itemizedlist> + <listitem> + <para><varname>DATADIR</varname> преобразуется в + <filename>PREFIX/share/PORTNAME</filename>.</para> + </listitem> + + <listitem> + <para><varname>DATADIR_REL</varname> преобразуется в + <filename>share/PORTNAME</filename>.</para> + </listitem> + + <listitem> + <para><varname>DOCSDIR</varname> преобразуется в + <filename>PREFIX/share/doc/PORTNAME</filename>.</para> + </listitem> + + <listitem> + <para><varname>DOCSDIR_REL</varname> преобразуется в + <filename>share/doc/PORTNAME</filename>.</para> + </listitem> + + <listitem> + <para><varname>EXAMPLESDIR</varname> преобразуется в + <filename>PREFIX/share/examples/PORTNAME</filename>.</para> + </listitem> + + <listitem> + <para><varname>EXAMPLESDIR_REL</varname> преобразуется в + <filename>share/examples/PORTNAME</filename>.</para> + </listitem> + </itemizedlist> + + <note> + <para>Параметр <literal>DOCS</literal> управляет установкой + дополнительной документации в <varname>DOCSDIR</varname>. Это + не относится к стандартным страницам справочника и страницам info. + Все, что устанавливается в <varname>DATADIR</varname> и + <varname>EXAMPLESDIR</varname>, соответственно управляется + через параметры <literal>DATA</literal> и + <literal>EXAMPLES</literal>.</para> + </note> + + <para>Эти переменные экспортируются в <varname>PLIST_SUB</varname>. + Их значения появятся там в виде имён путей относительно + <filename>PREFIX</filename>, если это возможно. + То есть <filename>share/doc/PORTNAME</filename> + в списке сборки по умолчанию будет заменен на + <literal>%%DOCSDIR%%</literal>, и так далее. (Дополнительную + информацию о подстановке в <filename>pkg-plist</filename> можно + найти <link linkend="plist-sub">здесь</link>.)</para> + + <para>Все условно устанавливаемые файлы и каталоги с документацией + должны быть перечислены в файле <filename>pkg-plist</filename> с + префиксом <literal>%%PORTDOCS%%</literal>, например:</para> + + <programlisting>%%PORTDOCS%%%%DOCSDIR%%/AUTHORS +%%PORTDOCS%%%%DOCSDIR%%/CONTACT +%%PORTDOCS%%@dirrm %%DOCSDIR%%</programlisting> + + <para>В качестве альтернативы перечислению файлов документации в файле + <filename>pkg-plist</filename>, порт может указать в переменной + <varname>PORTDOCS</varname> список имён файлов и глобальных шаблонов + командного процессора для добавления в окончательный список сборки. + Имена будут задаваться относительно <varname>DOCSDIR</varname>. + Таким образом, порт, использующий <varname>PORTDOCS</varname> и + нестандартное местоположение документации, должен задавать + соответствующим образом и <varname>DOCSDIR</varname>. Если каталог + указан в <varname>PORTDOCS</varname> или соответствует шаблону для + этой переменной, то полное поддерево с входящими в него файлами и + каталогами будет регистрироваться в окончательном списке сборки. + Если параметр <literal>DOCS</literal> не задан, то файлы и каталоги, + перечисленные в <varname>PORTDOCS</varname>, не будут установлены и + добавлены в список сборки порта. Установка документации в + <varname>PORTDOCS</varname>, как это показано выше, остаётся за + самим портом. Типичный пример использования + <varname>PORTDOCS</varname> выглядит следующим образом:</para> + + <programlisting>PORTDOCS= README.* ChangeLog docs/*</programlisting> + + <note> + <para>Эквивалентами <varname>PORTDOCS</varname> для файлов, + устанавливаемых в <varname>DATADIR</varname> и + <varname>EXAMPLESDIR</varname> являются <varname>PORTDATA</varname> + и <varname>PORTEXAMPLES</varname> соответственно.</para> + + <para>Во время установки выводится содержимое + <filename>pkg-message</filename>. За подробной информацией + обратитесь к <link linkend="porting-message">разделу об + использовании <filename>pkg-message</filename></link>. + Файл <filename>pkg-message</filename> не нужно добавлять в + <filename>pkg-plist</filename>.</para> + </note> + </sect2> + + <sect2 xml:id="install-subdirs"> + <title>Подкаталоги внутри PREFIX</title> + + <para>Попробуйте поместить все файлы порта в правильных подкаталогах + каталога <varname>PREFIX</varname>. Некоторые порты игнорируют все + установки и помещают все в подкаталог с именем порта, что + неправильно. Также многие порты помещают все, кроме бинарных файлов, + файлов заголовков и страниц Справочника, в подкаталог каталога + <filename>lib</filename>, что не очень хорошо работает с подходом + BSD. Многие файлы должны быть перемещены в одно из следующих + местоположений: <filename>etc</filename> + (настроечные/конфигурационные файлы), <filename>libexec</filename> + (выполнимые файлы, запускаемые из других программ), + <filename>sbin</filename> (исполнимые файлы для + администраторов/менеджеров системы), <filename>info</filename> + (документация в формате info для просмотрщика info) или + <filename>share</filename> (независимые от архитектуры файлы). + Обратитесь к &man.hier.7; для прояснения деталей; правила, + покрывающие <filename>/usr</filename>, достаточно хорошо подходят + также и к <filename>/usr/local</filename>. Исключением являются + порты, имеющие дело с <quote>новостями</quote> USENET. Они могут + использовать каталог + <filename>PREFIX/news</filename> для установки + своих файлов.</para> + </sect2> + + </sect1> + + </chapter> + |