Update documentation for the current state of buildlink3.

1 files changed, 2 insertions, 138 deletions

diff --git a/mk/buildlink3/BUILDLINK3_DG b/mk/buildlink3/BUILDLINK3_DG
index 473adfefe83..4ab79a25bff 100644
--- a/mk/buildlink3/BUILDLINK3_DG
+++ b/mk/buildlink3/BUILDLINK3_DG
@@ -1,4 +1,4 @@
-$NetBSD: BUILDLINK3_DG,v 1.4 2004/05/08 23:46:20 grant Exp $
+$NetBSD: BUILDLINK3_DG,v 1.5 2004/07/30 20:52:44 jlam Exp $
 
  0 Developer's guide to buildlink3
  =================================
@@ -67,143 +67,7 @@ scripts, and there are provisions for allowing an "overwrite" package
 to build against the viewed instance of a depoted package.
 
 
- 2 Writing buildlink3.mk files
- =============================
-
-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.
-
-
- 2.1 Simple packages
- ===================
-
-To generate an initial buildlink3.mk file for further editting, 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 -3 > buildlink3.mk
-
-The following real-life example buildlink3.mk is taken from
-graphics/tiff:
-
-------------8<------------8<------------8<------------8<------------
-# $NetBSD: BUILDLINK3_DG,v 1.4 2004/05/08 23:46:20 grant Exp $
-
-BUILDLINK_DEPTH:=	${BUILDLINK_DEPTH}+
-TIFF_BUILDLINK3_MK:=	${TIFF_BUILDLINK3_MK}+
-
-.if !empty(BUILDLINK_DEPTH:M+)
-BUILDLINK_DEPENDS+=	tiff
-.endif
-
-.if !empty(TIFF_BUILDLINK3_MK:M+)
-BUILDLINK_PACKAGES+=		tiff
-BUILDLINK_DEPENDS.tiff+=	tiff>=3.5.4
-BUILDLINK_PKGSRCDIR.tiff?=	../../graphics/tiff
-
-.  include "../../devel/zlib/buildlink3.mk"
-.  include "../../graphics/jpeg/buildlink3.mk"
-.endif	# TIFF_BUILDLINK3_MK
-
-BUILDLINK_DEPTH:=	${BUILDLINK_DEPTH:S/+$//}
-------------8<------------8<------------8<------------8<------------
-
-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 in including buildlink3.mk files.
-
-The first section controls if the dependency on tiff is added.
-BUILDLINK_DEPENDS is the global list of packages for which
-dependencies are added by buildlink3.  The tiff package is only
-appended to this list if the buildlink3.mk is included directly by a
-package Makefile.
-
-The second section is protected from multiple inclusion and control
-how the dependency on tiff is added.  Several important variables
-are set in the section:
-
- (1) 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;
-
- (2) BUILDLINK_DEPENDS.tiff 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.
-
- (3) BUILDLINK_PKGSRCDIR.tiff is the location of the tiff pkgsrc
-     directory;
-
- (4) BUILDLINK_DEPMETHOD.tiff (not shown above) controls whether we
-     use BUILD_DEPENDS or DEPENDS to add the dependency on tiff.  The
-     build dependency is selected by setting BUILDLINK_DEPMETHOD.tiff
-     to "build".  By default, the full dependency is used.
-
- (5) BUILDLINK_INCDIRS.tiff and BUILDLINK_LIBDIRS.tiff (not shown
-     above) are lists of subdirectories of ${BUILDLINK_PREFIX.tiff} to
-     add the header and library search paths.  These default to
-     "include" and "lib" respectively.
-
- (6) BUILDLINK_CPPFLAGS.tiff is the list of preprocessor flags to add
-     CPPFLAGS, which are passed on to the configure and build phases.
-     -I should be avoided and instead be added using
-     BUILDLINK_INCDIRS.tiff as above.
-
-Any buildlink3.mk for tiff's dependencies are also included at this
-point.  Including these buildlink3.mk files means that the headers
-and libraries for these dependencies are also symlinked into
-${BUILDLINK_DIR} whenever the tiff buildlink3.mk file is included.
-
-There are several considerations that arise when figuring out how
-to set BUILDLINK_DEPENDS.<pkg> correctly:
-
- (1) If the package has a pre-existing buildlink2.mk file, then
-     match the BUILDLINK_DEPENDS.<pkg> lines between the
-     buildlink2.mk file and the newly-created buildlink3.mk file.
-
- (2) If there is no pre-existing buildlink2.mk file, then set
-     BUILDLINK_DEPENDS.foo 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.
-
-
- 2.1 Packages that coincide with base system software
- ====================================================
-
-Some packages in pkgsrc install headers and libraries that coincide
-with headers and libraries present in the base system.  The best
-recommendation for writing buildlink3.mk files for these packages is
-to use graphics/MesaLib/buildlink3.mk as a template.
-
-
- 3 bl3ifying a package
- =====================
-
-The process of "bl3ifying" a package, or converting a package to use
-the buildlink3 framework, is surprisingly easy.  The things to keep in
-mind are:
-
-  (1) Set USE_BUILDLINK3=yes.
-
-  (2) Change references to buildlink2.mk files into buildlink3.mk
-      files.
-
-  (3) Ensure that the build always calls the wrapper scripts instead of
-      the actual toolchain.  Some are tricky, e.g. openssl, cdrecord,
-      ocaml, and the only way to know for sure is the check .work.log
-      to see if the wrappers are being invoked.
-
-  (4) 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>".
-
-
- 4 Troubleshooting
+ 2 Troubleshooting
  =================
 
 Q1: I'm trying to bl3ify a package but I get an error that looks like: