Table of Contents
Buildlink is a framework in pkgsrc that controls what headers and libraries are seen by a package's configure and build processes. This is implemented in a two step process:
Symlink headers and libraries for dependencies into
BUILDLINK_DIR, which by
default is a subdirectory of WRKDIR.
Create wrapper scripts that are used in place of the
normal compiler tools that translate -I${LOCALBASE}/include and -L${LOCALBASE}/lib into references to
BUILDLINK_DIR. The wrapper
scripts also make native compiler on some operating
systems look like GCC, so that packages that expect GCC
won't require modifications to build with those native
compilers.
This normalizes the environment in which a package is built
so that the package may be built consistently despite what
other software may be installed. Please note that the normal
system header and library paths, e.g. /usr/include, /usr/lib, etc., are always searched --
buildlink3 is designed to insulate the package build from
non-system-supplied software.
The process of converting packages to use the buildlink3 framework (“bl3ifying”) is fairly straightforward. The things to keep in mind are:
Ensure that the build always calls the wrapper
scripts instead of the actual toolchain. Some packages
are tricky, and the only way to know for sure is the
check ${WRKDIR}/.work.log to see if the
wrappers are being invoked.
Don't override PREFIX
from within the package Makefile, e.g. Java VMs,
standalone shells, etc., because the code to symlink
files into ${BUILDLINK_DIR} looks for files
relative to “pkg_info -qp
pkgname”.
Remember that only the buildlink3.mk files that you list in
a package's Makefile are added as dependencies for that
package.
If a dependency on a particular package is required for its libraries and headers, then we replace:
DEPENDS+= foo>=1.1.0:../../category/foo
with
.include "../../category/foo/buildlink3.mk"
The buildlink3.mk files usually define the required dependencies. If you need a newer version of the dependency when using buildlink3.mk files, then you can define it in your Makefile; for example:
BUILDLINK_DEPENDS.foo+= foo>=1.1.0
.include "../../category/foo/buildlink3.mk"
There are several buildlink3.mk files in pkgsrc/mk that handle special package
issues:
bdb.buildlink3.mk chooses either the
native or a pkgsrc Berkeley DB implementation based on
the values of BDB_ACCEPTED
and BDB_DEFAULT.
curses.buildlink3.mk: If the system
comes with neither Curses nor NCurses, this will take
care to install the devel/ncurses package.
krb5.buildlink3.mk uses the value of
KRB5_ACCEPTED to choose
between adding a dependency on Heimdal or MIT-krb5 for
packages that require a Kerberos 5 implementation.
motif.buildlink3.mk checks for a
system-provided Motif installation or adds a dependency
on x11/lesstif or x11/openmotif.
ossaudio.buildlink3.mk defines
several variables that may be used by packages that use
the Open Sound System (OSS) API.
pgsql.buildlink3.mk will accept
either Postgres 7.3 or 7.4, whichever is found
installed. See the file for more information.
pthread.buildlink3.mk uses the value
of PTHREAD_OPTS and checks
for native pthreads or adds a dependency on devel/pth as needed.
xaw.buildlink3.mk uses the value of
XAW_TYPE to choose a
particular Athena widgets library.
The comments in those buildlink3.mk files provide a more complete
description of how to use them properly.
A package's buildlink3.mk file is included by Makefiles
to indicate the need to compile and link against header files
and libraries provided by the package. A buildlink3.mk file should always provide
enough information to add the correct type of dependency
relationship and include any other buildlink3.mk files that it needs to find
headers and libraries that it needs in turn.
To generate an initial buildlink3.mk file for further editing,
Rene Hexel's pkgtools/createbuildlink package is
highly recommended. For most packages, the following command
will generate a good starting point for buildlink3.mk files:
%cd pkgsrc/category/pkgdir%createbuildlink >buildlink3.mk
The following real-life example buildlink3.mk is taken from pkgsrc/graphics/tiff:
# $NetBSD: buildlink.html,v 1.45 2006/03/01 17:23:13 rillig Exp $
BUILDLINK_DEPTH:= ${BUILDLINK_DEPTH}+
TIFF_BUILDLINK3_MK:= ${TIFF_BUILDLINK3_MK}+
.if !empty(BUILDLINK_DEPTH:M+)
BUILDLINK_DEPENDS+= tiff
.endif
BUILDLINK_PACKAGES:= ${BUILDLINK_PACKAGES:Ntiff}
BUILDLINK_PACKAGES+= tiff
.if !empty(TIFF_BUILDLINK3_MK:M+)
BUILDLINK_DEPENDS.tiff+= tiff>=3.6.1
BUILDLINK_PKGSRCDIR.tiff?= ../../graphics/tiff
.endif # TIFF_BUILDLINK3_MK
.include "../../devel/zlib/buildlink3.mk"
.include "../../graphics/jpeg/buildlink3.mk"
BUILDLINK_DEPTH:= ${BUILDLINK_DEPTH:S/+$//}
The header and footer manipulate BUILDLINK_DEPTH, which is common across
all buildlink3.mk files and is used to
track at what depth we are including buildlink3.mk files.
The first section controls if the dependency on
pkg is added.
BUILDLINK_DEPENDS is the
global list of packages for which dependencies are added by
buildlink3.
The second section advises pkgsrc that the buildlink3.mk file for pkg has been included at
some point. BUILDLINK_PACKAGES
is the global list of packages for which buildlink3.mk files have been included.
It must always be
appended to within a buildlink3.mk file.
The third section is protected from multiple inclusion
and controls how the dependency on pkg is added. Several
important variables are set in the section:
BUILDLINK_DEPENDS. is the
actual dependency recorded in the installed package;
this should always be set using += to ensure that we're
appending to any pre-existing list of values. This
variable should be set to the first version of the
package that had the last change in the major number
of a shared library or that had a major API
change.pkg
BUILDLINK_PKGSRCDIR. is the
location of the pkgpkg pkgsrc
directory.
BUILDLINK_DEPMETHOD. (not shown
above) controls whether we use pkgBUILD_DEPENDS or DEPENDS to add the dependency on
pkg. The
build dependency is selected by setting BUILDLINK_DEPMETHOD. to
“build”. By
default, the full dependency is used.pkg
BUILDLINK_INCDIRS. and
pkgBUILDLINK_LIBDIRS. (not shown
above) are lists of subdirectories of pkg${BUILDLINK_PREFIX. to add to
the header and library search paths. These default to
“include” and
“lib”
respectively.pkg}
BUILDLINK_CPPFLAGS.
(not shown above) is the list of preprocessor flags
to add to pkgCPPFLAGS,
which are passed on to the configure and build
phases. The “-I” option should be avoided and
instead be handled using BUILDLINK_INCDIRS. as
above.pkg
The following variables are all optionally defined
within this second section (protected against multiple
inclusion) and control which package files are symlinked
into ${BUILDLINK_DIR} and how their
names are transformed during the symlinking:
BUILDLINK_FILES. (not shown
above) is a shell glob pattern relative to
pkg${BUILDLINK_PREFIX. to be
symlinked into pkg}${BUILDLINK_DIR}, e.g. include/*.h.
BUILDLINK_FILES_CMD. (not shown
above) is a shell pipeline that outputs to stdout a
list of files relative to pkg${BUILDLINK_PREFIX.. The
resulting files are to be symlinked into pkg}${BUILDLINK_DIR}. By default, this
takes the +CONTENTS of a pkg and filters it
through ${BUILDLINK_CONTENTS_FILTER..pkg}
BUILDLINK_CONTENTS_FILTER. (not shown
above) is a filter command that filters pkg+CONTENTS input into a list of
files relative to ${BUILDLINK_PREFIX. on
stdout. By default for overwrite packages,
pkg}BUILDLINK_CONTENTS_FILTER. outputs
the contents of the pkginclude and lib directories in the package
+CONTENTS, and for pkgviews
packages, it outputs any libtool archives in
lib directories.
BUILDLINK_TRANSFORM. (not shown
above) is a list of sed arguments used to transform
the name of the source filename into a destination
filename, e.g. -e
"s|/curses.h|/ncurses.h|g".pkg
The last section includes any buildlink3.mk needed for pkg's library dependencies.
Including these buildlink3.mk files means that the
headers and libraries for these dependencies are also
symlinked into ${BUILDLINK_DIR} whenever the pkg buildlink3.mk file is included.
There are two situations that require increasing the
dependency listed in BUILDLINK_DEPENDS. after a package
update:pkg
if the sonames (major number of the library version) of any installed shared libraries change.
if the API or interface to the header files change.
In these cases, BUILDLINK_DEPENDS. should be
adjusted to require at least the new package version. In
some cases, the packages that depend on this new version
may need their pkgPKGREVISIONs
increased and, if they have buildlink3.mk files, their BUILDLINK_DEPENDS. adjusted, too.
This is needed so that binary packages made using it will
require the correct package dependency and not settle for
an older one which will not contain the necessary shared
libraries.pkg
Please take careful consideration before adjusting
BUILDLINK_DEPENDS. as we don't want
to cause unneeded package deletions and rebuilds. In many
cases, new versions of packages work just fine with older
dependencies. See Section 16.1.4,
“Handling dependencies” for more
information about dependencies on other packages, including
the pkgBUILDLINK_RECOMMENDED and
RECOMMENDED definitions.
Some packages in pkgsrc install headers and libraries that
coincide with headers and libraries present in the base
system. Aside from a buildlink3.mk file, these packages should
also include a builtin.mk file that includes the necessary
checks to decide whether using the built-in software or the
pkgsrc software is appropriate.
The only requirements of a builtin.mk file for pkg are:
It should set USE_BUILTIN. to either
“yes” or
“no” after it is
included.pkg
It should not
override any USE_BUILTIN. which is
already set before the pkgbuiltin.mk file is included.
It should be written to allow multiple inclusion.
This is very
important and takes careful attention to Makefile coding.
The following is the recommended template for builtin.mk files:
.if !defined(IS_BUILTIN.foo)
#
# IS_BUILTIN.foo is set to "yes" or "no" depending on whether "foo"
# genuinely exists in the system or not.
#
IS_BUILTIN.foo?= no
# BUILTIN_PKG.foo should be set here if "foo" is built-in and its package
# version can be determined.
#
. if !empty(IS_BUILTIN.foo:M[yY][eE][sS])
BUILTIN_PKG.foo?= foo-1.0
. endif
.endif # IS_BUILTIN.foo
.if !defined(USE_BUILTIN.foo)
USE_BUILTIN.foo?= ${IS_BUILTIN.foo}
. if defined(BUILTIN_PKG.foo)
. for _depend_ in ${BUILDLINK_DEPENDS.foo}
. if !empty(USE_BUILTIN.foo:M[yY][eE][sS])
USE_BUILTIN.foo!= \
if ${PKG_ADMIN} pmatch '${_depend_}' ${BUILTIN_PKG.foo}; then \
${ECHO} "yes"; \
else \
${ECHO} "no"; \
fi
. endif
. endfor
. endif
.endif # USE_BUILTIN.foo
CHECK_BUILTIN.foo?= no
.if !empty(CHECK_BUILTIN.foo:M[nN][oO])
#
# Here we place code that depends on whether USE_BUILTIN.foo is set to
# "yes" or "no".
#
.endif # CHECK_BUILTIN.foo
The first section sets IS_BUILTIN. depending on if
pkgpkg really exists
in the base system. This should not be a base system
software with similar functionality to pkg; it should only be
“yes” if the actual
package is included as part of the base system. This
variable is only used internally within the builtin.mk file.
The second section sets BUILTIN_PKG. to the version
of pkgpkg in the
base system if it exists (if IS_BUILTIN. is
“yes”). This
variable is only used internally within the pkgbuiltin.mk file.
The third section sets USE_BUILTIN. and is
required in all
pkgbuiltin.mk files. The code in this
section must make the determination whether the built-in
software is adequate to satisfy the dependencies listed in
BUILDLINK_DEPENDS.. This is
typically done by comparing pkgBUILTIN_PKG. against each of
the dependencies in pkgBUILDLINK_DEPENDS.. pkgUSE_BUILTIN. must be set to the correct value
by the end of the pkgbuiltin.mk file. Note that USE_BUILTIN. may be
“yes” even if
pkgIS_BUILTIN. is
“no” because we may
make the determination that the built-in version of the
software is similar enough to be used as a replacement.pkg
The last section is guarded by CHECK_BUILTIN., and includes
code that uses the value of pkgUSE_BUILTIN. set in the
previous section. This typically includes, e.g., adding
additional dependency restrictions and listing additional
files to symlink into pkg${BUILDLINK_DIR} (via BUILDLINK_FILES.).pkg
When building packages, it's possible to choose whether
to set a global preference for using either the built-in
(native) version or the pkgsrc version of software to
satisfy a dependency. This is controlled by setting
PREFER_PKGSRC and PREFER_NATIVE. These variables take values
of either “yes”,
“no”, or a list of
packages. PREFER_PKGSRC tells
pkgsrc to use the pkgsrc versions of software, while
PREFER_NATIVE tells pkgsrc to
use the built-in versions. Preferences are determined by
the most specific instance of the package in either
PREFER_PKGSRC or PREFER_NATIVE. If a package is specified
in neither or in both variables, then PREFER_PKGSRC has precedence over
PREFER_NATIVE. For example, to
require using pkgsrc versions of software for all but the
most basic bits on a NetBSD system, you can set:
PREFER_PKGSRC= yes
PREFER_NATIVE= getopt skey tcp_wrappers
A package must
have a builtin.mk file to be listed in
PREFER_NATIVE, otherwise it is
simply ignored in that list.