path: root/documentation/content/ru/books/porters-handbook/special/chapter.adoc

---
title: Глава 6. Особые соглашения
prev: books/porters-handbook/makefiles
next: books/porters-handbook/plist
---

[[special]]
= Особые соглашения
:doctype: book
:toc: macro
:toclevels: 1
:icons: font
:sectnums:
:source-highlighter: rouge
:experimental:
:skip-front-matter:
:toc-title: Содержание
:table-caption: Таблица
:figure-caption: Рисунок
:example-caption: Пример
:xrefstyle: basic
:relfileprefix: ../
:outfilesuffix:
:sectnumoffset: 6

include::shared/mirrors.adoc[]
include::shared/authors.adoc[]
include::shared/releases.adoc[]
include::shared/ru/mailing-lists.adoc[]
include::shared/ru/teams.adoc[]
include::shared/ru/urls.adoc[]

toc::[]

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

[[staging]]
== Staging

[.filename]#bsd.port.mk# ожидает от портов работу с "каталогом сборки". Это означает, что порт должен устанавливать файлы не напрямую в назначенные каталоги (то есть, например, под `PREFIX`), а в отдельный каталог, из которого затем собирается пакет. Во многих случаях привилегии root для этого не требуются, что делает возможным сборку пакетов из-под непривилегированного пользователя. В режиме staging порт собирается и устанавливается в каталог сборки `STAGEDIR`. Пакет создается из каталога сборки и затем устанавливается в систему. В инструментарии automake такая концепция именуется `DESTDIR`; в прочем, в FreeBSD `DESTDIR` имеет собственное значение (смотрите <<porting-prefix>>).

Если для порта всё ещё требуются системные привилегии при выполнении цели `package`, то в [.filename]#Makefile# должна быть добавлена следующая строка:

[.programlisting]
....
NEED_ROOT=	yes
....

Метапорты, то есть порты, которые не устанавливают файлы непосредственно, а только зависят от других портов, должны по возможности избегать распаковки man:mtree[8] в каталог сборки. Это основная иерархия каталогов пакета, и эти пустые каталоги будут выглядеть лишними. Для предотвращения распаковки man:mtree[8] добавьте эту строку:

[.programlisting]
....
NO_MTREE=	yes
....

Staging задействуется посредством добавления переменной `STAGEDIR` слева от путей, которые используются в целях `pre-install`, `do-install` и `post-install` (смотрите примеры в книге). Обычно сюда относятся `PREFIX`, `ETCDIR`, `DATADIR`, `EXAMPLESDIR`, `MANPREFIX`, `DOCSDIR` и так далее. Каталоги должны создаваться при выполнении цели `post-install`. Избегайте использования абсолютных путей, когда это возможно.

При создании символический ссылки `STAGEDIR` должен ставиться только для пути назначения. Например:

[.programlisting]
....
${LN} -sf libfoo.so.42 ${STAGEDIR}${PREFIX}/lib/libfoo.so
....

Первоначальный путь [.filename]#${PREFIX}/lib/libfoo.so.42# выглядит нормально, но по факту может быть неправильным. Абсолютные пути могут указывать на неподходящее место, например, когда удалённая файловая система смонтирована по NFS как непривилегированная точка монтирования. Относительные пути реже подвержены проблемам и часто намного короче.

