\input texinfo @c -*-texinfo-*-
-@comment $Id: gnulib.texi,v 1.19 2005-09-19 15:48:03 haible Exp $
+@comment $Id: gnulib.texi,v 1.31 2007-01-03 18:51:20 karl Exp $
@comment %**start of header
@setfilename gnulib.info
@settitle GNU Gnulib
@syncodeindex pg cp
@comment %**end of header
-@set UPDATED $Date: 2005-09-19 15:48:03 $
+@set UPDATED $Date: 2007-01-03 18:51:20 $
@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, 2005 Free Software Foundation, Inc.
+Copyright @copyright{} 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
-@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation; with no
-Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,''
-and with the Back-Cover Texts as in (a) below. A copy of the
-license is included in the section entitled ``GNU Free Documentation
-License.''
-
-(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
-this GNU Manual, like GNU software. Copies published by the Free
-Software Foundation raise funds for GNU development.''
-@end quotation
+Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
+Texts. A copy of the license is included in the section entitled
+``GNU Free Documentation License.''
@end copying
@dircategory Software development
@end ifnottex
@menu
-* Gnulib::
+* Introduction::
* Invoking gnulib-tool::
+* Miscellaneous Notes::
+* Particular Modules:: Documentation of Individual Modules
* Copying This Manual::
* Index::
@end menu
+@node Introduction
+@chapter Introduction
-@node Gnulib
-@chapter Gnulib
+Gnulib is a source code library. It provides basic functionalities to
+programs and libraries. Currently (as of October 2006) more than 30
+packages make use of Gnulib.
-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:
+Resources:
@itemize
@item Gnulib is hosted at Savannah:
@end itemize
@menu
+* Library vs. Reusable Code::
+* Portability and Application Code::
+* Modules::
+* Various Kinds of Modules::
+* Collaborative Development::
+* Copyright::
+* Steady Development::
+* Openness::
+@end menu
+
+@include gnulib-intro.texi
+
+
+@include gnulib-tool.texi
+
+
+@node Miscellaneous Notes
+@chapter Miscellaneous Notes
+
+@menu
* Comments::
* Header files::
-* Quoting::
-* ctime::
-* inet_ntoa::
* Out of memory handling::
* Library version handling::
-* Regular expressions::
+* Windows sockets::
+* Libtool and Windows::
+* License Texinfo sources::
@end menu
@end itemize
-@include quote.texi
-
-
-@include ctime.texi
-
-
-@include inet_ntoa.texi
-
-
@node Out of memory handling
@section Out of memory handling
However, we realize that some applications may not want to have the
GSS library abort execution in any situation. The GSS library support
a hook to let the application regain control and perform its own
-cleanups when an out of memory situation has occured. The application
+cleanups when an out of memory situation has occurred. The application
can define a function (having a @code{void} prototype, i.e., no return
value and no parameters) and set the library variable
@code{xalloc_fail_func} to that function. The variable should be
AC_DEFINE something like:
@example
-AC_DEFINE(check_version, stringprep_check_version, [Rename check_version.])
+AC_DEFINE(check_version, stringprep_check_version,
+ [Rename check_version.])
@end example
The @code{stringprep_check_version} function will thus be implemented
@end example
+@node Windows sockets
+@section Windows sockets
+
+There are several issues when building applications that should work
+under Windows. The most problematic part is for applications that use
+sockets.
+
+Hopefully, we can add helpful notes to this section that will help you
+port your application to Windows using gnulib.
+
+@subsection Getaddrinfo and WINVER
+
+This was written for the getaddrinfo module, but may be applicable to
+other functions too.
+
+The getaddrinfo function exists in ws2tcpip.h and -lws2_32 on Windows
+XP. The function declaration is present if @code{WINVER >= 0x0501}.
+Windows 2000 does not have getaddrinfo in its @file{WS2_32.dll}.
+
+Thus, if you want to assume Windows XP or later, you can add
+AC_DEFINE(WINVER, 0x0501) to avoid compiling to (partial) getaddrinfo
+implementation.
+
+If you want to support Windows 2000, don't do anything, but be aware
+that gnulib will use its own (partial) getaddrinfo implementation even
+on Windows XP. Currently the code does not attempt to determine if
+the getaddrinfo function is available during runtime.
+
+Todo: Make getaddrinfo.c open the WS2_32.DLL and check for the
+getaddrinfo symbol and use it if present, otherwise fall back to our
+own implementation.
+
+
+@node Libtool and Windows
+@section Libtool and Windows
+
+If you want it to be possible to cross-compile your program to MinGW
+and you use Libtool, you need to put:
+
+@example
+AC_LIBTOOL_WIN32_DLL
+@end example
+
+in your @file{configure.ac}. This sets the correct names for the
+@code{OBJDUMP}, @code{DLLTOOL}, and @code{AS} tools for the build.
+
+If you are building a library, you will also need to pass
+@code{-no-undefined} to make sure Libtool produces a DLL for your
+library. From a @file{Makefile.am}:
+
+@example
+libgsasl_la_LDFLAGS += -no-undefined
+@end example
+
+
+@node License Texinfo sources
+@section License Texinfo sources
+
+Gnulib provides copies of the GNU GPL, GNU LGPL, and GNU FDL licenses
+in Texinfo form. (The master location is
+@url{http://www.gnu.org/licenses/}). These Texinfo documents have
+various node names and structures built into them; for your manual,
+you might like to change these. It's ok to do this, and a convenient
+way to do so is to use a context diff and the @option{--local-dir}
+option to @command{gnulib-tool}.
+
+Of course the license texts themselves should not be changed at all.
+
+
+@node Particular Modules
+@chapter Particular Modules
+
+@menu
+* Quoting::
+* ctime::
+* error and progname::
+* gcd::
+* inet_ntoa::
+* Regular expressions::
+@end menu
+
+@include quote.texi
+@include error.texi
+@include ctime.texi
+@include gcd.texi
+@include inet_ntoa.texi
+
@node Regular expressions
@section Regular expressions
@include regexprops-generic.texi
-@include gnulib-tool.texi
-
-
@node Copying This Manual
@appendix Copying This Manual