Document buildlink.mk methodology.

1 files changed, 162 insertions, 63 deletions

diff --git a/Packages.txt b/Packages.txt
index 90679b1944b..76c69d6c8fc 100644
--- a/Packages.txt
+++ b/Packages.txt
@@ -1,4 +1,4 @@
-# $NetBSD: Packages.txt,v 1.162 2001/06/19 16:23:33 jlam Exp $
+# $NetBSD: Packages.txt,v 1.163 2001/06/19 20:55:01 jlam Exp $
 ###########################################################################
 
 			==========================
@@ -17,7 +17,7 @@ Run this command to produce a table of contents:
 
 
  0 Intro
- ========
+ =======
 
 There is a lot of software freely available for Unix based systems, which
 usually runs on NetBSD, too, sometimes with some modifications. The NetBSD
@@ -36,7 +36,7 @@ derived from FreeBSD.
 
 
  0.1 Overview
- =============
+ ============
 
 This document is divided into two parts.  The first, "User's Guide",
 describes how one can use one of the packages in the Package
@@ -483,7 +483,7 @@ in a way that keeps all the dependencies for given package on the same
 CD as that package.
 
  3.3.1 Example of cdpack
- =============================
+ =======================
 
 Complete documentation for cdpack is found in cdpack(1).  The following
 short example assumes that the binary packages are left in
@@ -1488,7 +1488,87 @@ perform the equivalent of:
     - None of the package's required (binary) packages were modified since
       it was built
 
- 8 Debugging
+
+ 8 buildlink.mk methodology
+ ==========================
+
+Many packages that install libraries and headers for use in other packages
+now have buildlink.mk files in their pkgsrc subdirectory.  The purpose of
+these files is two-fold:
+
+  (1) Cause all headers and libraries used by a particular package to be
+      found in a known location during the configure and build process.
+
+  (2) Cause _only_ those headers and libraries used by a particular package
+      to be found during the configure and build process.
+
+
+ 8.1 Using buildlink.mk files
+ ============================
+
+Goal (1) is accomplished by simply including a package dependency's
+buildlink.mk file in a package's Makefile, which does the following:
+
+  (1a) Adding a DEPENDS or BUILD_DEPENDS line for the package.
+
+  (1b) Creating a directory ${BUILDLINK_DIR}, by default set to a
+       subdirectory of ${WRKDIR}.
+
+  (1c) Linking all the headers and libraries for that package into
+       ${BUILDLINK_DIR}/include and ${BUILDLINK_DIR}/lib, respectively.
+
+  (1d) Prepending -I${BUILDLINK_DIR}/include to CPPFLAGS, CFLAGS, CXXFLAGS,
+       and -L${BUILDLINK_DIR}/lib to LDFLAGS.
+
+  (1e) Creating a wrapper script for GTK+-style config scripts, often found
+       in GNOME software, that translates -I${LOCALBASE}/include and
+       -L${LOCALBASE}/lib into references into ${BUILDLINK_DIR}.
+
+Some packages are for software libraries whose functionality is a part of
+recent released versions of NetBSD, e.g. readline, OpenSSL, and ncurses.
+For those packages, the buildlink.mk files link the appropriate system
+headers and libraries into ${BUILDLINK_DIR} so that goal (1) is still met.
+Where possible, the system headers and libraries are renamed when linked
+into ${BUILDLINK_DIR} to match the names of their pkgsrc counterparts so
+that the files may be referenced under a consistent name.
+
+Goal (2) requires some work on the part of the package builder.  As all
+headers and libraries used by a package may be found in ${BUILDLINK_DIR},
+and -I${BUILDLINK_DIR}/include and -L${BUILDLINK_DIR}/lib are already
+passed to the compiler, it is no longer necessary to pass
+-I${LOCALBASE}/include or -L${LOCABASE}/lib to the compiler.  Therefore,
+those lines should be removed from package Makefiles, and where necessary,
+the package sources should be patched to do the same.  If
+USE_BUILDLINK_ONLY is defined, then -L${LOCALBASE}/lib is not automatically
+added to LDFLAGS in bsd.pkg.mk.
+
+
+ 8.2 Writing buildlink.mk files
+ ==============================
+
+Most of the work done by buildlink.mk files is encapsulated and shared
+through bsd.buildlink.mk, which is included by package buildlink.mk files.
+Please see the comments at the top of bsd.buildlink.mk for complete
+documentation on how to use the file.  A simple example of a buildlink.mk
+for a mythical package foo follows:
+
+> BUILDLINK_PREFIX.foo=		${LOCALBASE}
+> BUILDLINK_FILES.foo=		include/foo.h
+> BUILDLINK_FILES.foo+=		include/bar.h
+> BUILDLINK_FILES.foo+=		lib/libfoo.*
+> 
+> # We need the libraries to be called "libbar.*".
+> BUILDLINK_TRANSFORM.foo=	-e "s|libfoo|libbar|g"
+> 
+> BUILDLINK_TARGETS+=		foo-buildlink
+> 
+> pre-configure: foo-buildlink
+> foo-buildlink: _BUILDLINK_USE
+> 
+> .include "../../mk/bsd.buildlink.mk"
+
+
+ 9 Debugging
  ===========
 
 To check out all the gotchas when building a package (wither from
@@ -1540,11 +1620,11 @@ debugging aids.
  - submit (or commit, if you have cvs access); see section 10.
 
 
- 9 FAQs & features of the package system
- =======================================
+ 10 FAQs & features of the package system
+ ========================================
 
- 9.1 Packages using GNU autoconfig
- =================================
+ 10.1 Packages using GNU autoconfig
+ ==================================
 
 If your package uses GNU autoconf, add the following to your package's
 Makefile:
@@ -1555,8 +1635,8 @@ Note that this appends --prefix=${PREFIX} to CONFIGURE_ARGS, so you don't
 have to do that yourself, and this may not be what you want.
 
 
- 9.2 Other distrib methods than .tar.gz
- ======================================
+ 10.2 Other distrib methods than .tar.gz
+ =======================================
 
 If your package uses a different distribution method from .tar.gz, take a
 look at the package for editors/sam, which uses a gzipped shell archive
@@ -1569,8 +1649,8 @@ DISTNAME field, and add the following to your package's Makefile:
 > EXTRACT_AFTER_ARGS=     |sh
 
 
- 9.3 Packages not creating their own subdirectory
- ================================================
+ 10.3 Packages not creating their own subdirectory
+ =================================================
 
 Your package doesn't create a subdirectory for itself (like GNU software
 does, for instance), but extracts itself in the current directory: see
