Mercurial > hg > octave-nkf > gnulib-hg
annotate doc/gnulib.texi @ 5883:19bb5e876a29
Add "Include ordering", based on e-mail from Bruno.
| author | Simon Josefsson <simon@josefsson.org> |
|---|---|
| date | Mon, 23 May 2005 11:05:53 +0000 |
| parents | 0e974fb1c99e |
| children | 14697da96543 |
| rev | line source |
|---|---|
| 5239 | 1 \input texinfo @c -*-texinfo-*- |
|
5883
19bb5e876a29
Add "Include ordering", based on e-mail from Bruno.
Simon Josefsson <simon@josefsson.org>
parents:
5870
diff
changeset
|
2 @comment $Id: gnulib.texi,v 1.9 2005-05-23 11:05:53 jas Exp $ |
| 5239 | 3 @comment %**start of header |
| 4 @setfilename gnulib.info | |
| 5 @settitle GNU Gnulib | |
|
5256
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
6 @syncodeindex fn cp |
| 5239 | 7 @syncodeindex pg cp |
| 8 @comment %**end of header | |
| 9 | |
|
5883
19bb5e876a29
Add "Include ordering", based on e-mail from Bruno.
Simon Josefsson <simon@josefsson.org>
parents:
5870
diff
changeset
|
10 @set UPDATED $Date: 2005-05-23 11:05:53 $ |
| 5239 | 11 |
| 12 @copying | |
| 13 This manual is for GNU Gnulib (updated @value{UPDATED}), | |
| 14 which is a library of common routines intended to be shared at the | |
| 15 source level. | |
| 16 | |
| 5870 | 17 Copyright @copyright{} 2004, 2005 Free Software Foundation, Inc. |
| 5239 | 18 |
| 19 @quotation | |
| 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 | |
| 26 License.'' | |
| 27 | |
| 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.'' | |
| 31 @end quotation | |
| 32 @end copying | |
| 33 | |
| 34 @dircategory Software development | |
| 35 @direntry | |
| 5257 | 36 * Gnulib: (gnulib). Source files to share among distributions. |
| 5239 | 37 @end direntry |
| 38 | |
| 39 @titlepage | |
| 40 @title GNU Gnulib | |
| 41 @subtitle updated @value{UPDATED} | |
| 42 @author @email{bug-gnulib@@gnu.org} | |
| 43 @page | |
| 44 @vskip 0pt plus 1filll | |
| 45 @insertcopying | |
| 46 @end titlepage | |
| 47 | |
| 48 @contents | |
| 49 | |
| 50 @ifnottex | |
| 51 @node Top | |
| 52 @top GNU Gnulib | |
| 53 | |
| 54 @insertcopying | |
| 55 @end ifnottex | |
| 56 | |
| 57 @menu | |
| 58 * Gnulib:: | |
| 59 * Invoking gnulib-tool:: | |
| 60 * Copying This Manual:: | |
| 61 * Index:: | |
| 62 @end menu | |
| 63 | |
| 64 | |
| 65 @node Gnulib | |
| 66 @chapter Gnulib | |
| 67 | |
| 5870 | 68 This manual contains some bare-bones documentation, but not much more. |
| 69 It's mostly been a place to store notes until someone (you?) gets | |
| 70 around to writing a coherent manual. | |
| 5239 | 71 |
| 72 Getting started: | |
| 73 | |
| 74 @itemize | |
| 75 @item Gnulib is hosted at Savannah: | |
| 76 @url{http://savannah.gnu.org/projects/gnulib}. Get the sources | |
| 77 through CVS from there. | |
| 78 @item The Gnulib home page: | |
| 79 @url{http://www.gnu.org/software/gnulib/}. | |
| 80 @end itemize | |
| 81 | |
| 82 @menu | |
| 83 * Comments:: | |
|
5260
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
84 * Header files:: |
| 5239 | 85 * ctime:: |
| 86 * inet_ntoa:: | |
| 87 * Out of memory handling:: | |
| 88 @end menu | |
| 89 | |
| 90 @node Comments | |
| 91 @section Comments | |
| 92 | |
| 93 @cindex comments describing functions | |
| 94 @cindex describing functions, locating | |
| 95 Where to put comments describing functions: Because of risk of | |
| 96 divergence, we prefer to keep most function describing comments in | |
| 97 only one place: just above the actual function definition. Some | |
| 98 people prefer to put that documentation in the .h file. In any case, | |
| 99 it should appear in just one place unless you can ensure that the | |
| 100 multiple copies will always remain identical. | |
| 101 | |
| 102 | |
|
5260
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
103 @node Header files |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
104 @section Header files |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
105 |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
106 @cindex double inclusion of header files |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
107 @cindex header file include protection |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
108 It is a tradition to use CPP tricks to avoid parsing the same header |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
109 file more than once, which might cause warnings. The trick is to wrap |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
110 the content of the header file (say, @file{foo.h}) in a block, as in: |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
111 |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
112 @example |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
113 #ifndef FOO_H |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
114 # define FOO_H |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
115 ... |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
116 body of header file goes here |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
117 ... |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
118 #endif /* FOO_H */ |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
119 @end example |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
120 |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
121 Whether to use @code{FOO_H} or @code{_FOO_H} is a matter of taste and |
|
5261
95f7304acdac
Minor fixups to previous patch.
Paul Eggert <eggert@cs.ucla.edu>
parents:
5260
diff
changeset
|
122 style. The C89 and C99 standards reserve all identifiers that begin with an |
|
5260
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
123 underscore and either an uppercase letter or another underscore, for |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
124 any use. Thus, in theory, an application might not safely assume that |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
125 @code{_FOO_H} has not already been defined by a library. On the other |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
126 hand, using @code{FOO_H} will likely lead the higher risk of |
| 5269 | 127 collisions with other symbols (e.g., @code{KEY_H}, @code{XK_H}, @code{BPF_H}, |
| 128 which are CPP macro constants, or @code{COFF_LONG_H}, which is a CPP | |
| 129 macro function). Your preference may depend on whether you consider | |
|
5260
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
130 the header file under discussion as part of the application (which has |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
131 its own namespace for CPP symbols) or a supporting library (that |
|
5261
95f7304acdac
Minor fixups to previous patch.
Paul Eggert <eggert@cs.ucla.edu>
parents:
5260
diff
changeset
|
132 shouldn't interfere with the application's CPP symbol namespace). |
|
5260
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
133 |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
134 @cindex C++ header files |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
135 @cindex Header files and C++ |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
136 Adapting C header files for use in C++ applications can use another |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
137 CPP trick, as in: |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
138 |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
139 @example |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
140 # ifdef __cplusplus |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
141 extern "C" |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
142 @{ |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
143 # endif |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
144 ... |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
145 body of header file goes here |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
146 ... |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
147 # ifdef __cplusplus |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
148 @} |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
149 # endif |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
150 @end example |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
151 |
|
5261
95f7304acdac
Minor fixups to previous patch.
Paul Eggert <eggert@cs.ucla.edu>
parents:
5260
diff
changeset
|
152 The idea here is that @code{__cplusplus} is defined only by C++ |
|
95f7304acdac
Minor fixups to previous patch.
Paul Eggert <eggert@cs.ucla.edu>
parents:
5260
diff
changeset
|
153 implementations, which will wrap the header file in an @samp{extern "C"} |
|
5260
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
154 block. Again, whether to use this trick is a matter of taste and |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
155 style. While the above can be seen as harmless, it could be argued |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
156 that the header file is written in C, and any C++ application using it |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
157 should explicitly use the @samp{extern "C"} block itself. Your |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
158 preference might depend on whether you consider the API exported by |
|
5261
95f7304acdac
Minor fixups to previous patch.
Paul Eggert <eggert@cs.ucla.edu>
parents:
5260
diff
changeset
|
159 your header file as something available for C programs only, or for C |
|
5260
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
160 and C++ programs alike. |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
161 |
|
5883
19bb5e876a29
Add "Include ordering", based on e-mail from Bruno.
Simon Josefsson <simon@josefsson.org>
parents:
5870
diff
changeset
|
162 @subsection Include ordering |
|
19bb5e876a29
Add "Include ordering", based on e-mail from Bruno.
Simon Josefsson <simon@josefsson.org>
parents:
5870
diff
changeset
|
163 |
|
19bb5e876a29
Add "Include ordering", based on e-mail from Bruno.
Simon Josefsson <simon@josefsson.org>
parents:
5870
diff
changeset
|
164 When writing a gnulib module, or even in general, a good way to order |
|
19bb5e876a29
Add "Include ordering", based on e-mail from Bruno.
Simon Josefsson <simon@josefsson.org>
parents:
5870
diff
changeset
|
165 the @samp{#include} directives is the following. |
|
19bb5e876a29
Add "Include ordering", based on e-mail from Bruno.
Simon Josefsson <simon@josefsson.org>
parents:
5870
diff
changeset
|
166 |
|
19bb5e876a29
Add "Include ordering", based on e-mail from Bruno.
Simon Josefsson <simon@josefsson.org>
parents:
5870
diff
changeset
|
167 @itemize |
|
19bb5e876a29
Add "Include ordering", based on e-mail from Bruno.
Simon Josefsson <simon@josefsson.org>
parents:
5870
diff
changeset
|
168 @item First comes the #include "..." specifying the module being implemented. |
|
19bb5e876a29
Add "Include ordering", based on e-mail from Bruno.
Simon Josefsson <simon@josefsson.org>
parents:
5870
diff
changeset
|
169 @item Then come all the #include <...> of system or system-replacement headers, |
|
19bb5e876a29
Add "Include ordering", based on e-mail from Bruno.
Simon Josefsson <simon@josefsson.org>
parents:
5870
diff
changeset
|
170 in arbitrary order. |
|
19bb5e876a29
Add "Include ordering", based on e-mail from Bruno.
Simon Josefsson <simon@josefsson.org>
parents:
5870
diff
changeset
|
171 @item Then come all the #include "..." of gnulib and private headers, in |
|
19bb5e876a29
Add "Include ordering", based on e-mail from Bruno.
Simon Josefsson <simon@josefsson.org>
parents:
5870
diff
changeset
|
172 arbitrary order. |
|
19bb5e876a29
Add "Include ordering", based on e-mail from Bruno.
Simon Josefsson <simon@josefsson.org>
parents:
5870
diff
changeset
|
173 @end itemize |
|
19bb5e876a29
Add "Include ordering", based on e-mail from Bruno.
Simon Josefsson <simon@josefsson.org>
parents:
5870
diff
changeset
|
174 |
| 5239 | 175 @node ctime |
| 176 @section ctime | |
| 177 @findex ctime | |
| 178 | |
| 179 The @code{ctime} function need not be reentrant, and consequently is | |
| 180 not required to be thread safe. Implementations of @code{ctime} | |
| 181 typically write the time stamp into static buffer. If two threads | |
| 182 call @code{ctime} at roughly the same time, you might end up with the | |
| 183 wrong date in one of the threads, or some undefined string. There is | |
| 184 a re-entrant interface @code{ctime_r}, that take a pre-allocated | |
| 185 buffer and length of the buffer, and return @code{NULL} on errors. | |
| 186 The input buffer should be at least 26 bytes in size. The output | |
| 187 string is locale-independent. However, years can have more than 4 | |
| 188 digits if @code{time_t} is sufficiently wide, so the length of the | |
| 189 required output buffer is not easy to determine. Increasing the | |
| 190 buffer size when @code{ctime_r} return @code{NULL} is not necessarily | |
| 191 sufficient. The @code{NULL} return value could mean some other error | |
| 192 condition, which will not go away by increasing the buffer size. | |
| 193 | |
| 194 A more flexible function is @code{strftime}. However, note that it is | |
| 195 locale dependent. | |
| 196 | |
| 197 | |
| 198 @node inet_ntoa | |
| 199 @section inet_ntoa | |
| 200 @findex inet_ntoa | |
| 201 | |
| 202 The @code{inet_ntoa} function need not be reentrant, and consequently | |
| 203 is not required to be thread safe. Implementations of | |
| 204 @code{inet_ntoa} typically write the time stamp into static buffer. | |
| 205 If two threads call @code{inet_ntoa} at roughly the same time, you | |
| 206 might end up with the wrong date in one of the threads, or some | |
| 207 undefined string. Further, @code{inet_ntoa} is specific for | |
| 208 @acronym{IPv4} addresses. | |
| 209 | |
| 210 A protocol independent function is @code{inet_ntop}. | |
| 211 | |
| 212 | |
| 213 @node Out of memory handling | |
| 214 @section Out of memory handling | |
| 215 | |
| 216 @cindex Out of Memory handling | |
| 217 @cindex Memory allocation failure | |
| 218 The GSS API does not have a standard error code for the out of memory | |
| 219 error condition. Instead of adding a non-standard error code, this | |
| 220 library has chosen to adopt a different strategy. Out of memory | |
| 221 handling happens in rare situations, but performing the out of memory | |
| 222 error handling after almost all API function invocations pollute your | |
| 223 source code and might make it harder to spot more serious problems. | |
| 224 The strategy chosen improve code readability and robustness. | |
| 225 | |
| 226 @cindex Aborting execution | |
| 227 For most applications, aborting the application with an error message | |
| 228 when the out of memory situation occur is the best that can be wished | |
| 229 for. This is how the library behaves by default. | |
| 230 | |
| 231 @vindex xalloc_fail_func | |
| 232 However, we realize that some applications may not want to have the | |
| 233 GSS library abort execution in any situation. The GSS library support | |
| 234 a hook to let the application regain control and perform its own | |
| 235 cleanups when an out of memory situation has occured. The application | |
| 236 can define a function (having a @code{void} prototype, i.e., no return | |
| 237 value and no parameters) and set the library variable | |
| 238 @code{xalloc_fail_func} to that function. The variable should be | |
| 239 declared as follows. | |
| 240 | |
| 241 @example | |
| 242 extern void (*xalloc_fail_func) (void); | |
| 243 @end example | |
| 244 | |
| 245 The GSS library will invoke this function if an out of memory error | |
| 246 occurs. Note that after this the GSS library is in an undefined | |
| 247 state, so you must unload or restart the application to continue call | |
| 248 GSS library functions. The hook is only intended to allow the | |
| 249 application to log the situation in a special way. Of course, care | |
| 250 must be taken to not allocate more memory, as that will likely also | |
| 251 fail. | |
| 252 | |
| 253 | |
| 254 @node Invoking gnulib-tool | |
| 255 @chapter Invoking gnulib-tool | |
| 256 | |
| 257 @pindex gnulib-tool | |
| 258 @cindex invoking @command{gnulib-tool} | |
| 259 | |
| 260 Run @samp{gnulib-tool --help}, and use the source. | |
| 261 @command{gnulib-tool} is the way to import Gnulib modules. | |
| 262 | |
|
5256
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
263 @menu |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
264 * Initial import:: First import of Gnulib modules. |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
265 * Importing updated files:: Subsequent imports. |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
266 * Finishing touches:: Simplifying imports. |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
267 @end menu |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
268 |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
269 |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
270 @node Initial import |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
271 @section Initial import |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
272 @cindex initial import |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
273 |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
274 Gnulib assumes your project uses Autoconf and Automake. Invoking |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
275 @samp{gnulib-tool --import} will copy source files, create a |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
276 @file{Makefile.am} to build them, and generate a @file{gnulib.m4} with |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
277 Autoconf M4 macro declarations used by @file{configure.ac}. |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
278 |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
279 Our example will be a library that uses Autoconf, Automake and |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
280 Libtool. It calls @code{strdup}, and you wish to use gnulib to make |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
281 the package portable to C89 (which doesn't have @code{strdup}). |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
282 |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
283 @example |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
284 ~/src/libfoo$ gnulib-tool --import strdup |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
285 Module list with included dependencies: |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
286 strdup |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
287 File list: |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
288 lib/strdup.c |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
289 lib/strdup.h |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
290 m4/onceonly_2_57.m4 |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
291 m4/strdup.m4 |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
292 Creating ./lib/Makefile.am... |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
293 Creating ./m4/gnulib.m4... |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
294 Finished. |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
295 |
|
5802
94a03274f562
(Initial import): Fix. Mention --aux-dir.
Simon Josefsson <simon@josefsson.org>
parents:
5269
diff
changeset
|
296 You may need to add #include directives for the following .h files. |
|
94a03274f562
(Initial import): Fix. Mention --aux-dir.
Simon Josefsson <simon@josefsson.org>
parents:
5269
diff
changeset
|
297 #include "strdup.h" |
|
94a03274f562
(Initial import): Fix. Mention --aux-dir.
Simon Josefsson <simon@josefsson.org>
parents:
5269
diff
changeset
|
298 |
|
5256
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
299 Don't forget to add "lib/Makefile" |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
300 to AC_CONFIG_FILES in "./configure.ac" and to mention |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
301 "lib" in SUBDIRS in some Makefile.am. |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
302 ~/src/libfoo$ |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
303 @end example |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
304 |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
305 By default, the source code is copied into @file{lib/} and the M4 |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
306 macros in @file{m4/}. You can override these paths by using |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
307 @code{--source-base=DIRECTORY} and @code{--m4-base=DIRECTORY}, or by |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
308 adding @samp{gl_SOURCE_BASE(DIRECTORY)} and |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
309 @samp{gl_M4_BASE(DIRECTORY)} to your @file{configure.ac}. |
|
5802
94a03274f562
(Initial import): Fix. Mention --aux-dir.
Simon Josefsson <simon@josefsson.org>
parents:
5269
diff
changeset
|
310 Some modules also provide other files necessary |
|
94a03274f562
(Initial import): Fix. Mention --aux-dir.
Simon Josefsson <simon@josefsson.org>
parents:
5269
diff
changeset
|
311 for building. These files are copied into the directory specified |
|
94a03274f562
(Initial import): Fix. Mention --aux-dir.
Simon Josefsson <simon@josefsson.org>
parents:
5269
diff
changeset
|
312 by @samp{AC_CONFIG_AUX_DIR} in @file{configure.ac} or by the |
|
94a03274f562
(Initial import): Fix. Mention --aux-dir.
Simon Josefsson <simon@josefsson.org>
parents:
5269
diff
changeset
|
313 @code{--aux-dir=DIRECTORY} option. If neither is specified, the |
|
94a03274f562
(Initial import): Fix. Mention --aux-dir.
Simon Josefsson <simon@josefsson.org>
parents:
5269
diff
changeset
|
314 current directory is assumed. |
|
94a03274f562
(Initial import): Fix. Mention --aux-dir.
Simon Josefsson <simon@josefsson.org>
parents:
5269
diff
changeset
|
315 |
|
94a03274f562
(Initial import): Fix. Mention --aux-dir.
Simon Josefsson <simon@josefsson.org>
parents:
5269
diff
changeset
|
316 @code{gnulib-tool} can make symbolic links instead |
|
94a03274f562
(Initial import): Fix. Mention --aux-dir.
Simon Josefsson <simon@josefsson.org>
parents:
5269
diff
changeset
|
317 of copying the source files. Use the @code{--symbolic} |
|
94a03274f562
(Initial import): Fix. Mention --aux-dir.
Simon Josefsson <simon@josefsson.org>
parents:
5269
diff
changeset
|
318 (or @code{-s} for short) option to do this. |
|
5256
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
319 |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
320 @code{gnulib-tool} will overwrite any pre-existing files, in |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
321 particular @file{Makefile.am}. Unfortunately, separating the |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
322 generated @file{Makefile.am} content (for building the gnulib library) |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
323 into a separate file, say @file{gnulib.mk}, that could be included |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
324 by your handwritten @file{Makefile.am} is not possible, due to how |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
325 variable assignments are handled by Automake. |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
326 |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
327 Consequently, it can be a good idea to chose directories that are not |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
328 already used by your projects, to separate gnulib imported files from |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
329 your own files. This approach can also be useful if you want to avoid |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
330 conflicts between other tools (e.g., @code{getextize} that also copy |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
331 M4 files into your package. Simon Josefsson successfully uses a source |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
332 base of @file{gl/}, and a M4 base of @file{gl/m4/}, in several |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
333 packages. |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
334 |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
335 A few manual steps are required to finish the initial import. |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
336 |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
337 First, you need to make sure Autoconf can find the macro definitions |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
338 in @file{gnulib.m4}. Use the @code{ACLOCAL_AMFLAGS} specifier in your |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
339 top-level @file{Makefile.am} file, as in: |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
340 |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
341 @example |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
342 ACLOCAL_AMFLAGS = -I m4 |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
343 @end example |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
344 |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
345 Naturally, replace @file{m4} with the value from @code{--m4-base} or |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
346 @code{gl_M4_BASE}. If the M4 base is @file{gl/m4} you would use: |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
347 |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
348 @example |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
349 ACLOCAL_AMFLAGS = -I gl/m4 |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
350 @end example |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
351 |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
352 You are now ready to call the M4 macros in @code{gnulib.m4} from |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
353 @file{configure.ac}. The macro @code{gl_EARLY} must be called as soon |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
354 as possible after verifying that the C compiler is working. |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
355 Typically, this is immediately after @code{AC_PROG_CC}, as in: |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
356 |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
357 @example |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
358 ... |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
359 AC_PROG_CC |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
360 gl_EARLY |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
361 ... |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
362 @end example |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
363 |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
364 The core part of the gnulib checks are done by the macro |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
365 @code{gl_INIT}. Place it further down in the file, typically where |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
366 you normally check for header files or functions. Or in a separate |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
367 section with other gnulib statements, such as @code{gl_SOURCE_BASE}. |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
368 For example: |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
369 |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
370 @example |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
371 ... |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
372 # For gnulib. |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
373 gl_INIT |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
374 ... |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
375 @end example |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
376 |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
377 You must also make sure that the gnulib library is built. Add the |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
378 @code{Makefile} in the gnulib source base directory to |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
379 @code{AC_CONFIG_FILES}, as in: |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
380 |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
381 @example |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
382 AC_CONFIG_FILES(... lib/Makefile ...) |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
383 @end example |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
384 |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
385 If your gnulib source base is @file{gl}, you would use: |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
386 |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
387 @example |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
388 AC_CONFIG_FILES(... gl/Makefile ...) |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
389 @end example |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
390 |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
391 You must also make sure that @code{make} work in the gnulib directory. |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
392 Add the gnulib source base directory to a @code{SUBDIRS} Makefile.am |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
393 statement, as in: |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
394 |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
395 @example |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
396 SUBDIRS = lib |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
397 @end example |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
398 |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
399 or if you, more likely, already have a few entries in @code{SUBDIRS}, |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
400 you can add something like: |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
401 |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
402 @example |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
403 SUBDIRS += lib |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
404 @end example |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
405 |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
406 If you are using a gnulib source base of @code{gl}, you would use: |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
407 |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
408 @example |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
409 SUBDIRS += gl |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
410 @end example |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
411 |
| 5870 | 412 Finally, you have to add compiler and linker flags in the appropriate |
| 413 source directories, so that you can make use | |
|
5256
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
414 of the gnulib library. For example: |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
415 |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
416 @example |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
417 ... |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
418 AM_CPPFLAGS = -I$(top_srcdir)/lib |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
419 ... |
| 5870 | 420 LIBADD = lib/libgnu.a |
|
5256
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
421 ... |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
422 @end example |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
423 |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
424 Don't forget to @code{#include} the various header files. In this |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
425 example, you would need to make sure that @samp{#include <strdup.h>} |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
426 is evaluated when compiling all source code files, that want to make |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
427 use of @code{strdup}. |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
428 |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
429 |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
430 @node Importing updated files |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
431 @section Importing updated files |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
432 |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
433 From time to time, you may want to invoke @samp{gnulib-tool --import} |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
434 to update the files in your package. Once you have set up your |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
435 package for gnulib, this step is quite simple. For example: |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
436 |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
437 @example |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
438 ~/src/libfoo$ gnulib-tool --import --source-base gl --m4-base gl/m4 strdup |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
439 Module list with included dependencies: |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
440 strdup |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
441 File list: |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
442 lib/strdup.c |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
443 lib/strdup.h |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
444 m4/onceonly_2_57.m4 |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
445 m4/strdup.m4 |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
446 Creating ./lib/Makefile.am... |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
447 Creating ./m4/gnulib.m4... |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
448 Finished. |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
449 |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
450 Don't forget to add "lib/Makefile" |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
451 to AC_CONFIG_FILES in "./configure.ac" and to mention |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
452 "lib" in SUBDIRS in some Makefile.am. |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
453 ~/src/libfoo$ |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
454 @end example |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
455 |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
456 If you don't recall how you invoked the tool last time, the commands |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
457 used (and the operations it resulted in) are placed in comments within |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
458 the generated @file{Makefile.am} and @file{gnulib.m4}, as in: |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
459 |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
460 @example |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
461 ... |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
462 # Invoked as: gnulib-tool --import strdup |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
463 # Reproduce by: gnulib-tool --import --dir=. --lib=libgnu --source-base=lib --m4-base=m4 --libtool strdup |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
464 ... |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
465 @end example |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
466 |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
467 |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
468 @node Finishing touches |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
469 @section Finishing touches |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
470 |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
471 Invoking @samp{gnulib-tool --import} with the proper parameters (e.g., |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
472 @samp{--m4-base gl/m4}) and list of modules (e.g., @samp{strdup |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
473 snprintf getline minmax}) can be tedious. To simplify this procedure, |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
474 you may put the command line parameters in your @file{configure.ac}. |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
475 For example: |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
476 |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
477 @example |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
478 ... |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
479 AC_PROG_CC |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
480 gl_EARLY |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
481 ... |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
482 # For gnulib. |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
483 gl_SOURCE_BASE(gl) |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
484 gl_M4_BASE(gl/m4) |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
485 gl_LIB(libgl) |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
486 gl_MODULES(getopt progname strdup dummy exit error getpass-gnu getaddrinfo) |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
487 gl_INIT |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
488 ... |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
489 @end example |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
490 |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
491 This illustrate all macros defined in @file{gnulib.m4}. With the |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
492 above, importing new files are as simple as running @samp{gnulib-tool |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
493 --import} with no additional parameters. |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
494 |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
495 The macros @code{gl_EARLY}, @code{gl_INIT}, @code{gl_SOURCE_BASE}, and |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
496 @code{gl_M4_BASE} have been discussed earlier. The @code{gl_LIB} |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
497 macro can be used if you wish to change the library name (by default |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
498 @file{libgnu.a} or @file{libgnu.la} if you use libtool). The |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
499 @code{gl_MODULES} macro is used to specify which modules to import. |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
500 |
| 5239 | 501 |
| 502 @node Copying This Manual | |
| 503 @appendix Copying This Manual | |
| 504 | |
| 505 @menu | |
| 506 * GNU Free Documentation License:: License for copying this manual. | |
| 507 @end menu | |
| 508 | |
| 509 @include fdl.texi | |
| 510 | |
| 511 | |
| 512 @node Index | |
| 513 @unnumbered Index | |
| 514 | |
| 515 @printindex cp | |
| 516 | |
| 517 @bye |