From owner-svn-doc-all@FreeBSD.ORG Sat Feb 22 12:30:12 2014 Return-Path: Delivered-To: svn-doc-all@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) (using TLSv1 with cipher ADH-AES256-SHA (256/256 bits)) (No client certificate requested) by hub.freebsd.org (Postfix) with ESMTPS id 158D5EA6; Sat, 22 Feb 2014 12:30:12 +0000 (UTC) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:1900:2254:2068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mx1.freebsd.org (Postfix) with ESMTPS id F04B812CE; Sat, 22 Feb 2014 12:30:11 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.8/8.14.8) with ESMTP id s1MCUB0D037864; Sat, 22 Feb 2014 12:30:11 GMT (envelope-from pluknet@svn.freebsd.org) Received: (from pluknet@localhost) by svn.freebsd.org (8.14.8/8.14.8/Submit) id s1MCUB3Z037858; Sat, 22 Feb 2014 12:30:11 GMT (envelope-from pluknet@svn.freebsd.org) Message-Id: <201402221230.s1MCUB3Z037858@svn.freebsd.org> From: Sergey Kandaurov Date: Sat, 22 Feb 2014 12:30:11 +0000 (UTC) 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... X-SVN-Group: doc-head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-doc-all@freebsd.org X-Mailman-Version: 2.1.17 Precedence: list List-Id: "SVN commit messages for the entire doc trees \(except for " user" , " projects" , and " translations" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sat, 22 Feb 2014 12:30:12 -0000 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 @@ + + + + + + Приложения + + + Значения <varname>USES</varname> + + + Значения <varname>USES</varname> + + + + + Наименование + Аргументы + Описание + + + + &values.uses; + + +
+ + + + Значения <literal>__FreeBSD_version</literal> + + Ниже для справки приводится перечень значений + __FreeBSD_version в виде, который определён в + sys/param.h: + + + Значения <literal>__FreeBSD_version</literal> + + + + + Значение + Дата + Релиз + + + + + &values.versions; + + +
+ + + Заметьте, что 2.2-STABLE иногда идентифицирует себя как + 2.2.5-STABLE после 2.2.5-RELEASE. Такой принцип + использовался год и месяц, но мы решили изменить его на более + однозначную систему нумерации старший/младший, начиная с версии + 2.2. Это объясняется тем, что параллельная разработка в нескольких + ветках делает непрактичным идентификацию релизов просто по их + реальным датам выпуска. Если вы сейчас делаете порт, вам не стоит + заботиться о старых версиях -CURRENT; они перечислены здесь просто + в информационных целях. + + + + 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" [ -]> + + +%chapters; +]> + @@ -59,12671 +63,19 @@ $FreeBSD$ - - Введение - - Коллекция портов &os; является способом, используемым - практически каждым для установки приложений ("портов") на &os;. - Как и почти всё остальное во &os;, эта система в основном является - добровольно поддерживаемым начинанием. Важно иметь это в виду при - чтении данного документа. - - Во &os; каждый может прислать новый порт либо изъявить желание - поддерживать существующий порт, если его никто ещё никто не - поддерживает—вам не нужно иметь никаких особых привилегий на - внесение изменений, чтобы это делать. - - - - Как самому сделать новый порт - - Итак, вы интересуетесь, как создать собственный порт или - обновить существующий? Великолепно! - - Ниже находятся некоторые указания по созданию нового порта для - &os;. Если вы хотите обновить существующий порт, вы должны - прочесть их, а затем . - - Если этот документ недостаточно подробен, вы должны обратиться к - файлу /usr/ports/Mk/bsd.port.mk, который - включается в make-файл каждого порта. Он хорошо прокомментирован, и - даже если вы не занимаетесь хакингом make-файлов каждодневно, из него - вы сможете узнать много нового. Кроме того, конкретные вопросы можно - задать, послав письмо на адрес &a.ports;. - - - Только часть переменных - (VAR), которые могут быть - переопределены, описаны в этом документе. Большинство (если не все) - описаны в начале файла /usr/ports/Mk/bsd.port.mk; - остальные, скорее всего, тоже там описаны. Заметьте, что - в этом файле используется нестандартная настройка шага табуляции: - Emacs и Vim - должны распознать это при загрузке файла. Как &man.vi.1;, - так и &man.ex.1; могут быть настроены на использование - правильного значения выдачей команды :set tabstop=4 - после загрузки файла. - - - - Ищете, с чего бы начать попроще? Посмотрите на перечень запрошенных - портов, есть ли там такие, над которыми вы можете работать. - - - - - Быстрое портирование - - В этом разделе описано, как создать новый порт на скорую руку. - Во многих случаях этого бывает не достаточно, так что вам нужно будет - прочитать документ дальше. - - Во-первых, скачайте оригинальный tar-файл и поместите его в каталог - DISTDIR, который по умолчанию есть не что иное, как - /usr/ports/distfiles. - - - Здесь предполагается, что программное обеспечение компилируется - без проблем как есть, то есть для работы приложения на вашей системе - &os; не потребовалось абсолютно никаких изменений. Если - требовалось что-то изменить, то вам придется обратиться также и к - следующему разделу. - - - - Перед началом портирования рекомендуется установить - переменную &man.make.1; DEVELOPER в - /etc/make.conf. - - &prompt.root; echo DEVELOPER=yes >> /etc/make.conf - - Эта настройка включает режим разработчика, - в котором отображаются предупреждения при использовании - устаревших конструкций и задействуются некоторые дополнительные - проверки при вызове команды make. - - - - Создание файла <filename>Makefile</filename> - - Минимальный Makefile будет выглядеть - примерно так: - - # $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> - - - В некоторых случаях в заголовке Makefile - существующего порта могут содержаться дополнительные строки, - такие как название порта и дата его создания. - Эта дополнительная информация была объявлена устаревшей - и находится в процессе удаления. - - - Посмотрим, сможете ли вы его понять. Не обращайте внимание на - содержимое строчки $FreeBSD$, она - будет заполнена автоматически системой - Subversion, когда порт будет - импортирован в наше дерево портов. Вы можете найти более подробный - пример в разделе пример - Makefile. - - - - Создание информационных файлов - - Имеется два информационных файла, которые требуются для любого - порта, вне зависимости от того, является ли он пакетом или нет. Это - pkg-descr и pkg-plist. - Префикс pkg- отличает их от других файлов. - - - <filename>pkg-descr</filename> - - Это более подробное краткое описание порта. От одного до - нескольких абзацев, кратко описывающих, что представляет собой - порт, будет достаточно. - - - Это не руководство и не подробнейшее - описание того, как использовать или компилировать порт! - Пожалуйста, будьте внимательны при копировании текста - из README или страниц - справочника; слишком часто они не являются кратким - описанием порта или имеют неудобный формат (например, страницы - справочника выровнены пробелами, что особенно плохо - смотрится с моноширинными шрифтами). - - - Хорошо составленный pkg-descr - описывает порт достаточно полно, чтобы пользователю не - приходилось сверяться с документацией или посещать вебсайт - для понимания того, что делает данное программное обеспечение, - чем оно может быть полезно или какие хорошие функции у него - имеются. Упоминание про определённые требования, такие как - используемый графический инструментарий, тяжёлые зависимости, - окружение для запуска или используемый язык программирования - помогут пользователям определиться, будет ли этот порт для - них работать. - - Включите сюда URL официальной домашней страницы Интернет. - Перед одним из сайтов (выберите основной) - добавьте WWW: (с последующим единичным - пробелом) для того, чтобы вспомогательные утилиты работали - правильно. Если URI является корнем сайта или каталогом, - то значение должно быть дополнено косой чертой. - - - Если указанная для порта веб-страница не доступна, - попытайтесь сперва поискать, был ли официальный сайт - перемещён, переименован или размещён в другом месте. - - - Следующий пример показывает, как должен выглядеть ваш - pkg-descr: - - This is a port of oneko, in which a cat chases a poor mouse all over -the screen. - : -(etc.) - -WWW: http://www.oneko.org/ - - - - <filename>pkg-plist</filename> - - Здесь перечисляются все файлы, устанавливаемые портом. Его - также называют списком для упаковки, потому что - пакет генерируется упаковкой файлов, которые здесь указаны. - Имена путей указываются относительно установочного префикса - (обычно /usr/local). - Если порт во время установки создает каталоги, убедитесь, - что добавлены строки @dirrm для удаления - каталогов при удалении пакета. - - Вот маленький пример: - - bin/oneko -man/man1/oneko.1.gz -lib/X11/app-defaults/Oneko -lib/X11/oneko/cat1.xpm -lib/X11/oneko/cat2.xpm -lib/X11/oneko/mouse.xpm -@dirrm lib/X11/oneko - - Обратитесь к странице справочной системы по команде - &man.pkg-create.8; с подробным описанием формата списка - упаковки. - - - Рекомендуется, чтобы имена файлов в этом списке были - отсортированы в алфавитном порядке. Это позволит значительно - облегчить сверку изменений при обновлении порта. - - - - Создание списка упаковки вручную может оказаться весьма - трудоёмкой задачей. Если порт устанавливает большое количество - файлов, раздел об автоматическом построении списка - упаковки может помочь сэкономить время. - - - Существует только одно исключение, когда у порта может - отсутствовать pkg-plist. Если порт - устанавливает лишь несколько файлов, а возможно, и каталогов, то - они могут быть перечислены в переменных - PLIST_FILES и PLIST_DIRS, - соответственно, внутри файла Makefile порта. - К примеру, мы можем обойтись без файла - pkg-plist у приведённого выше порта - oneko, добавив следующие строки в - Makefile: - - PLIST_FILES= bin/oneko \ - man/man1/oneko.1.gz \ - lib/X11/app-defaults/Oneko \ - lib/X11/oneko/cat1.xpm \ - lib/X11/oneko/cat2.xpm \ - lib/X11/oneko/mouse.xpm -PLIST_DIRS= lib/X11/oneko - - Конечно, переменная PLIST_DIRS не должна - задаваться, если порт не устанавливает никаких каталогов. - - - Несколько портов могут совместно использовать общий - каталог. В этом случае PLIST_DIRS - следует заменить на PLIST_DIRSTRY, так - чтобы каталог удалялся только если он пуст, а иначе - игнорировался. Использование PLIST_DIRS - и PLIST_DIRSTRY аналогично - @dirrm и @dirrmtry - в pkg-plist, описание которых - входит в . - - - Обратной стороной такого способа перечисления файлов и - каталогов порта является невозможность использования - последовательностей команд, описанных в &man.pkg-create.8;. - Поэтому он подходит для простых портов, что делает их ещё более - простыми. Одновременно с этим положительным моментом является - уменьшение количества файлов в коллекции портов. Пожалуйста, - подумайте над использованием этой техники, прежде чем создавать - pkg-plist. - - Далее мы увидим, как можно использовать файлы - pkg-plist и PLIST_FILES - выполнения более сложных - задач. - - - - - Создание файла с контрольной суммой - - Просто введите команду make makesum. - Правила утилиты make автоматически сгенерируют файл - distinfo. - - Если у извлекаемого файла регулярно меняется контрольная - сумма и вы не сомневаетесь в надежности источника (т.е. он получен - из CD производителя, либо ежедневно обновляется документация), то вы - должны указать эти файлы в переменной IGNOREFILES. - Тогда контрольная сумма при выполнении make makesum - для этого файла создаваться не будет, а вместо этого для него будет - установлено значение IGNORE. - - - - Тестирование порта - - Вы должны удостовериться, что правила построения порта выполняют - именно то, что вы хотите, включая создание пакета для порта. Вот - те важные вещи, которые вы должны проверить. - - - - pkg-plist не содержит ничего сверх того, - что устанавливается портом - - - - pkg-plist содержит абсолютно все, что - устанавливается портом - - - - Порт может быть установлен с помощью - указания цели install. Это - позволяет убедиться в правильной работе сценария - установки. - - - - Порт может быть правильным образом удалён с помощью - указания цели deinstall. Это - позволяет убедиться в правильной работе сценария - удаления. - - - - Следует убедиться, что make package - можно запустить из-под обычного пользователя (то есть, - не из-под root). - Если это не так, в Makefile порта - должно быть добавлено NEED_ROOT=yes. - - - - - Рекомендуемый порядок проверки - - - make stage - - - - make check-orphans - - - - make package - - - - make install - - - - make deinstall - - - - pkg add package-filename - - - - make package (из-под - пользователя) - - - - Убедитесь, что на любом из этапов не выдается никаких - предупреждений. - - Основательное автоматизированное тестирование может быть - выполнено при помощи - ports-mgmt/tinderbox или - ports-mgmt/poudriere из Коллекции - Портов. Эти приложения используют jails, - в которых проверяются все перечисленные выше этапы без - изменения состояния основной системы. - - - - Проверка вашего порта утилитой - <command>portlint</command> - - Будьте добры, пользуйтесь утилитой portlint - для проверки того, что ваш порт соответствует нашим рекомендациям. - Программа ports-mgmt/portlint - является частью Коллекции - Портов. В частности, вы можете захотеть проверить, правильно ли - сформирован файл Makefile и - соответствующим ли образом именован пакет. - - - - Посылка нового порта - - Перед посылкой нового порта прочитайте раздел о том, что - можно и нельзя делать. - - Когда вы наконец довольны своим первым портом, единственное, - что осталось сделать, это включить его в основное дерево портов - &os; и осчастливить этим всех остальных. Нам не нужен ни - каталог work, ни пакет - pkgname.tgz, так что удалите их прямо - сейчас. - - Затем получите файл &man.shar.1;. Предполагая, что порт - называется oneko, перейдите в каталог выше, где находится - каталог oneko, и наберите: - shar `find oneko` > oneko.shar - - Включите oneko.shar в сообщение об - ошибке и пошлите его с помощью &man.send-pr.1;. Обратитесь к - разделу - Сообщения об ошибках и общие замечания для получения - подробной информации о &man.send-pr.1;). - - Укажите в сообщении категорию ports и - класс change-request. - Не указывайте, что сообщение имеет статус - confidential! Добавьте краткое описание - программы в поле Description отправляемого PR - (например, содержимое COMMENT в сокращённом - варианте) и сам файл в виде архива .shar - в поле Fix. - - - Хорошее описание в заголовке сообщения о проблеме - значительно облегчает работу коммиттеров портов. Для новых - портов мы предпочитаем нечто вроде New port: - <категория>/<название порта> <краткое - описание порта>. Следование этой схеме - упрощает и ускоряет начало работы по добавлению нового - порта. - - - Повторим ещё раз, что не нужно включать ни оригинальный - файл с дистрибутивом, ни каталог work, - ни пакет, построенный вами командой - make package; для новых портов - используйте &man.shar.1;, но не &man.diff.1;. - - После отправки порта, пожалуйста, потерпите. Время, - необходимое для включения нового порта во &os;, может занимать - от нескольких дней до нескольких месяцев. - Здесь можно увидеть список ожидающих PR для портов. - - После рассмотрения нового порта мы при необходимости вам - ответим, а затем включим порт в наше дерево. Ваше имя также - будет добавлено в список - Дополнительных контрибуторов проекта &os; и другие - файлы. - - - - - Медленное портирование - - Итак, все оказалось не так уж и просто, и порт потребовал - некоторых модификаций для того, чтобы заставить его работать. В этом - разделе мы расскажем, шаг за шагом, как его модифицировать, чтобы он - работал с нашей системой портов. - - - Как всё это работает - - Во-первых, когда пользователь дает в своем каталоге с портом - команду make, происходит целая череда событий. - Во время чтения этого текста может оказаться полезным иметь файл - bsd.port.mk открытым в другом окне, что сильно - поможет в их понимании. - - Но не волнуйтесь сильно, если вы не до конца понимаете, что - делается в bsd.port.mk, не так уж много людей - его понимает... :-> - - - - Запускается цель fetch. Цель - fetch отвечает за то, что архив исходных - текстов имеется в наличии локально в каталоге - DISTDIR. Если цель - fetch не может найти требуемые файлы в - каталоге DISTDIR, то они будут искаться по - указателю URL MASTER_SITES, который - устанавливается в Makefile, а также на наших FTP зеркалах, - куда мы по возможности помещаем дистрибутивные файлы для архива. - Затем она попытается сгрузить указанный файл с помощью - FETCH, полагая, что запрашивающая машина имеет - прямое подключение к Интернет. Если файл скачается удачно, то - он будет помещен в каталог DISTDIR для - последующего использования и обработки. - - - - Выполняется цель extract. Она ищет - дистрибутивный файл порта (как правило, tar-архив - gzip) в - каталоге DISTDIR и распаковывает его во - временный каталог, задаваемый переменной - WRKDIR (по умолчанию - work). - - - - Выполняется цель patch. Во-первых, - применяются все патчи, заданные переменной - PATCHFILES. Во-вторых, если какие-либо файлы с - патчами, носящие имена - patch-*, имеются в - подкаталоге PATCHDIR (по умолчанию это каталог - files), то они применяются в этот момент в - алфавитном порядке. - - - - Запускается цель configure. Здесь - может выполняться любая из многих различных вещей. - - - - Если существует скрипт - scripts/configure, то он запускается. - - - - - Если задана переменная HAS_CONFIGURE - или GNU_CONFIGURE, то запускается скрипт - WRKSRC/configure. - - - - - - - Выполняется цель build. Она - отвечает за переход в собственный рабочий каталог порта - (WRKSRC) и его построение. - - - - Выполняется цель stage. - Конечный набор построенных файлов помещается во временный - каталог (STAGEDIR, смотрите - ). Иерархия этого - каталога отражает иерархию каталогов системы, в которую - данный пакет будет устанавливаться. - - - - Выполняется цель install. - В систему копируются файлы, перечисленные в pkg-plist - порта. - - - - Выше перечислены стандартные действия. Кроме того, вы сами - можете определить цели - pre-что-то или - post-что-то, - или создать скрипты с такими именами в подкаталоге - scripts, и они будут запущены до или после - выполнения действий по умолчанию. - - Например, если у вас есть цель - post-extract, определённая в вашем файле - Makefile и файл pre-build в - подкаталоге - scripts, то после выполнения обычных действий по - распаковке, будет вызвана цель post-extract - а скрипт pre-build будет выполнен перед - запуском стандартных правил построения. Рекомендуется использовать - цели из Makefile, если действия достаточно - просты, потому что в дальнейшем будет проще определить, какие - нестандартные действия требует порт. - - Действия по умолчанию выполняются целями - do-что-то из - bsd.port.mk. Например, команды для - распаковки порта находятся в цели - do-extract. Если вам не хватает цели по - умолчанию, вы можете ее исправить, переопределив цель - do-something - в вашем файле Makefile. - - - Основные цели (к примеру, - extract, configure - и так далее) не делают ничего больше, - чем проверяют успешность завершения всех предыдущих шагов и - вызывают настоящие цели или скрипты, и их не нужно менять. Если - вам нужно изменить распаковку, исправляйте - do-extract, но никогда не меняйте способ - работы extract! Кроме того, цель - post-deinstall является недействительной - и не выполняется инфраструктурой портов. - - - Теперь, когда вы представляете, что происходит, когда - пользователь набирает команду make install, - давайте пройдемся - через шаги, рекомендуемые для создания настоящего порта. - - - - Получение исходного кода - - Получите оригинальные исходные тексты (обычно) в виде - упакованного tar-архива - (foo.tar.gz или - foo.tar.bz2) - и скопируйте его в каталог DISTDIR. Всегда - используйте исходные тексты основной ветки - разработки везде, где это возможно. - - Вам потребуется задать значение переменной - MASTER_SITES так, чтобы оно указывало на - местоположение оригинального tar-архива. В файле - bsd.sites.mk вы найдёте краткие обозначения - для большинства популярных сайтов. Пожалуйста, используйте эти - сайты—и соответствующие определения—везде, где это - возможно, чтобы избежать проблем повторения одной и той же информации - в базе источников. Так как эти сайты со временем меняются, для - всех причастных поддержка становится настоящим кошмаром. - - Если вы не можете найти FTP/HTTP сайт с хорошим подключением к - сети, или находите только сайты, которые имеют раздражающе - нестандартные форматы, то можете захотеть поместить копию на надежный - сервер FTP или HTTP, который вам доступен (например, ваша домашняя - страница). - - Если вы не можете найти доступного и надёжного места для - помещения дистрибутивного файла, то мы сами сможем разместить его на - сервере ftp.FreeBSD.org; однако это наименее - рекомендуемое решение. Дистрибутивный файл должен - быть помещён в каталог ~/public_distfiles/ - одного из пользователей машины freefall. Попросите - того, кто коммиттил ваш порт, сделать это. Этот человек также задаст - переменной MASTER_SITES значение - MASTER_SITE_LOCAL, а в переменной - MASTER_SITE_SUBDIR укажет своё имя пользователя - с машины freefall. - - Если дистрибутивные файлы вашего порта постоянно меняются по - неизвестным причинам без изменения версий со стороны автора, остаётся - только поместить дистрибутив на вашу домашнюю Web-страницу и указать - её первой в списке MASTER_SITES. Если можете, - попытайтесь договориться с автором порта об этом; это действительно - помогает в достижении некоторого управления исходным кодом. - Размещение собственной версии поможет избежать появления ошибок у - пользователей типа checksum mismatch, а - также уменьшит нагрузку на людей, сопровождающих наш FTP-сервер. - Также, если у порта имеется только один основной сервер, то - рекомендуется поместить архивную копию на свой сайт и указать его в - списке MASTER_SITES вторым. - - Если вашему порту требуются дополнительные `патчи', доступные - в Интернет, скачайте также и их, поместив в каталог - DISTDIR. Не волнуйтесь, если они находятся не - на том же сайте, откуда взят дистрибутивный архив, мы умеем - обрабатывать такие ситуации (смотрите описание PATCHFILES ниже). - - - - Модификация порта - - Распакуйте копию дистрибутивного файла в отдельный каталог и - внесите изменения, которые необходимы для того, чтобы порт - компилировался нормально в текущей версии &os;. - Тщательно отслеживайте все, что вы делаете, - этот процесс вам предстоит автоматизировать. Все, включая удаление, - добавление или модификацию в файлах должны будут выполняться - автоматически с помощью скриптов или файлов патчей, когда вы - завершите работу над портом. - - Если вашему порту во время компиляции, установки и настройки - требуется довольно много взаимодействовать с пользователем, то - посмотрите на один из классических скриптов - Configure Лэрри Уолла (Larry Wall) и - сделайте сами что-либо подобное. Предназначение новой коллекции - портов - это сделать каждое приложение в стиле - plug-and-play настолько, насколько это вообще возможно - для конечного пользователя при минимальном использовании дискового - пространства. - - - Если явно не указано обратное, то патчи, скрипты и другие - файлы, которые вы создали и предоставили для Коллекции Портов - &os;, неявно подпадают под стандартные условия лицензии - BSD. - - - - - Создание патчей - - Файлы, которые добавлялись или изменялись в процессе создания - порта, могут быть выявлены программой &man.diff.1;, - а результат работы этой программы может быть в дальнейшем передан - программе &man.patch.1;. Такое действие с обычным файлом - подразумевает сохранение копии файла с первоначальным содержимым - перед внесением каких-либо изменений. - - &prompt.user; cp file file.orig - - Патчи сохраняются в виде файлов с именем - patch-*, где - * обозначает путь к файлу, - к которому применяется патч, такой как - patch-Imakefile или - patch-src-config.h. - - После того как файл был изменён, используется &man.diff.1; - для получения разницы между первоначальной и изменённой - версиями. Параметр указывает &man.diff.1; - выводить разницу в унифицированном формате, - который также является предпочтительным. - - &prompt.user; diff -u file.orig file > patch-pathname-file - - Для порождении патчей для новых добавляемых файлов - используется параметр , который заставляет - &man.diff.1; трактовать несуществующие прежде файлы как если - бы они существовали, но имели пустое содержимое: - - &prompt.user; diff -u -N newfile.orig newfile > patch-pathname-newfile - - Файлы с патчами помещаются в - каталоге PATCHDIR - (как правило, это files/), - откуда они будут взяты автоматически. Все патчи обязаны быть сделаны - относительно каталога WRKSRC (как правило, - это каталог, в который распаковывается исходный архив и где будет - выполняться построение). Для упрощения внесения изменений и - обновлений избегайте наличия более чем одного патча для - одного и того же файла (например, патчей - patch-file и patch-file2, - оба меняющих файл WRKSRC/foobar.c). - Обратите внимание, что если путь к изменяемому файлу содержит символ - подчеркивания (_), то патч должен содержать в своем - имени два подчеркивания вместо одного. Например, для применения патча - на файл с именем src/freeglut_joystick.c - соответствующий патч следует назвать - patch-src-freeglut__joystick.c. - - Пожалуйста, используйте для именования патчей только символы - [-+._a-zA-Z0-9]. Не используйте любые другие - символы, кроме этих. Не называйте патчи как - patch-aa или patch-ab, - всегда ссылайтесь на путь и название файла в названиях самих - патчей. - - Существует альтернативный упрощённый способ создания - патчей для существующих файлов. Первые шаги те же самые: - создание копии неизменённого файла с расширением - .orig и внесение изменений. После этого - используйте make makepatch, чтобы обновить - файлы с патчами в каталоге files данного - порта. - - Не помещайте строки RCS в патчи. - Subversion будет изменять их при - помещении файлов в дерево портов, и когда мы будем их оттуда - извлекать, они будут уже другие, поэтому применение патчей - окончится неудачей. Строчки RCS предваряются знаком доллара - ($), и обычно начинаются с - $Id или - $RCS. - - Использование параметра рекурсии () с командой - &man.diff.1; для генерации патчей - это хорошо, но всё же, - пожалуйста, смотрите на получающиеся патчи, чтобы убедиться в - отсутствии ненужного мусора. В частности, diff-разниц между двумя - резервными копиями файлов, файлы Makefile, когда - как порт использует Imake или - GNU-версию программы configure, и так далее, - не нужны, и должны быть удалены. Если было необходимо - отредактировать файл configure.in и - запустить autoconf для перегенерации - configure, не нужно включать файлы diff для - configure (они частенько вырастают до нескольких - тысяч строк!). Вместо этого задайте - USE_AUTOTOOLS=autoconf:261 и - включите diff-файл для configure.in. - - Старайтесь минимизировать в патчах объём - нефункциональных изменений с пустыми символами. В мире Открытого - Исходного Кода является распространенным совместное использование - проектами больших объемов кодовой базы, но с различными стилями - и правилами отступов. При копировании работающей функциональной - части из одного проекта для исправления похожей области в другом, - будьте аккуратны, пожалуйста: получаемый однострочный патч - может указаться полон нефункциональных изменений. Это не только - увеличивает размер репозитория Subversion, - но также усложняет поиск того, - что конкретно вызвало проблему и что вообще поменялось. - - Если нужно удалить файл, сделайте это при выполнении цели - post-extract, вместо того чтобы - оформлять это как часть патча. - - Простые перемещения могут быть выполнены непосредственно из - Makefile порта с использованием &man.sed.1; в - режиме in-place. Это удобно, когда при изменении используется - значение переменной: - - post-patch: - @${REINPLACE_CMD} -e 's|for Linux|for FreeBSD|g' ${WRKSRC}/README - - Довольно часто в исходных файлах портируемого программного - обеспечения используется конвенция CR/LF. Это может стать - причиной проблем с дальнейшей упаковкой, предупреждениями - компилятора или выполнением скриптов (таких как - /bin/sh^M not found). Для быстрого - преобразования всех файлов из CR/LF просто в LF добавьте - в Makefile порта эту запись: - - USES= dos2unix - - Может быть задан точный список преобразуемых файлов: - - USES= dos2unix -DOS2UNIX_FILES= util.c util.h - - Используйте DOS2UNIX_REGEX, чтобы - преобразовать группу файлов в разных подкаталогах. - Его параметром является регулярное выражение, совместимое с - &man.find.1;. Подробнее о формате в &man.re.format.7;. - Такой вариант удобен для преобразования всех файлов заданного - расширения. Для примера, преобразуем все исходные файлы, - не затрагивая двоичные файлы: - *** DIFF OUTPUT TRUNCATED AT 1000 LINES ***