@@ -1579,8 +1659,8 @@ editors/sam again, but the quick answer is:
 > NO_WRKSUBDIR=   yes
 
 
- 9.4 Custom configuration process
- ================================
+ 10.4 Custom configuration process
+ =================================
 
 Your package uses a weird Configure script: See the top package, but the
 quick answer is:
@@ -1590,7 +1670,7 @@ quick answer is:
 > CONFIGURE_ARGS+=        netbsd13
 
 
- 9.5 Packages not building in their DISTNAME directory
+ 10.5 Packages not building in their DISTNAME directory
  ======================================================
 
 Your package builds in a different directory from its base DISTNAME - see
@@ -1599,8 +1679,8 @@ tcl and tk packages:
 > WRKSRC=         ${WRKDIR}/${DISTNAME}/unix
 
 
- 9.6 How to fetch all distfiles at once
- ======================================
+ 10.6 How to fetch all distfiles at once
+ =======================================
 
 You would like to download all the distfiles in a single batch from work or
 university, where you can't run a "make fetch". But there's no archive of
@@ -1634,8 +1714,8 @@ get all & everything by typing
 	make fetch NO_IGNORE=yes
 
 
- 9.7 How to fetch files from behind a firewall
- =============================================
+ 10.7 How to fetch files from behind a firewall
+ ==============================================
 
 If you are sitting behind a firewall which does not allow direct connections
 to Internet hosts (i.e. non-NAT), you may specify the relevant proxy hosts.
@@ -1648,14 +1728,14 @@ variables look like:
 	http_proxy=http://orpheus.amdahl.com:80/
 
 
- 9.8 If your patch contains an RCS ID
- ====================================
+ 10.8 If your patch contains an RCS ID
+ =====================================
 
 See section 4.3 on how to remove RCS IDs from patch files. 
 
 
- 9.9 How to pull in variables from /etc/mk.conf
- ==============================================
+ 10.9 How to pull in variables from /etc/mk.conf
+ ===============================================
 
 The problem with package-defined variables that can be overridden via
 MAKECONF or /etc/mk.conf is that make(1) expands a variable as it is
@@ -1676,8 +1756,8 @@ preprocessor-like .if, .ifdef, or .ifndef statements:
 	.endif
 
 
- 9.10 Is there a mailing list for pkg-related discussion?
- ========================================================
+ 10.10 Is there a mailing list for pkg-related discussion?
+ =========================================================
 
 Yes. We are using tech-pkg@netbsd.org for discussing package related
 issues. To subscribe do:
