]> Savannah Git Hosting - gnulib.git/commitdiff
doc: Mention requirement regarding #include syntax.
authorBruno Haible <bruno@clisp.org>
Sun, 18 Feb 2024 12:17:38 +0000 (13:17 +0100)
committerBruno Haible <bruno@clisp.org>
Sun, 18 Feb 2024 12:17:38 +0000 (13:17 +0100)
* doc/gnulib-tool.texi (-I options, Include <config.h>,
Style of #include statements): New subsections.

ChangeLog
doc/gnulib-tool.texi

index f048c91af50dc371c86b76b9e6ffa92d17f2c2f6..f09e8197079f63e7ee848bef614d36f7324dd87c 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,9 @@
+2024-02-18  Bruno Haible  <bruno@clisp.org>
+
+       doc: Mention requirement regarding #include syntax.
+       * doc/gnulib-tool.texi (-I options, Include <config.h>,
+       Style of #include statements): New subsections.
+
 2024-02-17  Paul Eggert  <eggert@cs.ucla.edu>
 
        qsort_r-tests: minor visibility cleanup
index 55a2b32a9a537ed0bea93f2b405acd723acc3ce1..5626ce9d53c6a8d4bb742b6d047f8320f76afa51 100644 (file)
@@ -434,6 +434,12 @@ your project.
 @node Source changes
 @section Changing your sources for use with Gnulib
 
+When you use Gnulib, you need to make some small changes to your source code
+base.
+
+@node -I options
+@subsection -I options
+
 Gnulib contains some header file overrides.  This means that when building
 on systems with deficient header files in @file{/usr/include/}, it may create
 files named @file{string.h}, @file{stdlib.h}, @file{stdint.h} or similar in
@@ -442,6 +448,9 @@ will usually pass @samp{-I} options to the compiler, so that these Gnulib
 substitutes are visible and take precedence over the files in
 @file{/usr/include/}.
 
+@node Include <config.h>
+@subsection Include <config.h>
+
 These Gnulib substitute header files rely on @file{<config.h>} being
 already included.  Furthermore @file{<config.h>} must be the first include
 in every compilation unit.  This means that to @emph{all your source files}
@@ -454,6 +463,91 @@ This is annoying, but inevitable: On many systems, @file{<config.h>} is
 used to set system dependent flags (such as @code{_GNU_SOURCE} on GNU systems),
 and these flags have no effect after any system header file has been included.
 
+@node Style of #include statements
+@subsection Style of #include statements
+
+When including including specific header files, you need to use the
+@samp{#include <...>} syntax, not the @samp{#include "..."} syntax.
+This is true for the following POSIX or ISO C standardized header files:
+@itemize @asis
+@item @code{arpa/inet.h}
+@item @code{assert.h}
+@item @code{ctype.h}
+@item @code{dirent.h}
+@item @code{errno.h}
+@item @code{fcntl.h}
+@item @code{fenv.h}
+@item @code{float.h}
+@item @code{fnmatch.h}
+@item @code{glob.h}
+@item @code{iconv.h}
+@item @code{inttypes.h}
+@item @code{langinfo.h}
+@item @code{limits.h}
+@item @code{locale.h}
+@item @code{math.h}
+@item @code{monetary.h}
+@item @code{netdb.h}
+@item @code{net/if.h}
+@item @code{netinet/in.h}
+@item @code{poll.h}
+@item @code{pthread.h}
+@item @code{sched.h}
+@item @code{search.h}
+@item @code{signal.h}
+@item @code{spawn.h}
+@item @code{stdalign.h}
+@item @code{stdarg.h}
+@item @code{stddef.h}
+@item @code{stdint.h}
+@item @code{stdio.h}
+@item @code{stdlib.h}
+@item @code{string.h}
+@item @code{strings.h}
+@item @code{sys/msg.h}
+@item @code{sys/resource.h}
+@item @code{sys/select.h}
+@item @code{sys/sem.h}
+@item @code{sys/shm.h}
+@item @code{sys/socket.h}
+@item @code{sys/stat.h}
+@item @code{sys/time.h}
+@item @code{sys/times.h}
+@item @code{sys/types.h}
+@item @code{sys/uio.h}
+@item @code{sys/utsname.h}
+@item @code{sys/wait.h}
+@item @code{termios.h}
+@item @code{threads.h}
+@item @code{time.h}
+@item @code{uchar.h}
+@item @code{unistd.h}
+@item @code{utime.h}
+@item @code{wchar.h}
+@item @code{wctype.h}
+@end itemize
+@noindent
+as well as for the following header files that exist in the GNU C library
+but are not standardized:
+@itemize @asis
+@item @code{alloca.h}
+@item @code{error.h}
+@item @code{getopt.h}
+@item @code{malloc.h}
+@item @code{omp.h}
+@item @code{pty.h}
+@item @code{selinux/selinux.h}
+@item @code{sys/file.h}
+@item @code{sys/ioctl.h}
+@item @code{sys/random.h}
+@item @code{sysexits.h}
+@item @code{utmp.h}
+@end itemize
+@noindent
+The reason for this requirement is that for these header files, the Gnulib
+override uses @code{#include_next} to include the system-provided header
+of the same name, and @code{#include_next} may not work right with the
+@samp{#include "..."} syntax.
 
 @node Link-time requirements
 @section Changing your link commands for use with Gnulib