Многие приложения могут быть построены в различных конфигурациях и с дополнительной функциональностью. Например, выбор естественного (человеческого) языка, GUI против командной строки или типа используемой базы данных. Пользователи могут нуждаться в различных конфигурациях, отличных от используемой по умолчанию, поэтому в системе портов предусмотрен механизм, позволяющий автору порта управлять сборкой того или иного варианта конфигурации. Правильная поддержка этих необязательных параметров облегчает пользователям жизнь и даёт два или более порта по цене одного.
Эти переменные предназначены для установки системным
администратором. Многие из них стандартизованы в файле
ports/KNOBS
.
При создании порта не давайте имя для knob, специфичное
для данного приложения. На примере порта Avahi, используйте
WITHOUT_MDNS
вместо
WITHOUT_AVAHI_MDNS
.
Не стоит рассчитывать, что
WITH_
обязательно имеет соответствующую переменную
*
WITHOUT_
,
и наоборот. В общем случае, предполагается значение по
умолчанию.*
Если обратное не указано, то проверяется только факт
установки самих переменных, но не их конкретное значение типа
YES
или NO
.
WITH_*
и WITHOUT_*
Переменная | Значение |
---|---|
WITH_OPENSSL_BASE | Использовать версию OpenSSL из базовой системы. |
WITH_OPENSSL_PORT | Устанавливает версию OpenSSL из security/openssl, даже если в базовой системе последняя версия. |
Портеры должны использовать так называемые
knobs для помощи конечным пользователям и для поддержания
количества наименований knobs в небольшом количестве.
Список популярных названий knobs можно найти в файле KNOBS
Названия knobs должны отражать, что это такое и что
выполняет. Если у порта имеется библиотечный префикс в
PORTNAME
, то он должен присутствовать в
названии knobs.
При установке порта переменные OPTIONS_*
предоставляют пользователю окно диалога с отображением
доступных параметров, с записью выбранных параметров в файл
/var/db/ports/${UNIQUENAME}/options
.
Эти опции повторно используются при следующем построении
порта.
Когда пользователь запускает make config
(или запускает впервые make build
),
инфраструктура выполняет проверку существования файла
/var/db/ports/${UNIQUENAME}/options
.
Если этот файл не существует, то используются значения
OPTIONS_*
и отображается диалоговое окно,
в котором эти параметры можно включить или выключить.
Затем сохраняется файл опций options
,
и выбранные переменные используются при построении порта.
Если новая версия порта добавляет новые значения
OPTIONS
, то пользователю будет представлено
окно диалога с сохраненными заполненными значениями старых
OPTIONS.
make showconfig
отображает
сохраненную конфигурацию. Для удаления
сохраненной конфигурации используйте
make rmconfig
.
OPTIONS_DEFINE
содержит список
используемых OPTIONS
. Они независимы
друг от друга и не сгруппированы:
OPTIONS_DEFINE= OPT1 OPT2
Далее после определения следует описание
OPTIONS
(не является обязательным,
но настоятельно рекомендуется):
OPT1_DESC= Describe OPT1 OPT2_DESC= Describe OPT2 OPT3_DESC= Describe OPT3 OPT4_DESC= Describe OPT4 OPT5_DESC= Describe OPT5 OPT6_DESC= Describe OPT6
ports/Mk/bsd.options.desc.mk
содержит описание множества наиболее используемых
OPTIONS
; переопределять их, как
правило, не нужно.
При описании параметров старайтесь представить себя
на месте пользователя: «Что это делает?»
и «Для чего бы я захотел включить это?»
Не делайте простое повторение названия. Например,
описание параметра NLS
как
«include NLS support» («включить
поддержку NLS») не поможет пользователю, который
уже видит название параметра, но может не знать, что
это означает. Описав его как «Native Language
Support via gettext utilities» («Поддержка
национального языка через утилиты gettext»),
вы поможете пользователю гораздо больше.
OPTIONS
можно группировать в виде
переключателей, для которых разрешен выбор единственного
варианта в каждой группе:
OPTIONS_SINGLE= SG1 OPTIONS_SINGLE_SG1= OPT3 OPT4
OPTIONS
можно группировать в виде
переключателей, для которых разрешен выбор единственного
варианта (или ни одного) в каждой группе:
OPTIONS_RADIO= RG1 OPTIONS_RADIO_RG1= OPT7 OPT8
OPTIONS
также можно группировать
в виде списков со множественным выбором, для которых
обязан быть включен по крайней мере
один из параметров:
OPTIONS_MULTI= MG1 OPTIONS_MULTI_MG1= OPT5 OPT6
OPTIONS
также можно группировать
в виде списков со множественным выбором, для которых
могут быть включены любые параметры, включая отсутствие
выбора:
OPTIONS_GROUP= GG1 OPTIONS_GROUP_GG1= OPT9 OPT10
По умолчанию OPTIONS
находится в
выключенном положении, если при этом оно также отсутствует
в списке OPTIONS_DEFAULT
:
OPTIONS_DEFAULT= OPT1 OPT3 OPT6
Определения OPTIONS
обязаны появиться
до подключения bsd.port.options.mk
.
Переменные PORT_OPTIONS
могут быть проверены только после
подключения bsd.port.options.mk
.
Вместо этого также можно использовать подключение
bsd.port.pre.mk
, что все еще широко
используется в портах, написанных до появления
bsd.port.options.mk
. Но имейте в виду,
что некоторые переменные, обычно, это некоторые флаги
USE_*
,
после подключения bsd.port.pre.mk
будут
работать не так, как этого от них ожидают.
OPTIONS
OPTIONS_DEFINE= FOO BAR FOO_DESC= Enable option foo BAR_DESC= Support feature bar .include <bsd.port.options.mk> .if ${PORT_OPTIONS:MFOO} CONFIGURE_ARGS+=--with-foo .else CONFIGURE_ARGS+=--without-foo .endif .if ${PORT_OPTIONS:MBAR} RUN_DEPENDS+= bar:${PORTSDIR}/bar/bar .endif .include <bsd.port.mk>
OPTIONS
.if ! ${PORT_OPTIONS:MEXAMPLES} CONFIGURE_ARGS+=--without-examples .endif
OPTIONS
OPTIONS_DEFINE= EXAMPLES OPTIONS_SINGLE= BACKEND OPTIONS_SINGLE_BACKEND= MYSQL PGSQL BDB OPTIONS_MULTI= AUTH OPTIONS_MULTI_AUTH= LDAP PAM SSL EXAMPLES_DESC= Install extra examples MYSQL_DESC= Use MySQL as backend PGSQL_DESC= Use PostgreSQL as backend BDB_DESC= Use Berkeley DB as backend LDAP_DESC= Build with LDAP authentication support PAM_DESC= Build with PAM support SSL_DESC= Build with OpenSSL support OPTIONS_DEFAULT= PGSQL LDAP SSL .include <bsd.port.options.mk> .if ${PORT_OPTIONS:MPGSQL} USE_PGSQL= yes CONFIGURE_ARGS+= --with-postgres .else CONFIGURE_ARGS+= --without-postgres .endif .if ${PORT_OPTIONS:MICU} LIB_DEPENDS+= icuuc:${PORTSDIR}/devel/icu .endif .if ! ${PORT_OPTIONS:MEXAMPLES} CONFIGURE_ARGS+= --without-examples .endif # Проверка других параметров OPTIONS .include <bsd.port.mk>
Следующие параметры по умолчанию всегда включены.
DOCS
— построение и установка
документации.
NLS
— интернационализация.
EXAMPLES
— построение и
установка примеров использования.
IPV6
— поддержка протокола
IPv6.
Нет необходимости добавлять эти параметры в
OPTIONS_DEFAULT
. Тем не менее, чтобы
отобразить их в окне диалога выбора параметров, они должны
быть добавлены в OPTIONS_DEFINE
.
При использовании сценария GNU configure, следите за тем,
какие необязательные функции задействуются посредством
автоматической активации. Отключайте явным образом те
необязательные функции, которые вы не хотели бы использовать,
через передачу соответствующих --without-xxx
или --disable-xxx
в переменной
CONFIGURE_ARGS
.
.if ${PORT_OPTIONS:MFOO} LIB_DEPENDS+= libfoo.so:${PORTSDIR}/devel/foo CONFIGURE_ARGS+= --enable-foo .endif
В приведенном выше примере представьте себе библиотеку libfoo,
установленную в системе. Пользователь не желает, чтобы приложение
использовало libfoo, и поэтому он выключает соответствующую опцию
в диалоге make config
. Но сценарий configure
приложения определяет наличие библиотеки в системе и включает ее
поддержку в итоговый исполняемый файл. Теперь, когда пользователь
решит удалить libfoo из системы, система портов позволит это
сделать (т.к. зависимость от libfoo не была записана), но
приложение перестанет работать.
.if ${PORT_OPTIONS:MFOO} LIB_DEPENDS+= libfoo.so:${PORTSDIR}/devel/foo CONFIGURE_ARGS+= --enable-foo .else CONFIGURE_ARGS+= --disable-foo .endif
Во втором примере библиотека libfoo отключена явным образом. Сценарий configure не включает соответствующие функции в приложении, несмотря на присутствие библиотеки в системе.
При определенных условиях сокращенный синтаксис записи
условий может вызывать проблемы со сложными конструкциями.
Если вы получаете ошибки, такие как Malformed
conditional
, то может быть использован
альтернативный синтаксис.
.if !empty(VARIABLE:MVALUE) # as an alternative to .if ${VARIABLE:MVALUE}
Существует несколько макросов, упрощающих запись условных значений, которые отличаются в зависимости от набора параметров.
Если переменная OPTIONS_SUB
имеет
значение yes
, то каждый из указанных в
OPTIONS_DEFINE
параметров будет добавлен
в PLIST_SUB
. Следующая запись:
OPTIONS_DEFINE= OPT1 OPTIONS_SUB= yes
соответствует:
OPTIONS_DEFINE= OPT1 .include <bsd.port.options.mk> .if ${PORT_OPTIONS:MOPT1} PLIST_SUB+= OPT1="" .else PLIST_SUB+= OPT1="@comment " .endif
X_CONFIGURE_ENABLE
дописывает в
CONFIGURE_ARGS
строку
--enable-${X_CONFIGURE_ENABLE}
или
--disable-${X_CONFIGURE_ENABLE}
в
соответствии с состоянием X
. Следующая
запись:
OPTIONS_DEFINE= OPT1 OPT1_CONFIGURE_ENABLE= test
соответствует:
OPTIONS_DEFINE= OPT1 .include <bsd.port.options.mk> .if ${PORT_OPTIONS:MOPT1} CONFIGURE_ARGS+= --enable-test .else CONFIGURE_ARGS+= --disable-test .endif
X_CONFIGURE_WITH
дописывает в
CONFIGURE_ARGS
строку
--with-${X_CONFIGURE_WITH}
или
--without-${X_CONFIGURE_WITH}
в
соответствии с состоянием X
. Следующая
запись:
OPTIONS_DEFINE= OPT1 OPT1_CONFIGURE_WITH= test
соответствует:
OPTIONS_DEFINE= OPT1 .include <bsd.port.options.mk> .if ${PORT_OPTIONS:MOPT1} CONFIGURE_ARGS+= --with-test .else CONFIGURE_ARGS+= --without-test .endif
Значение переменной X_CONFIGURE_ON
будет дописано в CONFIGURE_ARGS
в
соответствии с состоянием X
. Следующая
запись:
OPTIONS_DEFINE= OPT1 OPT1_CONFIGURE_ON= --add-test
соответствует:
OPTIONS_DEFINE= OPT1 .include <bsd.port.options.mk> .if ${PORT_OPTIONS:MOPT1} CONFIGURE_ARGS+= --add-test .endif
Значение переменной X_CONFIGURE_OFF
будет дописано в CONFIGURE_ARGS
в
соответствии с состоянием X
. Следующая
запись:
OPTIONS_DEFINE= OPT1 OPT1_CONFIGURE_OFF= --no-test
соответствует:
OPTIONS_DEFINE= OPT1 .include <bsd.port.options.mk> .if ! ${PORT_OPTIONS:MOPT1} CONFIGURE_ARGS+= --no-test .endif
Значение переменной X_CMAKE_ON
будет
дописано в CMAKE_ARGS
в соответствии с
состоянием X
. Следующая запись:
OPTIONS_DEFINE= OPT1 OPT1_CMAKE_ON= -DTEST:BOOL=true
соответствует:
OPTIONS_DEFINE= OPT1 .include <bsd.port.options.mk> .if ${PORT_OPTIONS:MOPT1} CMAKE_ARGS+= -DTEST:BOOL=true .endif
Значение переменной X_CMAKE_OFF
будет
дописано в CMAKE_ARGS
в соответствии с
состоянием X
. Следующая запись:
OPTIONS_DEFINE= OPT1 OPT1_CMAKE_OFF= -DTEST:BOOL=false
соответствует:
OPTIONS_DEFINE= OPT1 .include <bsd.port.options.mk> .if ! ${PORT_OPTIONS:MOPT1} CMAKE_ARGS+= -DTEST:BOOL=false .endif
Для любой из следующих переменных:
ALL_TARGET
CATEGORIES
CFLAGS
CPPFLAGS
CXXFLAGS
CONFIGURE_ENV
DISTFILES
EXTRA_PATCHES
INSTALL_TARGET
LDFLAGS
MAKE_ARGS
MAKE_ENV
PATCH_SITES
PATCHFILES
PLIST_FILES
PLIST_DIRS
PLIST_DIRSTRY
USES
Значение переменной X_ABOVEVARIABLE
будет дописано в ABOVEVARIABLE
в
соответствии с состоянием X
. Следующая
запись:
OPTIONS_DEFINE= OPT1 OPT1_USES= gmake OPT1_CFLAGS= -DTEST
соответствует:
OPTIONS_DEFINE= OPT1 .include <bsd.port.options.mk> .if ${PORT_OPTIONS:MOPT1} USES+= gmake CFLAGS+= -DTEST .endif
Для любого из следующих типов зависимости:
PKG_DEPENDS
EXTRACT_DEPENDS
PATCH_DEPENDS
FETCH_DEPENDS
BUILD_DEPENDS
LIB_DEPENDS
RUN_DEPENDS
Значение переменной X_ABOVEVARIABLE
будет дописано в ABOVEVARIABLE
в
соответствии с состоянием X
. Следующая
запись:
OPTIONS_DEFINE= OPT1 OPT1_LIB_DEPENDS= liba.so:${PORTSDIR}/devel/a
соответствует:
OPTIONS_DEFINE= OPT1 .include <bsd.port.options.mk> .if ${PORT_OPTIONS:MOPT1} LIB_DEPENDS+= liba.so:${PORTSDIR}/devel/a .endif
Этот, и другие документы, могут быть скачаны с http://ftp.FreeBSD.org/pub/FreeBSD/doc/.
По вопросам, связанным с FreeBSD, прочитайте
документацию прежде чем писать в
<questions@FreeBSD.org>.
По вопросам, связанным с этой документацией, пишите в рассылку
<doc@FreeBSD.org>.