Date: Sat, 22 Feb 2014 12:30:11 +0000 (UTC) From: Sergey Kandaurov <pluknet@FreeBSD.org> To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r44029 - in head/ru_RU.KOI8-R/books/porters-handbook: . appendices keeping-up makefiles new-port pkg-files plist porting-dads porting-samplem porting-why quick-porting security slow-por... Message-ID: <201402221230.s1MCUB3Z037858@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: pluknet Date: Sat Feb 22 12:30:10 2014 New Revision: 44029 URL: http://svnweb.freebsd.org/changeset/doc/44029 Log: MFen r43840 et al. Break the porters handbook out into individual chapters. Added: head/ru_RU.KOI8-R/books/porters-handbook/appendices/ head/ru_RU.KOI8-R/books/porters-handbook/appendices/Makefile (contents, props changed) head/ru_RU.KOI8-R/books/porters-handbook/appendices/chapter.xml (contents, props changed) head/ru_RU.KOI8-R/books/porters-handbook/chapters.ent (contents, props changed) head/ru_RU.KOI8-R/books/porters-handbook/keeping-up/ head/ru_RU.KOI8-R/books/porters-handbook/keeping-up/Makefile (contents, props changed) head/ru_RU.KOI8-R/books/porters-handbook/keeping-up/chapter.xml (contents, props changed) head/ru_RU.KOI8-R/books/porters-handbook/makefiles/ head/ru_RU.KOI8-R/books/porters-handbook/makefiles/Makefile (contents, props changed) head/ru_RU.KOI8-R/books/porters-handbook/makefiles/chapter.xml (contents, props changed) head/ru_RU.KOI8-R/books/porters-handbook/new-port/ head/ru_RU.KOI8-R/books/porters-handbook/new-port/Makefile (contents, props changed) head/ru_RU.KOI8-R/books/porters-handbook/new-port/chapter.xml (contents, props changed) head/ru_RU.KOI8-R/books/porters-handbook/pkg-files/ head/ru_RU.KOI8-R/books/porters-handbook/pkg-files/Makefile (contents, props changed) head/ru_RU.KOI8-R/books/porters-handbook/pkg-files/chapter.xml (contents, props changed) head/ru_RU.KOI8-R/books/porters-handbook/plist/ head/ru_RU.KOI8-R/books/porters-handbook/plist/Makefile (contents, props changed) head/ru_RU.KOI8-R/books/porters-handbook/plist/chapter.xml (contents, props changed) head/ru_RU.KOI8-R/books/porters-handbook/porting-dads/ head/ru_RU.KOI8-R/books/porters-handbook/porting-dads/Makefile (contents, props changed) head/ru_RU.KOI8-R/books/porters-handbook/porting-dads/chapter.xml (contents, props changed) head/ru_RU.KOI8-R/books/porters-handbook/porting-samplem/ head/ru_RU.KOI8-R/books/porters-handbook/porting-samplem/Makefile (contents, props changed) head/ru_RU.KOI8-R/books/porters-handbook/porting-samplem/chapter.xml (contents, props changed) head/ru_RU.KOI8-R/books/porters-handbook/porting-why/ head/ru_RU.KOI8-R/books/porters-handbook/porting-why/Makefile (contents, props changed) head/ru_RU.KOI8-R/books/porters-handbook/porting-why/chapter.xml (contents, props changed) head/ru_RU.KOI8-R/books/porters-handbook/quick-porting/ head/ru_RU.KOI8-R/books/porters-handbook/quick-porting/Makefile (contents, props changed) head/ru_RU.KOI8-R/books/porters-handbook/quick-porting/chapter.xml (contents, props changed) head/ru_RU.KOI8-R/books/porters-handbook/security/ head/ru_RU.KOI8-R/books/porters-handbook/security/Makefile (contents, props changed) head/ru_RU.KOI8-R/books/porters-handbook/security/chapter.xml (contents, props changed) head/ru_RU.KOI8-R/books/porters-handbook/slow-porting/ head/ru_RU.KOI8-R/books/porters-handbook/slow-porting/Makefile (contents, props changed) head/ru_RU.KOI8-R/books/porters-handbook/slow-porting/chapter.xml (contents, props changed) head/ru_RU.KOI8-R/books/porters-handbook/special/ head/ru_RU.KOI8-R/books/porters-handbook/special/Makefile (contents, props changed) head/ru_RU.KOI8-R/books/porters-handbook/special/chapter.xml (contents, props changed) head/ru_RU.KOI8-R/books/porters-handbook/testing/ head/ru_RU.KOI8-R/books/porters-handbook/testing/Makefile (contents, props changed) head/ru_RU.KOI8-R/books/porters-handbook/testing/chapter.xml (contents, props changed) head/ru_RU.KOI8-R/books/porters-handbook/upgrading/ head/ru_RU.KOI8-R/books/porters-handbook/upgrading/Makefile (contents, props changed) head/ru_RU.KOI8-R/books/porters-handbook/upgrading/chapter.xml (contents, props changed) Modified: head/ru_RU.KOI8-R/books/porters-handbook/Makefile head/ru_RU.KOI8-R/books/porters-handbook/book.xml head/ru_RU.KOI8-R/books/porters-handbook/uses.xml Modified: head/ru_RU.KOI8-R/books/porters-handbook/Makefile ============================================================================== --- head/ru_RU.KOI8-R/books/porters-handbook/Makefile Sat Feb 22 11:36:40 2014 (r44028) +++ head/ru_RU.KOI8-R/books/porters-handbook/Makefile Sat Feb 22 12:30:10 2014 (r44029) @@ -4,7 +4,7 @@ # $FreeBSD$ # $FreeBSDru: frdp/doc/ru_RU.KOI8-R/books/porters-handbook/Makefile,v 1.7 2003/09/26 02:34:16 andy Exp $ # -# Original revision: r42686 +# Original revision: r43849 # # @@ -27,6 +27,21 @@ INSTALL_ONLY_COMPRESSED?= # XML content SRCS= book.xml +SRCS+= porting-why/chapter.xml +SRCS+= new-port/chapter.xml +SRCS+= quick-porting/chapter.xml +SRCS+= slow-porting/chapter.xml +SRCS+= makefiles/chapter.xml +SRCS+= special/chapter.xml +SRCS+= plist/chapter.xml +SRCS+= pkg-files/chapter.xml +SRCS+= testing/chapter.xml +SRCS+= upgrading/chapter.xml +SRCS+= security/chapter.xml +SRCS+= porting-dads/chapter.xml +SRCS+= porting-samplem/chapter.xml +SRCS+= keeping-up/chapter.xml +SRCS+= appendices/chapter.xml SRCS+= uses.xml SRCS+= versions.xml @@ -55,4 +70,14 @@ IMAGES_LIB+= callouts/21.png DOC_PREFIX?= ${.CURDIR}/../../.. +# Entities +SRCS+= chapters.ent + +SYMLINKS= ${DESTDIR} index.html handbook.html + +# Turn on all the chapters. +CHAPTERS?= ${SRCS:M*chapter.xml} + +XMLFLAGS+= ${CHAPTERS:S/\/chapter.xml//:S/^/-i chap./} + .include "${DOC_PREFIX}/share/mk/doc.project.mk" Added: head/ru_RU.KOI8-R/books/porters-handbook/appendices/Makefile ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ head/ru_RU.KOI8-R/books/porters-handbook/appendices/Makefile Sat Feb 22 12:30:10 2014 (r44029) @@ -0,0 +1,17 @@ +# +# Build the Porters Handbook with just the content from this chapter. +# +# $FreeBSD$ +# +# Original revision: r43840 +# + +CHAPTERS= appendices/chapter.xml + +VPATH= .. + +MASTERDOC= ${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX} + +DOC_PREFIX?= ${.CURDIR}/../../../.. + +.include "../Makefile" Added: head/ru_RU.KOI8-R/books/porters-handbook/appendices/chapter.xml ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ head/ru_RU.KOI8-R/books/porters-handbook/appendices/chapter.xml Sat Feb 22 12:30:10 2014 (r44029) @@ -0,0 +1,73 @@ +<?xml version="1.0" encoding="koi8-r"?> +<!-- + The FreeBSD Russian Documentation Project + + $FreeBSD$ + + Original revision: r43844 +--> + +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="appendices"> + + <title>Приложения</title> + + <sect1 xml:id="uses-values"> + <title>Значения <varname>USES</varname></title> + + <table> + <title>Значения <varname>USES</varname></title> + + <tgroup cols="3"> + <thead> + <row> + <entry>Наименование</entry> + <entry>Аргументы</entry> + <entry>Описание</entry> + </row> + </thead> + <tbody valign="top"> + &values.uses; + </tbody> + </tgroup> + </table> + </sect1> + + <sect1 xml:id="freebsd-versions"> + <title>Значения <literal>__FreeBSD_version</literal></title> + + <para>Ниже для справки приводится перечень значений + <literal>__FreeBSD_version</literal> в виде, который определён в + <link xlink:href="http://svnweb.FreeBSD.org/base/head/sys/sys/param.h?view=markup">sys/param.h</link>:</para>; + + <table frame="none"> + <title>Значения <literal>__FreeBSD_version</literal></title> + + <tgroup cols="3"> + <thead> + <row> + <entry>Значение</entry> + <entry>Дата</entry> + <entry>Релиз</entry> + </row> + </thead> + + <tbody> + &values.versions; + </tbody> + </tgroup> + </table> + + <note> + <para>Заметьте, что 2.2-STABLE иногда идентифицирует себя как + <quote>2.2.5-STABLE</quote> после 2.2.5-RELEASE. Такой принцип + использовался год и месяц, но мы решили изменить его на более + однозначную систему нумерации старший/младший, начиная с версии + 2.2. Это объясняется тем, что параллельная разработка в нескольких + ветках делает непрактичным идентификацию релизов просто по их + реальным датам выпуска. Если вы сейчас делаете порт, вам не стоит + заботиться о старых версиях -CURRENT; они перечислены здесь просто + в информационных целях.</para> + </note> + </sect1> + </chapter> + Modified: head/ru_RU.KOI8-R/books/porters-handbook/book.xml ============================================================================== --- head/ru_RU.KOI8-R/books/porters-handbook/book.xml Sat Feb 22 11:36:40 2014 (r44028) +++ head/ru_RU.KOI8-R/books/porters-handbook/book.xml Sat Feb 22 12:30:10 2014 (r44029) @@ -3,16 +3,20 @@ "http://www.FreeBSD.org/XML/share/xml/freebsd50.dtd" [ <!ENTITY values.uses SYSTEM "uses.xml"> <!ENTITY values.versions SYSTEM "versions.xml"> -]> + <!-- The FreeBSD Russian Documentation Project $FreeBSD$ $FreeBSDru: frdp/doc/ru_RU.KOI8-R/books/porters-handbook/book.xml,v 1.136 2006/10/20 09:25:00 marck Exp $ - Original revision: r43827 + Original revision: r43840 --> +<!ENTITY % chapters SYSTEM "chapters.ent"> +%chapters; +]> + <book xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="ru"> @@ -59,12671 +63,19 @@ <releaseinfo>$FreeBSD$</releaseinfo> </info> - <chapter xml:id="why-port"> - <title>Введение</title> - - <para>Коллекция портов &os; является способом, используемым - практически каждым для установки приложений ("портов") на &os;. - Как и почти всё остальное во &os;, эта система в основном является - добровольно поддерживаемым начинанием. Важно иметь это в виду при - чтении данного документа.</para> - - <para>Во &os; каждый может прислать новый порт либо изъявить желание - поддерживать существующий порт, если его никто ещё никто не - поддерживает—вам не нужно иметь никаких особых привилегий на - внесение изменений, чтобы это делать.</para> - </chapter> - - <chapter xml:id="own-port"> - <title>Как самому сделать новый порт</title> - - <para>Итак, вы интересуетесь, как создать собственный порт или - обновить существующий? Великолепно!</para> - - <para>Ниже находятся некоторые указания по созданию нового порта для - &os;. Если вы хотите обновить существующий порт, вы должны - прочесть их, а затем <xref linkend="port-upgrading"/>.</para> - - <para>Если этот документ недостаточно подробен, вы должны обратиться к - файлу <filename>/usr/ports/Mk/bsd.port.mk</filename>, который - включается в make-файл каждого порта. Он хорошо прокомментирован, и - даже если вы не занимаетесь хакингом make-файлов каждодневно, из него - вы сможете узнать много нового. Кроме того, конкретные вопросы можно - задать, послав письмо на адрес &a.ports;.</para> - - <note> - <para>Только часть переменных - (<varname><replaceable>VAR</replaceable></varname>), которые могут быть - переопределены, описаны в этом документе. Большинство (если не все) - описаны в начале файла <filename>/usr/ports/Mk/bsd.port.mk</filename>; - остальные, скорее всего, тоже там описаны. Заметьте, что - в этом файле используется нестандартная настройка шага табуляции: - <application>Emacs</application> и <application>Vim</application> - должны распознать это при загрузке файла. Как &man.vi.1;, - так и &man.ex.1; могут быть настроены на использование - правильного значения выдачей команды <command>:set tabstop=4</command> - после загрузки файла.</para> - </note> - - <para> - Ищете, с чего бы начать попроще? Посмотрите на <link xlink:href="http://wiki.freebsd.org/WantedPorts">перечень запрошенных - портов</link>, есть ли там такие, над которыми вы можете работать. - </para> - </chapter> - - <chapter 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># $FreeBSD$ - -PORTNAME= oneko -PORTVERSION= 1.1b -CATEGORIES= games -MASTER_SITES= ftp://ftp.cs.columbia.edu/archives/X11R5/contrib/ - -MAINTAINER= youremail@example.com -COMMENT= Cat chasing a mouse all over the screen - -.include <bsd.port.mk></programlisting> - - <note> - <para>В некоторых случаях в заголовке <filename>Makefile</filename> - существующего порта могут содержаться дополнительные строки, - такие как название порта и дата его создания. - Эта дополнительная информация была объявлена устаревшей - и находится в процессе удаления.</para> - </note> - - <para>Посмотрим, сможете ли вы его понять. Не обращайте внимание на - содержимое строчки <literal>$FreeBSD$</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` > 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: - <категория>/<название порта> <краткое - описание порта></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> - - <chapter xml:id="slow"> - <title>Медленное портирование</title> - - <para>Итак, все оказалось не так уж и просто, и порт потребовал - некоторых модификаций для того, чтобы заставить его работать. В этом - разделе мы расскажем, шаг за шагом, как его модифицировать, чтобы он - работал с нашей системой портов.</para> - - <sect1 xml:id="slow-work"> - <title>Как всё это работает</title> - - <para>Во-первых, когда пользователь дает в своем каталоге с портом - команду <command>make</command>, происходит целая череда событий. - Во время чтения этого текста может оказаться полезным иметь файл - <filename>bsd.port.mk</filename> открытым в другом окне, что сильно - поможет в их понимании.</para> - - <para>Но не волнуйтесь сильно, если вы не до конца понимаете, что - делается в <filename>bsd.port.mk</filename>, не так уж много людей - его понимает... <!-- smiley --><emphasis>:-></emphasis></para> - - <procedure> - <step> - <para>Запускается цель <buildtarget>fetch</buildtarget>. Цель - <buildtarget>fetch</buildtarget> отвечает за то, что архив исходных - текстов имеется в наличии локально в каталоге - <varname>DISTDIR</varname>. Если цель - <buildtarget>fetch</buildtarget> не может найти требуемые файлы в - каталоге <varname>DISTDIR</varname>, то они будут искаться по - указателю URL <varname>MASTER_SITES</varname>, который - устанавливается в Makefile, а также на наших FTP зеркалах, - куда мы по возможности помещаем дистрибутивные файлы для архива. - Затем она попытается сгрузить указанный файл с помощью - <varname>FETCH</varname>, полагая, что запрашивающая машина имеет - прямое подключение к Интернет. Если файл скачается удачно, то - он будет помещен в каталог <varname>DISTDIR</varname> для - последующего использования и обработки.</para> - </step> - - <step> - <para>Выполняется цель <buildtarget>extract</buildtarget>. Она ищет - дистрибутивный файл порта (как правило, tar-архив - <command>gzip</command>) в - каталоге <varname>DISTDIR</varname> и распаковывает его во - временный каталог, задаваемый переменной - <varname>WRKDIR</varname> (по умолчанию - <filename>work</filename>).</para> - </step> - - <step> - <para>Выполняется цель <buildtarget>patch</buildtarget>. Во-первых, - применяются все патчи, заданные переменной - <varname>PATCHFILES</varname>. Во-вторых, если какие-либо файлы с - патчами, носящие имена - <filename>patch-*</filename>, имеются в - подкаталоге <varname>PATCHDIR</varname> (по умолчанию это каталог - <filename>files</filename>), то они применяются в этот момент в - алфавитном порядке.</para> - </step> - - <step> - <para>Запускается цель <buildtarget>configure</buildtarget>. Здесь - может выполняться любая из многих различных вещей.</para> - - <orderedlist> - <listitem> - <para>Если существует скрипт - <filename>scripts/configure</filename>, то он запускается. - </para> - </listitem> - - <listitem> - <para>Если задана переменная <varname>HAS_CONFIGURE</varname> - или <varname>GNU_CONFIGURE</varname>, то запускается скрипт - <filename>WRKSRC/configure</filename>. - </para> - </listitem> - </orderedlist> - </step> - - <step> - <para>Выполняется цель <buildtarget>build</buildtarget>. Она - отвечает за переход в собственный рабочий каталог порта - (<varname>WRKSRC</varname>) и его построение.</para> - </step> - - <step> - <para>Выполняется цель <buildtarget>stage</buildtarget>. - Конечный набор построенных файлов помещается во временный - каталог (<varname>STAGEDIR</varname>, смотрите - <xref linkend="staging"/>). Иерархия этого - каталога отражает иерархию каталогов системы, в которую - данный пакет будет устанавливаться.</para> - </step> - - <step> - <para>Выполняется цель <buildtarget>install</buildtarget>. - В систему копируются файлы, перечисленные в pkg-plist - порта.</para> - </step> - </procedure> - - <para>Выше перечислены стандартные действия. Кроме того, вы сами - можете определить цели - <buildtarget>pre-<replaceable>что-то</replaceable></buildtarget> или - <buildtarget>post-<replaceable>что-то</replaceable></buildtarget>, - или создать скрипты с такими именами в подкаталоге - <filename>scripts</filename>, и они будут запущены до или после - выполнения действий по умолчанию.</para> - - <para>Например, если у вас есть цель - <buildtarget>post-extract</buildtarget>, определённая в вашем файле - <filename>Makefile</filename> и файл <filename>pre-build</filename> в - подкаталоге - <filename>scripts</filename>, то после выполнения обычных действий по - распаковке, будет вызвана цель <buildtarget>post-extract</buildtarget> - а скрипт <filename>pre-build</filename> будет выполнен перед - запуском стандартных правил построения. Рекомендуется использовать - цели из <filename>Makefile</filename>, если действия достаточно - просты, потому что в дальнейшем будет проще определить, какие - нестандартные действия требует порт.</para> - - <para>Действия по умолчанию выполняются целями - <buildtarget>do-<replaceable>что-то</replaceable></buildtarget> из - <filename>bsd.port.mk</filename>. Например, команды для - распаковки порта находятся в цели - <buildtarget>do-extract</buildtarget>. Если вам не хватает цели по - умолчанию, вы можете ее исправить, переопределив цель - <buildtarget>do-<replaceable>something</replaceable></buildtarget> - в вашем файле <filename>Makefile</filename>.</para> - - <note> - <para><quote>Основные</quote> цели (к примеру, - <buildtarget>extract</buildtarget>, <buildtarget>configure</buildtarget> - и так далее) не делают ничего больше, - чем проверяют успешность завершения всех предыдущих шагов и - вызывают настоящие цели или скрипты, и их не нужно менять. Если - вам нужно изменить распаковку, исправляйте - <buildtarget>do-extract</buildtarget>, но никогда не меняйте способ - работы <buildtarget>extract</buildtarget>! Кроме того, цель - <buildtarget>post-deinstall</buildtarget> является недействительной - и не выполняется инфраструктурой портов.</para> - </note> - - <para>Теперь, когда вы представляете, что происходит, когда - пользователь набирает команду <command>make install</command>, - давайте пройдемся - через шаги, рекомендуемые для создания настоящего порта.</para> - </sect1> - - <sect1 xml:id="slow-sources"> - <title>Получение исходного кода</title> - - <para>Получите оригинальные исходные тексты (обычно) в виде - упакованного tar-архива - (<filename>foo.tar.gz</filename> или - <filename>foo.tar.bz2</filename>) - и скопируйте его в каталог <varname>DISTDIR</varname>. Всегда - используйте исходные тексты <emphasis>основной ветки - разработки</emphasis> везде, где это возможно.</para> - - <para>Вам потребуется задать значение переменной - <varname>MASTER_SITES</varname> так, чтобы оно указывало на - местоположение оригинального tar-архива. В файле - <filename>bsd.sites.mk</filename> вы найдёте краткие обозначения - для большинства популярных сайтов. Пожалуйста, используйте эти - сайты—и соответствующие определения—везде, где это - возможно, чтобы избежать проблем повторения одной и той же информации - в базе источников. Так как эти сайты со временем меняются, для - всех причастных поддержка становится настоящим кошмаром.</para> - - <para>Если вы не можете найти FTP/HTTP сайт с хорошим подключением к - сети, или находите только сайты, которые имеют раздражающе - нестандартные форматы, то можете захотеть поместить копию на надежный - сервер FTP или HTTP, который вам доступен (например, ваша домашняя - страница).</para> - - <para>Если вы не можете найти доступного и надёжного места для - помещения дистрибутивного файла, то мы сами сможем разместить его на - сервере <systemitem>ftp.FreeBSD.org</systemitem>; однако это наименее - рекомендуемое решение. Дистрибутивный файл должен - быть помещён в каталог <filename>~/public_distfiles/</filename> - одного из пользователей машины <systemitem>freefall</systemitem>. Попросите - того, кто коммиттил ваш порт, сделать это. Этот человек также задаст - переменной <varname>MASTER_SITES</varname> значение - <varname>MASTER_SITE_LOCAL</varname>, а в переменной - <varname>MASTER_SITE_SUBDIR</varname> укажет своё имя пользователя - с машины <systemitem>freefall</systemitem>.</para> - - <para>Если дистрибутивные файлы вашего порта постоянно меняются по - неизвестным причинам без изменения версий со стороны автора, остаётся - только поместить дистрибутив на вашу домашнюю Web-страницу и указать - её первой в списке <varname>MASTER_SITES</varname>. Если можете, - попытайтесь договориться с автором порта об этом; это действительно - помогает в достижении некоторого управления исходным кодом. - Размещение собственной версии поможет избежать появления ошибок у - пользователей типа <errorname>checksum mismatch</errorname>, а - также уменьшит нагрузку на людей, сопровождающих наш FTP-сервер. - Также, если у порта имеется только один основной сервер, то - рекомендуется поместить архивную копию на свой сайт и указать его в - списке <varname>MASTER_SITES</varname> вторым.</para> - - <para>Если вашему порту требуются дополнительные `патчи', доступные - в Интернет, скачайте также и их, поместив в каталог - <varname>DISTDIR</varname>. Не волнуйтесь, если они находятся не - на том же сайте, откуда взят дистрибутивный архив, мы умеем - обрабатывать такие ситуации (смотрите описание <link linkend="porting-patchfiles">PATCHFILES</link> ниже).</para> - </sect1> - - <sect1 xml:id="slow-modifying"> - <title>Модификация порта</title> - - <para>Распакуйте копию дистрибутивного файла в отдельный каталог и - внесите изменения, которые необходимы для того, чтобы порт - компилировался нормально в текущей версии &os;. - <emphasis>Тщательно отслеживайте</emphasis> все, что вы делаете, - этот процесс вам предстоит автоматизировать. Все, включая удаление, - добавление или модификацию в файлах должны будут выполняться - автоматически с помощью скриптов или файлов патчей, когда вы - завершите работу над портом.</para> - - <para>Если вашему порту во время компиляции, установки и настройки - требуется довольно много взаимодействовать с пользователем, то - посмотрите на один из классических скриптов - <application>Configure</application> Лэрри Уолла (Larry Wall) и - сделайте сами что-либо подобное. Предназначение новой коллекции - портов - это сделать каждое приложение в стиле - <quote>plug-and-play</quote> настолько, насколько это вообще возможно - для конечного пользователя при минимальном использовании дискового - пространства.</para> - - <note> - <para>Если явно не указано обратное, то патчи, скрипты и другие - файлы, которые вы создали и предоставили для Коллекции Портов - &os;, неявно подпадают под стандартные условия лицензии - BSD.</para> - </note> - </sect1> - - <sect1 xml:id="slow-patch"> - <title>Создание патчей</title> - - <para>Файлы, которые добавлялись или изменялись в процессе создания - порта, могут быть выявлены программой &man.diff.1;, - а результат работы этой программы может быть в дальнейшем передан - программе &man.patch.1;. Такое действие с обычным файлом - подразумевает сохранение копии файла с первоначальным содержимым - перед внесением каких-либо изменений.</para> - - <screen>&prompt.user; <userinput>cp <replaceable>file</replaceable> <replaceable>file</replaceable>.orig</userinput></screen> - - <para>Патчи сохраняются в виде файлов с именем - <filename>patch-*</filename>, где - <replaceable>*</replaceable> обозначает путь к файлу, - к которому применяется патч, такой как - <filename>patch-Imakefile</filename> или - <filename>patch-src-config.h</filename>.</para> - - <para>После того как файл был изменён, используется &man.diff.1; - для получения разницы между первоначальной и изменённой - версиями. Параметр <option>-u</option> указывает &man.diff.1; - выводить разницу в <quote>унифицированном</quote> формате, - который также является предпочтительным.</para> - - <screen>&prompt.user; <userinput>diff -u <replaceable>file</replaceable>.orig <replaceable>file</replaceable> > patch-<replaceable>pathname-file</replaceable></userinput></screen> - - <para>Для порождении патчей для новых добавляемых файлов - используется параметр <option>-N</option>, который заставляет - &man.diff.1; трактовать несуществующие прежде файлы как если - бы они существовали, но имели пустое содержимое:</para> - - <screen>&prompt.user; <userinput>diff -u -N <replaceable>newfile</replaceable>.orig <replaceable>newfile</replaceable> > patch-<replaceable>pathname-newfile</replaceable></userinput></screen> - - <para>Файлы с патчами помещаются в - каталоге <varname>PATCHDIR</varname> - (как правило, это <filename class="directory">files/</filename>), - откуда они будут взяты автоматически. Все патчи обязаны быть сделаны - относительно каталога <varname>WRKSRC</varname> (как правило, - это каталог, в который распаковывается исходный архив и где будет - выполняться построение). Для упрощения внесения изменений и - обновлений избегайте наличия более чем одного патча для - одного и того же файла (например, патчей - <filename>patch-file</filename> и <filename>patch-file2</filename>, - оба меняющих файл <filename>WRKSRC/foobar.c</filename>). - Обратите внимание, что если путь к изменяемому файлу содержит символ - подчеркивания (<literal>_</literal>), то патч должен содержать в своем - имени два подчеркивания вместо одного. Например, для применения патча - на файл с именем <filename>src/freeglut_joystick.c</filename> - соответствующий патч следует назвать - <filename>patch-src-freeglut__joystick.c</filename>.</para> - - <para>Пожалуйста, используйте для именования патчей только символы - <literal>[-+._a-zA-Z0-9]</literal>. Не используйте любые другие - символы, кроме этих. Не называйте патчи как - <filename>patch-aa</filename> или <filename>patch-ab</filename>, - всегда ссылайтесь на путь и название файла в названиях самих - патчей.</para> - - <para>Существует альтернативный упрощённый способ создания - патчей для существующих файлов. Первые шаги те же самые: - создание копии неизменённого файла с расширением - <filename>.orig</filename> и внесение изменений. После этого - используйте <command>make makepatch</command>, чтобы обновить - файлы с патчами в каталоге <filename>files</filename> данного - порта.</para> - - <para>Не помещайте строки RCS в патчи. - <application>Subversion</application> будет изменять их при - помещении файлов в дерево портов, и когда мы будем их оттуда - извлекать, они будут уже другие, поэтому применение патчей - окончится неудачей. Строчки RCS предваряются знаком доллара - (<literal>$</literal>), и обычно начинаются с - <literal>$Id</literal> или - <literal>$RCS</literal>.</para> - - <para>Использование параметра рекурсии (<option>-r</option>) с командой - &man.diff.1; для генерации патчей - это хорошо, но всё же, - пожалуйста, смотрите на получающиеся патчи, чтобы убедиться в - отсутствии ненужного мусора. В частности, diff-разниц между двумя - резервными копиями файлов, файлы <filename>Makefile</filename>, когда - как порт использует <command>Imake</command> или - GNU-версию программы <command>configure</command>, и так далее, - не нужны, и должны быть удалены. Если было необходимо - отредактировать файл <filename>configure.in</filename> и - запустить <command>autoconf</command> для перегенерации - <command>configure</command>, не нужно включать файлы diff для - <command>configure</command> (они частенько вырастают до нескольких - тысяч строк!). Вместо этого задайте - <literal>USE_AUTOTOOLS=autoconf:261</literal> и - включите diff-файл для <filename>configure.in</filename>.</para> - - <para>Старайтесь минимизировать в патчах объём - нефункциональных изменений с пустыми символами. В мире Открытого - Исходного Кода является распространенным совместное использование - проектами больших объемов кодовой базы, но с различными стилями - и правилами отступов. При копировании работающей функциональной - части из одного проекта для исправления похожей области в другом, - будьте аккуратны, пожалуйста: получаемый однострочный патч - может указаться полон нефункциональных изменений. Это не только - увеличивает размер репозитория <application>Subversion</application>, - но также усложняет поиск того, - что конкретно вызвало проблему и что вообще поменялось.</para> - - <para>Если нужно удалить файл, сделайте это при выполнении цели - <buildtarget>post-extract</buildtarget>, вместо того чтобы - оформлять это как часть патча.</para> - - <para>Простые перемещения могут быть выполнены непосредственно из - <filename>Makefile</filename> порта с использованием &man.sed.1; в - режиме in-place. Это удобно, когда при изменении используется - значение переменной:</para> - - <programlisting>post-patch: - @${REINPLACE_CMD} -e 's|for Linux|for FreeBSD|g' ${WRKSRC}/README</programlisting> - - <para>Довольно часто в исходных файлах портируемого программного - обеспечения используется конвенция CR/LF. Это может стать - причиной проблем с дальнейшей упаковкой, предупреждениями - компилятора или выполнением скриптов (таких как - <literal>/bin/sh^M not found</literal>). Для быстрого - преобразования всех файлов из CR/LF просто в LF добавьте - в <filename>Makefile</filename> порта эту запись:</para> - - <programlisting>USES= dos2unix</programlisting> - - <para>Может быть задан точный список преобразуемых файлов:</para> - - <programlisting>USES= dos2unix -DOS2UNIX_FILES= util.c util.h</programlisting> - - <para>Используйте <varname>DOS2UNIX_REGEX</varname>, чтобы - преобразовать группу файлов в разных подкаталогах. - Его параметром является регулярное выражение, совместимое с - &man.find.1;. Подробнее о формате в &man.re.format.7;. - Такой вариант удобен для преобразования всех файлов заданного - расширения. Для примера, преобразуем все исходные файлы, - не затрагивая двоичные файлы:</para> - *** DIFF OUTPUT TRUNCATED AT 1000 LINES ***
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201402221230.s1MCUB3Z037858>