1: @node Maintenance, Contributors, Installation, Top
    2: @c %MENU% How to enhance and port the GNU C Library
    3: @appendix Library Maintenance
    4: 
    5: @menu
    6: * Source Layout::         How to add new functions or header files
    7:                              to the GNU C library.
    8: * Porting::               How to port the GNU C library to
    9:                              a new machine or operating system.
   10: @end menu
   11: 
   12: @node Source Layout
   13: @appendixsec Adding New Functions
   14: 
   15: The process of building the library is driven by the makefiles, which
   16: make heavy use of special features of GNU @code{make}.  The makefiles
   17: are very complex, and you probably don't want to try to understand them.
   18: But what they do is fairly straightforward, and only requires that you
   19: define a few variables in the right places.
   20: 
   21: The library sources are divided into subdirectories, grouped by topic.
   22: 
   23: The @file{string} subdirectory has all the string-manipulation
   24: functions, @file{math} has all the mathematical functions, etc.
   25: 
   26: Each subdirectory contains a simple makefile, called @file{Makefile},
   27: which defines a few @code{make} variables and then includes the global
   28: makefile @file{Rules} with a line like:
   29: 
   30: @smallexample
   31: include ../Rules
   32: @end smallexample
   33: 
   34: @noindent
   35: The basic variables that a subdirectory makefile defines are:
   36: 
   37: @table @code
   38: @item subdir
   39: The name of the subdirectory, for example @file{stdio}.
   40: This variable @strong{must} be defined.
   41: 
   42: @item headers
   43: The names of the header files in this section of the library,
   44: such as @file{stdio.h}.
   45: 
   46: @item routines
   47: @itemx aux
   48: The names of the modules (source files) in this section of the library.
   49: These should be simple names, such as @samp{strlen} (rather than
   50: complete file names, such as @file{strlen.c}).  Use @code{routines} for
   51: modules that define functions in the library, and @code{aux} for
   52: auxiliary modules containing things like data definitions.  But the
   53: values of @code{routines} and @code{aux} are just concatenated, so there
   54: really is no practical difference.@refill
   55: 
   56: @item tests
   57: The names of test programs for this section of the library.  These
   58: should be simple names, such as @samp{tester} (rather than complete file
   59: names, such as @file{tester.c}).  @w{@samp{make tests}} will build and
   60: run all the test programs.  If a test program needs input, put the test
   61: data in a file called @file{@var{test-program}.input}; it will be given to
   62: the test program on its standard input.  If a test program wants to be
   63: run with arguments, put the arguments (all on a single line) in a file
   64: called @file{@var{test-program}.args}.  Test programs should exit with
   65: zero status when the test passes, and nonzero status when the test
   66: indicates a bug in the library or error in building.
   67: 
   68: @item others
   69: The names of ``other'' programs associated with this section of the
   70: library.  These are programs which are not tests per se, but are other
   71: small programs included with the library.  They are built by
   72: @w{@samp{make others}}.@refill
   73: 
   74: @item install-lib
   75: @itemx install-data
   76: @itemx install
   77: Files to be installed by @w{@samp{make install}}.  Files listed in
   78: @samp{install-lib} are installed in the directory specified by
   79: @samp{libdir} in @file{configparms} or @file{Makeconfig}
   80: (@pxref{Installation}).  Files listed in @code{install-data} are
   81: installed in the directory specified by @samp{datadir} in
   82: @file{configparms} or @file{Makeconfig}.  Files listed in @code{install}
   83: are installed in the directory specified by @samp{bindir} in
   84: @file{configparms} or @file{Makeconfig}.@refill
   85: 
   86: @item distribute
   87: Other files from this subdirectory which should be put into a
   88: distribution tar file.  You need not list here the makefile itself or
   89: the source and header files listed in the other standard variables.
   90: Only define @code{distribute} if there are files used in an unusual way
   91: that should go into the distribution.
   92: 
   93: @item generated
   94: Files which are generated by @file{Makefile} in this subdirectory.
   95: These files will be removed by @w{@samp{make clean}}, and they will
   96: never go into a distribution.
   97: 
   98: @item extra-objs
   99: Extra object files which are built by @file{Makefile} in this
  100: subdirectory.  This should be a list of file names like @file{foo.o};
  101: the files will actually be found in whatever directory object files are
  102: being built in.  These files will be removed by @w{@samp{make clean}}.
  103: This variable is used for secondary object files needed to build
  104: @code{others} or @code{tests}.
  105: @end table
  106: 
  107: @node Porting
  108: @appendixsec Porting the GNU C Library
  109: 
  110: The GNU C library is written to be easily portable to a variety of
  111: machines and operating systems.  Machine- and operating system-dependent
  112: functions are well separated to make it easy to add implementations for
  113: new machines or operating systems.  This section describes the layout of
  114: the library source tree and explains the mechanisms used to select
  115: machine-dependent code to use.
  116: 
  117: All the machine-dependent and operating system-dependent files in the
  118: library are in the subdirectory @file{sysdeps} under the top-level
  119: library source directory.  This directory contains a hierarchy of
  120: subdirectories (@pxref{Hierarchy Conventions}).
  121: 
  122: Each subdirectory of @file{sysdeps} contains source files for a
  123: particular machine or operating system, or for a class of machine or
  124: operating system (for example, systems by a particular vendor, or all
  125: machines that use IEEE 754 floating-point format).  A configuration
  126: specifies an ordered list of these subdirectories.  Each subdirectory
  127: implicitly appends its parent directory to the list.  For example,
  128: specifying the list @file{unix/bsd/vax} is equivalent to specifying the
  129: list @file{unix/bsd/vax unix/bsd unix}.  A subdirectory can also specify
  130: that it implies other subdirectories which are not directly above it in
  131: the directory hierarchy.  If the file @file{Implies} exists in a
  132: subdirectory, it lists other subdirectories of @file{sysdeps} which are
  133: appended to the list, appearing after the subdirectory containing the
  134: @file{Implies} file.  Lines in an @file{Implies} file that begin with a
  135: @samp{#} character are ignored as comments.  For example,
  136: @file{unix/bsd/Implies} contains:@refill
  137: @smallexample
  138: # BSD has Internet-related things.
  139: unix/inet
  140: @end smallexample
  141: @noindent
  142: and @file{unix/Implies} contains:
  143: @need 300
  144: @smallexample
  145: posix
  146: @end smallexample
  147: 
  148: @noindent
  149: So the final list is @file{unix/bsd/vax unix/bsd unix/inet unix posix}.
  150: 
  151: @file{sysdeps} has a ``special'' subdirectory called @file{generic}.  It
  152: is always implicitly appended to the list of subdirectories, so you
  153: needn't put it in an @file{Implies} file, and you should not create any
  154: subdirectories under it intended to be new specific categories.
  155: @file{generic} serves two purposes.  First, the makefiles do not bother
  156: to look for a system-dependent version of a file that's not in
  157: @file{generic}.  This means that any system-dependent source file must
  158: have an analogue in @file{generic}, even if the routines defined by that
  159: file are not implemented on other platforms.  Second, the @file{generic}
  160: version of a system-dependent file is used if the makefiles do not find
  161: a version specific to the system you're compiling for.
  162: 
  163: If it is possible to implement the routines in a @file{generic} file in
  164: machine-independent C, using only other machine-independent functions in
  165: the C library, then you should do so.  Otherwise, make them stubs.  A
  166: @dfn{stub} function is a function which cannot be implemented on a
  167: particular machine or operating system.  Stub functions always return an
  168: error, and set @code{errno} to @code{ENOSYS} (Function not implemented).
  169: @xref{Error Reporting}.  If you define a stub function, you must place
  170: the statement @code{stub_warning(@var{function})}, where @var{function}
  171: is the name of your function, after its definition; also, you must
  172: include the file @code{<stub-tag.h>} into your file.  This causes the
  173: function to be listed in the installed @code{<gnu/stubs.h>}, and
  174: makes GNU ld warn when the function is used.
  175: 
  176: Some rare functions are only useful on specific systems and aren't
  177: defined at all on others; these do not appear anywhere in the
  178: system-independent source code or makefiles (including the
  179: @file{generic} directory), only in the system-dependent @file{Makefile}
  180: in the specific system's subdirectory.
  181: 
  182: If you come across a file that is in one of the main source directories
  183: (@file{string}, @file{stdio}, etc.), and you want to write a machine- or
  184: operating system-dependent version of it, move the file into
  185: @file{sysdeps/generic} and write your new implementation in the
  186: appropriate system-specific subdirectory.  Note that if a file is to be
  187: system-dependent, it @strong{must not} appear in one of the main source
  188: directories.@refill
  189: 
  190: There are a few special files that may exist in each subdirectory of
  191: @file{sysdeps}:
  192: 
  193: @comment Blank lines after items make the table look better.
  194: @table @file
  195: @item Makefile
  196: 
  197: A makefile for this machine or operating system, or class of machine or
  198: operating system.  This file is included by the library makefile
  199: @file{Makerules}, which is used by the top-level makefile and the
  200: subdirectory makefiles.  It can change the variables set in the
  201: including makefile or add new rules.  It can use GNU @code{make}
  202: conditional directives based on the variable @samp{subdir} (see above) to
  203: select different sets of variables and rules for different sections of
  204: the library.  It can also set the @code{make} variable
  205: @samp{sysdep-routines}, to specify extra modules to be included in the
  206: library.  You should use @samp{sysdep-routines} rather than adding
  207: modules to @samp{routines} because the latter is used in determining
  208: what to distribute for each subdirectory of the main source tree.@refill
  209: 
  210: Each makefile in a subdirectory in the ordered list of subdirectories to
  211: be searched is included in order.  Since several system-dependent
  212: makefiles may be included, each should append to @samp{sysdep-routines}
  213: rather than simply setting it:
  214: 
  215: @smallexample
  216: sysdep-routines := $(sysdep-routines) foo bar
  217: @end smallexample
  218: 
  219: @need 1000
  220: @item Subdirs
  221: 
  222: This file contains the names of new whole subdirectories under the
  223: top-level library source tree that should be included for this system.
  224: These subdirectories are treated just like the system-independent
  225: subdirectories in the library source tree, such as @file{stdio} and
  226: @file{math}.
  227: 
  228: Use this when there are completely new sets of functions and header
  229: files that should go into the library for the system this subdirectory
  230: of @file{sysdeps} implements.  For example,
  231: @file{sysdeps/unix/inet/Subdirs} contains @file{inet}; the @file{inet}
  232: directory contains various network-oriented operations which only make
  233: sense to put in the library on systems that support the Internet.@refill
  234: 
  235: @item configure
  236: 
  237: This file is a shell script fragment to be run at configuration time.
  238: The top-level @file{configure} script uses the shell @code{.} command to
  239: read the @file{configure} file in each system-dependent directory
  240: chosen, in order.  The @file{configure} files are often generated from
  241: @file{configure.in} files using Autoconf.
  242: 
  243: A system-dependent @file{configure} script will usually add things to
  244: the shell variables @samp{DEFS} and @samp{config_vars}; see the
  245: top-level @file{configure} script for details.  The script can check for
  246: @w{@samp{--with-@var{package}}} options that were passed to the
  247: top-level @file{configure}.  For an option
  248: @w{@samp{--with-@var{package}=@var{value}}} @file{configure} sets the
  249: shell variable @w{@samp{with_@var{package}}} (with any dashes in
  250: @var{package} converted to underscores) to @var{value}; if the option is
  251: just @w{@samp{--with-@var{package}}} (no argument), then it sets
  252: @w{@samp{with_@var{package}}} to @samp{yes}.
  253: 
  254: @item configure.in
  255: 
  256: This file is an Autoconf input fragment to be processed into the file
  257: @file{configure} in this subdirectory.  @xref{Introduction,,,
  258: autoconf.info, Autoconf: Generating Automatic Configuration Scripts},
  259: for a description of Autoconf.  You should write either @file{configure}
  260: or @file{configure.in}, but not both.  The first line of
  261: @file{configure.in} should invoke the @code{m4} macro
  262: @samp{GLIBC_PROVIDES}.  This macro does several @code{AC_PROVIDE} calls
  263: for Autoconf macros which are used by the top-level @file{configure}
  264: script; without this, those macros might be invoked again unnecessarily
  265: by Autoconf.
  266: @end table
  267: 
  268: That is the general system for how system-dependencies are isolated.
  269: @iftex
  270: The next section explains how to decide what directories in
  271: @file{sysdeps} to use.  @ref{Porting to Unix}, has some tips on porting
  272: the library to Unix variants.
  273: @end iftex
  274: 
  275: @menu
  276: * Hierarchy Conventions::       The layout of the @file{sysdeps} hierarchy.
  277: * Porting to Unix::             Porting the library to an average
  278:                                    Unix-like system.
  279: @end menu
  280: 
  281: @node Hierarchy Conventions
  282: @appendixsubsec Layout of the @file{sysdeps} Directory Hierarchy
  283: 
  284: A GNU configuration name has three parts: the CPU type, the
  285: manufacturer's name, and the operating system.  @file{configure} uses
  286: these to pick the list of system-dependent directories to look for.  If
  287: the @samp{--nfp} option is @emph{not} passed to @file{configure}, the
  288: directory @file{@var{machine}/fpu} is also used.  The operating system
  289: often has a @dfn{base operating system}; for example, if the operating
  290: system is @samp{Linux}, the base operating system is @samp{unix/sysv}.
  291: The algorithm used to pick the list of directories is simple:
  292: @file{configure} makes a list of the base operating system,
  293: manufacturer, CPU type, and operating system, in that order.  It then
  294: concatenates all these together with slashes in between, to produce a
  295: directory name; for example, the configuration @w{@samp{i686-linux-gnu}}
  296: results in @file{unix/sysv/linux/i386/i686}.  @file{configure} then
  297: tries removing each element of the list in turn, so
  298: @file{unix/sysv/linux} and @file{unix/sysv} are also tried, among others.
  299: Since the precise version number of the operating system is often not
  300: important, and it would be very inconvenient, for example, to have
  301: identical @file{irix6.2} and @file{irix6.3} directories,
  302: @file{configure} tries successively less specific operating system names
  303: by removing trailing suffixes starting with a period.
  304: 
  305: As an example, here is the complete list of directories that would be
  306: tried for the configuration @w{@samp{i686-linux-gnu}} (with the
  307: @file{crypt} and @file{linuxthreads} add-on):
  308: 
  309: @smallexample
  310: sysdeps/i386/elf
  311: crypt/sysdeps/unix
  312: linuxthreads/sysdeps/unix/sysv/linux
  313: linuxthreads/sysdeps/pthread
  314: linuxthreads/sysdeps/unix/sysv
  315: linuxthreads/sysdeps/unix
  316: linuxthreads/sysdeps/i386/i686
  317: linuxthreads/sysdeps/i386
  318: linuxthreads/sysdeps/pthread/no-cmpxchg
  319: sysdeps/unix/sysv/linux/i386
  320: sysdeps/unix/sysv/linux
  321: sysdeps/gnu
  322: sysdeps/unix/common
  323: sysdeps/unix/mman
  324: sysdeps/unix/inet
  325: sysdeps/unix/sysv/i386/i686
  326: sysdeps/unix/sysv/i386
  327: sysdeps/unix/sysv
  328: sysdeps/unix/i386
  329: sysdeps/unix
  330: sysdeps/posix
  331: sysdeps/i386/i686
  332: sysdeps/i386/i486
  333: sysdeps/libm-i387/i686
  334: sysdeps/i386/fpu
  335: sysdeps/libm-i387
  336: sysdeps/i386
  337: sysdeps/wordsize-32
  338: sysdeps/ieee754
  339: sysdeps/libm-ieee754
  340: sysdeps/generic
  341: @end smallexample
  342: 
  343: Different machine architectures are conventionally subdirectories at the
  344: top level of the @file{sysdeps} directory tree.  For example,
  345: @w{@file{sysdeps/sparc}} and @w{@file{sysdeps/m68k}}.  These contain
  346: files specific to those machine architectures, but not specific to any
  347: particular operating system.  There might be subdirectories for
  348: specializations of those architectures, such as
  349: @w{@file{sysdeps/m68k/68020}}. Code which is specific to the
  350: floating-point coprocessor used with a particular machine should go in
  351: @w{@file{sysdeps/@var{machine}/fpu}}.
  352: 
  353: There are a few directories at the top level of the @file{sysdeps}
  354: hierarchy that are not for particular machine architectures.
  355: 
  356: @table @file
  357: @item generic
  358: As described above (@pxref{Porting}), this is the subdirectory
  359: that every configuration implicitly uses after all others.
  360: 
  361: @item ieee754
  362: This directory is for code using the IEEE 754 floating-point format,
  363: where the C type @code{float} is IEEE 754 single-precision format, and
  364: @code{double} is IEEE 754 double-precision format.  Usually this
  365: directory is referred to in the @file{Implies} file in a machine
  366: architecture-specific directory, such as @file{m68k/Implies}.
  367: 
  368: @item libm-ieee754
  369: This directory contains an implementation of a mathematical library
  370: usable on platforms which use @w{IEEE 754} conformant floating-point
  371: arithmetic.
  372: 
  373: @item libm-i387
  374: This is a special case.  Ideally the code should be in
  375: @file{sysdeps/i386/fpu} but for various reasons it is kept aside.
  376: 
  377: @item posix
  378: This directory contains implementations of things in the library in
  379: terms of @sc{POSIX.1} functions.  This includes some of the @sc{POSIX.1}
  380: functions themselves.  Of course, @sc{POSIX.1} cannot be completely
  381: implemented in terms of itself, so a configuration using just
  382: @file{posix} cannot be complete.
  383: 
  384: @item unix
  385: This is the directory for Unix-like things.  @xref{Porting to Unix}.
  386: @file{unix} implies @file{posix}.  There are some special-purpose
  387: subdirectories of @file{unix}:
  388: 
  389: @table @file
  390: @item unix/common
  391: This directory is for things common to both BSD and System V release 4.
  392: Both @file{unix/bsd} and @file{unix/sysv/sysv4} imply @file{unix/common}.
  393: 
  394: @item unix/inet
  395: This directory is for @code{socket} and related functions on Unix systems.
  396: @file{unix/inet/Subdirs} enables the @file{inet} top-level subdirectory.
  397: @file{unix/common} implies @file{unix/inet}.
  398: @end table
  399: 
  400: @item mach
  401: This is the directory for things based on the Mach microkernel from CMU
  402: (including the GNU operating system).  Other basic operating systems
  403: (VMS, for example) would have their own directories at the top level of
  404: the @file{sysdeps} hierarchy, parallel to @file{unix} and @file{mach}.
  405: @end table
  406: 
  407: @node Porting to Unix
  408: @appendixsubsec Porting the GNU C Library to Unix Systems
  409: 
  410: Most Unix systems are fundamentally very similar.  There are variations
  411: between different machines, and variations in what facilities are
  412: provided by the kernel.  But the interface to the operating system
  413: facilities is, for the most part, pretty uniform and simple.
  414: 
  415: The code for Unix systems is in the directory @file{unix}, at the top
  416: level of the @file{sysdeps} hierarchy.  This directory contains
  417: subdirectories (and subdirectory trees) for various Unix variants.
  418: 
  419: The functions which are system calls in most Unix systems are
  420: implemented in assembly code, which is generated automatically from
  421: specifications in files named @file{syscalls.list}.  There are several
  422: such files, one in @file{sysdeps/unix} and others in its subdirectories.
  423: Some special system calls are implemented in files that are named with a
  424: suffix of @samp{.S}; for example, @file{_exit.S}.  Files ending in
  425: @samp{.S} are run through the C preprocessor before being fed to the
  426: assembler.
  427: 
  428: These files all use a set of macros that should be defined in
  429: @file{sysdep.h}.  The @file{sysdep.h} file in @file{sysdeps/unix}
  430: partially defines them; a @file{sysdep.h} file in another directory must
  431: finish defining them for the particular machine and operating system
  432: variant.  See @file{sysdeps/unix/sysdep.h} and the machine-specific
  433: @file{sysdep.h} implementations to see what these macros are and what
  434: they should do.@refill
  435: 
  436: The system-specific makefile for the @file{unix} directory
  437: (@file{sysdeps/unix/Makefile}) gives rules to generate several files
  438: from the Unix system you are building the library on (which is assumed
  439: to be the target system you are building the library @emph{for}).  All
  440: the generated files are put in the directory where the object files are
  441: kept; they should not affect the source tree itself.  The files
  442: generated are @file{ioctls.h}, @file{errnos.h}, @file{sys/param.h}, and
  443: @file{errlist.c} (for the @file{stdio} section of the library).
  444: 
  445: @ignore
  446: @c This section might be a good idea if it is finished,
  447: @c but there's no point including it as it stands. --rms
  448: @c @appendixsec Compatibility with Traditional C
  449: 
  450: @c ??? This section is really short now.  Want to keep it? --roland
  451: 
  452: @c It's not anymore true.  glibc 2.1 cannot be used with K&R compilers.
  453: @c --drepper
  454: 
  455: Although the GNU C library implements the @w{ISO C} library facilities, you
  456: @emph{can} use the GNU C library with traditional, ``pre-ISO'' C
  457: compilers.  However, you need to be careful because the content and
  458: organization of the GNU C library header files differs from that of
  459: traditional C implementations.  This means you may need to make changes
  460: to your program in order to get it to compile.
  461: @end ignore