maint.texi

一个C源代码分析器

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}.@refill

@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

@node Porting
@appendixsec Porting the GNU C Library

The GNU C library 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 two ``special'' subdirectories, called @file{generic}
and @file{stub}.  These two are always implicitly appended to the list
of subdirectories (in that order), so you needn't put them in an
@file{Implies} file, and you should not create any subdirectories under
them.  @file{generic} is for things that can be implemented in
machine-independent C, using only other machine-independent functions in
the C library.  @file{stub} is for @dfn{stub} versions of functions
which cannot be implemented on a particular machine or operating system.
The stub functions always return an error, and set @code{errno} to
@code{ENOSYS} (Function not implemented).  @xref{Error Reporting}.

A source file is known to be system-dependent by its having a version in
@file{generic} or @file{stub}; every system-dependent function should
have either a generic or stub implementation (there is no point in
having both).

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 Dist

This file contains the names of files (relative to the subdirectory of
@file{sysdeps} in which it appears) which should be included in the
distribution.  List any new files used by rules in the @file{Makefile}
in the same directory, or header files used by the source files in that
directory.  You don't need to list files that are implementations
(either C or assembly source) of routines whose names are given in the
machine-independent makefiles in the main source tree.

@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.in} 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.in

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.in}, but not both.  The first line of
@file{configure.in} 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{sunos4.1}, the base operating system is @samp{unix/bsd}.
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{sparc-sun-sunos4.1}}
results in @file{unix/bsd/sun/sparc/sunos4.1}.  @file{configure} then
tries removing each element of the list in turn, so
@file{unix/bsd/sparc} and @file{sun/sparc} 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{sunos4.1.1} and @file{sunos4.1.2} 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{sparc-sun-sunos4.1}} (without the
@w{@samp{--nfp}} option):

@smallexample
sparc/fpu
unix/bsd/sun/sunos4.1/sparc
unix/bsd/sun/sunos4.1
unix/bsd/sun/sunos4/sparc
unix/bsd/sun/sunos4
unix/bsd/sun/sunos/sparc
unix/bsd/sun/sunos
unix/bsd/sun/sparc
unix/bsd/sun
unix/bsd/sunos4.1/sparc
unix/bsd/sunos4.1
unix/bsd/sunos4/sparc
unix/bsd/sunos4
unix/bsd/sunos/sparc
unix/bsd/sunos
unix/bsd/sparc
unix/bsd
unix/sun/sunos4.1/sparc
unix/sun/sunos4.1
unix/sun/sunos4/sparc
unix/sun/sunos4
unix/sun/sunos/sparc
unix/sun/sunos
unix/sun/sparc
unix/sun
unix/sunos4.1/sparc
unix/sunos4.1
unix/sunos4/sparc
unix/sunos4
unix/sunos/sparc
unix/sunos
unix/sparc
unix
sun/sunos4.1/sparc
sun/sunos4.1
sun/sunos4/sparc
sun/sunos4
sun/sunos/sparc
sun/sunos
sun/sparc
sun
sunos4.1/sparc
sunos4.1
sunos4/sparc
sunos4
sunos/sparc
sunos
sparc
@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
@itemx stub
As described above (@pxref{Porting}), these are the two subdirectories
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 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