Глава 12. Что делать нужно, и что делать нельзя

Вот список часто встречающихся действий, которые нужно и которые нельзя делать во время процесса портирования. Проверьте порт по этому списку, и также проверьте порты в базе сообщений PR, которые присланы другими людьми. Присылайте любые комментарии о портах, которые вы проверили, так, как это описано в статье о Сообщениях об ошибках и общих замечаниях. Проверка портов в базе сообщений PR позволит нам быстрее коммиттить их и удостовериться, что вы знаете, что делаете.

Не пишите ничего в файлы вне каталога WRKDIR. Каталог WRKDIR является единственным местом, которое гарантированно будет доступно для записи во время построения порта (обратитесь к главе об установке портов с CDROM за примером построения портов из дерева, доступного только для чтения). Если вам нужно изменить какой-либо из файлов pkg-*, сделайте это, переопределив переменную, но не перезаписывая их.

Добейтесь того, чтобы ваш порт принимал во внимание значение переменной WRKDIRPREFIX. Большинство портов об этом не заботятся. В частности, если вы обращаетесь к каталогу WRKDIR другого порта, заметьте, что его правильным местоположением является WRKDIRPREFIXPORTSDIR/subdir/name/work, а не PORTSDIR/subdir/work или .CURDIR/../../subdir/name/work мли что-то подобное.

Кроме того, если вы сами задаете WRKDIR, то должны поставить перед ним знак ${WRKDIRPREFIX}${.CURDIR}.

Вы можете встретиться с кодом, который требует модификаций или условной компиляции в зависимости от того, с какой версией FreeBSD Unix он работает. Предпочтительным способом отделения кода для версий FreeBSD является использование макросов __FreeBSD_version и __FreeBSD__, определённых в sys/param.h. Если этот файл не подключен, добавьте код

в нужном месте файла .c.

__FreeBSD__ определён во всех версиях FreeBSD в качестве старшего номера версии системы. Например, в FreeBSD 9.x __FreeBSD__ определён со значением 9.

Не пишите ничего после строки .include <bsd.port.mk>. Этой строки можно избежать, включив в где-то в середину вашего файла Makefile файл bsd.port.pre.mk, и файл bsd.port.post.mk в конец.

В файле bsd.port.pre.mk определяются лишь несколько переменных, которые могут быть использованы в тестах из файла Makefile, в файле bsd.port.post.mk заданы остальные.

Вот некоторые важные переменные, определенные в файле bsd.port.pre.mk (это не полный список, для выяснения полного списка прочтите, пожалуйста, сам файл bsd.port.mk).

Вот несколько примеров того, что вы можете написать после bsd.port.pre.mk:

Вы не забываете об использовании табуляции вместо пробелов после BROKEN=:-).

Если порт устанавливает сценарий на языке shell, который служит для запуска другой программы, и если запуск этой программы является последним действием сценария, убедитесь, что запуск программы производится с использованием выражения exec, например:

Выражение exec заменяет процесс сценария на указанную программу. Если exec опущен, то процесс сценария во время работы программы остается в памяти, бесполезно потребляя системные ресурсы.

Файл Makefile должен выполнять действия просто и небеспричинно. Если вы можете сделать что-то на несколько строк короче или более читабельно, сделайте это. В качестве примеров можно привести использование конструкций .if утилиты make вместо соответствующей конструкции if командного процессора, ненужность переопределения цели do-extract при возможности переопределения EXTRACT* и использование GNU_CONFIGURE вместо CONFIGURE_ARGS += --prefix=${PREFIX}.

Если вы обнаружите, что для выполнения чего-то приходится писать много нового кода, то, пожалуйста, просмотрите файл bsd.port.mk на предмет того, не содержит ли он решение именно вашей проблемы. Хотя его трудно читать, имеется много проблем, выглядящих сложными, для которых файл bsd.port.mk уже содержит быстрое решение.

Порт должен принимать во внимание как переменную CC, так и CXX. Под этим мы подразумеваем, что порт ни в коем случае не должен устанавливать значения этих переменных, переопределяя имеющиеся значения; вместо этого можно добавлять нужные значения к уже имеющимся. Это связано с тем, что параметры построения, относящиеся ко всем портам, могут быть заданы глобально.