@@ -1685,8 +1765,8 @@ issues. To subscribe do:
     echo subscribe tech-pkg | mail majordomo@netbsd.org
 
 
- 9.11 How do i tell "make fetch" to do passive FTP?
- ==================================================
+ 10.11 How do i tell "make fetch" to do passive FTP?
+ ===================================================
 
 This depends on which utility is used to retrieve distfiles. From
 bsd.pkg.mk, FETCH_CMD is assigned the first available command from the
@@ -1705,8 +1785,8 @@ Having that option present will prevent /usr/bin/ftp from falling back to
 active transfers.
 
 
- 9.12 Dependencies on other packages
- ===================================
+ 10.12 Dependencies on other packages
+ ====================================
 
 Your package may depend on some other package being present - and there are
 various ways of expressing this dependency. NetBSD supports the
@@ -1787,8 +1867,8 @@ installed version of an older gettext package, or if it isn't, installs the
 devel/gettext-m4 package.
 
 
- 9.13 Conflicts with other packages
- ==================================
+ 10.13 Conflicts with other packages
+ ===================================
 
 Your package may conflict with other packages a user might already have
 installed on his system, e.g. if your package installs the same set of
@@ -1811,8 +1891,8 @@ and a different version string. "Xaw3d-1.5" e.g. will automatically conflict
 with the older version "Xaw3d-1.3".
 
 
- 9.14 Software which has a WWW Home Page
- =======================================
+ 10.14 Software which has a WWW Home Page
+ ========================================
 
 The NetBSD packages system now supports a variable called HOMEPAGE.
 If the software being packaged has a home page, the Makefile should
@@ -1821,8 +1901,8 @@ of the variable should be placed immediately after the MAINTAINER
 variable.
 
 
- 9.15 How to handle modified distfiles with the 'old' name
- =========================================================
+ 10.15 How to handle modified distfiles with the 'old' name
+ ==========================================================
 
 Sometimes authors of a software package make some modifications after the
 software was released, and they put up a new distfile without changing the
@@ -1836,8 +1916,8 @@ the distfile was really updated on purpose, and that no trojan horse or so
 crept in.
 
 
- 9.16 What does "Don't know how to make /usr/share/tmac/tmac.andoc" mean?
- ========================================================================
+ 10.16 What does "Don't know how to make /usr/share/tmac/tmac.andoc" mean?
+ =========================================================================
 
 When compiling the pkgsrc/pkgtools/pkg_install package, you get the error
 from make that it doesn't know how to make /usr/share/tmac/tmac.andoc? This
@@ -1848,8 +1928,8 @@ In the case of the pkg_install package, you can get away with setting
 NOMAN=YES either in the environment or in /etc/mk.conf.
 
 
- 9.17 How to handle incrementing versions when fixing an existing package
- ========================================================================
+ 10.17 How to handle incrementing versions when fixing an existing package
+ =========================================================================
 
 When making fixes to an existing package it can be useful to change
 the version number in PKGNAME. To avoid conflicting with future versions
@@ -1857,8 +1937,8 @@ by the original author, use a 'nb1' suffix (later versions should
 increment this to give 'nb2' and so on).
 
 
- 9.18 "Could not find bsd.own.mk" - what's wrong?
- ================================================
+ 10.18 "Could not find bsd.own.mk" - what's wrong?
+ =================================================
 
 You didn't install the compiler set, comp.tgz, when you installed your
 NetBSD machine. Please get it and install it, by extracting it in /:
@@ -1869,8 +1949,8 @@ comp.tgz is part of every NetBSD release, please get the one matching
 the release you have installed (determine via "uname -r").
 
 
- 9.19 Restricted packages
- ========================
+ 10.19 Restricted packages
+ =========================
 
 Some licenses restrict how software may be re-distributed.  In order to
 satisfy these restrictions, the package system defines five make variables
@@ -1905,15 +1985,22 @@ Please note that the use of NO_PACKAGE, IGNORE, NO_CDROM, or other generic
 make variables to denote restrictions is deprecated, because they
 unconditionally prevent users from generating binary packages!
 
- 9.20 Packages using (n)curses
- =============================
+ 10.20 Packages using (n)curses
+ ==============================
 
 Some packages need curses functionality that wasn't present in NetBSD's own
