X-Git-Url: http://erislabs.net/gitweb/?a=blobdiff_plain;ds=sidebyside;f=doc%2Fgnulib.texi;h=683bc94774b78aeb8296e2ed0df81b249fda5578;hb=eee009073c7e98c56ad5d8b8f9a7e583e7460012;hp=897d8eae0e025b4cfe0cf18e2a47336fee887b5d;hpb=e198412802cd9796992efdac69c3590958bde1be;p=gnulib.git diff --git a/doc/gnulib.texi b/doc/gnulib.texi index 897d8eae0..683bc9477 100644 --- a/doc/gnulib.texi +++ b/doc/gnulib.texi @@ -1,5 +1,5 @@ \input texinfo @c -*-texinfo-*- -@comment $Id: gnulib.texi,v 1.24 2006-07-10 06:37:33 rwild Exp $ +@comment $Id: gnulib.texi,v 1.33 2007-03-15 22:58:36 eggert Exp $ @comment %**start of header @setfilename gnulib.info @settitle GNU Gnulib @@ -7,28 +7,21 @@ @syncodeindex pg cp @comment %**end of header -@set UPDATED $Date: 2006-07-10 06:37:33 $ +@set UPDATED $Date: 2007-03-15 22:58:36 $ @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, 2006 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 @@ -55,21 +48,22 @@ Software Foundation raise funds for GNU 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: @@ -80,16 +74,34 @@ Getting started: @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:: -* gcd:: * Out of memory handling:: * Library version handling:: -* Regular expressions:: * Windows sockets:: +* Libtool and Windows:: +* License Texinfo sources:: +* Build robot for gnulib:: @end menu @@ -179,15 +191,6 @@ arbitrary order. @end itemize -@include quote.texi - -@include ctime.texi - -@include gcd.texi - -@include inet_ntoa.texi - - @node Out of memory handling @section Out of memory handling @@ -284,17 +287,6 @@ Typical uses look like: @end example -@node Regular expressions -@section Regular expressions - -Gnulib supports many different types of regular expressions; although -the underlying features are the same or identical, the syntax used -varies. The descriptions given here for the different types are -generated automatically. - -@include regexprops-generic.texi - - @node Windows sockets @section Windows sockets @@ -327,7 +319,129 @@ 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. -@include gnulib-tool.texi + +@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 Build robot for gnulib +@section Build robot for gnulib + +To simplify testing on a wide set of platforms, gnulib is built on +many platforms every day and the results are uploaded to: + +@url{http://autobuild.josefsson.org/gnulib/} + +If you wish to help the gnulib development effort with build logs for +your favorite platform, you may perform these steps: + +@enumerate + +@item Create gnulib directory + +On a machine with recent automake, autoconf, m4 installed and with a +gnulib cvs checkout (typically a Linux machine), use + +@example +gnulib-tool --create-megatestdir --with-tests --dir=..." +@end example + +Note: The created directory uses ca. 512 MB on disk. + +@item Transfer gnulib directory + +Transfer this directory to a build machine (HP-UX, Cygwin, or +whatever). Often it is easier to transfer one file, and this can be +achieved by running, inside the directory the following commands: + +@example +./configure +make dist +@end example + +And then transferring the @file{dummy-0.tar.gz} file. + +@item Build modules + +On the build machine, run ./autobuild (or "nohup ./autobuild"). It +creates a directory 'logs/' with a log file for each module. + +@item Submit build logs + +Submit each log file to Simon's site, either through a + +@example +mail `echo gnulib__at__autobuild.josefsson.org | sed -e s/__at__/@/` +@end example + +or through netcat + +@example +autobuild-submit logs/* +@end example + +@end enumerate + +@node Particular Modules +@chapter Particular Modules + +@menu +* Quoting:: +* ctime:: +* error and progname:: +* gcd:: +* inet_ntoa:: +* Regular expressions:: +* Supporting Relocation:: +@end menu + +@include quote.texi +@include error.texi +@include ctime.texi +@include gcd.texi +@include inet_ntoa.texi +@include relocatable-maint.texi + +@node Regular expressions +@section Regular expressions + +Gnulib supports many different types of regular expressions; although +the underlying features are the same or identical, the syntax used +varies. The descriptions given here for the different types are +generated automatically. + +@include regexprops-generic.texi @node Copying This Manual