Mercurial > hg > octave-nkf > gnulib-hg
annotate doc/gnulib.texi @ 5802:94a03274f562
(Initial import): Fix. Mention --aux-dir.
| author | Simon Josefsson <simon@josefsson.org> |
|---|---|
| date | Mon, 18 Apr 2005 20:58:20 +0000 |
| parents | 7ce2f4babcdc |
| children | 0e974fb1c99e |
| rev | line source |
|---|---|
| 5239 | 1 \input texinfo @c -*-texinfo-*- |
|
5802
94a03274f562
(Initial import): Fix. Mention --aux-dir.
Simon Josefsson <simon@josefsson.org>
parents:
5269
diff
changeset
|
2 @comment $Id: gnulib.texi,v 1.7 2005-04-18 20:58:20 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 | |
|
5802
94a03274f562
(Initial import): Fix. Mention --aux-dir.
Simon Josefsson <simon@josefsson.org>
parents:
5269
diff
changeset
|
10 @set UPDATED $Date: 2005-04-18 20:58:20 $ |
| 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 | |
| 17 Copyright @copyright{} 2004 Free Software Foundation, Inc. | |
| 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 | |
| 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. | |
| 70 | |
| 71 Getting started: | |
| 72 | |
| 73 @itemize | |
| 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/}. | |
| 79 @end itemize | |
| 80 | |
| 81 @menu | |
| 82 * Comments:: | |
|
5260
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
83 * Header files:: |
| 5239 | 84 * ctime:: |
| 85 * inet_ntoa:: | |
| 86 * Out of memory handling:: | |
| 87 @end menu | |
| 88 | |
| 89 @node Comments | |
| 90 @section Comments | |
| 91 | |
| 92 @cindex comments describing functions | |
| 93 @cindex describing functions, locating | |
| 94 Where to put comments describing functions: Because of risk of | |
| 95 divergence, we prefer to keep most function describing comments in | |
| 96 only one place: just above the actual function definition. Some | |
| 97 people prefer to put that documentation in the .h file. In any case, | |
| 98 it should appear in just one place unless you can ensure that the | |
| 99 multiple copies will always remain identical. | |
| 100 | |
| 101 | |
|
5260
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
102 @node Header files |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
103 @section Header files |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
104 |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
105 @cindex double inclusion of header files |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
106 @cindex header file include protection |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
107 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
|
108 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
|
109 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
|
110 |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
111 @example |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
112 #ifndef FOO_H |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
113 # define FOO_H |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
114 ... |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
115 body of header file goes here |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
116 ... |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
117 #endif /* FOO_H */ |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
118 @end example |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
119 |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
120 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
|
121 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
|
122 underscore and either an uppercase letter or another underscore, for |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
123 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
|
124 @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
|
125 hand, using @code{FOO_H} will likely lead the higher risk of |
| 5269 | 126 collisions with other symbols (e.g., @code{KEY_H}, @code{XK_H}, @code{BPF_H}, |
| 127 which are CPP macro constants, or @code{COFF_LONG_H}, which is a CPP | |
| 128 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
|
129 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
|
130 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
|
131 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
|
132 |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
133 @cindex C++ header files |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
134 @cindex Header files and C++ |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
135 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
|
136 CPP trick, as in: |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
137 |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
138 @example |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
139 # ifdef __cplusplus |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
140 extern "C" |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
141 @{ |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
142 # endif |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
143 ... |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
144 body of header file goes here |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
145 ... |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
146 # ifdef __cplusplus |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
147 @} |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
148 # endif |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
149 @end example |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
150 |
|
5261
95f7304acdac
Minor fixups to previous patch.
Paul Eggert <eggert@cs.ucla.edu>
parents:
5260
diff
changeset
|
151 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
|
152 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
|
153 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
|
154 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
|
155 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
|
156 should explicitly use the @samp{extern "C"} block itself. Your |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
157 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
|
158 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
|
159 and C++ programs alike. |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
160 |
| 5239 | 161 @node ctime |
| 162 @section ctime | |
| 163 @findex ctime | |
| 164 | |
| 165 The @code{ctime} function need not be reentrant, and consequently is | |
| 166 not required to be thread safe. Implementations of @code{ctime} | |
| 167 typically write the time stamp into static buffer. If two threads | |
| 168 call @code{ctime} at roughly the same time, you might end up with the | |
| 169 wrong date in one of the threads, or some undefined string. There is | |
| 170 a re-entrant interface @code{ctime_r}, that take a pre-allocated | |
| 171 buffer and length of the buffer, and return @code{NULL} on errors. | |
| 172 The input buffer should be at least 26 bytes in size. The output | |
| 173 string is locale-independent. However, years can have more than 4 | |
| 174 digits if @code{time_t} is sufficiently wide, so the length of the | |
| 175 required output buffer is not easy to determine. Increasing the | |
| 176 buffer size when @code{ctime_r} return @code{NULL} is not necessarily | |
| 177 sufficient. The @code{NULL} return value could mean some other error | |
| 178 condition, which will not go away by increasing the buffer size. | |
| 179 | |
| 180 A more flexible function is @code{strftime}. However, note that it is | |
| 181 locale dependent. | |
| 182 | |
| 183 | |
| 184 @node inet_ntoa | |
| 185 @section inet_ntoa | |
| 186 @findex inet_ntoa | |
| 187 | |
| 188 The @code{inet_ntoa} function need not be reentrant, and consequently | |
| 189 is not required to be thread safe. Implementations of | |
| 190 @code{inet_ntoa} typically write the time stamp into static buffer. | |
| 191 If two threads call @code{inet_ntoa} at roughly the same time, you | |
| 192 might end up with the wrong date in one of the threads, or some | |
| 193 undefined string. Further, @code{inet_ntoa} is specific for | |
| 194 @acronym{IPv4} addresses. | |
| 195 | |
| 196 A protocol independent function is @code{inet_ntop}. | |
| 197 | |
| 198 | |
| 199 @node Out of memory handling | |
| 200 @section Out of memory handling | |
| 201 | |
| 202 @cindex Out of Memory handling | |
| 203 @cindex Memory allocation failure | |
| 204 The GSS API does not have a standard error code for the out of memory | |
| 205 error condition. Instead of adding a non-standard error code, this | |
| 206 library has chosen to adopt a different strategy. Out of memory | |
| 207 handling happens in rare situations, but performing the out of memory | |
| 208 error handling after almost all API function invocations pollute your | |
| 209 source code and might make it harder to spot more serious problems. | |
| 210 The strategy chosen improve code readability and robustness. | |
| 211 | |
| 212 @cindex Aborting execution | |
| 213 For most applications, aborting the application with an error message | |
| 214 when the out of memory situation occur is the best that can be wished | |
| 215 for. This is how the library behaves by default. | |
| 216 | |
| 217 @vindex xalloc_fail_func | |
| 218 However, we realize that some applications may not want to have the | |
| 219 GSS library abort execution in any situation. The GSS library support | |
| 220 a hook to let the application regain control and perform its own | |
| 221 cleanups when an out of memory situation has occured. The application | |
| 222 can define a function (having a @code{void} prototype, i.e., no return | |
| 223 value and no parameters) and set the library variable | |
| 224 @code{xalloc_fail_func} to that function. The variable should be | |
| 225 declared as follows. | |
| 226 | |
| 227 @example | |
| 228 extern void (*xalloc_fail_func) (void); | |
| 229 @end example | |
| 230 | |
| 231 The GSS library will invoke this function if an out of memory error | |
| 232 occurs. Note that after this the GSS library is in an undefined | |
| 233 state, so you must unload or restart the application to continue call | |
| 234 GSS library functions. The hook is only intended to allow the | |
| 235 application to log the situation in a special way. Of course, care | |
| 236 must be taken to not allocate more memory, as that will likely also | |
| 237 fail. | |
| 238 | |
| 239 | |
| 240 @node Invoking gnulib-tool | |
| 241 @chapter Invoking gnulib-tool | |
| 242 | |
| 243 @pindex gnulib-tool | |
| 244 @cindex invoking @command{gnulib-tool} | |
| 245 | |
| 246 Run @samp{gnulib-tool --help}, and use the source. | |
| 247 @command{gnulib-tool} is the way to import Gnulib modules. | |
| 248 | |
|
5256
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
249 @menu |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
250 * Initial import:: First import of Gnulib modules. |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
251 * Importing updated files:: Subsequent imports. |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
252 * Finishing touches:: Simplifying imports. |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
253 @end menu |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
254 |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
255 |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
256 @node Initial import |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
257 @section Initial import |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
258 @cindex initial import |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
259 |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
260 Gnulib assumes your project uses Autoconf and Automake. Invoking |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
261 @samp{gnulib-tool --import} will copy source files, create a |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
262 @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
|
263 Autoconf M4 macro declarations used by @file{configure.ac}. |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
264 |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
265 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
|
266 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
|
267 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
|
268 |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
269 @example |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
270 ~/src/libfoo$ gnulib-tool --import strdup |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
271 Module list with included dependencies: |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
272 strdup |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
273 File list: |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
274 lib/strdup.c |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
275 lib/strdup.h |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
276 m4/onceonly_2_57.m4 |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
277 m4/strdup.m4 |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
278 Creating ./lib/Makefile.am... |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
279 Creating ./m4/gnulib.m4... |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
280 Finished. |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
281 |
|
5802
94a03274f562
(Initial import): Fix. Mention --aux-dir.
Simon Josefsson <simon@josefsson.org>
parents:
5269
diff
changeset
|
282 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
|
283 #include "strdup.h" |
|
94a03274f562
(Initial import): Fix. Mention --aux-dir.
Simon Josefsson <simon@josefsson.org>
parents:
5269
diff
changeset
|
284 |
|
5256
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
285 Don't forget to add "lib/Makefile" |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
286 to AC_CONFIG_FILES in "./configure.ac" and to mention |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
287 "lib" in SUBDIRS in some Makefile.am. |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
288 ~/src/libfoo$ |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
289 @end example |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
290 |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
291 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
|
292 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
|
293 @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
|
294 adding @samp{gl_SOURCE_BASE(DIRECTORY)} and |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
295 @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
|
296 Some modules also provide other files necessary |
|
94a03274f562
(Initial import): Fix. Mention --aux-dir.
Simon Josefsson <simon@josefsson.org>
parents:
5269
diff
changeset
|
297 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
|
298 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
|
299 @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
|
300 current directory is assumed. |
|
94a03274f562
(Initial import): Fix. Mention --aux-dir.
Simon Josefsson <simon@josefsson.org>
parents:
5269
diff
changeset
|
301 |
|
94a03274f562
(Initial import): Fix. Mention --aux-dir.
Simon Josefsson <simon@josefsson.org>
parents:
5269
diff
changeset
|
302 @code{gnulib-tool} can make symbolic links instead |
|
94a03274f562
(Initial import): Fix. Mention --aux-dir.
Simon Josefsson <simon@josefsson.org>
parents:
5269
diff
changeset
|
303 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
|
304 (or @code{-s} for short) option to do this. |
|
5256
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
305 |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
306 @code{gnulib-tool} will overwrite any pre-existing files, in |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
307 particular @file{Makefile.am}. Unfortunately, separating the |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
308 generated @file{Makefile.am} content (for building the gnulib library) |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
309 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
|
310 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
|
311 variable assignments are handled by Automake. |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
312 |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
313 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
|
314 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
|
315 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
|
316 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
|
317 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
|
318 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
|
319 packages. |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
320 |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
321 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
|
322 |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
323 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
|
324 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
|
325 top-level @file{Makefile.am} file, as in: |
|
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 @example |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
328 ACLOCAL_AMFLAGS = -I m4 |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
329 @end example |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
330 |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
331 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
|
332 @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
|
333 |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
334 @example |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
335 ACLOCAL_AMFLAGS = -I gl/m4 |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
336 @end example |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
337 |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
338 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
|
339 @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
|
340 as possible after verifying that the C compiler is working. |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
341 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
|
342 |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
343 @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 AC_PROG_CC |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
346 gl_EARLY |
|
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 @end example |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
349 |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
350 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
|
351 @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
|
352 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
|
353 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
|
354 For example: |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
355 |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
356 @example |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
357 ... |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
358 # For gnulib. |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
359 gl_INIT |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
360 ... |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
361 @end example |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
362 |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
363 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
|
364 @code{Makefile} in the gnulib source base directory to |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
365 @code{AC_CONFIG_FILES}, as in: |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
366 |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
367 @example |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
368 AC_CONFIG_FILES(... lib/Makefile ...) |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
369 @end example |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
370 |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
371 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
|
372 |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
373 @example |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
374 AC_CONFIG_FILES(... gl/Makefile ...) |
|
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 @code{make} work in the gnulib directory. |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
378 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
|
379 statement, 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 SUBDIRS = lib |
|
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 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
|
386 you can add something like: |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
387 |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
388 @example |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
389 SUBDIRS += lib |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
390 @end example |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
391 |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
392 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
|
393 |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
394 @example |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
395 SUBDIRS += gl |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
396 @end example |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
397 |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
398 Finally, you have add C flags and LD flags, so that you can make use |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
399 of the gnulib library. For example: |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
400 |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
401 @example |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
402 ... |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
403 AM_CPPFLAGS = -I$(top_srcdir)/lib |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
404 ... |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
405 LIBADD = lib/libgnu.la |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
406 ... |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
407 @end example |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
408 |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
409 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
|
410 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
|
411 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
|
412 use of @code{strdup}. |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
413 |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
414 |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
415 @node Importing updated files |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
416 @section Importing updated files |
|
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 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
|
419 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
|
420 package for gnulib, this step is quite simple. For example: |
|
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 @example |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
423 ~/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
|
424 Module list with included dependencies: |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
425 strdup |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
426 File list: |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
427 lib/strdup.c |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
428 lib/strdup.h |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
429 m4/onceonly_2_57.m4 |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
430 m4/strdup.m4 |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
431 Creating ./lib/Makefile.am... |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
432 Creating ./m4/gnulib.m4... |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
433 Finished. |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
434 |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
435 Don't forget to add "lib/Makefile" |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
436 to AC_CONFIG_FILES in "./configure.ac" and to mention |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
437 "lib" in SUBDIRS in some Makefile.am. |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
438 ~/src/libfoo$ |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
439 @end example |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
440 |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
441 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
|
442 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
|
443 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
|
444 |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
445 @example |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
446 ... |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
447 # Invoked as: gnulib-tool --import strdup |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
448 # 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
|
449 ... |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
450 @end example |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
451 |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
452 |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
453 @node Finishing touches |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
454 @section Finishing touches |
|
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 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
|
457 @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
|
458 snprintf getline minmax}) can be tedious. To simplify this procedure, |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
459 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
|
460 For 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 @example |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
463 ... |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
464 AC_PROG_CC |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
465 gl_EARLY |
|
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 # For gnulib. |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
468 gl_SOURCE_BASE(gl) |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
469 gl_M4_BASE(gl/m4) |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
470 gl_LIB(libgl) |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
471 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
|
472 gl_INIT |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
473 ... |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
474 @end example |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
475 |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
476 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
|
477 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
|
478 --import} with no additional parameters. |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
479 |
|
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
480 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
|
481 @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
|
482 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
|
483 @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
|
484 @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
|
485 |
| 5239 | 486 |
| 487 @node Copying This Manual | |
| 488 @appendix Copying This Manual | |
| 489 | |
| 490 @menu | |
| 491 * GNU Free Documentation License:: License for copying this manual. | |
| 492 @end menu | |
| 493 | |
| 494 @include fdl.texi | |
| 495 | |
| 496 | |
| 497 @node Index | |
| 498 @unnumbered Index | |
| 499 | |
| 500 @printindex cp | |
| 501 | |
| 502 @bye |