maint.texi

一个C源代码分析器

@c \input /gd/gnu/doc/texinfo
@c This is for making the `INSTALL' file for the distribution.
@c Makeinfo ignores it when processing the file from the include.
@setfilename INSTALL

@node Maintenance, Copying, Library Summary, Top
@appendix Library Maintenance

@menu
* Installation::          How to configure, compile and
                             install the GNU C library.
* Reporting Bugs::        How to report bugs (if you want to
                             get them fixed) and other troubles
                             you may have with the GNU C library.
* 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.
* Contributors::          Contributors to the GNU C Library.
@end menu

@node Installation
@appendixsec How to Install the GNU C Library
@cindex installing the library

Installation of the GNU C library is relatively simple.

You need the latest version of GNU @code{make}.  Modifying the GNU C
Library to work with other @code{make} programs would be so hard that we
recommend you port GNU @code{make} instead.  @strong{Really.}@refill

To configure the GNU C library for your system, run the shell script
@file{configure} with @code{sh}.  Use an argument which is the
conventional GNU name for your system configuration---for example,
@samp{sparc-sun-sunos4.1}, for a Sun 4 running Sunos 4.1.
@xref{Installation, Installation, Installing GNU CC, gcc.info, Using and
Porting GNU CC}, for a full description of standard GNU configuration
names.  If you omit the configuration name, @file{configure} will try to
guess one for you by inspecting the system it is running on.  It may or
may not be able to come up with a guess, and the its guess might be
wrong.  @file{configure} will tell you the canonical name of the chosen
configuration before proceeding.

The GNU C Library currently supports configurations that match the
following patterns:

@smallexample
alpha-dec-osf1
i386-@var{anything}-bsd4.3
i386-@var{anything}-gnu
i386-@var{anything}-isc2.2
i386-@var{anything}-isc3.@var{n}
i386-@var{anything}-sco3.2
i386-@var{anything}-sco3.2v4
i386-@var{anything}-sysv
i386-@var{anything}-sysv4
i386-force_cpu386-none
i386-sequent-bsd
i960-nindy960-none
m68k-hp-bsd4.3
m68k-mvme135-none
m68k-mvme136-none
m68k-sony-newsos3
m68k-sony-newsos4
m68k-sun-sunos4.@var{n}
mips-dec-ultrix4.@var{n}
mips-sgi-irix4.@var{n}
sparc-sun-solaris2.@var{n}
sparc-sun-sunos4.@var{n}
@end smallexample

While no other configurations are supported, there are handy aliases for
these few.  (These aliases work in other GNU software as well.)

@smallexample
decstation
hp320-bsd4.3 hp300bsd
i386-sco
i386-sco3.2v4
i386-sequent-dynix
i386-svr4
news
sun3-sunos4.@var{n} sun3
sun4-solaris2.@var{n} sun4-sunos5.@var{n}
sun4-sunos4.@var{n} sun4
@end smallexample

Here are some options that you should specify (if appropriate) when
you run @code{configure}:

@table @samp
@item --with-gnu-ld
Use this option if you plan to use GNU @code{ld} to link programs with
the GNU C Library.  (We strongly recommend that you do.)  This option
enables use of features that exist only in GNU @code{ld}; so if you
configure for GNU @code{ld} you must use GNU @code{ld} @emph{every time}
you link with the GNU C Library, and when building it.

@item --with-gnu-as
Use this option if you plan to use the GNU assembler, @code{gas}, when
building the GNU C Library.  On some systems, the library may not build
properly if you do @emph{not} use @code{gas}.

@c extra blank line makes it look better
@item --nfp

Use this option if your computer lacks hardware floating point support.

@item --prefix=@var{directory}
Install machine-independent data files in subdirectories of
@file{@var{directory}}.  (You can also set this in @file{configparms};
see below.)

@item --exec-prefix=@var{directory}
Install the library and other machine-dependent files in subdirectories
of @file{@var{directory}}.  (You can also set this in
@file{configparms}; see below.)
@end table

The simplest way to run @code{configure} is to do it in the directory
that contains the library sources.  This prepares to build the library
in that very directory.

You can prepare to build the library in some other directory by going
to that other directory to run @code{configure}.  In order to run
configure, you will have to specify a directory for it, like this:

@smallexample
mkdir sun4
cd sun4
../configure sparc-sun-sunos4.1
@end smallexample

@noindent
@code{configure} looks for the sources in whatever directory you
specified for finding @code{configure} itself.  It does not matter where
in the file system the source and build directories are---as long as you
specify the source directory when you run @code{configure}, you will get
the proper results.

This feature lets you keep sources and binaries in different
directories, and that makes it easy to build the library for several
different machines from the same set of sources.  Simply create a 
build directory for each target machine, and run @code{configure} in
that directory specifying the target machine's configuration name.

The library has a number of special-purpose configuration parameters.
These are defined in the file @file{Makeconfig}; see the comments in
that file for the details.

But don't edit the file @file{Makeconfig} yourself---instead, create a
file @file{configparms} in the directory where you are building the
library, and define in that file the parameters you want to specify.
@file{configparms} should @strong{not} be an edited copy of
@file{Makeconfig}; specify only the parameters that you want to
override.  To see how to set these parameters, find the section of
@file{Makeconfig} that says ``These are the configuration variables.''
Then for each parameter that you want to change, copy the definition
from @file{Makeconfig} to your new @file{configparms} file, and change
the value as appropriate for your system.

It is easy to configure the GNU C library for cross-compilation by
setting a few variables in @file{configparms}.  Set @code{CC} to the
cross-compiler for the target you configured the library for; it is
important to use this same @code{CC} value when running
@code{configure}, like this: @samp{CC=@var{target}-gcc configure
@var{target}}.  Set @code{BUILD_CC} to the compiler to use for for
programs run on the build system as part of compiling the library.  You
may need to set @code{AR} and @code{RANLIB} to cross-compiling versions
of @code{ar} and @code{ranlib} if the native tools are not configured to
work with object files for the target you configured for.

Some of the machine-dependent code for some machines uses extensions in
the GNU C compiler, so you may need to compile the library with GCC.
(In fact, all of the existing complete ports require GCC.)

The current release of the C library contains some header files that the
compiler normally provides: @file{stddef.h}, @file{stdarg.h}, and
several files with names of the form @file{va-@var{machine}.h}.  The
versions of these files that came with older releases of GCC do not work
properly with the GNU C library.  The @file{stddef.h} file in release
2.2 and later of GCC is correct.  If you have release 2.2 or later of
GCC, use its version of @file{stddef.h} instead of the C library's.  To
do this, put the line @w{@samp{override stddef.h =}} in
@file{configparms}.  The other files are corrected in release 2.3 and
later of GCC.  @file{configure} will automatically detect whether the
installed @file{stdarg.h} and @file{va-@var{machine}.h} files are
compatible with the C library, and use its own if not.

There is a potential problem with the @code{size_t} type and versions of
GCC prior to release 2.4.  ANSI C requires that @code{size_t} always be
an unsigned type.  For compatibility with existing systems' header
files, GCC defines @code{size_t} in @file{stddef.h} to be whatever type
the system's @file{sys/types.h} defines it to be.  Most Unix systems
that define @code{size_t} in @file{sys/types.h}, define it to be a
signed type.  Some code in the library depends on @code{size_t} being an
unsigned type, and will not work correctly if it is signed.

The GNU C library code which expects @code{size_t} to be unsigned is
correct.  The definition of @code{size_t} as a signed type is incorrect.
Versions 2.4 and later of GCC always define @code{size_t} as an unsigned
type, and GCC's @file{fixincludes} script massages the system's
@file{sys/types.h} so as not to conflict with this.

In the meantime, we work around this problem by telling GCC explicitly
to use an unsigned type for @code{size_t} when compiling the GNU C
library.  @file{configure} will automatically detect what type GCC uses
for @code{size_t} arrange to override it if necessary.

To build the library, type @code{make lib}.  This will produce a lot of
output, some of which looks like errors from @code{make} (but isn't).
Look for error messages from @code{make} containing @samp{***}.  Those
indicate that something is really wrong.

To build and run some test programs which exercise some of the library
facilities, type @code{make tests}.  This will produce several files
with names like @file{@var{program}.out}.

To format the @cite{GNU C Library Reference Manual} for printing, type
@w{@code{make dvi}}.  To format the Info version of the manual for on
line reading with @kbd{C-h i} in Emacs or with the @code{info} program,
type @w{@code{make info}}.

To install the library and its header files, and the Info files of the
manual, type @code{make install}, after setting the installation
directories in @file{configparms}.  This will build things if necessary,
before installing them.@refill

@node Reporting Bugs
@appendixsec Reporting Bugs
@cindex reporting bugs
@cindex bugs, reporting

There are probably bugs in the GNU C library.  There are certainly
errors and omissions in this manual.  If you report them, they will get
fixed.  If you don't, no one will ever know about them and they will
remain unfixed for all eternity, if not longer.

To report a bug, first you must find it.  Hopefully, this will be the
hard part.  Once you've found a bug, make sure it's really a bug.  A
good way to do this is to see if the GNU C library behaves the same way
some other C library does.  If so, probably you are wrong and the
libraries are right (but not necessarily).  If not, one of the libraries
is probably wrong.

Once you're sure you've found a bug, try to narrow it down to the
smallest test case that reproduces the problem.  In the case of a C
library, you really only need to narrow it down to one library
function call, if possible.  This should not be too difficult.

The final step when you have a simple test case is to report the bug.
When reporting a bug, send your test case, the results you got, the
results you expected, what you think the problem might be (if you've
thought of anything), your system type, and the version of the GNU C
library which you are using.  Also include the files
@file{config.status} and @file{config.make} which are created by running
@file{configure}; they will be in whatever directory was current when
you ran @file{configure}.

If you think you have found some way in which the GNU C library does not
conform to the ANSI and POSIX standards (@pxref{Standards and
Portability}), that is definitely a bug.  Report it!@refill

Send bug reports to the Internet address
@samp{bug-glibc@@prep.ai.mit.edu} or the UUCP path
@samp{mit-eddie!prep.ai.mit.edu!bug-glibc}.  If you have other problems
with installation or use, please report those as well.@refill

If you are not sure how a function should behave, and this manual
doesn't tell you, that's a bug in the manual.  Report that too!  If the
function's behavior disagrees with the manual, then either the library
or the manual has a bug, so report the disagreement.  If you find any
errors or omissions in this manual, please report them to the Internet
address @samp{bug-glibc-manual@@prep.ai.mit.edu} or the UUCP path
@samp{mit-eddie!prep.ai.mit.edu!bug-glibc-manual}.

@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{stdio} has all the standard I/O 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