diff options
author | rillig <rillig@pkgsrc.org> | 2006-11-05 09:09:20 +0000 |
---|---|---|
committer | rillig <rillig@pkgsrc.org> | 2006-11-05 09:09:20 +0000 |
commit | 7814f8fc1add5efcc76d09134c8401bcdd3134aa (patch) | |
tree | b350546df99abb0030720662c845ebb78b42f137 /doc | |
parent | 328f48b7e59c623cb0c7aeed7aac72e6b1347f78 (diff) | |
download | pkgsrc-7814f8fc1add5efcc76d09134c8401bcdd3134aa.tar.gz |
Removed the pkgsrc portability book, as editing DocBook XML is no fun at
all. The contents has been moved to the NetBSD wiki at:
http://wiki.aydogan.net/index.php/The_pkgsrc_portability_guide
Diffstat (limited to 'doc')
-rw-r--r-- | doc/portability-book/DESCR | 3 | ||||
-rw-r--r-- | doc/portability-book/Makefile | 93 | ||||
-rw-r--r-- | doc/portability-book/distinfo | 5 | ||||
-rw-r--r-- | doc/portability-book/files/Makefile | 27 | ||||
-rw-r--r-- | doc/portability-book/files/chapters.ent | 10 | ||||
-rw-r--r-- | doc/portability-book/files/devices.xml | 10 | ||||
-rw-r--r-- | doc/portability-book/files/functions.xml | 94 | ||||
-rw-r--r-- | doc/portability-book/files/headers.xml | 9 | ||||
-rw-r--r-- | doc/portability-book/files/intro.xml | 22 | ||||
-rw-r--r-- | doc/portability-book/files/libraries.xml | 9 | ||||
-rw-r--r-- | doc/portability-book/files/portability.xml | 59 | ||||
-rw-r--r-- | doc/portability-book/files/utilities.xml | 200 |
12 files changed, 0 insertions, 541 deletions
diff --git a/doc/portability-book/DESCR b/doc/portability-book/DESCR deleted file mode 100644 index ac2394f239e..00000000000 --- a/doc/portability-book/DESCR +++ /dev/null @@ -1,3 +0,0 @@ -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 deleted file mode 100644 index 04af909a284..00000000000 --- a/doc/portability-book/Makefile +++ /dev/null @@ -1,93 +0,0 @@ -# $NetBSD: Makefile,v 1.2 2006/10/07 09:28:23 rillig Exp $ -# - -DISTNAME= portability-book-${TODAY} -CATEGORIES= # empty -MASTER_SITES= ${MASTER_SITE_LOCAL} -DISTFILES= htdocs-share-20061007.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 deleted file mode 100644 index 88dd9527b93..00000000000 --- a/doc/portability-book/distinfo +++ /dev/null @@ -1,5 +0,0 @@ -$NetBSD: distinfo,v 1.2 2006/10/07 09:28:23 rillig Exp $ - -SHA1 (pkgsrc-guide/htdocs-share-20061007.tar.gz) = b8a57eb2b7d2ae4bc632dca9e2d97ab278010e3a -RMD160 (pkgsrc-guide/htdocs-share-20061007.tar.gz) = 6a135fea1cf25ff83dd53ded17c908911a01d2c3 -Size (pkgsrc-guide/htdocs-share-20061007.tar.gz) = 94100 bytes diff --git a/doc/portability-book/files/Makefile b/doc/portability-book/files/Makefile deleted file mode 100644 index 2d65f090115..00000000000 --- a/doc/portability-book/files/Makefile +++ /dev/null @@ -1,27 +0,0 @@ -# $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 deleted file mode 100644 index 579ea165245..00000000000 --- a/doc/portability-book/files/chapters.ent +++ /dev/null @@ -1,10 +0,0 @@ -<!-- $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 deleted file mode 100644 index 2f3f98b0b42..00000000000 --- a/doc/portability-book/files/devices.xml +++ /dev/null @@ -1,10 +0,0 @@ -<!-- $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 deleted file mode 100644 index 5fb9c5f3366..00000000000 --- a/doc/portability-book/files/functions.xml +++ /dev/null @@ -1,94 +0,0 @@ -<!-- $NetBSD: functions.xml,v 1.4 2006/11/05 07:24:33 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> - -<sect1 id="feature"> -<title>Feature test macros</title> - -<para>When writing code that conforms to a specific standard, some -programmers may want to check that really only features from that -standard are used. For that purpose there exist a number of so-called -feature test macros that can be defined on the command line to the -compiler or in C and C++ source files before including any of the -standard include files.</para> - -<table> -<title>Documentation of the feature test macros</title> -<tgroup cols="2"> -<thead> -<row><entry>Platform</entry><entry>Location</entry></row> -</thead> -<tbody> -<row><entry>SunOS-*-*</entry><entry><literal>standards(5)</literal></entry></row> -<row><entry>NetBSD-*-*</entry><entry><filename>/usr/include/sys/featuretest.h</filename></entry></row> -<row><entry>Linux-*-*</entry><entry><filename>/usr/include/features.h</filename></entry></row> -</tbody> -</tgroup> -</table> - -</sect1> - -<sect1 id="functions.byname"> -<title>Functions on various platforms</title> - -<sect2 id="functions.asprintf"> -<title>asprintf</title> - -<para>Solaris 10 does not have this function. But it has -<literal>snprintf</literal>, which can be used as a good replacement.</para> - -</sect2> - -<sect2 id="functions.getopt"> -<title>getopt</title> - -<para>Solaris provides the <function>getopt</function> function in three -of the standard headers: <stdio.h>, <stdlib.h> and -<unistd.h>, but the latter definition depends on other feature -test macros than the first two. Additionally, since Solaris 5.10, there -is also <getopt.h>, which provides -<function>getopt_long</function>, but not <function>getopt</function>. -The exact behavior also depends on the compiler. While SUNpro is quite -strict and requires the feature test macros, gcc finds the definition -without any of these macros. (TODO: Investigate further.)</para> - -<informaltable> -<tgroup cols="4"> -<thead><row> - <entry>Platform</entry> - <entry>Library</entry> - <entry>Headers</entry> - <entry>Feature test macros</entry> -</row></thead> - -<tbody> -<row> - <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>SunOS-5.10-*</entry> - <entry>c</entry> - <entry>unistd.h</entry> - <entry>(_XOPEN_SOURCE && _XOPEN_VERSION == 4) || __EXTENSIONS__</entry> -</row> -</tbody> -</tgroup> -</informaltable> - -</sect2> - -<sect2 id="functions.nanosleep"> -<title>nanosleep</title> - -<para>On Solaris, the <literal>rt</literal> library is needed.</para> -</sect2> - -</sect1> -</chapter> diff --git a/doc/portability-book/files/headers.xml b/doc/portability-book/files/headers.xml deleted file mode 100644 index a191558058b..00000000000 --- a/doc/portability-book/files/headers.xml +++ /dev/null @@ -1,9 +0,0 @@ -<!-- $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 deleted file mode 100644 index 2b9c243ba8c..00000000000 --- a/doc/portability-book/files/intro.xml +++ /dev/null @@ -1,22 +0,0 @@ -<!-- $NetBSD: intro.xml,v 1.3 2006/10/20 10:15:02 rillig Exp $ --> - -<chapter id="intro"> -<title>Introduction</title> - -<para>Writing programs that are portable to a wide range of platforms -isn't easy. Maybe some platforms are lacking your favorite tool, while -others implemented it, but with arbitrary limitations. Some don't have -such useful functions like <function>snprintf</function> or -<function>strlcpy</function>.</para> - -<para>This book provides information about which features are -<emphasis>not</emphasis> on the platforms, since the features that -<emphasis>are</emphasis> available are already documented quite well. It -also explains how portable shell programs look like, since that's also a -topic that hasn't spread wide yet.</para> - -<para>Since pkgsrc uses the POSIX tools quite a lot, and the packages -using all other features, it's good to know on which platforms a certain -program will not work without further work.</para> - -</chapter> diff --git a/doc/portability-book/files/libraries.xml b/doc/portability-book/files/libraries.xml deleted file mode 100644 index ffffac29fbf..00000000000 --- a/doc/portability-book/files/libraries.xml +++ /dev/null @@ -1,9 +0,0 @@ -<!-- $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 deleted file mode 100644 index e180eb6c772..00000000000 --- a/doc/portability-book/files/portability.xml +++ /dev/null @@ -1,59 +0,0 @@ -<!-- $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 deleted file mode 100644 index f63819651ad..00000000000 --- a/doc/portability-book/files/utilities.xml +++ /dev/null @@ -1,200 +0,0 @@ -<!-- $NetBSD: utilities.xml,v 1.5 2006/11/05 07:24:04 rillig Exp $ --> - -<chapter id="utilities"> -<title>Command line utilities</title> - -<para>This chapter collects the various bugs and peculiarities of the -<ulink url="http://www.opengroup.org/onlinepubs/000095399/idx/utilities.html">POSIX-like -utilities</ulink> on the platforms.</para> - -<sect1 id="util.ls"> -<title>ls</title> - -<para>On MacOS X, <literal>ls</literal> does not return an error -code when the file to be listed does not exist. On some other platforms, -it does.</para> - -</sect1> - -<sect1 id="util.sh"> -<title>sh</title> - -<sect2 id="util.sh.ext"> -<title>Non-standard extensions</title> - -<para>The variable <varname>RANDOM</varname> is an addition of -<filename>ksh</filename>, and <filename>bash</filename> can do it as -well.</para> - -<para>The command <command>[[</command> is an addition of -<filename>ksh</filename>, and <filename>bash</filename> can do it as -well.</para> - -</sect2> - -<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&state=closed&state=feedback&text=/bin/sh&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.options"> -<title>Supported options</title> - -<para>It is expected that the <emphasis>test</emphasis> utility fully -supports the POSIX standard. Any deviations from it are recorded in the -<quote>Unsupported</quote> column.</para> - -<table> -<title>Supported options of the <emphasis>test</emphasis> utility</title> -<tgroup cols="2"> -<thead> -<row><entry>Platform</entry><entry>Unsupported</entry><entry>Supported</entry><entry>Extensions</entry></row> -</thead> -<tbody> -<row><entry>AIX-4.3-powerpc</entry><entry></entry><entry>bcdefghLnprstuwxz</entry><entry>k</entry></row> -<row><entry>IRIX-6.5-mipseb</entry><entry></entry><entry>bcdefghLnprstuwxz</entry><entry>k</entry></row> -<row><entry>Linux-2.6.*-*</entry><entry></entry><entry>bcdefgLnprSstuwxz</entry><entry>GkO nt ot ef</entry></row> -<row><entry>NetBSD-3.0-*</entry><entry></entry><entry>bcdefgLnprSstuwxz</entry><entry>GkO nt ot ef</entry></row> -<row><entry>SunOS-5.10-* /bin/sh</entry><entry>eS</entry><entry>bcdfghLnprstuwz</entry><entry>k</entry></row> -<row><entry>SunOS-5.10-* /bin/test</entry><entry></entry><entry>bcdefgLnprSstuwxz</entry><entry>aGkOo nt ot ef</entry></row> -</tbody> -</tgroup> -</table> - -<para>Remarks:</para> - -<itemizedlist> - -<listitem><para>On Solaris-5.10-*, the behavior of the -<literal>-f</literal> operator depends on the value of the environment -variable <varname>PATH</varname>.</para></listitem> - -<listitem><para>On Solaris-5.10-*, <filename>/usr/ucb/test</filename> -behaves like the builtin command in <filename>/bin/sh</filename>. On the -other hand, <filename>/usr/bin/test</filename> conforms to -POSIX.</para></listitem> - -</itemizedlist> - -</sect2> - -<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. By the way, not even the GNU coreutils have that -<quote>feature</quote>, it's really only Bash that does. After all, -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> |