doc/ru_RU.KOI8-R/books/porters-handbook/quick-porting/chapter.xml

<?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="quick-porting">

  <title>Быстрое портирование</title>

  <para>В этом разделе описано, как создать новый порт на скорую
    руку.  Во многих случаях этого бывает не достаточно, так что вам
    нужно будет прочитать документ дальше.</para>

  <para>Во-первых, скачайте оригинальный tar-файл и поместите его в
    каталог <varname>DISTDIR</varname>, который по умолчанию есть не
    что иное, как <filename>/usr/ports/distfiles</filename>.</para>

  <note>
    <para>Здесь предполагается, что программное обеспечение
      компилируется без проблем как есть, то есть для работы
      приложения на вашей системе &os; не потребовалось абсолютно
      никаких изменений.  Если требовалось что-то изменить, то вам
      придется обратиться также и к следующему разделу.</para>
  </note>

  <note>
    <para>Перед началом портирования рекомендуется установить
      переменную &man.make.1; <varname>DEVELOPER</varname> в
      <filename>/etc/make.conf</filename>.</para>

    <screen>&prompt.root; <userinput>echo DEVELOPER=yes >> /etc/make.conf</userinput></screen>

    <para>Эта настройка включает <quote>режим разработчика</quote>, в
      котором отображаются предупреждения при использовании
      устаревших конструкций и задействуются некоторые дополнительные
      проверки при вызове команды <command>make</command>.</para>
  </note>

  <sect1 xml:id="porting-makefile">
    <title>Создание файла <filename>Makefile</filename></title>

    <para>Минимальный <filename>Makefile</filename> будет выглядеть
      примерно так:</para>

    <programlisting># &dollar;FreeBSD&dollar;

PORTNAME=	oneko
PORTVERSION=	1.1b
CATEGORIES=	games
MASTER_SITES=	ftp://ftp.cs.columbia.edu/archives/X11R5/contrib/

MAINTAINER=	youremail@example.com
COMMENT=	Cat chasing a mouse all over the screen

.include &lt;bsd.port.mk&gt;</programlisting>

    <note>
      <para>В некоторых случаях в заголовке
	<filename>Makefile</filename> существующего порта могут
	содержаться дополнительные строки, такие как название порта и
	дата его создания.  Эта дополнительная информация была
	объявлена устаревшей и находится в процессе удаления.</para>
    </note>

    <para>Посмотрим, сможете ли вы его понять.  Не обращайте внимание
      на содержимое строчки
      <literal>&dollar;FreeBSD&dollar;</literal>, она будет заполнена
      автоматически системой <application>Subversion</application>,
      когда порт будет импортирован в наше дерево портов.  Вы можете
      найти более подробный пример в разделе <link
	linkend="porting-samplem">пример Makefile</link>.</para>
  </sect1>

  <sect1 xml:id="porting-desc">
    <title>Создание информационных файлов</title>

    <para>Имеется два информационных файла, которые требуются для
      любого порта, вне зависимости от того, является ли он пакетом
      или нет.  Это <filename>pkg-descr</filename> и
      <filename>pkg-plist</filename>.  Префикс
      <filename>pkg-</filename> отличает их от других файлов.</para>

    <sect2>
      <title><filename>pkg-descr</filename></title>

      <para>Это более подробное краткое описание порта.  От одного до
	нескольких абзацев, кратко описывающих, что представляет
	собой порт, будет достаточно.</para>

      <note>
	<para>Это <emphasis>не</emphasis> руководство и не
	  подробнейшее описание того, как использовать или
	  компилировать порт!  <emphasis>Пожалуйста, будьте
	  внимательны при копировании текста из
	  <filename>README</filename> или страниц справочника
	  </emphasis>; слишком часто они не являются кратким
	  описанием порта или имеют неудобный формат (например,
	  страницы справочника выровнены пробелами, что особенно
	  плохо смотрится с моноширинными шрифтами).</para>
      </note>

      <para>Хорошо составленный <filename>pkg-descr</filename>
	описывает порт достаточно полно, чтобы пользователю не
	приходилось сверяться с документацией или посещать вебсайт
	для понимания того, что делает данное программное
	обеспечение, чем оно может быть полезно или какие хорошие
	функции у него имеются.  Упоминание про определённые
	требования, такие как используемый графический
	инструментарий, тяжёлые зависимости, окружение для запуска
	или используемый язык программирования помогут пользователям
	определиться, будет ли этот порт для них работать.</para>

      <para>Включите сюда URL официальной домашней страницы Интернет.
	Перед <emphasis>одним</emphasis> из сайтов (выберите
	основной) добавьте <literal>WWW:</literal> (с последующим
	единичным пробелом) для того, чтобы вспомогательные утилиты
	работали правильно.  Если URI является корнем сайта или
	каталогом, то значение должно быть дополнено косой
	чертой.</para>

      <note>
	<para>Если указанная для порта веб-страница не доступна,
	  попытайтесь сперва поискать, был ли официальный сайт
	  перемещён, переименован или размещён в другом месте.</para>
      </note>

      <para>Следующий пример показывает, как должен выглядеть ваш
	<filename>pkg-descr</filename>:</para>

      <programlisting>This is a port of oneko, in which a cat chases a poor mouse all over
