diff options
Diffstat (limited to 'REORG.TODO/manual/maint.texi')
| -rw-r--r-- | REORG.TODO/manual/maint.texi | 539 |
1 files changed, 539 insertions, 0 deletions
diff --git a/REORG.TODO/manual/maint.texi b/REORG.TODO/manual/maint.texi new file mode 100644 index 0000000000..473ab162f0 --- /dev/null +++ b/REORG.TODO/manual/maint.texi @@ -0,0 +1,539 @@ +@node Maintenance, Platform, Installation, Top +@c %MENU% How to enhance and port the GNU C Library +@appendix Library Maintenance + +@menu +* Source Layout:: How to add new functions or header files + to the GNU C Library. +* Porting:: How to port the GNU C Library to + a new machine or operating system. +@end menu + +@node Source Layout +@appendixsec Adding New Functions + +The process of building the library is driven by the makefiles, which +make heavy use of special features of GNU @code{make}. The makefiles +are very complex, and you probably don't want to try to understand them. +But what they do is fairly straightforward, and only requires that you +define a few variables in the right places. + +The library sources are divided into subdirectories, grouped by topic. + +The @file{string} subdirectory has all the string-manipulation +functions, @file{math} has all the mathematical functions, etc. + +Each subdirectory contains a simple makefile, called @file{Makefile}, +which defines a few @code{make} variables and then includes the global +makefile @file{Rules} with a line like: + +@smallexample +include ../Rules +@end smallexample + +@noindent +The basic variables that a subdirectory makefile defines are: + +@table @code +@item subdir +The name of the subdirectory, for example @file{stdio}. +This variable @strong{must} be defined. + +@item headers +The names of the header files in this section of the library, +such as @file{stdio.h}. + +@item routines +@itemx aux +The names of the modules (source files) in this section of the library. +These should be simple names, such as @samp{strlen} (rather than +complete file names, such as @file{strlen.c}). Use @code{routines} for +modules that define functions in the library, and @code{aux} for +auxiliary modules containing things like data definitions. But the +values of @code{routines} and @code{aux} are just concatenated, so there +really is no practical difference.@refill + +@item tests +The names of test programs for this section of the library. These +should be simple names, such as @samp{tester} (rather than complete file +names, such as @file{tester.c}). @w{@samp{make tests}} will build and +run all the test programs. If a test program needs input, put the test +data in a file called @file{@var{test-program}.input}; it will be given to +the test program on its standard input. If a test program wants to be +run with arguments, put the arguments (all on a single line) in a file +called @file{@var{test-program}.args}. Test programs should exit with +zero status when the test passes, and nonzero status when the test +indicates a bug in the library or error in building. + +@item others +The names of ``other'' programs associated with this section of the +library. These are programs which are not tests per se, but are other +small programs included with the library. They are built by +@w{@samp{make others}}.@refill + +@item install-lib +@itemx install-data +@itemx install +Files to be installed by @w{@samp{make install}}. Files listed in +@samp{install-lib} are installed in the directory specified by +@samp{libdir} in @file{configparms} or @file{Makeconfig} +(@pxref{Installation}). Files listed in @code{install-data} are +installed in the directory specified by @samp{datadir} in +@file{configparms} or @file{Makeconfig}. Files listed in @code{install} +are installed in the directory specified by @samp{bindir} in +@file{configparms} or @file{Makeconfig}.@refill + +@item distribute +Other files from this subdirectory which should be put into a +distribution tar file. You need not list here the makefile itself or +the source and header files listed in the other standard variables. +Only define @code{distribute} if there are files used in an unusual way +that should go into the distribution. + +@item generated +Files which are generated by @file{Makefile} in this subdirectory. +These files will be removed by @w{@samp{make clean}}, and they will +never go into a distribution. + +@item extra-objs +Extra object files which are built by @file{Makefile} in this +subdirectory. This should be a list of file names like @file{foo.o}; +the files will actually be found in whatever directory object files are +being built in. These files will be removed by @w{@samp{make clean}}. +This variable is used for secondary object files needed to build +@code{others} or @code{tests}. +@end table + +@menu +* Platform: Adding Platform-specific. Adding platform-specific + features. +@end menu + +@node Adding Platform-specific +@appendixsubsec Platform-specific types, macros and functions + +It's sometimes necessary to provide nonstandard, platform-specific +features to developers. The C library is traditionally the +lowest library layer, so it makes sense for it to provide these +low-level features. However, including these features in the C +library may be a disadvantage if another package provides them +as well as there will be two conflicting versions of them. Also, +the features won't be available to projects that do not use +@theglibc{} but use other GNU tools, like GCC. + +The current guidelines are: +@itemize @bullet +@item +If the header file provides features that only make sense on a particular +machine architecture and have nothing to do with an operating system, then +the features should ultimately be provided as GCC built-in functions. Until +then, @theglibc{} may provide them in the header file. When the GCC built-in +functions become available, those provided in the header file should be made +conditionally available prior to the GCC version in which the built-in +function was made available. + +@item +If the header file provides features that are specific to an operating system, +both GCC and @theglibc{} could provide it, but @theglibc{} is preferred +as it already has a lot of information about the operating system. + +@item +If the header file provides features that are specific to an operating system +but used by @theglibc{}, then @theglibc{} should provide them. +@end itemize + +The general solution for providing low-level features is to export them as +follows: + +@itemize @bullet +@item +A nonstandard, low-level header file that defines macros and inline +functions should be called @file{sys/platform/@var{name}.h}. + +@item +Each header file's name should include the platform name, to avoid +users thinking there is anything in common between the different +header files for different platforms. For example, a +@file{sys/platform/@var{arch}.h} name such as +@file{sys/platform/ppc.h} is better than @file{sys/platform.h}. + +@item +A platform-specific header file provided by @theglibc{} should coordinate +with GCC such that compiler built-in versions of the functions and macros are +preferred if available. This means that user programs will only ever need to +include @file{sys/platform/@var{arch}.h}, keeping the same names of types, +macros, and functions for convenience and portability. + +@item +Each included symbol must have the prefix @code{__@var{arch}_}, such as +@code{__ppc_get_timebase}. +@end itemize + + +The easiest way to provide a header file is to add it to the +@code{sysdep_headers} variable. For example, the combination of +Linux-specific header files on PowerPC could be provided like this: + +@smallexample +sysdep_headers += sys/platform/ppc.h +@end smallexample + +Then ensure that you have added a @file{sys/platform/ppc.h} +header file in the machine-specific directory, e.g., +@file{sysdeps/powerpc/sys/platform/ppc.h}. + + +@node Porting +@appendixsec Porting @theglibc{} + +@Theglibc{} is written to be easily portable to a variety of +machines and operating systems. Machine- and operating system-dependent +functions are well separated to make it easy to add implementations for +new machines or operating systems. This section describes the layout of +the library source tree and explains the mechanisms used to select +machine-dependent code to use. + +All the machine-dependent and operating system-dependent files in the +library are in the subdirectory @file{sysdeps} under the top-level +library source directory. This directory contains a hierarchy of +subdirectories (@pxref{Hierarchy Conventions}). + +Each subdirectory of @file{sysdeps} contains source files for a +particular machine or operating system, or for a class of machine or +operating system (for example, systems by a particular vendor, or all +machines that use IEEE 754 floating-point format). A configuration +specifies an ordered list of these subdirectories. Each subdirectory +implicitly appends its parent directory to the list. For example, +specifying the list @file{unix/bsd/vax} is equivalent to specifying the +list @file{unix/bsd/vax unix/bsd unix}. A subdirectory can also specify +that it implies other subdirectories which are not directly above it in +the directory hierarchy. If the file @file{Implies} exists in a +subdirectory, it lists other subdirectories of @file{sysdeps} which are +appended to the list, appearing after the subdirectory containing the +@file{Implies} file. Lines in an @file{Implies} file that begin with a +@samp{#} character are ignored as comments. For example, +@file{unix/bsd/Implies} contains:@refill +@smallexample +# BSD has Internet-related things. +unix/inet +@end smallexample +@noindent +and @file{unix/Implies} contains: +@need 300 +@smallexample +posix +@end smallexample + +@noindent +So the final list is @file{unix/bsd/vax unix/bsd unix/inet unix posix}. + +@file{sysdeps} has a ``special'' subdirectory called @file{generic}. It +is always implicitly appended to the list of subdirectories, so you +needn't put it in an @file{Implies} file, and you should not create any +subdirectories under it intended to be new specific categories. +@file{generic} serves two purposes. First, the makefiles do not bother +to look for a system-dependent version of a file that's not in +@file{generic}. This means that any system-dependent source file must +have an analogue in @file{generic}, even if the routines defined by that +file are not implemented on other platforms. Second, the @file{generic} +version of a system-dependent file is used if the makefiles do not find +a version specific to the system you're compiling for. + +If it is possible to implement the routines in a @file{generic} file in +machine-independent C, using only other machine-independent functions in +the C library, then you should do so. Otherwise, make them stubs. A +@dfn{stub} function is a function which cannot be implemented on a +particular machine or operating system. Stub functions always return an +error, and set @code{errno} to @code{ENOSYS} (Function not implemented). +@xref{Error Reporting}. If you define a stub function, you must place +the statement @code{stub_warning(@var{function})}, where @var{function} +is the name of your function, after its definition. This causes the +function to be listed in the installed @code{<gnu/stubs.h>}, and +makes GNU ld warn when the function is used. + +Some rare functions are only useful on specific systems and aren't +defined at all on others; these do not appear anywhere in the +system-independent source code or makefiles (including the +@file{generic} directory), only in the system-dependent @file{Makefile} +in the specific system's subdirectory. + +If you come across a file that is in one of the main source directories +(@file{string}, @file{stdio}, etc.), and you want to write a machine- or +operating system-dependent version of it, move the file into +@file{sysdeps/generic} and write your new implementation in the +appropriate system-specific subdirectory. Note that if a file is to be +system-dependent, it @strong{must not} appear in one of the main source +directories.@refill + +There are a few special files that may exist in each subdirectory of +@file{sysdeps}: + +@comment Blank lines after items make the table look better. +@table @file +@item Makefile + +A makefile for this machine or operating system, or class of machine or +operating system. This file is included by the library makefile +@file{Makerules}, which is used by the top-level makefile and the +subdirectory makefiles. It can change the variables set in the +including makefile or add new rules. It can use GNU @code{make} +conditional directives based on the variable @samp{subdir} (see above) to +select different sets of variables and rules for different sections of +the library. It can also set the @code{make} variable +@samp{sysdep-routines}, to specify extra modules to be included in the +library. You should use @samp{sysdep-routines} rather than adding +modules to @samp{routines} because the latter is used in determining +what to distribute for each subdirectory of the main source tree.@refill + +Each makefile in a subdirectory in the ordered list of subdirectories to +be searched is included in order. Since several system-dependent +makefiles may be included, each should append to @samp{sysdep-routines} +rather than simply setting it: + +@smallexample +sysdep-routines := $(sysdep-routines) foo bar +@end smallexample + +@need 1000 +@item Subdirs + +This file contains the names of new whole subdirectories under the +top-level library source tree that should be included for this system. +These subdirectories are treated just like the system-independent +subdirectories in the library source tree, such as @file{stdio} and +@file{math}. + +Use this when there are completely new sets of functions and header +files that should go into the library for the system this subdirectory +of @file{sysdeps} implements. For example, +@file{sysdeps/unix/inet/Subdirs} contains @file{inet}; the @file{inet} +directory contains various network-oriented operations which only make +sense to put in the library on systems that support the Internet.@refill + +@item configure + +This file is a shell script fragment to be run at configuration time. +The top-level @file{configure} script uses the shell @code{.} command to +read the @file{configure} file in each system-dependent directory +chosen, in order. The @file{configure} files are often generated from +@file{configure.ac} files using Autoconf. + +A system-dependent @file{configure} script will usually add things to +the shell variables @samp{DEFS} and @samp{config_vars}; see the +top-level @file{configure} script for details. The script can check for +@w{@samp{--with-@var{package}}} options that were passed to the +top-level @file{configure}. For an option +@w{@samp{--with-@var{package}=@var{value}}} @file{configure} sets the +shell variable @w{@samp{with_@var{package}}} (with any dashes in +@var{package} converted to underscores) to @var{value}; if the option is +just @w{@samp{--with-@var{package}}} (no argument), then it sets +@w{@samp{with_@var{package}}} to @samp{yes}. + +@item configure.ac + +This file is an Autoconf input fragment to be processed into the file +@file{configure} in this subdirectory. @xref{Introduction,,, +autoconf.info, Autoconf: Generating Automatic Configuration Scripts}, +for a description of Autoconf. You should write either @file{configure} +or @file{configure.ac}, but not both. The first line of +@file{configure.ac} should invoke the @code{m4} macro +@samp{GLIBC_PROVIDES}. This macro does several @code{AC_PROVIDE} calls +for Autoconf macros which are used by the top-level @file{configure} +script; without this, those macros might be invoked again unnecessarily +by Autoconf. +@end table + +That is the general system for how system-dependencies are isolated. +@iftex +The next section explains how to decide what directories in +@file{sysdeps} to use. @ref{Porting to Unix}, has some tips on porting +the library to Unix variants. +@end iftex + +@menu +* Hierarchy Conventions:: The layout of the @file{sysdeps} hierarchy. +* Porting to Unix:: Porting the library to an average + Unix-like system. +@end menu + +@node Hierarchy Conventions +@appendixsubsec Layout of the @file{sysdeps} Directory Hierarchy + +A GNU configuration name has three parts: the CPU type, the +manufacturer's name, and the operating system. @file{configure} uses +these to pick the list of system-dependent directories to look for. If +the @samp{--nfp} option is @emph{not} passed to @file{configure}, the +directory @file{@var{machine}/fpu} is also used. The operating system +often has a @dfn{base operating system}; for example, if the operating +system is @samp{Linux}, the base operating system is @samp{unix/sysv}. +The algorithm used to pick the list of directories is simple: +@file{configure} makes a list of the base operating system, +manufacturer, CPU type, and operating system, in that order. It then +concatenates all these together with slashes in between, to produce a +directory name; for example, the configuration @w{@samp{i686-linux-gnu}} +results in @file{unix/sysv/linux/i386/i686}. @file{configure} then +tries removing each element of the list in turn, so +@file{unix/sysv/linux} and @file{unix/sysv} are also tried, among others. +Since the precise version number of the operating system is often not +important, and it would be very inconvenient, for example, to have +identical @file{irix6.2} and @file{irix6.3} directories, +@file{configure} tries successively less specific operating system names +by removing trailing suffixes starting with a period. + +As an example, here is the complete list of directories that would be +tried for the configuration @w{@samp{i686-linux-gnu}} (with the +@file{crypt} and @file{linuxthreads} add-on): + +@smallexample +sysdeps/i386/elf +crypt/sysdeps/unix +linuxthreads/sysdeps/unix/sysv/linux +linuxthreads/sysdeps/pthread +linuxthreads/sysdeps/unix/sysv +linuxthreads/sysdeps/unix +linuxthreads/sysdeps/i386/i686 +linuxthreads/sysdeps/i386 +linuxthreads/sysdeps/pthread/no-cmpxchg +sysdeps/unix/sysv/linux/i386 +sysdeps/unix/sysv/linux +sysdeps/gnu +sysdeps/unix/common +sysdeps/unix/mman +sysdeps/unix/inet +sysdeps/unix/sysv/i386/i686 +sysdeps/unix/sysv/i386 +sysdeps/unix/sysv +sysdeps/unix/i386 +sysdeps/unix +sysdeps/posix +sysdeps/i386/i686 +sysdeps/i386/i486 +sysdeps/libm-i387/i686 +sysdeps/i386/fpu +sysdeps/libm-i387 +sysdeps/i386 +sysdeps/wordsize-32 +sysdeps/ieee754 +sysdeps/libm-ieee754 +sysdeps/generic +@end smallexample + +Different machine architectures are conventionally subdirectories at the +top level of the @file{sysdeps} directory tree. For example, +@w{@file{sysdeps/sparc}} and @w{@file{sysdeps/m68k}}. These contain +files specific to those machine architectures, but not specific to any +particular operating system. There might be subdirectories for +specializations of those architectures, such as +@w{@file{sysdeps/m68k/68020}}. Code which is specific to the +floating-point coprocessor used with a particular machine should go in +@w{@file{sysdeps/@var{machine}/fpu}}. + +There are a few directories at the top level of the @file{sysdeps} +hierarchy that are not for particular machine architectures. + +@table @file +@item generic +As described above (@pxref{Porting}), this is the subdirectory +that every configuration implicitly uses after all others. + +@item ieee754 +This directory is for code using the IEEE 754 floating-point format, +where the C type @code{float} is IEEE 754 single-precision format, and +@code{double} is IEEE 754 double-precision format. Usually this +directory is referred to in the @file{Implies} file in a machine +architecture-specific directory, such as @file{m68k/Implies}. + +@item libm-ieee754 +This directory contains an implementation of a mathematical library +usable on platforms which use @w{IEEE 754} conformant floating-point +arithmetic. + +@item libm-i387 +This is a special case. Ideally the code should be in +@file{sysdeps/i386/fpu} but for various reasons it is kept aside. + +@item posix +This directory contains implementations of things in the library in +terms of @sc{POSIX.1} functions. This includes some of the @sc{POSIX.1} +functions themselves. Of course, @sc{POSIX.1} cannot be completely +implemented in terms of itself, so a configuration using just +@file{posix} cannot be complete. + +@item unix +This is the directory for Unix-like things. @xref{Porting to Unix}. +@file{unix} implies @file{posix}. There are some special-purpose +subdirectories of @file{unix}: + +@table @file +@item unix/common +This directory is for things common to both BSD and System V release 4. +Both @file{unix/bsd} and @file{unix/sysv/sysv4} imply @file{unix/common}. + +@item unix/inet +This directory is for @code{socket} and related functions on Unix systems. +@file{unix/inet/Subdirs} enables the @file{inet} top-level subdirectory. +@file{unix/common} implies @file{unix/inet}. +@end table + +@item mach +This is the directory for things based on the Mach microkernel from CMU +(including @gnuhurdsystems{}). Other basic operating systems +(VMS, for example) would have their own directories at the top level of +the @file{sysdeps} hierarchy, parallel to @file{unix} and @file{mach}. +@end table + +@node Porting to Unix +@appendixsubsec Porting @theglibc{} to Unix Systems + +Most Unix systems are fundamentally very similar. There are variations +between different machines, and variations in what facilities are +provided by the kernel. But the interface to the operating system +facilities is, for the most part, pretty uniform and simple. + +The code for Unix systems is in the directory @file{unix}, at the top +level of the @file{sysdeps} hierarchy. This directory contains +subdirectories (and subdirectory trees) for various Unix variants. + +The functions which are system calls in most Unix systems are +implemented in assembly code, which is generated automatically from +specifications in files named @file{syscalls.list}. There are several +such files, one in @file{sysdeps/unix} and others in its subdirectories. +Some special system calls are implemented in files that are named with a +suffix of @samp{.S}; for example, @file{_exit.S}. Files ending in +@samp{.S} are run through the C preprocessor before being fed to the +assembler. + +These files all use a set of macros that should be defined in +@file{sysdep.h}. The @file{sysdep.h} file in @file{sysdeps/unix} +partially defines them; a @file{sysdep.h} file in another directory must +finish defining them for the particular machine and operating system +variant. See @file{sysdeps/unix/sysdep.h} and the machine-specific +@file{sysdep.h} implementations to see what these macros are and what +they should do.@refill + +The system-specific makefile for the @file{unix} directory +(@file{sysdeps/unix/Makefile}) gives rules to generate several files +from the Unix system you are building the library on (which is assumed +to be the target system you are building the library @emph{for}). All +the generated files are put in the directory where the object files are +kept; they should not affect the source tree itself. The files +generated are @file{ioctls.h}, @file{errnos.h}, @file{sys/param.h}, and +@file{errlist.c} (for the @file{stdio} section of the library). + +@ignore +@c This section might be a good idea if it is finished, +@c but there's no point including it as it stands. --rms +@c @appendixsec Compatibility with Traditional C + +@c ??? This section is really short now. Want to keep it? --roland + +@c It's not anymore true. glibc 2.1 cannot be used with K&R compilers. +@c --drepper + +Although @theglibc{} implements the @w{ISO C} library facilities, you +@emph{can} use @theglibc{} with traditional, ``pre-ISO'' C +compilers. However, you need to be careful because the content and +organization of the @glibcadj{} header files differs from that of +traditional C implementations. This means you may need to make changes +to your program in order to get it to compile. +@end ignore |