| <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: <a rel="previous" accesskey="p" href="Source-Layout.html#Source-Layout">Source Layout</a>, |
| Up: <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 |
| ‘<samp><span class="samp">#</span></samp>’ 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 “special” 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><stub-tag.h></code> into your file. This causes the |
| function to be listed in the installed <code><gnu/stubs.h></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 ‘<samp><span class="samp">subdir</span></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><span class="samp">sysdep-routines</span></samp>’, to specify extra modules to be included in the |
| library. You should use ‘<samp><span class="samp">sysdep-routines</span></samp>’ rather than adding |
| modules to ‘<samp><span class="samp">routines</span></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><span class="samp">sysdep-routines</span></samp>’ |
| 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 ‘<samp><span class="samp">DEFS</span></samp>’ and ‘<samp><span class="samp">config_vars</span></samp>’; see the |
| top-level <samp><span class="file">configure</span></samp> script for details. The script can check for |
| ‘<samp><span class="samp">--with-</span><var>package</var></samp>’<!-- /@w --> options that were passed to the |
| top-level <samp><span class="file">configure</span></samp>. For an option |
| ‘<samp><span class="samp">--with-</span><var>package</var><span class="samp">=</span><var>value</var></samp>’<!-- /@w --> <samp><span class="file">configure</span></samp> sets the |
| shell variable ‘<samp><span class="samp">with_</span><var>package</var></samp>’<!-- /@w --> (with any dashes in |
| <var>package</var> converted to underscores) to <var>value</var>; if the option is |
| just ‘<samp><span class="samp">--with-</span><var>package</var></samp>’<!-- /@w --> (no argument), then it sets |
| ‘<samp><span class="samp">with_</span><var>package</var></samp>’<!-- /@w --> to ‘<samp><span class="samp">yes</span></samp>’. |
| |
| <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 |
| ‘<samp><span class="samp">GLIBC_PROVIDES</span></samp>’. 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> |
| |
