X-Git-Url: http://erislabs.net/gitweb/?a=blobdiff_plain;f=doc%2Fgnulib-intro.texi;h=efac23d4ed0eadc9813f166ff51309813a4c4210;hb=578b78a0f92cb6732d1b76d76933b376be85de55;hp=557d67ff7b18c1b1614daff084f222871c5d3be0;hpb=a1130afc30629e2597bb81e7c9752073df9174e3;p=gnulib.git diff --git a/doc/gnulib-intro.texi b/doc/gnulib-intro.texi index 557d67ff7..efac23d4e 100644 --- a/doc/gnulib-intro.texi +++ b/doc/gnulib-intro.texi @@ -26,15 +26,15 @@ access functions to the kernel's system calls, and little more. There is no clear borderline between both areas. For example, Gnulib has a facility for generating the name of backup -files. While this task is entirely at the application level---no -standard specifies an API for it---the na@"{@dotless{i}}ve code has +files. While this task is entirely at the application level --- no +standard specifies an API for it --- the na@"{@dotless{i}}ve code has some portability problems because on some platforms the length of file name components is limited to 30 characters or so. Gnulib handles that. Similarly, Gnulib has a facility for executing a command in a subprocess. It is at the same time a portability enhancement (it -works on GNU/Unix and Windows, compared to the classical +works on GNU, Unix, and Windows, compared to the classical @code{fork()}/@code{exec()} which is not portable to Windows), as well as an application aid: it takes care of redirecting stdin and/or stdout if desired, and emits an error message if the subprocess @@ -44,7 +44,7 @@ failed. @section Modules Gnulib is divided into modules. Every module implements a single -facility. Modules can depend on other modules. +facility. Modules can depend on other modules. A module consists of a number of files and a module description. The files are copied by @code{gnulib-tool} into the package that will use it, @@ -53,13 +53,13 @@ reside in the @file{lib/} subdirectory. Autoconf macro files reside in the @file{m4/} subdirectory. Build scripts reside in the @file{build-aux/} subdirectory. -The module description contains the list of files---@code{gnulib-tool} +The module description contains the list of files --- @code{gnulib-tool} copies these files. It contains the module's -dependencies---@code{gnulib-tool} installs them as well. It also +dependencies --- @code{gnulib-tool} installs them as well. It also contains the autoconf macro invocation (usually a single line or -nothing at all)---@code{gnulib-tool} ensures this is invoked from the +nothing at all) --- @code{gnulib-tool} ensures this is invoked from the package's @file{configure.ac} file. And also a @file{Makefile.am} -snippet---@code{gnulib-tool} collects these into a @file{Makefile.am} +snippet --- @code{gnulib-tool} collects these into a @file{Makefile.am} for the tailored Gnulib part. The module description and include file specification are for documentation purposes; they are combined into @file{MODULES.html}. @@ -70,8 +70,8 @@ The module system serves two purposes: @item It ensures consistency of the used autoconf macros and @file{Makefile.am} rules with the source code. For example, source code which uses the -@code{getopt_long} function---this is a common way to implement parsing -of command line options in a way that complies with the GNU standards--- +@code{getopt_long} function --- this is a common way to implement parsing +of command line options in a way that complies with the GNU standards --- needs the source code (@file{lib/getopt.c} and others), the autoconf macro which detects whether the system's libc already has this function (in @file{m4/getopt.m4}), and a few @file{Makefile.am} lines that create the @@ -146,17 +146,17 @@ header file the system's one is used. @subsection Enhancements of ISO C or POSIX functions These are sometimes POSIX functions with GNU extensions also found in -glibc--examples: @samp{getopt}, @samp{fnmatch}---and often new -APIs---for example, for all functions that allocate memory in one way +glibc --- examples: @samp{getopt}, @samp{fnmatch} --- and often new +APIs --- for example, for all functions that allocate memory in one way or the other, we have variants which also include the error checking against the out-of-memory condition. @subsection Portable general use facilities -Examples are a module for copying a file---the portability problems +Examples are a module for copying a file --- the portability problems relate to the copying of the file's modification time, access rights, -and extended attributes---or a module for extracting the tail -component of a file name---here the portability to Woe32 requires a +and extended attributes --- or a module for extracting the tail +component of a file name --- here the portability to Woe32 requires a different API than the classical POSIX @code{basename} function. @subsection Reusable application code @@ -214,6 +214,49 @@ reasonably be used in libraries, are under LGPL. The source files always say "GPL", but the real license specification is in the module description file. +More precisely, the license specification in the module description +file applies to the files in @file{lib/} and @file{build-aux/}. Different +licenses apply to files in special directories: + +@table @file +@item modules/ +Module description files are under this copyright: + +@quotation +Copyright @copyright{} 200X-200Y Free Software Foundation, Inc.@* +Copying and distribution of this file, with or without modification, +in any medium, are permitted without royalty provided the copyright +notice and this notice are preserved. +@end quotation + +@item m4/ +Autoconf macro files are under this copyright: + +@quotation +Copyright @copyright{} 200X-200Y Free Software Foundation, Inc.@* +This file is free software; the Free Software Foundation +gives unlimited permission to copy and/or distribute it, +with or without modifications, as long as this notice is preserved. +@end quotation + +@item tests/ +If a license statement is not present in a test module, the test files are +under GPL. Even if the corresponding source module is under LGPL, this is +not a problem, since compiled tests are not installed by ``make install''. + +@item doc/ +Documentation files are under this copyright: + +@quotation +Copyright @copyright{} 200X-200Y Free Software Foundation, Inc.@* +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 no Front-Cover Texts, and with no Back-Cover +Texts. +@end quotation +@end table + If you want to use some Gnulib modules under LGPL, you can do so by passing the option @samp{--lgpl} to @code{gnulib-tool}. This will replace the GPL header with an LGPL header while copying the source