Imported portability-book.

The pkgsrc portability book covers many of the platform-specific issues
that are useful when writing programs that are portable to a great
number of UNIX-like operating systems.

12 files changed, 406 insertions, 0 deletions

diff --git a/doc/portability-book/DESCR b/doc/portability-book/DESCR
new file mode 100644
index 00000000000..ac2394f239e
--- /dev/null
+++ b/doc/portability-book/DESCR
@@ -0,0 +1,3 @@
+The pkgsrc portability book covers many of the platform-specific issues
+that are useful when writing programs that are portable to a great
+number of UNIX-like operating systems.
diff --git a/doc/portability-book/Makefile b/doc/portability-book/Makefile
new file mode 100644
index 00000000000..1e85259eec3
--- /dev/null
+++ b/doc/portability-book/Makefile
@@ -0,0 +1,93 @@
+# $NetBSD: Makefile,v 1.1.1.1 2006/10/06 21:10:41 rillig Exp $
+#
+
+DISTNAME=		portability-book-${TODAY}
+CATEGORIES=		# empty
+MASTER_SITES=		${MASTER_SITE_LOCAL}
+DISTFILES=		htdocs-share-20061001.tar.gz
+
+MAINTAINER=		rillig@NetBSD.org
+#HOMEPAGE=		http://www.NetBSD.org/Documentation/pkgsrc/
+COMMENT=		The pkgsrc portability book
+
+TODAY!=			date '+%Y%m%d'
+DIST_SUBDIR=		pkgsrc-guide
+NO_MTREE=		yes
+USE_LANGUAGES=		# none
+
+PLIST_SRC=		${WRKDIR}/PLIST_DYNAMIC
+DOCDIR=			${PREFIX}/share/doc/pkgsrc-portability
+HTDOCSDIR?=		${.CURDIR}/../../../htdocs
+
+BUILD_DEFS+=		OUTPUTS
+OUTPUTS?=		lint html html-split ascii pdf
+
+.if defined(OUTPUTS)
+.  if !empty(OUTPUTS:Mascii)
+# the html is needed to build the ascii version.
+OUTPUTS+=		html
+.  endif
+
+# only override the Makefile.common default if it is explicitly set
+_GUIDE_OUTPUTS=		${OUTPUTS}
+.endif
+
+DEPENDS+=		netbsd-doc-print>=1.2:../../meta-pkgs/netbsd-doc-print
+
+# The source files are only symlinked into the WRKSRC, so that they can
+# be easily modified, should the "lint" phase fail.
+pre-extract:
+	${MKDIR} ${WRKSRC}
+	${LN} -s ${FILESDIR}/* ${WRKSRC}
+	ln -s ${PKGSRCDIR}/doc/guide/files/share ${WRKSRC}/
+
+do-build:
+.for _output_ in ${OUTPUTS}
+	@cd ${WRKSRC} && ${SETENV} ${MAKE_ENV} ${MAKE_PROGRAM} ${MAKE_FLAGS} ${_output_}
+.endfor
+
+post-build:
+	@${RM} -f ${WRKSRC}/portability.tmp.html
+
+do-install:
+	${INSTALL_DATA_DIR} ${DOCDIR}
+.if !empty(OUTPUTS:Mhtml) || !empty(OUTPUTS:Mhtml-split)
+	${INSTALL_DATA} ${WRKSRC}/*.html ${DOCDIR}
+	${INSTALL_DATA} ${WRKDIR}/htdocs/NetBSD.css ${DOCDIR}
+.endif
+.if !empty(OUTPUTS:Mascii)
+	${INSTALL_DATA} ${WRKSRC}/portability.txt ${DOCDIR}
+.endif
+.if !empty(OUTPUTS:Mpdf)
+	${INSTALL_DATA} ${WRKSRC}/portability.ps ${DOCDIR}
+	${INSTALL_DATA} ${WRKSRC}/portability.pdf ${DOCDIR}
+.endif
+
+post-install:
+	${FIND} ${DOCDIR} \( -type f -o -type l \) -print		\
+		| ${SORT} | ${SED} -e "s,${PREFIX}/,,g"			\
+		>> ${PLIST_SRC}
+	${FIND} ${DOCDIR} -type d -print				\
+		| ${SORT} -r | ${SED} -e "s,${PREFIX}/,@dirrm ,g"	\
+		>> ${PLIST_SRC}
+
+do-lint:
+	cd ${WRKSRC} && ${SETENV} ${MAKE_ENV} ${MAKE_PROGRAM} lint
+
+DETAB_PROGRAM= \
+	if (/<programlisting>/ .. /<\/programlisting>/) {		\
+		while (/(.*?)\t(.*)/s) {				\
+			my $$filler = " " x (8 - (length($$1) % 8));	\
+			$$_ = "$$1$$filler$$2";				\
+		}							\
+	}
+
+# remove tabulators from the <programlisting> tags.
+# TeX does not like them.
+.PHONY: detab
+detab:
+	cd ${FILESDIR} &&						\
+	perl -p -i".detab.tmp" -e '${DETAB_PROGRAM}' *.xml &&		\
+	${RM} -f *.xml.detab.tmp
+
+.include "../../mk/bsd.pkg.mk"
diff --git a/doc/portability-book/distinfo b/doc/portability-book/distinfo
new file mode 100644
index 00000000000..149d69ad53a
--- /dev/null
+++ b/doc/portability-book/distinfo
@@ -0,0 +1,5 @@
+$NetBSD: distinfo,v 1.1.1.1 2006/10/06 21:10:41 rillig Exp $
+
+SHA1 (pkgsrc-guide/htdocs-share-20061001.tar.gz) = 9d952e5da6c846882c058ce0ec5095b643a1363e
+RMD160 (pkgsrc-guide/htdocs-share-20061001.tar.gz) = dd8f2a83d8f816c980219c54fc55b711b9e1a310
+Size (pkgsrc-guide/htdocs-share-20061001.tar.gz) = 93042 bytes
diff --git a/doc/portability-book/files/Makefile b/doc/portability-book/files/Makefile
new file mode 100644
index 00000000000..2d65f090115
--- /dev/null
+++ b/doc/portability-book/files/Makefile
@@ -0,0 +1,27 @@
+# $NetBSD: Makefile,v 1.1.1.1 2006/10/06 21:10:41 rillig Exp $
+
+DOC=	portability
+
+SRCS=	portability.xml
+SRCS+=	chapters.ent
+SRCS+=	intro.xml
+SRCS+=	utilities.xml
+SRCS+=	headers.xml
+SRCS+=	functions.xml
+SRCS+=	devices.xml
+
+# Make deeper TOC:
+XSL_DBX_WITH_TOC_SECTION_DEPTH?= 2 
+
+# Avoid extra normalization
+NO_TIDY?=	yes
+
+
+all:	# doing this as depends doesn't work
+	${MAKE} html-split
+	${MAKE} html
+	${MAKE} ascii
+	${MAKE} pdf
+
+WEB_PREFIX=	${.CURDIR}/../htdocs
+.include "../htdocs/share/mk/doc.docbook.mk"
diff --git a/doc/portability-book/files/chapters.ent b/doc/portability-book/files/chapters.ent
new file mode 100644
index 00000000000..579ea165245
--- /dev/null
+++ b/doc/portability-book/files/chapters.ent
@@ -0,0 +1,10 @@
+<!-- $NetBSD: chapters.ent,v 1.1.1.1 2006/10/06 21:10:41 rillig Exp $ -->
+
+<!ENTITY chap.intro	SYSTEM "intro.xml">
+<!ENTITY chap.shell	SYSTEM "shell.xml">
+<!ENTITY chap.utilities	SYSTEM "utilities.xml">
+<!ENTITY chap.headers	SYSTEM "headers.xml">
+<!ENTITY chap.functions	SYSTEM "functions.xml">
+<!ENTITY chap.libraries	SYSTEM "libraries.xml">
+<!ENTITY chap.devices	SYSTEM "devices.xml">
+<!ENTITY chap.faq	SYSTEM "faq.xml">
diff --git a/doc/portability-book/files/devices.xml b/doc/portability-book/files/devices.xml
new file mode 100644
index 00000000000..2f3f98b0b42
--- /dev/null
+++ b/doc/portability-book/files/devices.xml
@@ -0,0 +1,10 @@
+<!-- $NetBSD: devices.xml,v 1.1.1.1 2006/10/06 21:10:41 rillig Exp $ -->
+
+<chapter id="dev">
+<title>Device files</title>
+
+<para>This chapter lists the device files that are available on the
+platforms and whether they are compatible to other platform's
+devices.</para>
+
+</chapter>
diff --git a/doc/portability-book/files/functions.xml b/doc/portability-book/files/functions.xml
new file mode 100644
index 00000000000..488c82b4aca
--- /dev/null
+++ b/doc/portability-book/files/functions.xml
@@ -0,0 +1,39 @@
+<!-- $NetBSD: functions.xml,v 1.1.1.1 2006/10/06 21:10:41 rillig Exp $ -->
+
+<chapter id="functions">
+<title>C/C++: functions</title>
+
+<para>This chapter contains the requirements for using certain functions
+in C and C++ code.</para>
+
+<table>
+<title>Functions on various platforms</title>
+<tgroup cols="5">
+<thead><row>
+  <entry>Function name</entry>
+  <entry>Platform</entry>
+  <entry>Library</entry>
+  <entry>Headers</entry>
+  <entry>Feature test macros</entry>
+</row></thead>
+
+<tbody>
+<row>
+  <entry>getopt</entry>
+  <entry>NetBSD-*-*</entry>
+  <entry>c</entry>
+  <entry>unistd.h</entry>
+  <entry>_POSIX_C_SOURCE >= 2 || _XOPEN_SOURCE >= 4 || defined(_NETBSD_SOURCE)</entry>
+</row>
+<row>
+  <entry>getopt</entry>
+  <entry>SunOS-5.10-*</entry>
+  <entry>c</entry>
+  <entry>unistd.h</entry>
+  <entry>(_XOPEN_SOURCE && _XOPEN_VERSION == 4) || __EXTENSIONS__</entry>
+</row>
+</tbody>
+</tgroup>
+</table>
+
+</chapter>
diff --git a/doc/portability-book/files/headers.xml b/doc/portability-book/files/headers.xml
new file mode 100644
index 00000000000..a191558058b
--- /dev/null
+++ b/doc/portability-book/files/headers.xml
@@ -0,0 +1,9 @@
+<!-- $NetBSD: headers.xml,v 1.1.1.1 2006/10/06 21:10:41 rillig Exp $ -->
+
+<chapter id="headers">
+<title>C/C++: Header files</title>
+
+<para>This chapter provides information about which header files are
+available on which platform.</para>
+
+</chapter>
diff --git a/doc/portability-book/files/intro.xml b/doc/portability-book/files/intro.xml
new file mode 100644
index 00000000000..aef735f75a7
--- /dev/null
+++ b/doc/portability-book/files/intro.xml
@@ -0,0 +1,8 @@
+<!-- $NetBSD: intro.xml,v 1.1.1.1 2006/10/06 21:10:41 rillig Exp $ -->
+
+<chapter id="intro">
+<title>Introduction</title>
+
+<para>Blubb.</para>
+
+</chapter>
diff --git a/doc/portability-book/files/libraries.xml b/doc/portability-book/files/libraries.xml
new file mode 100644
index 00000000000..ffffac29fbf
--- /dev/null
+++ b/doc/portability-book/files/libraries.xml
@@ -0,0 +1,9 @@
+<!-- $NetBSD: libraries.xml,v 1.1.1.1 2006/10/06 21:10:41 rillig Exp $ -->
+
+<chapter id="libraries">
+<title>C/C++: libraries</title>
+
+<para>This chapter provides information about which libraries are
+available on which platform.</para>
+
+</chapter>
diff --git a/doc/portability-book/files/portability.xml b/doc/portability-book/files/portability.xml
new file mode 100644
index 00000000000..e180eb6c772
--- /dev/null
+++ b/doc/portability-book/files/portability.xml
@@ -0,0 +1,59 @@
+<!-- $NetBSD: portability.xml,v 1.1.1.1 2006/10/06 21:10:41 rillig Exp $ -->
+
+<?xml version="1.0"?>
+<!DOCTYPE book PUBLIC "-//NetBSD//DTD DocBook XML V4.2-Based DocBook Extension//EN" [
+	<!ENTITY % man-refs.ent PUBLIC "-//NetBSD//ENTITIES NetBSD Manual Page Entities//EN">
+	%man-refs.ent;
+	<!ENTITY % misc.ent PUBLIC "-//NetBSD//ENTITIES NetBSD Miscellaneous Entities//EN">
+	%misc.ent;
+	<!ENTITY % chapters SYSTEM "chapters.ent">
+	%chapters;
+
+	<!ENTITY u.PR "http://www.netbsd.org/cgi-bin/query-pr-single.pl?number=">
+]>
+
+<book id="portability">
+  <bookinfo>
+    <title>The pkgsrc portability book</title>
+
+    <authorgroup>
+      <author>
+	<firstname>Roland</firstname>
+	<surname>Illig</surname>
+
+	<affiliation>
+	  <address><email>rillig@NetBSD.org</email></address>
+	</affiliation>
+      </author>
+      <corpauthor>
+        The pkgsrc Developers
+      </corpauthor>
+    </authorgroup>
+
+    <copyright>
+      <year>2006</year>
+
+      <holder role="mailto:www@NetBSD.org">The NetBSD Foundation, Inc.</holder>
+    </copyright>
+
+    <pubdate>2006-10-01</pubdate>
+
+    <abstract>
+
+	<para>pkgsrc is a package management system that has been ported
+	to various POSIX-like operating systems. These systems differ in
+	a lot of small details that are all nice to know when writing
+	code that will later run on as many of these platforms as
+	possible. This book collects some of the limitations, bugs and
+	other characteristics of the pkgsrc platforms.</para>
+
+    </abstract>
+  </bookinfo>
+
+  &chap.intro;
+  &chap.utilities;
+  &chap.headers;
+  &chap.functions;
+  &chap.libraries;
+  &chap.devices;
+</book>
diff --git a/doc/portability-book/files/utilities.xml b/doc/portability-book/files/utilities.xml
new file mode 100644
index 00000000000..8d84a131803
--- /dev/null
+++ b/doc/portability-book/files/utilities.xml
@@ -0,0 +1,134 @@
+<!-- $NetBSD: utilities.xml,v 1.1.1.1 2006/10/06 21:10:41 rillig Exp $ -->
+
+<chapter id="utilities">
+<title>Command line utilities</title>
+
+<para>This chapter collects the various bugs and peculiarities of the
+POSIX-like utilities on the platforms.</para>
+
+<sect1 id="util.sh">
+<title>sh</title>
+
+<sect2 id="util.sh.netbsd">
+<title>NetBSD</title>
+
+<para>On NetBSD, have a look at <ulink
+url="http://www.netbsd.org/cgi-bin/query-pr-list.pl?state=open&amp;state=closed&amp;state=feedback&amp;text=/bin/sh&amp;category=bin">the
+various PRs</ulink> to see what's wrong with the shell.</para>
+
+</sect2>
+
+<sect2 id="util.sh.solaris">
+<title>Solaris</title>
+
+<para>On Solaris, <filename>/bin/sh</filename> is missing some features
+that POSIX <ulink
+url="http://www.opengroup.org/onlinepubs/000095399/utilities/sh.html">requires</ulink>
+for the sh utility:</para>
+
+<programlisting>
+    $ if ! false; then echo ok; fi
+    !: not found
+
+    $ echo ${PWD%/}
+    bad substitution
+
+    $ foo=$(true)
+    syntax error: `foo=$' unexpected
+</programlisting>
+
+<para>There is another sh implementation in
+<filename>/usr/xpg4/bin</filename>, which implements these features.
+However, many shell scripts and other programs have /bin/sh
+hard-coded.</para>
+
+<para>Another incompatibility is this:</para>
+
+<programlisting>
+    $ set -- foo bar baz; echo "before: $#"; set --; echo "after: $#"
+    before: 3
+    after: 3
+</programlisting>
+
+<para>All(?) other shells, including <filename>/usr/xpg4/bin/sh</filename>,
+reply with <quote>after: 0</quote>.</para>
+
+<para>On Solaris, both <filename>/bin/sh</filename> and
+<filename>/usr/xpg4/bin/sh</filename> cannot handle empty for loops.</para>
+
+<programlisting>
+    $ for i in ; do echo "i=$i"; done
+    syntax error: `;' unexpected
+</programlisting>
+
+<para>The work-around is either to add some dummy arguments or to save
+the list of things in a variable. Looping over empty lists is no
+problem. But note that the various parameter expansions that are applied
+here differ in this case.</para>
+
+<programlisting>
+    $ things=""; for i in $things; do echo "i=$i"; done
+</programlisting>
+
+<sect3 id="util.sh.solaris.glob">
+<title>Globbing problems with quoting and hidden files</title>
+
+<programlisting>
+    rm -rf "testdir"
+    mkdir "testdir"
+    touch "testdir/.file"
+
+    x="."
+    y=".file"
+    echo "=== x and y quoted"
+    ls "$x"/*/"$y"
+    echo "=== only x quoted"
+    ls "$x"/*/$y
+    echo "=== nothing quoted"
+    ls $x/*/$y
+</programlisting>
+
+<para>The result of running this code with <filename>/bin/sh</filename>
+is that in the first case, the result of the globbing expansion is
+<quote><literal>./*/.file</literal></quote>, while in the two other
+cases, it is the correct
+<quote><literal>./testdir/.file</literal></quote>. This does only happen
+when y starts with a dot, that is, for hidden files.</para>
+
+</sect3>
+</sect2>
+</sect1>
+
+<sect1 id="util.test">
+<title>test</title>
+
+<sect2 id="util.test.ext">
+<title>Non-standard extensions</title>
+
+<para>The Bourne Again Shell (Bash) allows the binary operator
+<literal>==</literal> to be used as an alias for <literal>=</literal>.
+This leads to problems when programs using this feature are ported to
+other platforms. Furthermore, there is no apparent benefit for having
+two names for the same operator.</para>
+
+</sect2>
+
+<sect2 id="util.test.bugs">
+<title>Bugs</title>
+
+<para>On NetBSD upto X.Y (see <ulink url="&u.PR;34646">PR 34646</ulink>), the &man.test.1; utility cannot
+handle the following:</para>
+
+<programlisting>
+    test ! = foo
+</programlisting>
+
+<para>POSIX <ulink
+url="http://www.opengroup.org/onlinepubs/000095399/utilities/test.html">requires</ulink>
+that when test is called with three arguments, the second operand is
+checked first to see whether it is a binary operator. On NetBSD, the
+unary <quote>!</quote> operator takes precedence.</para>
+
+</sect2>
+</sect1>
+</chapter>