diff --git a/documentation/content/en/books/porters-handbook/plist/_index.adoc b/documentation/content/en/books/porters-handbook/plist/_index.adoc index 7ee24afc97..57c1a6bf19 100644 --- a/documentation/content/en/books/porters-handbook/plist/_index.adoc +++ b/documentation/content/en/books/porters-handbook/plist/_index.adoc @@ -1,703 +1,696 @@ --- title: Chapter 8. Advanced pkg-plist Practices prev: books/porters-handbook/flavors next: books/porters-handbook/pkg-files description: Advanced pkg-plist Practices tags: ["pkg-plist", "practices", "configuration"] showBookMenu: true weight: 8 path: "/books/porters-handbook/" --- [[plist]] = Advanced pkg-plist Practices :doctype: book :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :sectnumoffset: 8 :partnums: :source-highlighter: rouge :experimental: :images-path: books/porters-handbook/ ifdef::env-beastie[] ifdef::backend-html5[] :imagesdir: ../../../../images/{images-path} endif::[] ifndef::book[] include::shared/authors.adoc[] include::shared/mirrors.adoc[] include::shared/releases.adoc[] include::shared/attributes/attributes-{{% lang %}}.adoc[] include::shared/{{% lang %}}/teams.adoc[] include::shared/{{% lang %}}/mailing-lists.adoc[] include::shared/{{% lang %}}/urls.adoc[] toc::[] endif::[] ifdef::backend-pdf,backend-epub3[] include::../../../../../shared/asciidoctor.adoc[] endif::[] endif::[] ifndef::env-beastie[] toc::[] include::../../../../../shared/asciidoctor.adoc[] endif::[] [[plist-sub]] == Changing pkg-plist Based on Make Variables Some ports, particularly the `p5-` ports, need to change their [.filename]#pkg-plist# depending on what options they are configured with (or version of `perl`, in the case of `p5-` ports). To make this easy, any instances in [.filename]#pkg-plist# of `%%OSREL%%`, `%%PERL_VER%%`, and `%%PERL_VERSION%%` will be substituted appropriately. The value of `%%OSREL%%` is the numeric revision of the operating system (for example, `4.9`). `%%PERL_VERSION%%` and `%%PERL_VER%%` is the full version number of `perl` (for example, `5.8.9`). Several other `%%_VARS_%%` related to port's documentation files are described in crossref:makefiles[install-documentation,the relevant section]. To make other substitutions, set `PLIST_SUB` with a list of `_VAR=VALUE_` pairs and instances of `%%_VAR_%%` will be substituted with _VALUE_ in [.filename]#pkg-plist#. For instance, if a port installs many files in a version-specific subdirectory, use a placeholder for the version so that [.filename]#pkg-plist# does not have to be regenerated every time the port is updated. For example, set: [.programlisting] .... OCTAVE_VERSION= ${PORTREVISION} PLIST_SUB= OCTAVE_VERSION=${OCTAVE_VERSION} .... in the [.filename]#Makefile# and use `%%OCTAVE_VERSION%%` wherever the version shows up in [.filename]#pkg-plist#. When the port is upgraded, it will not be necessary to edit dozens (or in some cases, hundreds) of lines in [.filename]#pkg-plist#. If files are installed conditionally on the options set in the port, the usual way of handling it is prefixing [.filename]#pkg-plist# lines with a `%%OPT%%` for lines needed when the option is enabled, or `%%NO_OPT%%` when the option is disabled, and adding `OPTIONS_SUB=yes` to the [.filename]#Makefile#. See crossref:makefiles[options_sub,`OPTIONS_SUB`] for more information. For instance, if there are files that are only installed when the `X11` option is enabled, and [.filename]#Makefile# has: [.programlisting] .... OPTIONS_DEFINE= X11 OPTIONS_SUB= yes .... In [.filename]#pkg-plist#, put `%%X11%%` in front of the lines only being installed when the option is enabled, like this : [.programlisting] .... %%X11%%bin/foo-gui .... This substitution will be done between the `pre-install` and `do-install` targets, by reading from [.filename]#PLIST# and writing to [.filename]#TMPPLIST# (default: [.filename]#WRKDIR/.PLIST.mktmp#). So if the port builds [.filename]#PLIST# on the fly, do so in or before `pre-install`. Also, if the port needs to edit the resulting file, do so in `post-install` to a file named [.filename]#TMPPLIST#. Another way of modifying a port's packing list is based on setting the variables `PLIST_FILES` and `PLIST_DIRS`. The value of each variable is regarded as a list of pathnames to write to [.filename]#TMPPLIST# along with [.filename]#PLIST# contents. While names listed in `PLIST_FILES` and `PLIST_DIRS` are subject to `%%_VAR_%%` substitution as described above, it is better to use the `${_VAR_}` directly. Except for that, names from `PLIST_FILES` will appear in the final packing list unchanged, while `@dir` will be prepended to names from `PLIST_DIRS`. To take effect, `PLIST_FILES` and `PLIST_DIRS` must be set before [.filename]#TMPPLIST# is written, that is, in `pre-install` or earlier. From time to time, using `OPTIONS_SUB` is not enough. In those cases, adding a specific `_TAG_` to `PLIST_SUB` inside the [.filename]#Makefile# with a special value of `@comment`, makes package tools to ignore the line. For instance, if some files are only installed when the `X11` option is on and the architecture is `i386`: [.programlisting] .... .include .if ${PORT_OPTIONS:MX11} && ${ARCH} == "i386" PLIST_SUB+= X11I386="" .else PLIST_SUB+= X11I386="@comment " .endif .... [[plist-cleaning]] == Empty Directories [[plist-dir-cleaning]] === Cleaning Up Empty Directories When being de-installed, a port has to remove empty directories it created. Most of these directories are removed automatically by man:pkg[8], but for directories created outside of [.filename]#${PREFIX}#, or empty directories, some more work needs to be done. This is usually accomplished by adding `@dir` lines for those directories. Subdirectories must be deleted before deleting parent directories. [.programlisting] .... [...] @dir /var/games/oneko/saved-games @dir /var/games/oneko .... [[plist-dir-empty]] === Creating Empty Directories Empty directories created during port installation need special attention. They must be present when the package is created. If they are not created by the port code, create them in the [.filename]#Makefile#: [.programlisting] .... post-install: ${MKDIR} ${STAGEDIR}${PREFIX}/some/directory .... Add the directory to [.filename]#pkg-plist# like any other. For example: [.programlisting] .... @dir some/directory .... [[plist-config]] == Configuration Files If the port installs configuration files to [.filename]#PREFIX/etc# (or elsewhere) do _not_ list them in [.filename]#pkg-plist#. That will cause `pkg delete` to remove files that have been carefully edited by the user, and a re-installation will wipe them out. Instead, install sample files with a [.filename]#filename.sample# extension. The `@sample` macro automates this, see <> for what it does exactly. For each sample file, add a line to [.filename]#pkg-plist#: [.programlisting] .... @sample etc/orbit.conf.sample .... If there is a very good reason not to install a working configuration file by default, only list the sample filename in [.filename]#pkg-plist#, without the `@sample` followed by a space part, and add a crossref:pkg-files[porting-message,message] pointing out that the user must copy and edit the file before the software will work. [TIP] ==== When a port installs its configuration in a subdirectory of [.filename]#${PREFIX}/etc#, use `ETCDIR`, which defaults to `${PREFIX}/etc/${PORTNAME}`, it can be overridden in the ports [.filename]#Makefile# if there is a convention for the port to use some other directory. The `%%ETCDIR%%` macro will be used in its stead in [.filename]#pkg-plist#. ==== [NOTE] ==== The sample configuration files should always have the [.filename]#.sample# suffix. If for some historical reason using the standard suffix is not possible, or if the sample files come from some other directory, use this construct: [.programlisting] .... @sample etc/orbit.conf-dist etc/orbit.conf .... or [.programlisting] .... @sample %%EXAMPLESDIR%%/orbit.conf etc/orbit.conf .... The format is `@sample _sample-file actual-config-file_`. ==== [[plist-dynamic]] == Dynamic Versus Static Package List A _static package list_ is a package list which is available in the Ports Collection either as [.filename]#pkg-plist# (with or without variable substitution), or embedded into the [.filename]#Makefile# via `PLIST_FILES` and `PLIST_DIRS`. Even if the contents are auto-generated by a tool or a target in the Makefile _before_ the inclusion into the Ports Collection by a committer (for example, using `make makeplist`), this is still considered a static list, since it is possible to examine it without having to download or compile the distfile. A _dynamic package list_ is a package list which is generated at the time the port is compiled based upon the files and directories which are installed. It is not possible to examine it before the source code of the ported application is downloaded and compiled, or after running a `make clean`. While the use of dynamic package lists is not forbidden, maintainers should use static package lists wherever possible, as it enables users to man:grep[1] through available ports to discover, for example, which port installs a certain file. Dynamic lists should be primarily used for complex ports where the package list changes drastically based upon optional features of the port (and thus maintaining a static package list is infeasible), or ports which change the package list based upon the version of dependent software used. For example, ports which generate docs with Javadoc. [[plist-autoplist]] == Automated Package List Creation First, make sure the port is almost complete, with only [.filename]#pkg-plist# missing. Running `make makeplist` will show an example for [.filename]#pkg-plist#. The output of `makeplist` must be double checked for correctness as it tries to automatically guess a few things, and can get it wrong. User configuration files should be installed as [.filename]#filename.sample#, as it is described in <>. [.filename]#info/dir# must not be listed and appropriate [.filename]#install-info# lines must be added as noted in the crossref:makefiles[makefile-info,info files] section. Any libraries installed by the port must be listed as specified in the crossref:special[porting-shlibs,shared libraries] section. [[plist-autoplist-regex]] === Expanding `PLIST_SUB` with Regular Expressions Strings to be replaced sometimes need to be very specific to avoid undesired replacements. This is a common problem with shorter values. To address this problem, for each `_PLACEHOLDER_=_value_`, a `PLACEHOLDER_regex=regex` can be set, with the `_regex_` part matching _value_ more precisely. [[plist-autoplist-regex-ex1]] .Using PLIST_SUB with Regular Expressions [example] ==== Perl ports can install architecture dependent files in a specific tree. On FreeBSD to ease porting, this tree is called `mach`. For example, a port that installs a file whose path contains `mach` could have that part of the path string replaced with the wrong values. Consider this [.filename]#Makefile#: [.programlisting] .... PORTNAME= Machine-Build DISTVERSION= 1 CATEGORIES= devel perl5 MASTER_SITES= CPAN PKGNAMEPREFIX= p5- MAINTAINER= perl@FreeBSD.org COMMENT= Building machine USES= perl5 USE_PERL5= configure PLIST_SUB= PERL_ARCH=mach .... The files installed by the port are: [.programlisting] .... /usr/local/bin/machine-build /usr/local/lib/perl5/site_perl/man/man1/machine-build.1.gz /usr/local/lib/perl5/site_perl/man/man3/Machine::Build.3.gz /usr/local/lib/perl5/site_perl/Machine/Build.pm /usr/local/lib/perl5/site_perl/mach/5.20/Machine/Build/Build.so .... Running `make makeplist` wrongly generates: [.programlisting] .... bin/%%PERL_ARCH%%ine-build %%PERL5_MAN1%%/%%PERL_ARCH%%ine-build.1.gz %%PERL5_MAN3%%/Machine::Build.3.gz %%SITE_PERL%%/Machine/Build.pm %%SITE_PERL%%/%%PERL_ARCH%%/%%PERL_VER%%/Machine/Build/Build.so .... Change the `PLIST_SUB` line from the [.filename]#Makefile# to: [.programlisting] .... PLIST_SUB= PERL_ARCH=mach \ PERL_ARCH_regex=\bmach\b .... Now `make makeplist` correctly generates: [.programlisting] .... bin/machine-build %%PERL5_MAN1%%/machine-build.1.gz %%PERL5_MAN3%%/Machine::Build.3.gz %%SITE_PERL%%/Machine/Build.pm %%SITE_PERL%%/%%PERL_ARCH%%/%%PERL_VER%%/Machine/Build/Build.so .... ==== [[plist-keywords]] == Expanding Package List with Keywords All keywords can also take optional arguments in parentheses. The arguments are owner, group, and mode. This argument is used on the file or directory referenced. To change the owner, group, and mode of a configuration file, use: [.programlisting] .... @sample(games,games,640) etc/config.sample .... The arguments are optional. If only the group and mode need to be changed, use: [.programlisting] .... @sample(,games,660) etc/config.sample .... [WARNING] ==== If a keyword is used on an crossref:makefiles[makefile-options,optional] entry, it must to be added after the helper: [.programlisting] .... %%FOO%%@sample etc/orbit.conf.sample .... This is because the options plist helpers are used to comment out the line, so they need to be put first. See crossref:makefiles[options_sub,`OPTIONS_SUB`] for more information. ==== [[plist-keywords-desktop-file-utils]] === `@desktop-file-utils` Will run `update-desktop-database -q` after installation and deinstallation. _Never_ use directly, add crossref:uses[uses-desktop-file-utils,`USES=desktop-file-utils`] to the [.filename]#Makefile#. [[plist-keywords-fc]] === `@fc` _directory_ Add a `@dir` entry for the directory passed as an argument, and run `fc-cache -fs` on that directory after installation and deinstallation. -[[plist-keywords-fcfontsdir]] -=== `@fcfontsdir` _directory_ - -Add a `@dir` entry for the directory passed as an argument, and run `fc-cache -fs`, `mkfontscale` and `mkfontdir` on that directory after installation and deinstallation. -Additionally, on deinstallation, it removes the [.filename]#fonts.scale# and [.filename]#fonts.dir# cache files if they are empty. -This keyword is equivalent to adding both <> and <>. - [[plist-keywords-fontsdir]] === `@fontsdir` _directory_ Add a `@dir` entry for the directory passed as an argument, and run `mkfontscale` and `mkfontdir` on that directory after installation and deinstallation. Additionally, on deinstallation, it removes the [.filename]#fonts.scale# and [.filename]#fonts.dir# cache files if they are empty. [[plist-keywords-glib-schemas]] === `@glib-schemas` Runs `glib-compile-schemas` on installation and deinstallation. [[plist-keywords-info]] === `@info` _file_ Add the file passed as argument to the plist, and updates the info document index on installation and deinstallation. Additionally, it removes the index if empty on deinstallation. This should never be used manually, but always through `INFO`. See crossref:makefiles[makefile-info,Info Files] for more information. [[plist-keywords-kld]] === `@kld` _directory_ Runs `kldxref` on the directory on installation and deinstallation. Additionally, on deinstallation, it will remove the directory if empty. [[plist-keywords-rmtry]] === `@rmtry` _file_ Will remove the file on deinstallation, and not give an error if the file is not there. [[plist-keywords-sample]] === `@sample` _file_ [_file_] This is used to handle installation of configuration files, through example files bundled with the package. The "actual", non-sample, file is either the second filename, if present, or the first filename without the [.filename]#.sample# extension. This does three things. First, add the first file passed as argument, the sample file, to the plist. Then, on installation, if the actual file is not found, copy the sample file to the actual file. And finally, on deinstallation, remove the actual file if it has not been modified. See <> for more information. [[plist-keywords-shared-mime-info]] === `@shared-mime-info` _directory_ Runs `update-mime-database` on the directory on installation and deinstallation. [[plist-keywords-shell]] === `@shell` _file_ Add the file passed as argument to the plist. On installation, add the full path to _file_ to [.filename]#/etc/shells#, while making sure it is not added twice. On deinstallation, remove it from [.filename]#/etc/shells#. [[plist-keywords-terminfo]] === `@terminfo` Do not use by itself. If the port installs [.filename]#*.terminfo# files, add crossref:uses[uses-terminfo,USES=terminfo] to its [.filename]#Makefile#. On installation and deinstallation, if `tic` is present, refresh [.filename]#${PREFIX}/shared/misc/terminfo.db# from the [.filename]#*.terminfo# files in [.filename]#${PREFIX}/shared/misc#. [[plist-keywords-base]] === Base Keywords There are a few keywords that are hardcoded, and documented in man:pkg-create[8]. For the sake of completeness, they are also documented here. [[plist-keywords-base-empty]] ==== `@` [_file_] The empty keyword is a placeholder to use when the file's owner, group, or mode need to be changed. For example, to set the group of the file to `games` and add the setgid bit, add: [.programlisting] .... @(,games,2755) sbin/daemon .... [[plist-keywords-base-exec]] ==== `@preexec` _command_, `@postexec` _command_, `@preunexec` _command_, `@postunexec` _command_ Execute _command_ as part of the package installation or deinstallation process. `@preexec` _command_:: Execute _command_ as part of the [.filename]#pre-install# scripts. `@postexec` _command_:: Execute _command_ as part of the [.filename]#post-install# scripts. `@preunexec` _command_:: Execute _command_ as part of the [.filename]#pre-deinstall# scripts. `@postunexec` _command_:: Execute _command_ as part of the [.filename]#post-deinstall# scripts. If _command_ contains any of these sequences somewhere in it, they are expanded inline. For these examples, assume that `@cwd` is set to [.filename]#/usr/local# and the last extracted file was [.filename]#bin/emacs#. `%F`:: Expand to the last filename extracted (as specified). In the example case [.filename]#bin/emacs#. `%D`:: Expand to the current directory prefix, as set with `@cwd`. In the example case [.filename]#/usr/local#. `%B`:: Expand to the basename of the fully qualified filename, that is, the current directory prefix plus the last filespec, minus the trailing filename. In the example case, that would be [.filename]#/usr/local/bin#. `%f`:: Expand to the filename part of the fully qualified name, or the converse of `%B`. In the example case, [.filename]#emacs#. [IMPORTANT] ==== These keywords are here to help you set up the package so that it is as ready to use as possible. They _must not_ be abused to start services, stop services, or run any other commands that will modify the currently running system. ==== [[plist-keywords-base-mode]] ==== `@mode` _mode_ Set default permission for all subsequently extracted files to _mode_. Format is the same as that used by man:chmod[1]. Use without an arg to set back to default permissions (mode of the file while being packed). [IMPORTANT] ==== This must be a numeric mode, like `644`, `4755`, or `600`. It cannot be a relative mode like `u+s`. ==== [[plist-keywords-base-owner]] ==== `@owner` _user_ Set default ownership for all subsequent files to _user_. Use without an argument to set back to default ownership (`root`). [[plist-keywords-base-group]] ==== `@group` _group_ Set default group ownership for all subsequent files to _group_. Use without an arg to set back to default group ownership (`wheel`). [[plist-keywords-base-comment]] ==== `@comment` _string_ This line is ignored when packing. [[plist-keywords-base-dir]] ==== `@dir` _directory_ Declare directory name. By default, directories created under `PREFIX` by a package installation are automatically removed. Use this when an empty directory under `PREFIX` needs to be created, or when the directory needs to have non default owner, group, or mode. Directories outside of `PREFIX` need to be registered. For example, [.filename]#/var/db/${PORTNAME}# needs to have a `@dir` entry whereas [.filename]#${PREFIX}/shared/${PORTNAME}# does not if it contains files or uses the default owner, group, and mode. [[plist-keywords-base-exec-deprecated]] ==== `@exec` _command_, `@unexec` _command_ (Deprecated) Execute _command_ as part of the installation or deinstallation process. Please use <> instead. [[plist-keywords-base-dirrm]] ==== `@dirrm` _directory_ (Deprecated) Declare directory name to be deleted at deinstall time. By default, directories created under `PREFIX` by a package installation are deleted when the package is deinstalled. [[plist-keywords-base-dirrmtry]] ==== `@dirrmtry` _directory_ (Deprecated) Declare directory name to be removed, as for `@dirrm`, but does not issue a warning if the directory cannot be removed. [[plist-keywords-creating-new]] === Creating New Keywords Package list files can be extended by keywords that are defined in the [.filename]#${PORTSDIR}/Keywords# directory. The settings for each keyword are stored in a UCL file named [.filename]#keyword.ucl#. The file must contain at least one of these sections: * `attributes` * `action` * `pre-install` * `post-install` * `pre-deinstall` * `post-deinstall` * `pre-upgrade` * `post-upgrade` [[plist-keywords-attributes]] ==== `attributes` Changes the owner, group, or mode used by the keyword. Contains an associative array where the possible keys are `owner`, `group`, and `mode`. The values are, respectively, a user name, a group name, and a file mode. For example: [.programlisting] .... attributes: { owner: "games", group: "games", mode: 0555 } .... [[plist-keywords-action]] ==== `action` Defines what happens to the keyword's parameter. Contains an array where the possible values are: `setprefix`:: Set the prefix for the next plist entries. `dir`:: Register a directory to be created on install and removed on deinstall. `dirrm`:: Register a directory to be deleted on deinstall. Deprecated. `dirrmtry`:: Register a directory to try and deleted on deinstall. Deprecated. `file`:: Register a file. `setmode`:: Set the mode for the next plist entries. `setowner`:: Set the owner for the next plist entries. `setgroup`:: Set the group for the next plist entries. `comment`:: Does not do anything, equivalent to not entering an `action` section. `ignore_next`:: Ignore the next entry in the plist. [[plist-keywords-arguments]] ==== `arguments` If set to `true`, adds argument handling, splitting the whole line, `%@`, into numbered arguments, `%1`, `%2`, and so on. For example, for this line: [.programlisting] .... @foo some.content other.content .... `%1` and `%2` will contain: [.programlisting] .... some.content other.content .... It also affects how the <> entry works. When there is more than one argument, the argument number must be specified. For example: [.programlisting] .... actions: [file(1)] .... [[plist-keywords-pre-post]] ==== `pre-install`, `post-install`, `pre-deinstall`, `post-deinstall`, `pre-upgrade`, `post-upgrade` These keywords contains a man:sh[1] script to be executed before or after installation, deinstallation, or upgrade of the package. In addition to the usual `@exec %_foo_` placeholders described in <>, there is a new one, `%@`, which represents the argument of the keyword. [[plist-keywords-examples]] ==== Custom Keyword Examples [[plist-keywords-fc-example]] .Example of a `@dirrmtryecho` Keyword [example] ==== This keyword does two things, it adds a `@dirrmtry _directory_` line to the packing list, and echoes the fact that the directory is removed when deinstalling the package. [.programlisting] .... actions: [dirrmtry] post-deinstall: <> will be added to the plist. [[uses-desthack]] == `desthack` Possible arguments: (none) Changes the behavior of GNU configure to properly support `DESTDIR` in case the original software does not. [[uses-display]] == `display` Possible arguments: (none), _ARGS_ Set up a virtual display environment. If the environment variable `DISPLAY` is not set, then Xvfb is added as a build dependency, and `CONFIGURE_ENV` is extended with the port number of the currently running instance of Xvfb. The _ARGS_ parameter defaults to `install` and controls the phase around which to start and stop the virtual display. [[uses-dos2unix]] == `dos2unix` Possible arguments: (none) The port has files with line endings in DOS format which need to be converted. Several variables can be set to control which files will be converted. The default is to convert _all_ files, including binaries. See crossref:slow-porting[slow-patch-automatic-replacements,Simple Automatic Replacements] for examples. * `DOS2UNIX_REGEX`: match file names based on a regular expression. * `DOS2UNIX_FILES`: match literal file names. * `DOS2UNIX_GLOB`: match file names based on a glob pattern. * `DOS2UNIX_WRKSRC`: the directory from which to start the conversions. Defaults to `${WRKSRC}`. [[uses-drupal]] == `drupal` Possible arguments: `7`, `module`, `theme` Automate installation of a port that is a Drupal theme or module. Use with the version of Drupal that the port is expecting. For example, `USES=drupal:7,module` says that this port creates a Drupal 6 module. A Drupal 7 theme can be specified with `USES=drupal:7,theme`. [[uses-eigen]] == `eigen` Possible arguments: 2, 3, build (default), run Add dependency on package:math/eigen[]. [[uses-elfctl]] == `elfctl` Possible arguments: (none) Change an ELF binary's feature control note by setting ELF_FEATURES. [[uses-elfct-ex1]] .Uses=elfctl [example] ==== [.programlisting] .... USES= elfctl ELF_FEATURES= featurelist:path/to/file1 \ featurelist:path/to/file1 \ featurelist:path/to/file2 .... ==== The format of `featurelist` is described in man:elfctl[1]. The file paths are relative to ${BUILD_WRKSRC}. [[uses-fakeroot]] == `fakeroot` Possible arguments: (none) Changes some default behavior of build systems to allow installing as a user. See https://wiki.debian.org/FakeRoot[] for more information on `fakeroot`. [[uses-fam]] == `fam` Possible arguments: (none), `fam`, `gamin` Uses a File Alteration Monitor as a library dependency, either package:devel/fam[] or package:devel/gamin[]. End users can set WITH_FAM_SYSTEM to specify their preference. [[uses-firebird]] == `firebird` Possible arguments: (none), `25` Add a dependency to the client library of the Firebird database. [[uses-fonts]] == `fonts` -Possible arguments: (none), `fc`, `fcfontsdir` (default), `fontsdir`, `none` +Possible arguments: (none), `fc`, `fontsdir` (default), `none` Adds a runtime dependency on tools needed to register fonts. -Depending on the argument, add a `crossref:plist[plist-keywords-fc,@fc] ${FONTSDIR}` line, `crossref:plist[plist-keywords-fcfontsdir,@fcfontsdir] ${FONTSDIR}` line, `crossref:plist[plist-keywords-fontsdir,@fontsdir] ${FONTSDIR}` line, or no line if the argument is `none`, to the plist. +Depending on the argument, add a `crossref:plist[plist-keywords-fc,@fc] ${FONTSDIR}` line, `crossref:plist[plist-keywords-fontsdir,@fontsdir] ${FONTSDIR}` line, or no line if the argument is `none`, to the plist. `FONTSDIR` defaults to [.filename]#${PREFIX}/share/fonts/${FONTNAME}# and `FONTNAME` to `${PORTNAME}`. Add `FONTSDIR` to `PLIST_SUB` and `SUB_LIST` [[uses-fortran]] == `fortran` Possible arguments: `gcc` (default) Uses the GNU Fortran compiler. [[uses-fuse]] == `fuse` Possible arguments: `2` (default), `3` The port will depend on the FUSE library and handle the dependency on the kernel module depending on the version of FreeBSD. [[uses-gem]] == `gem` Possible arguments: (none), `noautoplist` Handle building with RubyGems. If `noautoplist` is used, the packing list is not generated automatically. [[uses-gettext]] == `gettext` Possible arguments: (none) Deprecated. Will include both <> and <>. [[uses-gettext-runtime]] == `gettext-runtime` Possible arguments: (none), `lib` (default), `build`, `run` Uses package:devel/gettext-runtime[]. By default, with no arguments or with the `lib` argument, implies a library dependency on [.filename]#libintl.so#. `build` and `run` implies, respectively a build-time and a run-time dependency on [.filename]#gettext#. [[uses-gettext-tools]] == `gettext-tools` Possible arguments: (none), `build` (default), `run` Uses package:devel/gettext-tools[]. By default, with no argument, or with the `build` argument, a build time dependency on [.filename]#msgfmt# is registered. With the `run` argument, a run-time dependency is registered. [[uses-ghostscript]] == `ghostscript` Possible arguments: _X_, `build`, `run`, `nox11` A specific version _X_ can be used. Possible versions are `7`, `8`, `9`, and `agpl` (default). `nox11` indicates that the `-nox11` version of the port is required. `build` and `run` add build- and run-time dependencies on Ghostscript. The default is both build- and run-time dependencies. [[uses-gl]] == `gl` Possible arguments: (none) Provides an easy way to depend on GL components. The components should be listed in `USE_GL`. The available components are: `egl`:: add a library dependency on [.filename]#libEGL.so# from package:graphics/libglvnd[] `gbm`:: Add a library dependency on [.filename]#libgbm.so# from package:graphics/mesa-libs[] `gl`:: Add a library dependency on [.filename]#libGL.so# from package:graphics/libglvnd[] `glesv2`:: Add a library dependency on [.filename]#libGLESv2.so# from package:graphics/libglvnd[] `glew`:: Add a library dependency on [.filename]#libGLEW.so# from package:graphics/glew[] `glu`:: Add a library dependency on [.filename]#libGLU.so# from package:graphics/libGLU[] `glut`:: Add a library dependency on [.filename]#libglut.so# from package:graphics/freeglut[] `opengl`:: Add a library dependency on [.filename]#libOpenGL.so# from package:graphics/libglvnd[] [[uses-gmake]] == `gmake` Possible arguments: (none) Uses package:devel/gmake[] as a build-time dependency and sets up the environment to use `gmake` as the default `make` for the build. [[uses-gnome]] == `gnome` Possible arguments: (none) Provides an easy way to depend on GNOME components. The components should be listed in `USE_GNOME`. The available components are: * `atk` * `atkmm` * `cairo` * `cairomm` * `dconf` * `esound` * `evolutiondataserver3` * `gconf2` * `gconfmm26` * `gdkpixbuf` * `gdkpixbuf2` * `glib12` * `glib20` * `glibmm` * `gnomecontrolcenter3` * `gnomedesktop3` * `gnomedocutils` * `gnomemenus3` * `gnomemimedata` * `gnomeprefix` * `gnomesharp20` * `gnomevfs2` * `gsound` * `gtk-update-icon-cache` * `gtk12` * `gtk20` * `gtk30` * `gtkhtml3` * `gtkhtml4` * `gtkmm20` * `gtkmm24` * `gtkmm30` * `gtksharp20` * `gtksourceview` * `gtksourceview2` * `gtksourceview3` * `gtksourceviewmm3` * `gvfs` * `intlhack` * `intltool` * `introspection` * `libartlgpl2` * `libbonobo` * `libbonoboui` * `libgda5` * `libgda5-ui` * `libgdamm5` * `libglade2` * `libgnome` * `libgnomecanvas` * `libgnomekbd` * `libgnomeprint` * `libgnomeprintui` * `libgnomeui` * `libgsf` * `libgtkhtml` * `libgtksourceviewmm` * `libidl` * `librsvg2` * `libsigc++12` * `libsigc++20` * `libwnck` * `libwnck3` * `libxml++26` * `libxml2` * `libxslt` * `metacity` * `nautilus3` * `orbit2` * `pango` * `pangomm` * `pangox-compat` * `py3gobject3` * `pygnome2` * `pygobject` * `pygobject3` * `pygtk2` * `pygtksourceview` * `referencehack` * `vte` * `vte3` The default dependency is build- and run-time, it can be changed with `:build` or `:run`. For example: [.programlisting] .... USES= gnome USE_GNOME= gnomemenus3:build intlhack .... See crossref:special[using-gnome,Using GNOME] for more information. [[uses-go]] == `go` [IMPORTANT] ==== Ports should not be created for Go libs, see crossref:special[go-libs,Go Libraries] for more information. ==== Possible arguments: (none), `modules`, `no_targets`, `run` Sets default values and targets used to build Go software. A build dependency on the Go compiler port selected via `GO_PORT` is added. By default the build is performed in GOPATH mode. If Go software uses modules, the modules-aware mode can be switched on with `modules` argument. `no_targets` will setup build environment like `GO_ENV`, `GO_BUILDFLAGS` but skip creating `post-extract` and `do-{build,install,test}` targets. `run` will also add a run dependency on what is in `GO_PORT`. The build process is controlled by several variables: `GO_MODULE`:: The name of the application module as specified by the `module` directive in `go.mod`. In most cases, this is the only required variable for ports that use Go modules. `GO_PKGNAME`:: The name of the Go package when building in GOPATH mode. This is the directory that will be created in `${GOPATH}/src`. If not set explicitly and `GH_SUBDIR` or `GL_SUBDIR` is present, `GO_PKGNAME` will be inferred from it. It is not needed when building in modules-aware mode. `GO_TARGET`:: The packages to build. The default value is `${GO_PKGNAME}`. `GO_TARGET` can also be a tuple in the form `package:path` where path can be either a simple filename or a full path starting with `${PREFIX}`. `GO_TESTTARGET`:: The packages to test. The default value is `./...` (the current package and all subpackages). `CGO_CFLAGS`:: Additional `CFLAGS` values to be passed to the C compiler by `go`. `CGO_LDFLAGS`:: Additional `LDFLAGS` values to be passed to the C compiler by `go`. `GO_BUILDFLAGS`:: Additional build arguments to be passed to `go build`. `GO_TESTFLAGS`:: Additional build arguments to be passed to `go test`. `GO_PORT`:: The Go compiler port to use. By default this is package:lang/go[] but can be set to package:lang/go-devel[] in `make.conf` for testing with future Go versions. + [WARNING] ==== This variable must not be set by individual ports! ==== See crossref:special[using-go,Building Go Applications] for usage examples. [[uses-gperf]] == `gperf` Possible arguments: (none) Add a buildtime dependency on package:devel/gperf[] if `gperf` is not present in the base system. [[uses-grantlee]] == `grantlee` Possible arguments: `5`, `selfbuild` Handle dependency on Grantlee. Specify `5` to depend on the Qt5 based version, package:devel/grantlee5[]. `selfbuild` is used internally by package:devel/grantlee5[] to get their versions numbers. [[uses-groff]] == `groff` Possible arguments: `build`, `run`, `both` Registers a dependency on package:textproc/groff[] if not present in the base system. [[uses-gssapi]] == `gssapi` Possible arguments: (none), `base` (default), `heimdal`, `mit`, `flags`, `bootstrap` Handle dependencies needed by consumers of the GSS-API. Only libraries that provide the Kerberos mechanism are available. By default, or set to `base`, the GSS-API library from the base system is used. Can also be set to `heimdal` to use package:security/heimdal[], or `mit` to use package:security/krb5[]. When the local Kerberos installation is not in `LOCALBASE`, set `HEIMDAL_HOME` (for `heimdal`) or `KRB5_HOME` (for `krb5`) to the location of the Kerberos installation. These variables are exported for the ports to use: * `GSSAPIBASEDIR` * `GSSAPICPPFLAGS` * `GSSAPIINCDIR` * `GSSAPILDFLAGS` * `GSSAPILIBDIR` * `GSSAPILIBS` * `GSSAPI_CONFIGURE_ARGS` The `flags` option can be given alongside `base`, `heimdal`, or `mit` to automatically add `GSSAPICPPFLAGS`, `GSSAPILDFLAGS`, and `GSSAPILIBS` to `CFLAGS`, `LDFLAGS`, and `LDADD`, respectively. For example, use `base,flags`. The `bootstrap` option is a special prefix only for use by package:security/krb5[] and package:security/heimdal[]. For example, use `bootstrap,mit`. [[uses-gssapi-ex1]] .Typical Use [example] ==== [.programlisting] .... OPTIONS_SINGLE= GSSAPI OPTIONS_SINGLE_GSSAPI= GSSAPI_BASE GSSAPI_HEIMDAL GSSAPI_MIT GSSAPI_NONE GSSAPI_BASE_USES= gssapi GSSAPI_BASE_CONFIGURE_ON= --with-gssapi=${GSSAPIBASEDIR} ${GSSAPI_CONFIGURE_ARGS} GSSAPI_HEIMDAL_USES= gssapi:heimdal GSSAPI_HEIMDAL_CONFIGURE_ON= --with-gssapi=${GSSAPIBASEDIR} ${GSSAPI_CONFIGURE_ARGS} GSSAPI_MIT_USES= gssapi:mit GSSAPI_MIT_CONFIGURE_ON= --with-gssapi=${GSSAPIBASEDIR} ${GSSAPI_CONFIGURE_ARGS} GSSAPI_NONE_CONFIGURE_ON= --without-gssapi .... ==== [[uses-gstreamer]] == `gstreamer` Possible arguments: (none) Provides an easy way to depend on GStreamer components. The components should be listed in `USE_GSTREAMER`. The available components are: * `a52dec` * `aalib` * `amrnb` * `amrwbdec` * `aom` * `assrender` * `bad` * `bs2b` * `cairo` * `cdio` * `cdparanoia` * `chromaprint` * `curl` * `dash` * `dtls` * `dts` * `dv` * `dvd` * `dvdread` * `editing-services` * `faac` * `faad` * `flac` * `flite` * `gdkpixbuf` * `gl` * `gme` * `gnonlin` * `good` * `gsm` * `gtk4` * `gtk` * `hal` * `hls` * `jack` * `jpeg` * `kate` * `kms` * `ladspa` * `lame` * `libav` * `libcaca` * `libde265` * `libmms` * `libvisual` * `lv2` * `mm` * `modplug` * `mpeg2dec` * `mpeg2enc` * `mpg123` * `mplex` * `musepack` * `neon` * `ogg` * `opencv` * `openexr` * `openh264` * `openjpeg` * `openmpt` * `opus` * `pango` * `png` * `pulse` * `qt` * `resindvd` * `rsvg` * `rtmp` * `shout2` * `sidplay` * `smoothstreaming` * `sndfile` * `sndio` * `soundtouch` * `soup` * `spandsp` * `speex` * `srtp` * `taglib` * `theora` * `ttml` * `twolame` * `ugly` * `v4l2` * `vorbis` * `vpx` * `vulkan` * `wavpack` * `webp` * `webrtcdsp` * `x264` * `x265` * `x` * `ximagesrc` * `zbar` [[uses-horde]] == `horde` Possible arguments: (none) Add buildtime and runtime dependencies on package:devel/pear-channel-horde[]. Other Horde dependencies can be added with `USE_HORDE_BUILD` and `USE_HORDE_RUN`. See crossref:special[php-horde,Horde Modules] for more information. [[uses-iconv]] == `iconv` Possible arguments: (none), `lib`, `build`, `patch`, `translit`, `wchar_t` Uses `iconv` functions, either from the port package:converters/libiconv[] as a build-time and run-time dependency, or from the base system. By default, with no arguments or with the `lib` argument, implies `iconv` with build-time and run-time dependencies. `build` implies a build-time dependency, and `patch` implies a patch-time dependency. If the port uses the `WCHAR_T` or `//TRANSLIT` iconv extensions, add the relevant arguments so that the correct iconv is used. For more information see crossref:special[using-iconv,Using `iconv`]. [[uses-imake]] == `imake` Possible arguments: (none), `env`, `notall`, `noman` Add package:devel/imake[] as a build-time dependency and run `xmkmf -a` during the `configure` stage. If the `env` argument is given, the `configure` target is not set. If the `-a` flag is a problem for the port, add the `notall` argument. If `xmkmf` does not generate a `install.man` target, add the `noman` argument. [[uses-kde]] == `kde` Possible arguments: `5` Add dependency on KDE components. See crossref:special[using-kde,Using KDE] for more information. [[uses-kmod]] == `kmod` Possible arguments: (none), `debug` Fills in the boilerplate for kernel module ports, currently: * Add `kld` to `CATEGORIES`. * Set `SSP_UNSAFE`. * Set `IGNORE` if the kernel sources are not found in `SRC_BASE`. * Define `KMODDIR` to [.filename]#/boot/modules# by default, add it to `PLIST_SUB` and `MAKE_ENV`, and create it upon installation. If `KMODDIR` is set to [.filename]#/boot/kernel#, it will be rewritten to [.filename]#/boot/modules#. This prevents breaking packages when upgrading the kernel due to [.filename]#/boot/kernel# being renamed to [.filename]#/boot/kernel.old# in the process. * Handle cross-referencing kernel modules upon installation and deinstallation, using crossref:plist[plist-keywords-kld,`@kld`]. * If the `debug` argument is given, the port can install a debug version of the module into [.filename]#KERN_DEBUGDIR#/[.filename]#KMODDIR#. By default, `KERN_DEBUGDIR` is copied from `DEBUGDIR` and set to [.filename]#/usr/lib/debug#. The framework will take care of creating and removing any required directories. [[uses-lha]] == `lha` Possible arguments: (none) Set `EXTRACT_SUFX` to `.lzh` [[uses-libarchive]] == `libarchive` Possible arguments: (none) Registers a dependency on package:archivers/libarchive[]. Any ports depending on libarchive must include `USES=libarchive`. [[uses-libedit]] == `libedit` Possible arguments: (none) Registers a dependency on package:devel/libedit[]. Any ports depending on libedit must include `USES=libedit`. [[uses-libtool]] == `libtool` Possible arguments: (none), `keepla`, `build` Patches `libtool` scripts. This must be added to all ports that use `libtool`. The `keepla` argument can be used to keep [.filename]#.la# files. Some ports do not ship with their own copy of libtool and need a build time dependency on package:devel/libtool[], use the `:build` argument to add such dependency. [[uses-linux]] == `linux` Possible arguments: `c6`, `c7` Ports Linux compatibility framework. Specify `c6` to depend on CentOS 6 packags. Specify `c7` to depend on CentOS 7 packages. The available packages are: * `allegro` * `alsa-plugins-oss` * `alsa-plugins-pulseaudio` * `alsalib` * `atk` * `avahi-libs` * `base` * `cairo` * `cups-libs` * `curl` * `cyrus-sasl2` * `dbusglib` * `dbuslibs` * `devtools` * `dri` * `expat` * `flac` * `fontconfig` * `gdkpixbuf2` * `gnutls` * `graphite2` * `gtk2` * `harfbuzz` * `jasper` * `jbigkit` * `jpeg` * `libasyncns` * `libaudiofile` * `libelf` * `libgcrypt` * `libgfortran` * `libgpg-error` * `libmng` * `libogg` * `libpciaccess` * `libsndfile` * `libsoup` * `libssh2` * `libtasn1` * `libthai` * `libtheora` * `libv4l` * `libvorbis` * `libxml2` * `mikmod` * `naslibs` * `ncurses-base` * `nspr` * `nss` * `openal` * `openal-soft` * `openldap` * `openmotif` * `openssl` * `pango` * `pixman` * `png` * `pulseaudio-libs` * `qt` * `qt-x11` * `qtwebkit` * `scimlibs` * `sdl12` * `sdlimage` * `sdlmixer` * `sqlite3` * `tcl85` * `tcp_wrappers-libs` * `tiff` * `tk85` * `ucl` * `xorglibs` [[uses-localbase]] == `localbase` Possible arguments: (none), `ldflags` Ensures that libraries from dependencies in `LOCALBASE` are used instead of the ones from the base system. Specify `ldflags` to add `-L${LOCALBASE}/lib` to `LDFLAGS` instead of `LIBS`. Ports that depend on libraries that are also present in the base system should use this. It is also used internally by a few other `USES`. [[uses-lua]] == `lua` Possible arguments: (none), `_XY_`, `_XY_+`, `-_XY_`, `_XY_-_ZA_`, `module`, `flavors`, `build`, `run`, `env` Adds a dependency on Lua. By default this is a library dependency, unless overridden by the `build` and/or `run` option. The `env` option prevents the addition of any dependency, while still defining all the usual variables. The default version is set by the usual `DEFAULT_VERSIONS` mechanism, unless a version or range of versions is specified as an argument, for example, `51` or `51-53`. Applications using Lua are normally built for only a single Lua version. However, library modules intended to be loaded by Lua code should use the `module` option to build with multiple flavors. For more information see crossref:special[using-lua,Using Lua]. [[uses-lxqt]] == `lxqt` Possible arguments: (none) Handle dependencies for the LXQt Desktop Environment. Use `USE_LXQT` to select the components needed for the port. See crossref:special[using-lxqt,Using LXQt] for more information. [[uses-magick]] == `magick` Possible arguments: (none), `_X_`, `build`, `nox11`, `run`, `test` Add a library dependency on `ImageMagick`. A specific version _X_ can be used. Possible versions are `6` and `7` (default). `nox11` indicates that the `-nox11` version of the port is required. `build`, `run` and `test` add build-, run-time and test dependencies on ImageMagick. [[uses-makeinfo]] == `makeinfo` Possible arguments: (none) Add a build-time dependency on `makeinfo` if it is not present in the base system. [[uses-makeself]] == `makeself` Possible arguments: (none) Indicates that the distribution files are makeself archives and sets the appropriate dependencies. [[uses-mate]] == `mate` Possible arguments: (none) Provides an easy way to depend on MATE components. The components should be listed in `USE_MATE`. The available components are: * `autogen` * `caja` * `common` * `controlcenter` * `desktop` * `dialogs` * `docutils` * `icontheme` * `intlhack` * `intltool` * `libmatekbd` * `libmateweather` * `marco` * `menus` * `notificationdaemon` * `panel` * `pluma` * `polkit` * `session` * `settingsdaemon` The default dependency is build- and run-time, it can be changed with `:build` or `:run`. For example: [.programlisting] .... USES= mate USE_MATE= menus:build intlhack .... [[uses-meson]] == `meson` Possible arguments: (none) Provide support for Meson based projects. For more information see crossref:special[using-meson,Using `meson`]. [[uses-metaport]] == `metaport` Possible arguments: (none) Sets the following variables to make it easier to create a metaport: `MASTER_SITES`, `DISTFILES`, `EXTRACT_ONLY`, `NO_BUILD`, `NO_INSTALL`, `NO_MTREE`, `NO_ARCH`. [[uses-minizip]] == `minizip` Possible arguments: (none), `ng` Adds a library dependency on package:archivers/minizip[] or package:archivers/minizip-ng[] respectively. [[uses-mysql]] == `mysql` Possible arguments: (none), `_version_`, `client` (default), `server`, `embedded` Provide support for MySQL If no version is given, try to find the current installed version. Fall back to the default version, MySQL-5.6. The possible versions are `55`, `55m`, `55p`, `56`, `56p`, `56w`, `57`, `57p`, `80`, `100m`, `101m`, and `102m`. The `m` and `p` suffixes are for the MariaDB and Percona variants of MySQL. `server` and `embedded` add a build- and run-time dependency on the MySQL server. When using `server` or `embedded`, add `client` to also add a dependency on [.filename]#libmysqlclient.so#. A port can set `IGNORE_WITH_MYSQL` if some versions are not supported. The framework sets `MYSQL_VER` to the detected MySQL version. [[uses-mono]] == `mono` Possible arguments: (none), `nuget` Adds a dependency on the Mono (currently only C#) framework by setting the appropriate dependencies. Specify `nuget` when the port uses nuget packages. `NUGET_DEPENDS` needs to be set with the names and versions of the nuget packages in the format `_name_=_version_`. An optional package origin can be added using `_name_=_version_:_origin_`. The helper target, `buildnuget`, will output the content of the `NUGET_DEPENDS` based on the provided [.filename]#packages.config#. [[uses-motif]] == `motif` Possible arguments: (none) Uses package:x11-toolkits/open-motif[] as a library dependency. End users can set `WANT_LESSTIF` for the dependency to be on package:x11-toolkits/lesstif[] instead of package:x11-toolkits/open-motif[]. [[uses-ncurses]] == `ncurses` Possible arguments: (none), `base`, `port` Uses ncurses, and causes some useful variables to be set. [[uses-ninja]] == `ninja` Possible arguments: (none) Uses ninja to build the port. [[uses-nodejs]] == `nodejs` Possible arguments: (none), `build`, `run`, `current`, `lts`, `10`, `14`, `16`, `17`. Uses nodejs. Adds a dependency on package:www/node*[]. If a supported version is specified then `run` and/or `build` must be specified too. [[uses-objc]] == `objc` Possible arguments: (none) Add objective C dependencies (compiler, runtime library) if the base system does not support it. [[uses-openal]] == `openal` Possible arguments: `al`, `soft` (default), `si`, `alut` Uses OpenAL. The backend can be specified, with the software implementation as the default. The user can specify a preferred backend with `WANT_OPENAL`. Valid values for this knob are `soft` (default) and `si`. [[uses-pathfix]] == `pathfix` Possible arguments: (none) Look for [.filename]#Makefile.in# and [.filename]#configure# in `PATHFIX_WRKSRC` (defaults to `WRKSRC`) and fix common paths to make sure they respect the FreeBSD hierarchy. For example, it fixes the installation directory of `pkgconfig`'s [.filename]#.pc# files to [.filename]#${PREFIX}/libdata/pkgconfig#. If the port uses `USES=autoreconf`, [.filename]#Makefile.am# will be added to `PATHFIX_MAKEFILEIN` automatically. If the port <> it will look for [.filename]#CMakeLists.txt# in `PATHFIX_WRKSRC`. If needed, that default filename can be changed with `PATHFIX_CMAKELISTSTXT`. [[uses-pear]] == `pear` Possible arguments: `env` Adds a dependency on package:devel/pear[]. It will setup default behavior for software using the PHP Extension and Application Repository. Using the `env` arguments only sets up the PEAR environment variables. See crossref:special[php-pear,PEAR Modules] for more information. [[uses-perl5]] == `perl5` Possible arguments: (none) Depends on Perl. The configuration is done using `USE_PERL5`. `USE_PERL5` can contain the phases in which to use Perl, can be `extract`, `patch`, `build`, `run`, or `test`. `USE_PERL5` can also contain `configure`, `modbuild`, or `modbuildtiny` when [.filename]#Makefile.PL#, [.filename]#Build.PL#, or Module::Build::Tiny's flavor of [.filename]#Build.PL# is required. `USE_PERL5` defaults to `build run`. When using `configure`, `modbuild`, or `modbuildtiny`, `build` and `run` are implied. See crossref:special[using-perl,Using Perl] for more information. [[uses-pgsql]] == `pgsql` Possible arguments: (none), `_X.Y_`, `_X.Y_+`, `_X.Y_-`, `_X.Y_-_Z.A_` Provide support for PostgreSQL. Port maintainer can set version required. Minimum and maximum versions or a range can be specified; for example, `9.0-`, `8.4+`, `8.4-9.2.` By default, the added dependency will be the client, but if the port requires additional components, this can be done using `WANT_PGSQL=_component[:target]_`; for example, `WANT_PGSQL=server:configure pltcl plperl`. The available components are: * `client` * `contrib` * `docs` * `pgtcl` * `plperl` * `plpython` * `pltcl` * `server` [[uses-php]] == `php` Possible arguments: (none), `phpize`, `ext`, `zend`, `build`, `cli`, `cgi`, `mod`, `web`, `embed`, `pecl`, `flavors`, `noflavors` Provide support for PHP. Add a runtime dependency on the default PHP version, package:lang/php56[]. `phpize`:: Use to build a PHP extension. Enables flavors. `ext`:: Use to build, install and register a PHP extension. Enables flavors. `zend`:: Use to build, install and register a Zend extension. Enables flavors. `build`:: Set PHP also as a build-time dependency. `cli`:: Needs the CLI version of PHP. `cgi`:: Needs the CGI version of PHP. `mod`:: Needs the Apache module for PHP. `web`:: Needs the Apache module or the CGI version of PHP. `embed`:: Needs the embedded library version of PHP. `pecl`:: Provide defaults for fetching PHP extensions from the PECL repository. Enables flavors. `flavors`:: Enable automatic crossref:flavors[flavors-auto-php,PHP flavors] generation. Flavors will be generated for all PHP versions, except the ones present in <>. `noflavors`:: Disable automatic PHP flavors generation. _Must only_ be used with extensions provided by PHP itself. Variables are used to specify which PHP modules are required, as well as which version of PHP are supported. `USE_PHP`:: The list of required PHP extensions at run-time. Add `:build` to the extension name to add a build-time dependency. Example: `pcre xml:build gettext` [[uses-php-ignore]] `IGNORE_WITH_PHP`:: The port does not work with PHP of the given version. For possible values look at the content of `_ALL_PHP_VERSIONS` in [.filename]#Mk/Uses/php.mk#. When building a PHP or Zend extension with `:ext` or `:zend`, these variables can be set: `PHP_MODNAME`:: The name of the PHP or Zend extension. Default value is `${PORTNAME}`. `PHP_HEADER_DIRS`:: A list of subdirectories from which to install header files. The framework will always install the header files that are present in the same directory as the extension. `PHP_MOD_PRIO`:: The priority at which to load the extension. It is a number between `00` and `99`. + For extensions that do not depend on any extension, the priority is automatically set to `20`, for extensions that depend on another extension, the priority is automatically set to `30`. Some extensions may need to be loaded before every other extension, for example package:www/php56-opcache[]. Some may need to be loaded after an extension with a priority of `30`. In that case, add `PHP_MOD_PRIO=_XX_` in the port's Makefile. For example: + [.programlisting] .... USES= php:ext USE_PHP= wddx PHP_MOD_PRIO= 40 .... These variables are available to use in `PKGNAMEPREFIX` or `PKGNAMESUFFIX`: `PHP_PKGNAMEPREFIX`:: Contains `php_XY_-` where _XY_ is the current flavor's PHP version. Use with PHP extensions and modules. `PHP_PKGNAMESUFFIX`:: Contains `-php_XY_` where _XY_ is the current flavor's PHP version. Use with PHP applications. `PECL_PKGNAMEPREFIX`:: Contains `php_XY_-pecl-` where _XY_ is the current flavor's PHP version. Use with PECL modules. [IMPORTANT] ==== With flavors, all PHP extensions, PECL extensions, PEAR modules _must have_ a different package name, so they must all use one of these three variables in their `PKGNAMEPREFIX` or `PKGNAMESUFFIX`. ==== [[uses-pkgconfig]] == `pkgconfig` Possible arguments: (none), `build` (default), `run`, `both` Uses package:devel/pkgconf[]. With no arguments or with the `build` argument, it implies `pkg-config` as a build-time dependency. `run` implies a run-time dependency and `both` implies both run-time and build-time dependencies. [[uses-pure]] == `pure` Possible arguments: (none), `ffi` Uses package:lang/pure[]. Largely used for building related pure ports. With the `ffi` argument, it implies package:devel/pure-ffi[] as a run-time dependency. [[uses-pyqt]] == `pyqt` Possible arguments: (none), `4`, `5` Uses PyQt. If the port is part of PyQT itself, set `PYQT_DIST`. Use `USE_PYQT` to select the components the port needs. The available components are: * `core` * `dbus` * `dbussupport` * `demo` * `designer` * `designerplugin` * `doc` * `gui` * `multimedia` * `network` * `opengl` * `qscintilla2` * `sip` * `sql` * `svg` * `test` * `webkit` * `xml` * `xmlpatterns` These components are only available with PyQT4: * `assistant` * `declarative` * `help` * `phonon` * `script` * `scripttools` These components are only available with PyQT5: * `multimediawidgets` * `printsupport` * `qml` * `serialport` * `webkitwidgets` * `widgets` The default dependency for each component is build- and run-time, to select only build or run, add `_build` or `_run` to the component name. For example: [.programlisting] .... USES= pyqt USE_PYQT= core doc_build designer_run .... [[uses-pytest]] == `pytest` Possible arguments: (none), 4 Introduces a new dependency on package:devel/pytest[]. It defines a `do-test` target which will run the tests properly. Use the argument to depend on a specific package:devel/pytest[] version. For ports using package:devel/pytest[] consider using this instead of a specific `do-test` target. The framework exposes the following variables to the port: `PYTEST_ARGS`:: Additional arguments to pytest (defaults to empty). `PYTEST_IGNORED_TESTS`:: lists of `pytest -k` patterns of tests to ignore (defaults to empty). For tests which are not expected to pass, such as ones requiring a database access. `PYTEST_BROKEN_TESTS`:: lists of `pytest -k` patterns of tests to ignore (defaults to empty). For broken tests which require fixing. In addition the following variables may be set by the user: `PYTEST_ENABLE_IGNORED_TESTS`:: Enable tests which are otherwise ignored by `PYTEST_IGNORED_TESTS`. `PYTEST_ENABLE_BROKEN_TESTS`:: Enable tests which are otherwise ignored by `PYTEST_BROKEN_TESTS`. `PYTEST_ENABLE_ALL_TESTS`:: Enable tests which are otherwise ignored by `PYTEST_IGNORED_TESTS` and `PYTEST_BROKEN_TESTS`. [[uses-python]] == `python` Possible arguments: (none), `_X.Y_`, `_X.Y+_`, `_-X.Y_`, `_X.Y-Z.A_`, `patch`, `build`, `run`, `test` Uses Python. A supported version or version range can be specified. If Python is only needed at build time, run time or for the tests, it can be set as a build, run or test dependency with `build`, `run`, or `test`. If Python is also needed during the patch phase, use `patch`. See crossref:special[using-python, Using Python] for more information. `PYTHON_NO_DEPENDS=yes` can be used when the variables exported by the framework are needed but a dependency on Python is not. It can happen when using with <>, and the goal is only to fix the shebangs but not add a dependency on Python. [[uses-qmail]] == `qmail` Possible arguments: (none), `build`, `run`, `both`, `vars` Uses package:mail/qmail[]. With the `build` argument, it implies `qmail` as a build-time dependency. `run` implies a run-time dependency. Using no argument or the `both` argument implies both run-time and build-time dependencies. `vars` will only set QMAIL variables for the port to use. [[uses-qmake]] == `qmake` Possible arguments: (none), `norecursive`, `outsource`, `no_env`, `no_configure` Uses QMake for configuring. For more information see crossref:special[using-qmake,Using `qmake`]. [[uses-qt]] == `qt` Possible arguments: `5`, `no_env` Add dependency on Qt components. `no_env` is passed directly to `USES= qmake`. See crossref:special[using-qt,Using Qt] for more information. [[uses-qt-dist]] == `qt-dist` Possible arguments: (none) or `5` and (none) or one of `3d`, `activeqt`, `androidextras`, `base`, `canvas3d`, `charts`, `connectivity`, `datavis3d`, `declarative`, `doc`, `gamepad`, `graphicaleffects`, `imageformats`, `location`, `macextras`, `multimedia`, `networkauth`, `purchasing`, `quickcontrols2`, `quickcontrols`, `remoteobjects`, `script`, `scxml`, `sensors`, `serialbus`, `serialport`, `speech`, `svg`, `tools`, `translations`, `virtualkeyboard`, `wayland`, `webchannel`, `webengine`, `websockets`, `webview`, `winextras`, `x11extras`, `xmlpatterns` Provides support for building Qt 5 components. It takes care of setting up the appropriate configuration environment for the port to build. [[qt5-dist-example]] .Building Qt 5 Components [example] ==== The port is Qt 5's `networkauth` component, which is part of the `networkauth` distribution file. [.programlisting] .... PORTNAME= networkauth DISTVERSION= ${QT5_VERSION} USES= qt-dist:5 .... ==== If `PORTNAME` does not match the component name, it can be passed as an argument to `qt-dist`. [[qt5-dist-example-explicit]] .Building Qt 5 Components with Different Names [example] ==== The port is Qt 5's `gui` component, which is part of the `base` distribution file. [.programlisting] .... PORTNAME= gui DISTVERSION= ${QT5_VERSION} USES= qt-dist:5,base .... ==== [[uses-readline]] == `readline` Possible arguments: (none), `port` Uses readline as a library dependency, and sets `CPPFLAGS` and `LDFLAGS` as necessary. If the `port` argument is used or if readline is not present in the base system, add a dependency on package:devel/readline[] [[uses-samba]] == `samba` Possible arguments: `build`, `env`, `lib`, `run` Handle dependency on Samba. `env` will not add any dependency and only set up the variables. `build` and `run` will add build-time and run-time dependency on [.filename]#smbd#. `lib` will add a dependency on [.filename]#libsmbclient.so#. The variables that are exported are: `SAMBAPORT`:: The origin of the default Samba port. `SAMBAINCLUDES`:: The location of the Samba header files. `SAMBALIBS`:: The directory where the Samba shared libraries are available. [[uses-scons]] == `scons` Possible arguments: (none) Provide support for the use of package:devel/scons[]. See crossref:special[using-scons,Using `scons`] for more information. [[uses-shared-mime-info]] == `shared-mime-info` Possible arguments: (none) Uses update-mime-database from package:misc/shared-mime-info[]. This uses will automatically add a post-install step in such a way that the port itself still can specify there own post-install step if needed. It also add an crossref:plist[plist-keywords-shared-mime-info,`@shared-mime-info`] entry to the plist. [[uses-shebangfix]] == `shebangfix` Possible arguments: (none) A lot of software uses incorrect locations for script interpreters, most notably [.filename]#/usr/bin/perl# and [.filename]#/bin/bash#. The shebangfix macro fixes shebang lines in scripts listed in `SHEBANG_REGEX`, `SHEBANG_GLOB`, or `SHEBANG_FILES`. `SHEBANG_REGEX`:: Contains _one_ extended regular expressions, and is used with the `-iregex` argument of man:find[1]. See <>. `SHEBANG_GLOB`:: Contains a list of patterns used with the `-name` argument of man:find[1]. See <>. `SHEBANG_FILES`:: Contains a list of files or man:sh[1] globs. The shebangfix macro is run from `${WRKSRC}`, so `SHEBANG_FILES` can contain paths that are relative to `${WRKSRC}`. It can also deal with absolute paths if files outside of `${WRKSRC}` require patching. See <>. Currently Bash, Java, Ksh, Lua, Perl, PHP, Python, Ruby, Tcl, and Tk are supported by default. There are three configuration variables: `SHEBANG_LANG`:: The list of supported interpreters. `_interp__CMD`:: The path to the command interpreter on FreeBSD. The default value is `${LOCALBASE}/bin/_interp_`. `_interp__OLD_CMD`:: The list of wrong invocations of interpreters. These are typically obsolete paths, or paths used on other operating systems that are incorrect on FreeBSD. They will be replaced by the correct path in `_interp__CMD`. + [NOTE] ==== These will _always_ be part of `_interp__OLD_CMD`: `"/usr/bin/env _interp_" /bin/_interp_ /usr/bin/_interp_ /usr/local/bin/_interp_`. ==== + [TIP] ==== `_interp__OLD_CMD` contain multiple values. Any entry with spaces must be quoted. See <>. ==== [IMPORTANT] ==== The fixing of shebangs is done during the `patch` phase. If scripts are created with incorrect shebangs during the `build` phase, the build process (for example, the [.filename]#configure# script, or the [.filename]#Makefiles#) must be patched or given the right path (for example, with `CONFIGURE_ENV`, `CONFIGURE_ARGS`, `MAKE_ENV`, or `MAKE_ARGS`) to generate the right shebangs. Correct paths for supported interpreters are available in `_interp__CMD`. ==== [TIP] ==== When used with <>, and the aim is only to fix the shebangs but a dependency on Python itself is not wanted, use `PYTHON_NO_DEPENDS=yes`. ==== [[uses-shebangfix-ex-lua]] .Adding Another Interpreter to `USES=shebangfix` [example] ==== To add another interpreter, set `SHEBANG_LANG`. For example: [.programlisting] .... SHEBANG_LANG= lua .... ==== [[uses-shebangfix-ex-ksh]] .Specifying all the Paths When Adding an Interpreter to `USES=shebangfix` [example] ==== If it was not already defined, and there were no default values for `_interp__OLD_CMD` and `_interp__CMD` the Ksh entry could be defined as: [.programlisting] .... SHEBANG_LANG= ksh ksh_OLD_CMD= "/usr/bin/env ksh" /bin/ksh /usr/bin/ksh ksh_CMD= ${LOCALBASE}/bin/ksh .... ==== [[uses-shebangfix-ex-strange]] .Adding a Strange Location for an Interpreter [example] ==== Some software uses strange locations for an interpreter. For example, an application might expect Python to be located in [.filename]#/opt/bin/python2.7#. The strange path to be replaced can be declared in the port [.filename]#Makefile#: [.programlisting] .... python_OLD_CMD= /opt/bin/python2.7 .... ==== [[uses-shebangfix-ex-regex]] .`USES=shebangfix` with `SHEBANG_REGEX` [example] ==== To fix all the files in `${WRKSRC}/scripts` ending in [.filename]#.pl#, [.filename]#.sh#, or [.filename]#.cgi# do: [.programlisting] .... USES= shebangfix SHEBANG_REGEX= ./scripts/.*\.(sh|pl|cgi) .... [NOTE] ====== `SHEBANG_REGEX` is used by running `find -E`, which uses modern regular expressions also known as extended regular expressions. See man:re_format[7] for more information. ====== ==== [[uses-shebangfix-ex-glob]] .`USES=shebangfix` with `SHEBANG_GLOB` [example] ==== To fix all the files in `${WRKSRC}` ending in [.filename]#.pl# or [.filename]#.sh#, do: [.programlisting] .... USES= shebangfix SHEBANG_GLOB= *.sh *.pl .... ==== [[uses-shebangfix-ex-files]] .`USES=shebangfix` with `SHEBANG_FILES` [example] ==== To fix the files [.filename]#script/foobar.pl# and [.filename]#script/*.sh# in `${WRKSRC}`, do: [.programlisting] .... USES= shebangfix SHEBANG_FILES= scripts/foobar.pl scripts/*.sh .... ==== [[uses-sqlite]] == `sqlite` Possible arguments: (none), `2`, `3` Add a dependency on SQLite. The default version used is 3, but version 2 is also possible using the `:2` modifier. [[uses-ssl]] == `ssl` Possible arguments: (none), `build`, `run` Provide support for OpenSSL. A build- or run-time only dependency can be specified using `build` or `run`. These variables are available for the port's use, they are also added to `MAKE_ENV`: `OPENSSLBASE`:: Path to the OpenSSL installation base. `OPENSSLDIR`:: Path to OpenSSL's configuration files. `OPENSSLLIB`:: Path to the OpenSSL libraries. `OPENSSLINC`:: Path to the OpenSSL includes. `OPENSSLRPATH`:: If defined, the path the linker needs to use to find the OpenSSL libraries. [TIP] ==== If a port does not build with an OpenSSL flavor, set the `BROKEN_SSL` variable, and possibly the `BROKEN_SSL_REASON__flavor_`: [.programlisting] .... BROKEN_SSL= libressl BROKEN_SSL_REASON_libressl= needs features only available in OpenSSL .... ==== [[uses-tar]] == `tar` Possible arguments: (none), `Z`, `bz2`, `bzip2`, `lzma`, `tbz`, `tbz2`, `tgz`, `txz`, `xz`, `zst`, `zstd` Set `EXTRACT_SUFX` to `.tar`, `.tar.Z`, `.tar.bz2`, `.tar.bz2`, `.tar.lzma`, `.tbz`, `.tbz2`, `.tgz`, `.txz`, `.tar.xz`, `.tar.zst` or `.tar.zstd` respectively. [[uses-tcl]] == `tcl` Possible arguments: _version_, `wrapper`, `build`, `run`, `tea` Add a dependency on Tcl. A specific version can be requested using _version_. The version can be empty, one or more exact version numbers (currently `84`, `85`, or `86`), or a minimal version number (currently `84+`, `85+` or `86+`). To only request a non version specific wrapper, use `wrapper`. A build- or run-time only dependency can be specified using `build` or `run`. To build the port using the Tcl Extension Architecture, use `tea`. After including [.filename]#bsd.port.pre.mk# the port can inspect the results using these variables: * `TCL_VER`: chosen major.minor version of Tcl * `TCLSH`: full path of the Tcl interpreter * `TCL_LIBDIR`: path of the Tcl libraries * `TCL_INCLUDEDIR`: path of the Tcl C header files * `TK_VER`: chosen major.minor version of Tk * `WISH`: full path of the Tk interpreter * `TK_LIBDIR`: path of the Tk libraries * `TK_INCLUDEDIR`: path of the Tk C header files [[uses-terminfo]] == `terminfo` Possible arguments: (none) Adds crossref:plist[plist-keywords-terminfo,`@terminfo`] to the [.filename]#plist#. Use when the port installs [.filename]#*.terminfo# files in [.filename]#${PREFIX}/share/misc#. [[uses-tk]] == `tk` Same as arguments for `tcl` Small wrapper when using both Tcl and Tk. The same variables are returned as when using Tcl. [[uses-uidfix]] == `uidfix` Possible arguments: (none) Changes some default behavior (mostly variables) of the build system to allow installing this port as a normal user. Try this in the port before using <> or patching. [[uses-uniquefiles]] == `uniquefiles` Possible arguments: (none), `dirs` Make files or directories 'unique', by adding a prefix or suffix. If the `dirs` argument is used, the port needs a prefix (and only a prefix) based on `UNIQUE_PREFIX` for standard directories `DOCSDIR`, `EXAMPLESDIR`, `DATADIR`, `WWWDIR`, `ETCDIR`. These variables are available for ports: * `UNIQUE_PREFIX`: The prefix to be used for directories and files. Default: `${PKGNAMEPREFIX}`. * `UNIQUE_PREFIX_FILES`: A list of files that need to be prefixed. Default: empty. * `UNIQUE_SUFFIX`: The suffix to be used for files. Default: `${PKGNAMESUFFIX}`. * `UNIQUE_SUFFIX_FILES`: A list of files that need to be suffixed. Default: empty. [[uses-varnish]] == `varnish` Possible arguments: `4` (default), `6`, `7` Handle dependencies on Varnish Cache. Adds a dependency on package:www/varnish*[]. [[uses-webplugin]] == `webplugin` Possible arguments: (none), `ARGS` Automatically create and remove symbolic links for each application that supports the webplugin framework. `ARGS` can be one of: * `gecko`: support plug-ins based on Gecko * `native`: support plug-ins for Gecko, Opera, and WebKit-GTK * `linux`: support Linux plug-ins * `all` (default, implicit): support all plug-in types * (individual entries): support only the browsers listed These variables can be adjusted: * `WEBPLUGIN_FILES`: No default, must be set manually. The plug-in files to install. * `WEBPLUGIN_DIR`: The directory to install the plug-in files to, default [.filename]#PREFIX/lib/browser_plugins/WEBPLUGIN_NAME#. Set this if the port installs plug-in files outside of the default directory to prevent broken symbolic links. * `WEBPLUGIN_NAME`: The final directory to install the plug-in files into, default `PKGBASE`. [[uses-xfce]] == `xfce` Possible arguments: (none), `gtk2` Provide support for Xfce related ports. See crossref:special[using-xfce,Using Xfce] for details. The `gtk2` argument specifies that the port requires GTK2 support. It adds additional features provided by some core components, for example, package:x11/libxfce4menu[] and package:x11-wm/xfce4-panel[]. [[uses-xorg]] == `xorg` Possible arguments: (none) Provides an easy way to depend on X.org components. The components should be listed in `USE_XORG`. The available components are: [[using-x11-components]] .Available X.Org Components [cols="1,1", frame="none", options="header"] |=== | Name | Description |`dmx` |DMX extension library |`fontenc` |The fontenc Library |`fontutil` |Create an index of X font files in a directory |`ice` |Inter Client Exchange library for X11 |`libfs` |The FS library |`pciaccess` |Generic PCI access library |`pixman` |Low-level pixel manipulation library |`sm` |Session Management library for X11 |`x11` |X11 library |`xau` |Authentication Protocol library for X11 |`xaw` |X Athena Widgets library |`xaw6` |X Athena Widgets library |`xaw7` |X Athena Widgets library |`xbitmaps` |X.Org bitmaps data |`xcb` |The X protocol C-language Binding (XCB) library |`xcomposite` |X Composite extension library |`xcursor` |X client-side cursor loading library |`xdamage` |X Damage extension library |`xdmcp` |X Display Manager Control Protocol library |`xext` |X11 Extension library |`xfixes` |X Fixes extension library |`xfont` |X font library |`xfont2` |X font library |`xft` |Client-sided font API for X applications |`xi` |X Input extension library |`xinerama` |X11 Xinerama library |`xkbfile` |XKB file library |`xmu` |X Miscellaneous Utilities libraries |`xmuu` |X Miscellaneous Utilities libraries |`xorg-macros` |X.Org development aclocal macros |`xorg-server` |X.Org X server and related programs |`xorgproto` |xorg protocol headers |`xpm` |X Pixmap library |`xpresent` |X Present Extension library |`xrandr` |X Resize and Rotate extension library |`xrender` |X Render extension library |`xres` |X Resource usage library |`xscrnsaver` |The XScrnSaver library |`xshmfence` |Shared memory 'SyncFence' synchronization primitive |`xt` |X Toolkit library |`xtrans` |Abstract network code for X |`xtst` |X Test extension |`xv` |X Video Extension library |`xvmc` |X Video Extension Motion Compensation library |`xxf86dga` |X DGA Extension |`xxf86vm` |X Vidmode Extension |=== [[uses-xorg-cat]] == `xorg-cat` Possible arguments: `app`, `data`, `doc`, `driver`, `font`, `lib`, `proto`, `util`, `xserver` and (none) or one off `autotools` (default), `meson` Provide support for building Xorg components. It takes care of setting up common dependencies and an appropriate configuration environment needed. This is intended only for Xorg components. The category has to match upstream categories. The second argument is the build system to use. autotools is the default, but meson is also supported. [[uses-zip]] == `zip` Possible arguments: (none), `infozip` Indicates that the distribution files use the ZIP compression algorithm. For files using the InfoZip algorithm the `infozip` argument must be passed to set the appropriate dependencies.