Fix typo.
[kopensolaris-gnu/glibc.git] / manual / maint.texi
1 @node Maintenance, Contributors, Installation, Top
2 @c %MENU% How to enhance and port the GNU C Library
3 @appendix Library Maintenance
4
5 @menu
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.
10 @end menu
11
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.
22
23 The @file{string} subdirectory has all the string-manipulation
24 functions, @file{math} has all the mathematical functions, etc.
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
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.
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
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
159 file are not implemented on other platforms.  Second. the @file{generic}
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
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.
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
235 @item Dist
236
237 This file contains the names of files (relative to the subdirectory of
238 @file{sysdeps} in which it appears) which should be included in the
239 distribution.  List any new files used by rules in the @file{Makefile}
240 in the same directory, or header files used by the source files in that
241 directory.  You don't need to list files that are implementations
242 (either C or assembly source) of routines whose names are given in the
243 machine-independent makefiles in the main source tree.
244
245 @item configure
246
247 This file is a shell script fragment to be run at configuration time.
248 The top-level @file{configure} script uses the shell @code{.} command to
249 read the @file{configure} file in each system-dependent directory
250 chosen, in order.  The @file{configure} files are often generated from
251 @file{configure.in} files using Autoconf.
252
253 A system-dependent @file{configure} script will usually add things to
254 the shell variables @samp{DEFS} and @samp{config_vars}; see the
255 top-level @file{configure} script for details.  The script can check for
256 @w{@samp{--with-@var{package}}} options that were passed to the
257 top-level @file{configure}.  For an option
258 @w{@samp{--with-@var{package}=@var{value}}} @file{configure} sets the
259 shell variable @w{@samp{with_@var{package}}} (with any dashes in
260 @var{package} converted to underscores) to @var{value}; if the option is
261 just @w{@samp{--with-@var{package}}} (no argument), then it sets
262 @w{@samp{with_@var{package}}} to @samp{yes}.
263
264 @item configure.in
265
266 This file is an Autoconf input fragment to be processed into the file
267 @file{configure} in this subdirectory.  @xref{Introduction,,,
268 autoconf.info, Autoconf: Generating Automatic Configuration Scripts},
269 for a description of Autoconf.  You should write either @file{configure}
270 or @file{configure.in}, but not both.  The first line of
271 @file{configure.in} should invoke the @code{m4} macro
272 @samp{GLIBC_PROVIDES}.  This macro does several @code{AC_PROVIDE} calls
273 for Autoconf macros which are used by the top-level @file{configure}
274 script; without this, those macros might be invoked again unnecessarily
275 by Autoconf.
276 @end table
277
278 That is the general system for how system-dependencies are isolated.
279 @iftex
280 The next section explains how to decide what directories in
281 @file{sysdeps} to use.  @ref{Porting to Unix}, has some tips on porting
282 the library to Unix variants.
283 @end iftex
284
285 @menu
286 * Hierarchy Conventions::       The layout of the @file{sysdeps} hierarchy.
287 * Porting to Unix::             Porting the library to an average
288                                    Unix-like system.
289 @end menu
290
291 @node Hierarchy Conventions
292 @appendixsubsec Layout of the @file{sysdeps} Directory Hierarchy
293
294 A GNU configuration name has three parts: the CPU type, the
295 manufacturer's name, and the operating system.  @file{configure} uses
296 these to pick the list of system-dependent directories to look for.  If
297 the @samp{--nfp} option is @emph{not} passed to @file{configure}, the
298 directory @file{@var{machine}/fpu} is also used.  The operating system
299 often has a @dfn{base operating system}; for example, if the operating
300 system is @samp{Linux}, the base operating system is @samp{unix/sysv}.
301 The algorithm used to pick the list of directories is simple:
302 @file{configure} makes a list of the base operating system,
303 manufacturer, CPU type, and operating system, in that order.  It then
304 concatenates all these together with slashes in between, to produce a
305 directory name; for example, the configuration @w{@samp{i686-linux-gnu}}
306 results in @file{unix/sysv/linux/i386/i686}.  @file{configure} then
307 tries removing each element of the list in turn, so
308 @file{unix/sysv/linux} and @file{unix/sysv} are also tried, among others.
309 Since the precise version number of the operating system is often not
310 important, and it would be very inconvenient, for example, to have
311 identical @file{irix6.2} and @file{irix6.3} directories,
312 @file{configure} tries successively less specific operating system names
313 by removing trailing suffixes starting with a period.
314
315 As an example, here is the complete list of directories that would be
316 tried for the configuration @w{@samp{i686-linux-gnu}} (with the
317 @file{crypt} and @file{linuxthreads} add-on):
318
319 @smallexample
320 sysdeps/i386/elf
321 crypt/sysdeps/unix
322 linuxthreads/sysdeps/unix/sysv/linux
323 linuxthreads/sysdeps/pthread
324 linuxthreads/sysdeps/unix/sysv
325 linuxthreads/sysdeps/unix
326 linuxthreads/sysdeps/i386/i686
327 linuxthreads/sysdeps/i386
328 linuxthreads/sysdeps/pthread/no-cmpxchg
329 sysdeps/unix/sysv/linux/i386
330 sysdeps/unix/sysv/linux
331 sysdeps/gnu
332 sysdeps/unix/common
333 sysdeps/unix/mman
334 sysdeps/unix/inet
335 sysdeps/unix/sysv/i386/i686
336 sysdeps/unix/sysv/i386
337 sysdeps/unix/sysv
338 sysdeps/unix/i386
339 sysdeps/unix
340 sysdeps/posix
341 sysdeps/i386/i686
342 sysdeps/i386/i486
343 sysdeps/libm-i387/i686
344 sysdeps/i386/fpu
345 sysdeps/libm-i387
346 sysdeps/i386
347 sysdeps/wordsize-32
348 sysdeps/ieee754
349 sysdeps/libm-ieee754
350 sysdeps/generic
351 @end smallexample
352
353 Different machine architectures are conventionally subdirectories at the
354 top level of the @file{sysdeps} directory tree.  For example,
355 @w{@file{sysdeps/sparc}} and @w{@file{sysdeps/m68k}}.  These contain
356 files specific to those machine architectures, but not specific to any
357 particular operating system.  There might be subdirectories for
358 specializations of those architectures, such as
359 @w{@file{sysdeps/m68k/68020}}. Code which is specific to the
360 floating-point coprocessor used with a particular machine should go in
361 @w{@file{sysdeps/@var{machine}/fpu}}.
362
363 There are a few directories at the top level of the @file{sysdeps}
364 hierarchy that are not for particular machine architectures.
365
366 @table @file
367 @item generic
368 As described above (@pxref{Porting}), this is the subdirectory
369 that every configuration implicitly uses after all others.
370
371 @item ieee754
372 This directory is for code using the IEEE 754 floating-point format,
373 where the C type @code{float} is IEEE 754 single-precision format, and
374 @code{double} is IEEE 754 double-precision format.  Usually this
375 directory is referred to in the @file{Implies} file in a machine
376 architecture-specific directory, such as @file{m68k/Implies}.
377
378 @item libm-ieee754
379 This directory contains an implementation of a mathematical library
380 usable on platforms which use @w{IEEE 754} conformant floating-point
381 arithmetic.
382
383 @item libm-i387
384 This is a special case.  Ideally the code should be in
385 @file{sysdeps/i386/fpu} but for various reasons it is kept aside.
386
387 @item posix
388 This directory contains implementations of things in the library in
389 terms of @sc{POSIX.1} functions.  This includes some of the @sc{POSIX.1}
390 functions themselves.  Of course, @sc{POSIX.1} cannot be completely
391 implemented in terms of itself, so a configuration using just
392 @file{posix} cannot be complete.
393
394 @item unix
395 This is the directory for Unix-like things.  @xref{Porting to Unix}.
396 @file{unix} implies @file{posix}.  There are some special-purpose
397 subdirectories of @file{unix}:
398
399 @table @file
400 @item unix/common
401 This directory is for things common to both BSD and System V release 4.
402 Both @file{unix/bsd} and @file{unix/sysv/sysv4} imply @file{unix/common}.
403
404 @item unix/inet
405 This directory is for @code{socket} and related functions on Unix systems.
406 @file{unix/inet/Subdirs} enables the @file{inet} top-level subdirectory.
407 @file{unix/common} implies @file{unix/inet}.
408 @end table
409
410 @item mach
411 This is the directory for things based on the Mach microkernel from CMU
412 (including the GNU operating system).  Other basic operating systems
413 (VMS, for example) would have their own directories at the top level of
414 the @file{sysdeps} hierarchy, parallel to @file{unix} and @file{mach}.
415 @end table
416
417 @node Porting to Unix
418 @appendixsubsec Porting the GNU C Library to Unix Systems
419
420 Most Unix systems are fundamentally very similar.  There are variations
421 between different machines, and variations in what facilities are
422 provided by the kernel.  But the interface to the operating system
423 facilities is, for the most part, pretty uniform and simple.
424
425 The code for Unix systems is in the directory @file{unix}, at the top
426 level of the @file{sysdeps} hierarchy.  This directory contains
427 subdirectories (and subdirectory trees) for various Unix variants.
428
429 The functions which are system calls in most Unix systems are
430 implemented in assembly code, which is generated automatically from
431 specifications in files named @file{syscalls.list}.  There are several
432 such files, one in @file{sysdeps/unix} and others in its subdirectories.
433 Some special system calls are implemented in files that are named with a
434 suffix of @samp{.S}; for example, @file{_exit.S}.  Files ending in
435 @samp{.S} are run through the C preprocessor before being fed to the
436 assembler.
437
438 These files all use a set of macros that should be defined in
439 @file{sysdep.h}.  The @file{sysdep.h} file in @file{sysdeps/unix}
440 partially defines them; a @file{sysdep.h} file in another directory must
441 finish defining them for the particular machine and operating system
442 variant.  See @file{sysdeps/unix/sysdep.h} and the machine-specific
443 @file{sysdep.h} implementations to see what these macros are and what
444 they should do.@refill
445
446 The system-specific makefile for the @file{unix} directory
447 (@file{sysdeps/unix/Makefile}) gives rules to generate several files
448 from the Unix system you are building the library on (which is assumed
449 to be the target system you are building the library @emph{for}).  All
450 the generated files are put in the directory where the object files are
451 kept; they should not affect the source tree itself.  The files
452 generated are @file{ioctls.h}, @file{errnos.h}, @file{sys/param.h}, and
453 @file{errlist.c} (for the @file{stdio} section of the library).
454
455 @ignore
456 @c This section might be a good idea if it is finished,
457 @c but there's no point including it as it stands. --rms
458 @c @appendixsec Compatibility with Traditional C
459
460 @c ??? This section is really short now.  Want to keep it? --roland
461
462 @c It's not anymore true.  glibc 2.1 cannot be used with K&R compilers.
463 @c --drepper
464
465 Although the GNU C library implements the @w{ISO C} library facilities, you
466 @emph{can} use the GNU C library with traditional, ``pre-ISO'' C
467 compilers.  However, you need to be careful because the content and
468 organization of the GNU C library header files differs from that of
469 traditional C implementations.  This means you may need to make changes
470 to your program in order to get it to compile.
471 @end ignore