Many ports depend on other ports. This is a very convenient
feature of most Unix-like operating systems, including FreeBSD.
Multiple ports can share a common dependency, rather than
bundling that dependency with every port or package that needs
it. There are seven variables that can be used to ensure that
all the required bits will be on the user's machine. There are
also some pre-supported dependency variables for common cases,
plus a few more to control the behavior of dependencies.
Important:
When software has extra dependencies that provide extra
features, the base dependencies listed in
*_DEPENDS
This variable specifies the shared libraries this port
depends on. It is a list of
lib:dir
tuples where lib is the name of
the shared library, dir is the
directory in which to find it in case it is not available.
For example,
LIB_DEPENDS= libjpeg.so:graphics/jpeg
will check for a shared jpeg library with any version, and
descend into the graphics/jpeg
subdirectory of the ports tree to build and install it if it
is not found.
The dependency is checked twice, once from within the
build target and then from within
the install target. Also, the name
of the dependency is put into the package so that
pkg install (see pkg-install(8)) will
automatically install it if it is not on the user's
system.
This variable specifies executables or files this port
depends on during run-time. It is a list of
path:dir[:target]
tuples where path is the name of
the executable or file, dir is the
directory in which to find it in case it is not available, and
target is the target to call in
that directory. If path starts
with a slash (/), it is treated as a file
and its existence is tested with test -e;
otherwise, it is assumed to be an executable, and
which -s is used to determine if the
program exists in the search path.
For example,
RUN_DEPENDS= ${LOCALBASE}/news/bin/innd:news/inn \
xmlcatmgr:textproc/xmlcatmgrwill check if the file or directory
/usr/local/news/bin/innd exists, and
build and install it from the news/inn
subdirectory of the ports tree if it is not found. It will
also see if an executable called xmlcatmgr
is in the search path, and descend into
textproc/xmlcatmgr
to build and install it if it is not found.
Note:
In this case, innd is actually an
executable; if an executable is in a place that is not
expected to be in the search path, use the full
pathname.
Note:
The official search PATH used on the
ports build cluster is
/sbin:/bin:/usr/sbin:/usr/bin:/usr/local/sbin:/usr/local/bin
The dependency is checked from within the
install target. Also, the name of
the dependency is put into the package so that
pkg install (see pkg-install(8)) will
automatically install it if it is not on the user's system.
The target part can be omitted if
it is the same as DEPENDS_TARGET.
A quite common situation is when
RUN_DEPENDS is literally the same as
BUILD_DEPENDS, especially if ported
software is written in a scripted language or if it requires
the same build and run-time environment. In this case, it is
both tempting and intuitive to directly assign one to the
other:
RUN_DEPENDS= ${BUILD_DEPENDS}However, such assignment can pollute run-time
dependencies with entries not defined in the port's original
BUILD_DEPENDS. This happens because of
make(1)'s lazy evaluation of variable assignment.
Consider a Makefile with
USE_*,
which are processed by ports/Mk/bsd.*.mk
to augment initial build dependencies. For example,
USES= gmake adds
devel/gmake to
BUILD_DEPENDS. To prevent such additional
dependencies from polluting RUN_DEPENDS,
create another variable with the current content of
BUILD_DEPENDS and assign it to both
BUILD_DEPENDS and
RUN_DEPENDS:
MY_DEPENDS= some:devel/some \
other:lang/other
BUILD_DEPENDS= ${MY_DEPENDS}
RUN_DEPENDS= ${MY_DEPENDS}Important:
Do not use :=
to assign BUILD_DEPENDS to
RUN_DEPENDS or vice-versa. All
variables are expanded immediately, which is exactly the
wrong thing to do and almost always a failure.
This variable specifies executables or files this port
requires to build. Like RUN_DEPENDS, it
is a list of
path:dir[:target]
tuples. For example,
BUILD_DEPENDS= unzip:archivers/unzip
will check for an executable called
unzip, and descend into the
archivers/unzip subdirectory of the
ports tree to build and install it if it is not found.
Note:
“build” here means everything from
extraction to compilation. The dependency is checked from
within the extract target. The
target part can be omitted if it
is the same as DEPENDS_TARGET
This variable specifies executables or files this port
requires to fetch. Like the previous two, it is a list of
path:dir[:target]
tuples. For example,
FETCH_DEPENDS= ncftp2:net/ncftp2
will check for an executable called
ncftp2, and descend into the
net/ncftp2 subdirectory of the ports
tree to build and install it if it is not found.
The dependency is checked from within the
fetch target. The
target part can be omitted if it is
the same as DEPENDS_TARGET.
This variable specifies executables or files this port
requires for extraction. Like the previous, it is a list of
path:dir[:target]
tuples. For example,
EXTRACT_DEPENDS= unzip:archivers/unzip
will check for an executable called
unzip, and descend into the
archivers/unzip subdirectory of the
ports tree to build and install it if it is not found.
The dependency is checked from within the
extract target. The
target part can be omitted if it
is the same as DEPENDS_TARGET.
Note:
Use this variable only if the extraction does not
already work (the default assumes tar)
and cannot be made to work using
USES=tar, USES=lha or
USES=zip described in Chapter 17, Using USES Macros.
This variable specifies executables or files this port
requires to patch. Like the previous, it is a list of
path:dir[:target]
tuples. For example,
PATCH_DEPENDS= ${NONEXISTENT}:java/jfc:extractwill descend into the java/jfc
subdirectory of the ports tree to extract it.
The dependency is checked from within the
patch target. The
target part can be omitted if it
is the same as DEPENDS_TARGET.
Parameters can be added to define different features and
dependencies used by the port. They are specified by adding
this line to the Makefile:
USES= feature[:arguments]
For the complete list of values, please see
Chapter 17, Using USES Macros.
Warning:
USES cannot be assigned after
inclusion of bsd.port.pre.mk.
Several variables exist to define common dependencies
shared by many ports. Their use is optional, but helps to
reduce the verbosity of the port
Makefiles. Each of them is styled as
USE_*. These
variables may be used only in the port
Makefiles and
ports/Mk/bsd.*.mk. They are not meant
for user-settable options — use
PORT_OPTIONS for that purpose.
Note:
It is always incorrect to set any
USE_* in
/etc/make.conf. For instance,
setting
USE_GCC=X.Y
(where X.Y is version number) would add a dependency
on gccXY for every port, including
lang/gccXY itself!
Table 5.8. USE_*
| Variable | Means |
|---|
USE_GCC |
The port requires GCC (gcc or
g++) to build. Some ports need any
GCC version, some require modern, recent versions. It
is typically set to any (in this
case, GCC from base would be used on versions of FreeBSD
that still have it, or lang/gcc
port would be installed when default C/C++ compiler is
Clang); or yes (means always use
stable, modern GCC from lang/gcc
port). The exact version can also be specified, with
a value such as 4.7. The minimal
required version can be specified as
4.6+. The GCC from the base system
is used when it satisfies the requested version,
otherwise an appropriate compiler is built from the
port, and CC and
CXX are adjusted
accordingly.
Note: USE_GCC will register a
build-time and a run-time dependency.
|
Variables related to gmake and
configure are described in
Section 6.5, “Building Mechanisms”, while
autoconf,
automake and
libtool are described in
Section 6.6, “Using GNU Autotools”.
Perl related variables are
described in Section 6.8, “Using Perl”. X11 variables are
listed in Section 6.9, “Using X11”.
Section 6.10, “Using GNOME” deals with GNOME and
Section 6.13, “Using KDE” with KDE related variables.
Section 6.15, “Using Java” documents Java variables, while
Section 6.16, “Web Applications, Apache and PHP” contains information on
Apache,
PHP and PEAR modules.
Python is discussed in
Section 6.17, “Using Python”, while
Ruby in
Section 6.19, “Using Ruby”. Section 6.20, “Using SDL”
provides variables used for SDL
applications and finally, Section 6.24, “Using Xfce”
contains information on
Xfce.
5.9.9. Minimal Version of a Dependency
A minimal version of a dependency can be specified in any
*_DEPENDSLIB_DEPENDS using this
syntax:
p5-Spiffy>=0.26:devel/p5-Spiffy
The first field contains a dependent package name, which
must match the entry in the package database, a comparison
sign, and a package version. The dependency is satisfied if
p5-Spiffy-0.26 or newer is installed on the machine.
5.9.10. Notes on Dependencies
As mentioned above, the default target to call when a
dependency is required is
DEPENDS_TARGET. It defaults to
install. This is a user variable; it is
never defined in a port's Makefile. If
the port needs a special way to handle a dependency, use the
:target part of
*_DEPENDSDEPENDS_TARGET.
When running make clean, the port
dependencies are automatically cleaned too. If this is not
desirable, define
NOCLEANDEPENDS in the environment. This
may be particularly desirable if the port has something that
takes a long time to rebuild in its dependency list, such as
KDE, GNOME or Mozilla.
To depend on another port unconditionally, use the
variable ${NONEXISTENT} as the first field
of BUILD_DEPENDS or
RUN_DEPENDS. Use this only when
the source of the other port is needed. Compilation time can
be saved by specifying the target too. For
instance
BUILD_DEPENDS= ${NONEXISTENT}:graphics/jpeg:extractwill always descend to the jpeg port
and extract it.
5.9.11. Circular Dependencies Are Fatal
Important:
Do not introduce any circular dependencies into the
ports tree!
The ports building technology does not tolerate circular
dependencies. If one is introduced, someone, somewhere in the
world, will have their FreeBSD installation broken
almost immediately, with many others quickly to follow. These
can really be hard to detect. If in doubt, before making
that change, make sure to run:
cd /usr/ports; make index. That process
can be quite slow on older machines, but it may be able to
save a large number of people, including yourself,
a lot of grief in the process.
5.9.12. Problems Caused by Automatic Dependencies
Dependencies must be declared either explicitly or by
using the
OPTIONS framework.
Using other methods like automatic detection complicates
indexing, which causes problems for port and package
management.
Example 5.37. Wrong Declaration of an Optional Dependency
.include <bsd.port.pre.mk>
.if exists(${LOCALBASE}/bin/foo)
LIB_DEPENDS= libbar.so:foo/bar
.endifThe problem with trying to automatically add dependencies
is that files and settings outside an individual port can
change at any time. For example: an index is built, then a
batch of ports are installed. But one of the ports installs
the tested file. The index is now incorrect, because an
installed port unexpectedly has a new dependency. The index
may still be wrong even after rebuilding if other ports also
determine their need for dependencies based on the existence
of other files.
Example 5.38. Correct Declaration of an Optional Dependency
OPTIONS_DEFINE= BAR
BAR_DESC= Calling cellphones via bar
BAR_LIB_DEPENDS= libbar.so:foo/bar
Testing option variables is the correct method. It will
not cause inconsistencies in the index of a batch of ports,
provided the options were defined prior to the index build.
Simple scripts can then be used to automate the building,
installation, and updating of these ports and their
packages.
Chapter 6. Special Considerations
This section explains the most common things to consider when
creating a port.
bsd.port.mk expects ports to work
with a “stage directory”. This means that a port
must not install files directly to the regular destination
directories (that is, under PREFIX, for
example) but instead into a separate directory from which the
package is then built. In many cases, this does not require
root privileges, making it possible to build packages as an
unprivileged user. With staging, the port is built and
installed into the stage directory,
STAGEDIR. A package is created from the
stage directory and then installed on the system. Automake
tools refer to this concept as DESTDIR, but
in FreeBSD, DESTDIR has a different meaning
(see Section 10.4, “PREFIX and
DESTDIR”).
Note:
No port really needs to be root. It
can mostly be avoided by using USES=uidfix.
If the port still runs commands like chown(8),
chgrp(1), or forces owner or group with install(1)
then use USES=fakeroot
to fake those calls. Some patching of the port's
Makefiles will be needed.
Meta ports, or ports that do not install files themselves
but only depend on other ports, must avoid needlessly
extracting the mtree(8) to the stage directory. This is
the basic directory layout of the package, and these empty
directories will be seen as orphans. To prevent
mtree(8) extraction, add this line:
NO_MTREE= yes
Tip:
Metaports should use USES=metaport.
It sets up defaults for ports that do not fetch, build, or
install anything.
Staging is enabled by prepending
STAGEDIR to paths used in the
pre-install,
do-install, and
post-install targets (see the
examples through the book). Typically, this includes
PREFIX, ETCDIR,
DATADIR, EXAMPLESDIR,
MANPREFIX, DOCSDIR, and
so on. Directories should be created as part of the
post-install target. Avoid using
absolute paths whenever possible.
Tip:
Ports that install kernel modules must prepend
STAGEDIR to their destination, by default
/boot/modules.
6.1.1. Handling Symbolic Links
When creating a symbolic link, relative ones are strongly
recommended. Use ${RLN} to create relative
symbolic links. It uses install(1) under the hood to
automatically figure out the relative link to create.
Example 6.1. Create Relative Symbolic Links Automatically
${RLN} uses install(1)'s
relative symbolic feature which frees the porter of
computing the relative path.
${RLN} ${STAGEDIR}${PREFIX}/lib/libfoo.so.42 ${STAGEDIR}${PREFIX}/lib/libfoo.so
${RLN} ${STAGEDIR}${PREFIX}/libexec/foo/bar ${STAGEDIR}${PREFIX}/bin/bar
${RLN} ${STAGEDIR}/var/cache/foo ${STAGEDIR}${PREFIX}/share/fooWill generate:
% ls -lF ${STAGEDIR}${PREFIX}/lib
lrwxr-xr-x 1 nobody nobody 181 Aug 3 11:27 libfoo.so@ -> libfoo.so.42
-rwxr-xr-x 1 nobody nobody 15 Aug 3 11:24 libfoo.so.42*
% ls -lF ${STAGEDIR}${PREFIX}/bin
lrwxr-xr-x 1 nobody nobody 181 Aug 3 11:27 bar@ -> ../libexec/foo/bar
% ls -lF ${STAGEDIRDIR}${PREFIX}/share
lrwxr-xr-x 1 nobody nobody 181 Aug 3 11:27 foo@ -> ../../../var/cache/foo
This section explains why bundled dependencies are
considered bad and what to do about them.
6.2.1. Why Bundled Libraries Are Bad
Some software requires the porter to locate third-party
libraries and add the required dependencies to the port.
Other software bundles all necessary libraries into the
distribution file. The second approach seems easier at
first, but there are some serious drawbacks:
This list is loosely based on the Fedora
and Gentoo
wikis, both licensed under the CC-BY-SA
3.0 license.
- Security
If vulnerabilities are found in the upstream library
and fixed there, they might not be fixed in the library
bundled with the port. One reason could be that the
author is not aware of the problem. This means that the
porter must fix them, or upgrade to a non-vulnerable
version, and send a patch to the author. This all takes
time, which results in software being vulnerable longer
than necessary. This in turn makes it harder to
coordinate a fix without unnecessarily leaking
information about the vulnerability.
- Bugs
This problem is similar to the problem with security
in the last paragraph, but generally less severe.
- Forking
It is easier for the author to fork the upstream
library once it is bundled. While convenient on first
sight, it means that the code diverges from upstream
making it harder to address security or other problems
with the software. A reason for this is that patching
becomes harder.
Another problem of forking is that because code
diverges from upstream, bugs get solved over and over
again instead of just once at a central location. This
defeats the idea of open source software in the first
place.
- Symbol collision
When a library is installed on the system, it might
collide with the bundled version. This can cause
immediate errors at compile or link time. It can also
cause errors when running the program which might be
harder to track down. The latter problem could be
caused because the versions of the two libraries are
incompatible.
- Licensing
When bundling projects from different sources,
license issues can arise more easily, especially when
licenses are incompatible.
- Waste of resources
Bundled libraries waste resources on several levels.
It takes longer to build the actual application,
especially if these libraries are already present on the
system. At run-time, they can take up unnecessary
memory when the system-wide library is already loaded by
one program and the bundled library is loaded by another
program.
- Waste of effort
When a library needs patches for FreeBSD, these patches
have to be duplicated again in the bundled library.
This wastes developer time because the patches might not
apply cleanly. It can also be hard to notice that these
patches are required in the first place.
6.2.2. What to do About Bundled Libraries
Whenever possible, use the unbundled version of the
library by adding a LIB_DEPENDS to the
port. If such a port does not exist yet, consider creating
it.
Only use bundled libraries if the upstream has a
good track record on security and using unbundled versions
leads to overly complex patches.
Note:
In some very special cases, for example emulators, like
Wine, a port has to bundle
libraries, because they are in a different architecture, or
they have been modified to fit the software's use. In that
case, those libraries should not be exposed to other ports
for linking. Add BUNDLE_LIBS=yes to the
port's Makefile. This will tell
pkg(8) to not compute provided libraries. Always ask
the Ports Management Team <portmgr@FreeBSD.org> before adding this to a port.
If the port installs one or more shared libraries, define
a USE_LDCONFIG make variable, which will
instruct a bsd.port.mk to run
${LDCONFIG} -m on the directory
where the new library is installed (usually
PREFIX/lib) during
post-install target to register it
into the shared library cache. This variable, when defined,
will also facilitate addition of an appropriate
@exec /sbin/ldconfig -m and
@unexec /sbin/ldconfig -R pair into
pkg-plist, so that a user who
installed the package can start using the shared library
immediately and de-installation will not cause the system to
still believe the library is there.
USE_LDCONFIG= yes
The default directory can be overridden by
setting USE_LDCONFIG to a list of
directories into which shared libraries are to be installed.
For example, if the port installs shared libraries into
PREFIX/lib/foo and
PREFIX/lib/bar
use this in
Makefile:
USE_LDCONFIG= ${PREFIX}/lib/foo ${PREFIX}/lib/barPlease double-check, often this is not necessary at all or
can be avoided through -rpath or setting
LD_RUN_PATH during linking (see
lang/mosml for an
example), or through a shell-wrapper which sets
LD_LIBRARY_PATH before invoking the binary,
like www/seamonkey
does.
When installing 32-bit libraries on 64-bit system, use
USE_LDCONFIG32 instead.
If the software uses autotools, and specifically
libtool, add USES=libtool.
When the major library version number increments in the
update to the new port version, all other ports that link to
the affected library must have their
PORTREVISION incremented, to force
recompilation with the new library version.
6.4. Ports with Distribution Restrictions or Legal
Concerns
Licenses vary, and some of them place restrictions on how
the application can be packaged, whether it can be sold for
profit, and so on.
Important:
It is the responsibility of a porter to read the
licensing terms of the software and make sure that the
FreeBSD project will not be held accountable for violating
them by redistributing the source or compiled binaries
either via FTP/HTTP or CD-ROM. If in doubt, please contact
the FreeBSD ports mailing list.
In situations like this, the variables described in the
next sections can be set.
This variable indicates that we may not generate a
binary package of the application. For instance, the
license may disallow binary redistribution, or it may
prohibit distribution of packages created from patched
sources.
However, the port's DISTFILES may be
freely mirrored on FTP/HTTP. They may also be distributed
on a CD-ROM (or similar media) unless
NO_CDROM is set as well.
If the
binary package is not generally useful, and the application
must always be compiled from the source code, use
NO_PACKAGE. For
example, if the application has configuration information
that is site specific hard coded into it at compile time,
set NO_PACKAGE.
Set NO_PACKAGE to a string
describing the reason why the package cannot be
generated.
This variable alone indicates that, although we are
allowed to generate binary packages, we may put neither
those packages nor the port's DISTFILES
onto a CD-ROM (or similar media) for resale. However, the
binary packages and the port's DISTFILES
will still be available via FTP/HTTP.
If this variable is set along with
NO_PACKAGE, then only the port's
DISTFILES will be available, and only via
FTP/HTTP.
Set NO_CDROM to a string
describing the reason why the port cannot be redistributed
on CD-ROM. For instance, use this if the port's
license is for “non-commercial” use
only.
Files defined in NOFETCHFILES
are not fetchable from any of
MASTER_SITES. An example of such a file
is when the file is supplied on CD-ROM by the vendor.
Tools which check for the availability of these files
on MASTER_SITES have to ignore these
files and not report about them.
Set this variable alone if the application's license
permits neither mirroring the application's
DISTFILES nor distributing the binary
package in any way.
Do not set NO_CDROM or
NO_PACKAGE along with
RESTRICTED, since the latter variable
implies the former ones.
Set RESTRICTED to a string
describing the reason why the port cannot be redistributed.
Typically, this indicates that the port contains proprietary
software and that the user will need to manually download
the DISTFILES, possibly after registering
for the software or agreeing to accept the terms of an
EULA.
When RESTRICTED or
NO_CDROM is set, this variable defaults
to ${DISTFILES} ${PATCHFILES}, otherwise
it is empty. If only some of the distribution files are
restricted, then set this variable to list them.
If the port has legal concerns not addressed by the
above variables, set LEGAL_TEXT
to a string explaining the concern. For
example, if special permission was obtained for FreeBSD to
redistribute the binary, this variable must indicate
so.
6.4.7. /usr/ports/LEGAL and
LEGAL
A port which sets any of the above variables must also
be added to /usr/ports/LEGAL. The
first column is a glob which matches the restricted
distfiles. The second column is the port's origin. The
third column is the output of
make -VLEGAL.
The preferred way to state "the distfiles for this port
must be fetched manually" is as follows:
.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}
.endifThis both informs the user, and sets the proper metadata
on the user's machine for use by automated programs.
Note that this stanza must be preceded by an inclusion
of bsd.port.pre.mk.
6.5.1. Building Ports in Parallel
The FreeBSD ports framework supports parallel building
using multiple make sub-processes, which
allows SMP systems to utilize all of
their available CPU power, allowing port
builds to be faster and more effective.
This is achieved by passing -jX flag
to make(1) running on vendor code. This is the default
build behavior of ports. Unfortunately, not all ports
handle parallel building well and it may be required to
explicitly disable this feature by adding the
MAKE_JOBS_UNSAFE=yes variable. It is
used when a port is known to be broken with
-jX due to race conditions causing
intermittent build failures.
Important:
When setting MAKE_JOBS_UNSAFE, it
is very important to explain either with a comment in the
Makefile, or at least in the commit
message, why the port does not build
when enabling. Otherwise, it is almost impossible to
either fix the problem, or test if it has been fixed when
committing an update at a later date.
6.5.2. make, gmake,
and imake
Several differing make
implementations exist. Ported software often requires a
particular implementation, like GNU
make, known in FreeBSD as
gmake.
If the port uses GNU make,
add gmake to
USES.
MAKE_CMD can be used to reference the
specific command configured by the USES
setting in the port's Makefile.
Only use MAKE_CMD within the
application Makefiles in
WRKSRC to call the
make implementation expected by the
ported software.
If the port is an X application that uses
imake to create
Makefiles from
Imakefiles, set USES=
imake.. See the USES=imake
section of Chapter 17, Using USES Macros for more details.
If the port's source Makefile has
something other than all as the
main build target, set ALL_TARGET
accordingly. The same goes for
install and
INSTALL_TARGET.
If the port uses the configure
script to generate Makefile from
Makefile.in, set
GNU_CONFIGURE=yes. To give
extra arguments to the configure script
(the default argument is --prefix=${PREFIX}
--infodir=${PREFIX}/${INFO_PATH}
--mandir=${MANPREFIX}/man
--build=${CONFIGURE_TARGET}), set those
extra arguments in CONFIGURE_ARGS. Extra
environment variables can be passed using
CONFIGURE_ENV.
Table 6.1. Variables for Ports That Use
configure
| Variable | Means |
|---|
GNU_CONFIGURE | The port uses configure
script to prepare build. |
HAS_CONFIGURE | Same as GNU_CONFIGURE,
except default configure target is not added to
CONFIGURE_ARGS. |
CONFIGURE_ARGS | Additional arguments passed to
configure script. |
CONFIGURE_ENV | Additional environment variables to be set
for configure script run. |
CONFIGURE_TARGET | Override default configure target. Default
value is
${MACHINE_ARCH}-portbld-freebsd${OSREL}. |
For ports that use CMake,
define USES= cmake.
Table 6.2. Variables for Ports That Use
cmake
| Variable | Means |
|---|
CMAKE_ARGS | Port specific CMake
flags to be passed to the cmake
binary. |
CMAKE_ON | For each entry in CMAKE_ON, an
enabled boolean value is added to
CMAKE_ARGS. See Example 6.3, “CMAKE_ON and
CMAKE_OFF”. |
CMAKE_OFF | For each entry in CMAKE_OFF, a
disabled boolean value is added to
CMAKE_ARGS. See Example 6.3, “CMAKE_ON and
CMAKE_OFF”. |
CMAKE_BUILD_TYPE | Type of build (CMake
predefined build profiles). Default is
Release, or
Debug if
WITH_DEBUG is set. |
CMAKE_SOURCE_PATH | Path to the source directory. Default is
${WRKSRC}. |
CONFIGURE_ENV | Additional environment variables to be set for
the cmake binary. |
Table 6.3. Variables the Users Can Define for
cmake Builds
| Variable | Means |
|---|
CMAKE_NOCOLOR | Disables color build output. Default not set,
unless BATCH or
PACKAGE_BUILDING are set. |
CMake supports these
build profiles: Debug,
Release,
RelWithDebInfo and
MinSizeRel. Debug and
Release profiles respect system
*FLAGS, RelWithDebInfo
and MinSizeRel will set
CFLAGS to -O2 -g and
-Os -DNDEBUG correspondingly. The
lower-cased value of CMAKE_BUILD_TYPE is
exported to PLIST_SUB and must be
used if the port installs
*.cmakeCMAKE_BUILD_TYPE in
CMakeLists.txt. To make a port for such
a project respect CFLAGS and
WITH_DEBUG, the
CMAKE_BUILD_TYPE definitions must be
removed from those files.
Most CMake-based projects
support an out-of-source method of building. The
out-of-source build for a port is the default setting.
An in-source build can be requested by using the
:insource suffix. With out-of-source
builds, CONFIGURE_WRKSRC,
BUILD_WRKSRC and
INSTALL_WRKSRC will be set to
${WRKDIR}/.build and this
directory will be used to keep all files generated during
configuration and build stages, leaving the source directory
intact.
Example 6.2. USES= cmake Example
This snippet demonstrates the use of
CMake for a port.
CMAKE_SOURCE_PATH is not usually
required, but can be set when the sources are not located
in the top directory, or if only a subset of the project
is intended to be built by the port.
USES= cmake
CMAKE_SOURCE_PATH= ${WRKSRC}/subprojectExample 6.3. CMAKE_ON and
CMAKE_OFF
When adding boolean values to
CMAKE_ARGS, it is easier to use the
CMAKE_ON and CMAKE_OFF
variables instead. This:
CMAKE_ON= VAR1 VAR2
CMAKE_OFF= VAR3
Is equivalent to:
CMAKE_ARGS= -DVAR1:BOOL=TRUE -DVAR2:BOOL=TRUE -DVAR3:BOOL=FALSE
If the port uses SCons,
define USES=scons.
To make third party SConstruct
respect everything that is passed to SCons in
the environment (that is, most importantly,
CC/CXX/CFLAGS/CXXFLAGS), patch
SConstruct so build
Environment is constructed like
this:
env = Environment(**ARGUMENTS)
It may be then modified with
env.Append and
env.Replace.
6.5.6. Building Rust Applications
with cargo
For ports that use Cargo,
define USES=cargo.
Table 6.4. Variables the Users Can Define for
cargo Builds
| Variable | Default | Description |
|---|
CARGO_CRATES | | List of crates the port depends on. Each entry
needs to have a format like
cratename-semver for example,
libc-0.2.40. Port maintainers can
generate this list from
Cargo.lock using
make cargo-crates. Manually
bumping crate versions is possible but be mindful of
transitive dependencies. |
CARGO_FEATURES | | List of application features to build (space
separated list). To deactivate all default
features add the special token
--no-default-features
to CARGO_FEATURES. Manually
passing it to CARGO_BUILD_ARGS,
CARGO_INSTALL_ARGS, and
CARGO_TEST_ARGS is not
needed. |
CARGO_CARGOTOML | ${WRKSRC}/Cargo.toml | The path to the Cargo.toml
to use. |
CARGO_CARGOLOCK | ${WRKSRC}/Cargo.lock | The path to the Cargo.lock
to use for make cargo-crates. It
is possible to specify more than one lock file when
necessary. |
CARGO_ENV | | A list of environment variables to pass to Cargo
similar to MAKE_ENV. |
RUSTFLAGS | | Flags to pass to the Rust compiler. |
CARGO_CONFIGURE | yes | Use the default
do-configure. |
CARGO_UPDATE_ARGS | | Extra arguments to pass to Cargo during the
configure phase. Valid arguments can be looked up
with cargo update --help. |
CARGO_BUILDDEP | yes | Add a build dependency on
lang/rust. |
CARGO_CARGO_BIN | ${LOCALBASE}/bin/cargo | Location of the cargo
binary. |
CARGO_BUILD | yes | Use the default
do-build. |
CARGO_BUILD_ARGS | | Extra arguments to pass to Cargo during the
build phase. Valid arguments can be looked up with
cargo build --help. |
CARGO_INSTALL | yes | Use the default
do-install. |
CARGO_INSTALL_ARGS | | Extra arguments to pass to Cargo during the
install phase. Valid arguments can be looked up with
cargo install --help. |
CARGO_INSTALL_PATH | . | Path to the crate to install. This is passed
to cargo install via its
--path argument. When multiple
paths are specified cargo install
is run multiple times. |
CARGO_TEST | yes | Use the default
do-test. |
CARGO_TEST_ARGS | | Extra arguments to pass to Cargo during the test
phase. Valid arguments can be looked up with
cargo test --help. |
CARGO_TARGET_DIR | ${WRKDIR}/target | Location of the cargo output directory. |
CARGO_DIST_SUBDIR | rust/crates | Directory relative to DISTDIR
where the crate distribution files will be
stored. |
CARGO_VENDOR_DIR | ${WRKSRC}/cargo-crates | Location of the vendor directory where
all crates will be extracted to. Try to keep this
under PATCH_WRKSRC, so that
patches can be applied easily. |
CARGO_USE_GITHUB | no | Enable fetching of crates locked to specific Git
commits on GitHub via GH_TUPLE.
This will try to patch all
Cargo.toml under
WRKDIR to point to the
offline sources instead of fetching them from a
Git repository during the build. |
CARGO_USE_GITLAB | no | Same as CARGO_USE_GITHUB
but for GitLab instances and
GL_TUPLE. |
Example 6.4. Creating a Port for a Simple Rust Application
Creating a Cargo based port is a three stage process.
First we need to provide a ports template that fetches the
application distribution file:
PORTNAME= tokei
DISTVERSIONPREFIX= v
DISTVERSION= 7.0.2
CATEGORIES= devel
MAINTAINER= tobik@FreeBSD.org
COMMENT= Display statistics about your code
USES= cargo
USE_GITHUB= yes
GH_ACCOUNT= Aaronepower
.include <bsd.port.mk>
Generate an initial
distinfo:
% make makesum
=> Aaronepower-tokei-v7.0.2_GH0.tar.gz doesn't seem to exist in /usr/ports/distfiles/.
=> Attempting to fetch https://codeload.github.com/Aaronepower/tokei/tar.gz/v7.0.2?dummy=/Aaronepower-tokei-v7.0.2_GH0.tar.gz
fetch: https://codeload.github.com/Aaronepower/tokei/tar.gz/v7.0.2?dummy=/Aaronepower-tokei-v7.0.2_GH0.tar.gz: size of remote file is not known
Aaronepower-tokei-v7.0.2_GH0.tar.gz 45 kB 239 kBps 00m00s
Now the distribution file is ready to use and we can go
ahead and extract crate dependencies from the bundled
Cargo.lock:
% make cargo-crates
CARGO_CRATES= aho-corasick-0.6.4 \
ansi_term-0.11.0 \
arrayvec-0.4.7 \
atty-0.2.9 \
bitflags-1.0.1 \
byteorder-1.2.2 \
[...]
The output of this command needs to be pasted directly
into the Makefile:
PORTNAME= tokei
DISTVERSIONPREFIX= v
DISTVERSION= 7.0.2
CATEGORIES= devel
MAINTAINER= tobik@FreeBSD.org
COMMENT= Display statistics about your code
USES= cargo
USE_GITHUB= yes
GH_ACCOUNT= Aaronepower
CARGO_CRATES= aho-corasick-0.6.4 \
ansi_term-0.11.0 \
arrayvec-0.4.7 \
atty-0.2.9 \
bitflags-1.0.1 \
byteorder-1.2.2 \
[...]
.include <bsd.port.mk>distinfo needs to be regenerated to
contain all the crate distribution files:
% make makesum
=> rust/crates/aho-corasick-0.6.4.tar.gz doesn't seem to exist in /usr/ports/distfiles/.
=> Attempting to fetch https://crates.io/api/v1/crates/aho-corasick/0.6.4/download?dummy=/rust/crates/aho-corasick-0.6.4.tar.gz
rust/crates/aho-corasick-0.6.4.tar.gz 100% of 24 kB 6139 kBps 00m00s
=> rust/crates/ansi_term-0.11.0.tar.gz doesn't seem to exist in /usr/ports/distfiles/.
=> Attempting to fetch https://crates.io/api/v1/crates/ansi_term/0.11.0/download?dummy=/rust/crates/ansi_term-0.11.0.tar.gz
rust/crates/ansi_term-0.11.0.tar.gz 100% of 16 kB 21 MBps 00m00s
=> rust/crates/arrayvec-0.4.7.tar.gz doesn't seem to exist in /usr/ports/distfiles/.
=> Attempting to fetch https://crates.io/api/v1/crates/arrayvec/0.4.7/download?dummy=/rust/crates/arrayvec-0.4.7.tar.gz
rust/crates/arrayvec-0.4.7.tar.gz 100% of 22 kB 3237 kBps 00m00s
=> rust/crates/atty-0.2.9.tar.gz doesn't seem to exist in /usr/ports/distfiles/.
=> Attempting to fetch https://crates.io/api/v1/crates/atty/0.2.9/download?dummy=/rust/crates/atty-0.2.9.tar.gz
rust/crates/atty-0.2.9.tar.gz 100% of 5898 B 81 MBps 00m00s
=> rust/crates/bitflags-1.0.1.tar.gz doesn't seem to exist in /usr/ports/distfiles/.
[...]
The port is now ready for a test build and further
adjustments like creating a plist, writing a description,
adding license information, options, etc. as normal.
If you are not testing your port in a clean environment
like with Poudriere, remember to
run make clean before any testing.
Example 6.5. Enabling Additional Application Features
Some applications define additional features in their
Cargo.toml. They can be compiled in
by setting CARGO_FEATURES in the
port.
Here we enable Tokei's json and
yaml features:
CARGO_FEATURES= json yaml
Example 6.6. Encoding Application Features As Port Options
An example [features] section
in Cargo.toml could look like
this:
[features]
pulseaudio_backend = ["librespot-playback/pulseaudio-backend"]
portaudio_backend = ["librespot-playback/portaudio-backend"]
default = ["pulseaudio_backend"]
pulseaudio_backend is a default
feature. It is always enabled unless we explicitly turn
off default features by adding
--no-default-features to
CARGO_FEATURES. Here we turn the
portaudio_backend
and pulseaudio_backend features into
port options:
CARGO_FEATURES= --no-default-features
OPTIONS_DEFINE= PORTAUDIO PULSEAUDIO
PORTAUDIO_VARS= CARGO_FEATURES+=portaudio_backend
PULSEAUDIO_VARS= CARGO_FEATURES+=pulseaudio_backend
Example 6.7. Listing Crate Licenses
Crates have their own licenses. It is important to
know what they are when adding a LICENSE
block to the port (see Section 5.7, “Licenses”). The
helper target
cargo-crates-licenses will try
to list all the licenses of all crates defined in
CARGO_CRATES.
% make cargo-crates-licenses
aho-corasick-0.6.4 Unlicense/MIT
ansi_term-0.11.0 MIT
arrayvec-0.4.7 MIT/Apache-2.0
atty-0.2.9 MIT
bitflags-1.0.1 MIT/Apache-2.0
byteorder-1.2.2 Unlicense/MIT
[...]
Note:
The license names
make cargo-crates-licenses outputs are
SPDX 2.1 licenses expression which do not match the
license names defined in the ports framework. They need
to be translated to the names from
Table 5.7, “Predefined License List”.
For ports that use Meson,
define USES=meson.
Table 6.5. Variables for Ports That Use
meson
| Variable | Description |
|---|
MESON_ARGS | Port specific Meson
flags to be passed to the meson
binary. |
MESON_BUILD_DIR | Path to the build directory relative to
WRKSRC. Default is
_build. |
Example 6.8. USES=meson Example
This snippet demonstrates the use of
Meson for a port.
USES= meson
MESON_ARGS= -Dfoo=enabled
6.5.8. Building Go
Applications
For ports that use Go,
define USES=go. Refer to Section 17.35, “go” for a list of variables that can be
set to control the build process.
Example 6.9. Creating a Port for a Go Modules Based
Application
Creating a Go based port is a five stage process.
First we need to provide a ports template that fetches the
application distribution file:
PORTNAME= ghq
DISTVERSIONPREFIX= v
DISTVERSION= 0.12.5
CATEGORIES= devel
MAINTAINER= tobik@FreeBSD.org
COMMENT= Remote repository management made easy
USES= go:modules
USE_GITHUB= yes
GH_ACCOUNT= motemen
.include <bsd.port.mk>
Generate an initial
distinfo:
% make makesum
===> License MIT accepted by the user
=> motemen-ghq-v0.12.5_GH0.tar.gz doesn't seem to exist in /usr/ports/distfiles/.
=> Attempting to fetch https://codeload.github.com/motemen/ghq/tar.gz/v0.12.5?dummy=/motemen-ghq-v0.12.5_GH0.tar.gz
fetch: https://codeload.github.com/motemen/ghq/tar.gz/v0.12.5?dummy=/motemen-ghq-v0.12.5_GH0.tar.gz: size of remote file is not known
motemen-ghq-v0.12.5_GH0.tar.gz 32 kB 177 kBps 00s
Now the distribution file is ready to use and we can
extract the required Go module dependencies. This step
requires having
ports-mgmt/modules2tuple
installed:
% make gomod-vendor
[...]
GH_TUPLE= \
Songmu:gitconfig:v0.0.2:songmu_gitconfig/vendor/github.com/Songmu/gitconfig \
daviddengcn:go-colortext:186a3d44e920:daviddengcn_go_colortext/vendor/github.com/daviddengcn/go-colortext \
go-yaml:yaml:v2.2.2:go_yaml_yaml/vendor/gopkg.in/yaml.v2 \
golang:net:3ec191127204:golang_net/vendor/golang.org/x/net \
golang:sync:112230192c58:golang_sync/vendor/golang.org/x/sync \
golang:xerrors:3ee3066db522:golang_xerrors/vendor/golang.org/x/xerrors \
motemen:go-colorine:45d19169413a:motemen_go_colorine/vendor/github.com/motemen/go-colorine \
urfave:cli:v1.20.0:urfave_cli/vendor/github.com/urfave/cli
The output of this command needs to be pasted directly
into the Makefile:
PORTNAME= ghq
DISTVERSIONPREFIX= v
DISTVERSION= 0.12.5
CATEGORIES= devel
MAINTAINER= tobik@FreeBSD.org
COMMENT= Remote repository management made easy
USES= go:modules
USE_GITHUB= yes
GH_ACCOUNT= motemen
GH_TUPLE= Songmu:gitconfig:v0.0.2:songmu_gitconfig/vendor/github.com/Songmu/gitconfig \
daviddengcn:go-colortext:186a3d44e920:daviddengcn_go_colortext/vendor/github.com/daviddengcn/go-colortext \
go-yaml:yaml:v2.2.2:go_yaml_yaml/vendor/gopkg.in/yaml.v2 \
golang:net:3ec191127204:golang_net/vendor/golang.org/x/net \
golang:sync:112230192c58:golang_sync/vendor/golang.org/x/sync \
golang:xerrors:3ee3066db522:golang_xerrors/vendor/golang.org/x/xerrors \
motemen:go-colorine:45d19169413a:motemen_go_colorine/vendor/github.com/motemen/go-colorine \
urfave:cli:v1.20.0:urfave_cli/vendor/github.com/urfave/cli
.include <bsd.port.mk>
distinfo needs to be regenerated to
contain all the distribution files:
% make makesum
=> Songmu-gitconfig-v0.0.2_GH0.tar.gz doesn't seem to exist in /usr/ports/distfiles/.
=> Attempting to fetch https://codeload.github.com/Songmu/gitconfig/tar.gz/v0.0.2?dummy=/Songmu-gitconfig-v0.0.2_GH0.tar.gz
fetch: https://codeload.github.com/Songmu/gitconfig/tar.gz/v0.0.2?dummy=/Songmu-gitconfig-v0.0.2_GH0.tar.gz: size of remote file is not known
Songmu-gitconfig-v0.0.2_GH0.tar.gz 5662 B 936 kBps 00s
=> daviddengcn-go-colortext-186a3d44e920_GH0.tar.gz doesn't seem to exist in /usr/ports/distfiles/.
=> Attempting to fetch https://codeload.github.com/daviddengcn/go-colortext/tar.gz/186a3d44e920?dummy=/daviddengcn-go-colortext-186a3d44e920_GH0.tar.gz
fetch: https://codeload.github.com/daviddengcn/go-colortext/tar.gz/186a3d44e920?dummy=/daviddengcn-go-colortext-186a3d44e920_GH0.tar.gz: size of remote file is not known
daviddengcn-go-colortext-186a3d44e920_GH0.tar. 4534 B 1098 kBps 00s
[...]
The port is now ready for a test build and further
adjustments like creating a plist, writing a description,
adding license information, options, etc. as normal.
If you are not testing your port in a clean environment
like with Poudriere, remember to
run make clean before any testing.
Example 6.10. Setting Output Binary Name or Installation Path
Some ports need to install the resulting binary under a
different name or to a path other than
the default ${PREFIX}/bin. This can be
done by using GO_TARGET tuple syntax,
for example:
GO_TARGET= ./cmd/ipfs:ipfs-go
will install ipfs binary as
${PREFIX}/bin/ipfs-go and
GO_TARGET= ./dnscrypt-proxy:${PREFIX}/sbin/dnscrypt-proxywill install dnscrypt-proxy to
${PREFIX}/sbin.
6.5.9. Building Haskell
Applications with cabal
For ports that use Cabal,
build system defines USES=cabal. Refer to Section 17.8, “cabal” for a list of variables that can be
set to control the build process.
Example 6.11. Creating a Port for a Hackage-hosted Haskell
Application
When preparing a Haskell Cabal port, the
devel/hs-cabal-install program is
required, so make sure it is installed beforehand. First we need
to define common ports variables that allows
cabal-install to fetch the package distribution file:
PORTNAME= ShellCheck
DISTVERSION= 0.6.0
CATEGORIES= devel
MAINTAINER= haskell@FreeBSD.org
COMMENT= Shell script analysis tool
USES= cabal
.include <bsd.port.mk>
This minimal Makefile allows us to fetch the distribution file:
% make cabal-extract
[...]
Downloading the latest package list from hackage.haskell.org
cabal get ShellCheck-0.6.0
Downloading ShellCheck-0.6.0
Downloaded ShellCheck-0.6.0
Unpacking to ShellCheck-0.6.0/
Now we have ShellCheck.cabal package description file,
which allows us to fetch all package's dependencies,
including transitive ones:
% make cabal-extract-deps
[...]
Resolving dependencies...
Downloading base-orphans-0.8.2
Downloaded base-orphans-0.8.2
Downloading primitive-0.7.0.0
Starting base-orphans-0.8.2 (lib)
Building base-orphans-0.8.2 (lib)
Downloaded primitive-0.7.0.0
Downloading dlist-0.8.0.7
[...]
As a side effect, the package's dependencies are
also compiled, so the command may take some time.
Once done, a list of required dependencies can generated:
% make make-use-cabal
USE_CABAL=QuickCheck-2.12.6.1 \
hashable-1.3.0.0 \
integer-logarithms-1.0.3 \
[...]
Haskell packages may contain revisions, just like
FreeBSD ports. Revisions can affect only .cabal
files, but it is still important to pull them in.
To check USE_CABAL items for available
revision updates, run following command:
% make make-use-cabal-revs
USE_CABAL=QuickCheck-2.12.6.1_1 \
hashable-1.3.0.0 \
integer-logarithms-1.0.3_2 \
[...]
Note additional version numbers after _
symbol. Put newly generated USE_CABAL list
instead of an old one.
Finally, distinfo needs to be regenerated to
contain all the distribution files:
% make makesum
=> ShellCheck-0.6.0.tar.gz doesn't seem to exist in /usr/local/poudriere/ports/git/distfiles/cabal.
=> Attempting to fetch https://hackage.haskell.org/package/ShellCheck-0.6.0/ShellCheck-0.6.0.tar.gz
ShellCheck-0.6.0.tar.gz 136 kB 642 kBps 00s
=> QuickCheck-2.12.6.1/QuickCheck-2.12.6.1.tar.gz doesn't seem to exist in /usr/local/poudriere/ports/git/distfiles/cabal.
=> Attempting to fetch https://hackage.haskell.org/package/QuickCheck-2.12.6.1/QuickCheck-2.12.6.1.tar.gz
QuickCheck-2.12.6.1/QuickCheck-2.12.6.1.tar.gz 65 kB 361 kBps 00s
[...]
The port is now ready for a test build and further
adjustments like creating a plist, writing a description,
adding license information, options, etc. as normal.
If you are not testing your port in a clean environment
like with Poudriere, remember to
run make clean before any testing.
If the port requires gettext, set
USES= gettext, and the port will inherit
a dependency on libintl.so from
devel/gettext. Other
values for gettext usage are listed in
USES=gettext.
A rather common case is a port using
gettext and configure.
Generally, GNU configure should be able
to locate gettext automatically.
USES= gettext
GNU_CONFIGURE= yes
If it ever fails to, hints at the location of
gettext can be passed in
CPPFLAGS and LDFLAGS using
localbase as follows:
USES= gettext localbase:ldflags
GNU_CONFIGURE= yes
Some software products allow for disabling
NLS. For example, through passing
--disable-nls to
configure. In that case, the port must use
gettext conditionally, depending on the
status of the NLS option. For ports of low
to medium complexity, use this idiom:
GNU_CONFIGURE= yes
OPTIONS_DEFINE= NLS
OPTIONS_SUB= yes
NLS_USES= gettext
NLS_CONFIGURE_ENABLE= nls
.include <bsd.port.mk>
Or using the older way of using options:
GNU_CONFIGURE= yes
OPTIONS_DEFINE= NLS
.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>The next item on the to-do list is to arrange so that
the message catalog files are included in the packing list
conditionally. The Makefile part of
this task is already provided by the idiom. It is explained
in the section on advanced
pkg-plist practices. In a
nutshell, each occurrence of %%NLS%% in
pkg-plist will be replaced by
“@comment ” if NLS is
disabled, or by a null string if NLS is enabled.
Consequently, the lines prefixed by
%%NLS%% will become mere comments in the
final packing list if NLS is off; otherwise the prefix will
be just left out. Then insert
%%NLS%% before each path to a message
catalog file in pkg-plist. For
example:
%%NLS%%share/locale/fr/LC_MESSAGES/foobar.mo
%%NLS%%share/locale/no/LC_MESSAGES/foobar.mo
In high complexity cases, more advanced techniques
may be needed, such as
dynamic packing list
generation.
6.7.3. Handling Message Catalog Directories
There is a point to note about installing message
catalog files. The target directories for them, which
reside under
LOCALBASE/share/locale,
must not be created and removed by a port. The most
popular languages have their respective directories listed
in
PORTSDIR/Templates/BSD.local.dist.
The directories for many other languages are governed by the
devel/gettext port.
Consult its pkg-plist and see whether
the port is going to install a message catalog file for a
unique language.
If MASTER_SITES is set to
CPAN, the correct subdirectory is usually
selected automatically. If the default subdirectory is wrong,
CPAN/Module can be used to change it.
MASTER_SITES can also be set to the old
MASTER_SITE_PERL_CPAN, then the preferred
value of MASTER_SITE_SUBDIR is the
top-level hierarchy name. For example, the recommended value
for p5-Module-Name is
Module. The top-level hierarchy can be
examined at cpan.org.
This keeps the port working when the author of the module
changes.
The exception to this rule is when the relevant directory
does not exist or the distfile does not exist in that
directory. In such case, using author's id as
MASTER_SITE_SUBDIR is allowed.
The CPAN:AUTHOR macro can be used, which will
be translated to the hashed author directory. For example,
CPAN:AUTHOR will be converted to
authors/id/A/AU/AUTHOR.
When a port needs Perl support,
it must set USES=perl5 with the optional
USE_PERL5 described in the perl5 USES description.
Table 6.6. Read-Only Variables for Ports That Use
Perl
| Read only variables | Means |
|---|
PERL | The full path of the Perl 5 interpreter,
either in the system or installed from a port, but
without the version number. Use this when the software
needs the path to the Perl
interpreter. To replace
“#!”lines in scripts,
use USES=shebangfix. |
PERL_VERSION | The full version of Perl installed (for example,
5.8.9). |
PERL_LEVEL | The installed Perl version as
an integer of the form MNNNPP
(for example, 500809). |
PERL_ARCH | Where Perl stores architecture
dependent libraries. Defaults to
${ARCH}-freebsd. |
PERL_PORT | Name of the Perl port that is installed (for
example, perl5). |
SITE_PERL | Directory name where site specific
Perl packages go. This value is
added to PLIST_SUB. |
Note:
Ports of Perl modules which do not have an official
website must link to cpan.org in
the WWW line of pkg-descr. The
preferred URL form is
http://search.cpan.org/dist/Module-Name/
(including the trailing slash).
Note:
Do not use ${SITE_PERL} in dependency
declarations. Doing so assumes that
perl5.mk has been included, which is
not always true. Ports depending on this port will have
incorrect dependencies if this port's files move later in an
upgrade. The right way to declare Perl module dependencies
is shown in the example below.
Example 6.12. Perl Dependency Example
p5-IO-Tee>=0.64:devel/p5-IO-Tee
For Perl ports that install manual pages, the macro
PERL5_MAN3 and PERL5_MAN1
can be used
inside pkg-plist. For example,
lib/perl5/5.14/man/man1/event.1.gz
lib/perl5/5.14/man/man3/AnyEvent::I3.3.gz
can be replaced with
%%PERL5_MAN1%%/event.1.gz
%%PERL5_MAN3%%/AnyEvent::I3.3.gz
Note:
There are no
PERL5_MANx
macros for the
other sections (x in
2 and
4 to 9) because those
get installed in the regular directories.
Example 6.13. A Port Which Only Requires Perl to Build
As the default USE_PERL5 value is build and run, set it
to:
USES= perl5
USE_PERL5= build
Example 6.14. A Port Which Also Requires Perl to Patch
From time to time, using sed(1) for patching is not
enough. When using perl(1) is easier, use:
USES= perl5
USE_PERL5= patch build run
Example 6.15. A Perl Module Which Needs
ExtUtils::MakeMaker to Build
Most Perl modules come with a
Makefile.PL configure script. In this
case, set:
USES= perl5
USE_PERL5= configure
Example 6.16. A Perl Module Which Needs
Module::Build to Build
When a Perl module comes with a
Build.PL configure script, it can require
Module::Build, in which case,
set
USES= perl5
USE_PERL5= modbuild
If it instead requires
Module::Build::Tiny, set
USES= perl5
USE_PERL5= modbuildtiny
The X11 implementation available in The Ports Collection
is X.Org. If the application depends on X components, add
USES= xorg and set
USE_XORG to the list of required
components. A full list can be found in Section 17.94, “xorg”.
The Mesa Project is an effort to provide free OpenGL
implementation. To specify a dependency on various
components of this project, use USES= gl
and USE_GL. See
Section 17.32, “gl” for a full list of available
components. For backwards compatibility, the value of
yes maps to glu.
Example 6.17. USE_XORG Example
USES= gl xorg
USE_GL= glu
USE_XORG= xrender xft xkbfile xt xaw
Table 6.7. Variables for Ports That Use X
USES= imake | The port uses imake. |
XMKMF | Set to the path of xmkmf if
not in the PATH. Defaults to
xmkmf -a. |
Example 6.18. Using X11-Related Variables
# Use some X11 libraries
USES= xorg
USE_XORG= x11 xpm
6.9.2. Ports That Require Motif
If the port requires a Motif library, define
USES= motif in the
Makefile. Default Motif implementation
is
x11-toolkits/open-motif.
Users can choose
x11-toolkits/lesstif
instead by setting WANT_LESSTIF
in their make.conf.
MOTIFLIB will be set by
motif.mk to reference the
appropriate Motif library. Please patch the source of the
port to use ${MOTIFLIB} wherever
the Motif library is referenced in the original
Makefile or
Imakefile.
There are two common cases:
If the port refers to the Motif library as
-lXm in its
Makefile or
Imakefile, substitute
${MOTIFLIB} for it.
If the port uses XmClientLibs in
its Imakefile, change it to
${MOTIFLIB} ${XTOOLLIB}
${XLIB}.
Note that MOTIFLIB (usually) expands
to -L/usr/local/lib -lXm -lXp or
/usr/local/lib/libXm.a, so there is no
need to add -L or -l
in front.
If the port installs fonts for the X Window System, put
them in
LOCALBASE/lib/X11/fonts/local.
6.9.4. Getting a Fake DISPLAY with Xvfb
Some applications require a working X11 display for
compilation to succeed. This poses a problem for machines
that operate headless. When this variable is used,
the build infrastructure will start the virtual framebuffer
X server. The working DISPLAY is then passed
to the build. See USES=display
for the possible arguments.
USES= display
Desktop entries (a
Freedesktop standard) provide a way to
automatically adjust desktop features when a new program is
installed, without requiring user intervention. For
example, newly-installed programs automatically appear in
the application menus of compatible desktop environments.
Desktop entries originated in the
GNOME desktop environment, but
are now a standard and also work with
KDE and
Xfce. This bit of automation
provides a real benefit to the user, and desktop entries are
encouraged for applications which can be used in a desktop
environment.
6.9.5.1. Using Predefined .desktop
Files
Ports that include predefined
*.desktoppkg-plist
and install them in the
$LOCALBASE/share/applications
directory. The INSTALL_DATA
macro is useful for installing these
files.
6.9.5.2. Updating Desktop Database
If a port has a MimeType entry in its
portname.desktopUSES=
desktop-file-utils.
6.9.5.3. Creating Desktop Entries with
DESKTOP_ENTRIES
Desktop entries can be easily created for applications
by using DESKTOP_ENTRIES. A
file named
name.desktoppkg-plist automatically. Syntax
is:
DESKTOP_ENTRIES= "NAME" "COMMENT" "ICON" "COMMAND" "CATEGORY" StartupNotify
The list of possible categories is available on the
Freedesktop
website. StartupNotify
indicates whether the application is compatible with
startup notifications. These are
typically a graphic indicator like a clock that appear at
the mouse pointer, menu, or panel to give the user an
indication when a program is starting. A program that is
compatible with startup notifications clears the indicator
after it has started. Programs that are not compatible
with startup notifications would never clear the indicator
(potentially confusing and infuriating the user), and
must have StartupNotify set to
false so the indicator is not shown at
all.
Example:
DESKTOP_ENTRIES= "ToME" "Roguelike game based on JRR Tolkien's work" \
"${DATADIR}/xtra/graf/tome-128.png" \
"tome -v -g" "Application;Game;RolePlaying;" \
falseThis chapter explains the GNOME
framework as used by ports. The framework can be loosely
divided into the base components, GNOME
desktop components, and a few special macros that simplify the
work of port maintainers.
Adding this variable to the port allows the use of
the macros and components defined in
bsd.gnome.mk. The code in
bsd.gnome.mk adds the needed
build-time, run-time or library dependencies
or the handling of special files.
GNOME applications under FreeBSD use the
USE_GNOME infrastructure. Include all the
needed components as a space-separated list. The
USE_GNOME components are divided into
these virtual lists: basic components, GNOME 3 components
and legacy components. If the port needs only GTK3 libraries,
this is the shortest way to define it:
USE_GNOME= gtk30
USE_GNOME components automatically
add the dependencies they need. Please see
Section 6.11, “GNOME Components” for an exhaustive
list of all USE_GNOME components and which
other components they imply and their dependencies.
Here is an example Makefile for a
GNOME port that uses many of the techniques outlined in this
document. Please use it as a guide for creating new
ports.
# $FreeBSD$
PORTNAME= regexxer
DISTVERSION= 0.10
CATEGORIES= devel textproc gnome
MASTER_SITES= GNOME
MAINTAINER= kwm@FreeBSD.org
COMMENT= Interactive tool for performing search and replace operations
USES= gettext gmake localbase:ldflags pathfix pkgconfig tar:xz
GNU_CONFIGURE= yes
USE_GNOME= gnomeprefix intlhack gtksourceviewmm3
INSTALLS_ICONS= yes
GLIB_SCHEMAS= org.regexxer.gschema.xml
.include <bsd.port.mk>
Note:
The USE_GNOME macro without any
arguments does not add any dependencies to the port.
USE_GNOME cannot be set after
bsd.port.pre.mk.
This section explains which macros are available and how
they are used. Like they are used in the above example. The
Section 6.11, “GNOME Components” has a more in-depth
explanation. USE_GNOME has to be set for
these macros to be of use.
INSTALLS_ICONSGTK+ ports which install
Freedesktop-style icons to
${LOCALBASE}/share/icons should use
this macro to ensure that the icons are cached and will
display correctly. The cache file is named
icon-theme.cache. Do not include
that file in pkg-plist. This macro
handles that automatically. This macro is not needed
for Qt, which uses an
internal method.
GLIB_SCHEMASList of all the glib schema files the port installs.
The macro will add the files to the port plist and
handle the registration of these files on install and
deinstall.
The glib schema files are written in
XML and end with the
gschema.xml extension. They are
installed in the
share/glib-2.0/schemas/ directory.
These schema files contain all application config values
with their default settings. The actual database used
by the applications is built by
glib-compile-schema, which is
run by the GLIB_SCHEMAS macro.
GLIB_SCHEMAS=foo.gschema.xml
Note:
Do not add glib schemas to the
pkg-plist. If they are listed in
pkg-plist, they will not be
registered and the applications might not work
properly.
GCONF_SCHEMASList all the gconf schema files. The macro will add
the schema files to the port plist and will handle their
registration on install and deinstall.
GConf is the XML-based database
that virtually all GNOME applications use for storing
their settings. These files are installed into the
etc/gconf/schemas directory. This
database is defined by installed schema files that are
used to generate %gconf.xml key
files. For each schema file installed by the port,
there must be an entry in the
Makefile:
GCONF_SCHEMAS=my_app.schemas my_app2.schemas my_app3.schemas
Note:
Gconf schemas are listed in the
GCONF_SCHEMAS macro rather than
pkg-plist. If they are listed in
pkg-plist, they will not be
registered and the applications might not work
properly.
INSTALLS_OMFOpen Source Metadata Framework
(OMF) files are commonly used by
GNOME 2 applications. These files contain the
application help file information, and require special
processing by ScrollKeeper/rarian. To properly register
OMF files when installing GNOME
applications from packages, make sure that
omf files are listed in
pkg-plist and that the port
Makefile has
INSTALLS_OMF defined:
INSTALLS_OMF=yes
When set, bsd.gnome.mk
automatically scans pkg-plist and
adds appropriate @exec and
@unexec directives for each
.omf to track in the
OMF registration database.
For further help with a GNOME port, look at some of the
existing
ports for examples. The
FreeBSD GNOME
page has contact information if more help is
needed. The components are divided into GNOME components
that are currently in use and legacy components. If the
component supports argument, they are listed between
parenthesis in the description. The first is the default.
"Both" is shown if the component defaults to adding to both
build and run dependencies.
Table 6.8. GNOME Components
| Component | Associated program | Description |
|---|
atk | accessibility/atk | Accessibility toolkit (ATK) |
atkmm | accessibility/atkmm | c++ bindings for atk |
cairo | graphics/cairo | Vector graphics library with cross-device output
support |
cairomm | graphics/cairomm | c++ bindings for cairo |
dconf | devel/dconf | Configuration database system
(both, build, run) |
evolutiondataserver3 | databases/evolution-data-server | Data backends for the Evolution integrated
mail/PIM suite |
gdkpixbuf2 | graphics/gdk-pixbuf2 | Graphics library for GTK+ |
glib20 | devel/glib20 | GNOME core library
glib20 |
glibmm | devel/glibmm | c++ bindings for glib20 |
gnomecontrolcenter3 | sysutils/gnome-control-center | GNOME 3 Control Center |
gnomedesktop3 | x11/gnome-desktop | GNOME 3 desktop UI library |
gsound | audio/gsound | GObject library for playing system sounds
(both, build, run) |
gtk-update-icon-cache | graphics/gtk-update-icon-cache | Gtk-update-icon-cache utility from the Gtk+
toolkit |
gtk20 | x11-toolkits/gtk20 | Gtk+ 2 toolkit |
gtk30 | x11-toolkits/gtk30 | Gtk+ 3 toolkit |
gtkmm20 | x11-toolkits/gtkmm20 | c++ bindings 2.0 for the gtk20 toolkit |
gtkmm24 | x11-toolkits/gtkmm24 | c++ bindings 2.4 for the gtk20 toolkit |
gtkmm30 | x11-toolkits/gtkmm30 | c++ bindings 3.0 for the gtk30 toolkit |
gtksourceview2 | x11-toolkits/gtksourceview2 | Widget that adds syntax highlighting to
GtkTextView |
gtksourceview3 | x11-toolkits/gtksourceview3 | Text widget that adds syntax highlighting to
the GtkTextView widget |
gtksourceviewmm3 | x11-toolkits/gtksourceviewmm3 | c++ bindings for the gtksourceview3 library |
gvfs | devel/gvfs | GNOME virtual file system |
intltool | textproc/intltool | Tool for internationalization (also see
intlhack) |
introspection | devel/gobject-introspection | Basic introspection bindings and tools to
generate introspection bindings. Most of the time
:build is enough, :both/:run is only need for
applications that use introspection bindings.
(both, build, run) |
libgda5 | databases/libgda5 | Provides uniform access to different kinds of
data sources |
libgda5-ui | databases/libgda5-ui | UI library from the libgda5 library |
libgdamm5 | databases/libgdamm5 | c++ bindings for the libgda5 library |
libgsf | devel/libgsf | Extensible I/O abstraction for dealing with
structured file formats |
librsvg2 | graphics/librsvg2 | Library for parsing and rendering SVG
vector-graphic files |
libsigc++20 | devel/libsigc++20 | Callback Framework for C++ |
libxml++26 | textproc/libxml++26 | c++ bindings for the libxml2 library |
libxml2 | textproc/libxml2 | XML parser library (both, build, run) |
libxslt | textproc/libxslt | XSLT C library (both, build, run) |
metacity | x11-wm/metacity | Window manager from GNOME |
nautilus3 | x11-fm/nautilus | GNOME file manager |
pango | x11-toolkits/pango | Open-source framework for the layout and
rendering of i18n text |
pangomm | x11-toolkits/pangomm | c++ bindings for the pango library |
py3gobject3 | devel/py3-gobject3 | Python 3, GObject 3.0 bindings |
pygobject3 | devel/py-gobject3 | Python 2, GObject 3.0 bindings |
vte3 | x11-toolkits/vte3 | Terminal widget with improved accessibility and
I18N support |
Table 6.9. GNOME Macro Components
| Component | Description |
|---|
gnomeprefix | Supply configure with
some default locations. |
intlhack | Same as intltool, but patches to make sure
share/locale/ is used. Please
only use when intltool alone is
not enough. |
referencehack | This macro is there to help splitting of the API or
reference documentation into its own port. |
Table 6.10. GNOME Legacy Components
| Component | Associated program | Description |
|---|
atspi | accessibility/at-spi | Assistive Technology Service Provider
Interface |
esound | audio/esound | Enlightenment sound package |
gal2 | x11-toolkits/gal2 | Collection of widgets taken from GNOME 2
gnumeric |
gconf2 | devel/gconf2 | Configuration database system for GNOME 2 |
gconfmm26 | devel/gconfmm26 | c++ bindings for gconf2 |
gdkpixbuf | graphics/gdk-pixbuf | Graphics library for GTK+ |
glib12 | devel/glib12 | glib 1.2 core library |
gnomedocutils | textproc/gnome-doc-utils | GNOME doc utils |
gnomemimedata | misc/gnome-mime-data | MIME and Application database for GNOME 2 |
gnomesharp20 | x11-toolkits/gnome-sharp20 | GNOME 2 interfaces for the .NET runtime |
gnomespeech | accessibility/gnome-speech | GNOME 2 text-to-speech API |
gnomevfs2 | devel/gnome-vfs | GNOME 2 Virtual File System |
gtk12 | x11-toolkits/gtk12 | Gtk+ 1.2 toolkit |
gtkhtml3 | www/gtkhtml3 | Lightweight HTML rendering/printing/editing
engine |
gtkhtml4 | www/gtkhtml4 | Lightweight HTML rendering/printing/editing
engine |
gtksharp20 | x11-toolkits/gtk-sharp20 | GTK+ and GNOME 2 interfaces for the .NET
runtime |
gtksourceview | x11-toolkits/gtksourceview | Widget that adds syntax highlighting to
GtkTextView |
libartgpl2 | graphics/libart_lgpl | Library for high-performance 2D graphics |
libbonobo | devel/libbonobo | Component and compound document system for
GNOME 2 |
libbonoboui | x11-toolkits/libbonoboui | GUI frontend to the libbonobo component of
GNOME 2 |
libgda4 | databases/libgda4 | Provides uniform access to different kinds of
data sources |
libglade2 | devel/libglade2 | GNOME 2 glade library |
libgnome | x11/libgnome | Libraries for GNOME 2, a GNU desktop
environment |
libgnomecanvas | graphics/libgnomecanvas | Graphics library for GNOME 2 |
libgnomekbd | x11/libgnomekbd | GNOME 2 keyboard shared library |
libgnomeprint | print/libgnomeprint | Gnome 2 print support library |
libgnomeprintui | x11-toolkits/libgnomeprintui | Gnome 2 print support library |
libgnomeui | x11-toolkits/libgnomeui | Libraries for the GNOME 2 GUI, a GNU desktop
environment |
libgtkhtml | www/libgtkhtml | Lightweight HTML rendering/printing/editing
engine |
libgtksourceviewmm | x11-toolkits/libgtksourceviewmm | c++ binding of GtkSourceView |
libidl | devel/libIDL | Library for creating trees of CORBA IDL
file |
libsigc++12 | devel/libsigc++12 | Callback Framework for C++ |
libwnck | x11-toolkits/libwnck | Library used for writing pagers and
taskslists |
libwnck3 | x11-toolkits/libwnck3 | Library used for writing pagers and
taskslists |
orbit2 | devel/ORBit2 | High-performance CORBA ORB with support for the
C language |
pygnome2 | x11-toolkits/py-gnome2 | Python bindings for GNOME 2 |
pygobject | devel/py-gobject | Python 2, GObject 2.0 bindings |
pygtk2 | x11-toolkits/py-gtk2 | Set of Python bindings for GTK+ |
pygtksourceview | x11-toolkits/py-gtksourceview | Python bindings for GtkSourceView 2 |
vte | x11-toolkits/vte | Terminal widget with improved accessibility and
I18N support |
Table 6.11. Deprecated Components: Do Not Use
| Component | Description |
|---|
pangox-compat | pangox-compat has been
deprecated and split off from the
pango package. |
6.12.1. Ports That Require Qt
The Ports Collection provides support for Qt 5 with
USES+=qt:5. Set USE_QT
to the list of required Qt components (libraries, tools,
plugins).
The Qt framework exports a number of variables which can
be used by ports, some of them listed below:
Table 6.12. Variables Provided to Ports That Use Qt
QMAKE | Full path to qmake
binary. |
LRELEASE | Full path to lrelease
utility. |
MOC | Full path to moc. |
RCC | Full path to rcc. |
UIC | Full path to uic. |
QT_INCDIR | Qt include directory. |
QT_LIBDIR | Qt libraries path. |
QT_PLUGINDIR | Qt plugins path. |
6.12.2. Component Selection
Individual Qt tool and library dependencies must be
specified in USE_QT.
Every component can be suffixed with
_build or _run, the
suffix indicating whether the dependency on the component is
at buildtime or runtime. If unsuffixed, the component will be
depended on at both build- and runtime. Usually, library
components are specified unsuffixed, tool components
are mostly specified with the _build suffix
and plugin components are specified with the
_run suffix. The most commonly used
components are listed below (all available components are
listed in _USE_QT_ALL, and
_USE_QT5_ONLY in
/usr/ports/Mk/Uses/qt.mk):
Table 6.13. Available Qt Library Components
| Name | Description |
|---|
3d | Qt3D module |
assistant | Qt 5 documentation browser |
canvas3d | Qt canvas3d module |
charts | Qt 5 charts module |
concurrent | Qt multi-threading module |
connectivity | Qt connectivity (Bluetooth/NFC) module |
core | Qt core non-graphical module |
datavis3d | Qt 5 3D data visualization module |
dbus | Qt D-Bus inter-process communication
module |
declarative | Qt declarative framework for dynamic user
interfaces |
designer | Qt 5 graphical user interface designer |
diag | Tool for reporting diagnostic information about
Qt and its environment |
doc | Qt 5 documentation |
examples | Qt 5 examples sourcecode |
gamepad | Qt 5 Gamepad Module |
graphicaleffects | Qt Quick graphical effects |
gui | Qt graphical user interface module |
help | Qt online help integration module |
l10n | Qt localized messages |
linguist | Qt 5 translation tool |
location | Qt location module |
multimedia | Qt audio, video, radio and camera support
module |
network | Qt network module |
networkauth | Qt network auth module |
opengl | Qt 5-compatible OpenGL support module |
paths | Command line client to QStandardPaths |
phonon4 | KDE multimedia framework |
pixeltool | Qt 5 screen magnifier |
plugininfo | Qt5 plugin metadata dumper |
printsupport | Qt print support module |
qdbus | Qt command-line interface to D-Bus |
qdbusviewer | Qt 5 graphical interface to D-Bus |
qdoc | Qt documentation generator |
qdoc-data | QDoc configuration files |
qev | Qt QWidget events introspection tool |
qmake | Qt Makefile generator |
quickcontrols | Set of controls for building complete interfaces
in Qt Quick |
quickcontrols2 | Set of controls for building complete interfaces
in Qt Quick |
remoteobjects | Qt5 SXCML module |
script | Qt 4-compatible scripting module |
scripttools | Qt Script additional components |
scxml | Qt5 SXCML module |
sensors | Qt sensors module |
serialbus | Qt functions to access industrial bus
systems |
serialport | Qt functions to access serial ports |
speech | Accessibilty features for Qt5 |
sql | Qt SQL database integration module |
sql-ibase | Qt InterBase/Firebird database plugin |
sql-mysql | Qt MySQL database plugin |
sql-odbc | Qt Open Database Connectivity plugin |
sql-pgsql | Qt PostgreSQL database plugin |
sql-sqlite2 | Qt SQLite 2 database plugin |
sql-sqlite3 | Qt SQLite 3 database plugin |
sql-tds | Qt TDS Database Connectivity database
plugin |
svg | Qt SVG support module |
testlib | Qt unit testing module |
uiplugin | Custom Qt widget plugin interface for Qt
Designer |
uitools | Qt Designer UI forms support module |
virtualkeyboard | Qt 5 Virtual Keyboard Module |
wayland | Qt5 wrapper for Wayland |
webchannel | Qt 5 library for integration of C++/QML with
HTML/js clients |
webengine | Qt 5 library to render web content |
webkit | QtWebKit with a more modern WebKit code
base |
websockets | Qt implementation of WebSocket protocol |
websockets-qml | Qt implementation of WebSocket protocol (QML
bindings) |
webview | Qt component for displaying web content |
widgets | Qt C++ widgets module |
x11extras | Qt platform-specific features for X11-based
systems |
xml | Qt SAX and DOM implementations |
xmlpatterns | Qt support for XPath, XQuery, XSLT and XML
Schema |
To determine the libraries an application
depends on, run ldd on the main
executable after a successful compilation.
Table 6.14. Available Qt Tool Components
| Name | Description |
|---|
buildtools | build tools (moc,
rcc), needed for almost every
Qt application. |
linguisttools | localization tools: lrelease,
lupdate |
qmake | Makefile generator/build utility |
Table 6.15. Available Qt Plugin Components
| Name | Description |
|---|
imageformats | plugins for TGA, TIFF, and MNG
image formats |
Example 6.19. Selecting Qt 5 Components
In this example, the ported application uses the Qt 5
graphical user interface library, the Qt 5 core library,
all of the Qt 5 code generation tools and Qt 5's Makefile
generator. Since the gui library
implies a dependency on the core library,
core does not need to be specified.
The Qt 5 code generation tools moc,
uic and rcc, as well
as the Makefile generator qmake are
only needed at buildtime, thus they are specified with the
_build suffix:
USES= qt:5
USE_QT= gui buildtools_build qmake_build
If the application provides a
qmake project file
(*.pro), define
USES= qmake along with
USE_QT. USES= qmake
already implies a build dependency on qmake, therefore the
qmake component can be omitted from
USE_QT. Similar to CMake,
qmake supports out-of-source
builds, which can be enabled by specifying the
outsource argument (see USES= qmake
example). Also see Table 6.16, “Possible Arguments for
USES= qmake”.
Table 6.16. Possible Arguments for
USES= qmake
| Variable | Description |
|---|
no_configure | Do not add the configure target. This is
implied by HAS_CONFIGURE=yes
and GNU_CONFIGURE=yes.
It is required when the build only needs the
environment setup from
USES= qmake, but otherwise runs
qmake on its own. |
no_env | Suppress modification of the configure and make
environments. It is only required when
qmake is used to configure the
software and the build fails to understand the
environment setup by
USES= qmake. |
norecursive | Do not pass the -recursive
argument to qmake. |
outsource | Perform an out-of-source build. |
Table 6.17. Variables for Ports That Use
qmake
| Variable | Description |
|---|
QMAKE_ARGS | Port specific qmake
flags to be passed to the qmake
binary. |
QMAKE_ENV | Environment variables to be set for the
qmake binary. The default is
${CONFIGURE_ENV}. |
QMAKE_SOURCE_PATH | Path to qmake project files
(.pro). The default is
${WRKSRC} if an
out-of-source build is requested, empty
otherwise. |
When using USES= qmake, these
settings are deployed:
CONFIGURE_ARGS+= --with-qt-includes=${QT_INCDIR} \
--with-qt-libraries=${QT_LIBDIR} \
--with-extra-libs=${LOCALBASE}/lib \
--with-extra-includes=${LOCALBASE}/include
CONFIGURE_ENV+= QTDIR="${QT_PREFIX}" QMAKE="${QMAKE}" \
MOC="${MOC}" RCC="${RCC}" UIC="${UIC}" \
QMAKESPEC="${QMAKESPEC}"
PLIST_SUB+= QT_INCDIR=${QT_INCDIR_REL} \
QT_LIBDIR=${QT_LIBDIR_REL} \
QT_PLUGINDIR=${QT_PLUGINDIR_REL}Some configure scripts do not support the arguments above.
To suppress modification of CONFIGURE_ENV
and CONFIGURE_ARGS, set
USES= qmake:no_env.
Example 6.20. USES= qmake Example
This snippet demonstrates the use of
qmake for a Qt 5 port:
USES= qmake:outsource qt:5
USE_QT= buildtools_build
Qt applications are often written to be cross-platform
and often X11/Unix is not the platform they are developed
on, which in turn leads to certain loose ends,
like:
Missing additional include
paths. Many applications come with
system tray icon support, but neglect to look for
includes and/or libraries in the X11 directories. To add
directories to qmake's
include and library search paths via the command
line, use:
QMAKE_ARGS+= INCLUDEPATH+=${LOCALBASE}/include \
LIBS+=-L${LOCALBASE}/libBogus installation paths.
Sometimes data such as icons or .desktop files are by
default installed into directories which are not scanned
by XDG-compatible applications.
editors/texmaker is
an example for this - look at
patch-texmaker.pro in the
files directory of that port for a
template on how to remedy this directly in the
qmake project file.
6.13.1. KDE Variable Definitions
If the application depends on KDE, set
USES+=kde:5 and
USE_KDE to the list of required
components. _build and
_run suffixes can be used to force
components dependency type (for example,
baseapps_run). If no suffix is set, a
default dependency type will be used. To force both types,
add the component twice with both suffixes (for example,
ecm_build ecm_run). Available components
are listed below (up-to-date components are also listed in
/usr/ports/Mk/Uses/kde.mk):
Table 6.18. Available KDE Components
| Name | Description |
|---|
activities | KF5 runtime and library to organize work in
separate activities |
activities-stats | KF5 statistics for activities |
activitymanagerd | System service to manage user's activities, track
the usage patterns |
akonadi | Storage server for KDE-Pim |
akonadicalendar | Akonadi Calendar Integration |
akonadiconsole | Akonadi management and debugging console |
akonadicontacts | Libraries and daemons to implement Contact
Management in Akonadi |
akonadiimportwizard | Import data from other mail clients to
KMail |
akonadimime | Libraries and daemons to implement basic email
handling |
akonadinotes | KDE library for accessing mail storages in MBox
format |
akonadisearch | Libraries and daemons to implement searching in
Akonadi |
akregator | A Feed Reader by KDE |
alarmcalendar | KDE API for KAlarm alarms |
apidox | KF5 API Documentation Tools |
archive | KF5 library that provides classes for handling
archive formats |
attica | Open Collaboration Services API library KDE5
version |
attica5 | Open Collaboration Services API library KDE5
version |
auth | KF5 abstraction to system policy and
authentication features |
baloo | KF5 Framework for searching and managing user
metadata |
baloo-widgets | BalooWidgets library |
baloo5 | KF5 Framework for searching and managing user
metadata |
blog | KDE API for weblogging access |
bookmarks | KF5 library for bookmarks and the XBEL
format |
breeze | Plasma5 artwork, styles and assets for the Breeze
visual style |
breeze-gtk | Plasma5 Breeze visual style for Gtk |
breeze-icons | Breeze icon theme for KDE |
calendarcore | KDE calendar access library |
calendarsupport | Calendar support libraries for KDEPim |
calendarutils | KDE utility and user interface functions for
accessing calendar |
codecs | KF5 library for string manipulation |
completion | KF5 text completion helpers and widgets |
config | KF5 widgets for configuration dialogs |
configwidgets | KF5 widgets for configuration dialogs |
contacts | KDE api to manage contact information |
coreaddons | KF5 addons to QtCore |
crash | KF5 library to handle crash analysis and bug
report from apps |
dbusaddons | KF5 addons to QtDBus |
decoration | Plasma5 library to create window
decorations |
designerplugin | KF5 integration of Frameworks widgets in Qt
Designer/Creator |
discover | Plasma5 package management tools |
dnssd | KF5 abstraction to system DNSSD features |
doctools | KF5 documentation generation from docbook |
drkonqi | Plasma5 crash handler |
ecm | Extra modules and scripts for CMake |
emoticons | KF5 library to convert emoticons |
eventviews | Event view libriares for KDEPim |
filemetadata | KF5 library for extracting file metadata |
frameworkintegration | KF5 workspace and cross-framework integration
plugins |
gapi | KDE based library to access google
services |
globalaccel | KF5 library to add support for global workspace
shortcuts |
grantlee-editor | Editor for Grantlee themes |
grantleetheme | KDE PIM grantleetheme |
gravatar | Library for gravatar support |
guiaddons | KF5 addons to QtGui |
holidays | KDE library for calendar holidays |
hotkeys | Plasma5 library for hotkeys |
i18n | KF5 advanced internationalization
framework |
iconthemes | KF5 library for handling icons in
applications |
identitymanagement | KDE pim identities |
idletime | KF5 library for monitoring user activity |
imap | KDE API for IMAP support |
incidenceeditor | Incidence editor libriares for KDEPim |
infocenter | Plasma5 utility providing system
information |
init | KF5 process launcher to speed up launching KDE
applications |
itemmodels | KF5 models for Qt Model/View system |
itemviews | KF5 widget addons for Qt Model/View |
jobwidgets | KF5 widgets for tracking KJob instance |
js | KF5 library providing an ECMAScript
interpreter |
jsembed | KF5 library for binding JavaScript objects to
QObjects |
kaddressbook | KDE contact manager |
kalarm | Personal alarm scheduler |
kalarm | Personal alarm scheduler |
kate | Basic editor framework for the KDE system |
kcmutils | KF5 utilities for working with KCModules |
kde-cli-tools | Plasma5 non-interactive system tools |
kde-gtk-config | Plasma5 GTK2 and GTK3 configurator |
kdeclarative | KF5 library providing integration of QML and KDE
Frameworks |
kded | KF5 extensible daemon for providing system level
services |
kdelibs4support | KF5 porting aid from KDELibs4 |
kdepim-addons | KDE PIM addons |
kdepim-apps-libs | KDE PIM mail related libraries |
kdepim-runtime5 | KDE PIM tools and services |
kdeplasma-addons | Plasma5 addons to improve the Plasma
experience |
kdesu | KF5 integration with su for elevated
privileges |
kdewebkit | KF5 library providing integration of
QtWebKit |
kgamma5 | Plasma5 monitor's gamma settings |
khtml | KF5 KTHML rendering engine |
kimageformats | KF5 library providing support for additional
image formats |
kio | KF5 resource and network access
abstraction |
kirigami2 | QtQuick based components set |
kitinerary | Data Model and Extraction System for Travel
Reservation information |
kmail | KDE mail client |
kmail | KDE mail client |
kmail-account-wizard | KDE mail account wizard |
kmenuedit | Plasma5 menu editor |
knotes | Popup notes |
kontact | KDE Personal Information Manager |
kontact | KDE Personal Information Manager |
kontactinterface | KDE glue for embedding KParts into
Kontact |
korganizer | Calendar and scheduling Program |
kpimdav | A DAV protocol implementation with KJobs |
kpkpass | Library to deal with Apple Wallet pass
files |
kross | KF5 multi-language application scripting |
kscreen | Plasma5 screen management library |
kscreenlocker | Plasma5 secure lock screen architecture |
ksmtp | Job-based library to send email through an SMTP
server |
ksshaskpass | Plasma5 ssh-add frontend |
ksysguard | Plasma5 utility to track and control the running
processes |
kwallet-pam | Plasma5 KWallet PAM Integration |
kwayland-integration | Integration plugins for a Wayland-based
desktop |
kwin | Plasma5 window manager |
kwrited | Plasma5 daemon listening for wall and write
messages |
ldap | LDAP access API for KDE |
libkcddb | KDE CDDB library |
libkcompactdisc | KDE library for interfacing with audio
CDs |
libkdcraw | LibRaw interface for KDE |
libkdegames | Libraries used by KDE games |
libkdepim | KDE PIM Libraries |
libkeduvocdocument | Library for reading and writing vocabulary
files |
libkexiv2 | Exiv2 library interface for KDE |
libkipi | KDE Image Plugin Interface |
libkleo | Certificate manager for KDE |
libksane | SANE library interface for KDE |
libkscreen | Plasma5 screen management library |
libksieve | Sieve libriares for KDEPim |
libksysguard | Plasma5 library to track and control running
processes |
mailcommon | Common libriares for KDEPim |
mailimporter | Import mbox files to KMail |
mailtransport | KDE library to managing mail transport |
marble | Virtual globe and world atlas for KDE |
mbox | KDE library for accessing mail storages in MBox
format |
mbox-importer | Import mbox files to KMail |
mediaplayer | KF5 plugin interface for media player
features |
messagelib | Library for handling messages |
milou | Plasma5 Plasmoid for search |
mime | Library for handling MIME data |
newstuff | KF5 library for downloading application assets
from the network |
notifications | KF5 abstraction for system notifications |
notifyconfig | KF5 configuration system for KNotify |
okular | KDE universal document viewer |
oxygen | Plasma5 Oxygen style |
oxygen-icons5 | The Oxygen icon theme for KDE |
package | KF5 library to load and install packages |
parts | KF5 document centric plugin system |
people | KF5 library providing access to contacts |
pim-data-exporter | Import and export KDE PIM settings |
pimcommon | Common libriares for KDEPim |
pimtextedit | KDE library for PIM-specific text editing
utilities |
plasma-browser-integration | Plasma5 components to integrate browsers into the
desktop |
plasma-desktop | Plasma5 plasma desktop |
plasma-framework | KF5 plugin based UI runtime used to write user
interfaces |
plasma-integration | Qt Platform Theme integration plugins for the
Plasma workspaces |
plasma-pa | Plasma5 Plasma pulse audio mixer |
plasma-sdk | Plasma5 applications useful for Plasma
development |
plasma-workspace | Plasma5 Plasma workspace |
plasma-workspace-wallpapers | Plasma5 wallpapers |
plotting | KF5 lightweight plotting framework |
polkit-kde-agent-1 | Plasma5 daemon providing a polkit authentication
UI |
powerdevil | Plasma5 tool to manage the power consumption
settings |
prison | API to produce barcodes |
pty | KF5 pty abstraction |
purpose | Offers available actions for a specific
purpose |
qqc2-desktop-style | Qt QuickControl2 style for KDE |
runner | KF5 parallelized query system |
service | KF5 advanced plugin and service
introspection |
solid | KF5 hardware integration and detection |
sonnet | KF5 plugin-based spell checking library |
syndication | KDE RSS feed handling library |
syntaxhighlighting | KF5 syntax highlighting engine for structured
text and code |
systemsettings | Plasma5 system settings |
texteditor | KF5 advanced embeddable text editor |
textwidgets | KF5 advanced text editing widgets |
threadweaver | KF5 addons to QtDBus |
tnef | KDE API for the handling of TNEF data |
unitconversion | KF5 library for unit conversion |
user-manager | Plasma5 user manager |
wallet | KF5 secure and unified container for user
passwords |
wayland | KF5 Client and Server library wrapper for the
Wayland libraries |
widgetsaddons | KF5 addons to QtWidgets |
windowsystem | KF5 library for access to the windowing
system |
xmlgui | KF5 user configurable main windows |
xmlrpcclient | KF5 interaction with XMLRPC services |
Example 6.21. USE_KDE Example
This is a simple example for a KDE port.
USES= cmake instructs the
port to utilize CMake, a
configuration tool widely used by KDE projects (see
Section 6.5.4, “Using cmake” for detailed usage).
USE_KDE brings dependency on KDE
libraries. Required KDE components and other dependencies
can be determined through the configure log.
USE_KDE does not imply
USE_QT. If a port requires some
Qt components, specify them in
USE_QT.
USES= cmake kde:5 qt:5
USE_KDE= ecm
USE_QT= core buildtools_build qmake_build
Applications depending on LXQt should set
USES+= lxqt and set
USE_LXQT
to the list of required components from the table below
Table 6.19. Available LXQt Components
| Name | Description |
|---|
buildtools | Helpers for additional CMake modules |
libfmqt | Libfm Qt bindings |
lxqt | LXQt core library |
qtxdg | Qt implementation of freedesktop.org
XDG specifications |
Example 6.22. USE_LXQT Example
This is a simple example,
USE_LXQT adds a dependency on
LXQt libraries. Required LXQt components and
other dependencies can be determined from the
configure log.
USES= cmake lxqt qt:5 tar:xz
USE_QT= core dbus widgets buildtools_build qmake_build
USE_LXQT= buildtools libfmqt
6.15.1. Variable Definitions
If the port needs a Java™ Development Kit
(JDK™) to either build, run or even
extract the distfile, then define
USE_JAVA.
There are several JDKs in the ports
collection, from various vendors, and in several versions. If
the port must use a particular version, specify it using the
JAVA_VERSION variable.
The most current version is
java/openjdk15, with
java/openjdk14,
java/openjdk13,
java/openjdk12,
java/openjdk11,
java/openjdk8, and
java/openjdk7 also
available.
Table 6.20. Variables Which May be Set by Ports That Use
Java
| Variable | Means |
|---|
USE_JAVA | Define for the remaining variables
to have any effect. |
JAVA_VERSION | List of space-separated suitable Java versions
for the port. An optional "+"
allows specifying a range of versions (allowed
values: 7[+] 8[+] 11[+] 12[+] 13[+] 14[+]
15[+]). |
JAVA_OS | List of space-separated suitable
JDK port operating systems for the
port (allowed values:
native linux). |
JAVA_VENDOR | List of space-separated suitable
JDK port vendors for the port
(allowed values:
freebsd bsdjava sun
openjdk). |
JAVA_BUILD | When set, add the selected JDK
port to the build dependencies. |
JAVA_RUN | When set, add the selected JDK
port to the run dependencies. |
JAVA_EXTRACT | When set, add the selected JDK
port to the extract dependencies. |
Below is the list of all settings a port will receive
after setting USE_JAVA:
Table 6.21. Variables Provided to Ports That Use Java
| Variable | Value |
|---|
JAVA_PORT | The name of the JDK port (for
example, java/openjdk6). |
JAVA_PORT_VERSION | The full version of the JDK
port (for example, 1.6.0). Only
the first two digits of this version number are
needed, use
${JAVA_PORT_VERSION:C/^([0-9])\.([0-9])(.*)$/\1.\2/}. |
JAVA_PORT_OS | The operating system used by the
JDK port (for example,
'native'). |
JAVA_PORT_VENDOR | The vendor of the JDK port
(for example, 'openjdk'). |
JAVA_PORT_OS_DESCRIPTION | Description of the operating system used by the
JDK port (for example,
'Native'). |
JAVA_PORT_VENDOR_DESCRIPTION | Description of the vendor of the
JDK port (for example,
'OpenJDK BSD Porting
Team'). |
JAVA_HOME | Path to the installation directory of the
JDK (for example,
'/usr/local/openjdk6'). |
JAVAC | Path to the Java compiler to use (for example,
'/usr/local/openjdk6/bin/javac'). |
JAR | Path to the jar tool to use
(for example,
'/usr/local/openjdk6/bin/jar'
or
'/usr/local/bin/fastjar'). |
APPLETVIEWER | Path to the appletviewer
utility (for example,
'/usr/local/openjdk6/bin/appletviewer'). |
JAVA | Path to the java executable.
Use this for executing Java programs (for example,
'/usr/local/openjdk6/bin/java'). |
JAVADOC | Path to the javadoc utility
program. |
JAVAH | Path to the javah
program. |
JAVAP | Path to the javap
program. |
JAVA_KEYTOOL | Path to the keytool utility
program. |
JAVA_N2A | Path to the native2ascii
tool. |
JAVA_POLICYTOOL | Path to the policytool
program. |
JAVA_SERIALVER | Path to the serialver
utility program. |
RMIC | Path to the RMI stub/skeleton generator,
rmic. |
RMIREGISTRY | Path to the RMI registry program,
rmiregistry. |
RMID | Path to the RMI daemon program
rmid. |
JAVA_CLASSES | Path to the archive that contains the
JDK class files,
${JAVA_HOME}/jre/lib/rt.jar. |
Use the java-debug make
target to get information for debugging the port. It will
display the value of many of the previously listed
variables.
Additionally, these constants are defined so all
Java ports may be installed in a consistent way:
Table 6.22. Constants Defined for Ports That Use Java
| Constant | Value |
|---|
JAVASHAREDIR | The base directory for everything related to
Java. Default:
${PREFIX}/share/java. |
JAVAJARDIR | The directory where JAR files is
installed. Default:
${JAVASHAREDIR}/classes. |
JAVALIBDIR | The directory where JAR files installed by
other ports are located. Default:
${LOCALBASE}/share/java/classes. |
The related entries are defined in both
PLIST_SUB (documented in
Section 8.1, “Changing pkg-plist Based on Make
Variables”) and
SUB_LIST.
6.15.2. Building with Ant
When the port is to be built using Apache Ant, it has to
define USE_ANT. Ant is thus considered to
be the sub-make command. When no
do-build target is defined by the
port, a default one will be set that runs Ant according to
MAKE_ENV, MAKE_ARGS and
ALL_TARGET. This is similar to the
USES= gmake mechanism, which is documented
in Section 6.5, “Building Mechanisms”.
When porting a Java library, the port has to install
the JAR file(s) in ${JAVAJARDIR}, and
everything else under
${JAVASHAREDIR}/${PORTNAME} (except for
the documentation, see below). To reduce the packing file
size, reference the JAR file(s) directly in the
Makefile. Use this statement (where
myport.jar
PLIST_FILES+= ${JAVAJARDIR}/myport.jarWhen porting a Java application, the port usually
installs everything under a single directory (including its
JAR dependencies). The use of
${JAVASHAREDIR}/${PORTNAME} is strongly
encouraged in this regard. It is up the porter to decide
whether the port installs the additional JAR
dependencies under this directory or uses the
already installed ones (from
${JAVAJARDIR}).
When porting a Java™ application that requires an
application server such as
www/tomcat7 to run the
service, it is quite common for a vendor to distribute a
.war. A .war
is a Web application ARchive and is extracted when
called by the application. Avoid adding a
.war
to pkg-plist.
It is not considered best practice. An application server
will expand war archive, but not
clean it up properly if the port is removed. A more
desirable way of working with this file is to extract the
archive, then install the files, and lastly add these files
to pkg-plist.
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}Regardless of the type of port (library or
application), the additional documentation is installed in the
same location as
for any other port. The Javadoc tool is known to produce a
different set of files depending on the version of the
JDK that is used. For ports that do not
enforce the use of a particular JDK, it is
therefore a complex task to specify the packing list
(pkg-plist). This is one reason why
porters are strongly encouraged to use
PORTDOCS. Moreover, even if the set of
files that will be generated by javadoc can
be predicted, the size of the resulting
pkg-plist advocates for the use of
PORTDOCS.
The default value for DATADIR is
${PREFIX}/share/${PORTNAME}. It is a
good idea to override DATADIR to
${JAVASHAREDIR}/${PORTNAME} for Java
ports. Indeed, DATADIR is automatically
added to PLIST_SUB (documented in
Section 8.1, “Changing pkg-plist Based on Make
Variables”) so use
%%DATADIR%% directly in
pkg-plist.
As for the choice of building Java ports from source or
directly installing them from a binary distribution, there
is no defined policy at the time of writing. However,
people from the
FreeBSD Java
Project encourage porters to have their ports
built from source whenever it is a trivial task.
All the features that have been presented in this
section are implemented in bsd.java.mk.
If the port needs more sophisticated
Java support, please first have a look at the bsd.java.mk
Subversion log as it
usually takes some time to document the latest features.
Then, if the needed support that is lacking would be
beneficial to many other Java ports, feel free to discuss it
on the FreeBSD Java Language mailing list.
Although there is a java category for
PRs, it refers to the JDK porting effort
from the FreeBSD Java project. Therefore, submit the Java port
in the ports category as for any other
port, unless the issue is related to either a
JDK implementation or
bsd.java.mk.
Similarly, there is a defined policy regarding the
CATEGORIES of a Java port, which is
detailed in Section 5.3, “Categorization”.
6.16. Web Applications, Apache and PHP
Table 6.23. Variables for Ports That Use Apache
USE_APACHE | The port requires Apache. Possible values:
yes (gets any version),
22, 24,
22-24, 22+,
etc. The default APACHE version is
22. More details are available
in ports/Mk/bsd.apache.mk and
at wiki.freebsd.org/Apache/. |
APXS | Full path to the apxs
binary. Can be overridden in the port. |
HTTPD | Full path to the httpd
binary. Can be overridden in the port. |
APACHE_VERSION | The version of present Apache installation
(read-only variable). This variable is only
available after inclusion of
bsd.port.pre.mk. Possible
values: 22,
24. |
APACHEMODDIR | Directory for Apache modules. This variable is
automatically expanded in
pkg-plist. |
APACHEINCLUDEDIR | Directory for Apache headers. This variable is
automatically expanded in
pkg-plist. |
APACHEETCDIR | Directory for Apache configuration files. This
variable is automatically expanded in
pkg-plist. |
Table 6.24. Useful Variables for Porting Apache Modules
MODULENAME | Name of the module. Default value is
PORTNAME. Example:
mod_hello |
SHORTMODNAME | Short name of the module. Automatically
derived from MODULENAME, but can
be overridden. Example:
hello |
AP_FAST_BUILD | Use apxs to compile and
install the module. |
AP_GENPLIST | Also automatically creates a
pkg-plist. |
AP_INC | Adds a directory to a header search path during
compilation. |
AP_LIB | Adds a directory to a library search path
during compilation. |
AP_EXTRAS | Additional flags to pass to
apxs. |
Web applications must be installed into
PREFIX/www/appname.
This path is available both in
Makefile and in
pkg-plist as WWWDIR,
and the path relative to PREFIX is
available in Makefile as
WWWDIR_REL.
The user and group of web server process are available
as WWWOWN and WWWGRP,
in case the ownership of some files needs to be changed. The
default values of both are www. Use
WWWOWN?= myuser and WWWGRP?=
mygroup if the port needs different values. This
allows the user to override them easily.
Important:
Use WWWOWN and
WWWGRP sparingly. Remember that every
file the web server can write to is a security risk waiting
to happen.
Do not depend on Apache unless the web app explicitly
needs Apache. Respect that users may wish to run a web
application on a web server other than
Apache.
PHP web applications declare
their dependency on it with USES=php. See
Section 17.69, “php” for more information.
Porting PEAR modules is a very simple process.
Add USES=pear to the port's
Makefile. The framework will install the
relevant files in the right places and automatically generate
the plist at install time.
Example 6.23. Example Makefile for PEAR Class
PORTNAME= Date
DISTVERSION= 1.4.3
CATEGORIES= devel www pear
MAINTAINER= example@domain.com
COMMENT= PEAR Date and Time Zone Classes
USES= pear
.include <bsd.port.mk>
Tip:
PEAR modules will
automatically be flavorized using PHP
flavors.
Note:
If a non default PEAR_CHANNEL is
used, the build and run-time dependencies will automatically
be added.
Important:
PEAR modules do not need to defined
PKGNAMESUFFIX it is automatically filled
in using PEAR_PKGNAMEPREFIX. If a port
needs to add to PKGNAMEPREFIX, it must
also use PEAR_PKGNAMEPREFIX to
differentiate between different flavors.
In the same way, porting
Horde modules is a simple
process.
Add USES=horde to the port's
Makefile. The framework will install
the relevant files in the right places and automatically
generate the plist at install time.
The USE_HORDE_BUILD and
USE_HORDE_RUN variables can be used to
add buildtime and runtime dependencies on other
Horde modules. See
Mk/Uses/horde.mk for a complete list of
available modules.
Example 6.24. Example Makefile for Horde
Module
PORTNAME= Horde_Core
DISTVERSION= 2.14.0
CATEGORIES= devel www pear
MAINTAINER= horde@FreeBSD.org
COMMENT= Horde Core Framework libraries
OPTIONS_DEFINE= KOLAB SOCKETS
KOLAB_DESC= Enable Kolab server support
SOCKETS_DESC= Depend on sockets PHP extension
USES= horde
USE_PHP= session
USE_HORDE_BUILD= Horde_Role
USE_HORDE_RUN= Horde_Role Horde_History Horde_Pack \
Horde_Text_Filter Horde_View
KOLAB_USE= HORDE_RUN=Horde_Kolab_Server,Horde_Kolab_Session
SOCKETS_USE= PHP=sockets
.include <bsd.port.mk>
Tip:
As Horde modules are also
PEAR modules they will also
automatically be flavorized using PHP
flavors.
The Ports Collection supports parallel installation of
multiple Python versions. Ports must use a
correct python interpreter, according to
the user-settable PYTHON_VERSION.
Most prominently, this means replacing the path to
python executable in scripts with the value
of PYTHON_CMD.
Ports that install files under
PYTHON_SITELIBDIR must use the
pyXY- package name prefix, so their package
name embeds the version of Python they are installed
into.
PKGNAMEPREFIX= ${PYTHON_PKGNAMEPREFIX}Table 6.25. Most Useful Variables for Ports That Use Python
USES=python | The port needs Python. The minimal required
version can be specified with values such as
2.7+. Version ranges can also be
specified by separating two version numbers with a dash:
USES=python:3.2-3.3 |
USE_PYTHON=distutils | Use Python distutils for configuring, compiling,
and installing. This is required when the port comes
with setup.py. This overrides
the do-build and
do-install targets and may
also override do-configure
if GNU_CONFIGURE is not
defined. Additionally, it implies
USE_PYTHON=flavors. |
USE_PYTHON=autoplist | Create the packaging list automatically. This also
requires USE_PYTHON=distutils to be
set. |
USE_PYTHON=concurrent | The port will use an unique prefix, typically
PYTHON_PKGNAMEPREFIX for certain
directories, such as EXAMPLESDIR and
DOCSDIR and also will append a
suffix, the python version from
PYTHON_VER, to binaries and scripts
to be installed. This allows ports to be installed for
different Python versions at the same time, which
otherwise would install conflicting files. |
USE_PYTHON=flavors | The port does not use distutils but still supports
multiple Python versions. FLAVORS
will be set to the supported Python versions. See Section 7.4, “USES=python and Flavors” for more
information. |
USE_PYTHON=optsuffix | If the current Python version is not the default
version, the port will gain
PKGNAMESUFFIX=${PYTHON_PKGNAMESUFFIX}.
Only useful with flavors. |
PYTHON_PKGNAMEPREFIX | Used as a PKGNAMEPREFIX to
distinguish packages for different Python versions.
Example: py27- |
PYTHON_SITELIBDIR | Location of the site-packages tree, that contains
installation path of Python (usually
LOCALBASE).
PYTHON_SITELIBDIR can be
very useful when installing Python modules. |
PYTHONPREFIX_SITELIBDIR | The PREFIX-clean variant of PYTHON_SITELIBDIR.
Always use %%PYTHON_SITELIBDIR%% in
pkg-plist when possible. The
default value of
%%PYTHON_SITELIBDIR%% is
lib/python%%PYTHON_VERSION%%/site-packages |
PYTHON_CMD | Python interpreter command line, including
version number. |
Table 6.26. Python Module Dependency Helpers
PYNUMERIC | Dependency line for numeric extension. |
PYNUMPY | Dependency line for the new numeric extension,
numpy. (PYNUMERIC is deprecated by upstream
vendor). |
PYXML | Dependency line for XML extension (not needed for
Python 2.0 and higher as it is also in base
distribution). |
PY_ENUM34 | Conditional dependency on
devel/py-enum34 depending on the
Python version. |
PY_ENUM_COMPAT | Conditional dependency on
devel/py-enum-compat depending on the
Python version. |
PY_PATHLIB | Conditional dependency on
devel/py-pathlib depending on the
Python version. |
PY_IPADDRESS | Conditional dependency on
net/py-ipaddress depending on the
Python version. |
PY_FUTURES | Conditional dependency on
devel/py-futures depending on the
Python version. |
A complete list of available variables can be found in
/usr/ports/Mk/Uses/python.mk.
Example 6.25. Makefile for a Simple Python
Module
PORTNAME= sample
DISTVERSION= 1.2.3
CATEGORIES= devel
MAINTAINER= john@doe.tld
COMMENT= Python sample module
RUN_DEPENDS= ${PYTHON_PKGNAMEPREFIX}six>0:devel/py-six@${PY_FLAVOR}
USES= python
USE_PYTHON= autoplist distutils
.include <bsd.port.mk>Some Python applications claim to have
DESTDIR support (which would be required
for staging) but it is broken (Mailman up to 2.1.16, for
instance). This can be worked around by recompiling the
scripts. This can be done, for example, in the
post-build target. Assuming the
Python scripts are supposed to reside in
PYTHONPREFIX_SITELIBDIR after installation,
this solution can be applied:
(cd ${STAGEDIR}${PREFIX} \
&& ${PYTHON_CMD} ${PYTHON_LIBDIR}/compileall.py \
-d ${PREFIX} -f ${PYTHONPREFIX_SITELIBDIR:S;${PREFIX}/;;})This recompiles the sources with a path relative to the
stage directory, and prepends the value of
PREFIX to the file name recorded in the
byte-compiled output file by -d.
-f is required to force recompilation, and
the :S;${PREFIX}/;; strips prefixes from
the value of PYTHONPREFIX_SITELIBDIR
to make it relative to
PREFIX.
The Ports Collection supports parallel installation of
multiple Tcl/Tk versions. Ports
should try to support at least the default
Tcl/Tk version and higher with
USES=tcl. It is possible to specify the
desired version of tcl by appending
:xx, for example,
USES=tcl:85.
Table 6.27. The Most Useful Read-Only Variables for Ports That Use
Tcl/Tk
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 |
See the USES=tcl and
USES=tk of
Chapter 17, Using USES Macros for a full description of those
variables. A complete list of those variables is available in
/usr/ports/Mk/Uses/tcl.mk.
Table 6.28. Useful Variables for Ports That Use Ruby
| Variable | Description |
|---|
USE_RUBY | Adds build and run dependencies on Ruby. |
USE_RUBY_EXTCONF | The port uses extconf.rb to
configure. |
USE_RUBY_SETUP | The port uses setup.rb to
configure. |
RUBY_SETUP | Override the name of the setup script from
setup.rb. Another common value is
install.rb. |
This table shows the selected variables available
to port authors via the ports infrastructure. These variables
are used to install files into their proper locations.
Use them in pkg-plist as much as
possible. Do not redefine these variables in the port.
Table 6.29. Selected Read-Only Variables for Ports That Use
Ruby
| Variable | Description | Example value |
|---|
RUBY_PKGNAMEPREFIX | Used as a PKGNAMEPREFIX to
distinguish packages for different Ruby
versions. | ruby19- |
RUBY_VERSION | Full version of Ruby in the form of
x.y.z[.p]. | 1.9.3.484 |
RUBY_SITELIBDIR | Architecture independent libraries installation
path. | /usr/local/lib/ruby/site_ruby/1.9 |
RUBY_SITEARCHLIBDIR | Architecture dependent libraries installation
path. | /usr/local/lib/ruby/site_ruby/1.9/amd64-freebsd10 |
RUBY_MODDOCDIR | Module documentation installation path. | /usr/local/share/doc/ruby19/patsy |
RUBY_MODEXAMPLESDIR | Module examples installation path. | /usr/local/share/examples/ruby19/patsy |
A complete list of available variables can be found in
/usr/ports/Mk/bsd.ruby.mk.
USE_SDL is used to
autoconfigure the dependencies for ports which use an SDL
based library like devel/sdl12
and graphics/sdl_image.
These SDL libraries for version 1.2 are recognized:
These SDL libraries for version 2.0 are recognized:
Therefore, if a port has a dependency on
net/sdl_net and
audio/sdl_mixer,
the syntax will be:
USE_SDL= net mixer
The dependency
devel/sdl12, which is
required by net/sdl_net
and audio/sdl_mixer, is
automatically added as well.
Using USE_SDL with entries for
SDL 1.2, it will automatically:
Add a dependency on
sdl12-config to
BUILD_DEPENDS
Add the variable SDL_CONFIG to
CONFIGURE_ENV
Add the dependencies of the selected libraries to
LIB_DEPENDS
Using USE_SDL with entries for
SDL 2.0, it will automatically:
Add a dependency on
sdl2-config to
BUILD_DEPENDS
Add the variable SDL2_CONFIG to
CONFIGURE_ENV
Add the dependencies of the selected libraries to
LIB_DEPENDS
This section describes the status of the
wxWidgets libraries in the ports
tree and its integration with the ports system.
There are many versions of the
wxWidgets libraries which
conflict between them (install files under the same name).
In the ports tree this problem has been solved by installing
each version under a different name using version number
suffixes.
The obvious disadvantage of this is that each
application has to be modified to find the expected version.
Fortunately, most of the applications call the
wx-config script to determine the
necessary compiler and linker flags. The script is named
differently for every available version. Majority of
applications respect an environment variable, or accept a
configure argument, to specify which
wx-config script to call. Otherwise they
have to be patched.
6.21.2. Version Selection
To make the port use a specific version of
wxWidgets there are two variables
available for defining (if only one is defined the other
will be set to a default value):
Table 6.30. Variables to Select
wxWidgets Versions
| Variable | Description | Default value |
|---|
USE_WX | List of versions the port can use | All available versions |
USE_WX_NOT | List of versions the port cannot use | None |
The available
wxWidgets versions and the
corresponding ports in the tree are:
Table 6.31. Available wxWidgets
Versions
The variables in Table 6.30, “Variables to Select
wxWidgets Versions” can
be set to one or more of these combinations
separated by spaces:
Table 6.32. wxWidgets Version
Specifications
| Description | Example |
|---|
| Single version | 2.8 |
| Ascending range | 2.8+ |
| Descending range | 3.0- |
| Full range (must be ascending) | 2.8-3.0 |
There are also some variables to select the preferred
versions from the available ones. They can be set to a list
of versions, the first ones will have higher
priority.
Table 6.33. Variables to Select Preferred
wxWidgets Versions
| Name | Designed for |
|---|
WANT_WX_VER | the port |
WITH_WX_VER | the user |
6.21.3. Component Selection
There are other applications that, while not being
wxWidgets libraries, are related
to them. These applications can be specified in
WX_COMPS. These
components are available:
Table 6.34. Available wxWidgets
Components
| Name | Description | Version restriction |
|---|
wx | main library | none |
contrib | contributed libraries | none |
python | wxPython
(Python bindings) | 2.8-3.0 |
The dependency type can be selected for each component
by adding a suffix separated by a semicolon. If not present
then a default type will be used (see
Table 6.36, “Default wxWidgets
Dependency Types”). These types
are available:
Table 6.35. Available wxWidgets
Dependency Types
| Name | Description |
|---|
build | Component is required for building, equivalent
to BUILD_DEPENDS |
run | Component is required for running, equivalent
to RUN_DEPENDS |
lib | Component is required for building and running,
equivalent to LIB_DEPENDS |
The default values for the components are detailed in
this table:
Table 6.36. Default wxWidgets
Dependency Types
| Component | Dependency type |
|---|
wx | lib |
contrib | lib |
python | run |
mozilla | lib |
svg | lib |
Example 6.26. Selecting wxWidgets
Components
This fragment corresponds to a port which
uses wxWidgets version
2.4 and its contributed
libraries.
USE_WX= 2.8
WX_COMPS= wx contrib
6.21.4. Detecting Installed Versions
To detect an installed version, define
WANT_WX. If it is not set to a
specific version then the components will have a version
suffix. HAVE_WX will be
filled after detection.
Example 6.27. Detecting Installed
wxWidgets Versions and
Components
This fragment can be used in a port that uses
wxWidgets if it is installed,
or an option is selected.
WANT_WX= yes
.include <bsd.port.pre.mk>
.if defined(WITH_WX) || !empty(PORT_OPTIONS:MWX) || !empty(HAVE_WX:Mwx-2.8)
USE_WX= 2.8
CONFIGURE_ARGS+= --enable-wx
.endif
This fragment can be used in a port that
enables wxPython support if it
is installed or if an option is selected, in addition to
wxWidgets, both version
2.8.
USE_WX= 2.8
WX_COMPS= wx
WANT_WX= 2.8
.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
6.21.5. Defined Variables
These variables are available in the port (after
defining one from
Table 6.30, “Variables to Select
wxWidgets Versions”).
Table 6.37. Variables Defined for Ports That Use
wxWidgets
| Name | Description |
|---|
WX_CONFIG | The path to the
wxWidgets
wx-config script (with different
name) |
WXRC_CMD | The path to the
wxWidgets
wxrc program (with different
name) |
WX_VERSION | The wxWidgets
version that is going to be used (for example,
2.6) |
6.21.6. Processing in
bsd.port.pre.mk
Define WX_PREMK to be able to use the
variables right after including
bsd.port.pre.mk.
Important:
When defining WX_PREMK, then the
version, dependencies, components and defined variables
will not change if modifying the
wxWidgets port variables
after including
bsd.port.pre.mk.
Example 6.28. Using wxWidgets Variables
in Commands
This fragment illustrates the use of
WX_PREMK by running the
wx-config script to obtain the full
version string, assign it to a variable and pass it to the
program.
USE_WX= 2.8
WX_PREMK= yes
.include <bsd.port.pre.mk>
.if exists(${WX_CONFIG})
VER_STR!= ${WX_CONFIG} --release
PLIST_SUB+= VERSION="${VER_STR}"
.endifNote:
The wxWidgets variables can
be safely used in commands when they are inside targets
without the need of WX_PREMK.
6.21.7. Additional configure
Arguments
Some GNU configure scripts cannot
find wxWidgets with just the
WX_CONFIG environment variable set,
requiring additional arguments.
WX_CONF_ARGS can be used for
provide them.
Table 6.38. Legal Values for
WX_CONF_ARGS
| Possible value | Resulting argument |
|---|
absolute | --with-wx-config=${WX_CONFIG} |
relative | --with-wx=${LOCALBASE}
--with-wx-config=${WX_CONFIG:T} |
This section describes the status of the
Lua libraries in the ports tree and
its integration with the ports system.
There are many versions of the
Lua libraries and corresponding
interpreters, which conflict between them (install files
under the same name). In the ports tree this problem has
been solved by installing each version under a different
name using version number suffixes.
The obvious disadvantage of this is that each
application has to be modified to find the expected version.
But it can be solved by adding some additional flags to the
compiler and linker.
Applications that use Lua
should normally build for just one version. However, loadable
modules for Lua are built in a separate flavor for each Lua
version that they support, and dependencies on such modules
should specify the flavor using the
@${LUA_FLAVOR} suffix on the port
origin.
6.22.2. Version Selection
A port using Lua should
have a line of this form:
USES= lua
If a specific version of Lua, or range of versions, is
needed, it can be specified as a parameter in the form
XY (which may be used multiple times),
XY+, -XY, or
XY-ZA. The default version of
Lua as set via
DEFAULT_VERSIONS will be used if it falls
in the requested range, otherwise the closest requested
version to the default will be used. For example:
USES= lua:52-53
Note that no attempt is made to adjust the version
selection based on the presence of any already-installed
Lua version.
Note:
The XY+ form of version specification
should not be used without careful consideration; the
Lua API changes to some extent in
every version, and configuration tools like
CMake or
Autoconf will often fail to work
on future versions of Lua until
updated to do so.
6.22.3. Configuration and Compiler flags
Software that uses Lua may have
been written to auto-detect the Lua
version in use. In general ports should override this
assumption, and force the use of the specific
Lua version selected as described
above. Depending on the software being ported, this might
require any or all of:
Using LUA_VER as part of a parameter
to the software's configuration script via
CONFIGURE_ARGS or
CONFIGURE_ENV (or equivalent for other
build systems);
Adding -I${LUA_INCDIR},
-L${LUA_LIBDIR}, and
-llua-${LUA_VER} to CFLAGS,
LDFLAGS, LIBS respectively
as appropriate;
Patch the software's configuration or build files to select
the correct version.
A port which installs a Lua
module (rather than an application that simply makes use of
Lua) should build a separate
flavor for each supported Lua
version. This is done by adding the module
parameter:
USES= lua:module
A version number or range of versions can be specified as
well; use a comma to separate parameters.
Since each flavor must have a different package name, the
variable LUA_PKGNAMEPREFIX is provided which
will be set to an appropriate value; the intended usage
is:
PKGNAMEPREFIX= ${LUA_PKGNAMEPREFIX}Module ports should normally install files only to
LUA_MODLIBDIR,
LUA_MODSHAREDIR,
LUA_DOCSDIR, and
LUA_EXAMPLESDIR, all of which are set up
to refer to version-specific subdirectories. Installing any
other files must be done with care to avoid conflicts between
versions.
A port (other than a Lua module)
which wishes to build a separate package for each
Lua version should use the
flavors parameter:
USES= lua:flavors
This operates the same way as the module
parameter described above, but without the assumption that the
package should be documented as a Lua
module (so LUA_DOCSDIR and
LUA_EXAMPLESDIR are not defined by
default). However, the port may choose to define
LUA_DOCSUBDIR as a suitable subdirectory name
(usually the port's PORTNAME as long as this
does not conflict with the PORTNAME of any
module), in which case the framework will define both
LUA_DOCSDIR and
LUA_EXAMPLESDIR.
As with module ports, a flavored port should avoid installing
files that would conflict between versions. Typically this is done
by adding LUA_VER_STR as a suffix to program
names (e.g. using
USES=uniquefiles), and
otherwise using either LUA_VER or
LUA_VER_STR as part of any other files or
subdirectories used outside of LUA_MODLIBDIR
and LUA_MODSHAREDIR.
6.22.5. Defined Variables
These variables are available in the port.
Table 6.39. Variables Defined for Ports That Use
Lua
| Name | Description |
|---|
LUA_VER | The Lua version that
is going to be used (for example,
5.1) |
LUA_VER_STR | The Lua version
without the dots (for example,
51) |
LUA_FLAVOR | The flavor name corresponding to the selected
Lua version, to be used
for specifying dependencies |
LUA_BASE | The prefix that should be used to locate
Lua (and components) that
are already installed |
LUA_PREFIX | The prefix where Lua
(and components) are to be installed by this port |
LUA_INCDIR | The directory where
Lua header files are
installed |
LUA_LIBDIR | The directory where
Lua libraries are
installed |
LUA_REFMODLIBDIR | The directory where
Lua module libraries
(.so) that are already
installed are to be found |
LUA_REFMODSHAREDIR | The directory where
Lua modules
(.lua) that are already
installed are to be found |
LUA_MODLIBDIR | The directory where
Lua module libraries
(.so) are to be installed
by this port |
LUA_MODSHAREDIR | The directory where
Lua modules
(.lua) are to be installed
by this port |
LUA_PKGNAMEPREFIX | The package name prefix used by
Lua modules |
LUA_CMD | The name of the Lua
interpreter (e.g. lua53) |
LUAC_CMD | The name of the Lua
compiler (e.g. luac53) |
These additional variables are available for ports that
specified the module parameter:
Table 6.40. Variables Defined for Lua
Module Ports
| Name | Description |
|---|
LUA_DOCSDIR | the directory to which the module's
documentation should be installed. |
LUA_EXAMPLESDIR | the directory to which the module's
example files should be installed. |
Example 6.29. Makefile for an application using
Lua
This example shows how to reference a
Lua module required at run
time. Notice that the reference must specify a
flavor.
PORTNAME= sample
DISTVERSION= 1.2.3
CATEGORIES= whatever
MAINTAINER= john@doe.tld
COMMENT= Sample
RUN_DEPENDS= ${LUA_REFMODLIBDIR}/lpeg.so:devel/lua-lpeg@${LUA_FLAVOR}
USES= lua
.include <bsd.port.mk>Example 6.30. Makefile for a simple Lua
module
PORTNAME= sample
DISTVERSION= 1.2.3
CATEGORIES= whatever
PKGNAMEPREFIX= ${LUA_PKGNAMEPREFIX}
MAINTAINER= john@doe.tld
COMMENT= Sample
USES= lua:module
DOCSDIR= ${LUA_DOCSDIR}
.include <bsd.port.mk>After 2013-10-08 (254273),
FreeBSD 10-CURRENT and newer versions have a native
iconv in the operating system. On earlier
versions, converters/libiconv
was used as a dependency.
For software that needs iconv, define
USES=iconv. FreeBSD versions before
10-CURRENT on 2013-08-13 (254273) do
not have a native iconv. On these earlier
versions, a dependency on
converters/libiconv will be
added automatically.
When a port defines USES=iconv, these
variables will be available:
These two examples automatically populate the variables
with the correct value for systems using
converters/libiconv or the
native iconv respectively:
Example 6.31. Simple iconv Usage
USES= iconv
LDFLAGS+= -L${LOCALBASE}/lib ${ICONV_LIB}Example 6.32. iconv Usage with
configure
USES= iconv
CONFIGURE_ARGS+=${ICONV_CONFIGURE_ARG}As shown above, ICONV_LIB is empty when
a native iconv is present. This can be
used to detect the native iconv and respond
appropriately.
Sometimes a program has an ld argument
or search path hardcoded in a Makefile or
configure script. This approach can be used to solve that
problem:
Example 6.33. Fixing Hardcoded -liconv
USES= iconv
post-patch:
@${REINPLACE_CMD} -e 's/-liconv/${ICONV_LIB}/' ${WRKSRC}/MakefileIn some cases it is necessary to set alternate values or
perform operations depending on whether there is a native
iconv.
bsd.port.pre.mk must be included before
testing the value of ICONV_LIB:
Example 6.34. Checking for Native iconv
Availability
USES= iconv
.include <bsd.port.pre.mk>
post-patch:
.if empty(ICONV_LIB)
# native iconv detected
@${REINPLACE_CMD} -e 's|iconv||' ${WRKSRC}/Config.sh
.endif
.include <bsd.port.post.mk>Ports that need Xfce libraries or
applications set USES=xfce.
Specific Xfce library and
application dependencies are set with values assigned to
USE_XFCE. They are defined in
/usr/ports/Mk/Uses/xfce.mk. The possible
values are:
Example 6.35. USES=xfce Example
USES= xfce
USE_XFCE= libmenu
Example 6.36. Using Xfce's Own GTK2 Widgets
In this example, the ported application uses the
GTK2-specific widgets x11/libxfce4menu and x11/xfce4-conf.
USES= xfce:gtk2
USE_XFCE= libmenu xfconf
Tip:
Xfce components included this
way will automatically include any dependencies they need. It
is no longer necessary to specify the entire list. If the
port only needs x11-wm/xfce4-panel, use:
USES= xfce
USE_XFCE= panel
There is no need to list the components x11-wm/xfce4-panel needs itself like
this:
USES= xfce
USE_XFCE= libexo libmenu libutil panel
However, Xfce components and
non-Xfce dependencies of the port
must be included explicitly. Do not count on an
Xfce component to provide a
sub-dependency other than itself for the main port.
Use one of the USES macros from
Table 6.41, “Database USES Macros” to add a dependency
on a database.
Table 6.41. Database USES Macros
Example 6.38. Using MySQL
When a port needs the MySQL
client library add
USES= mysql
See Section 17.58, “mysql” for more
information.
Example 6.39. Using PostgreSQL
When a port needs the
PostgreSQL server version 9.6
or later add
USES= pgsql:9.6+
WANT_PGSQL= server
See Section 17.68, “pgsql” for more
information.
6.26. Starting and Stopping Services (rc
Scripts)
rc.d scripts are used to start
services on system startup, and to give administrators a
standard way of stopping, starting and restarting the service.
Ports integrate into the system rc.d
framework. Details on its usage can be found in the
rc.d Handbook chapter. Detailed explanation of
the available commands is provided in rc(8) and
rc.subr(8). Finally, there is
an
article on practical aspects of
rc.d scripting.
With a mythical port called
doorman, which needs to start a
doormand daemon. Add the following
to the Makefile:
USE_RC_SUBR= doormand
Multiple scripts may be listed and will be installed.
Scripts must be placed in the files
subdirectory and a .in suffix must be added
to their filename. Standard SUB_LIST
expansions will be ran against this file. Use of the
%%PREFIX%% and
%%LOCALBASE%% expansions is strongly
encouraged as well. More on SUB_LIST in
the relevant
section.
As of FreeBSD 6.1-RELEASE, local
rc.d scripts (including those installed
by ports) are included in the overall rcorder(8) of the
base system.
An example simple rc.d script to start
the doormand daemon:
#!/bin/sh
# $FreeBSD$
#
# PROVIDE: doormand
# REQUIRE: LOGIN
# KEYWORD: shutdown
#
# Add these 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 doormand.
# 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"
Unless there is a very good reason to start the service
earlier, or it runs as a particular user (other than root), all
ports scripts must use:
REQUIRE: LOGIN
If the startup script launches a daemon that must be
shutdown, the following will trigger a stop of the service on
system shutdown:
KEYWORD: shutdown
If the script is not starting a persistent service this is
not necessary.
For optional configuration elements the "="
style of default variable assignment is preferable to the
":=" style here, since the former sets a default
value only if the variable is unset, and the latter sets one
if the variable is unset or null. A user
might very well include something like:
doormand_flags=""
in their rc.conf.local, and a
variable substitution using ":=" would
inappropriately override the user's intention. The
_enable variable is not optional,
and must use the ":" for the default.
6.26.1. Pre-Commit Checklist
Before contributing a port with an
rc.d script, and more importantly,
before committing one, please consult this
checklist to be sure that it is ready.
The devel/rclint
port can check for most of these, but it is not a
substitute for proper review.
If this is a new file, does it have a
.sh extension? If so, that must be
changed to just
file.inrc.d files may not end with
that extension.
Does the file have a
$FreeBSD$ tag?
Do the name of the file (minus
.in), the
PROVIDE line, and
$name
all match? The file name matching
PROVIDE makes debugging easier,
especially for rcorder(8) issues. Matching the
file name and
$name
makes it easier to figure out which variables are
relevant in rc.conf[.local]. It is
also a policy
for all new scripts, including those in the base
system.
Is the REQUIRE line set to
LOGIN? This is mandatory for scripts
that run as a non-root user. If it runs as root, is
there a good reason for it to run prior to
LOGIN? If not, it must run after
so that local scrips can be loosely grouped to a point in
rcorder(8) after most everything in the base is
already running.
Does the script start a persistent service? If so,
it must have KEYWORD:
shutdown.
Make sure there is no
KEYWORD: FreeBSD present. This has
not been necessary nor desirable for years. It is also
an indication that the new script was copy/pasted from
an old script, so extra caution must be given to the
review.
If the script uses an interpreted language like
perl, python, or
ruby, make certain that
command_interpreter is set
appropriately, for example, for
Perl, by adding
PERL=${PERL} to
SUB_LIST and using
%%PERL%%. Otherwise,
# service name stop
will probably not work properly. See
service(8) for more information.
Have all occurrences of
/usr/local been replaced with
%%PREFIX%%?
Do the default variable assignments come after
load_rc_config?
Are there default assignments to empty strings?
They should be removed, but double-check that the option
is documented in the comments at the top of the
file.
Are things that are set in variables actually used
in the script?
Are options listed in the default
name_flags
things that are actually mandatory? If so, they must
be in command_args.
-d is a red flag (pardon the
pun) here, since it is usually the option to
“daemonize” the process, and therefore is
actually mandatory.
name_flagscommand_args (and vice versa,
although that error is less common).
Does the script execute any code unconditionally?
This is frowned on. Usually these things must be
dealt with through a
start_precmd.
All boolean tests must use the
checkyesno function. No
hand-rolled tests for [Yy][Ee][Ss],
etc.
If there is a loop (for example, waiting for
something to start) does it have a counter to terminate
the loop? We do not want the boot to be stuck forever
if there is an error.
Does the script create files or directories that
need specific permissions, for example, a
pid that needs to be owned by
the user that runs the process? Rather than the
traditional touch(1)/chown(8)/chmod(1)
routine, consider using install(1) with the proper
command line arguments to do the whole procedure with
one step.
6.27. Adding Users and Groups
Some ports require a particular user account to be present,
usually for daemons that run as that user. For these ports,
choose a unique UID from 50 to 999 and
register it in ports/UIDs (for users) and
ports/GIDs (for groups). The unique
identification should be the same for users and groups.
Please include a patch against these two files when
requiring a new user or group to be created for the
port.
Then use USERS and
GROUPS in
Makefile, and the user will be
automatically created when installing the port.
USERS= pulse
GROUPS= pulse pulse-access pulse-rt
The current list of reserved UIDs and GIDs can be found
in ports/UIDs and
ports/GIDs.
6.28. Ports That Rely on Kernel Sources
Some ports (such as kernel loadable modules) need the
kernel source files so that the port can compile. Here is the
correct way to determine if the user has them
installed:
USES= kmod
Apart from this check, the kmod feature
takes care of most items that these ports need to take into
account.
Ports must not package or install Go libs or source code.
Go ports must fetch the required deps at the normal fetch time
and should only install the programs and things users need, not
the things Go developers would need.
Ports should (in order of preference):
Use vendored dependencies included with the package
source.
Fetch the versions of deps specified by upstream (in the
case of go.mod, vendor.json or similar).
As a last resort (deps are not included nor versions
specified exactly) fetch versions of dependencies available
at the time of upstream development/release.
Just like in case of Go language, Ports must not package or
install Haskell libraries. Haskell ports must link statically
to their dependencies and fetch all distribution files on
fetch stage.
6.31. Shell Completion Files
Many modern shells (including bash, tcsh, and zsh) support
parameter and/or option tab-completion. This support usually
comes from completion files, which contain the definitions for
how tab completion will work for a certain command. Ports
sometimes ship with their own completion files, or porters may
have created them themselves.
When available, completion files should always be
installed. It is not necessary to make an option for it.
If an option is used, though, always enable it in
OPTIONS_DEFAULT.
Table 6.42. Shell completion file paths
bash | ${PREFIX}/etc/bash_completion.d |
zsh | ${PREFIX}/share/zsh/site-functions |
Do not register any dependencies on the shells
themselves.
Chapter 11. Upgrading a Port
When a port is not the most recent version available from the
authors, update the local working copy of
/usr/ports. The port might have already been
updated to the new version.
When working with more than a few ports, it will probably be
easier to use Subversion to keep
the whole ports collection up-to-date, as described in the Handbook.
This will have the added benefit of tracking all the port's
dependencies.
The next step is to see if there is an update already pending.
To do this, there are two options. There is a searchable
interface to the FreeBSD Problem
Report (PR) or bug database. Select Ports &
Packages in the Product multiple
select menu, and
enter the name of the port in the Summary
field.
However, sometimes people forget to put the name of the port
into the Summary field in an unambiguous fashion. In that
case, try searching in the Comment field in
the Detailled Bug Information section, or try
the
FreeBSD Ports Monitoring System
(also known as portsmon). This system
attempts to classify port PRs by portname. To search for PRs
about a particular port, use the Overview
of One Port.
If there is no pending PR, the next step is to send an email
to the port's maintainer, as shown by
make maintainer. That person may already be
working on an upgrade, or have a reason to not upgrade the port
right now (because of, for example, stability problems of the
new version), and there is no need to duplicate their work. Note
that unmaintained ports are listed with a maintainer of
ports@FreeBSD.org, which is just the general
ports mailing list, so sending mail there probably will not help
in this case.
If the maintainer asks you to do the upgrade or there is
no maintainer, then help out FreeBSD by
preparing the update! Please do this by using the
diff(1) command in the base system.
To create a suitable diff for a single
patch, copy the file that needs patching to
something.origsomething
Otherwise, either use the
svn diff method (Section 11.1, “Using Subversion to Make
Patches”)
or copy the contents of the port to an entire different
directory and use the result of the recursive diff(1)
output of the new and old ports directories (for example, if the
modified port directory is called superedit
and the original is in our tree as
superedit.bak, then save the result of
diff -ruN superedit.bak superedit). Either
unified or context diff is fine, but port committers generally
prefer unified diffs. Note the use of the -N
option—this is the accepted way to force diff to properly
deal with the case of new files being added or old files being
deleted. Before sending us the diff, please examine the output
to make sure all the changes make sense. (In particular, make
sure to first clean out the work directories with
make clean).
Note:
If some files have been added, copied, moved, or removed,
add this information to the problem report so that the committer
picking up the patch will know what svn(1) commands to
run.
To simplify common operations with patch files, use
make makepatch as described in Section 4.4, “Patching”.
Other tools exists, like
/usr/ports/Tools/scripts/patchtool.py.
Before using it, please read
/usr/ports/Tools/scripts/README.patchtool.
If the port is unmaintained, and you are actively using
it, please consider volunteering to become its
maintainer. FreeBSD has over 4000 ports without maintainers, and
this is an area where more volunteers are always needed. (For a
detailed description of the responsibilities of maintainers,
refer to the section in the Developer's
Handbook.)
To submit the diff, use the bug submit
form (product Ports & Packages,
component Individual Port(s)).
Always include the category
with the port name, followed by colon, and brief descripton of the
issue. Examples:
category/portname:
add FOO option
category/portname:
Update to X.Y.
Please mention any added or
deleted files in the message, as they have to be explicitly
specified to svn(1) when doing a commit. Do not compress or
encode the diff.
Before submitting the bug, review the
Writing the problem report section in the Problem
Reports article. It contains far more information about how to
write useful problem reports.
Important:
If the upgrade is motivated by security concerns or a
serious fault in the currently committed port, please notify
the Ports Management Team <portmgr@FreeBSD.org> to request immediate rebuilding and
redistribution of the port's package. Unsuspecting users
of pkg will otherwise continue to install
the old version via pkg install for several
weeks.
Note:
Please use diff(1) or svn diff to
create updates to existing ports. Other formats include the
whole file and make it impossible to see just what has changed.
When diffs are not included, the entire update might be
ignored.
Now that all of that is done, read about
how to keep up-to-date in Chapter 16, Keeping Up.
11.1. Using Subversion to Make
Patches
When possible, please submit a svn(1) diff. They
are easier to handle than diffs between
“new and old” directories. It is easier
to see what has changed, and to update the diff if
something was modified in the Ports Collection since the
work on it began, or if the
committer asks for something to be fixed. Also, a patch
generated with svn diff can be easily applied
with svn patch and will save some time to the
committer.
% cd ~/my_wrkdir 
% svn co https://svn.FreeBSD.org/ports/head/dns/pdnsd 
% cd ~/my_wrkdir/pdnsd
| This can be anywhere, of course. Building
ports is not limited to within
/usr/ports/. |
| svn.FreeBSD.org
is the FreeBSD public Subversion
server. See Subversion
mirror sites for more information. |
While in the port directory, make any changes that are
needed. If adding, copying, moving, or removing a
file, use svn to track these changes:
% svn add new_file
% svn copy some_file file_copy
% svn move old_name new_name
% svn remove deleted_file
Make sure to check the port using the checklist in
Section 3.4, “Testing the Port” and
Section 3.5, “Checking the Port with
portlint”.
% svn status
% svn update This will attempt to merge the differences between the
patch and current repository version. Watch the output
carefully. The letter in front of each file name
indicates what was done with it. See
Table 11.1, “Subversion Update File
Prefixes” for a complete list. |
Table 11.1. Subversion Update File
Prefixes
| U | The file was updated without problems. |
| G | The file was updated without problems (only when
working against a remote
repository). |
| M | The file had been modified, and was merged
without conflicts. |
| C | The file had been modified, and was merged with
conflicts. |
If C is displayed as a result of
svn update, it means something changed in
the Subversion repository and
svn(1) was not able to merge the local changes with those
from the repository. It is always a good idea to inspect the
changes anyway, since svn(1) does not know anything about
the structure of a port, so it might (and probably will) merge
things that do not make sense.
The last step is to make a unified diff(1)
of the changes:
% svn diff > ../`make -VPKGNAME`.diff
Note:
If files have been added, copied, moved, or removed,
include the svn(1) add,
copy, move, and
remove commands that were used.
svn move or svn copy
must be run before the patch can be applied. svn
add or svn remove must be run
after the patch is applied.
Send the patch following the problem
report submission guidelines.
Chapter 13. Dos and Don'ts
Here is a list of common dos and don'ts that are encountered
during the porting process. Check the port against this list,
but also check ports in the PR
database that others have submitted. Submit any
comments on ports as described in Bug
Reports and General Commentary. Checking ports in the
PR database will both make it faster for us to commit them, and
prove that you know what you are doing.
Do not write anything to files outside
WRKDIR. WRKDIR is the
only place that is guaranteed to be writable during the port
build (see
installing ports from a CDROM for an example of
building ports from a read-only tree). The
pkg-* files can
be modified by redefining a
variable rather than overwriting the file.
Make sure the port honors WRKDIRPREFIX.
Most ports do not have to worry about this. In particular, when
referring to a WRKDIR of another
port, note that the correct location is
WRKDIRPREFIXPORTSDIR/subdir/name/work
not
PORTSDIR/subdir/name/work
or
.CURDIR/../../subdir/name/work
or some such.
Also, if defining WRKDIR,
make sure to prepend
${WRKDIRPREFIX}${.CURDIR} in
the front.
13.4. Differentiating Operating Systems and OS Versions
Some code needs modifications or
conditional compilation based upon what version of FreeBSD Unix it
is running under. The preferred way to tell FreeBSD versions apart
are the __FreeBSD_version and
__FreeBSD__ macros defined in sys/param.h.
If this file is not included add the code,
#include <sys/param.h>
to the proper place in the .c
file.
__FreeBSD__ is defined in all versions
of FreeBSD as their major version number. For example, in FreeBSD
9.x, __FreeBSD__ is defined to be
9.
#if __FreeBSD__ >= 9
# if __FreeBSD_version >= 901000
/* 9.1+ release specific code here */
# endif
#endif
A complete list of __FreeBSD_version
values is available in Chapter 18, __FreeBSD_version Values.
13.5. Writing Something After
bsd.port.mk
Do not write anything after the
.include <bsd.port.mk> line. It
usually can be avoided by including
bsd.port.pre.mk somewhere in the middle of
the Makefile and
bsd.port.post.mk at the end.
Important:
Include either the
bsd.port.pre.mk/bsd.port.post.mk
pair or bsd.port.mk only; do not mix
these two usages.
bsd.port.pre.mk only defines a few
variables, which can be used in tests in the
Makefile,
bsd.port.post.mk defines the rest.
Here are some important variables defined in
bsd.port.pre.mk (this is not the complete
list, please read bsd.port.mk for the
complete list).
Note:
When MASTERDIR is needed, always define
it before including
bsd.port.pre.mk.
Here are some examples of things that can be added after
bsd.port.pre.mk:
# no need to compile lang/perl5 if perl5 is already in system
.if ${OSVERSION} > 300003
BROKEN= perl is in system
.endifAlways use tab instead of spaces after
BROKEN=.
13.6. Use the exec Statement in Wrapper
Scripts
If the port installs a shell script whose purpose is to
launch another program, and if launching that program is the
last action performed by the script, make sure to launch the
program using the exec statement, for
instance:
#!/bin/sh
exec %%LOCALBASE%%/bin/java -jar %%DATADIR%%/foo.jar "$@"
The exec statement replaces the shell
process with the specified program. If
exec is omitted, the shell process remains
in memory while the program is executing, and needlessly
consumes system resources.
13.7. Do Things Rationally
The Makefile should do things in a
simple and reasonable manner. Making it a couple of lines
shorter or more readable is always better. Examples include
using a make .if construct instead of a shell
if construct, not redefining
do-extract if redefining
EXTRACT* is enough, and using
GNU_CONFIGURE instead of
CONFIGURE_ARGS
+= --prefix=${PREFIX}.
If a lot of new code is needed to do something, there may
already be an implementation of it in
bsd.port.mk. While hard to read, there are
a great many seemingly-hard problems for which
bsd.port.mk already provides a shorthand
solution.
13.8. Respect Both CC and
CXX
The port must respect both CC and
CXX. What we mean by this is that
the port must not set the values of these variables absolutely,
overriding existing values; instead, it may append whatever
values it needs to the existing values. This is so that build
options that affect all ports can be set globally.
If the port does not respect these variables,
please add
NO_PACKAGE=ignores either cc or cxx to the
Makefile.
Here is an example of a Makefile
respecting both CC and
CXX. Note the ?=:
CC?= gcc
CXX?= g++
Here is an example which respects neither
CC nor CXX:
CC= gcc
CXX= g++
Both CC and CXX
can be defined on FreeBSD systems in
/etc/make.conf. The first example defines
a value if it was not previously set in
/etc/make.conf, preserving any system-wide
definitions. The second example clobbers anything previously
defined.
The port must respect CFLAGS.
What we mean by this is that the port must not set
the value of this variable absolutely, overriding the existing
value. Instead, it may append whatever values it needs to the
existing value. This is so that build options that affect all
ports can be set globally.
If it does not, please add
NO_PACKAGE=ignores cflags to the
Makefile.
Here is an example of a Makefile
respecting CFLAGS. Note the
+=:
CFLAGS+= -Wall -Werror
Here is an example which does not respect
CFLAGS:
CFLAGS= -Wall -Werror
CFLAGS is defined on
FreeBSD systems in /etc/make.conf. The first
example appends additional flags to
CFLAGS, preserving any system-wide
definitions. The second example clobbers anything previously
defined.
Remove optimization flags from the third party
Makefiles. The system
CFLAGS contains system-wide optimization
flags. An example from an unmodified
Makefile:
CFLAGS= -O3 -funroll-loops -DHAVE_SOUND
Using system optimization flags, the
Makefile would look similar to this
example:
CFLAGS+= -DHAVE_SOUND
13.10. Verbose Build Logs
Make the port build system display all commands executed
during the build stage. Complete build logs are crucial to
debugging port problems.
Non-informative build log example (bad):
CC source1.o
CC source2.o
CCLD someprogram
Verbose build log example (good):
cc -O2 -pipe -I/usr/local/include -c -o source1.o source1.c
cc -O2 -pipe -I/usr/local/include -c -o source2.o source2.c
cc -o someprogram source1.o source2.o -L/usr/local/lib -lsomelib
Some build systems such as CMake,
ninja, and GNU
configure are set up for verbose logging by
the ports framework. In other cases, ports might need
individual tweaks.
Do send applicable changes and patches to the upstream
maintainer for inclusion in the next release of the code.
This makes updating to the next release that much easier.
README.html is not part of the port,
but generated by make readme. Do not
include this file in patches or commits.
Note:
If make readme fails, make sure that
the default value of ECHO_MSG has not
been modified by the port.
13.13. Marking a Port Not Installable with
BROKEN, FORBIDDEN, or
IGNORE
In certain cases, users must be prevented from installing
a port. There are several variables that can be used in a
port's Makefile to tell the user that the
port cannot be installed. The value of
these make variables will be the
reason that is shown to users for why the port refuses to
install itself. Please use the correct make
variable. Each variable conveys radically different
meanings, both to users and to automated systems that depend on
Makefiles, such as
the ports build cluster,
FreshPorts, and
portsmon.
BROKEN is reserved for ports that
currently do not compile, install, deinstall, or run
correctly. Use it for ports where the problem
is believed to be temporary.
If instructed, the build cluster will still attempt
to try to build them to see if the underlying problem has
been resolved. (However, in general, the cluster is run
without this.)
For instance, use BROKEN when a
port:
does not compile
fails its configuration or installation
process
installs files outside of
${PREFIX}
does not remove all its files cleanly upon
deinstall (however, it may be acceptable, and
desirable, for the port to leave user-modified files
behind)
has runtime issues on systems where it is
supposed to run fine.
FORBIDDEN is used for ports that
contain a security vulnerability or induce grave concern
regarding the security of a FreeBSD system with a given port
installed (for example, a reputably insecure program or a
program that provides easily exploitable services). Mark
ports as FORBIDDEN as soon as a
particular piece of software has a vulnerability and there
is no released upgrade. Ideally upgrade ports as soon as
possible when a security vulnerability is discovered so as
to reduce the number of vulnerable FreeBSD hosts (we like
being known for being secure), however sometimes there is
a noticeable time gap between disclosure of a
vulnerability and an updated release of the vulnerable
software. Do not mark a port FORBIDDEN
for any reason other than security.
IGNORE is reserved for ports that
must not be built for some other reason. Use it
for ports where the problem is believed to be
structural. The build cluster will not, under any
circumstances, build ports marked as
IGNORE. For instance, use
IGNORE when a port:
does not work on the installed version of
FreeBSD
has a distfile which may not be automatically
fetched due to licensing restrictions
does not work with some other currently
installed port (for instance, the port depends on
www/apache20 but
www/apache22 is
installed)
Note:
If a port would conflict with a currently
installed port (for example, if they install a file in
the same place that performs a different function),
use
CONFLICTS instead.
CONFLICTS will set
IGNORE by itself.
13.13.2. Implementation Notes
Do not quote the values of BROKEN,
IGNORE, and related variables. Due to the
way the information is shown to the user, the wording of
messages for each variable differ:
BROKEN= fails to link with base -lcrypto
IGNORE= unsupported on recent versions
resulting in this output from
make describe:
===> foobar-0.1 is marked as broken: fails to link with base -lcrypto.
===> foobar-0.1 is unsupported on recent versions.
13.14. Architectural Considerations
13.14.1. General Notes on Architectures
FreeBSD runs on many more processor architectures than
just the well-known x86-based ones. Some ports have
constraints which are particular to one or more of these
architectures.
For the list of supported architectures, run:
cd ${SRCDIR}; make targetsThe values are shown in the form
TARGET/TARGET_ARCH.
The ports read-only makevar ARCH is set
based on the value of TARGET_ARCH.
Port Makefiles should test the value
of this Makevar.
13.14.2. Marking a Port as Architecture Neutral
Ports that do not have any architecture-dependent files
or requirements are identified by setting
NO_ARCH=yes.
Note:
NO_ARCH is meant to indicate
that there is no need to build a package for each of the
supported architectures. The goal is to reduce the amount
of resources spent on building and distributing the packages
such as network bandwidth and disk space on mirrors
and on distribution media. Currently, however,
our package infrastructure (e.g., package managers, mirrors,
and package builders) is not set up to fully benefit from
NO_ARCH.
13.14.3. Marking a Port as Ignored Only On Certain Architectures
To mark a port as IGNOREd
only on certain architectures, there are two other
convenience variables that will automatically set
IGNORE:
ONLY_FOR_ARCHS and
NOT_FOR_ARCHS. Examples:
ONLY_FOR_ARCHS= i386 amd64
NOT_FOR_ARCHS= ia64 sparc64
A custom IGNORE message can be
set using ONLY_FOR_ARCHS_REASON and
NOT_FOR_ARCHS_REASON. Per
architecture entries are possible with
ONLY_FOR_ARCHS_REASON_ARCH
and
NOT_FOR_ARCHS_REASON_ARCH.
If a port fetches i386 binaries and installs them,
set IA32_BINARY_PORT. If this variable
is set, /usr/lib32 must be present
for IA32 versions of libraries and the kernel must support
IA32 compatibility. If one of these two
dependencies is not satisfied, IGNORE
will be set automatically.
13.14.5. Cluster-Specific Considerations
Some ports attempt to tune themselves to the
exact machine they are being built on by specifying
-march=native to the compiler.
This should be avoided: either list it under an
off-by-default option, or delete it entirely.
Otherwise, the default package produced by the
build cluster might not run on every single machine
of that ARCH.
13.15. Marking a Port for Removal with
DEPRECATED or
EXPIRATION_DATE
Do remember that BROKEN and
FORBIDDEN are to be used as a temporary
resort if a port is not working. Permanently broken ports
will be removed from the tree entirely.
When it makes sense to do so, users can be warned about
a pending port removal with DEPRECATED and
EXPIRATION_DATE. The former is a
string stating why the port is scheduled for removal; the latter
is a string in ISO 8601 format (YYYY-MM-DD). Both will be shown
to the user.
It is possible to set DEPRECATED
without an EXPIRATION_DATE (for instance,
recommending a newer version of the port), but the converse
does not make any sense.
There is no set policy on how much notice to give.
Current practice seems to be one month for security-related
issues and two months for build issues. This also gives any
interested committers a little time to fix the problems.
13.16. Avoid Use of the .error
Construct
The correct way for a Makefile to
signal that the port cannot be installed due to some external
factor (for instance, the user has specified an illegal
combination of build options) is to set a non-blank value to
IGNORE. This value will be formatted and
shown to the user by make install.
It is a common mistake to use .error
for this purpose. The problem with this is that many automated
tools that work with the ports tree will fail in this situation.
The most common occurrence of this is seen when trying to build
/usr/ports/INDEX (see
Section 10.1, “Running make describe”). However, even more trivial
commands such as make maintainer also fail in
this scenario. This is not acceptable.
Example 13.1. How to Avoid Using .error
The first of the
next two Makefile snippets will cause
make index to fail, while the second one
will not:
.error "option is not supported"
IGNORE=option is not supported
The usage of sysctl is discouraged
except in targets. This is because the evaluation of any
makevars, such as used during
make index, then has to run the command,
further slowing down that process.
Only use sysctl(8) through
SYSCTL, as it contains the fully
qualified path and can be overridden, if one has such a
special need.
13.18. Rerolling Distfiles
Sometimes the authors of software change the content of
released distfiles without changing the file's name.
Verify that the changes are official and have been performed
by the author. It has happened in the past that the distfile
was silently altered on the download servers with the intent to
cause harm or compromise end user security.
Put the old distfile aside, download the new one, unpack
them and compare the content with diff(1). If there is
nothing suspicious, update
distinfo.
Important:
Be sure to summarize the differences in the PR and commit
log, so that other people know that nothing bad has
happened.
Contact the authors of the software
and confirm the changes with them.
13.19. Use POSIX Standards
FreeBSD ports generally expect POSIX
compliance. Some software and build systems make assumptions
based on a particular operating system or environment that can
cause problems when used in a port.
Do not use /proc if there are any
other ways of getting the information. For example,
setprogname(argv[0]) in
main() and then getprogname(3)
to know the executable name.
Do not rely on behavior that is undocumented by
POSIX.
Do not record timestamps in the critical path of the
application if it also works without. Getting timestamps may be
slow, depending on the accuracy of timestamps in the
OS. If timestamps are really needed,
determine how precise they have to be and use an
API which is documented to just deliver the
needed precision.
A number of simple syscalls (for example
gettimeofday(2), getpid(2)) are much faster on Linux®
than on any other operating system due to caching and the
vsyscall performance optimizations. Do not rely on them being
cheap in performance-critical applications. In general, try
hard to avoid syscalls if possible.
Do not rely on Linux®-specific socket behavior. In
particular, default socket buffer sizes are different (call
setsockopt(2) with SO_SNDBUF and
SO_RCVBUF, and while Linux®'s send(2)
blocks when the socket buffer is full, FreeBSD's will fail and
set ENOBUFS in errno.
If relying on non-standard behavior is required,
encapsulate it properly into a generic API,
do a check for the behavior in the configure stage, and stop
if it is missing.
Check the
man
pages to see if the function used is a
POSIX interface (in the
“STANDARDS” section of the man page).
Do not assume that /bin/sh is
bash. Ensure that a command line
passed to system(3) will work with a
POSIX compliant shell.
A list of common bashisms is
available here.
Check that headers are included in the
POSIX or man page recommended way. For
example, sys/types.h is often forgotten,
which is not as much of a problem for Linux® as it is for
FreeBSD.
Always double-check pkg-descr and
pkg-plist.
If reviewing a port and a better wording can be achieved,
do so.
Do not copy more copies of the GNU General Public License
into our system, please.
Please be careful to note any legal issues! Do not let us
illegally distribute software!
Chapter 17. Using USES Macros
17.1. An Introduction to USES
USES macros make it easy to declare
requirements and settings for a port. They can add
dependencies, change building behavior, add metadata to
packages, and so on, all by selecting simple, preset
values.
Each section in this chapter describes a possible value for
USES, along with its possible arguments.
Arguments are appeneded to the value after a colon
(:). Multiple arguments are separated by
commas (,).
Example 17.1. Using Multiple Values
Example 17.2. Adding an Argument
Example 17.3. Adding Multiple Arguments
Example 17.4. Mixing it All Together
USES= pgsql:9.3+ cpe python:2.7,build
Possible arguments: (none), p7zip,
partial
Extract using 7z(1) instead of bsdtar(1) and sets
EXTRACT_SUFX=.7z. The
p7zip option forces a dependency on the
7z from archivers/p7zip if the one from the base
system is not able to extract the files.
EXTRACT_SUFX is not changed if the
partial option is used, this can be used if
the main distribution file does not have a
.7z extension.
Possible arguments: (none),
5,
6
Depends on an Ada-capable
compiler, and sets CC accordingly. Defaults
to use gcc 5 from ports. Use the
:X version option
to force building with a different version.
Possible arguments: (none), build
Runs autoreconf. It encapsulates the
aclocal, autoconf,
autoheader, automake,
autopoint, and libtoolize
commands. Each command applies to
${AUTORECONF_WRKSRC}/configure.ac or its
old name,
${AUTORECONF_WRKSRC}/configure.in. If
configure.ac defines subdirectories with
their own configure.ac using
AC_CONFIG_SUBDIRS,
autoreconf will recursively update those as
well. The :build argument only adds build
time dependencies on those tools but does not run
autoreconf. A port can set
AUTORECONF_WRKSRC if
WRKSRC does not contain the path to
configure.ac.
Possible arguments: (none), atlas,
netlib (default),
gotoblas, openblas
Adds dependencies on Blas / Lapack libraries.
Possible arguments: (none), 48,
5 (default), 6
Add dependency on the Berkeley DB
library. Default to databases/db5. It can also depend on
databases/db48 when using the
:48 argument or databases/db6 with
:6. It is possible to declare a range of
acceptable values, :48+ finds the highest
installed version, and falls back to 4.8 if nothing else is
installed. INVALID_BDB_VER can be used to
specify versions which do not work with this port. The
framework exposes the following variables to the port:
BDB_LIB_NAMEThe name of the Berkeley DB
library. For example, when using databases/db5, it contains
db-5.3.
BDB_LIB_CXX_NAMEThe name of the Berkeley DB
C++ library. For example, when
using databases/db5, it
contains db_cxx-5.3.
BDB_INCLUDE_DIRThe location of the Berkeley
DB include directory. For example, when
using databases/db5, it
will contain
${LOCALBASE}/include/db5.
BDB_LIB_DIRThe location of the Berkeley
DB library directory. For example, when
using databases/db5, it
contains ${LOCALBASE}/lib.
BDB_VERThe detected Berkeley DB
version. For example, if using
USES=bdb:48+ and Berkeley
DB 5 is installed, it contains
5.
Important:
databases/db48 is
deprecated and unsupported. It must not be used by any
port.
Possible arguments: (none), build,
run, both
Uses devel/bison By default,
with no arguments or with the build argument,
it implies bison is a build-time dependency,
run implies a run-time dependency, and
both implies both run-time and build-time
dependencies.
Possible arguments: (none), hpack
Sets default values and targets used to build
Haskell software using Cabal.
A build dependency on the Haskell compiler port (GHC)
is added. If hpack argument is given,
a build dependency on devel/hs-hpack
is added and hpack is invoked at
configuration step to generate .cabal file.
The framework provides the following variables:
USE_CABALIf the software uses Haskell dependencies, list them in
this variable. Each item should be present on Hackage and
be listed in form packagename-0.1.2.
Dependencies can have revisions, which are specified after the
_ symbol. Automatic generation of dependency
list is supported, see Section 6.5.9, “Building Haskell
Applications with cabal”.
CABAL_FLAGSList of flags to be passed to cabal-install
during the configuring and building stage. The flags are
passed verbatim.
EXECUTABLESList of executable files installed by the port.
Default value: ${PORTNAME}.
Items from this list are automatically added to pkg-plist.
SKIP_CABAL_PLISTIf defined, do not add items from
${EXECUTABLES} to pkg-plist.
opt_USE_CABALAdds items to ${USE_CABAL}
depending on opt option.
opt_EXECUTABLESAdds items to ${EXECUTABLES}
depending on opt option.
opt_CABAL_FLAGSIf opt is enabled, append the value
to ${CABAL_FLAGS}. Otherwise, append
-value to disable the flag.
FOO_DATADIR_VARSFor an executable named FOO
list Haskell packages, whose data files
should be accessible by the executable.
Possible arguments: (none)
Prevents the port from installing
charset.alias. This must be installed only
by converters/libiconv.
CHARSETFIX_MAKEFILEIN can be set to a path
relative to WRKSRC if
charset.alias is not installed by
${WRKSRC}/Makefile.in.
Possible arguments: (none), insource,
noninja, run
Uses CMake for configuring and
building.
By default an out-of-source build is performed, leaving the
sources in WRKSRC free from build artifacts.
With the insource argument, an in-source
build will be performed instead. Setting it should be the
exception when a regular out-of-source build does not
work.
By default Ninja is used for
the build. In some cases this does not work correctly. With
the noninja argument, the build will
fallback to using regular make for builds.
It should only be used if a
Ninja-based build does not
work.
With the run argument, a run dependency
is registered in addition to a build dependency.
For more information see Section 6.5.4, “Using cmake”.
Possible arguments: (none), env
(default, implicit), c++17-lang,
c++14-lang,
c++11-lang, gcc-c++11-lib,
c++11-lib, c++0x,
c11, openmp,
nestedfct, features
Determines which compiler to use based on any given wishes.
Use c++17-lang if the port needs a
C++17-capable compiler,
c++14-lang if the port needs a
C++14-capable compiler, c++11-lang
if the port needs a C++11-capable compiler,
gcc-c++11-lib if the
port needs the g++ compiler with a C++11
library, or c++11-lib if the port needs
a C++11-ready standard library. If the port needs a compiler
understanding C++0X, C11, OpenMP, or nested functions,
the corresponding parameters should be used.
Use
features to request a list of features
supported by the default compiler. After including
bsd.port.pre.mk the port can inspect the
results using these variables:
COMPILER_TYPE: the default compiler
on the system, either gcc or clang
ALT_COMPILER_TYPE: the alternative
compiler on the system, either gcc or clang. Only set if
two compilers are present in the base system.
COMPILER_VERSION: the first two
digits of the version of the default compiler.
ALT_COMPILER_VERSION: the first two
digits of the version of the alternative compiler, if
present.
CHOSEN_COMPILER_TYPE: the chosen
compiler, either gcc or clang
COMPILER_FEATURES: the features
supported by the default compiler. It currently lists the
C++ library.
Possible arguments: (none)
Include Common Platform Enumeration
(CPE) information in package manifest as a
CPE 2.3 formatted string. See the CPE
specification for details. To add
CPE information to a port, follow these
steps:
Search for the official CPE entry for the software
product either by using the NVD's CPE
search engine or in the official
CPE dictionary (warning, very
large XML file). Do not ever
make up CPE data.
Add cpe to USES
and compare the result of make -V CPE_STR
to the CPE dictionary entry. Continue one
step at a time until make -V CPE_STR is
correct.
If the product name (second field, defaults to
PORTNAME) is incorrect, define
CPE_PRODUCT.
If the vendor name (first field, defaults to
CPE_PRODUCT) is incorrect, define
CPE_VENDOR.
If the version field (third field, defaults to
PORTVERSION) is incorrect, define
CPE_VERSION.
If the update field (fourth field, defaults to empty) is
incorrect, define CPE_UPDATE.
If it is still not correct, check
Mk/Uses/cpe.mk for additional details,
or contact the Ports Security Team <ports-secteam@FreeBSD.org>.
Derive as much as possible of the CPE
name from existing variables such as
PORTNAME and
PORTVERSION. Use variable modifiers to
extract the relevant portions from these variables rather
than hardcoding the name.
Always run make -V
CPE_STR and check the output before committing
anything that changes PORTNAME or
PORTVERSION or any other variable which
is used to derive CPE_STR.
Possible arguments: (none),
auto-plist,
compiles
Uses the Comprehensive R Archive Network. Specify
auto-plist to automatically generate
pkg-plist. Specify
compiles if the port has code that need to be
compiled.
17.15. desktop-file-utils
Possible arguments: (none)
Uses update-desktop-database from
devel/desktop-file-utils. An
extra post-install step will be run without interfering with any
post-install steps already in the port
Makefile. A line with @desktop-file-utils
will be added to the plist.
Possible arguments: (none)
Changes the behavior of GNU configure to properly support
DESTDIR in case the original software does
not.
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.
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 Section 4.4.3, “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}.
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.
Possible arguments: 2, 3, build (default), run
Add dependency on math/eigen.
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.
Possible arguments: (none), fam,
gamin
Uses a File Alteration Monitor as a library dependency,
either devel/fam or devel/gamin. End users can set
WITH_FAM_SYSTEM to specify their preference.
Possible arguments: (none), 25
Add a dependency to the client library of the Firebird
database.
Possible arguments: (none), fc,
fcfontsdir (default),
fontsdir, none
Adds a runtime dependency on tools needed to register fonts.
Depending on the argument, add a @fc ${FONTSDIR}
line, @fcfontsdir
${FONTSDIR} line, @fontsdir
${FONTSDIR} line, or no line if the argument is
none, to the plist.
FONTSDIR defaults to
${PREFIX}/share/fonts/${FONTNAME} and
FONTNAME to ${PORTNAME}.
Add FONTSDIR to PLIST_SUB
and SUB_LIST
Possible arguments: gcc (default)
Uses the GNU Fortran compiler.
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.
Possible arguments: (none),
noautoplist
Handle building with RubyGems.
If noautoplist is used, the packing list is
not generated automatically.
Possible arguments: (none), lib
(default), build,
run
Uses devel/gettext-runtime.
By default, with no arguments or with the lib
argument, implies a library dependency on
libintl.so. build and
run implies, respectively a build-time and a
run-time dependency on gettext.
Possible arguments: (none), build
(default), run
Uses devel/gettext-tools. By
default, with no argument, or with the build
argument, a build time dependency on msgfmt
is registered. With the run argument, a
run-time dependency is registered.
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.
Possible arguments: (none)
Provides an easy way to depend on
GL components. The components
should be listed in USE_GL. The available
components are:
Possible arguments: (none)
Uses devel/gmake as a
build-time dependency and sets up the environment to use
gmake as the default make
for the build.
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:
USES= gnome
USE_GNOME= gnomemenus3:build intlhack
See Section 6.10, “Using GNOME” 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_PKGNAMEThe 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_TARGETThe 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_TESTTARGETThe packages to test. The default
value is ./... (the current package
and all subpackages).
CGO_CFLAGSAdditional CFLAGS values to be
passed to the C compiler by
go.
CGO_LDFLAGSAdditional LDFLAGS values to be
passed to the C compiler by
go.
GO_BUILDFLAGSAdditional build arguments to be passed to
go build.
GO_TESTFLAGSAdditional build arguments to be passed to
go test.
GO_PORTThe Go compiler port to use. By default this is
lang/go but can be set
to lang/go-devel in
make.conf for testing with future Go
versions.
Warning:
This variable must not be set by individual
ports!
See Section 6.5.8, “Building Go
Applications” for usage examples.
Possible arguments: (none)
Add a buildtime dependency on devel/gperf if gperf
is not present in the base system.
Possible arguments: 5,
selfbuild
Handle dependency on Grantlee.
Specify 5 to depend on the
Qt5 based version, devel/grantlee5.
selfbuild is used internally by devel/grantlee5 to get their versions
numbers.
Possible arguments: build,
run, both
Registers a dependency on textproc/groff if not present in the
base system.
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 security/heimdal, or
mit to use 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 security/krb5 and
security/heimdal. For example,
use bootstrap,mit.
Example 17.5. Typical Use
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-gssapiPossible arguments: (none), lib,
build,
patch, translit,
wchar_t
Uses iconv functions, either from the
port converters/libiconv as a
build-time and run-time dependency, or from the base system on
10-CURRENT after a native iconv was committed
in 254273. 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 Section 6.23, “Using iconv”.
Possible arguments: (none), env,
notall, noman
Add 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.
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
/boot/modules by default, add it to
PLIST_SUB and
MAKE_ENV, and create it upon
installation. If KMODDIR is set to
/boot/kernel, it will be rewritten to
/boot/modules. This prevents breaking
packages when upgrading the kernel due to
/boot/kernel being renamed to
/boot/kernel.old in the process.
Handle cross-referencing kernel modules upon
installation and deinstallation, using @kld.
If the debug argument is given, the
port can install a debug version of the module into
KERN_DEBUGDIR/KMODDIR.
By default, KERN_DEBUGDIR is copied from
DEBUGDIR and set to
/usr/lib/debug. The framework will
take care of creating and removing any required
directories.
Possible arguments: (none)
Set EXTRACT_SUFX to
.lzh
Possible arguments: (none)
Registers a dependency on archivers/libarchive. Any ports
depending on libarchive must include
USES=libarchive.
Possible arguments: (none)
Registers a dependency on devel/libedit. Any ports depending on
libedit must include
USES=libedit.
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
.la files. Some ports do not ship with
their own copy of libtool and need a build time dependency on
devel/libtool, use the
:build argument to add such
dependency.
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
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.
Possible arguments: (none),
XYXY+-XY,
XY-ZAmodule, 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 Section 6.22, “Using Lua”.
Possible arguments: (none)
Handle dependencies for the LXQt Desktop
Environment. Use USE_LXQT to
select the components needed for the port. See Section 6.14, “Using LXQt” for more information.
Possible arguments: (none)
Add a build-time dependency on makeinfo
if it is not present in the base system.
Possible arguments: (none)
Indicates that the distribution files are makeself archives
and sets the appropriate dependencies.
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:
USES= mate
USE_MATE= menus:build intlhack
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.
Possible arguments: (none),
versionclient (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
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.
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=versionname=version:origin
The helper target, buildnuget,
will output the content of the NUGET_DEPENDS
based on the provided
packages.config.
Possible arguments: (none), base,
port
Uses ncurses, and causes some
useful variables to be set.
Possible arguments: (none)
Uses ninja to build the
port.
Possible arguments: (none)
Add objective C dependencies (compiler, runtime library) if
the base system does not support it.
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.
Possible arguments: (none)
Look for Makefile.in and
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 .pc files
to ${PREFIX}/libdata/pkgconfig. If
the port uses USES=autoreconf,
Makefile.am will be added to
PATHFIX_MAKEFILEIN automatically.
If the port USES=cmake it
will look for CMakeLists.txt in
PATHFIX_WRKSRC. If needed, that default
filename can be changed with
PATHFIX_CMAKELISTSTXT.
Possible arguments: env
Adds a dependency on 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
Section 6.16.4, “PEAR Modules” for more information.
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 Makefile.PL,
Build.PL, or
Module::Build::Tiny's flavor of
Build.PL is required.
USE_PERL5 defaults to build
run. When using configure,
modbuild, or modbuildtiny,
build and run are
implied.
See Section 6.8, “Using Perl” for more
information.
Possible arguments: (none),
X.YX.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
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, lang/php56.
phpizeUse to build a PHP
extension. Enables flavors.
extUse to build, install and register a
PHP extension. Enables
flavors.
zendUse to build, install and register a Zend
extension. Enables flavors.
buildSet PHP also as a
build-time dependency.
cliNeeds the CLI version of
PHP.
cgiNeeds the CGI version of
PHP.
modNeeds the Apache module for
PHP.
webNeeds the Apache module or
the CGI version of
PHP.
embedNeeds the embedded library version of
PHP.
peclProvide defaults for fetching
PHP extensions from the PECL
repository. Enables flavors.
flavorsEnable automatic PHP
flavors generation. Flavors will be generated
for all PHP versions, except the ones present in
IGNORE_WITH_PHP.
noflavorsDisable 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_PHPThe 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
IGNORE_WITH_PHPThe port does not work with
PHP of the given version. For
possible values look at the content of
_ALL_PHP_VERSIONS in
Mk/Uses/php.mk.
When building a PHP or
Zend extension with
:ext or :zend, these
variables can be set:
PHP_MODNAMEThe name of the PHP or
Zend extension. Default value
is ${PORTNAME}.
PHP_HEADER_DIRSA 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_PRIOThe 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 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:
USES= php:ext
USE_PHP= wddx
PHP_MOD_PRIO= 40
These variables are available to use in
PKGNAMEPREFIX or
PKGNAMESUFFIX:
PHP_PKGNAMEPREFIXContains
phpXY- where
XY is the current flavor's PHP
version. Use with PHP extensions and modules.
PHP_PKGNAMESUFFIXContains
-phpXY where
XY is the current flavor's PHP
version. Use with PHP applications.
PECL_PKGNAMEPREFIXContains
phpXY-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.
Possible arguments: (none), build
(default), run,
both
Uses 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.
Possible arguments: (none), ffi
Uses lang/pure. Largely used
for building related pure ports.
With the ffi argument, it implies devel/pure-ffi as a run-time
dependency.
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:
USES= pyqt
USE_PYQT= core doc_build designer_run
Possible arguments: (none),
X.YX.Y+-X.YX.Y-Z.Apatch,
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
Section 6.17, “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 USES=shebangfix,
and the goal is only to fix the shebangs but not add a
dependency on Python.
Possible arguments: (none), build,
run, both,
vars
Uses 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.
Possible arguments: (none), norecursive,
outsource, no_env,
no_configure
Uses QMake for configuring. For
more information see Section 6.12.3, “Using qmake”.
Possible arguments: 5,
no_env
Add dependency on Qt components.
no_env is passed directly to
USES= qmake. See Section 6.12, “Using Qt”
for more information.
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.
Example 17.6. Building Qt 5 Components
The port is Qt 5's
networkauth component, which is part of
the networkauth distribution file.
PORTNAME= networkauth
DISTVERSION= ${QT5_VERSION}
USES= qt-dist:5If PORTNAME does not match the
component name, it can be passed as an argument to
qt-dist.
Example 17.7. Building Qt 5 Components with Different Names
The port is Qt 5's
gui component, which is part of the
base distribution file.
PORTNAME= gui
DISTVERSION= ${QT5_VERSION}
USES= qt-dist:5,basePossible 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 devel/readline
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 smbd. lib
will add a dependency on libsmbclient.so.
The variables that are exported are:
SAMBAPORTThe origin of the default
Samba port.
SAMBAINCLUDESThe location of the Samba
header files.
SAMBALIBSThe directory where the
Samba shared libraries are
available.
Possible arguments: (none)
Uses update-mime-database from
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 @shared-mime-info
entry to the plist.
Possible arguments: (none)
A lot of software uses incorrect locations for script
interpreters, most notably /usr/bin/perl
and /bin/bash. The shebangfix macro fixes
shebang lines in scripts listed in
SHEBANG_REGEX,
SHEBANG_GLOB, or
SHEBANG_FILES.
Currently
Bash,
Java, Ksh,
Lua,
Perl, PHP,
Python,
Ruby, Tcl,
and Tk are supported by
default.
There are three configuration variables:
SHEBANG_LANGThe list of supported interpreters.
interp_CMDThe path to the command interpreter on FreeBSD. The
default value is
${LOCALBASE}/bin/interp.
interp_OLD_CMDThe 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.
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 configure script, or the
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 USES=python,
and the aim is only to fix the shebangs but a dependency on
Python itself is not wanted, use
PYTHON_NO_DEPENDS=yes.
Example 17.8. Adding Another Interpreter to
USES=shebangfix
To add another interpreter, set
SHEBANG_LANG. For example:
SHEBANG_LANG= lua
Example 17.9. Specifying all the Paths When Adding an Interpreter to
USES=shebangfix
If it was not already defined, and there were no default
values for
interp_OLD_CMDinterp_CMD
SHEBANG_LANG= ksh
ksh_OLD_CMD= "/usr/bin/env ksh" /bin/ksh /usr/bin/ksh
ksh_CMD= ${LOCALBASE}/bin/kshExample 17.10. Adding a Strange Location for an Interpreter
Some software uses strange locations for an interpreter.
For example, an application might expect
Python to be located in
/opt/bin/python2.7. The strange path to
be replaced can be declared in the port
Makefile:
python_OLD_CMD= /opt/bin/python2.7
Example 17.11. USES=shebangfix with
SHEBANG_REGEX
To fix all the files in
${WRKSRC}/scripts ending in
.pl, .sh, or
.cgi do:
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
re_format(7) for more information.
Example 17.12. USES=shebangfix with
SHEBANG_GLOB
To fix all the files in ${WRKSRC}
ending in .pl or
.sh, do:
USES= shebangfix
SHEBANG_GLOB= *.sh *.pl
Example 17.13. USES=shebangfix with
SHEBANG_FILES
To fix the files script/foobar.pl and
script/*.sh in
${WRKSRC}, do:
USES= shebangfix
SHEBANG_FILES= scripts/foobar.pl scripts/*.sh
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.
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:
OPENSSLBASEPath to the OpenSSL installation base.
OPENSSLDIRPath to OpenSSL's
configuration files.
OPENSSLLIBPath to the OpenSSL
libraries.
OPENSSLINCPath to the OpenSSL
includes.
OPENSSLRPATHIf 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:
BROKEN_SSL= libressl
BROKEN_SSL_REASON_libressl= needs features only available in OpenSSL
Possible arguments: (none), Z,
bz2, bzip2,
lzma, tbz,
tbz2,
tgz, txz,
xz
Set EXTRACT_SUFX to
.tar, .tar.Z,
.tar.bz2, .tar.bz2,
.tar.lzma, .tbz,
.tbz2,
.tgz, .txz or
.tar.xz respectively.
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
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
Possible arguments: (none)
Adds @terminfo
to the plist. Use when the port installs
*.terminfo${PREFIX}/share/misc.
Same as arguments for tcl
Small wrapper when using both Tcl
and Tk. The same variables are
returned as when using Tcl.
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 USES=fakeroot or
patching.
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.
Possible arguments: 4,
5
Handle dependencies on Varnish
Cache. 4 will add a
dependency on www/varnish4.
5 will add a dependency on www/varnish5.
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
PREFIX/lib/browser_plugins/WEBPLUGIN_NAME
WEBPLUGIN_NAME: The final directory
to install the plug-in files into, default
PKGBASE.
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:
Table 17.1. Available X.Org Components
| 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 |
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.
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.
