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

12.1. Введение

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

12.2. WRKDIR

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

12.3. WRKDIRPREFIX

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

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

12.4. Различение операционных систем и версий ОС

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

#include <sys/param.h>

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

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

#if __FreeBSD__ >= 9
#  if __FreeBSD_version >= 901000
	 /* здесь особый код для версий 9.1+ */
#  endif
#endif

12.5. Написание чего-либо после bsd.port.mk

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

Вам нужно включить либо пару файлов bsd.port.pre.mk/bsd.port.post.mk, либо только bsd.port.mk; не используйте оба этих метода одновременно.

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

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

Переменная Описание

ARCH

Архитектура машины в виде, получаемом по команде uname -m (например, i386)

OPSYS

Тип операционной системы, получаемый по команде uname -s (например, FreeBSD)

OSREL

Версия релиза операционной системы (например, 2.1.5 или 2.2.7)

OSVERSION

Версия операционной системы в виде числа, та же, что и __FreeBSD_version.

LOCALBASE

Корень дерева "local" (например, /usr/local)

PREFIX

Куда, собственно, устанавливается порт (обратитесь к подробной информации о PREFIX).

Если вы задаете переменную MASTERDIR, делайте это до подключения bsd.port.pre.mk.

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

# no need to compile lang/perl5 if perl5 is already in system
.if ${OSVERSION} > 300003
BROKEN=	perl is in system
.endif

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

12.6. Использование выражения exec в сценариях обёртках

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

#!/bin/sh
exec %%LOCALBASE%%/bin/java -jar %%DATADIR%%/foo.jar "$@"

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

12.7. Поступайте разумно

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

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

12.8. Работа как с CC, так и CXX

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

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

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

CC?= gcc
CXX?= g++

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

CC= gcc
CXX= g++

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

12.9. Использование CFLAGS

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

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

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

CFLAGS+= -Wall -Werror

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

CFLAGS= -Wall -Werror

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

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

CFLAGS= -O3 -funroll-loops -DHAVE_SOUND

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

CFLAGS+= -DHAVE_SOUND

12.10. Библиотеки потоков

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

Если построение порта заканчивается ошибкой unrecognized option '-pthread', то может быть желательно использование cc в качестве компоновщика через установку CONFIGURE_ENV в LD=${CC}. Параметр -pthread напрямую командой ld не поддерживается.

12.11. Пожелания

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

12.12. README.html

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

Если не удается выполнить make readme, убедитесь, что значение по умолчанию ECHO_MSG не изменено внутри порта.

12.13. Пометка неустанавливаемого порта как BROKEN, FORBIDDEN или IGNORE

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

12.13.1. Переменные

  • BROKEN предназначена для портов, которые в настоящее время не компилируются, не устанавливаются или не удаляются правильно. Следует использовать, когда проблема считается временной.

    В особых случаях кластер построения будет продолжать попытки собрать их, чтобы показать, решена ли основная проблема. (Однако, как правило, кластер запускается без этой возможности.)

    В частности, используйте BROKEN, когда порт:

    • не компилируется

    • не выполняет процесс своей конфигурации или установки

    • устанавливает файлы вовне ${LOCALBASE}

    • не удаляет полностью все свои файлы при деинсталляции (тем не менее, это может быть допустимо, и подходит для портов, оставляющих после себя файлы, измененные пользователем)

  • FORBIDDEN используется для портов, которые содержат уязвимости в информационной безопасности или являются потенциально вредными в плане обеспечения информационной безопасности системы FreeBSD при установке данного порта (например: заведомо небезопасная программа или программа, которая предоставляет легко взламываемые сервисы). Порты должны помечаться как FORBIDDEN, как только в конкретном программном обеспечении обнаружилась уязвимость, но обновление выпущено не было. В идеальном случае порты должны обновляться максимально быстро после обнаружения уязвимости, чтобы уменьшить число уязвимых хостов FreeBSD (нам нравится иметь репутацию безопасной системы), однако иногда случается значительный временной разрыв между обнаружением уязвимости и выходом обновлённого релиза уязвимого программного обеспечения. Не помечайте порт как FORBIDDEN, если причина не вызвана соображениями информационной безопасности.

  • IGNORE предназначена для портов, которые не должны строиться по какой-либо другой причине. Следует использовать для портов, в случае когда проблема считается структурной. Кластер построения ни при каких условиях не будет строить порты, помеченные как IGNORE. В частности, используйте IGNORE, когда порт:

    • компилируется, но работает неправильно

    • не работает на установленной версии FreeBSD

    • имеет дистрибутивный файл, который не может быть автоматически извлечен из-за лицензионных ограничений

    • не работает с каким-либо другим портом, установленным в настоящее время (например, порт зависит от www/apache20, но установлен www/apache22)

    Если порт будет конфликтовать с уже установленным портом (например, если они устанавливают файл в то же место, но с иным функциональным назначением), то используйте вместо этого CONFLICTS. CONFLICTS сам установит значение IGNORE.

  • Если порт нужно пометить как IGNORE только на некоторых архитектурах, для этого есть две другие удобные переменные, которые автоматически установят для вас значения: ONLY_FOR_ARCHS и NOT_FOR_ARCHS. Примеры:

    ONLY_FOR_ARCHS=	i386 amd64
    NOT_FOR_ARCHS=	ia64 sparc64

    Собственное сообщение IGNORE можно задать с использованием ONLY_FOR_ARCHS_REASON и NOT_FOR_ARCHS_REASON. Отдельно для каждой архитектуры это возможно с использованием ONLY_FOR_ARCHS_REASON_ARCH и NOT_FOR_ARCHS_REASON_ARCH.

  • Если порт загружает и устанавливает исполняемые файлы i386, то следует установить IA32_BINARY_PORT. Если эта переменная установлена, будет выполнена проверка доступности каталога /usr/lib32 для библиотек версии IA32 и поддержки IA32 в ядре. При невыполнении любого из этих условий будет автоматически установлена переменная IGNORE.

12.13.2. Замечания по реализации

Строки не следует брать в кавычки. Также построение строки должно несколько различаться из-за способа отображения информации пользователю. Примеры:

BROKEN=	fails to link with base -lcrypto
IGNORE=	unsupported on recent versions

получаемые в результате следующего вывода make describe:

===>  foobar-0.1 is marked as broken: fails to link with base -lcrypto.
===>  foobar-0.1 is unsupported on recent versions.

12.14. Пометка порта на удаление с DEPRECATED или EXPIRATION_DATE

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

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

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

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

12.15. Избегайте использования конструкции .error

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

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

Пример 1. Как избегать использования .error

Из следующих двух вариантов строки файла Makefile первый приведёт к неудачному завершению работы make index, а второй - нет:

.error "option is not supported"
IGNORE=option is not supported

12.16. Использование sysctl

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

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

12.17. Меняющиеся дистрибутивные файлы

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

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

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

12.18. Избегание линуксизмов

Не используйте /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" или как-либо ещё.

12.19. Разное

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

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

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