]>
Commit | Line | Data |
---|---|---|
3c20b9b6 | 1 | @node Maintenance, Contributors, Installation, Top |
7a68c94a | 2 | @c %MENU% How to enhance and port the GNU C Library |
28f540f4 RM |
3 | @appendix Library Maintenance |
4 | ||
5 | @menu | |
28f540f4 RM |
6 | * Source Layout:: How to add new functions or header files |
7 | to the GNU C library. | |
8 | * Porting:: How to port the GNU C library to | |
9 | a new machine or operating system. | |
7da3079b | 10 | @end menu |
28f540f4 | 11 | |
28f540f4 RM |
12 | @node Source Layout |
13 | @appendixsec Adding New Functions | |
14 | ||
15 | The process of building the library is driven by the makefiles, which | |
16 | make heavy use of special features of GNU @code{make}. The makefiles | |
17 | are very complex, and you probably don't want to try to understand them. | |
18 | But what they do is fairly straightforward, and only requires that you | |
19 | define a few variables in the right places. | |
20 | ||
21 | The library sources are divided into subdirectories, grouped by topic. | |
41f27456 | 22 | |
28f540f4 | 23 | The @file{string} subdirectory has all the string-manipulation |
41f27456 | 24 | functions, @file{math} has all the mathematical functions, etc. |
28f540f4 RM |
25 | |
26 | Each subdirectory contains a simple makefile, called @file{Makefile}, | |
27 | which defines a few @code{make} variables and then includes the global | |
28 | makefile @file{Rules} with a line like: | |
29 | ||
30 | @smallexample | |
31 | include ../Rules | |
32 | @end smallexample | |
33 | ||
34 | @noindent | |
35 | The basic variables that a subdirectory makefile defines are: | |
36 | ||
37 | @table @code | |
38 | @item subdir | |
39 | The name of the subdirectory, for example @file{stdio}. | |
40 | This variable @strong{must} be defined. | |
41 | ||
42 | @item headers | |
43 | The names of the header files in this section of the library, | |
44 | such as @file{stdio.h}. | |
45 | ||
46 | @item routines | |
47 | @itemx aux | |
48 | The names of the modules (source files) in this section of the library. | |
49 | These should be simple names, such as @samp{strlen} (rather than | |
50 | complete file names, such as @file{strlen.c}). Use @code{routines} for | |
51 | modules that define functions in the library, and @code{aux} for | |
52 | auxiliary modules containing things like data definitions. But the | |
53 | values of @code{routines} and @code{aux} are just concatenated, so there | |
54 | really is no practical difference.@refill | |
55 | ||
56 | @item tests | |
57 | The names of test programs for this section of the library. These | |
58 | should be simple names, such as @samp{tester} (rather than complete file | |
59 | names, such as @file{tester.c}). @w{@samp{make tests}} will build and | |
60 | run all the test programs. If a test program needs input, put the test | |
61 | data in a file called @file{@var{test-program}.input}; it will be given to | |
62 | the test program on its standard input. If a test program wants to be | |
63 | run with arguments, put the arguments (all on a single line) in a file | |
41f27456 RM |
64 | called @file{@var{test-program}.args}. Test programs should exit with |
65 | zero status when the test passes, and nonzero status when the test | |
66 | indicates a bug in the library or error in building. | |
28f540f4 RM |
67 | |
68 | @item others | |
69 | The names of ``other'' programs associated with this section of the | |
70 | library. These are programs which are not tests per se, but are other | |
71 | small programs included with the library. They are built by | |
72 | @w{@samp{make others}}.@refill | |
73 | ||
74 | @item install-lib | |
75 | @itemx install-data | |
76 | @itemx install | |
77 | Files to be installed by @w{@samp{make install}}. Files listed in | |
78 | @samp{install-lib} are installed in the directory specified by | |
79 | @samp{libdir} in @file{configparms} or @file{Makeconfig} | |
80 | (@pxref{Installation}). Files listed in @code{install-data} are | |
81 | installed in the directory specified by @samp{datadir} in | |
82 | @file{configparms} or @file{Makeconfig}. Files listed in @code{install} | |
83 | are installed in the directory specified by @samp{bindir} in | |
84 | @file{configparms} or @file{Makeconfig}.@refill | |
85 | ||
86 | @item distribute | |
87 | Other files from this subdirectory which should be put into a | |
88 | distribution tar file. You need not list here the makefile itself or | |
89 | the source and header files listed in the other standard variables. | |
90 | Only define @code{distribute} if there are files used in an unusual way | |
91 | that should go into the distribution. | |
92 | ||
93 | @item generated | |
94 | Files which are generated by @file{Makefile} in this subdirectory. | |
95 | These files will be removed by @w{@samp{make clean}}, and they will | |
96 | never go into a distribution. | |
97 | ||
98 | @item extra-objs | |
99 | Extra object files which are built by @file{Makefile} in this | |
100 | subdirectory. This should be a list of file names like @file{foo.o}; | |
101 | the files will actually be found in whatever directory object files are | |
102 | being built in. These files will be removed by @w{@samp{make clean}}. | |
103 | This variable is used for secondary object files needed to build | |
104 | @code{others} or @code{tests}. | |
105 | @end table | |
106 | ||
107 | @node Porting | |
108 | @appendixsec Porting the GNU C Library | |
109 | ||
110 | The GNU C library is written to be easily portable to a variety of | |
111 | machines and operating systems. Machine- and operating system-dependent | |
112 | functions are well separated to make it easy to add implementations for | |
113 | new machines or operating systems. This section describes the layout of | |
114 | the library source tree and explains the mechanisms used to select | |
115 | machine-dependent code to use. | |
116 | ||
117 | All the machine-dependent and operating system-dependent files in the | |
118 | library are in the subdirectory @file{sysdeps} under the top-level | |
119 | library source directory. This directory contains a hierarchy of | |
120 | subdirectories (@pxref{Hierarchy Conventions}). | |
121 | ||
122 | Each subdirectory of @file{sysdeps} contains source files for a | |
123 | particular machine or operating system, or for a class of machine or | |
124 | operating system (for example, systems by a particular vendor, or all | |
125 | machines that use IEEE 754 floating-point format). A configuration | |
126 | specifies an ordered list of these subdirectories. Each subdirectory | |
127 | implicitly appends its parent directory to the list. For example, | |
128 | specifying the list @file{unix/bsd/vax} is equivalent to specifying the | |
129 | list @file{unix/bsd/vax unix/bsd unix}. A subdirectory can also specify | |
130 | that it implies other subdirectories which are not directly above it in | |
131 | the directory hierarchy. If the file @file{Implies} exists in a | |
132 | subdirectory, it lists other subdirectories of @file{sysdeps} which are | |
133 | appended to the list, appearing after the subdirectory containing the | |
134 | @file{Implies} file. Lines in an @file{Implies} file that begin with a | |
135 | @samp{#} character are ignored as comments. For example, | |
136 | @file{unix/bsd/Implies} contains:@refill | |
137 | @smallexample | |
138 | # BSD has Internet-related things. | |
139 | unix/inet | |
140 | @end smallexample | |
141 | @noindent | |
142 | and @file{unix/Implies} contains: | |
143 | @need 300 | |
144 | @smallexample | |
145 | posix | |
146 | @end smallexample | |
147 | ||
148 | @noindent | |
149 | So the final list is @file{unix/bsd/vax unix/bsd unix/inet unix posix}. | |
150 | ||
f2ea0f5b UD |
151 | @file{sysdeps} has a ``special'' subdirectory called @file{generic}. It |
152 | is always implicitly appended to the list of subdirectories, so you | |
153 | needn't put it in an @file{Implies} file, and you should not create any | |
154 | subdirectories under it intended to be new specific categories. | |
155 | @file{generic} serves two purposes. First, the makefiles do not bother | |
156 | to look for a system-dependent version of a file that's not in | |
157 | @file{generic}. This means that any system-dependent source file must | |
158 | have an analogue in @file{generic}, even if the routines defined by that | |
32c075e1 | 159 | file are not implemented on other platforms. Second. the @file{generic} |
f2ea0f5b UD |
160 | version of a system-dependent file is used if the makefiles do not find |
161 | a version specific to the system you're compiling for. | |
162 | ||
163 | If it is possible to implement the routines in a @file{generic} file in | |
164 | machine-independent C, using only other machine-independent functions in | |
165 | the C library, then you should do so. Otherwise, make them stubs. A | |
166 | @dfn{stub} function is a function which cannot be implemented on a | |
167 | particular machine or operating system. Stub functions always return an | |
168 | error, and set @code{errno} to @code{ENOSYS} (Function not implemented). | |
169 | @xref{Error Reporting}. If you define a stub function, you must place | |
170 | the statement @code{stub_warning(@var{function})}, where @var{function} | |
171 | is the name of your function, after its definition; also, you must | |
172 | include the file @code{<stub-tag.h>} into your file. This causes the | |
173 | function to be listed in the installed @code{<gnu/stubs.h>}, and | |
174 | makes GNU ld warn when the function is used. | |
175 | ||
cc3fa755 UD |
176 | Some rare functions are only useful on specific systems and aren't |
177 | defined at all on others; these do not appear anywhere in the | |
178 | system-independent source code or makefiles (including the | |
179 | @file{generic} directory), only in the system-dependent @file{Makefile} | |
180 | in the specific system's subdirectory. | |
28f540f4 RM |
181 | |
182 | If you come across a file that is in one of the main source directories | |
183 | (@file{string}, @file{stdio}, etc.), and you want to write a machine- or | |
184 | operating system-dependent version of it, move the file into | |
185 | @file{sysdeps/generic} and write your new implementation in the | |
186 | appropriate system-specific subdirectory. Note that if a file is to be | |
187 | system-dependent, it @strong{must not} appear in one of the main source | |
188 | directories.@refill | |
189 | ||
190 | There are a few special files that may exist in each subdirectory of | |
191 | @file{sysdeps}: | |
192 | ||
193 | @comment Blank lines after items make the table look better. | |
194 | @table @file | |
195 | @item Makefile | |
196 | ||
197 | A makefile for this machine or operating system, or class of machine or | |
198 | operating system. This file is included by the library makefile | |
199 | @file{Makerules}, which is used by the top-level makefile and the | |
200 | subdirectory makefiles. It can change the variables set in the | |
201 | including makefile or add new rules. It can use GNU @code{make} | |
202 | conditional directives based on the variable @samp{subdir} (see above) to | |
203 | select different sets of variables and rules for different sections of | |
204 | the library. It can also set the @code{make} variable | |
205 | @samp{sysdep-routines}, to specify extra modules to be included in the | |
206 | library. You should use @samp{sysdep-routines} rather than adding | |
207 | modules to @samp{routines} because the latter is used in determining | |
208 | what to distribute for each subdirectory of the main source tree.@refill | |
209 | ||
210 | Each makefile in a subdirectory in the ordered list of subdirectories to | |
211 | be searched is included in order. Since several system-dependent | |
212 | makefiles may be included, each should append to @samp{sysdep-routines} | |
213 | rather than simply setting it: | |
214 | ||
215 | @smallexample | |
216 | sysdep-routines := $(sysdep-routines) foo bar | |
217 | @end smallexample | |
218 | ||
219 | @need 1000 | |
220 | @item Subdirs | |
221 | ||
222 | This file contains the names of new whole subdirectories under the | |
223 | top-level library source tree that should be included for this system. | |
224 | These subdirectories are treated just like the system-independent | |
225 | subdirectories in the library source tree, such as @file{stdio} and | |
226 | @file{math}. | |
227 | ||
228 | Use this when there are completely new sets of functions and header | |
229 | files that should go into the library for the system this subdirectory | |
230 | of @file{sysdeps} implements. For example, | |
231 | @file{sysdeps/unix/inet/Subdirs} contains @file{inet}; the @file{inet} | |
232 | directory contains various network-oriented operations which only make | |
233 | sense to put in the library on systems that support the Internet.@refill | |
234 | ||
28f540f4 RM |
235 | @item configure |
236 | ||
237 | This file is a shell script fragment to be run at configuration time. | |
238 | The top-level @file{configure} script uses the shell @code{.} command to | |
239 | read the @file{configure} file in each system-dependent directory | |
240 | chosen, in order. The @file{configure} files are often generated from | |
241 | @file{configure.in} files using Autoconf. | |
242 | ||
243 | A system-dependent @file{configure} script will usually add things to | |
244 | the shell variables @samp{DEFS} and @samp{config_vars}; see the | |
245 | top-level @file{configure} script for details. The script can check for | |
246 | @w{@samp{--with-@var{package}}} options that were passed to the | |
247 | top-level @file{configure}. For an option | |
248 | @w{@samp{--with-@var{package}=@var{value}}} @file{configure} sets the | |
249 | shell variable @w{@samp{with_@var{package}}} (with any dashes in | |
250 | @var{package} converted to underscores) to @var{value}; if the option is | |
251 | just @w{@samp{--with-@var{package}}} (no argument), then it sets | |
252 | @w{@samp{with_@var{package}}} to @samp{yes}. | |
253 | ||
254 | @item configure.in | |
255 | ||
256 | This file is an Autoconf input fragment to be processed into the file | |
257 | @file{configure} in this subdirectory. @xref{Introduction,,, | |
258 | autoconf.info, Autoconf: Generating Automatic Configuration Scripts}, | |
259 | for a description of Autoconf. You should write either @file{configure} | |
260 | or @file{configure.in}, but not both. The first line of | |
261 | @file{configure.in} should invoke the @code{m4} macro | |
262 | @samp{GLIBC_PROVIDES}. This macro does several @code{AC_PROVIDE} calls | |
263 | for Autoconf macros which are used by the top-level @file{configure} | |
264 | script; without this, those macros might be invoked again unnecessarily | |
265 | by Autoconf. | |
266 | @end table | |
267 | ||
268 | That is the general system for how system-dependencies are isolated. | |
269 | @iftex | |
270 | The next section explains how to decide what directories in | |
271 | @file{sysdeps} to use. @ref{Porting to Unix}, has some tips on porting | |
272 | the library to Unix variants. | |
273 | @end iftex | |
274 | ||
275 | @menu | |
276 | * Hierarchy Conventions:: The layout of the @file{sysdeps} hierarchy. | |
277 | * Porting to Unix:: Porting the library to an average | |
278 | Unix-like system. | |
279 | @end menu | |
280 | ||
281 | @node Hierarchy Conventions | |
282 | @appendixsubsec Layout of the @file{sysdeps} Directory Hierarchy | |
283 | ||
284 | A GNU configuration name has three parts: the CPU type, the | |
285 | manufacturer's name, and the operating system. @file{configure} uses | |
286 | these to pick the list of system-dependent directories to look for. If | |
287 | the @samp{--nfp} option is @emph{not} passed to @file{configure}, the | |
288 | directory @file{@var{machine}/fpu} is also used. The operating system | |
289 | often has a @dfn{base operating system}; for example, if the operating | |
68b50604 | 290 | system is @samp{Linux}, the base operating system is @samp{unix/sysv}. |
28f540f4 RM |
291 | The algorithm used to pick the list of directories is simple: |
292 | @file{configure} makes a list of the base operating system, | |
293 | manufacturer, CPU type, and operating system, in that order. It then | |
294 | concatenates all these together with slashes in between, to produce a | |
68b50604 UD |
295 | directory name; for example, the configuration @w{@samp{i686-linux-gnu}} |
296 | results in @file{unix/sysv/linux/i386/i686}. @file{configure} then | |
28f540f4 | 297 | tries removing each element of the list in turn, so |
68b50604 | 298 | @file{unix/sysv/linux} and @file{unix/sysv} are also tried, among others. |
28f540f4 RM |
299 | Since the precise version number of the operating system is often not |
300 | important, and it would be very inconvenient, for example, to have | |
68b50604 | 301 | identical @file{irix6.2} and @file{irix6.3} directories, |
28f540f4 RM |
302 | @file{configure} tries successively less specific operating system names |
303 | by removing trailing suffixes starting with a period. | |
304 | ||
305 | As an example, here is the complete list of directories that would be | |
68b50604 UD |
306 | tried for the configuration @w{@samp{i686-linux-gnu}} (with the |
307 | @file{crypt} and @file{linuxthreads} add-on): | |
28f540f4 RM |
308 | |
309 | @smallexample | |
68b50604 UD |
310 | sysdeps/i386/elf |
311 | crypt/sysdeps/unix | |
312 | linuxthreads/sysdeps/unix/sysv/linux | |
313 | linuxthreads/sysdeps/pthread | |
314 | linuxthreads/sysdeps/unix/sysv | |
315 | linuxthreads/sysdeps/unix | |
316 | linuxthreads/sysdeps/i386/i686 | |
317 | linuxthreads/sysdeps/i386 | |
318 | linuxthreads/sysdeps/pthread/no-cmpxchg | |
319 | sysdeps/unix/sysv/linux/i386 | |
320 | sysdeps/unix/sysv/linux | |
321 | sysdeps/gnu | |
322 | sysdeps/unix/common | |
323 | sysdeps/unix/mman | |
324 | sysdeps/unix/inet | |
325 | sysdeps/unix/sysv/i386/i686 | |
326 | sysdeps/unix/sysv/i386 | |
327 | sysdeps/unix/sysv | |
328 | sysdeps/unix/i386 | |
329 | sysdeps/unix | |
330 | sysdeps/posix | |
331 | sysdeps/i386/i686 | |
332 | sysdeps/i386/i486 | |
333 | sysdeps/libm-i387/i686 | |
334 | sysdeps/i386/fpu | |
335 | sysdeps/libm-i387 | |
336 | sysdeps/i386 | |
337 | sysdeps/wordsize-32 | |
338 | sysdeps/ieee754 | |
339 | sysdeps/libm-ieee754 | |
340 | sysdeps/generic | |
28f540f4 RM |
341 | @end smallexample |
342 | ||
343 | Different machine architectures are conventionally subdirectories at the | |
344 | top level of the @file{sysdeps} directory tree. For example, | |
345 | @w{@file{sysdeps/sparc}} and @w{@file{sysdeps/m68k}}. These contain | |
346 | files specific to those machine architectures, but not specific to any | |
347 | particular operating system. There might be subdirectories for | |
348 | specializations of those architectures, such as | |
349 | @w{@file{sysdeps/m68k/68020}}. Code which is specific to the | |
350 | floating-point coprocessor used with a particular machine should go in | |
351 | @w{@file{sysdeps/@var{machine}/fpu}}. | |
352 | ||
353 | There are a few directories at the top level of the @file{sysdeps} | |
354 | hierarchy that are not for particular machine architectures. | |
355 | ||
356 | @table @file | |
357 | @item generic | |
f2ea0f5b | 358 | As described above (@pxref{Porting}), this is the subdirectory |
28f540f4 RM |
359 | that every configuration implicitly uses after all others. |
360 | ||
361 | @item ieee754 | |
362 | This directory is for code using the IEEE 754 floating-point format, | |
363 | where the C type @code{float} is IEEE 754 single-precision format, and | |
364 | @code{double} is IEEE 754 double-precision format. Usually this | |
365 | directory is referred to in the @file{Implies} file in a machine | |
366 | architecture-specific directory, such as @file{m68k/Implies}. | |
367 | ||
68b50604 UD |
368 | @item libm-ieee754 |
369 | This directory contains an implementation of a mathematical library | |
370 | usable on platforms which use @w{IEEE 754} conformant floating-point | |
371 | arithmetic. | |
372 | ||
373 | @item libm-i387 | |
374 | This is a special case. Ideally the code should be in | |
375 | @file{sysdeps/i386/fpu} but for various reasons it is kept aside. | |
376 | ||
28f540f4 RM |
377 | @item posix |
378 | This directory contains implementations of things in the library in | |
379 | terms of @sc{POSIX.1} functions. This includes some of the @sc{POSIX.1} | |
380 | functions themselves. Of course, @sc{POSIX.1} cannot be completely | |
381 | implemented in terms of itself, so a configuration using just | |
382 | @file{posix} cannot be complete. | |
383 | ||
384 | @item unix | |
385 | This is the directory for Unix-like things. @xref{Porting to Unix}. | |
386 | @file{unix} implies @file{posix}. There are some special-purpose | |
387 | subdirectories of @file{unix}: | |
388 | ||
389 | @table @file | |
390 | @item unix/common | |
391 | This directory is for things common to both BSD and System V release 4. | |
392 | Both @file{unix/bsd} and @file{unix/sysv/sysv4} imply @file{unix/common}. | |
393 | ||
394 | @item unix/inet | |
395 | This directory is for @code{socket} and related functions on Unix systems. | |
3c20b9b6 | 396 | @file{unix/inet/Subdirs} enables the @file{inet} top-level subdirectory. |
28f540f4 RM |
397 | @file{unix/common} implies @file{unix/inet}. |
398 | @end table | |
399 | ||
400 | @item mach | |
401 | This is the directory for things based on the Mach microkernel from CMU | |
402 | (including the GNU operating system). Other basic operating systems | |
403 | (VMS, for example) would have their own directories at the top level of | |
404 | the @file{sysdeps} hierarchy, parallel to @file{unix} and @file{mach}. | |
405 | @end table | |
406 | ||
407 | @node Porting to Unix | |
408 | @appendixsubsec Porting the GNU C Library to Unix Systems | |
409 | ||
410 | Most Unix systems are fundamentally very similar. There are variations | |
411 | between different machines, and variations in what facilities are | |
412 | provided by the kernel. But the interface to the operating system | |
413 | facilities is, for the most part, pretty uniform and simple. | |
414 | ||
415 | The code for Unix systems is in the directory @file{unix}, at the top | |
416 | level of the @file{sysdeps} hierarchy. This directory contains | |
417 | subdirectories (and subdirectory trees) for various Unix variants. | |
418 | ||
419 | The functions which are system calls in most Unix systems are | |
26b4d766 | 420 | implemented in assembly code, which is generated automatically from |
3c20b9b6 UD |
421 | specifications in files named @file{syscalls.list}. There are several |
422 | such files, one in @file{sysdeps/unix} and others in its subdirectories. | |
423 | Some special system calls are implemented in files that are named with a | |
26b4d766 UD |
424 | suffix of @samp{.S}; for example, @file{_exit.S}. Files ending in |
425 | @samp{.S} are run through the C preprocessor before being fed to the | |
426 | assembler. | |
28f540f4 RM |
427 | |
428 | These files all use a set of macros that should be defined in | |
429 | @file{sysdep.h}. The @file{sysdep.h} file in @file{sysdeps/unix} | |
430 | partially defines them; a @file{sysdep.h} file in another directory must | |
431 | finish defining them for the particular machine and operating system | |
432 | variant. See @file{sysdeps/unix/sysdep.h} and the machine-specific | |
433 | @file{sysdep.h} implementations to see what these macros are and what | |
434 | they should do.@refill | |
435 | ||
3c20b9b6 UD |
436 | The system-specific makefile for the @file{unix} directory |
437 | (@file{sysdeps/unix/Makefile}) gives rules to generate several files | |
28f540f4 RM |
438 | from the Unix system you are building the library on (which is assumed |
439 | to be the target system you are building the library @emph{for}). All | |
440 | the generated files are put in the directory where the object files are | |
441 | kept; they should not affect the source tree itself. The files | |
442 | generated are @file{ioctls.h}, @file{errnos.h}, @file{sys/param.h}, and | |
443 | @file{errlist.c} (for the @file{stdio} section of the library). | |
444 | ||
445 | @ignore | |
446 | @c This section might be a good idea if it is finished, | |
447 | @c but there's no point including it as it stands. --rms | |
448 | @c @appendixsec Compatibility with Traditional C | |
449 | ||
450 | @c ??? This section is really short now. Want to keep it? --roland | |
451 | ||
68b50604 UD |
452 | @c It's not anymore true. glibc 2.1 cannot be used with K&R compilers. |
453 | @c --drepper | |
454 | ||
f65fd747 UD |
455 | Although the GNU C library implements the @w{ISO C} library facilities, you |
456 | @emph{can} use the GNU C library with traditional, ``pre-ISO'' C | |
28f540f4 RM |
457 | compilers. However, you need to be careful because the content and |
458 | organization of the GNU C library header files differs from that of | |
459 | traditional C implementations. This means you may need to make changes | |
460 | to your program in order to get it to compile. | |
461 | @end ignore |