Если порты не учитывают значения этих переменных, добавьте строку NO_PACKAGE=ignores either cc or cxx в файл Makefile.

Далее следует пример файла Makefile, использующего как переменную CC, так и CXX. Обратите внимание на использование символов ?=:

Вот пример, в котором не принимаются во внимание ни CC, ни CXX:

В системах FreeBSD обе переменные CC и CXX могут быть определены в файле /etc/make.conf. В первом примере задаётся значение, если оно ранее не было определено в /etc/make.conf, что сохраняет любые определения, данные на уровне системы в целом. Второй пример переопределяет всё, что было задано ранее.

Порт должен учитывать переменную CFLAGS. Под этим мы подразумеваем, что порт ни в коем случае не должен устанавливать значения этой переменной, переопределяя имеющиеся значения; вместо этого можно добавлять нужные значения к уже имеющимся. Это связано с тем, что параметры построения, относящиеся ко всем портам, могут быть заданы глобально.

Если порты не учитывают значения этой переменной, добавьте строку NO_PACKAGE=ignores cflags в файл Makefile.

Далее следует пример файла Makefile, использующего переменную CFLAGS. Обратите внимание на использование символов +=:

А вот пример, в котором не учитывается значение переменной CFLAGS:

В системе FreeBSD переменная CFLAGS определена в файле /etc/make.conf. В первом примере к переменной CFLAGS добавляются дополнительные флаги, при этом сохраняются все определения, данные ранее на уровне системы. Во втором примере всё, что было задано ранее, игнорируется.

Из сторонних файлов Makefile следует удалить флаги оптимизации. Общесистемные флаги оптимизации находятся в системной переменной CFLAGS. Пример из немодифицированного Makefile:

При использовании системных флагов оптимизации Makefile станет похожим на следующий пример:

Во FreeBSD библиотека потоков обязана быть скомпонована с исполняемыми файлами с использованием специального флага -pthread. Если порт настаивает на прямой компоновке с -lpthread, создайте патч для использования -pthread.

Посылайте подходящие изменения/патчи автору/сопровождающему для включения в следующий релиз. Это только сделает вашу работу гораздо легче при выходе следующего релиза.

README.html не является частью порта и генерируется при помощи make readme. Не включайте этот файл в патчи или коммиты.

В некоторых случаях пользователи не должны допускаться к установке порта. Для того, чтобы сообщить пользователю, что порт не следует устанавливать, имеется несколько make-переменных, которые могут быть использованы в файле Makefile порта. Значения следующих make-переменных будут причиной, возвращаемой пользователям, по которой порт отказывает в установке. Пожалуйста, используйте корректные make-переменные, так как каждая переменная make передает абсолютно различный смысл как для пользователей, так и для автоматизированных систем, которые полагаются на файлы Makefile, таких как кластер построения портов, FreshPorts и portsmon.

Помните, что BROKEN и FORBIDDEN будут использованы как временное средство, если порт не является работающим. Постоянно неработоспособные порты должны полностью удаляться из дерева.

В подходящих ситуациях пользователи могут быть оповещены о предстоящем удалении через переменные DEPRECATED и EXPIRATION_DATE. Первое - это просто строка, сообщающая причину запланированного удаления порта; вторая является строкой в формате ISO 8601 (YYYY-MM-DD). Обе будут показаны пользователю.

Переменную DEPRECATED можно установить без использования EXPIRATION_DATE (в частности, при рекомендации новой версии порта), но обратный порядок не имеет никакого смысла.

Не существует устоявшейся политики, как долго следует продолжать уведомления. Текущая практика дает около месяца для решения проблем безопасности и два месяца для проблем построения. Это также дает немного времени на исправление проблем любым заинтересованным коммиттерам.

Правильным способом подать сигнал для Makefile о том, что порт не может быть установлен из-за какого-то внешнего фактора (например, пользователь указал недопустимую комбинацию опций построения), является установка непустого значения для IGNORE. Это значение будет сформатировано и показано пользователю во время make install.