Порты, устанавливающие модули ядра, должны предварять путь установки (по умолчанию [.filename]#/boot/modules#) переменной `STAGEDIR`.

[[porting-shlibs]]
== Динамические библиотеки

Если ваш порт устанавливает одну или несколько динамических библиотек, определите переменную `USE_LDCONFIG`, которая приведёт к запуску из [.filename]#bsd.port.mk# команды `${LDCONFIG} -m` относительно каталога, в который устанавливается новая библиотека (как правило, это [.filename]#PREFIX/lib#), во время выполнения цели `post-install` для её регистрации в кэше динамических библиотек. Эта переменная, если она определена, также приведёт к добавлению соответствующей пары команд `@exec /sbin/ldconfig -m` и `@unexec /sbin/ldconfig -R` в ваш файл [.filename]#pkg-plist#, так что пользователь, устанавливающий пакет, сможет сразу же использовать динамическую библиотеку, а удаление пакета не приведёт к тому, что система будет предполагать, что библиотека всё ещё имеется в наличии.

[.programlisting]
....
USE_LDCONFIG=	yes
....

Если нужно, вы можете переопределить каталог по умолчанию, задав значение `USE_LDCONFIG`, в котором должны быть перечислены каталоги, в которые устанавливаются динамические библиотеки. Например, если ваш порт устанавливает динамические библиотеки в каталоги [.filename]#PREFIX/lib/foo# и [.filename]#PREFIX/lib/bar#, то вы можете в файле [.filename]#Makefile# указать следующее:

[.programlisting]
....
USE_LDCONFIG=	${PREFIX}/lib/foo ${PREFIX}/lib/bar
....

Будьте добры перепроверить, т.к. часто это вовсе не является необходимым и может быть решено иначе с помощью `-rpath` или установки `LD_RUN_PATH` во время компоновки (для примера смотрите package:lang/moscow_ml[]), или с помощью сценария-обёртки, который выставляет `LD_LIBRARY_PATH` перед запуском исполняемого файла как это делает package:www/seamonkey[].

При установке 32-разрядных библиотек на 64-разрядной системе используйте вместо этого `USE_LDCONFIG32`.

Постарайтесь сохранять номера версий динамических библиотек в формате [.filename]#libfoo.so.0#. Наш компоновщик позаботится только о старшем (первом) номере.

Если при обновлении порта увеличивается старший номер версии библиотеки, то для всех портов, компонуемых с затронутой библиотекой, следует увеличить значение `PORTREVISION` для форсирования перекомпиляции с новой версией библиотеки.

[[porting-restrictions]]
== Порты с ограничениями на распространение или с правовым обременением

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

[IMPORTANT]
====
На вас, как на человека, портирующего приложение, ложится обязанность прочесть лицензионные соглашения на программное обеспечение и удостовериться, что проект FreeBSD не будет являться их нарушителем, если будет заниматься распространением исходного кода или в бинарном виде по FTP/HTTP или на CD-ROM. Если у вас возникли сомнения, то, пожалуйста, обратитесь в {freebsd-ports}.
====

В подобных ситуациях можно использовать переменные, описываемые в последующих разделах.

=== `NO_PACKAGE`

Эта переменная указывает, что мы не можем создавать для приложения двоичный пакет. К примеру, лицензия не позволяет бинарное распространение или она может запрещать распространение пакетов, созданных из изменённых исходников.

Однако файлы `DISTFILES` могут свободно зеркалироваться по FTP/HTTP. Они также могут распространяться, используя CD-ROM (или на похожих носителях), если не установлена переменная `NO_CDROM`.

`NO_PACKAGE` должна также использоваться, если двоичный пакет, как правило, бесполезен, а приложение должно всегда компилироваться из исходного кода. К примеру, если в приложение во время компиляции жёстко включается конфигурационная информация, привязанная к конкретной системе, то задайте переменную `NO_PACKAGE`.

Значением переменной `NO_PACKAGE` должна быть строка, описывающая причину, по которой пакет не должен создаваться.

=== `NO_CDROM`

Эта переменная указывает на то, что, хотя мы имеем право создавать бинарные пакеты, мы не можем помещать эти пакеты или файлы `DISTFILES` порта на CD-ROM (или на похожие носители) для перепродажи. Однако бинарные пакеты и файлы `DISTFILES` порта будут оставаться доступными посредством FTP/HTTP.

Если эта переменная устанавливается вместе с `NO_PACKAGE`, то только файлы порта `DISTFILES` будут доступны, и только посредством FTP/HTTP.

В качестве значения `NO_CDROM` должна указываться строка, описывающая причины, по которым порт не может распространяться на CD-ROM. К примеру, это применяется, если лицензионное соглашение приложения предполагает только его "некоммерческое" использование.

=== `NOFETCHFILES`

Файлы, определенные в переменной `NOFETCHFILES`, не будут извлекаться ни из одного из `MASTER_SITES`. Примером такого файла является файл, поставляемый на CD-ROM.

Инструменты, проверяющие доступность этих файлов на `MASTER_SITES`, должны игнорировать эти файлы и не сообщать о них.

=== `RESTRICTED`

Задайте эту переменную, если лицензия на приложение не позволяет ни зеркалировать файлы `DISTFILES`, ни распространять бинарный пакет через FTP/HTTP или на CD-ROM.

Ни `NO_CDROM`, ни `NO_PACKAGE` не стоит устанавливать вместе с `RESTRICTED`, так как последняя переменная подразумевает первые две.

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

=== `RESTRICTED_FILES`

Если заданы `RESTRICTED` или `NO_CDROM`, то значение этой переменной по умолчанию соответствует `${DISTFILES} ${PATCHFILES}`, в противном случае она пуста. Если ограничены в распространении лишь некоторые из дистрибутивных файлов, то в этой переменной задаётся их список.

=== `LEGAL_TEXT`

Если порт имеет правовое обременение, которое не покрывается перечисленными выше переменными, то переменной `LEGAL_TEXT` следует присвоить строку с описанием данного обременения. Например, если было получено особое разрешение для FreeBSD на распространение двоичного файла, то эта переменная должна содержать соответствующее указание.

=== [.filename]#/usr/ports/LEGAL# и `LEGAL`

Порт, содержащий любую из перечисленных выше переменных, также должен быть добавлен в [.filename]#/usr/ports/LEGAL#. Первый столбец содержит шаблон совпадения с дистрибутивными файлами, имеющими ограничения на распространение. Второй столбец содержит корень порта. Третий столбец содержит вывод `make -VLEGAL`.

=== Примеры использования

Предпочтительным способом реализации утверждения "архивы исходных текстов для этого порта должны загружаться самостоятельно" является следующее:

[.programlisting]
....
.if !exists(${DISTDIR}/${DISTNAME}${EXTRACT_SUFX})
IGNORE=	may not be redistributed because of licensing reasons. Please visit some-website to accept their license and download ${DISTFILES} into ${DISTDIR}
.endif
....

Это одновременно и информирует пользователя, и устанавливает нужные метаданные на пользовательской машине для использования автоматическими программами.

Обратите внимание, что данная кляуза должна предшествовать подключению файла [.filename]#bsd.port.pre.mk#.

[[building]]
== Механизмы построения

[[parallel-builds]]
=== Параллельное построение портов

Инфраструктура портов FreeBSD поддерживает параллельное построение с использованием множественных подпроцессов `make`, что позволяет системам SMP задействовать всю доступную мощность CPU, тем самым делая построение портов более быстрым и эффективным.

Это достигается путём передачи флага `-jX` команде man:make[1]. Такое построение портов является поведением по умолчанию. К сожалению, не все порты поддерживают параллельную сборку достаточно хорошо, и поэтому может потребоваться выключить этот механизм явным образом путём добавления переменной `MAKE_JOBS_UNSAFE=yes`. Эта переменная используется в случае, когда известно, что порт ломается с `-jX`.

[[using-make]]
=== `make`, `gmake` и `imake`

Если ваш порт использует GNU make, то установите `USES= gmake`.

.Переменные для портов, использующих gmake
[cols="1,1", frame="none", options="header"]
|===
| Переменная
| Значение

|`USES= gmake`
|Для сборки порта требуется `gmake`.

|`GMAKE`
|Полный путь к команде `gmake`, если отсутствует в `PATH`.
|===

Если ваш порт является приложением X, которое создает файлы [.filename]#Makefile# из [.filename]#Imakefile#, используя imake, то установите `USES= imake`. Это заставит стадию конфигурирования автоматически выполнить `xmkmf -a`. Если флаг `-a` представляет для вашего порта проблему, то установите `XMKMF=xmkmf`. Если порт использует imake, но не понимает цель `install.man`, то следует установить `NO_INSTALL_MANPAGES=yes`.

Если исходный [.filename]#Makefile# вашего порта имеет что-нибудь помимо `all` в качестве основной цели построения, то задайте соответствующее значение `ALL_TARGET`. То же касается `install` и `INSTALL_TARGET`.

[[using-configure]]
=== Сценарий `configure`

Если ваш порт использует сценарий `configure` для получения файлов [.filename]#Makefile# из файлов [.filename]#Makefile.in#, то установите `GNU_CONFIGURE=yes`. Если вы хотите дать дополнительные параметры сценарию `configure` (аргументом по умолчанию является `--prefix=${PREFIX} --infodir=${PREFIX}/${INFO_PATH} --mandir=${MANPREFIX}/man --build=${CONFIGURE_TARGET}`), установите эти параметры в `CONFIGURE_ARGS`. Дополнительные переменные окружения можно передать, используя переменную `CONFIGURE_ENV`.

.Переменные для портов, использующих `configure`
[cols="1,1", frame="none", options="header"]
|===
| Переменная
| Значение

|`GNU_CONFIGURE`
|Порт использует сценарий `configure` для подготовки построения.

|`HAS_CONFIGURE`
|То же, что и `GNU_CONFIGURE`, кроме того, что цель configure по умолчанию не добавляется в `CONFIGURE_ARGS`.

|`CONFIGURE_ARGS`
|Дополнительные параметры, передаваемые сценарию `configure`.

|`CONFIGURE_ENV`
|Дополнительные переменные окружения, задаваемые для запуска сценария `configure`.

|`CONFIGURE_TARGET`
|Переопределить цель configure по умолчанию. Значением по умолчанию является `${MACHINE_ARCH}-portbld-freebsd${OSREL}`.
|===

[[using-cmake]]
=== Использование `cmake`

Если порт использует CMake, определите `USES= cmake` или `USES= cmake:outsource` для построения во внешнем каталоге (см. ниже).

.Переменные для портов, использующих `cmake`
[cols="1,1", frame="none", options="header"]
|===
| Переменная
| Значение

|`CMAKE_ARGS`
|Специфичные для порта флаги CMake, передаваемые `cmake`.

|`CMAKE_BUILD_TYPE`
|Тип построения (предопределённые профили построения CMake). По умолчанию `Release`, `Debug` при использовании `WITH_DEBUG`.

|`CMAKE_ENV`
|Переменные окружения для передачи `cmake`. По умолчанию `${CONFIGURE_ENV}`.

|`CMAKE_SOURCE_PATH`
|Путь к каталогу с исходным кодом. По умолчанию `${WRKSRC}`.
|===

.Переменные построения `cmake`, устанавливаемые пользователем
[cols="1,1", frame="none", options="header"]
|===
| Переменная
| Значение

|`CMAKE_VERBOSE`
|Разрешает подробный вывод сообщений при построении. Значение по умолчанию не задано, если не заданы `BATCH` или `PACKAGE_BUILDING`.

|`CMAKE_NOCOLOR`
|Запрещает цветной вывод сообщений при построении. Значение по умолчанию не задано, если не заданы `BATCH` или `PACKAGE_BUILDING`.
|===

CMake поддерживает следующие профили построения: `Debug`, `Release`, `RelWithDebInfo` и `MinSizeRel`. Профили `Debug` и `Release` учитывают системные флаги `\*FLAGS`; `RelWithDebInfo` и `MinSizeRel` соответственно определяют `CFLAGS` со значением `-O2 -g` и `-Os -DNDEBUG`. Значение `CMAKE_BUILD_TYPE` экспортируется в нижнем регистре в `PLIST_SUB` и должно использоваться, если порт устанавливает файлы `*.cmake` в зависимости от типа построения (для примера посмотрите на package:deskutils/strigi[]). Следует учитывать, что некоторые проекты могут определять собственные профили построения и/или форсировать конкретный тип построения через установку `CMAKE_BUILD_TYPE` в файлах [.filename]#CMakeLists.txt#. Для того чтобы порт для такого проекта учитывал `CFLAGS` и `WITH_DEBUG`, из этих файлов должны быть удалены значения `CMAKE_BUILD_TYPE`.

Большинство проектов, основанных на CMake, поддерживают метод внешнего (out-of-source) построения. Для порта внешнее построение можно запросить с использованием суффикса `:outsource`. В этом случае `CONFIGURE_WRKSRC`, `BUILD_WRKSRC` и `INSTALL_WRKSRC` будут иметь значение `${WRKDIR}/.build` для каталога, содержащего файлы, получаемые на этапах конфигурации и построения; при этом каталог с исходным кодом будет оставаться без изменений.

[[using-cmake-example]]
.Пример для `USES= cmake`
[example]
====
Следующий отрывок демонстрирует использование CMake для порта. `CMAKE_SOURCE_PATH` обычно не требуется, но может быть установлен, когда исходный код не находится в верхнем каталоге или если порт используется для построения части проекта.

[.programlisting]
....
USES=			cmake:outsource
CMAKE_SOURCE_PATH=	${WRKSRC}/subproject
....

====

[[using-scons]]
=== Использование `scons`

Если ваш порт использует SCons, определите `USE_SCONS=yes`.

.Переменные для портов, использующих `scons`
[cols="1,1", frame="none", options="header"]
|===
| Переменная
| Значение

|`SCONS_ARGS`
|Специфичные для порта флаги SCons, передаваемые окружению SCons.

|`SCONS_BUILDENV`
|Переменные для установки в системном окружении.

|`SCONS_ENV`
|Переменные для установки в окружении SCons.

|`SCONS_TARGET`
|Последний параметр для передачи SCons, похожий на `MAKE_TARGET`.
|===

Для того, чтобы сторонний [.filename]#SConstruct# соответствовал всему, что передается SCons в переменной `SCONS_ENV` (самое главное, это `CC/CXX/CFLAGS/CXXFLAGS`), примените патч к [.filename]#SConstruct#, так чтобы переменная построения `Environment` выглядела следующим образом:

[.programlisting]
....
env = Environment(**ARGUMENTS)
....

В дальнейшем ее можно изменить при помощи `env.Append` и `env.Replace`.

[[using-autotools]]
== Использование GNU Autotools

[[using-autotools-introduction]]
=== Введение

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

[.programlisting]
....
USE_AUTOTOOLS=	tool:version[:operation] ...
....

К моменту написания _tool_ может быть одним из `libtool`, `libltdl`, `autoconf`, `autoheader`, `automake` или `aclocal`.

_version_ указывает конкретную версию используемого инструмента (смотрите `devel/{automake,autoconf,libtool}[0-9]+` для получения действительных версий).

_operation_ является необязательным расширением и указывает на способ использования инструмента.

Одновременно может быть указано несколько инструментов, добавляя их все на одной строке или используя конструкцию Makefile `+=`.

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

[[using-libtool]]
=== `libtool`

Динамические библиотеки, использующие инфраструктуру построения GNU, обычно используют libtool для настройки компиляции и установки динамических библиотек в соответствии с особенностями данной операционной системы. В типичной практике используется копирование встроенного в приложение `libtool`. Если вам нужно использовать внешнюю команду `libtool`, то вы можете использовать версию, поставляемую Коллекцией Портов:

[.programlisting]
....
USE_AUTOTOOLS=	libtool:version[:env]
....

При отсутствии дополнительных операций, `libtool:version` сообщает инфраструктуре построения о применении патча к сценарию configure с установленной в системе копией `libtool`. Означает использование `GNU_CONFIGURE`. Более того, некоторые переменные make и оболочки shell будут назначены для дальнейшего использования этим портом. Подробности смотрите в [.filename]#bsd.autotools.mk#.

При использовании операции `:env` будет настроено только окружение.

Наконец, `LIBTOOLFLAGS` и `LIBTOOLFILES` можно установить по желанию, чтобы переопределить наиболее вероятные аргументы для `libtool` и файлы, предназначенные для изменения. Большинству портов это скорее всего не понадобится. Для дальнейших подробностей смотрите [.filename]#bsd.autotools.mk#.

[[using-libltdl]]
=== `libltdl`

Некоторые порты задействуют пакет с библиотекой `libltdl`, которая является частью комплекта `libtool`. Использование этой библиотеки не вызывает автоматическое использование самой `libtool`, и, таким образом, обеспечивается отдельная конструкция.

[.programlisting]
....
USE_AUTOTOOLS=	libltdl:version
....

Всё, что в настоящее время она делает, это добавление `LIB_DEPENDS` для подходящего порта `libltdl`, потому она предоставляется как удобная функция для помощи в устранении всяких зависимостей от портов autotools вне инфраструктуры `USE_AUTOTOOLS`. Для этого инструмента не существует необязательных операций.

[[using-autoconf]]
=== `autoconf` и `autoheader`

Вместо сценария configure некоторые порты содержат шаблон autoconf в файле [.filename]#configure.ac#. Вы можете использовать следующие присвоения, чтобы позволить `autoconf` создать сценарий configure, а `autoheader` создать заголовки шаблона для использования в сценарии configure.

[.programlisting]
....
USE_AUTOTOOLS=	autoconf:version[:env]
....

и

[.programlisting]
....
USE_AUTOTOOLS=	autoheader:version
....

которые также подразумевают использование `autoconf:version`.

Аналогично команде `libtool` включение необязательной операции `:env` всего лишь настраивает окружение для дальнейшего использования. Без этого выполняется наложение патчей и переконфигурирование порта.

Дополнительные необязательные переменные `AUTOCONF_ARGS` и `AUTOHEADER_ARGS` можно переопределить в [.filename]#Makefile# порта, если указано явным образом. Как и с эквивалентами `libtool`, большинству портов это вряд ли понадобится.

[[using-automake]]
=== `automake` и `aclocal`

Некоторые пакеты содержат только файлы [.filename]#Makefile.am#. Они должны быть преобразованы в файлы [.filename]#Makefile.in# с использованием automake и дальнейшей обработкой `configure` для получения настоящего [.filename]#Makefile#.

Аналогично, иногда пакеты не поставляются с вложенными файлами [.filename]#aclocal.m4#, снова требуемых для построения программного обеспечения. Их можно получить командой `aclocal`, которая просматривает [.filename]#configure.ac# или [.filename]#configure.in#.

`aclocal` имеет похожую связь с `automake`, как у `autoheader` с `autoconf`, что описано в предыдущей главе. `aclocal` подразумевает использование `automake`, таким образом, мы имеем:

[.programlisting]
....
USE_AUTOTOOLS=	automake:version[:env]
....

и

[.programlisting]
....
USE_AUTOTOOLS=	aclocal:version
....

которые также подразумевают использование `automake:version`.

Также как и для `libtool` и `autoconf`, подключение необязательной операции `:env` всего лишь устанавливает окружение для дальнейшего пользования. Без этого выполняется реконфигурирование этого порта.

Как и в случае с `autoconf` и `autoheader`, обе команды `automake` и `aclocal` соответственно имеют необязательные переменные `AUTOMAKE_ARGS` и `ACLOCAL_ARGS`, которые при необходимости можно переопределить в [.filename]#Makefile# порта.

[[using-gettext]]
== Использование GNU `gettext`

=== Простой вариант использования

Если для вашего порта требуется `gettext`, добавьте `USES= gettext`, и ваш порт унаследует зависимость от package:devel/gettext[]. <<uses-makefiles>> содержит перечень других значений для использования `gettext`.

Довольно распространенным случаем является использование в порте `gettext` и `configure`. Как правило, GNU `configure` способен находить `gettext` автоматически. Если он все же не сможет это сделать, то подсказки для размещения `gettext` можно передать через переменные окружения `CPPFLAGS` и `LDFLAGS`:

[.programlisting]
....
USES=	gettext
CPPFLAGS+=	-I${LOCALBASE}/include
LDFLAGS+=	-L${LOCALBASE}/lib

GNU_CONFIGURE=	yes
....

Конечно же, этот код можно записать в более компактном виде, если передавать флаги в `configure` не требуется:

[.programlisting]
....
USES=	gettext
GNU_CONFIGURE=	yes
....

=== Оптимальное использование

Некоторые программные продукты позволяют отключать NLS, к примеру, передавая параметр `--disable-nls` сценарию `configure`. В этом случае ваш порт должен использовать `gettext`, в зависимости от значения `NLS`. Для портов небольшой или средней сложности вы можете полагаться на следующую идиому:

[.programlisting]
....
GNU_CONFIGURE=	yes

.include <bsd.port.options.mk>

.if ${PORT_OPTIONS:MNLS}
USES+=			gettext
PLIST_SUB+=		NLS=""
.else
CONFIGURE_ARGS+=	--disable-nls
PLIST_SUB+=		NLS="@comment "
.endif

.include <bsd.port.mk>
....

Следующий пункт в вашем списке дел разобраться, чтобы файлы каталога сообщения включались в список упаковки по условию. Часть, входящая в [.filename]#Makefile#, уже обеспечена этой идиомой. Остальное объясняется в главе <<plist-sub,продвинутые практики [.filename]#pkg-plist#>>. Вкратце, каждое вхождение `%%NLS%%` в [.filename]#pkg-plist# будет заменено на "`@comment`", если NLS выключен, или пустой строкой, если включен. В результате строки, предваряемые `%%NLS%%`, станут комментариями в итоговом листе упаковки, если NLS выключен; иначе, префикс будет просто удален. Всё, что вам нужно, это вставить `%%NLS%%` перед каждым путем к файлу каталога сообщений в [.filename]#pkg-plist#. Например:

[.programlisting]
....
%%NLS%%share/locale/fr/LC_MESSAGES/foobar.mo
%%NLS%%share/locale/no/LC_MESSAGES/foobar.mo
....

В особо сложных случаях вам понадобиться использовать более продвинутые техники, чем данный рецепт, такие как <<plist-dynamic,динамические списки упаковки>>.

=== Управление каталогами сообщений

Существует момент, который следует учитывать при установке файлов каталогов сообщений. Целевые каталоги для размещения, расположенные под [.filename]#LOCALBASE/shared/locale#, редко когда должны создаваться и удаляться портом. Для наиболее популярных языков имеются собственные каталоги, перечисленные в [.filename]#PORTSDIR/Templates/BSD.local.dist#. Каталоги для множества других языков управляются с помощью порта package:devel/gettext[]. Обратите внимание на его [.filename]#pkg-plist# и посмотрите, куда данный порт собирается установить файлы каталогов сообщений для единственного в своем роде языка.

[[using-perl]]
== Использование Perl

Если `MASTER_SITES` установлена в значение `MASTER_SITE_PERL_CPAN`, то предпочтительным значением `MASTER_SITE_SUBDIR` является имя иерархии верхнего уровня. Например, рекомендуемым значением для `p5-Module-Name` является `Module`. Иерархию верхнего уровня можно посмотреть на сайте http://cpan.org/modules/by-module/[cpan.org]. Это поддерживает порт в рабочем состоянии при изменении модуля автором.

Исключением этого правила является отсутствие соответствующего каталога или файла с дистрибутивом в этом каталоге. В качестве `MASTER_SITE_SUBDIR` в этом случае разрешается использовать id автора.

В качестве значения все из настраиваемых knobs ниже принимают `YES` или строку с версией вида `5.8.0+`. `YES` означает, что данный порт можно использовать с любой из поддерживаемых версий Perl. Если порт работает только с некоторыми версиями Perl, то это можно обозначить при помощи строки с версией, указывающей на минимальную версию (пример: `5.7.3+`), максимальную версию (пример: `5.8.0-`) или точную версию (пример: `5.8.3`).

.Переменные для портов, использующих Perl
[cols="1,1", frame="none", options="header"]
|===
| Переменная
| Значение

|`USE_PERL5`
|Perl 5 используется для построения и работы.

|`USE_PERL5_BUILD`
|Perl 5 используется для построения.

|`USE_PERL5_RUN`
|Perl 5 используется во время работы.

|`PERL`
|Полный путь к интерпретатору Perl 5, либо в системе, либо установленному из портов, но без номера версии. Используйте это, если вам нужно заменить строки "`#!`" в скриптах.

|`PERL_CONFIGURE`
|Конфигурация при помощи MakeMaker языка Perl. Влечёт `USE_PERL5`.

|`PERL_MODBUILD`
|Конфигурация, построение и установка с использованием Module::Build. Влечёт `PERL_CONFIGURE`.
|===

[NOTE]
====
Порты для модулей Perl, которые не имеют официального вебсайта, должны указывать `cpan.org` в строке WWW в файле [.filename]#pkg-descr#. Предпочтительная форма URL `http://search.cpan.org/dist/Module-Name/` (включая завершающий слэш).
====

[NOTE]
====
Не используйте `${SITE_PERL}` в объявлении зависимостей. Использование этой конструкции подразумевает наличие подключенного [.filename]#bsd.perl.mk#, что не всегда так. Порты, зависимые от этого порта, получат неправильные зависимости, если файлы этого порта будут перемещены при последующем обновлении. Правильный способ объявления зависимостей для модулей Perl показан в примере ниже.
====

[[use-perl-dependency-example]]
.Пример зависимости Perl
[example]
====
[.programlisting]
....
p5-IO-Tee>=0.64:${PORTSDIR}/devel/p5-IO-Tee
....

====

Для портов Perl, которые устанавливают страницы справочника, в [.filename]#pkg-plist# можно использовать макрос `PERL5_MANx` (где _x_ принимает значение от `1` до `9`). Например,

[.programlisting]
....
lib/perl5/5.14/man/man3/AnyEvent::I3.3.gz
....

можно заменить на

[.programlisting]
....
%%PERL5_MAN3%%/AnyEvent::I3.3.gz
....

[[using-x11]]
== Использование X11

[[x11-variables]]
=== Компоненты X.Org

X.Org является реализацией X11, доступной в Коллекции Портов. Если ваше приложение зависит от компонентов X, установите в переменную `USE_XORG` в перечень требуемых компонентов. К настоящему времени доступными компонентами являются:

`bigreqsproto compositeproto damageproto dmx dmxproto dri2proto evieproto fixesproto fontcacheproto fontenc fontsproto fontutil glproto ice inputproto kbproto libfs oldx pciaccess pixman printproto randrproto recordproto renderproto resourceproto scrnsaverproto sm trapproto videoproto x11 xau xaw xaw6 xaw7 xbitmaps xcmiscproto xcomposite xcursor xdamage xdmcp xevie xext xextproto xf86bigfontproto xf86dgaproto xf86driproto xf86miscproto xf86rushproto xf86vidmodeproto xfixes xfont xfontcache xft xi xinerama xineramaproto xkbfile xkbui xmu xmuu xorg-server xp xpm xprintapputil xprintutil xproto xproxymngproto xrandr xrender xres xscrnsaver xt xtrans xtrap xtst xv xvmc xxf86dga xxf86misc xxf86vm`.

Всегда актуальный перечень можно найти в [.filename]#/usr/ports/Mk/bsd.xorg.mk#.

Проект Mesa является попыткой обеспечить свободную реализацию OpenGL. Вы можете указать зависимость от различных компонентов этого проекта при помощи переменной `USE_GL`. Действительные опции: `glut, glu, glw, glew, gl` и `linux`. Для обратной совместимости значение `yes` соответствует `glu`.

[[use-xorg-example]]
.Пример для USE_XORG
[example]
====
[.programlisting]
....
USE_XORG=	xrender xft xkbfile xt xaw
USE_GL=		glu
....

====

.Переменные для портов, использующих X
[cols="1,1", frame="none"]
|===
|`USES= imake`
|Используется `imake`.

|`XMKMF`
|Задаёт маршрут до `xmkmf`, если он отсутствует в `PATH`. По умолчанию это `xmkmf -a`.
|===

[[using-x11-vars]]
.Использование переменных X11 в порте
[example]
====
[.programlisting]
....
# Использовать некоторые библиотеки X11
USE_XORG=	x11 xpm
....

====

[[porting-motif]]
=== Порты, которым требуется Motif

Если вашему порту требуется Motif, задайте переменную `USES= motif` в файле [.filename]#Makefile#. Реализация Motif, используемая по умолчанию, находится в package:x11-toolkits/open-motif[]. Пользователи вместо этого могут выбрать package:x11-toolkits/lesstif[] через установку переменной `WANT_LESSTIF`.

Переменная `MOTIFLIB` будет установлена в [.filename]#bsd.port.mk#, чтобы ссылаться на соответствующую библиотеку Motif. Пожалуйста, измените исходные тексты вашего порта на использование `${MOTIFLIB}` везде, где упоминается библиотека Motif, в первоначальном [.filename]#Makefile# или [.filename]#Imakefile#.

Существует два общих случая:

* Если порт обращается к библиотеке Motif как `-lXm` в своих файлах [.filename]#Makefile# или [.filename]#Imakefile#, просто подставьте вместо этих обращений `${MOTIFLIB}`.
* Если порт использует `XmClientLibs` в своем файле [.filename]#Imakefile#, измените это обращение на `${MOTIFLIB} ${XTOOLLIB} ${XLIB}`.

Заметьте, что переменная `MOTIFLIB` (как правило) раскрывается в `-L/usr/local/lib -lXm` или `/usr/local/lib/libXm.a`, так что нет нужды впереди добавлять `-L` или `-l`.

=== Шрифты для X11

Если ваш порт устанавливает шрифты для X Window System, поместите их в каталог [.filename]#LOCALBASE/lib/X11/fonts/local#.

=== Получение поддельного `DISPLAY`, используя Xvfb

Некоторые приложения для успешной компиляции требуют наличие работающего дисплея X11. Это создает проблему для машин, которые работают в режиме headless. При использовании следующего канонического хака инфраструктура построения запустит сервер X в виртуальном фреймбуфере. Затем переменная работающего `DISPLAY` передается при построении.

[.programlisting]
....
USES=	display
....

[[desktop-entries]]
=== Элементы рабочего стола

Элементы рабочего стола (http://standards.freedesktop.org/desktop-entry-spec/latest/[стандарта Freedesktop]) предоставляют способ автоматической настройки функций рабочего стола при установке новой программы, не требуя вмешательства пользователя. Например, новые программы автоматически отображаются в меню приложений совместимых окружений рабочего стола. Элементы рабочего стола изначально появились в окружении рабочего стола GNOME, но в настоящее время являются стандартом и также работают с KDE и Xfce. Такая небольшая автоматизация предоставляет реальное удобство для пользователя, и посему элементы рабочего стола приветствуются в приложениях, которые можно использовать в окружении рабочего стола.

==== Использование предопределенных файлов [.filename]#.desktop#

Порты, включающие предопределенные файлы [.filename]#*.desktop#, должны включать эти файлы в [.filename]#pkg-plist# и устанавливать их в каталог [.filename]#$LOCALBASE/shared/applications#. Для установки этих файлов используется <<install-macros,макрос `INSTALL_DATA`>>.

[[updating-desktop-database]]
==== Обновление базы данных рабочего стола

Если в файле порта [.filename]#portname.desktop# имеется запись MimeType, то база данных рабочего стола олжна быть обновлена после установки и удаления. Для этого укажите `USES`= desktop-file-utils.

[[desktop-entries-macro]]
==== Создание элементов рабочего стола с использованием `DESKTOP_ENTRIES`

Элементы рабочего стола можно легко создавать для приложений, используя переменную `DESKTOP_ENTRIES`. Будет автоматически создан, установлен и добавлен в [.filename]#pkg-plist# файл с названием [.filename]#name.desktop#. Синтаксис:

[.programlisting]
....
DESKTOP_ENTRIES=	"NAME" "COMMENT" "ICON" "COMMAND" "CATEGORY" StartupNotify
....

Перечень возможных категорий доступен на http://standards.freedesktop.org/menu-spec/latest/apa.html[вебсайте Freedesktop]. `StartupNotify` отобразит, поддерживает ли приложение _уведомления о запуске_. Как правило, это графический индикатор часы вместо указателя мыши, меню или панель, которые уведомляют пользователя о загрузке программы. Программа, поддерживающая уведомления о запуске, очистит этот индикатор после запуска. Программы, несовместимые с уведомлениями о запуске, не будут очищать индикатор (возможно, вызывая путаницу и приводя пользователей в бешенство), и поэтому должны иметь `StartupNotify` в выключенном состоянии `false`; тогда индикатор не будет отображаться совсем.

Пример:

[.programlisting]
....
DESKTOP_ENTRIES=	"ToME" "Roguelike game based on JRR Tolkien's work" \
			"${DATADIR}/xtra/graf/tome-128.png" \
			"tome -v -g" "Application;Game;RolePlaying;" \
			false
....

[[using-gnome]]
== Использование GNOME

Для задания того, какие компоненты GNOME использует конкретный порт, проект FreeBSD/GNOME использует собственный набор переменных. На странице проекта FreeBSD/GNOME размещён http://www.FreeBSD.org/gnome/docs/porting/[ исчерпывающий список этих переменных].

[[using-qt]]
== Использование Qt

[[qt-common]]
=== Порты, для которых требуется Qt

.Переменные для портов, использующих Qt
[cols="1,1", frame="none"]
|===
|`USE_QT4`
|Указывает инструменты и библиотеки в качестве зависимостей для портов, которые используют Qt 4. Для получения подробностей смотрите <<qt4-components,выбор компонентов Qt 4>>.

|`QT_PREFIX`
|Устанавливается в значение, содержащее путь к установленному Qt (переменная только для чтения).

|`MOC`
|Устанавливается в значение, содержащее путь к `moc` (переменная только для чтения). По умолчанию устанавливается в соответствии со значением `USE_QT_VER`.

|`QTCPPFLAGS`
|Дополнительные флаги компилятора для инструментального пакета Qt, передаваемые через переменную `CONFIGURE_ENV`. По умолчанию устанавливается в соответствии со значением `USE_QT_VER`.

|`QTCFGLIBS`
|Дополнительные флаги компоновки для инструментального пакета Qt, передаваемые через переменную `CONFIGURE_ENV`. По умолчанию устанавливается в соответствии со значением `USE_QT_VER`.

|`QTNONSTANDARD`
|Подавляет изменение `CONFIGURE_ENV`, `CONFIGURE_ARGS`, `CPPFLAGS` и `MAKE_ENV`.
|===

.Дополнительные переменные для портов, использующих Qt 4.x
[cols="1,1", frame="none"]
|===
|`UIC`
|Устанавливает путь к `uic` (переменная только для чтения).

|`QMAKE`
|Устанавливает путь к `qmake` (переменная только для чтения).

|`QMAKESPEC`
|Устанавливает путь к конфигурационному файлу для `qmake` (переменная только для чтения).

|`QMAKEFLAGS`
|Дополнительные флаги для `qmake`.

|`QT_INCDIR`
|Устанавливает каталоги для заголовков Qt 4 (переменная только для чтения).

|`QT_LIBDIR`
|Устанавливает путь к библиотекам Qt 4 (переменная только для чтения).

|`QT_PLUGINDIRC`
|Устанавливает путь к плагинам Qt 4 (переменная только для чтения).
|===

При заданной переменной `USE_QT4` применяются следующие настройки:

[.programlisting]
....
CONFIGURE_ARGS+=	--with-qt-includes=${QT_INCDIR} \
			--with-qt-libraries=${QT_LIBDIR} \
			--with-extra-libs=${LOCALBASE}/lib \
			--with-extra-includes=${LOCALBASE}/include
CONFIGURE_ENV+=	MOC="${MOC}" UIC="${UIC}" LIBS="${QTCFGLIBS}" \
		QMAKE="${QMAKE}" QMAKESPEC="${QMAKESPEC}" QTDIR="${QT_PREFIX}"
MAKE_ENV+=	QMAKESPEC="${QMAKESPEC}"

PLIST_SUB+=	QT_INCDIR_REL=${QT_INCDIR_REL} \
		QT_LIBDIR_REL=${QT_LIBDIR_REL} \
		QT_PLUGINDIR_REL=${QT_PLUGINDIR_REL}
....

[[qt4-components]]
=== Выбор компонентов

В переменной `USE_QT4` должны указываться зависимости от отдельных инструментов и библиотек Qt 4. К каждому компоненту можно добавить суффикс, `_build` или `_run`, отражающий, когда должна быть применена зависимость, во время сборки или выполнения, соответственно. Если суффикс отсутствует, зависимость от компонента будет и для времени сборки, и для времени выполнения. Обычно, компоненты библиотек должны указываться без суффиксов, компоненты инструментов - с суффиксом `_build`, а компоненты плагинов - с суффиксом `_run`. Наиболее общие используемые компоненты перечислены ниже (все доступные компоненты перечислены в `_USE_QT4_ALL` в файле [.filename]#/usr/ports/Mk/bsd.qt.mk#):

.Доступные библиотечные компоненты Qt 4
[cols="1,1", frame="none", options="header"]
|===
| Название
| Описание

|`corelib`
|основная библиотека (можно опустить, если порт не использует ничего, кроме `corelib`)

|`gui`
|библиотека графического пользовательского интерфейса

|`network`
|сетевая библиотека

|`opengl`
|библиотека OpenGL

|`qt3support`
|библиотека совместимости с Qt 3

|`qtestlib`
|библиотека модульного тестирования

|`script`
|библиотека сценариев

|`sql`
|библиотека SQL

|`xml`
|библиотека XML
|===

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

.Доступные компоненты инструментов Qt 4
[cols="1,1", frame="none", options="header"]
|===
| Название
| Описание

|`moc`
|мета-объектный компилятор (нужен при построении почти для каждого приложения Qt)

|`qmake`
|генератор Makefile / утилита построения

|`rcc`
|компилятор ресурсов (нужен, если приложение идет вместе с файлами [.filename]#*.rc# или [.filename]#*.qrc#)

|`uic`
|компилятор пользовательского интерфейса (нужен, если приложение идет вместе с файлами [.filename]#*.ui#, созданными при помощи Qt Designer, - на практике каждое приложение Qt с GUI)
|===

.Доступные компоненты плагинов Qt 4
[cols="1,1", frame="none", options="header"]
|===
| Название
| Описание

|`iconengines`
|плагин для движка иконок SVG (если приложение поставляется с иконками SVG)

|`imageformats`
|плагины для графических форматов GIF, JPEG, MNG и SVG (если приложение поставляется с графическими файлами)
|===

[[qt4-components-example]]
.Выбор компонентов Qt 4
[example]
====
В этом примере портированное приложение использует библиотеку графического пользовательского интерфейса Qt 4, основную библиотеку Qt 4, все инструменты генерации кода Qt 4 и генератор Makefile Qt 4. Поскольку библиотека `gui` подразумевает зависимость от основной библиотеки, указывать `corelib` нет необходимости. Инструменты генерации кода Qt 4 `moc`, `uic` и `rcc`, а также генератор Makefile `qmake` нужны только для времени построения, поэтому они указаны с суффиксом `_build`:

[.programlisting]
....
USE_QT4=	gui moc_build qmake_build rcc_build uic_build
....

====

[[using-qmake]]
=== Использование `qmake`

.Переменные для портов, использующих `qmake`
[cols="1,1", frame="none", options="header"]
|===
| Название
| Описание

|`QMAKE_ARGS`
|Спефицичные для порта флаги QMake для передачи программе `qmake`.

|`QMAKE_ENV`
|Переменные окружения, устанавливаемые для программы `qmake`. По умолчанию соответствует значению `${CONFIGURE_ENV}`.

|`QMAKE_PRO`
|Название файла проекта [.filename]#.pro#. По умолчанию имеет пустое значение (с использованием автоопределения).
|===

Если вместе с приложением вместо [.filename]#configure# поставляется файл [.filename]#.pro#, вы можете использовать следующее:

[.programlisting]
....
USES=	qmake
USE_QT4=	qmake_build
....

`USES=qmake` указывает порту на использование `qmake` в процессе конфигурации. Обратите внимание, что `USES=qmake` не подразумевает зависимость от Qt 4 `qmake`. Для этого в значении `USE_QT4` должен присутствовать компонент `qmake_build`.

Приложения Qt часто пишутся в кроссплатформенной манере, и X11/Unix часто не является для них платформой разработки, что в свою очередь часто приводит к соответствующим упущенным моментам:

* _Отсутствующие дополнительные пути для заголовочных файлов._ Многие приложения идут с поддержкой иконки в системном трее, но пренебрегают смотреть на наличие заголовочных файлов и/или библиотеками в каталогах X11. Вы можете сообщить `qmake`, чтобы она добавила каталоги в пути поиска заголовочных файлов и библиотек через командную строку. К примеру:
+
[.programlisting]
....
QMAKE_ARGS+= INCLUDEPATH+=${LOCALBASE}/include \
	LIBS+=-L${LOCALBASE}/lib
....

* _Фиктивные пути установки._ Иногда данные, такие как иконки и файлы .desktop, устанавливаются по умолчанию в каталоги, которые не просматриваются XDG-совместимыми приложениями. Примером является package:editors/texmaker[] - взгляните на [.filename]#patch-texmaker.pro# из каталога [.filename]#files# этого порта, который можно взять в качестве шаблона исправления этого непосредственно в файле проекта `qmake`.

[[using-kde]]
== Использование KDE

[[kde4-variables]]
=== Задание переменных KDE 4

Если ваше приложение зависит от KDE 4.x, присвойте `USE_KDE4` список требуемых компонентов. Для переопределения типа зависимости компонента могут быть использованы суффиксы `_build` и `_run` (например, `baseapps_run`). Если суффикс не задан, будет использован тип зависимости по умолчанию. Если вы хотите использовать оба типа, добавьте компонент дважды с обоими суффиксами (например, `automoc4_build automoc4_run`). Основные наиболее используемые компоненты перечислены ниже (актуальные компоненты задокументированы в начале файла [.filename]#/usr/ports/Mk/bsd.kde4.mk#):

.Доступные компоненты KDE 4
[cols="1,1", frame="none", options="header"]
|===
| Название
| Описание

|`kdehier`
|Иерархия основных каталогов KDE

|`kdelibs`
|KDE Developer Platform

|`kdeprefix`
|Если установлено, то порт будет установлен в `${KDE4_PREFIX}` вместо `${LOCALBASE}`

|`sharedmime`
|База данных MIME типов для портов KDE

|`automoc4`
|automoc для пакетов Qt 4

|`akonadi`
|Сервер хранения KDE-Pim

|`soprano`
|Фреймворк Qt 4 RDF

|`strigi`
|Поисковые даемон рабочего стола

|`libkcddb`
|Библиотека KDE CDDB

|`libkcompactdisc`
|Библиотека KDE для взаимодействия с аудио-CD

|`libkdeedu`
|Библиотеки, используемые для образовательных приложений

|`libkdcraw`
|Библиотека KDE LibRaw

|`libkexiv2`
|Библиотека KDE Exiv2

|`libkipi`
| KDE Image Plugin Interface

|`libkonq`
|Основная библиотека Konqueror

|`libksane`
|Библиотека KDE SANE ("Scanner Access Now Easy")

|`pimlibs`
|Библиотеки KDE-Pim

|`kate`
|Тектовый редактор

|`marble`
|Виртуальный глобус

|`okular`
|Универсальный просмотрщик документов

|`korundum`
|Привязка Ruby к KDE

|`perlkde`
|Привязка Perl к KDE

|`pykde4`
|Привязка Python к KDE

|`pykdeuic4`
|Компилятор пользовательского интерфейса PyKDE

|`smokekde`
|Библиотеки KDE SMOKE
|===

Порты KDE 4.x устанавливаются в `KDE4_PREFIX`, что в настоящее время соответствует [.filename]#/usr/local/kde4#. Это достигается путем указания компонента `kdeprefix`, который определяет значение по умолчанию для `PREFIX`. Тем не менее, порты учитывают любые `PREFIX`, установленные через переменную окружения `MAKEFLAGS` и/или параметры `make`.

[[kde4-components-example]]
.Пример `USE_KDE4`
[example]
====
Это простой пример для порта KDE 4. `USES= cmake:outsource` указывает порту использовать CMake, конфигурационный инструмент, широко применяемый в проектах KDE 4 (подробное описание даёт <<using-cmake>>). `USE_KDE4` добавляет зависимость от библиотек KDE и заставляет порты использовать `automoc4` во время сборки. Требуемые компоненты KDE и другие зависимости можно определить в журнале configure. `USE_KDE4` не подразумевает `USE_QT4`. Если порт требует какой-либо из компонентов Qt 4, их следует указать в `USE_QT4`.

[.programlisting]
....
USES=		cmake:outsource
USE_KDE4=	kdelibs kdeprefix automoc4
USE_QT4=	moc_build qmake_build rcc_build uic_build
....

====

[[using-java]]
== Использование Java

[[java-variables]]
=== Задание переменных

Если вашему порту необходимо наличие Java(TM) Development Kit (JDK(TM)) для построения, работы или даже распаковки дистрибутивного файла, то в нём должна быть задана переменная `USE_JAVA`.

В Коллекции Портов присутствуют несколько JDK различных разработчиков и разных версий. Если ваш порт должен использовать одну из этих версий, то вы должны указать, какую именно. Самой последней версией и версией по умолчанию является package:java/openjdk6[].

.Переменные, которые которые могут задаваться портами, использующими Java
[cols="1,1", frame="none", options="header"]
|===
| Переменная
| Значение

|`USE_JAVA`
|Должна быть определена для того, что последующие переменные вступили в действие.

|`JAVA_VERSION`
|Список версий Java, перечисленных через пробел, подходящих для порта. Опциональный знак `"+"` позволяет вам указать диапазон версий (возможные значения: `1.5[+] 1.6[+] 1.7[+]`).

|`JAVA_OS`
|Список операционных систем, перечисленных через пробел, порты JDK для которых подходят для порта (возможные значения: `native linux`).

|`JAVA_VENDOR`
|Список разработчиков портов JDK, перечисленных через пробел, которые подходят для порта (возможные значения: `freebsd bsdjava sun openjdk`).

|`JAVA_BUILD`
|Если задана, то означает, что выбранный порт JDK должен быть добавлен к зависимостям порта для его построения.

|`JAVA_RUN`
|Если задана, то означает, что выбранный порт JDK должен быть добавлен в зависимостям порта для его работы.

|`JAVA_EXTRACT`
|Если задана, то означает, что выбранный порт JDK должен быть добавлен в зависимостям порта для распаковки его дистрибутивных файлов.
|===

Ниже перечисляются все значения, которые принимают переменные после задания переменной `USE_JAVA`:

.Переменные, доступные в портах, использующих Java
[cols="1,1", frame="none", options="header"]
|===
| Переменная
| Значение

|`JAVA_PORT`
|Название порта JDK (к примеру, `'java/openjdk6'`).

|`JAVA_PORT_VERSION`
|Полное наименовании версии порта JDK (к примеру, `'1.6.0'`). Если вам нужны только первые две цифры номера версии, используйте `${JAVA_PORT_VERSION:C/^([0-9])\.([0-9])(.*)$/\1.\2/}`.

|`JAVA_PORT_OS`
|Операционная система, используемая портом JDK (к примеру, `'native'`).

|`JAVA_PORT_VENDOR`
|Разработчик порта JDK (к примеру, `'openjdk'`).

|`JAVA_PORT_OS_DESCRIPTION`
|Описание операционной системы, используемой портом JDK (к примеру, `'Native'`).

|`JAVA_PORT_VENDOR_DESCRIPTION`
|Описание разработчика порта JDK (к примеру, `'OpenJDK BSD Porting Team'`).

|`JAVA_HOME`
|Маршрут к установочному каталогу JDK (к примеру, [.filename]#'/usr/local/openjdk6'#).

|`JAVAC`
|Маршрут к используемому компилятору Java (к примеру, [.filename]#'/usr/local/openjdk6/bin/javac'#.

|`JAR`
|Маршрут к используемой утилите `jar` (к примеру, [.filename]#'/usr/local/openjdk6/bin/jar'# или [.filename]#'/usr/local/bin/fastjar'#).

|`APPLETVIEWER`
|Маршрут к утилите `appletviewer` (к примеру, [.filename]#'/usr/local/openjdk6/bin/appletviewer'#).

|`JAVA`
|Маршрут к выполняемому файлу `java`. Используйте его для запуска Java-программ (к примеру, [.filename]#'/usr/local/openjdk6/bin/java'#).

|`JAVADOC`
|Маршрут к вспомогательной программе `javadoc`.

|`JAVAH`
|Маршрут к программе `javah`.

|`JAVAP`
|Маршрут к программе `javap`.

|`JAVA_KEYTOOL`
|Маршрут к вспомогательной программе `keytool`.

|`JAVA_N2A`
|Маршрут к утилите `native2ascii`.

|`JAVA_POLICYTOOL`
|Маршрут к программе `policytool`.

|`JAVA_SERIALVER`
|Маршрут к вспомогательной программе `serialver`.

|`RMIC`
|Маршрут к генератору каркаса программ RMI, утилите `rmic`.

|`RMIREGISTRY`
|Маршрут к программе регистрации RMI, `rmiregistry`.

|`RMID`
|Маршрут к программе-даемону RMI `rmid`.

|`JAVA_CLASSES`
|Маршрут к архиву, который содержит файлы классов JDK, [.filename]#${JAVA_HOME}/jre/lib/rt.jar#.
|===

Вы можете воспользоваться make-целью `java-debug` для получения информации, необходимой для отладки вашего порта. При её выполнении будут выданы значения многих упомянутых выше переменных.

Кроме того, для единообразия установки всех портов Java определены следующие константы:

.Константы, определённые для портов, использующих Java
[cols="1,1", frame="none", options="header"]
|===
| Константа
| Значение

|`JAVASHAREDIR`
|Корневой каталог для всего, что связано с Java. По умолчанию: [.filename]#${PREFIX}/shared/java#.

|`JAVAJARDIR`
|Каталог, в который должны устанавливаться JAR-файлы. По умолчанию: [.filename]#${JAVASHAREDIR}/classes#.

|`JAVALIBDIR`
|Каталог, в который устанавливаются JAR-файлы из других портов. По умолчанию: [.filename]#${LOCALBASE}/shared/java/classes#.
|===

Соответствующие записи определяются в обоих переменных `PLIST_SUB` (описана в <<plist-sub>>) и `SUB_LIST`.

[[java-building-with-ant]]
=== Построение с Ant

Если построение порта производится с использованием Apache Ant, то необходимо определить `USE_ANT`. Таким образом Ant становится подкомандой make. Если в порте не определена цель `do-build`, то будет установлена цель по умолчанию, которая просто запускает Ant в соответствии со значением `MAKE_ENV`, `MAKE_ARGS` и `ALL_TARGET`. Это похоже на механизм `USES= gmake`, который описан в <<building>>.

[[java-best-practices]]
=== Практические рекомендации

При портировании Java-библиотеки ваш порт должен устанавливать JAR-файл(ы) в каталог [.filename]#${JAVAJARDIR}#, а все остальные данные в каталог [.filename]#${JAVASHAREDIR}/${PORTNAME}# (за исключением документации, о которой пойдёт речь ниже). Для уменьшения размера упакованного файла вы можете сослаться на JAR-файл(ы) непосредственно в файле [.filename]#Makefile#. Просто воспользуйтесь следующей директивой (в которой [.filename]#myport.jar# является именем JAR-файла, устанавливаемого как часть порта):

[.programlisting]
....
PLIST_FILES+=	%%JAVAJARDIR%%/myport.jar
....

При портировании Java-приложения порт обычно устанавливает всё в один каталог (в том числе все свои JAR-зависимости). В этом отношении настоятельно рекомендуется использование [.filename]#${JAVASHAREDIR}/${PORTNAME}#. На усмотрение создателя порта остаётся решение вопроса о том, устанавливать ли дополнительные JAR-зависимости в этот каталог или напрямую использовать уже установленные (из каталога [.filename]#${JAVAJARDIR}#).

При портировании приложения Java(TM), для запуска сервиса которого требуется сервер приложений, такой как package:www/tomcat7[], для производителя в порядке вещей является распространение файла [.filename]#.war#. Файл [.filename]#.war# - это Веб-приложение АРхивированное и оно распаковывается при вызове данным приложением. Избегайте добавлять файлы [.filename]#.war# в [.filename]#pkg-plist#. Это не является наилучшим решением. Сервер приложений производит расширение архива [.filename]#war# без должной его очистки при удалении порта. Более подходящим способом работы с этим файлом будет распаковать архив, установить файлы и добавить их в [.filename]#pkg-plist#.

[.programlisting]
....
TOMCATDIR=	${LOCALBASE}/apache-tomcat-7.0
WEBAPPDIR=	myapplication

post-extract:
	@${MKDIR} ${WRKDIR}/${PORTDIRNAME}
	@${TAR} xf ${WRKDIR}/myapplication.war -C ${WRKDIR}/${PORTDIRNAME}

do-install:
	cd ${WRKDIR} && \
	${INSTALL} -d -o ${WWWOWN} -g ${WWWGRP} ${TOMCATDIR}/webapps/${PORTDIRNAME}
	@cd ${WRKDIR}/${PORTDIRNAME} && ${COPYTREE_SHARE} \* ${WEBAPPDIR}/${PORTDIRNAME}
....

Вне зависимости от типа вашего порта (библиотека это или приложение), дополнительная документация должна устанавливаться <<install-documentation,в тоже самое место>>, что и для других портов. Известно, что в зависимости от используемой версии JDK утилита JavaDoc генерирует различные наборы файлов. Для портов, которые не привязаны к использованию определённой версии JDK, таким образом становится проблематичным определить список файлов для упаковки ([.filename]#pkg-plist#). Это одна из причин, по которой создателям портов настоятельно рекомендуется использовать макрос `PORTDOCS`. Более того, даже если вы сможете угадать набор файлов, который будет сгенерирован утилитой `javadoc`, размер получающегося файла [.filename]#pkg-plist# голосует за использование `PORTDOCS`.

Значением по умолчанию для переменной `DATADIR` является [.filename]#${PREFIX}/shared/${PORTNAME}#. Хорошей идеей является переопределение для Java-портов значения `DATADIR` как [.filename]#${JAVASHAREDIR}/${PORTNAME}#. На самом деле `DATADIR` автоматически добавляется к `PLIST_SUB` (это описано в <<plist-sub>>), так что вы сможете использовать `%%DATADIR%%` непосредственно в [.filename]#pkg-plist#.

Что касается выбора между построением портов Java из исходных текстов или их прямой установкой из бинарных дистрибутивов, то на момент создания этого текста определённой политики на этот счёт не существует. Однако участники http://www.freebsd.org/java/[Проекта FreeBSD Java] рекомендуют создателям портов строить их из исходных текстов, если эта задача является несложной.

Все возможности, которые были описаны в этом разделе, реализованы в файле [.filename]#bsd.java.mk#. Если вы предположите, что вашему порту требуется менее тривиальная поддержка Java, пожалуйста, взгляните сначала на http://svnweb.FreeBSD.org/ports/head/Mk/bsd.java.mk?view=markup[журнал изменений bsd.java.mk в Subversion], так как для документирования последних изменений требуется какое-то время. Затем, если вы думаете, что не хватающая вам поддержка окажется полезной для многих других портов Java, обсудите ваш вопрос в freebsd-java.

Хотя в базе сообщений об ошибках для соответствующих PR имеется категория `java`, она относится к работе над портированием JDK, которые проводит Проект FreeBSD Java. Таким образом, вы должны относить свой Java-порт, как и любой другой, к категории `ports`, если решаемый вами вопрос не относится ни к реализации JDK, ни к [.filename]#bsd.java.mk#.

Похожим образом определена политика по отношению к `CATEGORIES` порта Java, которая подробно описана в <<makefile-categories>>.

[[using-php]]
== Веб-приложения, Apache и PHP

[[using-apache]]
=== Apache

.Переменные для портов, использующих Apache
[cols="1,1", frame="none"]
|===
|`USE_APACHE`
|Порт требует Apache. Возможные значения: `yes` (берёт любую версию), `22`, `24`, `22-24`, `22+` и так далее. Версия по умолчанию `22`. Более подробная информация содержится в файле [.filename]#ports/Mk/bsd.apache.mk# и на странице http://wiki.freebsd.org/Apache/[wiki.freebsd.org/Apache/].

|`APXS`
|Полный путь к исполняемому файлу `apxs`. Может быть переопределен в вашем порту.

|`HTTPD`
|Полный путь к исполняемому файлу `httpd`. Может быть переопределен в вашем порту.

|`APACHE_VERSION`
|Версия установленного Apache (переменная только для чтения). Эта переменная доступна только после подключения [.filename]#bsd.port.pre.mk#. Возможные значения: `22`, `24`.

|`APACHEMODDIR`
|Каталог для модулей Apache. Значение переменной автоматически подставляется в [.filename]#pkg-plist#.

|`APACHEINCLUDEDIR`
|Каталог для заголовков Apache. Значение переменной автоматически подставляется в [.filename]#pkg-plist#.

|`APACHEETCDIR`
|Каталог для конфигурационных файлов Apache. Значение переменной автоматически подставляется в [.filename]#pkg-plist#.
|===

.Используемые переменные при портировании модулей Apache
[cols="1,1", frame="none"]
|===
|`MODULENAME`
|Название модуля. Значением по умолчанию является `PORTNAME`. Пример: `mod_hello`

|`SHORTMODNAME`
|Краткое название модуля. Наследуется автоматически от `MODULENAME`, но может быть переопределено. Пример: `hello`

|`AP_FAST_BUILD`
|Использовать `apxs` для компиляции и установки модуля.

|`AP_GENPLIST`
|Также автоматически создает [.filename]#pkg-plist#.

|`AP_INC`
|Добавляет каталог к пути поиска заголовков во время компиляции.

|`AP_LIB`
|Добавляет каталог к пути поиска библиотек во время компиляции.

|`AP_EXTRAS`
|Дополнительные флаги, передаваемые `apxs`.
|===

[[web-apps]]
=== Веб-приложения

Веб-приложения следует устанавливать в [.filename]#PREFIX/www/appname#. Для вашего удобства этот путь одинаково доступен в [.filename]#Makefile# и [.filename]#pkg-plist# как переменная `WWWDIR`, а путь относительно `PREFIX` доступен в [.filename]#Makefile# как `WWWDIR_REL`.

Пользователь и группа процесса веб-сервера доступны как `WWWOWN` и `WWWGRP`, в случае если вам нужно изменить владельца для некоторых файлов. Значением по умолчанию и для владельца, и для группы является `www`. Если вы хотите использовать в вашем порте другие значения, воспользуйтесь для этого нотацией `WWWOWN?= myuser`, чтобы позволить пользователю легко переопределить их.

Не добавляйте зависимость от Apache, если веб-приложение явным образом не нуждается в Apache. Учитывайте, что пользователи могут пожелать запустить ваше веб-приложение на другом веб-сервере помимо Apache.

[[php-variables]]
=== PHP

.Переменные для портов, использующих PHP
[cols="1,1", frame="none"]
|===
|`USE_PHP`
|Порт требует PHP. Значение `yes` добавляет зависимость от PHP. Вместо этого может быть указан перечень требуемых расширений PHP. Пример: `pcre xml gettext`

|`DEFAULT_PHP_VER`
|Выбирает старший номер версии, с которым будет установлен PHP как зависимость в случае, когда PHP еще не установлен. По умолчанию `5`. Возможные значения: `4`, `5`

|`IGNORE_WITH_PHP`
|Порт не работает с PHP данной версии. Возможные значения: `4`, `5`

|`USE_PHPIZE`
|Порт будет построен как расширение PHP.

|`USE_PHPEXT`
|Порт будет считаться расширением PHP, включая установку и регистрацию в реестре расширений.

|`USE_PHP_BUILD`
|Установить PHP как зависимость времени построения.

|`WANT_PHP_CLI`
|Хочет CLI (командная строка) версию PHP.

|`WANT_PHP_CGI`
|Хочет CGI версию PHP.

|`WANT_PHP_MOD`
|Хочет PHP как модуль Apache.

|`WANT_PHP_SCR`
|Хочет CLI или CGI версию PHP.

|`WANT_PHP_WEB`
|Хочет модуль Apache или CGI версию PHP.
|===

=== Модули PEAR

Портирование модулей PEAR является очень простым процессом.

Используйте переменные `FILES`, `TESTS`, `DATA`, `SQLS`, `SCRIPTFILES`, `DOCS` and `EXAMPLES` для перечисления файлов, которые вы хотите установить. Все перечисленные файлы будут автоматически установлены в подходящие места и добавлены в [.filename]#pkg-plist#.

Подключите [.filename]#${PORTSDIR}/devel/pear/bsd.pear.mk# на последней строке [.filename]#Makefile#.

[[pear-makefile]]
.Пример Makefile для классов PEAR
[example]
====
[.programlisting]
....
PORTNAME=	Date
PORTVERSION=	1.4.3
CATEGORIES=	devel www pear

MAINTAINER=	example@domain.com
COMMENT=	PEAR Date and Time Zone Classes

BUILD_DEPENDS=	${PEARDIR}/PEAR.php:${PORTSDIR}/devel/pear-PEAR
RUN_DEPENDS:=	${BUILD_DEPENDS}

FILES=		Date.php Date/Calc.php Date/Human.php Date/Span.php     \
		Date/TimeZone.php
TESTS=		test_calc.php test_date_methods_span.php testunit.php   \
		testunit_date.php testunit_date_span.php wknotest.txt   \
		bug674.php bug727_1.php bug727_2.php bug727_3.php       \
		bug727_4.php bug967.php weeksinmonth_4_monday.txt       \
		weeksinmonth_4_sunday.txt weeksinmonth_rdm_monday.txt   \
		weeksinmonth_rdm_sunday.txt
DOCS=		TODO
_DOCSDIR=	.

.include <bsd.port.pre.mk>
.include "${PORTSDIR}/devel/pear/bsd.pear.mk"
.include <bsd.port.post.mk>
....

====

[[using-python]]
== Использование Python

Коллекция Портов поддерживает параллельную установку множества версий Python. Следует убедиться, что в портах используется правильный интерпретатор `python` в соответствии с переменной `PYTHON_VERSION`, установленной пользователем. По большей части это означает замену пути к исполняемому файлу `python` в сценариях на значение переменной `PYTHON_CMD`.

Порты, устанавливающие файлы под каталог `PYTHON_SITELIBDIR`, должны использовать префикс вида `pyXY-`, таким образом названия пакетов будут включать в себя версию Python, с которой они установлены.

[.programlisting]
....
PKGNAMEPREFIX=	${PYTHON_PKGNAMEPREFIX}
....

.Переменные для портов, которые используют Python
[cols="1,1", frame="none"]
|===
|`USE_PYTHON`
|Для этого порта нужен Python. Минимальная требуемая версия может быть указана с таким значением как `2.6+`. Также можно указан диапазон версий с разделением двух версий через -, например: `2.6-2.7`

|`USE_PYDISTUTILS`
|Использовать дистрибутивные утилиты (distutils) Python для конфигурации, компиляции и установки. Необходимо, если порт использует [.filename]#setup.py#. Переопределяет цели `do-build` и `do-install` и также может переопределять `do-configure`, если не определена `GNU_CONFIGURE`.

|`PYTHON_PKGNAMEPREFIX`
|Используется как `PKGNAMEPREFIX` для отличия пакетов, использующих разные версии Python. Пример: `py24-`

|`PYTHON_SITELIBDIR`
|Местонахождение дерева site-packages, которое содержит путь установки Python (обычно, `LOCALBASE`). Переменная `PYTHON_SITELIBDIR` может быть очень полезной при установке модулей Python.

|`PYTHONPREFIX_SITELIBDIR`
|Вариант PYTHON_SITELIBDIR без PREFIX. По возможности всегда используйте `%%PYTHON_SITELIBDIR%%` в [.filename]#pkg-plist#. Значением по умолчанию для `%%PYTHON_SITELIBDIR%%` является `lib/python%%PYTHON_VERSION%%/site-packages`.

|`PYTHON_CMD`
|Командная строка интерпретатора Python, включая номер версии.

|`PYNUMERIC`
|Строка зависимости для расширения numeric.

|`PYNUMPY`
|Строка зависимости для нового расширения numeric, numpy (PYNUMERIC объявлен устаревшим вышестоящим производителем).

|`PYXML`
|Строка зависимости для расширения XML (не нужно для Python 2.0 и выше, т.к. включено в основной дистрибутив).
|===

Полный перечень доступных переменных можно найти в [.filename]#/usr/ports/Mk/bsd.python.mk#.

Некоторые приложения на Python заявляют о поддержке `DESTDIR` (требуется для staging), которая не работает (в частности, у Mailman до версии 2.1.16). Ограничение можно обойти путём перекомпиляции сценариев. Например, это можно выполнить в цели `post-build`. С учётом того, что после установки предполагаемое место размещения сценариев Python будет находиться в `PYTHONPREFIX_SITELIBDIR`, можно применить следующее решение:

[.programlisting]
....
(cd ${STAGEDIR}${PREFIX} \
  && ${PYTHON_CMD} ${PYTHON_LIBDIR}/compileall.py \
   -d ${PREFIX} -f ${PYTHONPREFIX_SITELIBDIR:S;${PREFIX}/;;})
....

Эта команда перекомпилирует исходный текст с заменой путей на относительные к каталогу сборки, а также дописывает значение `PREFIX` перед именем файла, записанного в выходном файле с промежуточным представлением, с использованием `-d`. `-f` требуется для безусловной перекомпиляции, `:S;${PREFIX}/;;` удаляет префиксы из значения переменной `PYTHONPREFIX_SITELIBDIR`, чтобы сделать его относительным к `PREFIX`.

Для этого требуется Python 2.7 или выше. Это не работает с Python 2.6.

[[using-tcl]]
== Использование Tcl/Tk

В Коллекции Портов поддерживается одновременная установка множественных версий Tcl/Tk. Порты должны пытаться поддерживать по крайней мере версию Tcl/Tk, используемую по умолчанию, и выше с помощью переменных `USE_TCL` и `USE_TK`. Желаемую версию `tcl` можно указать в переменной `WITH_TCL_VER`.

.Наиболее востребованные переменные для портов, которые используют Tcl/Tk
[cols="1,1", frame="none"]
|===
|`USE_TCL`
|Порт зависит от библиотеки Tcl (не оболочки). Минимальную требуемую версию можно указать с использованием таких значений, как 84+. Отдельные неподдерживаемые версии указываются в переменной `INVALID_TCL_VER`.

|`USE_TCL_BUILD`
|Tcl нужен для порта только на время сборки.

|`USE_TCL_WRAPPER`
|Эту новую переменную следует использовать для портов, для которых требуется оболочка Tcl и не требуется конкретная версия `tclsh`. Обертка `tclsh` устанавливается в систему. Пользователь может указать желаемую оболочку `tcl` для использования.

|`WITH_TCL_VER`
|Определяемые пользователем переменные, которые устанавливают желаемую версию Tcl.

|`UNIQUENAME_WITH_TCL_VER`
|Подобно `WITH_TCL_VER`, но для каждого порта.

|`USE_TCL_THREADS`
|Требует многопоточную сборку Tcl/Tk.

|`USE_TK`
|Порт зависит от библиотеки Tk (не от предпочитаемой оболочки). Подразумевает `USE_TCL` с тем же значением. Для большей информации смотрите описание переменной `USE_TCL`.

|`USE_TK_BUILD`
|Аналогично `USE_TCL_BUILD`.

|`USE_TK_WRAPPER`
|Аналогично `USE_TCL_WRAPPER`.

|`WITH_TK_VER`
|Аналогично `WITH_TCL_VER`, подразумевает `WITH_TCL_VER` той же версии.
|===

Полный перечень доступных переменных находится в [.filename]#/usr/ports/Mk/bsd.tcl.mk#.

[[using-emacs]]
== Использование Emacs

Этот раздел ещё предстоит написать.

[[using-ruby]]
== Использование Ruby

.Полезные переменные для портов, использующих Ruby
[cols="1,1", frame="none", options="header"]
|===
| Переменная
| Описание

|`USE_RUBY`
|Порт требует Ruby.

|`USE_RUBY_EXTCONF`
|Порт использует для конфигурации [.filename]#extconf.rb#.

|`USE_RUBY_SETUP`
|Порт использует для конфигурации [.filename]#setup.rb#.

|`RUBY_SETUP`
|Устанавливает альтернативное имя для [.filename]#setup.rb#. Распространенным значением является [.filename]#install.rb#.
|===

Следующая таблица отражает некоторые переменные, доступные авторам портов через инфраструктуру портов. Эти переменные должны использоваться для установки файлов в правильное месторасположение. Используйте их в [.filename]#pkg-plist# как можно больше. Эти переменные не должны переопределяться в самом порте.

.Отобранные переменные только для чтения для портов, использующих Ruby
[cols="1,1,1", frame="none", options="header"]
|===
| Переменная
| Описание
| Примерное значение

|`RUBY_PKGNAMEPREFIX`
|Используется как `PKGNAMEPREFIX` для различия пакетов от разных версий Ruby.
|`ruby18-`

|`RUBY_VERSION`
|Полная версия Ruby в форме `x.y.z`.
|`1.8.2`

|`RUBY_SITELIBDIR`
|Путь для установки архитектуронезависимых библиотек.
|`/usr/local/lib/ruby/site_ruby/1.8`

|`RUBY_SITEARCHLIBDIR`
|Путь для установки архитектурозависимых библиотек.
|`/usr/local/lib/ruby/site_ruby/1.8/amd64-freebsd6`

|`RUBY_MODDOCDIR`
|Путь для установки документации модуля.
|`/usr/local/shared/doc/ruby18/patsy`

|`RUBY_MODEXAMPLESDIR`
|Путь для установки примеров модуля.
|`/usr/local/shared/examples/ruby18/patsy`
|===

Полный перечень доступных переменных находится в [.filename]#/usr/ports/Mk/bsd.ruby.mk#.

[[using-sdl]]
== Использование SDL

Переменная `USE_SDL` используется для автоматической настройки зависимостей для портов, использующих библиотеки на основе SDL, такие как package:devel/sdl12[] или package:graphics/sdl_image[].

Для версии 1.2 на данный момент распознаются следующие SDL-библиотеки:

* sdl: package:devel/sdl12[]
* console: package:devel/sdl_console[]
* gfx: package:graphics/sdl_gfx[]
* image: package:graphics/sdl_image[]
* mixer: package:audio/sdl_mixer[]
* mm: package:devel/sdlmm[]
* net: package:net/sdl_net[]
* pango: package:x11-toolkits/sdl_pango[]
* sound: package:audio/sdl_sound[]
* ttf: package:graphics/sdl_ttf[]

Для версии 2.0 на данный момент распознаются следующие SDL-библиотеки:

* sdl: package:devel/sdl20[]
* gfx: package:graphics/sdl2_gfx[]
* image: package:graphics/sdl2_image[]
* mixer: package:audio/sdl2_mixer[]
* net: package:net/sdl2_net[]
* ttf: package:graphics/sdl2_ttf[]

Таким образом, если порт имеет зависимость от package:net/sdl_net[] и package:audio/sdl_mixer[], то строка будет следующей:

[.programlisting]
....
USE_SDL=	net mixer
....

Зависимость от порта package:devel/sdl12[], который требуется для package:net/sdl_net[] и package:audio/sdl_mixer[], будет также автоматически добавлен.

Если вы используете `USE_SDL` с элементами SDL 1.2, то он автоматически:

* Добавляет зависимость от sdl12-config к `BUILD_DEPENDS`
* Добавляет переменную `SDL_CONFIG` к `CONFIGURE_ENV`
* Добавляет зависимости от указанных библиотек к `LIB_DEPENDS`

Если вы используете `USE_SDL` с элементами SDL 2.0, то он автоматически:

* Добавляет зависимость от sdl2-config к `BUILD_DEPENDS`
* Добавляет переменную `SDL2_CONFIG` к `CONFIGURE_ENV`
* Добавляет зависимости от указанных библиотек к `LIB_DEPENDS`

Для проверки наличия библиотеки SDL вы можете делать это при помощи переменной `WANT_SDL`:

[.programlisting]
....
WANT_SDL=	yes

.include <bsd.port.pre.mk>

.if ${HAVE_SDL:Mmixer}!=""
USE_SDL+=	mixer
.endif

.include <bsd.port.post.mk>
....

[[using-wx]]
== Использование wxWidgets

Эта глава описывает статус библиотек wxWidgets в дереве портов и их интеграцию с системой портов.

[[wx-introduction]]
=== Введение

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

Очевидным недостатком этого является необходимость изменения каждого приложения для нахождения искомой версии. К счастью, большинство приложений для определения нужного компилятора и флагов компоновки вызывают сценарий `wx-config`. Для каждой доступной версии этот сценарий имеет своё имя. Большинство приложений учитывают переменную окружения или принимают аргумент configure для указания, какой сценарий `wx-config` следует вызывать. На все остальные приходится накладывать патч.

[[wx-version]]
=== Выбор версии

Для того, чтобы заставить ваш порт использовать конкретную версию wxWidgets, существует две доступные для определения переменные (если определена только одна, то вторая примет значение по умолчанию):

[[wx-ver-sel-table]]
.Переменные для выбора версии wxWidgets
[cols="1,1,1", frame="none", options="header"]
|===
| Переменная
| Описание
| Значение по умолчанию

|`USE_WX`
|Перечень версий, которые порт может использовать
|Все доступные версии

|`USE_WX_NOT`
|Перечень версий, которые порт не может использовать
|Нет
|===

Перечень доступных версий wxWidgets и соответствующих им портов в дереве:

.Доступные версии wxWidgets
[cols="1,1", frame="none", options="header"]
|===
| Версия
| Порт

|`2.4`
|package:x11-toolkits/wxgtk24[]

|`2.6`
|package:x11-toolkits/wxgtk26[]

|`2.8`
|package:x11-toolkits/wxgtk28[]
|===

[NOTE]
====
Версии начиная с `2.5` также поставляются с Unicode и устанавливается подчиненным портом с названием как как у обычного, но с суффиксом `-unicode`, но этим можно управлять при помощи переменных (смотрите <<wx-unicode>>).
====

Переменные в <<wx-ver-sel-table>> можно установить в одну или более следующих комбинаций, разделенных пробелами:

.Определение версии для wxWidgets
[cols="1,1", frame="none", options="header"]
|===
| Описание
| Пример

|Единичная версия
|`2.4`

|Восходящий диапазон
|`2.4+`

|Нисходящий диапазон
|`2.6-`

|Полный диапазон (обязан быть восходящим)
|`2.4-2.6`
|===

Кроме того, существует несколько переменных для выбора предпочитаемых версий из перечня доступных. Они могут быть установлены в несколько версий, первая из которых будет иметь наибольший приоритет.

.Переменные для выбора предпочитаемых версий wxWidgets
[cols="1,1", frame="none", options="header"]
|===
| Название
| Предназначение

|`WANT_WX_VER`
|порт

|`WITH_WX_VER`
|пользователь
|===

[[wx-components]]
=== Выбор компонентов

Существуют другие приложения, которые, хотя и не являются библиотеками wxWidgets, но в тоже время относятся к ним. Эти приложения можно указать в переменной `WX_COMPS`. Доступны следующие компоненты:

.Доступные компоненты wxWidgets
[cols="1,1,1", frame="none", options="header"]
|===
| Название
| Описание
| Ограничение версии

|`wx`
|основная библиотека
|нет

|`contrib`
|сторонние библиотеки
|`нет`

|`python`
|wxPython (привязки к Python)
|`2.4-2.6`

|`mozilla`
|wxMozilla
|`2.4`

|`svg`
|wxSVG
|`2.6`
|===

Тип добавляемой зависимости при выборе каждого компонента может быть указан вручную путем добавления суффикса, отделенного точкой с запятой. Если таковой отсутствует, но будет использовано значение по умолчанию (смотрите <<wx-def-dep-types>>). Доступные типы зависимости:

.Доступные типы зависимости wxWidgets
[cols="1,1", frame="none", options="header"]
|===
| Название
| Описание

|`build`
|Компонент требуется для построения, эквивалентен `BUILD_DEPENDS`

|`run`
|Компонент требуется для запуска, эквивалентен `RUN_DEPENDS`

|`lib`
|Компонент требуется для построения и запуска, эквивалентен `LIB_DEPENDS`
|===

Значения по умолчанию для компонентов подробно рассматриваются в следующей таблице:

[[wx-def-dep-types]]
.Типы зависимости wxWidgets, используемые по умолчанию
[cols="1,1", frame="none", options="header"]
|===
| Компонент
| Тип зависимости

|`wx`
|`lib`

|`contrib`
|`lib`

|`python`
|`run`

|`mozilla`
|`lib`

|`svg`
|`lib`
|===

[[wx-components-example]]
.Выбор компонентов wxWidgets
[example]
====
Следующий фрагмент относится к порту, в котором используется wxWidgets версии `2.4` с его сторонними библиотеками.

[.programlisting]
....
USE_WX=		2.4
WX_COMPS=	wx contrib
....

====

[[wx-unicode]]
=== Unicode

Библиотека wxWidgets поддерживает Unicode начиная с версии `2.5`. В дереве портов доступны обе версии и могут быть выбраны с использованием следующих переменных:
[[wx-unicode-var-table]]
.Переменные для выбора версии wxWidgets с Unicode
[cols="1,1,1", frame="none", options="header"]
|===
| Переменная
| Описание
| Предназначение

|`WX_UNICODE`
|Порт работает _только_ с версией Unicode
|порт

|`WANT_UNICODE`
|Порт работает с обеими версиями, но предпочитает версию с Unicode
|порт

|`WITH_UNICODE`
|Порт будет использовать версию Unicode
|пользователь

|`WITHOUT_UNICODE`
|Порт будет использовать обычную версию, если это поддерживается (когда `WX_UNICODE` не определена)
|пользователь
|===

[WARNING]
====

Не используйте `WX_UNICODE` для портов, которые могут использовать обе версии. Если вы хотите, чтобы порт по умолчанию использовал Unicode, определите вместо этого `WANT_UNICODE`.
====

[[wx-version-detection]]
=== Обнаружение установленных версий

Для обнаружения установленной версии вам необходимо задать переменную `WANT_WX`. Если вы не присвоите ей определенную версию, то компоненты получат суффикс версии. Переменная `HAVE_WX` будет заполнена после обнаружения.

[[wx-ver-det-example]]
.Обнаружение установленных версий и компонентов wxWidgets
[example]
====
Следующий фрагмент может быть использован в порту, который использует wxWidgets, в случае если он установлен или выбран соответствующий параметр.

[.programlisting]
....
WANT_WX=	yes

.include <bsd.port.pre.mk>

.if defined(WITH_WX) || !empty(PORT_OPTIONS:MWX) || !empty(HAVE_WX:Mwx-2.4)
USE_WX=			2.4
CONFIGURE_ARGS+=	--enable-wx
.endif
....

Следующий фрагмент может быть использован в порту, который задействует поддержку wxPython, в случае если он установлен или выбран соответствующий параметр, в дополнение к wxWidgets, обе версии `2.6`.

[.programlisting]
....
USE_WX=		2.6
WX_COMPS=	wx
WANT_WX=	2.6

.include <bsd.port.pre.mk>

.if defined(WITH_WXPYTHON) || !empty(PORT_OPTIONS:MWXPYTHON) || !empty(HAVE_WX:Mpython)
WX_COMPS+=		python
CONFIGURE_ARGS+=	--enable-wxpython
.endif
....

====

[[wx-defined-variables]]
=== Переменные для определения

Следующие переменные доступны в порту (после определения одной из переменных из <<wx-ver-sel-table>>).

.Переменные, определенные для портов, использующих wxWidgets
[cols="1,1", frame="none", options="header"]
|===
| Название
| Описание

|`WX_CONFIG`
|Путь к сценарию wxWidgets `wx-config` (с другим именем)

|`WXRC_CMD`
|Путь к программе wxWidgets `wxrc` (с другим именем)

|`WX_VERSION`
|Версия wxWidgets, которая будет использоваться (например, `2.6`)

|`WX_UNICODE`
|Если не определена, но Unicode будет использоваться, то она будет определена
|===

[[wx-premk]]
=== Обработка в [.filename]#bsd.port.pre.mk#

Если вам нужно использовать переменные для запуска команд сразу после подключения [.filename]#bsd.port.pre.mk#, то вам нужно определить `WX_PREMK`.

[IMPORTANT]
====
Если вы определите `WX_PREMK`, то версия, зависимости, компоненты и заданные переменные не изменяться, в случае вы изменили переменные порта wxWidgets после подключения [.filename]#bsd.port.pre.mk#.
====

[[wx-premk-example]]
.Использование переменных wxWidgets в командах
[example]
====
Следующий фрагмент иллюстрирует использование переменной `WX_PREMK` посредством запуска сценария `wx-config` для получения строки с полной версией с присвоением ее переменной и передачей в программу.

[.programlisting]
....
USE_WX=		2.4
WX_PREMK=	yes

.include <bsd.port.pre.mk>

.if exists(${WX_CONFIG})
VER_STR!=	${WX_CONFIG} --release

PLIST_SUB+=	VERSION="${VER_STR}"
.endif
....

====

[NOTE]
====
Переменные wxWidgets можно безопасно использовать в командах внутри целей без необходимости в использовании `WX_PREMK`.
====

[[wx-additional-config-args]]
=== Дополнительные параметры `configure`

Некоторые сценарии GNU `configure` не могут найти wxWidgets только с установленной переменной окружения `WX_CONFIG`, требуя дополнительные параметры. Для их передачи можно использовать переменную `WX_CONF_ARGS`.

.Допустимые значения `WX_CONF_ARGS`
[cols="1,1", frame="none", options="header"]
|===
| Возможное значение
| Получаемый параметр

|`absolute`
|`--with-wx-config=${WX_CONFIG}`

|`relative`
|`--with-wx=${LOCALBASE} --with-wx-config=${WX_CONFIG:T}`
|===

[[using-lua]]
== Использование Lua

Эта глава описывает статус библиотек Lua в дереве портов и их интеграцию в систему портов.

[[lua-introduction]]
=== Введение

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

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

[[lua-version]]
=== Выбор версии

Для того, чтобы заставить ваш порт использовать конкретную версию Lua, существует две доступные для определения переменные (если определена только одна, то вторая примет значение по умолчанию):

[[lua-ver-sel-table]]
.Переменные для выбора версии Lua
[cols="1,1,1", frame="none", options="header"]
|===
| Переменная
| Описание
| Значение по умолчанию

|`USE_LUA`
|Перечень версий, которые порт может использовать
|Все доступные версии

|`USE_LUA_NOT`
|Перечень версий, которые порт не может использовать
|Пусто
|===

Перечень доступных версий Lua и соответствующих портов в дереве:

.Доступные версии Lua
[cols="1,1", frame="none", options="header"]
|===
| Версия
| Порт

|`4.0`
|package:lang/lua4[]

|`5.0`
|package:lang/lua50[]

|`5.1`
|package:lang/lua[]
|===

Переменные из <<lua-ver-sel-table>> могут иметь комбинации из одного или нескольких значений, разделенных пробелом:

.Определение версии Lua
[cols="1,1", frame="none", options="header"]
|===
| Описание
| Пример

|Единичная версия
|`4.0`

|Восходящий диапазон
|`5.0+`

|Нисходящий диапазон
|`5.0-`

|Полный диапазон (обязан быть восходящим)
|`5.0-5.1`
|===

Кроме того, существует несколько переменных для выбора предпочитаемых версий из перечня доступных. Они могут быть установлены в несколько версий, первая из которых будет иметь наибольший приоритет.

.Переменные для выбора предпочитаемых версий Lua
[cols="1,1", frame="none", options="header"]
|===
| Название
| Предназначение

|`WANT_LUA_VER`
|порт

|`WITH_LUA_VER`
|пользователь
|===

[[lua-version-example]]
.Выбор версии Lua
[example]
====
Следующий фрагмент взят из порта, который использует Lua версий `5.0` или `5.1`, по умолчанию `5.0`. Значение может быть переопределено пользователем с использованием переменной `WITH_LUA_VER`.

[.programlisting]
....
USE_LUA=	5.0-5.1
WANT_LUA_VER=	5.0
....

====

[[lua-components]]
=== Выбор компонентов

Существуют другие приложения, которые хотя и не являются библиотеками Lua, но относятся к ним. Эти приложения можно указать в переменной `LUA_COMPS`. Доступны следующие компоненты:

.Доступные компоненты Lua
[cols="1,1,1", frame="none", options="header"]
|===
| Название
| Описание
| Ограничение версии

|`lua`
|Основная библиотека
|нет

|`tolua`
|Библиотека доступа к коду C/C++
|4.0-5.0

|`ruby`
|Привязка к Ruby
|4.0-5.0
|===

[NOTE]
====
Есть и другие компоненты, но они относятся к модулям для интерпретатора и не используются приложениями (только другими модулями).
====

Тип зависимости можно выбрать для каждого компонента через добавление суффикса, отделенного точкой с запятой. В случае отсутствия будет использован тип по умолчанию (смотрите <<lua-def-dep-types>>). Доступные следующие типы:

.Доступные типы зависимости Lua
[cols="1,1", frame="none", options="header"]
|===
| Название
| Описание

|`build`
|Компонент требуется для построения, эквивалентен `BUILD_DEPENDS`

|`run`
|Компонент требуется для запуска, эквивалентен `RUN_DEPENDS`

|`lib`
|Компонент требуется для построения и запуска, эквивалентен `LIB_DEPENDS`
|===

Значения по умолчанию для компонентов подробно рассматриваются в следующей таблице:

[[lua-def-dep-types]]
.Типы зависимости Lua, используемые по умолчанию
[cols="1,1", frame="none", options="header"]
|===
| Компонент
| Тип зависимости

|`lua`
|`lib` для `4.0-5.0` (динамическая) и `build` для `5.1` (статическая)

|`tolua`
|`build` (статическая)

|`ruby`
|`lib` (динамическая)
|===

[[lua-components-example]]
.Выбор компонентов Lua
[example]
====
Следующий фрагмент соответствует порту, использующему Lua версии `4.0` и привязку к Ruby.

[.programlisting]
....
USE_LUA=	4.0
LUA_COMPS=	lua ruby
....

====

[[lua-version-detection]]
=== Обнаружение установленных версий

Для обнаружения установленной версии вам необходимо задать переменную `WANT_LUA`. Если вы не присвоите ей определенную версию, то компоненты получат суффикс версии. Переменная `HAVE_LUA` будет заполнена после обнаружения.

[[lua-ver-det-example]]
.Обнаружение установленных версий и компонентов Lua
[example]
====
Следующий фрагмент можно использовать для порта, использующего Lua, если она установлена, или был выбран соответствующий параметр.

[.programlisting]
....
WANT_LUA=	yes

.include <bsd.port.pre.mk>

.if defined(WITH_LUA5) || !empty(PORT_OPTIONS:MLUA5) || !empty(HAVE_LUA:Mlua-5.[01])
USE_LUA=		5.0-5.1
CONFIGURE_ARGS+=	--enable-lua5
.endif
....

Следующий фрагмент можно использовать для порта, который включает поддержку tolua, если такой компонент установлен, или был выбран соответствующий параметр в дополнение к Lua, оба имеют версию `4.0`.

[.programlisting]
....
USE_LUA=	4.0
LUA_COMPS=	lua
WANT_LUA=	4.0

.include <bsd.port.pre.mk>

.if defined(WITH_TOLUA) || !empty(PORT_OPTIONS:MTOLUA) || !empty(HAVE_LUA:Mtolua)
LUA_COMPS+=		tolua
CONFIGURE_ARGS+=	--enable-tolua
.endif
....

====

[[lua-defined-variables]]
=== Переменные для определения

Следующие переменные доступны в порту (после определения одной из переменных из <<lua-ver-sel-table>>).

.Переменные, определенные для портов, использующих Lua
[cols="1,1", frame="none", options="header"]
|===
| Название
| Описание

|`LUA_VER`
|Версия Lua, которая будет использоваться (например, `5.1`)

|`LUA_VER_SH`
|Старший номер версии динамической библиотеки Lua (например, `1`)

|`LUA_VER_STR`
|Версия Lua без точки (например, `51`)

|`LUA_PREFIX`
|Префикс, в который установлена Lua (и компоненты)

|`LUA_SUBDIR`
|Каталог под [.filename]#${PREFIX}/bin#, [.filename]#${PREFIX}/share# и [.filename]#${PREFIX}/lib#, в который установлена Lua

|`LUA_INCDIR`
|Каталог, в который установлены заголовочные файлы Lua и tolua

|`LUA_LIBDIR`
|Каталог, в который установлены библиотеки Lua и tolua

|`LUA_MODLIBDIR`
|Каталог, в который установлены модули библиотеки Lua ([.filename]#.so#)

|`LUA_MODSHAREDIR`
|Каталог, в который установлены модули Lua ([.filename]#.lua#)

|`LUA_PKGNAMEPREFIX`
|Префикс с именем пакета, используемый модулями Lua

|`LUA_CMD`
|Путь к интерпретатору Lua

|`LUAC_CMD`
|Путь к компилятору Lua

|`TOLUA_CMD`
|Путь к программе tolua
|===

[[lua-variables-example]]
.Указание для порта, где искать Lua
[example]
====
Следующий фрагмент показывает, как сообщить порту, который использует сценарий configure, где расположены заголовочные файлы и библиотеки Lua.

[.programlisting]
....
USE_LUA=	4.0
GNU_CONFIGURE=	yes
CONFIGURE_ENV=	CPPFLAGS="-I${LUA_INCDIR}" LDFLAGS="-L${LUA_LIBDIR}"
....

====

[[lua-premk]]
=== Обработка в [.filename]#bsd.port.pre.mk#

Если вам нужно использовать переменные для запуска команд сразу после подключения [.filename]#bsd.port.pre.mk#, для этого вам нужно определить переменную `LUA_PREMK`.

[IMPORTANT]
====
Если вы задаете `LUA_PREMK`, то версия, зависимости, компоненты и уже заданные переменные не будут изменены, в случае если вы изменили переменные порта Lua после подключения [.filename]#bsd.port.pre.mk#.
====

[[lua-premk-example]]
.Использование переменных Lua в командах
[example]
====
Следующий фрагмент иллюстрирует использование `LUA_PREMK` посредством запуска интерпретатора Lua для того, чтобы получить строку с полной версией, сохранить ее в переменную и передать программе.

[.programlisting]
....
USE_LUA=	5.0
LUA_PREMK=	yes

.include <bsd.port.pre.mk>

.if exists(${LUA_CMD})
VER_STR!=	${LUA_CMD} -v

CFLAGS+=	-DLUA_VERSION_STRING="${VER_STR}"
.endif
....

====

[NOTE]
====
Переменные Lua можно безопасно использовать в командах внутри целей без необходимости в использовании `LUA_PREMK`.
====

[[using-iconv]]
== Использование `iconv`

После 10-08-2013 (link:https://svnweb.freebsd.org/changeset/base/254273[r254273]) в составе FreeBSD 10-CURRENT и более новых версий имеется собственный `iconv`. В более ранних версиях дополнительной зависимостью выступал package:converters/libiconv[].

Для программного обеспечения, которому нужен `iconv`, определите `USES=iconv`. Версии FreeBSD до 10-CURRENT от 13-08-2013 (link:https://svnweb.freebsd.org/changeset/base/254273[r254273]) не имеют собственного `iconv`. На этих более ранных версиях будет автоматически добавлена зависимость от package:converters/libiconv[].

Когда порт задаёт `USES=iconv`, становятся доступными следующие переменные:

[.informaltable]
[cols="1,1,1,1", frame="none", options="header"]
|===
| Имя переменной
| Назначение
| Значение до FreeBSD 10-CURRENT 254273 (13-08-2013)
| Значение после FreeBSD 10-CURRENT 254273 (13-08-2013)

|`ICONV_CMD`
|Каталог размещения двоичного файла `iconv`
|`${LOCALBASE}/bin/iconv`
|[.filename]#/usr/bin/iconv#

|`ICONV_LIB`
|Аргумент `ld` для компоновки с [.filename]#libiconv# (если нужно)
|`-liconv`
|(пусто)

|`ICONV_PREFIX`
|Каталог размещения реализации `iconv` (используется для сценариев конфигурации)
|`${LOCALBASE}`
|[.filename]#/usr#

|`ICONV_CONFIGURE_ARG`
|Параметр предварительно собранной конфигурации для сценариев конфигурации
|`--with-libiconv-prefix=${LOCALBASE}`
|(пусто)

|`ICONV_CONFIGURE_BASE`
|Параметр предварительно собранной конфигурации для сценариев конфигурации
|`--with-libiconv=${LOCALBASE}`
|(пусто)
|===

В следующих двух примерах демонстрируется автоматическое присвоение переменным правильных значений для систем, использующих package:converters/libiconv[] или собственный `iconv`.

[[iconv-simple-use]]
.Простое использование `iconv`
[example]
====
[.programlisting]
....
USES=		iconv
LDFLAGS+=	-L${LOCALBASE}/lib ${ICONV_LIB}
....

====

[[iconv-configure-use]]
.Использование `iconv` с `configure`
[example]
====
[.programlisting]
....
USES=		iconv
CONFIGURE_ARGS+=${ICONV_CONFIGURE_ARG}
....

====

Как показано выше, `ICONV_LIB` имеет пустое значение с собственным `iconv`. Эту особенность можно использовать для обнаружения собственного `iconv` с соответствующими действиями.

Иногда в программе параметр `ld` или путь поиска жёстко заданы в [.filename]#Makefile# или сценарии конфигурации. Для решения этой проблемы можно использовать следующий подход:

[[iconv-reinplace]]
.Исправление жёстко заданного `-liconv`
[example]
====
[.programlisting]
....
USES=		iconv

post-patch:
	@${REINPLACE_CMD} -e 's/-liconv/${ICONV_LIB}/' ${WRKSRC}/Makefile
....

====

В некоторых случаях необходимо установить альтернативные значения или выполнить операции в случае использования собственного `iconv`. Перед проверкой значения `ICONV_LIB` обязан быть подключён [.filename]#bsd.port.pre.mk#:

[[iconv-conditional]]
.Проверка доступности собственного `iconv`
[example]
====
[.programlisting]
....
USES=		iconv

.include <bsd.port.pre.mk>

post-patch:
.if empty(ICONV_LIB)
	# обнаружен собственный iconv
	@${REINPLACE_CMD} -e 's|iconv||' ${WRKSRC}/Config.sh
.endif

.include <bsd.port.post.mk>
....

====

[[using-xfce]]
== Использование Xfce

Переменная `USE_XFCE` используется для автоматической конфигурации зависимостей для портов, использующих библиотеки или приложения на основе Xfce, такие как package:x11-toolkits/libxfce4gui[] и package:x11-wm/xfce4-panel[].

В настоящее время распознаются следующие библиотеки и приложения Xfce:

* libexo: package:x11/libexo[]
* libgui: package:x11-toolkits/libxfce4gui[]
* libutil: package:x11/libxfce4util[]
* libmcs: package:x11/libxfce4mcs[]
* mcsmanager: package:sysutils/xfce4-mcs-manager[]
* panel: package:x11-wm/xfce4-panel[]
* thunar: package:x11-fm/thunar[]
* wm: package:x11-wm/xfce4-wm[]
* xfdev: package:dev/xfce4-dev-tools[]

Распознаются следующие дополнительные параметры:

* configenv: Используйте, если ваш порт требует специально измененного значения `CONFIGURE_ENV` для поиска требуемых для порта библиотек.
+
[.programlisting]
....
-I${LOCALBASE}/include -L${LOCALBASE}/lib
....

+ 
добавляется в CPPFLAGS к `CONFIGURE_ENV`.

Следовательно, если у порта имеется зависимость от package:sysutils/xfce4-mcs-manager[], и порт требует специальных CPPFLAGS в своем окружении configure, то синтаксис будет следующим:

[.programlisting]
....
USE_XFCE=	mcsmanager configenv
....

[[using-mozilla]]
== Использование Mozilla

.Переменные для портов, использующих Mozilla
[cols="1,1", frame="none"]
|===
|`USE_GECKO`
|Один из бэкэндов Gecko, с которым может работать порт. Возможные значения: `libxul` ([.filename]#libxul.so#), `seamonkey` ([.filename]#libgtkembedmoz.so#, устаревший, больше не должен использоваться).

|`USE_FIREFOX`
|Для запуска порта требуется Firefox. Возможные значения: `yes` (версия по умолчанию), `40`, `36`, `35`. По умолчанию устанавливает зависимость от версии `40`.

|`USE_FIREFOX_BUILD`
|Для построения порта требуется Firefox. Возможные значения: смотрите USE_FIREFOX. Автоматически устанавливает USE_FIREFOX с присвоением того же значения.

|`USE_SEAMONKEY`
|Для запуска порта требуется SeaMonkey. Возможные значения: `yes` (версия по умолчанию), `20`, `11` (устарело, больше не должно использоваться). По умолчанию устанавливает зависимость от версии `20`.

|`USE_SEAMONKEY_BUILD`
|Для построения порта требуется SeaMonkey. Возможные значения: смотрите USE_SEAMONKEY. Автоматически устанавливает USE_SEAMONKEY с присвоением того же значения.

|`USE_THUNDERBIRD`
|Для запуска порта требуется Thunderbird. Возможные значения: `yes` (версия по умолчанию), `31`, `30` (устарело, больше не должно использоваться). По умолчанию устанавливает зависимость от версии `31`.

|`USE_THUNDERBIRD_BUILD`
|Для построения порта требуется Thunderbird. Возможные значения: смотрите USE_THUNDERBIRD. Автоматически устанавливает USE_THUNDERBIRD с присвоением того же значения.
|===

Полный перечень доступных переменных можно получить в файле [.filename]#/usr/ports/Mk/bsd.gecko.mk#.

[[using-databases]]
== Использование баз данных

.Переменные для портов, использующих базы данных
[cols="1,1", frame="none", options="header"]
|===
| Переменная
| Значение

|`USE_BDB`
|Если переменная установлена в `yes`, добавляет зависимость от порта package:databases/db41[]. Также переменной можно присвоить значения: 2, 3, 40, 41, 42, 43, 44, 46, 47, 48 или 51. Вы можете объявить диапазон принимаемых значений, `USE_BDB`=42+ будет искать установленную версию с наибольшим номером, и, если ничего не установлено, вернется к 42.

|`USE_MYSQL`
|Если переменная установлена в `yes`, добавляет зависимость от порта package:databases/mysql55-client[]. Как связанная переменная, `WANT_MYSQL_VER` может быть установлена в значение 323, 40, 41, 50, 51, 52, 55 или 60.

|`USE_PGSQL`
|Если установлена в `yes`, добавляет зависимость от порта package:databases/postgresql90-client[]. Как связанная переменная, `WANT_PGSQL_VER` может быть установлена в значение 83, 84, 90, 91 или 92. Вы можете указать максимальное и минимальное значения; `WANT_PGSQL_VER=90+` сделает порт зависимым от минимальной версии 9.0.

|`USE_SQLITE`
|Если переменная имеет значение `yes`, добавляет зависимость от порта package:databases/sqlite3[]. Переменная может принимать значения: 3, 2.
|===

Подробнее смотрите в http://svnweb.FreeBSD.org/ports/head/Mk/bsd.database.mk?view=markup[bsd.database.mk].

[[rc-scripts]]
== Запуск и остановка служб (сценарии `rc`)

Сценарии [.filename]#rc.d# используются для запуска служб при запуске системы и дают администратору стандартный способ остановки, запуска и перезапуска службы. Порты интегрируются в системную инфраструктуру [.filename]#rc.d#. Подробности по её использованию можно найти в link:{handbook}#configtuning-rcd/[главе rc.d Руководства]. Подробное объяснение доступных команд находится в man:rc[8] и man:rc.subr[8]. Наконец, есть link:{rc-scripting}[статья]о практических аспектах написания сценариев [.filename]#rc.d#.

Установить можно один или более сценариев [.filename]#rc.d#:

[.programlisting]
....
USE_RC_SUBR=	doormand
....

Сценарии обязаны размещаться в подкаталоге [.filename]#files# с обязательным добавлением суффикса `.in` к имени файла. Для этого файла будут использоваться стандартные расширения `SUB_LIST`. Также особенно приветствуется использование расширений `%%PREFIX%%` и `%%LOCALBASE%%`. Подробнее о `SUB_LIST` в <<using-sub-files,соответствующей главе>>.

Начиная с FreeBSD 6.1-RELEASE локальные сценарии [.filename]#rc.d# (включая установленные из портов) включены в общий man:rcorder[8] основной системы.

Пример простого сценария [.filename]#rc.d#:

[.programlisting]
....
#!/bin/sh

# $FreeBSD$
#
# PROVIDE: doormand
# REQUIRE: LOGIN
# KEYWORD: shutdown
#
# Add the following lines to /etc/rc.conf.local or /etc/rc.conf
# to enable this service:
#
# doormand_enable (bool):	Set to NO by default.
#				Set it to YES to enable doorman.
# doormand_config (path):	Set to %%PREFIX%%/etc/doormand/doormand.cf
#				by default.

. /etc/rc.subr

name=doormand
rcvar=doormand_enable

load_rc_config $name

: ${doormand_enable:="NO"}
: ${doormand_config="%%PREFIX%%/etc/doormand/doormand.cf"}

command=%%PREFIX%%/sbin/${name}
pidfile=/var/run/${name}.pid

command_args="-p $pidfile -f $doormand_config"

run_rc_command "$1"
....

Если нет стоящей причины запускать службы раньше всех портов, сценарии должны использовать

[.programlisting]
....
REQUIRE: LOGIN
....

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

[.programlisting]
....
KEYWORD: shutdown
....

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

Для необязательных элементов конфигурации присвоение переменной по умолчанию в стиле "=" является более предпочтительным по сравнению со стилем ":=", используемым здесь, поскольку первый устанавливает значение по умолчанию только если переменная не установлена, а последний устанавливает её, если переменная не установлена _или_ обнулена. Пользователь вполне может написать в своем файле [.filename]#rc.conf.local# что-нибудь типа

[.programlisting]
....
doormand_flags=""
....

и тогда произойдет неуместная подстановка переменной с использованием ":=", что переопределит намерения пользователя. Переменная `_enable` является обязательной; значением по умолчанию должно быть ":".

=== Контрольный список перед внесением изменений

Перед тем, как отсылать порт со сценарием [.filename]#rc.d#, и тем более перед его коммитом, сверьтесь со следующим контрольным списком, чтобы убедиться, что порт для этого готов.

Большинство из этих проверок умеет выполнять порт package:devel/rclint[], но это не является заменой надлежащему просмотру.

[.procedure]
====
. Если это новый файл, заканчивается ли он на [.filename]#.sh#? Если это так, то имя файла должно быть изменено на [.filename]#file.in#, поскольку файлы [.filename]#rc.d# не могут оканчиваться на такое расширение.
. Присутствует ли в файле тег `$FreeBSD$`?
. Соответствуют ли друг другу имя файла (без [.filename]#.in#), строка `PROVIDE` и ``$``__name__? Имя файла, совпадающее с `PROVIDE`, упрощает отладку, особенно для проблем, связанных с man:rcorder[8]. Соответствие имени файла и ``$``__name__ также упрощает понимание, какие переменные имеют отношение к сценарию в [.filename]#rc.conf[.local]#. Последнее также является тем, что вы могли бы назвать "политикой" для всех новых сценариев, включая те, что входят в базовую систему.
. Содержит ли строка `REQUIRE` значение LOGIN? Это условие обязательно для сценариев, работающих не из-под суперпользователя. Если сценарий запускается из-под суперпользователя, то стоит ли его запускать до `LOGIN`? Если нет, то его следует запускать после, так чтобы мы могли свободно сгруппировать локальные сценарии в той точке man:rcorder[8], когда почти все сценарии в базовой системе уже стартовали.
. Запускает ли сценарий постоянную службу? Если да, то он должен иметь `KEYWORD: shutdown`.
. Убедитесь в том, что в сценарии отсутствует `KEYWORD: FreeBSD`. Это перестало быть нужным и нежелательно уже много лет. Это также служит индикатором того, что новый сценарий был скопирован со старого, поэтому особое внимание должно быть уделено при проверке.
. Если сценарий использует интерпретируемый язык, такой как `perl`, `python` или `ruby`, то убедитесь, что значение `command_interpreter` установлено должным образом. В противном случае
+
[source,bash]
....
# service name stop
....
+ 
возможно будет работать неправильно. Смотрите man:service[8] для дополнительной информации.
. Все ли вхождения [.filename]#/usr/local# были заменены на `%%PREFIX%%`?
. Идет ли присвоение переменным значений по умолчанию после `load_rc_config`?
. Используются ли пустые строки при присвоении значений по умолчанию? Такие присвоения должны быть удалены, но перепроверьте, что эти параметры задокументированы в комментариях в начале файла.
. Действительно ли в сценариях используются значения, присвоенные переменным?
. Являются ли параметры по умолчанию, перечисленные в __name__``_flags``, обязательными? Если это так, то их следует поместить в `command_args`. Параметр `-d` здесь - это как красный флаг (прошу прощения за каламбур), поскольку обычно он применяется для "демонизации" процесса и поэтому на самом деле обязательный.
. Никогда не включайте переменную __name__``_flags`` в `command_args` (и наоборот; в прочем, такая ошибка встречается реже).
. Запускает ли сценарий какой-либо код безусловно? Это нехорошо. Обычно такие вещи могут/должны помещаться в `start_precmd`.
. Все логические условия должны использовать функцию `checkyesno`. Не пишите самописных проверок для `[Yy][Ee][Ss]`, и так далее.
. Если в сценарии выполняется цикл (например, ожидание чего-либо перед стартом), используется ли счетчик для завершения цикла? Мы не хотим бесконечного ожидания загрузки в случае возникновения ошибки.
. Создает ли сценарий файлы или каталоги, которым нужны особые права доступа? Например, файл [.filename]#pid#, который должен принадлежать пользователю, из-под которого запускается процесс. Вместо традиционных команд man:touch[1]/man:chown[8]/man:chmod[1] подумайте об использовании man:install[1] с подходящими аргументами командной строки, для того чтобы выполнить всю процедуру за один шаг.
====

[[users-and-groups]]
== Добавление пользователей и групп

Некоторые порты требуют в установленной системе наличие определенного пользователя. Выберите свободный UID в диапазоне от 50 до 999 и зарегистрируйте его в [.filename]#ports/UIDs# (для пользователей) и/или в [.filename]#ports/GIDs# (для групп). Удостоверьтесь, что не используете UID, уже используемый системой или другими портами.

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

Затем вы сможете использовать в вашем [.filename]#Makefile# переменные `USERS` и `GROUPS`, и пользователь автоматически создастся при установке порта.

[.programlisting]
....
USERS=	pulse
GROUPS=	pulse pulse-access pulse-rt
....

Текущий перечень зарезервированных UID и GID находится в [.filename]#ports/UIDs# и [.filename]#ports/GIDs#.

[[requiring-kernel-sources]]
== Порты, требующие наличия исходных текстов ядра

Некоторым портам (таким как загружаемые модули ядра) для компиляции нужны файлы с исходными текстами ядра. Ниже указан корректный способ определения, установлены ли они пользователем:

[.programlisting]
....
USES=	kmod
....

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