<html lang="en">
<head>
<title>Porting - The GNU C Library</title>
<meta http-equiv="Content-Type" content="text/html">
<meta name="description" content="The GNU C Library">
<meta name="generator" content="makeinfo 4.13">
<link title="Top" rel="start" href="index.html#Top">
<link rel="up" href="Maintenance.html#Maintenance" title="Maintenance">
<link rel="prev" href="Source-Layout.html#Source-Layout" title="Source Layout">
<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
<!--
This file documents the GNU C library.

This is Edition 0.12, last updated 2007-10-27,
of `The GNU C Library Reference Manual', for version
2.8 (Sourcery G++ Lite 2011.03-41).

Copyright (C) 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2001, 2002,
2003, 2007, 2008, 2010 Free Software Foundation, Inc.

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with the
Invariant Sections being ``Free Software Needs Free Documentation''
and ``GNU Lesser General Public License'', the Front-Cover texts being
``A GNU Manual'', and with the Back-Cover Texts as in (a) below.  A
copy of the license is included in the section entitled "GNU Free
Documentation License".

(a) The FSF's Back-Cover Text is: ``You have the freedom to
copy and modify this GNU manual.  Buying copies from the FSF
supports it in developing GNU and promoting software freedom.''-->
<meta http-equiv="Content-Style-Type" content="text/css">
<style type="text/css"><!--
  pre.display { font-family:inherit }
  pre.format  { font-family:inherit }
  pre.smalldisplay { font-family:inherit; font-size:smaller }
  pre.smallformat  { font-family:inherit; font-size:smaller }
  pre.smallexample { font-size:smaller }
  pre.smalllisp    { font-size:smaller }
  span.sc    { font-variant:small-caps }
  span.roman { font-family:serif; font-weight:normal; } 
  span.sansserif { font-family:sans-serif; font-weight:normal; } 
--></style>
<link rel="stylesheet" type="text/css" href="../cs.css">
</head>
<body>
<div class="node">
<a name="Porting"></a>
<p>
Previous:&nbsp;<a rel="previous" accesskey="p" href="Source-Layout.html#Source-Layout">Source Layout</a>,
Up:&nbsp;<a rel="up" accesskey="u" href="Maintenance.html#Maintenance">Maintenance</a>
<hr>
</div>

<h3 class="appendixsec">D.2 Porting the GNU C Library</h3>

<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 <samp><span class="file">sysdeps</span></samp> under the top-level
library source directory.  This directory contains a hierarchy of
subdirectories (see <a href="Hierarchy-Conventions.html#Hierarchy-Conventions">Hierarchy Conventions</a>).

   <p>Each subdirectory of <samp><span class="file">sysdeps</span></samp> 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 <samp><span class="file">unix/bsd/vax</span></samp> is equivalent to specifying the
list <samp><span class="file">unix/bsd/vax unix/bsd unix</span></samp>.  A subdirectory can also specify
that it implies other subdirectories which are not directly above it in
the directory hierarchy.  If the file <samp><span class="file">Implies</span></samp> exists in a
subdirectory, it lists other subdirectories of <samp><span class="file">sysdeps</span></samp> which are
appended to the list, appearing after the subdirectory containing the
<samp><span class="file">Implies</span></samp> file.  Lines in an <samp><span class="file">Implies</span></samp> file that begin with a
&lsquo;<samp><span class="samp">#</span></samp>&rsquo; character are ignored as comments.  For example,
<samp><span class="file">unix/bsd/Implies</span></samp> contains:
<pre class="smallexample">     # BSD has Internet-related things.
     unix/inet
</pre>
   <p class="noindent">and <samp><span class="file">unix/Implies</span></samp> contains:
<pre class="smallexample">     posix
</pre>
   <p class="noindent">So the final list is <samp><span class="file">unix/bsd/vax unix/bsd unix/inet unix posix</span></samp>.

   <p><samp><span class="file">sysdeps</span></samp> has a &ldquo;special&rdquo; subdirectory called <samp><span class="file">generic</span></samp>.  It
is always implicitly appended to the list of subdirectories, so you
needn't put it in an <samp><span class="file">Implies</span></samp> file, and you should not create any
subdirectories under it intended to be new specific categories. 
<samp><span class="file">generic</span></samp> serves two purposes.  First, the makefiles do not bother
to look for a system-dependent version of a file that's not in
<samp><span class="file">generic</span></samp>.  This means that any system-dependent source file must
have an analogue in <samp><span class="file">generic</span></samp>, even if the routines defined by that
file are not implemented on other platforms.  Second, the <samp><span class="file">generic</span></samp>
version of a system-dependent file is used if the makefiles do not find
a version specific to the system you're compiling for.

   <p>If it is possible to implement the routines in a <samp><span class="file">generic</span></samp> 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
<dfn>stub</dfn> function is a function which cannot be implemented on a
particular machine or operating system.  Stub functions always return an
error, and set <code>errno</code> to <code>ENOSYS</code> (Function not implemented). 
See <a href="Error-Reporting.html#Error-Reporting">Error Reporting</a>.  If you define a stub function, you must place
the statement <code>stub_warning(</code><var>function</var><code>)</code>, where <var>function</var>
is the name of your function, after its definition; also, you must
include the file <code>&lt;stub-tag.h&gt;</code> into your file.  This causes the
function to be listed in the installed <code>&lt;gnu/stubs.h&gt;</code>, and
makes GNU ld warn when the function is used.

   <p>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
<samp><span class="file">generic</span></samp> directory), only in the system-dependent <samp><span class="file">Makefile</span></samp>
in the specific system's subdirectory.

   <p>If you come across a file that is in one of the main source directories
(<samp><span class="file">string</span></samp>, <samp><span class="file">stdio</span></samp>, etc.), and you want to write a machine- or
operating system-dependent version of it, move the file into
<samp><span class="file">sysdeps/generic</span></samp> 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
<samp><span class="file">sysdeps</span></samp>:

<!-- Blank lines after items make the table look better. -->
     <dl>
<dt><samp><span class="file">Makefile</span></samp><dd>
A makefile for this machine or operating system, or class of machine or
operating system.  This file is included by the library makefile
<samp><span class="file">Makerules</span></samp>, 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 &lsquo;<samp><span class="samp">subdir</span></samp>&rsquo; (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
&lsquo;<samp><span class="samp">sysdep-routines</span></samp>&rsquo;, to specify extra modules to be included in the
library.  You should use &lsquo;<samp><span class="samp">sysdep-routines</span></samp>&rsquo; rather than adding
modules to &lsquo;<samp><span class="samp">routines</span></samp>&rsquo; 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 &lsquo;<samp><span class="samp">sysdep-routines</span></samp>&rsquo;
rather than simply setting it:

     <pre class="smallexample">          sysdep-routines := $(sysdep-routines) foo bar
</pre>
     <br><dt><samp><span class="file">Subdirs</span></samp><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 <samp><span class="file">stdio</span></samp> and
<samp><span class="file">math</span></samp>.

     <p>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 <samp><span class="file">sysdeps</span></samp> implements.  For example,
<samp><span class="file">sysdeps/unix/inet/Subdirs</span></samp> contains <samp><span class="file">inet</span></samp>; the <samp><span class="file">inet</span></samp>
directory contains various network-oriented operations which only make
sense to put in the library on systems that support the Internet.

     <br><dt><samp><span class="file">configure</span></samp><dd>
This file is a shell script fragment to be run at configuration time. 
The top-level <samp><span class="file">configure</span></samp> script uses the shell <code>.</code> command to
read the <samp><span class="file">configure</span></samp> file in each system-dependent directory
chosen, in order.  The <samp><span class="file">configure</span></samp> files are often generated from
<samp><span class="file">configure.in</span></samp> files using Autoconf.

     <p>A system-dependent <samp><span class="file">configure</span></samp> script will usually add things to
the shell variables &lsquo;<samp><span class="samp">DEFS</span></samp>&rsquo; and &lsquo;<samp><span class="samp">config_vars</span></samp>&rsquo;; see the
top-level <samp><span class="file">configure</span></samp> script for details.  The script can check for
&lsquo;<samp><span class="samp">--with-</span><var>package</var></samp>&rsquo;<!-- /@w --> options that were passed to the
top-level <samp><span class="file">configure</span></samp>.  For an option
&lsquo;<samp><span class="samp">--with-</span><var>package</var><span class="samp">=</span><var>value</var></samp>&rsquo;<!-- /@w --> <samp><span class="file">configure</span></samp> sets the
shell variable &lsquo;<samp><span class="samp">with_</span><var>package</var></samp>&rsquo;<!-- /@w --> (with any dashes in
<var>package</var> converted to underscores) to <var>value</var>; if the option is
just &lsquo;<samp><span class="samp">--with-</span><var>package</var></samp>&rsquo;<!-- /@w --> (no argument), then it sets
&lsquo;<samp><span class="samp">with_</span><var>package</var></samp>&rsquo;<!-- /@w --> to &lsquo;<samp><span class="samp">yes</span></samp>&rsquo;.

     <br><dt><samp><span class="file">configure.in</span></samp><dd>
This file is an Autoconf input fragment to be processed into the file
<samp><span class="file">configure</span></samp> in this subdirectory.  See <a href="../autoconf/Introduction.html#Introduction">Introduction</a>,
for a description of Autoconf.  You should write either <samp><span class="file">configure</span></samp>
or <samp><span class="file">configure.in</span></samp>, but not both.  The first line of
<samp><span class="file">configure.in</span></samp> should invoke the <code>m4</code> macro
&lsquo;<samp><span class="samp">GLIBC_PROVIDES</span></samp>&rsquo;.  This macro does several <code>AC_PROVIDE</code> calls
for Autoconf macros which are used by the top-level <samp><span class="file">configure</span></samp>
script; without this, those macros might be invoked again unnecessarily
by Autoconf. 
</dl>

   <p>That is the general system for how system-dependencies are isolated.

<ul class="menu">
<li><a accesskey="1" href="Hierarchy-Conventions.html#Hierarchy-Conventions">Hierarchy Conventions</a>:        The layout of the <samp><span class="file">sysdeps</span></samp> hierarchy. 
<li><a accesskey="2" href="Porting-to-Unix.html#Porting-to-Unix">Porting to Unix</a>:              Porting the library to an average
                                   Unix-like system. 
</ul>

   </body></html>