X-Git-Url: http://erislabs.net/gitweb/?a=blobdiff_plain;ds=sidebyside;f=doc%2Fgnulib.texi;h=34353d3eb2a20efc9fea46f74a4fd5acf8d9da28;hb=75e3b3670b7703b47beeeb923cc4f246693dc7d9;hp=9ecca8183a88912b8facd9599e2c6b54d0bbd84f;hpb=9923a4664ef3dfc9d3d74ef9fff00bcd16a434d7;p=gnulib.git diff --git a/doc/gnulib.texi b/doc/gnulib.texi index 9ecca8183..34353d3eb 100644 --- a/doc/gnulib.texi +++ b/doc/gnulib.texi @@ -1,5 +1,5 @@ \input texinfo @c -*-texinfo-*- -@comment $Id: gnulib.texi,v 1.5 2004-09-28 22:58:00 eggert Exp $ +@comment $Id: gnulib.texi,v 1.10 2005-06-27 22:36:50 jas Exp $ @comment %**start of header @setfilename gnulib.info @settitle GNU Gnulib @@ -7,14 +7,14 @@ @syncodeindex pg cp @comment %**end of header -@set UPDATED $Date: 2004-09-28 22:58:00 $ +@set UPDATED $Date: 2005-06-27 22:36:50 $ @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 @@ -65,8 +65,9 @@ Software Foundation raise funds for GNU development.'' @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: @@ -84,6 +85,7 @@ Getting started: * ctime:: * inet_ntoa:: * Out of memory handling:: +* Library version handling:: @end menu @node Comments @@ -123,8 +125,9 @@ 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{COFF_LONG_H} which is a CPP -macro function). Your preference may depeend on whether you consider +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). @@ -157,6 +160,19 @@ 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 @@ -236,6 +252,51 @@ must be taken to not allocate more memory, as that will likely also fail. +@node Library version handling +@section Library version handling + +The module ``check_version'' can be useful when your gnulib +application is a system library. You will typically wrap the call to +the @code{check_version} function through a library API, your library +header file may contain: + +@example +#define STRINGPREP_VERSION "0.5.18" +... + extern const char *stringprep_check_version (const char *req_version); +@end example + +The implementation of @code{stringprep_check_version} would simply +pass on the call to @code{check_version}. + +There are two uses of the interface. The first is a way to provide +for applications to find out the version number of the library it +uses. The application may contain diagnostic code such as: + +@example + printf ("Stringprep version: header %s library %s", + STRINGPREP_VERSION, + stringprep_check_version (NULL)); +@end example + +Separating the library and header file version can be useful when +searching for version mismatch related problems. + +The second uses is as a rudimentary test of proper library version, by +making sure the application get a library version that is the same, or +newer, than the header file used when building the application. This +doesn't catch all problems, libraries may change backwards incompatibly +in later versions, but enable applications to require a certain +minimum version before it may proceed. + +Typical uses look like: + +@example + /* Check version of libgcrypt. */ + if (!gcry_check_version (GCRYPT_VERSION)) + die ("version mismatch\n"); +@end example + @node Invoking gnulib-tool @chapter Invoking gnulib-tool @@ -278,6 +339,9 @@ Creating ./lib/Makefile.am... 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. @@ -289,6 +353,15 @@ macros in @file{m4/}. You can override these paths by using @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 @@ -382,14 +455,15 @@ If you are using a gnulib source base of @code{gl}, you would use: 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