the screen.
 :
(etc.)

WWW: http://www.oneko.org/</programlisting>
    </sect2>

    <sect2>
      <title><filename>pkg-plist</filename></title>

      <para>Здесь перечисляются все файлы, устанавливаемые портом.
	Его также называют <quote>списком для упаковки</quote>,
	потому что пакет генерируется упаковкой файлов, которые здесь
	указаны.  Имена путей указываются относительно установочного
	префикса (обычно <filename>/usr/local</filename>).  Если порт
	во время установки создает каталоги, убедитесь, что добавлены
	строки <literal>@dirrm</literal> для удаления каталогов при
	удалении пакета.</para>

      <para>Вот маленький пример:</para>

      <programlisting>bin/oneko
man/man1/oneko.1.gz
lib/X11/app-defaults/Oneko
lib/X11/oneko/cat1.xpm
lib/X11/oneko/cat2.xpm
lib/X11/oneko/mouse.xpm
@dirrm lib/X11/oneko</programlisting>

      <para>Обратитесь к странице справочной системы по команде
	&man.pkg-create.8; с подробным описанием формата списка
	упаковки.</para>

      <note>
	<para>Рекомендуется, чтобы имена файлов в этом списке были
	  отсортированы в алфавитном порядке.  Это позволит
	  значительно облегчить сверку изменений при обновлении
	  порта.</para>
      </note>

      <note>
	<para>Создание списка упаковки вручную может оказаться весьма
	  трудоёмкой задачей.  Если порт устанавливает большое
	  количество файлов, раздел об <link
	    linkend="plist-autoplist">автоматическом построении
	  списка упаковки</link> может помочь сэкономить
	  время.</para>
      </note>

      <para>Существует только одно исключение, когда у порта может
	отсутствовать <filename>pkg-plist</filename>.  Если порт
	устанавливает лишь несколько файлов, а возможно, и каталогов,
	то они могут быть перечислены в переменных
	<varname>PLIST_FILES</varname> и
	<varname>PLIST_DIRS</varname>, соответственно, внутри файла
	<filename>Makefile</filename> порта.  К примеру, мы можем
	обойтись без файла <filename>pkg-plist</filename> у
	приведённого выше порта <filename>oneko</filename>, добавив
	следующие строки в <filename>Makefile</filename>:</para>

      <programlisting>PLIST_FILES=	bin/oneko \
		man/man1/oneko.1.gz \
		lib/X11/app-defaults/Oneko \
		lib/X11/oneko/cat1.xpm \
		lib/X11/oneko/cat2.xpm \
		lib/X11/oneko/mouse.xpm
