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_API_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. The user can set MOTIF_TYPE to dt, lesstif, or openmotif to choose which Motif version will be used. oss.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 8.0, 8.1, or 8.2, 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: &cprompt; cd pkgsrc/category/pkgdir &cprompt; createbuildlink >buildlink3.mk The following real-life example buildlink3.mk is taken from pkgsrc/graphics/tiff: # $NetBSD: buildlink3.mk,v 1.7 2004/03/18 09:12:12 jlam Exp $ BUILDLINK_DEPTH:= ${BUILDLINK_DEPTH}+ TIFF_BUILDLINK3_MK:= ${TIFF_BUILDLINK3_MK}+ .if ${BUILDLINK_DEPTH} == "+" BUILDLINK_DEPENDS+= tiff .endif BUILDLINK_PACKAGES:= ${BUILDLINK_PACKAGES:Ntiff} BUILDLINK_PACKAGES+= tiff .if ${TIFF_BUILDLINK3_MK} == "+" BUILDLINK_API_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_API_DEPENDS.pkg 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 an API change. BUILDLINK_PKGSRCDIR.pkg is the location of the pkg pkgsrc directory. BUILDLINK_DEPMETHOD.pkg (not shown above) controls whether we use BUILD_DEPENDS or DEPENDS to add the dependency on pkg. The build dependency is selected by setting BUILDLINK_DEPMETHOD.pkg to build. By default, the full dependency is used. BUILDLINK_INCDIRS.pkg and BUILDLINK_LIBDIRS.pkg (not shown above) are lists of subdirectories of ${BUILDLINK_PREFIX.pkg} to add to the header and library search paths. These default to include and lib respectively. BUILDLINK_CPPFLAGS.pkg (not shown above) is the list of preprocessor flags to add to CPPFLAGS, which are passed on to the configure and build phases. The -I option should be avoided and instead be handled using BUILDLINK_INCDIRS.pkg as above. 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.pkg (not shown above) is a shell glob pattern relative to ${BUILDLINK_PREFIX.pkg} to be symlinked into ${BUILDLINK_DIR}, e.g. include/*.h. BUILDLINK_FILES_CMD.pkg (not shown above) is a shell pipeline that outputs to stdout a list of files relative to ${BUILDLINK_PREFIX.pkg}. The resulting files are to be symlinked into ${BUILDLINK_DIR}. By default, this takes the +CONTENTS of a pkg and filters it through ${BUILDLINK_CONTENTS_FILTER.pkg}. BUILDLINK_CONTENTS_FILTER.pkg (not shown above) is a filter command that filters +CONTENTS input into a list of files relative to ${BUILDLINK_PREFIX.pkg} on stdout. By default for overwrite packages, BUILDLINK_CONTENTS_FILTER.pkg outputs the contents of the include and lib directories in the package +CONTENTS, and for pkgviews packages, it outputs any libtool archives in lib directories. BUILDLINK_FNAME_TRANSFORM.pkg (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". 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. The situation that requires increasing the dependency listed in BUILDLINK_API_DEPENDS.pkg after a package update is when the API or interface to the header files change. In this case, BUILDLINK_API_DEPENDS.pkg 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 PKGREVISIONs increased and, if they have buildlink3.mk files, their BUILDLINK_API_DEPENDS.pkg adjusted, too. This is needed so pkgsrc will require the correct package dependency and not settle for an older one when building the source. BUILDLINK_ABI_DEPENDS.pkg should be increased when the binary interface or sonames (major number of the library version) of any installed shared libraries change. 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. See for more information about dependencies on other packages, including the BUILDLINK_ABI_DEPENDS and ABI_DEPENDS definitions. Please take careful consideration before adjusting BUILDLINK_API_DEPENDS.pkg or BUILDLINK_ABI_DEPENDS.pkg 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. Also it is not needed to set BUILDLINK_ABI_DEPENDS.pkg when it is identical to BUILDLINK_API_DEPENDS.pkg. 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.pkg to either yes or no after it is included. It should not override any USE_BUILTIN.pkg which is already set before the builtin.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_API_DEPENDS.foo} . if !empty(USE_BUILTIN.foo:M[yY][eE][sS]) USE_BUILTIN.foo!= \ ${PKG_ADMIN} pmatch '${_depend_}' ${BUILTIN_PKG.foo} \ && ${ECHO} "yes" || ${ECHO} "no" . 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.pkg depending on if pkg 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.pkg to the version of pkg in the base system if it exists (if IS_BUILTIN.pkg is yes). This variable is only used internally within the builtin.mk file. The third section sets USE_BUILTIN.pkg and is required in all builtin.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_API_DEPENDS.pkg. This is typically done by comparing BUILTIN_PKG.pkg against each of the dependencies in BUILDLINK_API_DEPENDS.pkg. USE_BUILTIN.pkg must be set to the correct value by the end of the builtin.mk file. Note that USE_BUILTIN.pkg may be yes even if IS_BUILTIN.pkg 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. The last section is guarded by CHECK_BUILTIN.pkg, and includes code that uses the value of USE_BUILTIN.pkg set in the previous section. This typically includes, e.g., adding additional dependency restrictions and listing additional files to symlink into ${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.