modules that define functions in the library, and <CODE>aux</CODE> for
auxiliary modules containing things like data definitions.  But the
values of <CODE>routines</CODE> and <CODE>aux</CODE> are just concatenated, so there
really is no practical difference.<P>
<DT><CODE>tests</CODE>
<DD>The names of test programs for this section of the library.  These
should be simple names, such as <SAMP>`tester'</SAMP> (rather than complete file
names, such as <TT>`tester.c'</TT>).  <SAMP>`make tests'</SAMP> will build and
run all the test programs.  If a test program needs input, put the test
data in a file called <TT>`<VAR>test-program</VAR>.input'</TT>; 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 <TT>`<VAR>test-program</VAR>.args'</TT>.<P>
<DT><CODE>others</CODE>
<DD>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
<SAMP>`make others'</SAMP>.<P>
<DT><CODE>install-lib</CODE>
<DD><DT><CODE>install-data</CODE>
<DD><DT><CODE>install</CODE>
<DD>Files to be installed by <SAMP>`make install'</SAMP>.  Things listed in
<SAMP>`install-lib'</SAMP> are installed in the directory specified by
<SAMP>`libdir'</SAMP> in <TT>`Makeconfig'</TT> (see section <A HREF="library_30.html#SEC494" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_30.html#SEC494">How to Install the GNU C Library</A>).  Files listed
in <CODE>install-data</CODE> are installed in the directory specified by
<SAMP>`datadir'</SAMP> in <TT>`configparms'</TT> or <TT>`Makeconfig'</TT>.  Files listed
in <CODE>install</CODE> are installed in the directory specified by
<SAMP>`bindir'</SAMP> in <TT>`Makeconfig'</TT>.<P>
<DT><CODE>distribute</CODE>
<DD>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</CODE> if there are files used in an unusual way
that should go into the distribution.
<P>
<DT><CODE>generated</CODE>
<DD>Files which are generated by <TT>`Makefile'</TT> in this subdirectory.
These files will be removed by <SAMP>`make clean'</SAMP>, and they will
never go into a distribution.
<P>
<DT><CODE>extra-objs</CODE>
<DD>Extra object files which are built by <TT>`Makefile'</TT> in this
subdirectory.  This should be a list of file names like <TT>`foo.o'</TT>;
the files will actually be found in whatever directory object files are
being built in.  These files will be removed by <SAMP>`make clean'</SAMP>.
This variable is used for secondary object files needed to build
<CODE>others</CODE> or <CODE>tests</CODE>.
</DL>
<P>
<H2><A NAME="SEC497" HREF="library_toc.html#SEC497" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC497">Porting the GNU C Library</A></H2>
<P>
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.
<P>
All the machine-dependent and operating system-dependent files in the
library are in the subdirectory <TT>`sysdeps'</TT> under the top-level
library source directory.  This directory contains a hierarchy of
subdirectories (see section <A HREF="library_30.html#SEC498" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_30.html#SEC498">The Layout of the <TT>`sysdeps'</TT> Directory Hierarchy</A>).
<P>
Each subdirectory of <TT>`sysdeps'</TT> 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 <TT>`unix/bsd/vax'</TT> is equivalent to specifying the
list <TT>`unix/bsd/vax unix/bsd unix'</TT>.  A subdirectory can also specify
that it implies other subdirectories which are not directly above it in
the directory hierarchy.  If the file <TT>`Implies'</TT> exists in a
subdirectory, it lists other subdirectories of <TT>`sysdeps'</TT> which are
appended to the list, appearing after the subdirectory containing the
<TT>`Implies'</TT> file.  Lines in an <TT>`Implies'</TT> file that begin with a
<SAMP>`#'</SAMP> character are ignored as comments.  For example,
<TT>`unix/bsd/Implies'</TT> contains:<PRE>
# BSD has Internet-related things.
unix/inet
</PRE>
and <TT>`unix/Implies'</TT> contains:
<PRE>
posix
</PRE>
<P>
So the final list is <TT>`unix/bsd/vax unix/bsd vax unix/inet unix posix'</TT>.
<P>
<TT>`sysdeps'</TT> has two "special" subdirectories, called <TT>`generic'</TT>
and <TT>`stub'</TT>.  These two are always implicitly appended to the list
of subdirectories (in that order), so you needn't put them in an
<TT>`Implies'</TT> file, and you should not create any subdirectories under
them.  <TT>`generic'</TT> is for things that can be implemented in
machine-independent C, using only other machine-independent functions in
the C library.  <TT>`stub'</TT> is for <DFN>stub</DFN> 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</CODE> to
<CODE>ENOSYS</CODE> (Function not implemented).  See section <A HREF="library_2.html#SEC14" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_2.html#SEC14">Error Reporting</A>.
<P>
A source file is known to be system-dependent by its having a version in
<TT>`generic'</TT> or <TT>`stub'</TT>; every system-dependent function should
have either a generic or stub implementation (there is no point in
having both).
<P>
If you come across a file that is in one of the main source directories
(<TT>`string'</TT>, <TT>`stdio'</TT>, etc.), and you want to write a machine- or
operating system-dependent version of it, move the file into
<TT>`sysdeps/generic'</TT> 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</STRONG> appear in one of the main source
directories.<P>
There are a few special files that may exist in each subdirectory of
<TT>`sysdeps'</TT>:
<P>
<DL COMPACT>
<DT><TT>`Makefile'</TT>
<DD>A makefile for this machine or operating system, or class of machine or
operating system.  This file is included by the library makefile
<TT>`Makerules'</TT>, 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</CODE>
conditional directives based on the variable <SAMP>`subdir'</SAMP> (see above) to
select different sets of variables and rules for different sections of
the library.  It can also set the <CODE>make</CODE> variable
<SAMP>`sysdep-routines'</SAMP>, to specify extra modules to be included in the
library.  You should use <SAMP>`sysdep-routines'</SAMP> rather than adding
modules to <SAMP>`routines'</SAMP> because the latter is used in determining
what to distribute for each subdirectory of the main source tree.<P>
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'</SAMP>
rather than simply setting it:
<P>
<PRE>
sysdep-routines := $(sysdep-routines) foo bar
</PRE>
<P>
<DT><TT>`Subdirs'</TT>
<DD>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 <TT>`stdio'</TT> and
<TT>`math'</TT>.
<P>
Use this when there are whole new sets of routines and header files that
should go into the library for the system this subdirectory of
<TT>`sysdeps'</TT> implements.  For example,
<TT>`sysdeps/unix/inet/Subdirs'</TT> contains <TT>`inet'</TT>; the <TT>`inet'</TT>
directory contains various network-oriented operations which only make
sense to put in the library on systems that support the Internet.<P>
<DT><TT>`Dist'</TT>
<DD>This file contains the names of files (relative the the subdirectory of
<TT>`sysdeps'</TT> in which it appears) which should be included in the
distribution.  List any new files used by rules in the <TT>`Makefile'</TT>
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.
</DL>
<P>
That is the general system for how system-dependencies are isolated.
The next section explains how to decide what directories in
<TT>`sysdeps'</TT> to use.  section <A HREF="library_30.html#SEC499" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_30.html#SEC499">Porting the GNU C Library to Unix Systems</A>, has some tips on porting
the library to Unix variants.
<P>
<H3><A NAME="SEC498" HREF="library_toc.html#SEC498" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC498">The Layout of the <TT>`sysdeps'</TT> Directory Hierarchy</A></H3>
<P>
A GNU configuration name has three parts: the CPU type, the
manufacturer's name, and the operating system.  <TT>`configure'</TT> uses
these to pick the list of system-dependent directories to look for.  If
the <SAMP>`--nfp'</SAMP> option is <EM>not</EM> passed to <TT>`configure'</TT>, the
directory <TT>`<VAR>machine</VAR>/fpu'</TT> is also used.  The operating system
often has a <DFN>base operating system</DFN>; for example, if the operating
system is <SAMP>`sunos4.1'</SAMP>, the base operating system is <SAMP>`unix/bsd'</SAMP>.
The algorithm used to pick the list of directories is simple:
<TT>`configure'</TT> 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 <SAMP>`sparc-sun-sunos4.1'</SAMP>
results in <TT>`unix/bsd/sun/sparc/sunos4.1'</TT>.  <TT>`configure'</TT> then
tries removing each element of the list in turn, so
<TT>`unix/bsd/sparc'</TT> and <TT>`sun/sparc'</TT> 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 <TT>`sunos4.1.1'</TT> and <TT>`sunos4.1.2'</TT> directories,
<TT>`configure'</TT> tries successively less specific operating system names
by removing trailing suffixes starting with a period.
<P>
Here is the complete list of directories that would be tried for the
configuration <SAMP>`sparc-sun-sunos4.1'</SAMP>:
<P>
<PRE>
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/sparc
unix/bsd/sun
unix/bsd/sunos4.1/sparc
unix/bsd/sunos4.1
unix/bsd/sunos4/sparc
unix/bsd/sunos4
unix/bsd/sparc
unix/bsd
sun/sunos4.1/sparc
sun/sunos4.1
sun/sunos4/sparc
sun/sunos4
sun/sparc
sun
sunos4.1/sparc
sunos4.1
sunos4/sparc
sunos4
sparc
</PRE>
<P>
Different machine architectures are generally at the top level of the
<TT>`sysdeps'</TT> directory tree.  For example, <TT>`sysdeps/sparc'</TT>
and <TT>`sysdeps/m68k'</TT>.  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 <TT>`sysdeps/m68k/68020'</TT>. Code which is
specific to the floating-point coprocessor used with a particular
machine should go in <TT>`sysdeps/<VAR>machine</VAR>/fpu'</TT>.
<P>
There are a few directories at the top level of the <TT>`sysdeps'</TT>