405 lines
18 KiB
Plaintext
405 lines
18 KiB
Plaintext
Library Maintenance
|
|
*******************
|
|
|
|
Adding New Functions
|
|
====================
|
|
|
|
The process of building the library is driven by the makefiles, which
|
|
make heavy use of special features of GNU `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 `string' subdirectory has all the string-manipulation functions,
|
|
`math' has all the mathematical functions, etc.
|
|
|
|
Each subdirectory contains a simple makefile, called `Makefile',
|
|
which defines a few `make' variables and then includes the global
|
|
makefile `Rules' with a line like:
|
|
|
|
include ../Rules
|
|
|
|
The basic variables that a subdirectory makefile defines are:
|
|
|
|
`subdir'
|
|
The name of the subdirectory, for example `stdio'. This variable
|
|
*must* be defined.
|
|
|
|
`headers'
|
|
The names of the header files in this section of the library, such
|
|
as `stdio.h'.
|
|
|
|
`routines'
|
|
`aux'
|
|
The names of the modules (source files) in this section of the
|
|
library. These should be simple names, such as `strlen' (rather
|
|
than complete file names, such as `strlen.c'). Use `routines' for
|
|
modules that define functions in the library, and `aux' for
|
|
auxiliary modules containing things like data definitions. But the
|
|
values of `routines' and `aux' are just concatenated, so there
|
|
really is no practical difference.
|
|
|
|
`tests'
|
|
The names of test programs for this section of the library. These
|
|
should be simple names, such as `tester' (rather than complete file
|
|
names, such as `tester.c'). `make tests' will build and run all
|
|
the test programs. If a test program needs input, put the test
|
|
data in a file called `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 `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.
|
|
|
|
`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
|
|
`make others'.
|
|
|
|
`install-lib'
|
|
`install-data'
|
|
`install'
|
|
Files to be installed by `make install'. Files listed in
|
|
`install-lib' are installed in the directory specified by `libdir'
|
|
in `configparms' or `Makeconfig' (*note Installation::.). Files
|
|
listed in `install-data' are installed in the directory specified
|
|
by `datadir' in `configparms' or `Makeconfig'. Files listed in
|
|
`install' are installed in the directory specified by `bindir' in
|
|
`configparms' or `Makeconfig'.
|
|
|
|
`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 `distribute' if there are files used in an
|
|
unusual way that should go into the distribution.
|
|
|
|
`generated'
|
|
Files which are generated by `Makefile' in this subdirectory.
|
|
These files will be removed by `make clean', and they will never
|
|
go into a distribution.
|
|
|
|
`extra-objs'
|
|
Extra object files which are built by `Makefile' in this
|
|
subdirectory. This should be a list of file names like `foo.o';
|
|
the files will actually be found in whatever directory object
|
|
files are being built in. These files will be removed by
|
|
`make clean'. This variable is used for secondary object files
|
|
needed to build `others' or `tests'.
|
|
|
|
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 `sysdeps' under the top-level library
|
|
source directory. This directory contains a hierarchy of
|
|
subdirectories (*note Hierarchy Conventions::.).
|
|
|
|
Each subdirectory of `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 `unix/bsd/vax' is equivalent to specifying the list
|
|
`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 `Implies' exists in a subdirectory,
|
|
it lists other subdirectories of `sysdeps' which are appended to the
|
|
list, appearing after the subdirectory containing the `Implies' file.
|
|
Lines in an `Implies' file that begin with a `#' character are ignored
|
|
as comments. For example, `unix/bsd/Implies' contains:
|
|
# BSD has Internet-related things.
|
|
unix/inet
|
|
|
|
and `unix/Implies' contains:
|
|
posix
|
|
|
|
So the final list is `unix/bsd/vax unix/bsd unix/inet unix posix'.
|
|
|
|
`sysdeps' has a "special" subdirectory called `generic'. It is
|
|
always implicitly appended to the list of subdirectories, so you
|
|
needn't put it in an `Implies' file, and you should not create any
|
|
subdirectories under it intended to be new specific categories.
|
|
`generic' serves two purposes. First, the makefiles do not bother to
|
|
look for a system-dependent version of a file that's not in `generic'.
|
|
This means that any system-dependent source file must have an analogue
|
|
in `generic', even if the routines defined by that file are not
|
|
implemented on other platforms. Second. the `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 `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
|
|
"stub" function is a function which cannot be implemented on a
|
|
particular machine or operating system. Stub functions always return an
|
|
error, and set `errno' to `ENOSYS' (Function not implemented). *Note
|
|
Error Reporting::. If you define a stub function, you must place the
|
|
statement `stub_warning(FUNCTION)', where FUNCTION is the name of your
|
|
function, after its definition; also, you must include the file
|
|
`<stub-tag.h>' into your file. This causes the function to be listed
|
|
in the installed `<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 `generic'
|
|
directory), only in the system-dependent `Makefile' in the specific
|
|
system's subdirectory.
|
|
|
|
If you come across a file that is in one of the main source
|
|
directories (`string', `stdio', etc.), and you want to write a machine-
|
|
or operating system-dependent version of it, move the file into
|
|
`sysdeps/generic' and write your new implementation in the appropriate
|
|
system-specific subdirectory. Note that if a file is to be
|
|
system-dependent, it *must not* appear in one of the main source
|
|
directories.
|
|
|
|
There are a few special files that may exist in each subdirectory of
|
|
`sysdeps':
|
|
|
|
`Makefile'
|
|
A makefile for this machine or operating system, or class of
|
|
machine or operating system. This file is included by the library
|
|
makefile `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 `make'
|
|
conditional directives based on the variable `subdir' (see above)
|
|
to select different sets of variables and rules for different
|
|
sections of the library. It can also set the `make' variable
|
|
`sysdep-routines', to specify extra modules to be included in the
|
|
library. You should use `sysdep-routines' rather than adding
|
|
modules to `routines' because the latter is used in determining
|
|
what to distribute for each subdirectory of the main source tree.
|
|
|
|
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
|
|
`sysdep-routines' rather than simply setting it:
|
|
|
|
sysdep-routines := $(sysdep-routines) foo bar
|
|
|
|
`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 `stdio' and `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 `sysdeps' implements. For example,
|
|
`sysdeps/unix/inet/Subdirs' contains `inet'; the `inet' directory
|
|
contains various network-oriented operations which only make sense
|
|
to put in the library on systems that support the Internet.
|
|
|
|
`Dist'
|
|
This file contains the names of files (relative to the
|
|
subdirectory of `sysdeps' in which it appears) which should be
|
|
included in the distribution. List any new files used by rules in
|
|
the `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.
|
|
|
|
`configure'
|
|
This file is a shell script fragment to be run at configuration
|
|
time. The top-level `configure' script uses the shell `.' command
|
|
to read the `configure' file in each system-dependent directory
|
|
chosen, in order. The `configure' files are often generated from
|
|
`configure.in' files using Autoconf.
|
|
|
|
A system-dependent `configure' script will usually add things to
|
|
the shell variables `DEFS' and `config_vars'; see the top-level
|
|
`configure' script for details. The script can check for
|
|
`--with-PACKAGE' options that were passed to the top-level
|
|
`configure'. For an option `--with-PACKAGE=VALUE' `configure'
|
|
sets the shell variable `with_PACKAGE' (with any dashes in PACKAGE
|
|
converted to underscores) to VALUE; if the option is just
|
|
`--with-PACKAGE' (no argument), then it sets `with_PACKAGE' to
|
|
`yes'.
|
|
|
|
`configure.in'
|
|
This file is an Autoconf input fragment to be processed into the
|
|
file `configure' in this subdirectory. *Note Introduction:
|
|
(autoconf.info)Introduction, for a description of Autoconf. You
|
|
should write either `configure' or `configure.in', but not both.
|
|
The first line of `configure.in' should invoke the `m4' macro
|
|
`GLIBC_PROVIDES'. This macro does several `AC_PROVIDE' calls for
|
|
Autoconf macros which are used by the top-level `configure'
|
|
script; without this, those macros might be invoked again
|
|
unnecessarily by Autoconf.
|
|
|
|
That is the general system for how system-dependencies are isolated.
|
|
|
|
Layout of the `sysdeps' Directory Hierarchy
|
|
-------------------------------------------
|
|
|
|
A GNU configuration name has three parts: the CPU type, the
|
|
manufacturer's name, and the operating system. `configure' uses these
|
|
to pick the list of system-dependent directories to look for. If the
|
|
`--nfp' option is *not* passed to `configure', the directory
|
|
`MACHINE/fpu' is also used. The operating system often has a "base
|
|
operating system"; for example, if the operating system is `Linux', the
|
|
base operating system is `unix/sysv'. The algorithm used to pick the
|
|
list of directories is simple: `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
|
|
`i686-linux-gnu' results in `unix/sysv/linux/i386/i686'. `configure'
|
|
then tries removing each element of the list in turn, so
|
|
`unix/sysv/linux' and `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 `irix6.2' and `irix6.3' directories, `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 `i686-linux-gnu' (with the `crypt' and
|
|
`linuxthreads' add-on):
|
|
|
|
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
|
|
|
|
Different machine architectures are conventionally subdirectories at
|
|
the top level of the `sysdeps' directory tree. For example,
|
|
`sysdeps/sparc' and `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 `sysdeps/m68k/68020'. Code which is
|
|
specific to the floating-point coprocessor used with a particular
|
|
machine should go in `sysdeps/MACHINE/fpu'.
|
|
|
|
There are a few directories at the top level of the `sysdeps'
|
|
hierarchy that are not for particular machine architectures.
|
|
|
|
`generic'
|
|
As described above (*note Porting::.), this is the subdirectory
|
|
that every configuration implicitly uses after all others.
|
|
|
|
`ieee754'
|
|
This directory is for code using the IEEE 754 floating-point
|
|
format, where the C type `float' is IEEE 754 single-precision
|
|
format, and `double' is IEEE 754 double-precision format. Usually
|
|
this directory is referred to in the `Implies' file in a machine
|
|
architecture-specific directory, such as `m68k/Implies'.
|
|
|
|
`libm-ieee754'
|
|
This directory contains an implementation of a mathematical library
|
|
usable on platforms which use IEEE 754 conformant floating-point
|
|
arithmetic.
|
|
|
|
`libm-i387'
|
|
This is a special case. Ideally the code should be in
|
|
`sysdeps/i386/fpu' but for various reasons it is kept aside.
|
|
|
|
`posix'
|
|
This directory contains implementations of things in the library in
|
|
terms of POSIX.1 functions. This includes some of the POSIX.1
|
|
functions themselves. Of course, POSIX.1 cannot be completely
|
|
implemented in terms of itself, so a configuration using just
|
|
`posix' cannot be complete.
|
|
|
|
`unix'
|
|
This is the directory for Unix-like things. *Note Porting to
|
|
Unix::. `unix' implies `posix'. There are some special-purpose
|
|
subdirectories of `unix':
|
|
|
|
`unix/common'
|
|
This directory is for things common to both BSD and System V
|
|
release 4. Both `unix/bsd' and `unix/sysv/sysv4' imply
|
|
`unix/common'.
|
|
|
|
`unix/inet'
|
|
This directory is for `socket' and related functions on Unix
|
|
systems. `unix/inet/Subdirs' enables the `inet' top-level
|
|
subdirectory. `unix/common' implies `unix/inet'.
|
|
|
|
`mach'
|
|
This is the directory for things based on the Mach microkernel
|
|
from CMU (including the GNU operating system). Other basic
|
|
operating systems (VMS, for example) would have their own
|
|
directories at the top level of the `sysdeps' hierarchy, parallel
|
|
to `unix' and `mach'.
|
|
|
|
Porting the GNU C Library 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 `unix', at the top
|
|
level of the `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 `syscalls.list'. There are several such
|
|
files, one in `sysdeps/unix' and others in its subdirectories. Some
|
|
special system calls are implemented in files that are named with a
|
|
suffix of `.S'; for example, `_exit.S'. Files ending in `.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
|
|
`sysdep.h'. The `sysdep.h' file in `sysdeps/unix' partially defines
|
|
them; a `sysdep.h' file in another directory must finish defining them
|
|
for the particular machine and operating system variant. See
|
|
`sysdeps/unix/sysdep.h' and the machine-specific `sysdep.h'
|
|
implementations to see what these macros are and what they should do.
|
|
|
|
The system-specific makefile for the `unix' directory
|
|
(`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 *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 `ioctls.h', `errnos.h', `sys/param.h', and `errlist.c'
|
|
(for the `stdio' section of the library).
|
|
|