1 \input texinfo @c -*-texinfo-*-
2 @comment $Id: gnulib.texi,v 1.2 2004-09-23 23:13:19 karl Exp $
3 @comment %**start of header
4 @setfilename gnulib.info
8 @comment %**end of header
10 @set UPDATED $Date: 2004-09-23 23:13:19 $
13 This manual is for GNU Gnulib (updated @value{UPDATED}),
14 which is a library of common routines intended to be shared at the
17 Copyright @copyright{} 2004 Free Software Foundation, Inc.
20 Permission is granted to copy, distribute and/or modify this document
21 under the terms of the GNU Free Documentation License, Version 1.1 or
22 any later version published by the Free Software Foundation; with no
23 Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,''
24 and with the Back-Cover Texts as in (a) below. A copy of the
25 license is included in the section entitled ``GNU Free Documentation
28 (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
29 this GNU Manual, like GNU software. Copies published by the Free
30 Software Foundation raise funds for GNU development.''
34 @dircategory Software development
36 * gnulib: (gnulib). Source files to share among distributions.
41 @subtitle updated @value{UPDATED}
42 @author @email{bug-gnulib@@gnu.org}
44 @vskip 0pt plus 1filll
59 * Invoking gnulib-tool::
60 * Copying This Manual::
68 This is not a real manual. It's just a place to store random notes
69 until someone (you?) gets around to actually writing a manual.
74 @item Gnulib is hosted at Savannah:
75 @url{http://savannah.gnu.org/projects/gnulib}. Get the sources
76 through CVS from there.
77 @item The Gnulib home page:
78 @url{http://www.gnu.org/software/gnulib/}.
85 * Out of memory handling::
91 @cindex comments describing functions
92 @cindex describing functions, locating
93 Where to put comments describing functions: Because of risk of
94 divergence, we prefer to keep most function describing comments in
95 only one place: just above the actual function definition. Some
96 people prefer to put that documentation in the .h file. In any case,
97 it should appear in just one place unless you can ensure that the
98 multiple copies will always remain identical.
105 The @code{ctime} function need not be reentrant, and consequently is
106 not required to be thread safe. Implementations of @code{ctime}
107 typically write the time stamp into static buffer. If two threads
108 call @code{ctime} at roughly the same time, you might end up with the
109 wrong date in one of the threads, or some undefined string. There is
110 a re-entrant interface @code{ctime_r}, that take a pre-allocated
111 buffer and length of the buffer, and return @code{NULL} on errors.
112 The input buffer should be at least 26 bytes in size. The output
113 string is locale-independent. However, years can have more than 4
114 digits if @code{time_t} is sufficiently wide, so the length of the
115 required output buffer is not easy to determine. Increasing the
116 buffer size when @code{ctime_r} return @code{NULL} is not necessarily
117 sufficient. The @code{NULL} return value could mean some other error
118 condition, which will not go away by increasing the buffer size.
120 A more flexible function is @code{strftime}. However, note that it is
128 The @code{inet_ntoa} function need not be reentrant, and consequently
129 is not required to be thread safe. Implementations of
130 @code{inet_ntoa} typically write the time stamp into static buffer.
131 If two threads call @code{inet_ntoa} at roughly the same time, you
132 might end up with the wrong date in one of the threads, or some
133 undefined string. Further, @code{inet_ntoa} is specific for
134 @acronym{IPv4} addresses.
136 A protocol independent function is @code{inet_ntop}.
139 @node Out of memory handling
140 @section Out of memory handling
142 @cindex Out of Memory handling
143 @cindex Memory allocation failure
144 The GSS API does not have a standard error code for the out of memory
145 error condition. Instead of adding a non-standard error code, this
146 library has chosen to adopt a different strategy. Out of memory
147 handling happens in rare situations, but performing the out of memory
148 error handling after almost all API function invocations pollute your
149 source code and might make it harder to spot more serious problems.
150 The strategy chosen improve code readability and robustness.
152 @cindex Aborting execution
153 For most applications, aborting the application with an error message
154 when the out of memory situation occur is the best that can be wished
155 for. This is how the library behaves by default.
157 @vindex xalloc_fail_func
158 However, we realize that some applications may not want to have the
159 GSS library abort execution in any situation. The GSS library support
160 a hook to let the application regain control and perform its own
161 cleanups when an out of memory situation has occured. The application
162 can define a function (having a @code{void} prototype, i.e., no return
163 value and no parameters) and set the library variable
164 @code{xalloc_fail_func} to that function. The variable should be
168 extern void (*xalloc_fail_func) (void);
171 The GSS library will invoke this function if an out of memory error
172 occurs. Note that after this the GSS library is in an undefined
173 state, so you must unload or restart the application to continue call
174 GSS library functions. The hook is only intended to allow the
175 application to log the situation in a special way. Of course, care
176 must be taken to not allocate more memory, as that will likely also
180 @node Invoking gnulib-tool
181 @chapter Invoking gnulib-tool
184 @cindex invoking @command{gnulib-tool}
186 Run @samp{gnulib-tool --help}, and use the source.
187 @command{gnulib-tool} is the way to import Gnulib modules.
190 * Initial import:: First import of Gnulib modules.
191 * Importing updated files:: Subsequent imports.
192 * Finishing touches:: Simplifying imports.
197 @section Initial import
198 @cindex initial import
200 Gnulib assumes your project uses Autoconf and Automake. Invoking
201 @samp{gnulib-tool --import} will copy source files, create a
202 @file{Makefile.am} to build them, and generate a @file{gnulib.m4} with
203 Autoconf M4 macro declarations used by @file{configure.ac}.
205 Our example will be a library that uses Autoconf, Automake and
206 Libtool. It calls @code{strdup}, and you wish to use gnulib to make
207 the package portable to C89 (which doesn't have @code{strdup}).
210 ~/src/libfoo$ gnulib-tool --import strdup
211 Module list with included dependencies:
218 Creating ./lib/Makefile.am...
219 Creating ./m4/gnulib.m4...
222 Don't forget to add "lib/Makefile"
223 to AC_CONFIG_FILES in "./configure.ac" and to mention
224 "lib" in SUBDIRS in some Makefile.am.
228 By default, the source code is copied into @file{lib/} and the M4
229 macros in @file{m4/}. You can override these paths by using
230 @code{--source-base=DIRECTORY} and @code{--m4-base=DIRECTORY}, or by
231 adding @samp{gl_SOURCE_BASE(DIRECTORY)} and
232 @samp{gl_M4_BASE(DIRECTORY)} to your @file{configure.ac}.
234 @code{gnulib-tool} will overwrite any pre-existing files, in
235 particular @file{Makefile.am}. Unfortunately, separating the
236 generated @file{Makefile.am} content (for building the gnulib library)
237 into a separate file, say @file{gnulib.mk}, that could be included
238 by your handwritten @file{Makefile.am} is not possible, due to how
239 variable assignments are handled by Automake.
241 Consequently, it can be a good idea to chose directories that are not
242 already used by your projects, to separate gnulib imported files from
243 your own files. This approach can also be useful if you want to avoid
244 conflicts between other tools (e.g., @code{getextize} that also copy
245 M4 files into your package. Simon Josefsson successfully uses a source
246 base of @file{gl/}, and a M4 base of @file{gl/m4/}, in several
249 A few manual steps are required to finish the initial import.
251 First, you need to make sure Autoconf can find the macro definitions
252 in @file{gnulib.m4}. Use the @code{ACLOCAL_AMFLAGS} specifier in your
253 top-level @file{Makefile.am} file, as in:
256 ACLOCAL_AMFLAGS = -I m4
259 Naturally, replace @file{m4} with the value from @code{--m4-base} or
260 @code{gl_M4_BASE}. If the M4 base is @file{gl/m4} you would use:
263 ACLOCAL_AMFLAGS = -I gl/m4
266 You are now ready to call the M4 macros in @code{gnulib.m4} from
267 @file{configure.ac}. The macro @code{gl_EARLY} must be called as soon
268 as possible after verifying that the C compiler is working.
269 Typically, this is immediately after @code{AC_PROG_CC}, as in:
278 The core part of the gnulib checks are done by the macro
279 @code{gl_INIT}. Place it further down in the file, typically where
280 you normally check for header files or functions. Or in a separate
281 section with other gnulib statements, such as @code{gl_SOURCE_BASE}.
291 You must also make sure that the gnulib library is built. Add the
292 @code{Makefile} in the gnulib source base directory to
293 @code{AC_CONFIG_FILES}, as in:
296 AC_CONFIG_FILES(... lib/Makefile ...)
299 If your gnulib source base is @file{gl}, you would use:
302 AC_CONFIG_FILES(... gl/Makefile ...)
305 You must also make sure that @code{make} work in the gnulib directory.
306 Add the gnulib source base directory to a @code{SUBDIRS} Makefile.am
313 or if you, more likely, already have a few entries in @code{SUBDIRS},
314 you can add something like:
320 If you are using a gnulib source base of @code{gl}, you would use:
326 Finally, you have add C flags and LD flags, so that you can make use
327 of the gnulib library. For example:
331 AM_CPPFLAGS = -I$(top_srcdir)/lib
333 LIBADD = lib/libgnu.la
337 Don't forget to @code{#include} the various header files. In this
338 example, you would need to make sure that @samp{#include <strdup.h>}
339 is evaluated when compiling all source code files, that want to make
340 use of @code{strdup}.
343 @node Importing updated files
344 @section Importing updated files
346 From time to time, you may want to invoke @samp{gnulib-tool --import}
347 to update the files in your package. Once you have set up your
348 package for gnulib, this step is quite simple. For example:
351 ~/src/libfoo$ gnulib-tool --import --source-base gl --m4-base gl/m4 strdup
352 Module list with included dependencies:
359 Creating ./lib/Makefile.am...
360 Creating ./m4/gnulib.m4...
363 Don't forget to add "lib/Makefile"
364 to AC_CONFIG_FILES in "./configure.ac" and to mention
365 "lib" in SUBDIRS in some Makefile.am.
369 If you don't recall how you invoked the tool last time, the commands
370 used (and the operations it resulted in) are placed in comments within
371 the generated @file{Makefile.am} and @file{gnulib.m4}, as in:
375 # Invoked as: gnulib-tool --import strdup
376 # Reproduce by: gnulib-tool --import --dir=. --lib=libgnu --source-base=lib --m4-base=m4 --libtool strdup
381 @node Finishing touches
382 @section Finishing touches
384 Invoking @samp{gnulib-tool --import} with the proper parameters (e.g.,
385 @samp{--m4-base gl/m4}) and list of modules (e.g., @samp{strdup
386 snprintf getline minmax}) can be tedious. To simplify this procedure,
387 you may put the command line parameters in your @file{configure.ac}.
399 gl_MODULES(getopt progname strdup dummy exit error getpass-gnu getaddrinfo)
404 This illustrate all macros defined in @file{gnulib.m4}. With the
405 above, importing new files are as simple as running @samp{gnulib-tool
406 --import} with no additional parameters.
408 The macros @code{gl_EARLY}, @code{gl_INIT}, @code{gl_SOURCE_BASE}, and
409 @code{gl_M4_BASE} have been discussed earlier. The @code{gl_LIB}
410 macro can be used if you wish to change the library name (by default
411 @file{libgnu.a} or @file{libgnu.la} if you use libtool). The
412 @code{gl_MODULES} macro is used to specify which modules to import.
415 @node Copying This Manual
416 @appendix Copying This Manual
419 * GNU Free Documentation License:: License for copying this manual.