path: root/manual/maint.texi

@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.
* Source Fortification::  Fortification of function calls.
* Symbol handling::       How to handle symbols in 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.

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

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

@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