-curses prior to 1.4Y. For packages using such functionality there are some
-variables: If USE_CURSES is set in a package's Makefile, NEED_NCURSES is
-set automatically to YES or NO, depending on whether a dependency on
-ncurses is needed on this system. You can use this variable to e.g. add
-arguments to configure to tell the package whether to use ncurses.
+curses prior to 1.4Y. For packages using such functionality there are two
+options, setting USE_CURSES or including ../../devel/ncurses/buildlink.mk
+in the package's Makefile.
+
+
+ 10.20.1 USE_CURSES
+ ===================
+
+If USE_CURSES is set in a package's Makefile, NEED_NCURSES is set
+automatically to YES or NO, depending on whether a dependency on ncurses is
+needed on this system. You can use this variable to e.g. add arguments to
+configure to tell the package whether to use ncurses.
 
 Additionally, you can set REPLACE_NCURSES to some filenames; in each of
 these files, each occurrence of 'ncurses' is replaced by 'curses' if the
@@ -1934,8 +2021,20 @@ Please note that the check for NEED_NCURSES has to be below the
 inclusion of bsd.prefs.mk, since the variable is set there.
 
 
- 9.21 Automated security check
- =============================
+ 10.20.2 devel/ncurses/buildlink.mk
+ ==================================
+
+If ../../devel/ncurses/buildlink.mk is included in a package's Makefile,
+then a curses library and headers with ncurses functionality are linked
+into ${BUILDLINK_DIR} at pre-configure time.  If ncurses is needed, then a
+dependency on ncurses is added to the package, otherwise, if the system
+curses is sufficient, then the library and headers are linked into
+${BUILDLINK_DIR} with ncurses names.  If ncurses is actually required, then
+define USE_NCURSES in the package's Makefile.
+
+
+ 10.21 Automated security check
+ ==============================
 
 Please be aware that there can often be bugs in third-party software,
 and some of these bugs can leave a machine vulnerable to exploitation
@@ -1989,10 +2088,10 @@ commit of that file, it should be copied to
 /pub/NetBSD/packages/distfiles/vulnerabilities on ftp.netbsd.org. 
 
 
- 10 Submitting & Committing
+ 11 Submitting & Committing
  ==========================
 
- 10.1 Submitting your packages
+ 11.1 Submitting your packages
  =============================
 
 You have to separate between binary and "normale" (source) packages here:
@@ -2021,7 +2120,7 @@ You have to separate between binary and "normale" (source) packages here:
    each one, it's easier for us to track things that way.
 
 
- 10.2 Committing: Importing the package into CVS
+ 11.2 Committing: Importing the package into CVS
  ===============================================
 
 This section is only of interest for NetBSD developers with write
@@ -2058,7 +2157,7 @@ format, because it will be used by scripts to automatically update pages on
 www.netbsd.org and other sites.
 
 
- 11 A simple example of a package: bison
+ 12 A simple example of a package: bison
  =======================================
 
 I checked to find a piece of software that isn't in the FreeBSD ports
@@ -2067,13 +2166,13 @@ bison when Berkeley yacc is already present in the tree is beyond me, but
 it's useful for the purposes of this exercise.
 
 
- 11.1 files
+ 12.1 files
  ==========
 
 The file contents in this section must be used without the "> " prefix.
 
 
- 11.1.1 Makefile
+ 12.1.1 Makefile
  ===============
 
 > # <$>NetBSD<$>
@@ -2092,7 +2191,7 @@ The file contents in this section must be used without the "> " prefix.
 > .include "../../mk/bsd.pkg.mk"
 
 
- 11.1.2 pkg/DESCR
+ 12.1.2 pkg/DESCR
  ================
 
 > GNU version of yacc.  Can make re-entrant parsers, and numerous other
@@ -2100,7 +2199,7 @@ The file contents in this section must be used without the "> " prefix.
 > of the NetBSD source tree is beyond me.
 
 
- 11.1.3 pkg/PLIST
+ 12.1.3 pkg/PLIST
  ================
 
 > @comment <$>NetBSD<$>
@@ -2118,7 +2217,7 @@ The file contents in this section must be used without the "> " prefix.
 > share/bison.hairy
 
 
- 11.1.4 Checking a package "pkglint"
+ 12.1.4 Checking a package "pkglint"
  ===================================
 
 The NetBSD package system comes with a tool called "pkglint" (located in the
@@ -2138,7 +2237,7 @@ verbose checks will be performed. Use e.g. "pkglint -v" for a very verbose
 check.
 
 
- 11.2 Steps for building, installing, packaging
+ 12.2 Steps for building, installing, packaging
  ==============================================
 
 Create the directory where the package lives, plus any auxiliary directories: