[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
GNU Coding Standards tools
From: |
Eric Blake |
Subject: |
GNU Coding Standards tools |
Date: |
Fri, 7 Nov 2008 21:09:15 +0000 (UTC) |
User-agent: |
Loom/3.14 (http://gmane.org/) |
I'm thinking of adding the following patch, so that all of the tools mentioned
in GNU Coding Standards at least have a mention (our manual mentions more tools
than GNU Coding Standards requires, but without this patch, it doesn't provide
complete coverage). We can add known portability problems later. Thoughts?
>From 9e72b3ed89057e52a0feaa441cdcb873d2e11816 Mon Sep 17 00:00:00 2001
From: Eric Blake <address@hidden>
Date: Fri, 7 Nov 2008 14:03:21 -0700
Subject: [PATCH] Provide a section on all tools allowed in GNU Coding Standards.
* doc/autoconf.texi (Limitations of Builtins) <read>: Sort.
<wait>: Add section.
(Limitations of Usual Tools) <awk>: Make table entry consistent.
<chgrp, mkfifo, rmdir, sleep, sort, tar> Add sections.
Signed-off-by: Eric Blake <address@hidden>
---
ChangeLog | 6 ++++
doc/autoconf.texi | 79 +++++++++++++++++++++++++++++++++++++++++++++++------
2 files changed, 76 insertions(+), 9 deletions(-)
diff --git a/ChangeLog b/ChangeLog
index 4f8bdd8..8c11265 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,11 @@
2008-11-07 Eric Blake <address@hidden>
+ Provide a section on all tools allowed in GNU Coding Standards.
+ * doc/autoconf.texi (Limitations of Builtins) <read>: Sort.
+ <wait>: Add section.
+ (Limitations of Usual Tools) <awk>: Make table entry consistent.
+ <chgrp, mkfifo, rmdir, sleep, sort, tar> Add sections.
+
Further doc updates for AC_CHECK_HEADER change.
* doc/autoconf.texi (Generic Headers) <AC_CHECK_HEADER>: Mention
new default, and make it more obvious that using [-] is generally
diff --git a/doc/autoconf.texi b/doc/autoconf.texi
index 14f891e..73ee539 100644
--- a/doc/autoconf.texi
+++ b/doc/autoconf.texi
@@ -14710,6 +14710,8 @@ Limitations of Builtins
the @samp{x} into account later in the pipe. Many of these limitations
can be worked around using M4sh (@pxref{Programming in M4sh}).
address@hidden This table includes things like address@hidden (files)', so we
can't
address@hidden use @table @command.
@table @asis
@item @command{.}
@c --------------
@@ -15290,12 +15292,6 @@ Limitations of Builtins
core.
address@hidden @command{read}
address@hidden ------------------
address@hidden @command{read}
-Not all shells support @option{-r} (Solaris @command{/bin/sh} for example).
-
-
@item @command{pwd}
@c ----------------
@prindex @command{pwd}
@@ -15334,6 +15330,12 @@ Limitations of Builtins
Also please see the discussion of the @command{cd} command.
address@hidden @command{read}
address@hidden -----------------
address@hidden @command{read}
+Not all shells support @option{-r} (Solaris @command{/bin/sh} for example).
+
+
@item @command{set}
@c ----------------
@prindex @command{set}
@@ -15635,6 +15637,11 @@ Limitations of Builtins
@xref{Special Shell Variables}, for some neutralizing values. Also, see
@ref{Limitations of Builtins}, documentation of @command{export}, for
the case of environment variables.
+
address@hidden @command{wait}
address@hidden -----------------
address@hidden @command{wait}
+The exit status of @command{wait} is not always reliable.
@end table
@node Limitations of Usual Tools
@@ -15644,10 +15651,16 @@ Limitations of Usual Tools
The small set of tools you can expect to find on any machine can still
include some limitations you should be aware of.
address@hidden Between this list and the list of builtins above, we should
address@hidden mention all the tools in GNU Coding Standards ``Utilities in
address@hidden Makefiles''.
+
address@hidden This table includes things like address@hidden (|)', so we can't
address@hidden use @table @command.
@table @asis
address@hidden Awk
address@hidden ------
address@hidden Awk
address@hidden @command{awk}
address@hidden ----------------
address@hidden @command{awk}
Don't leave white space before the opening parenthesis in a user function call.
Posix does not allow this and @acronym{GNU} Awk rejects it:
@@ -15857,6 +15870,13 @@ Limitations of Usual Tools
@samp{$(CC)}, so the value of the @samp{CC} make variable selects the
compiler name.
address@hidden @command{chgrp}
address@hidden @command{chown}
address@hidden -------------------
address@hidden @command{chgrp}
address@hidden @command{chown}
+It is not portable to change a file's group to a group that the owner
+does not belong to.
@item @command{chmod}
@c ------------------
@@ -16333,6 +16353,20 @@ Limitations of Usual Tools
OK, but copies from older versions are vulnerable.
address@hidden @command{mkfifo}
address@hidden @command{mknod}
address@hidden -------------------
address@hidden @command{mkfifo}
address@hidden @command{mknod}
+The GNU Coding Standards state that @command{mknod} is safe to use on
+platforms where it has been tested to exist; but it is generally portable
+only for creating named FIFOs, since device numbers are
+platform-specific. Autotest uses @command{mkfifo} to implement parallel
+testsuites. Posix states that behavior is unspecified when opening a
+named FIFO for both reading and writing; on at least Cygwin, this
+results in failure on any attempt to read or write to that file
+descriptor.
+
@item @command{mktemp}
@c -------------------
@prindex @command{mktemp}
@@ -16436,6 +16470,11 @@ Limitations of Usual Tools
support commands like @samp{rm foo >foo}, even though this is
perfectly portable among Posix hosts.
address@hidden @command{rmdir}
address@hidden ------------------
address@hidden @command{rmdir}
+Just as with @command{rm}, some platforms refuse to remove a working
+directory.
@item @command{sed}
@c ----------------
@@ -16682,6 +16721,28 @@ Limitations of Usual Tools
:end
@end example
address@hidden @command{sleep}
address@hidden ------------------
address@hidden @command{sleep}
+Using @command{sleep} is generally portable. However, remember that
+adding a @command{sleep} to work around timestamp issues, with a minimum
+granularity of one second, doesn't scale well for parallel builds on
+modern machines with sub-second process completion.
+
address@hidden @command{sort}
address@hidden -----------------
address@hidden @command{sort}
+Remember that sort order is influenced by the current locale. Inside
address@hidden, the C locale is in effect, but in Makefile snippets,
+you may need to specify @code{LC_ALL=C sort}.
+
address@hidden @command{tar}
address@hidden ----------------
address@hidden @command{tar}
+There are multiple file formats for @command{tar}; if you use Automake,
+the macro @code{AM_INIT_AUTOMAKE} has some options controlling which
+level of portability to use.
+
@item @command{touch}
@c ------------------
@prindex @command{touch}
--
1.6.0.2
- GNU Coding Standards tools,
Eric Blake <=