PLIST_DIRS=	lib/X11/oneko</programlisting>

      <para>Конечно, переменная <varname>PLIST_DIRS</varname> не
	должна задаваться, если порт не устанавливает никаких
	каталогов.</para>

      <note>
	<para>Несколько портов могут совместно использовать общий
	  каталог.  В этом случае <varname>PLIST_DIRS</varname>
	  следует заменить на <varname>PLIST_DIRSTRY</varname>, так
	  чтобы каталог удалялся только если он пуст, а иначе
	  игнорировался.  Использование <varname>PLIST_DIRS</varname>
	  и <varname>PLIST_DIRSTRY</varname> аналогично
	  <literal>@dirrm</literal> и <literal>@dirrmtry</literal> в
	  <filename>pkg-plist</filename>, описание которых входит в
	  <xref linkend="plist-dir-cleaning"/>.</para>
      </note>

      <para>Обратной стороной такого способа перечисления файлов и
	каталогов порта является невозможность использования
	последовательностей команд, описанных в &man.pkg-create.8;.
	Поэтому он подходит для простых портов, что делает их ещё
	более простыми.  Одновременно с этим положительным моментом
	является уменьшение количества файлов в коллекции портов.
	Пожалуйста, подумайте над использованием этой техники, прежде
	чем создавать <filename>pkg-plist</filename>.</para>

      <para>Далее мы увидим, как можно использовать файлы
	<filename>pkg-plist</filename> и
	<varname>PLIST_FILES</varname> выполнения <link
	  linkend="plist">более сложных задач</link>.</para>
    </sect2>
  </sect1>

  <sect1 xml:id="porting-checksum">
    <title>Создание файла с контрольной суммой</title>

    <para>Просто введите команду <command>make makesum</command>.
      Правила утилиты make автоматически сгенерируют файл
      <filename>distinfo</filename>.</para>

    <para>Если у извлекаемого файла регулярно меняется контрольная
      сумма и вы не сомневаетесь в надежности источника (т.е. он
      получен из CD производителя, либо ежедневно обновляется
      документация), то вы должны указать эти файлы в переменной
      <varname>IGNOREFILES</varname>.  Тогда контрольная сумма при
      выполнении <command>make makesum</command> для этого файла
      создаваться не будет, а вместо этого для него будет установлено
      значение <literal>IGNORE</literal>.</para>
  </sect1>

  <sect1 xml:id="porting-testing">
    <title>Тестирование порта</title>

    <para>Вы должны удостовериться, что правила построения порта
      выполняют именно то, что вы хотите, включая создание пакета для
      порта.  Вот те важные вещи, которые вы должны проверить.</para>

    <itemizedlist>
      <listitem>
	<para><filename>pkg-plist</filename> не содержит ничего сверх
	  того, что устанавливается портом</para>
      </listitem>

      <listitem>
	<para><filename>pkg-plist</filename> содержит абсолютно все,
	  что устанавливается портом</para>
      </listitem>

      <listitem>
	<para>Порт может быть установлен с помощью указания цели
	  <buildtarget>install</buildtarget>.  Это позволяет
	  убедиться в правильной работе сценария установки.</para>
      </listitem>

      <listitem>
	<para>Порт может быть правильным образом удалён с помощью
	  указания цели <buildtarget>deinstall</buildtarget>.  Это
	  позволяет убедиться в правильной работе сценария
	  удаления.</para>
      </listitem>

      <listitem>
	<para>Следует убедиться, что <command>make package</command>
	  можно запустить из-под обычного пользователя (то есть, не
	  из-под <systemitem class="username">root</systemitem>).
	  Если это не так, в <filename>Makefile</filename> порта
	  должно быть добавлено
	  <literal>NEED_ROOT=yes</literal>.</para>
      </listitem>
    </itemizedlist>

    <procedure>
      <title>Рекомендуемый порядок проверки</title>

      <step>
	<para><command>make stage</command></para>
      </step>

      <step>
	<para><command>make check-orphans</command></para>
      </step>

      <step>
	<para><command>make package</command></para>
      </step>

      <step>
	<para><command>make install</command></para>
      </step>

      <step>
	<para><command>make deinstall</command></para>
      </step>

      <step>
	<para><command>pkg add package-filename</command></para>
      </step>

      <step>
	<para><command>make package</command> (из-под
	  пользователя)</para>
      </step>
    </procedure>

    <para>Убедитесь, что на любом из этапов не выдается никаких
      предупреждений.</para>

    <para>Основательное автоматизированное тестирование может быть
      выполнено при помощи <package
	role="port">ports-mgmt/tinderbox</package> или <package
	role="port">ports-mgmt/poudriere</package> из Коллекции
      Портов.  Эти приложения используют <literal>jails</literal>,
      в которых проверяются все перечисленные выше этапы без
      изменения состояния основной системы.</para>
  </sect1>

  <sect1 xml:id="porting-portlint">
    <title>Проверка вашего порта утилитой
      <command>portlint</command></title>

    <para>Будьте добры, пользуйтесь утилитой
      <command>portlint</command> для проверки того, что ваш порт
      соответствует нашим рекомендациям.  Программа <package
	role="port">ports-mgmt/portlint</package> является частью
      Коллекции Портов.  В частности, вы можете захотеть проверить,
      правильно ли сформирован файл <link
	linkend="porting-samplem">Makefile</link> и соответствующим
      ли образом именован <link
	linkend="porting-pkgname">пакет</link>.</para>
  </sect1>

  <sect1 xml:id="porting-submitting">
    <title>Посылка нового порта</title>

    <para>Перед посылкой нового порта прочитайте раздел о том, что
      <link linkend="porting-dads">можно и нельзя</link>
      делать.</para>

    <para>Когда вы наконец довольны своим первым портом,
      единственное, что осталось сделать, это включить его в основное
      дерево портов &os; и осчастливить этим всех остальных.  Нам не
      нужен ни каталог <filename>work</filename>, ни пакет
      <filename>pkgname.tgz</filename>, так что удалите их прямо
      сейчас.</para>

    <para>Затем получите файл &man.shar.1;.  Предполагая, что порт
      называется oneko, перейдите в каталог выше, где находится
      каталог <literal>oneko</literal>, и наберите:
      <command>shar `find oneko` &gt; oneko.shar</command></para>

    <para>Включите <filename>oneko.shar</filename> в сообщение об
      ошибке и пошлите его с помощью &man.send-pr.1;.  Обратитесь к
      разделу <link
	xlink:href="&url.articles.contributing;/contrib-how.html#CONTRIB-GENERAL">Сообщения
	об ошибках и общие замечания</link> для получения подробной
      информации о &man.send-pr.1;).</para>

    <para>Укажите в сообщении категорию <literal>ports</literal> и
      класс <literal>change-request</literal>.
      <emphasis>Не</emphasis> указывайте, что сообщение имеет статус
      <literal>confidential</literal>!  Добавьте краткое описание
      программы в поле <quote>Description</quote> отправляемого PR
      (например, содержимое <varname>COMMENT</varname> в сокращённом
      варианте) и сам файл в виде архива <filename>.shar</filename> в
      поле <quote>Fix</quote>.</para>

    <note>
      <para>Хорошее описание в заголовке сообщения о проблеме
	значительно облегчает работу коммиттеров портов.  Для новых
	портов мы предпочитаем нечто вроде <quote>New port:
	  &lt;категория&gt;/&lt;название порта&gt; &lt;краткое
	  описание порта&gt;</quote>.  Следование этой схеме упрощает
	и ускоряет начало работы по добавлению нового порта.</para>
    </note>

    <para>Повторим ещё раз, что <emphasis>не нужно включать ни
	оригинальный файл с дистрибутивом, ни каталог
	<filename>work</filename>, ни пакет, построенный вами
	командой <command>make package</command></emphasis>; для
      новых портов используйте &man.shar.1;, но не
      &man.diff.1;.</para>

    <para>После отправки порта, пожалуйста, потерпите.  Время,
      необходимое для включения нового порта во &os;, может занимать
      от нескольких дней до нескольких месяцев.  <link
	xlink:href="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?category=ports">
	Здесь</link> можно увидеть список ожидающих PR для
      портов.</para>

    <para>После рассмотрения нового порта мы при необходимости вам
      ответим, а затем включим порт в наше дерево.  Ваше имя также
      будет добавлено в список <link
	xlink:href="&url.articles.contributors;/contrib-additional.html">
	Дополнительных контрибуторов проекта &os;</link> и другие
      файлы.</para>
  </sect1>
</chapter>