Использование для этих целей .error является распространенной ошибкой. Проблема в том, что в этой ситуации будут повреждены многие инструменты автоматизации, работающие с деревом портов. Наибольшим образом это распространено при попытке построить /usr/ports/INDEX (смотрите Запуск make describe). Тем не менее, даже более простые команды, такие как make maintainer, в этом случае также вернут ошибку. Это не является приемлемым.

Использование sysctl не рекомендуется, кроме как при выполнении целей. Это вызвано тем, что вычисление любых makevar, таких как во время команды make index, с необходимостью запуска этой команды, еще больше замедляет весь процесс.

sysctl(8) следует всегда использовать через переменную SYSCTL, поскольку она содержит полностью заданный путь, и при необходимости может быть переопределена.

Иногда авторы программного обеспечения меняют содержимое выпущенных дистрибутивных файлов без смены названия. Вы должны проверять, что изменения являются официальными и произведены автором. В прошлом бывало, что дистрибутивный файл молча изменялся на сайтах загрузки с намерением нанести вред или скомпрометировать безопасность конечного пользователя.

Отложите старый файл с дистрибутивом в сторону, загрузите новый, распакуйте его и сравните содержимое при помощи diff(1). Если вы не видите ничего подозрительного, то можете обновить файл distinfo. Убедитесь, что вы подытожили различия в вашем PR или описании коммита, чтобы другие люди были в курсе, что вы позаботились о том, что ничего плохого не случилось.

Возможно вы также захотите связаться с автором этого программного обеспечения для подтверждения изменений.

Не используйте /proc, если доступны любые другие источники получения информации, например, setprogname(argv[0]) в main() и getprogname(3), в случае если вы хотите "знать своё имя".

Не полагайтесь на поведение, не регламентированное POSIX.

Не выполняйте запись временных меток в критических путях выполнения приложения, если можно обойтись без этого. Получение временных меток может быть медленным, в зависимости от степени точности используемых часов в операционной системе. Если временные метки действительно нужны, определите степень требуемой точности и используйте тот API, в котором документируется получение достаточной точности.

Ряд простых системных вызовов (например, gettimeofday(2), getpid(2)) работают намного быстрее в Linux® по сравнению с любой другой операционной системой из-за кеширования и используемой оптимизации vsyscall. Не полагайтесь на их дешевизну в критичных к производительности приложениях. В целом, старайтесь избегать системных вызовов там, где это возможно.

Не полагайтесь на специфичное для Linux® поведение сокета. В частности, отличаются размеры буфера сокета по умолчанию (выполните вызов setsockopt(2) с SO_SNDBUF и SO_RCVBUF, и в то время как в Linux® при заполнении буфера сокета send(2) блокируется, FreeBSD возвращает ошибку и устанавливает ENOBUFS в качестве значения errno.

Если требуется рассчитывать на нестандартное поведение, инкапсулируйте это должным образом в общий для всех API с проверкой поведения на этапе конфигурации, и если требуемое поведение не найдено, прекращайте выполнение.

Используйте страницы справочника для проверки, относится ли функция к интерфейсу POSIX (ищите раздел "STANDARDS" на странице справочника).

Не рассчитывайте на то, что в качестве /bin/sh используется bash. Убедитесь, что командная строка, переданная в system(3), будет работать в POSIX-совместимой оболочке.

Список основных bash-измов расположен здесь.

Проверьте, что используемые заголовочные файлы включены в POSIX или список, рекомендуемый страницей справочника, т.к. например, забыть подключить sys/types.h - не такая уж проблема в Linux®, однако это не так во FreeBSD.

Компилируйте многопоточные приложения с ключом "-pthread", а не "-lpthread" или как-либо ещё.

Файлы pkg-descr и pkg-plist должны проверяться дважды. Если вы пересматриваете порт и думаете, что его можно описать иначе, сделайте это.

Пожалуйста, не создавайте дополнительных копий лицензии GNU General Public License в нашей системе.

Будьте внимательны с юридическими вопросами! Не делайте из нас нелегальных распространителей ПО!