[pkgsrc/trunk]: pkgsrc/mk/features More documentation.

[rillig <rillig%pkgsrc.org@localhost>]

details:   https://anonhg.NetBSD.org/pkgsrc/rev/31223f2b6e99
branches:  trunk
changeset: 535052:31223f2b6e99
user:      rillig <rillig%pkgsrc.org@localhost>
date:      Tue Nov 06 22:48:15 2007 +0000

description:
More documentation.

diffstat:

 mk/features/features-vars.mk |  36 +++++++++++++++++++++++++++++++-----
 1 files changed, 31 insertions(+), 5 deletions(-)

diffs (59 lines):

diff -r 86d9d6a40a03 -r 31223f2b6e99 mk/features/features-vars.mk
--- a/mk/features/features-vars.mk      Tue Nov 06 21:38:52 2007 +0000
+++ b/mk/features/features-vars.mk      Tue Nov 06 22:48:15 2007 +0000
@@ -1,8 +1,34 @@
-# $NetBSD: features-vars.mk,v 1.9 2007/11/03 11:50:18 rillig Exp $
+# $NetBSD: features-vars.mk,v 1.10 2007/11/06 22:48:15 rillig Exp $
+#
+# The platforms that are supported by pkgsrc differ in the amount of
+# functions they provide in the C library (libc). Functions that are
+# typically available on NetBSD are provided in the libnbcomat package.
+#
+# This file defines a set of "features" that some packages require.
+# Whenever a package makes use of them, it should list the features in
+# the USE_FEATURES variable. (It serves a similar purpose as USE_TOOLS.)
+#
+# The *.c files that use the features must be patched a little. When
+# there are missing features, the C preprocessor macro HAVE_NBCOMPAT_H
+# will be defined to 1. In this case, the headers from the nbcompat
+# directory must be included.
 #
-# This file is included by bsd.prefs.mk.
+# === Example ===
+#
+# In the package Makefile:
+#
+#      USE_FEATURES=           err
+#
+# In the C files using the err*() or warn*() functions:
 #
-# Package-settable variables:
+#      #if defined(HAVE_NBCOMPAT_H)
+#      #include <nbcompat/cdefs.h>     /* needed for the other headers */
+#      #include <nbcompat/err.h>
+#      #else
+#      #include <err.h>
+#      #endif
+#
+# === Package-settable variables ===
 #
 # USE_FEATURES
 #      Lists the system features required by the package.
@@ -10,7 +36,7 @@
 #      Possible:
 #      * err: The functions err, verr, errx, verrx.
 #      * warn: The functions warn, vwarn, warnx, vwarnx.
-#      * fts_close, ftp_open, fts_read, fts_set: Functions
+#      * fts_close, fts_open, fts_read, fts_set: Functions
 #        for filesystem traversal.
 #      * getopt_long: The GNU version of getopt.
 #      * getprogname, setprogname
@@ -22,7 +48,7 @@
 #
 #      Default value: undefined
 #
-# Variables defined by this file:
+# === Variables defined by this file ===
 #
 # MISSING_FEATURES
 #      The features listed in USE_FEATURES that are missing on the