\input texinfo @c -*-texinfo-*-
-@comment $Id: gnulib.texi,v 1.2 2004-09-23 23:13:19 karl Exp $
+@comment $Id: gnulib.texi,v 1.9 2005-05-23 11:05:53 jas Exp $
@comment %**start of header
@setfilename gnulib.info
@settitle GNU Gnulib
@syncodeindex pg cp
@comment %**end of header
-@set UPDATED $Date: 2004-09-23 23:13:19 $
+@set UPDATED $Date: 2005-05-23 11:05:53 $
@copying
This manual is for GNU Gnulib (updated @value{UPDATED}),
which is a library of common routines intended to be shared at the
source level.
-Copyright @copyright{} 2004 Free Software Foundation, Inc.
+Copyright @copyright{} 2004, 2005 Free Software Foundation, Inc.
@quotation
Permission is granted to copy, distribute and/or modify this document
@dircategory Software development
@direntry
-* gnulib: (gnulib). Source files to share among distributions.
+* Gnulib: (gnulib). Source files to share among distributions.
@end direntry
@titlepage
@node Gnulib
@chapter Gnulib
-This is not a real manual. It's just a place to store random notes
-until someone (you?) gets around to actually writing a manual.
+This manual contains some bare-bones documentation, but not much more.
+It's mostly been a place to store notes until someone (you?) gets
+around to writing a coherent manual.
Getting started:
@menu
* Comments::
+* Header files::
* ctime::
* inet_ntoa::
* Out of memory handling::
multiple copies will always remain identical.
+@node Header files
+@section Header files
+
+@cindex double inclusion of header files
+@cindex header file include protection
+It is a tradition to use CPP tricks to avoid parsing the same header
+file more than once, which might cause warnings. The trick is to wrap
+the content of the header file (say, @file{foo.h}) in a block, as in:
+
+@example
+#ifndef FOO_H
+# define FOO_H
+...
+body of header file goes here
+...
+#endif /* FOO_H */
+@end example
+
+Whether to use @code{FOO_H} or @code{_FOO_H} is a matter of taste and
+style. The C89 and C99 standards reserve all identifiers that begin with an
+underscore and either an uppercase letter or another underscore, for
+any use. Thus, in theory, an application might not safely assume that
+@code{_FOO_H} has not already been defined by a library. On the other
+hand, using @code{FOO_H} will likely lead the higher risk of
+collisions with other symbols (e.g., @code{KEY_H}, @code{XK_H}, @code{BPF_H},
+which are CPP macro constants, or @code{COFF_LONG_H}, which is a CPP
+macro function). Your preference may depend on whether you consider
+the header file under discussion as part of the application (which has
+its own namespace for CPP symbols) or a supporting library (that
+shouldn't interfere with the application's CPP symbol namespace).
+
+@cindex C++ header files
+@cindex Header files and C++
+Adapting C header files for use in C++ applications can use another
+CPP trick, as in:
+
+@example
+# ifdef __cplusplus
+extern "C"
+@{
+# endif
+...
+body of header file goes here
+...
+# ifdef __cplusplus
+@}
+# endif
+@end example
+
+The idea here is that @code{__cplusplus} is defined only by C++
+implementations, which will wrap the header file in an @samp{extern "C"}
+block. Again, whether to use this trick is a matter of taste and
+style. While the above can be seen as harmless, it could be argued
+that the header file is written in C, and any C++ application using it
+should explicitly use the @samp{extern "C"} block itself. Your
+preference might depend on whether you consider the API exported by
+your header file as something available for C programs only, or for C
+and C++ programs alike.
+
+@subsection Include ordering
+
+When writing a gnulib module, or even in general, a good way to order
+the @samp{#include} directives is the following.
+
+@itemize
+@item First comes the #include "..." specifying the module being implemented.
+@item Then come all the #include <...> of system or system-replacement headers,
+in arbitrary order.
+@item Then come all the #include "..." of gnulib and private headers, in
+arbitrary order.
+@end itemize
+
@node ctime
@section ctime
@findex ctime
Creating ./m4/gnulib.m4...
Finished.
+You may need to add #include directives for the following .h files.
+ #include "strdup.h"
+
Don't forget to add "lib/Makefile"
to AC_CONFIG_FILES in "./configure.ac" and to mention
"lib" in SUBDIRS in some Makefile.am.
@code{--source-base=DIRECTORY} and @code{--m4-base=DIRECTORY}, or by
adding @samp{gl_SOURCE_BASE(DIRECTORY)} and
@samp{gl_M4_BASE(DIRECTORY)} to your @file{configure.ac}.
+Some modules also provide other files necessary
+for building. These files are copied into the directory specified
+by @samp{AC_CONFIG_AUX_DIR} in @file{configure.ac} or by the
+@code{--aux-dir=DIRECTORY} option. If neither is specified, the
+current directory is assumed.
+
+@code{gnulib-tool} can make symbolic links instead
+of copying the source files. Use the @code{--symbolic}
+(or @code{-s} for short) option to do this.
@code{gnulib-tool} will overwrite any pre-existing files, in
particular @file{Makefile.am}. Unfortunately, separating the
SUBDIRS += gl
@end example
-Finally, you have add C flags and LD flags, so that you can make use
+Finally, you have to add compiler and linker flags in the appropriate
+source directories, so that you can make use
of the gnulib library. For example:
@example
...
AM_CPPFLAGS = -I$(top_srcdir)/lib
...
-LIBADD = lib/libgnu.la
+LIBADD = lib/libgnu.a
...
@end example