| <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> |
| <html> |
| <!-- The GNU coding standards, last updated April 12, 2010. |
| |
| Copyright (C) 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, |
| 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 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 no |
| Invariant Sections, with no Front-Cover Texts, and with no Back-Cover |
| Texts. A copy of the license is included in the section entitled |
| "GNU Free Documentation License". --> |
| <!-- Created by GNU Texinfo 5.2, http://www.gnu.org/software/texinfo/ --> |
| <head> |
| <title>GNU Coding Standards</title> |
| |
| <meta name="description" content="GNU Coding Standards"> |
| <meta name="keywords" content="GNU Coding Standards"> |
| <meta name="resource-type" content="document"> |
| <meta name="distribution" content="global"> |
| <meta name="Generator" content="makeinfo"> |
| <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> |
| <link href="#Top" rel="start" title="Top"> |
| <link href="#Index" rel="index" title="Index"> |
| <link href="#SEC_Contents" rel="contents" title="Table of Contents"> |
| <link href="dir.html#Top" rel="up" title="(dir)"> |
| <style type="text/css"> |
| <!-- |
| a.summary-letter {text-decoration: none} |
| blockquote.smallquotation {font-size: smaller} |
| div.display {margin-left: 3.2em} |
| div.example {margin-left: 3.2em} |
| div.indentedblock {margin-left: 3.2em} |
| div.lisp {margin-left: 3.2em} |
| div.smalldisplay {margin-left: 3.2em} |
| div.smallexample {margin-left: 3.2em} |
| div.smallindentedblock {margin-left: 3.2em; font-size: smaller} |
| div.smalllisp {margin-left: 3.2em} |
| kbd {font-style:oblique} |
| pre.display {font-family: inherit} |
| pre.format {font-family: inherit} |
| pre.menu-comment {font-family: serif} |
| pre.menu-preformatted {font-family: serif} |
| pre.smalldisplay {font-family: inherit; font-size: smaller} |
| pre.smallexample {font-size: smaller} |
| pre.smallformat {font-family: inherit; font-size: smaller} |
| pre.smalllisp {font-size: smaller} |
| span.nocodebreak {white-space:nowrap} |
| span.nolinebreak {white-space:nowrap} |
| span.roman {font-family:serif; font-weight:normal} |
| span.sansserif {font-family:sans-serif; font-weight:normal} |
| ul.no-bullet {list-style: none} |
| --> |
| </style> |
| |
| |
| </head> |
| |
| <body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> |
| <h1 class="settitle" align="center">GNU Coding Standards</h1> |
| |
| |
| |
| |
| |
| |
| |
| <a name="SEC_Contents"></a> |
| <h2 class="contents-heading">Table of Contents</h2> |
| |
| <div class="contents"> |
| |
| <ul class="no-bullet"> |
| <li><a name="toc-About-the-GNU-Coding-Standards" href="#Preface">1 About the GNU Coding Standards</a></li> |
| <li><a name="toc-Keeping-Free-Software-Free" href="#Legal-Issues">2 Keeping Free Software Free</a> |
| <ul class="no-bullet"> |
| <li><a name="toc-Referring-to-Proprietary-Programs" href="#Reading-Non_002dFree-Code">2.1 Referring to Proprietary Programs</a></li> |
| <li><a name="toc-Accepting-Contributions" href="#Contributions">2.2 Accepting Contributions</a></li> |
| <li><a name="toc-Trademarks-1" href="#Trademarks">2.3 Trademarks</a></li> |
| </ul></li> |
| <li><a name="toc-General-Program-Design" href="#Design-Advice">3 General Program Design</a> |
| <ul class="no-bullet"> |
| <li><a name="toc-Which-Languages-to-Use" href="#Source-Language">3.1 Which Languages to Use</a></li> |
| <li><a name="toc-Compatibility-with-Other-Implementations" href="#Compatibility">3.2 Compatibility with Other Implementations</a></li> |
| <li><a name="toc-Using-Non_002dstandard-Features" href="#Using-Extensions">3.3 Using Non-standard Features</a></li> |
| <li><a name="toc-Standard-C-and-Pre_002dStandard-C" href="#Standard-C">3.4 Standard C and Pre-Standard C</a></li> |
| <li><a name="toc-Conditional-Compilation-1" href="#Conditional-Compilation">3.5 Conditional Compilation</a></li> |
| </ul></li> |
| <li><a name="toc-Program-Behavior-for-All-Programs" href="#Program-Behavior">4 Program Behavior for All Programs</a> |
| <ul class="no-bullet"> |
| <li><a name="toc-Non_002dGNU-Standards-1" href="#Non_002dGNU-Standards">4.1 Non-GNU Standards</a></li> |
| <li><a name="toc-Writing-Robust-Programs" href="#Semantics">4.2 Writing Robust Programs</a></li> |
| <li><a name="toc-Library-Behavior" href="#Libraries">4.3 Library Behavior</a></li> |
| <li><a name="toc-Formatting-Error-Messages" href="#Errors">4.4 Formatting Error Messages</a></li> |
| <li><a name="toc-Standards-for-Interfaces-Generally" href="#User-Interfaces">4.5 Standards for Interfaces Generally</a></li> |
| <li><a name="toc-Standards-for-Graphical-Interfaces" href="#Graphical-Interfaces">4.6 Standards for Graphical Interfaces</a></li> |
| <li><a name="toc-Standards-for-Command-Line-Interfaces" href="#Command_002dLine-Interfaces">4.7 Standards for Command Line Interfaces</a> |
| <ul class="no-bullet"> |
| <li><a name="toc-_002d_002dversion-1" href="#g_t_002d_002dversion">4.7.1 <samp>--version</samp></a></li> |
| <li><a name="toc-_002d_002dhelp-1" href="#g_t_002d_002dhelp">4.7.2 <samp>--help</samp></a></li> |
| </ul></li> |
| <li><a name="toc-Table-of-Long-Options" href="#Option-Table">4.8 Table of Long Options</a></li> |
| <li><a name="toc-OID-Allocations-1" href="#OID-Allocations">4.9 OID Allocations</a></li> |
| <li><a name="toc-Memory-Usage-1" href="#Memory-Usage">4.10 Memory Usage</a></li> |
| <li><a name="toc-File-Usage-1" href="#File-Usage">4.11 File Usage</a></li> |
| </ul></li> |
| <li><a name="toc-Making-The-Best-Use-of-C" href="#Writing-C">5 Making The Best Use of C</a> |
| <ul class="no-bullet"> |
| <li><a name="toc-Formatting-Your-Source-Code" href="#Formatting">5.1 Formatting Your Source Code</a></li> |
| <li><a name="toc-Commenting-Your-Work" href="#Comments">5.2 Commenting Your Work</a></li> |
| <li><a name="toc-Clean-Use-of-C-Constructs" href="#Syntactic-Conventions">5.3 Clean Use of C Constructs</a></li> |
| <li><a name="toc-Naming-Variables_002c-Functions_002c-and-Files" href="#Names">5.4 Naming Variables, Functions, and Files</a></li> |
| <li><a name="toc-Portability-between-System-Types" href="#System-Portability">5.5 Portability between System Types</a></li> |
| <li><a name="toc-Portability-between-CPUs" href="#CPU-Portability">5.6 Portability between <small>CPU</small>s</a></li> |
| <li><a name="toc-Calling-System-Functions" href="#System-Functions">5.7 Calling System Functions</a></li> |
| <li><a name="toc-Internationalization-1" href="#Internationalization">5.8 Internationalization</a></li> |
| <li><a name="toc-Character-Set-1" href="#Character-Set">5.9 Character Set</a></li> |
| <li><a name="toc-Quote-Characters-1" href="#Quote-Characters">5.10 Quote Characters</a></li> |
| <li><a name="toc-Mmap-1" href="#Mmap">5.11 Mmap</a></li> |
| </ul></li> |
| <li><a name="toc-Documenting-Programs" href="#Documentation">6 Documenting Programs</a> |
| <ul class="no-bullet"> |
| <li><a name="toc-GNU-Manuals-1" href="#GNU-Manuals">6.1 GNU Manuals</a></li> |
| <li><a name="toc-Doc-Strings-and-Manuals-1" href="#Doc-Strings-and-Manuals">6.2 Doc Strings and Manuals</a></li> |
| <li><a name="toc-Manual-Structure-Details-1" href="#Manual-Structure-Details">6.3 Manual Structure Details</a></li> |
| <li><a name="toc-License-for-Manuals-1" href="#License-for-Manuals">6.4 License for Manuals</a></li> |
| <li><a name="toc-Manual-Credits-1" href="#Manual-Credits">6.5 Manual Credits</a></li> |
| <li><a name="toc-Printed-Manuals-1" href="#Printed-Manuals">6.6 Printed Manuals</a></li> |
| <li><a name="toc-The-NEWS-File" href="#NEWS-File">6.7 The NEWS File</a></li> |
| <li><a name="toc-Change-Logs-1" href="#Change-Logs">6.8 Change Logs</a> |
| <ul class="no-bullet"> |
| <li><a name="toc-Change-Log-Concepts-1" href="#Change-Log-Concepts">6.8.1 Change Log Concepts</a></li> |
| <li><a name="toc-Style-of-Change-Logs-1" href="#Style-of-Change-Logs">6.8.2 Style of Change Logs</a></li> |
| <li><a name="toc-Simple-Changes-1" href="#Simple-Changes">6.8.3 Simple Changes</a></li> |
| <li><a name="toc-Conditional-Changes-1" href="#Conditional-Changes">6.8.4 Conditional Changes</a></li> |
| <li><a name="toc-Indicating-the-Part-Changed-1" href="#Indicating-the-Part-Changed">6.8.5 Indicating the Part Changed</a></li> |
| </ul></li> |
| <li><a name="toc-Man-Pages-1" href="#Man-Pages">6.9 Man Pages</a></li> |
| <li><a name="toc-Reading-other-Manuals-1" href="#Reading-other-Manuals">6.10 Reading other Manuals</a></li> |
| </ul></li> |
| <li><a name="toc-The-Release-Process" href="#Managing-Releases">7 The Release Process</a> |
| <ul class="no-bullet"> |
| <li><a name="toc-How-Configuration-Should-Work" href="#Configuration">7.1 How Configuration Should Work</a></li> |
| <li><a name="toc-Makefile-Conventions-1" href="#Makefile-Conventions">7.2 Makefile Conventions</a> |
| <ul class="no-bullet"> |
| <li><a name="toc-General-Conventions-for-Makefiles" href="#Makefile-Basics">7.2.1 General Conventions for Makefiles</a></li> |
| <li><a name="toc-Utilities-in-Makefiles-1" href="#Utilities-in-Makefiles">7.2.2 Utilities in Makefiles</a></li> |
| <li><a name="toc-Variables-for-Specifying-Commands" href="#Command-Variables">7.2.3 Variables for Specifying Commands</a></li> |
| <li><a name="toc-DESTDIR_003a-support-for-staged-installs" href="#DESTDIR">7.2.4 <code>DESTDIR</code>: support for staged installs</a></li> |
| <li><a name="toc-Variables-for-Installation-Directories" href="#Directory-Variables">7.2.5 Variables for Installation Directories</a></li> |
| <li><a name="toc-Standard-Targets-for-Users" href="#Standard-Targets">7.2.6 Standard Targets for Users</a></li> |
| <li><a name="toc-Install-Command-Categories-1" href="#Install-Command-Categories">7.2.7 Install Command Categories</a></li> |
| </ul></li> |
| <li><a name="toc-Making-Releases" href="#Releases">7.3 Making Releases</a></li> |
| </ul></li> |
| <li><a name="toc-References-to-Non_002dFree-Software-and-Documentation" href="#References">8 References to Non-Free Software and Documentation</a></li> |
| <li><a name="toc-GNU-Free-Documentation-License-1" href="#GNU-Free-Documentation-License">Appendix A GNU Free Documentation License</a></li> |
| <li><a name="toc-Index-1" href="#Index">Index</a></li> |
| </ul> |
| </div> |
| |
| |
| <a name="Top"></a> |
| <div class="header"> |
| <p> |
| Next: <a href="#Preface" accesskey="n" rel="next">Preface</a>, Previous: <a href="dir.html#Top" accesskey="p" rel="prev">(dir)</a>, Up: <a href="dir.html#Top" accesskey="u" rel="up">(dir)</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p> |
| </div> |
| <a name="Version"></a> |
| <h1 class="top">Version</h1> |
| |
| <p>The GNU coding standards, last updated April 12, 2010. |
| </p> |
| <p>Copyright © 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, |
| 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 Free Software |
| Foundation, Inc. |
| </p> |
| <p>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 no |
| Invariant Sections, with no Front-Cover Texts, and with no Back-Cover |
| Texts. A copy of the license is included in the section entitled |
| “GNU Free Documentation License”. |
| </p> |
| |
| <table class="menu" border="0" cellspacing="0"> |
| <tr><td align="left" valign="top">• <a href="#Preface" accesskey="1">Preface</a>:</td><td> </td><td align="left" valign="top">About the GNU Coding Standards. |
| </td></tr> |
| <tr><td align="left" valign="top">• <a href="#Legal-Issues" accesskey="2">Legal Issues</a>:</td><td> </td><td align="left" valign="top">Keeping free software free. |
| </td></tr> |
| <tr><td align="left" valign="top">• <a href="#Design-Advice" accesskey="3">Design Advice</a>:</td><td> </td><td align="left" valign="top">General program design. |
| </td></tr> |
| <tr><td align="left" valign="top">• <a href="#Program-Behavior" accesskey="4">Program Behavior</a>:</td><td> </td><td align="left" valign="top">Program behavior for all programs |
| </td></tr> |
| <tr><td align="left" valign="top">• <a href="#Writing-C" accesskey="5">Writing C</a>:</td><td> </td><td align="left" valign="top">Making the best use of C. |
| </td></tr> |
| <tr><td align="left" valign="top">• <a href="#Documentation" accesskey="6">Documentation</a>:</td><td> </td><td align="left" valign="top">Documenting programs. |
| </td></tr> |
| <tr><td align="left" valign="top">• <a href="#Managing-Releases" accesskey="7">Managing Releases</a>:</td><td> </td><td align="left" valign="top">The release process. |
| </td></tr> |
| <tr><td align="left" valign="top">• <a href="#References" accesskey="8">References</a>:</td><td> </td><td align="left" valign="top">Mentioning non-free software or documentation. |
| </td></tr> |
| <tr><td align="left" valign="top">• <a href="#GNU-Free-Documentation-License" accesskey="9">GNU Free Documentation License</a>:</td><td> </td><td align="left" valign="top">Copying and sharing this manual. |
| </td></tr> |
| <tr><td align="left" valign="top">• <a href="#Index">Index</a>:</td><td> </td><td align="left" valign="top"> |
| </td></tr> |
| <tr><th colspan="3" align="left" valign="top"><pre class="menu-comment"> |
| </pre></th></tr></table> |
| |
| <hr> |
| <a name="Preface"></a> |
| <div class="header"> |
| <p> |
| Next: <a href="#Legal-Issues" accesskey="n" rel="next">Legal Issues</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p> |
| </div> |
| <a name="About-the-GNU-Coding-Standards"></a> |
| <h2 class="chapter">1 About the GNU Coding Standards</h2> |
| |
| <p>The GNU Coding Standards were written by Richard Stallman and other GNU |
| Project volunteers. Their purpose is to make the GNU system clean, |
| consistent, and easy to install. This document can also be read as a |
| guide to writing portable, robust and reliable programs. It focuses on |
| programs written in C, but many of the rules and principles are useful |
| even if you write in another programming language. The rules often |
| state reasons for writing in a certain way. |
| </p> |
| <a name="index-where-to-obtain-standards_002etexi"></a> |
| <a name="index-downloading-this-manual"></a> |
| <p>If you did not obtain this file directly from the GNU project and |
| recently, please check for a newer version. You can get the GNU |
| Coding Standards from the GNU web server in many |
| different formats, including the Texinfo source, PDF, HTML, DVI, plain |
| text, and more, at: <a href="http://www.gnu.org/prep/standards/">http://www.gnu.org/prep/standards/</a>. |
| </p> |
| <p>If you are maintaining an official GNU package, in addition to this |
| document, please read and follow the GNU maintainer information |
| (see <a href="http://www.gnu.org/prep/maintain/maintain.html#Top">Contents</a> in <cite>Information for Maintainers of GNU |
| Software</cite>). |
| </p> |
| <a name="index-gnustandards_002dcommit_0040gnu_002eorg-mailing-list"></a> |
| <p>If you want to receive diffs for every change to these GNU documents, |
| join the mailing list <code>gnustandards-commit@gnu.org</code>, via the web |
| interface at |
| <a href="http://lists.gnu.org/mailman/listinfo/gnustandards-commit">http://lists.gnu.org/mailman/listinfo/gnustandards-commit</a>. |
| Archives are also available there. |
| </p> |
| <a name="index-bug_002dstandards_0040gnu_002eorg-email-address"></a> |
| <a name="index-Savannah-repository-for-gnustandards"></a> |
| <a name="index-gnustandards-project-repository"></a> |
| <p>Please send corrections or suggestions for this document to |
| <a href="mailto:bug-standards@gnu.org">bug-standards@gnu.org</a>. If you make a suggestion, please |
| include a suggested new wording for it, to help us consider the |
| suggestion efficiently. We prefer a context diff to the Texinfo |
| source, but if that’s difficult for you, you can make a context diff |
| for some other version of this document, or propose it in any way that |
| makes it clear. The source repository for this document can be found |
| at <a href="http://savannah.gnu.org/projects/gnustandards">http://savannah.gnu.org/projects/gnustandards</a>. |
| </p> |
| <p>These standards cover the minimum of what is important when writing a |
| GNU package. Likely, the need for additional standards will come up. |
| Sometimes, you might suggest that such standards be added to this |
| document. If you think your standards would be generally useful, please |
| do suggest them. |
| </p> |
| <p>You should also set standards for your package on many questions not |
| addressed or not firmly specified here. The most important point is to |
| be self-consistent—try to stick to the conventions you pick, and try |
| to document them as much as possible. That way, your program will be |
| more maintainable by others. |
| </p> |
| <p>The GNU Hello program serves as an example of how to follow the GNU |
| coding standards for a trivial program. |
| <a href="http://www.gnu.org/software/hello/hello.html">http://www.gnu.org/software/hello/hello.html</a>. |
| </p> |
| <p>This release of the GNU Coding Standards was last updated |
| April 12, 2010. |
| </p> |
| |
| <hr> |
| <a name="Legal-Issues"></a> |
| <div class="header"> |
| <p> |
| Next: <a href="#Design-Advice" accesskey="n" rel="next">Design Advice</a>, Previous: <a href="#Preface" accesskey="p" rel="prev">Preface</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p> |
| </div> |
| <a name="Keeping-Free-Software-Free"></a> |
| <h2 class="chapter">2 Keeping Free Software Free</h2> |
| <a name="index-legal-aspects"></a> |
| |
| <p>This chapter discusses how you can make sure that GNU software |
| avoids legal difficulties, and other related issues. |
| </p> |
| <table class="menu" border="0" cellspacing="0"> |
| <tr><td align="left" valign="top">• <a href="#Reading-Non_002dFree-Code" accesskey="1">Reading Non-Free Code</a>:</td><td> </td><td align="left" valign="top">Referring to proprietary programs. |
| </td></tr> |
| <tr><td align="left" valign="top">• <a href="#Contributions" accesskey="2">Contributions</a>:</td><td> </td><td align="left" valign="top">Accepting contributions. |
| </td></tr> |
| <tr><td align="left" valign="top">• <a href="#Trademarks" accesskey="3">Trademarks</a>:</td><td> </td><td align="left" valign="top">How we deal with trademark issues. |
| </td></tr> |
| </table> |
| |
| <hr> |
| <a name="Reading-Non_002dFree-Code"></a> |
| <div class="header"> |
| <p> |
| Next: <a href="#Contributions" accesskey="n" rel="next">Contributions</a>, Up: <a href="#Legal-Issues" accesskey="u" rel="up">Legal Issues</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p> |
| </div> |
| <a name="Referring-to-Proprietary-Programs"></a> |
| <h3 class="section">2.1 Referring to Proprietary Programs</h3> |
| <a name="index-proprietary-programs"></a> |
| <a name="index-avoiding-proprietary-code"></a> |
| |
| <p>Don’t in any circumstances refer to Unix source code for or during |
| your work on GNU! (Or to any other proprietary programs.) |
| </p> |
| <p>If you have a vague recollection of the internals of a Unix program, |
| this does not absolutely mean you can’t write an imitation of it, but |
| do try to organize the imitation internally along different lines, |
| because this is likely to make the details of the Unix version |
| irrelevant and dissimilar to your results. |
| </p> |
| <p>For example, Unix utilities were generally optimized to minimize |
| memory use; if you go for speed instead, your program will be very |
| different. You could keep the entire input file in memory and scan it |
| there instead of using stdio. Use a smarter algorithm discovered more |
| recently than the Unix program. Eliminate use of temporary files. Do |
| it in one pass instead of two (we did this in the assembler). |
| </p> |
| <p>Or, on the contrary, emphasize simplicity instead of speed. For some |
| applications, the speed of today’s computers makes simpler algorithms |
| adequate. |
| </p> |
| <p>Or go for generality. For example, Unix programs often have static |
| tables or fixed-size strings, which make for arbitrary limits; use |
| dynamic allocation instead. Make sure your program handles NULs and |
| other funny characters in the input files. Add a programming language |
| for extensibility and write part of the program in that language. |
| </p> |
| <p>Or turn some parts of the program into independently usable libraries. |
| Or use a simple garbage collector instead of tracking precisely when |
| to free memory, or use a new GNU facility such as obstacks. |
| </p> |
| <hr> |
| <a name="Contributions"></a> |
| <div class="header"> |
| <p> |
| Next: <a href="#Trademarks" accesskey="n" rel="next">Trademarks</a>, Previous: <a href="#Reading-Non_002dFree-Code" accesskey="p" rel="prev">Reading Non-Free Code</a>, Up: <a href="#Legal-Issues" accesskey="u" rel="up">Legal Issues</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p> |
| </div> |
| <a name="Accepting-Contributions"></a> |
| <h3 class="section">2.2 Accepting Contributions</h3> |
| <a name="index-legal-papers"></a> |
| <a name="index-accepting-contributions"></a> |
| |
| <p>If the program you are working on is copyrighted by the Free Software |
| Foundation, then when someone else sends you a piece of code to add to |
| the program, we need legal papers to use it—just as we asked you to |
| sign papers initially. <em>Each</em> person who makes a nontrivial |
| contribution to a program must sign some sort of legal papers in order |
| for us to have clear title to the program; the main author alone is not |
| enough. |
| </p> |
| <p>So, before adding in any contributions from other people, please tell |
| us, so we can arrange to get the papers. Then wait until we tell you |
| that we have received the signed papers, before you actually use the |
| contribution. |
| </p> |
| <p>This applies both before you release the program and afterward. If |
| you receive diffs to fix a bug, and they make significant changes, we |
| need legal papers for that change. |
| </p> |
| <p>This also applies to comments and documentation files. For copyright |
| law, comments and code are just text. Copyright applies to all kinds of |
| text, so we need legal papers for all kinds. |
| </p> |
| <p>We know it is frustrating to ask for legal papers; it’s frustrating for |
| us as well. But if you don’t wait, you are going out on a limb—for |
| example, what if the contributor’s employer won’t sign a disclaimer? |
| You might have to take that code out again! |
| </p> |
| <p>You don’t need papers for changes of a few lines here or there, since |
| they are not significant for copyright purposes. Also, you don’t need |
| papers if all you get from the suggestion is some ideas, not actual code |
| which you use. For example, if someone sent you one implementation, but |
| you write a different implementation of the same idea, you don’t need to |
| get papers. |
| </p> |
| <p>The very worst thing is if you forget to tell us about the other |
| contributor. We could be very embarrassed in court some day as a |
| result. |
| </p> |
| <p>We have more detailed advice for maintainers of programs; if you have |
| reached the stage of actually maintaining a program for GNU (whether |
| released or not), please ask us for a copy. It is also available |
| online for your perusal: <a href="http://www.gnu.org/prep/maintain/">http://www.gnu.org/prep/maintain/</a>. |
| </p> |
| <hr> |
| <a name="Trademarks"></a> |
| <div class="header"> |
| <p> |
| Previous: <a href="#Contributions" accesskey="p" rel="prev">Contributions</a>, Up: <a href="#Legal-Issues" accesskey="u" rel="up">Legal Issues</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p> |
| </div> |
| <a name="Trademarks-1"></a> |
| <h3 class="section">2.3 Trademarks</h3> |
| <a name="index-trademarks"></a> |
| |
| <p>Please do not include any trademark acknowledgements in GNU software |
| packages or documentation. |
| </p> |
| <p>Trademark acknowledgements are the statements that such-and-such is a |
| trademark of so-and-so. The GNU Project has no objection to the basic |
| idea of trademarks, but these acknowledgements feel like kowtowing, |
| and there is no legal requirement for them, so we don’t use them. |
| </p> |
| <p>What is legally required, as regards other people’s trademarks, is to |
| avoid using them in ways which a reader might reasonably understand as |
| naming or labeling our own programs or activities. For example, since |
| “Objective C” is (or at least was) a trademark, we made sure to say |
| that we provide a “compiler for the Objective C language” rather |
| than an “Objective C compiler”. The latter would have been meant as |
| a shorter way of saying the former, but it does not explicitly state |
| the relationship, so it could be misinterpreted as using “Objective |
| C” as a label for the compiler rather than for the language. |
| </p> |
| <p>Please don’t use “win” as an abbreviation for Microsoft Windows in |
| GNU software or documentation. In hacker terminology, calling |
| something a “win” is a form of praise. If you wish to praise |
| Microsoft Windows when speaking on your own, by all means do so, but |
| not in GNU software. Usually we write the name “Windows” in full, |
| but when brevity is very important (as in file names and sometimes |
| symbol names), we abbreviate it to “w”. For instance, the files and |
| functions in Emacs that deal with Windows start with ‘<samp>w32</samp>’. |
| </p> |
| <hr> |
| <a name="Design-Advice"></a> |
| <div class="header"> |
| <p> |
| Next: <a href="#Program-Behavior" accesskey="n" rel="next">Program Behavior</a>, Previous: <a href="#Legal-Issues" accesskey="p" rel="prev">Legal Issues</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p> |
| </div> |
| <a name="General-Program-Design"></a> |
| <h2 class="chapter">3 General Program Design</h2> |
| <a name="index-program-design"></a> |
| |
| <p>This chapter discusses some of the issues you should take into |
| account when designing your program. |
| </p> |
| |
| |
| <table class="menu" border="0" cellspacing="0"> |
| <tr><td align="left" valign="top">• <a href="#Source-Language" accesskey="1">Source Language</a>:</td><td> </td><td align="left" valign="top">Which languages to use. |
| </td></tr> |
| <tr><td align="left" valign="top">• <a href="#Compatibility" accesskey="2">Compatibility</a>:</td><td> </td><td align="left" valign="top">Compatibility with other implementations. |
| </td></tr> |
| <tr><td align="left" valign="top">• <a href="#Using-Extensions" accesskey="3">Using Extensions</a>:</td><td> </td><td align="left" valign="top">Using non-standard features. |
| </td></tr> |
| <tr><td align="left" valign="top">• <a href="#Standard-C" accesskey="4">Standard C</a>:</td><td> </td><td align="left" valign="top">Using standard C features. |
| </td></tr> |
| <tr><td align="left" valign="top">• <a href="#Conditional-Compilation" accesskey="5">Conditional Compilation</a>:</td><td> </td><td align="left" valign="top">Compiling code only if a conditional is true. |
| </td></tr> |
| </table> |
| |
| <hr> |
| <a name="Source-Language"></a> |
| <div class="header"> |
| <p> |
| Next: <a href="#Compatibility" accesskey="n" rel="next">Compatibility</a>, Up: <a href="#Design-Advice" accesskey="u" rel="up">Design Advice</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p> |
| </div> |
| <a name="Which-Languages-to-Use"></a> |
| <h3 class="section">3.1 Which Languages to Use</h3> |
| <a name="index-programming-languages"></a> |
| |
| <p>When you want to use a language that gets compiled and runs at high |
| speed, the best language to use is C. Using another language is like |
| using a non-standard feature: it will cause trouble for users. Even if |
| GCC supports the other language, users may find it inconvenient to have |
| to install the compiler for that other language in order to build your |
| program. For example, if you write your program in C++, people will |
| have to install the GNU C++ compiler in order to compile your program. |
| </p> |
| <p>C has one other advantage over C++ and other compiled languages: more |
| people know C, so more people will find it easy to read and modify the |
| program if it is written in C. |
| </p> |
| <p>So in general it is much better to use C, rather than the |
| comparable alternatives. |
| </p> |
| <p>But there are two exceptions to that conclusion: |
| </p> |
| <ul> |
| <li> It is no problem to use another language to write a tool specifically |
| intended for use with that language. That is because the only people |
| who want to build the tool will be those who have installed the other |
| language anyway. |
| |
| </li><li> If an application is of interest only to a narrow part of the community, |
| then the question of which language it is written in has less effect on |
| other people, so you may as well please yourself. |
| </li></ul> |
| |
| <p>Many programs are designed to be extensible: they include an interpreter |
| for a language that is higher level than C. Often much of the program |
| is written in that language, too. The Emacs editor pioneered this |
| technique. |
| </p> |
| <a name="index-Guile"></a> |
| <a name="index-GNOME-and-Guile"></a> |
| <p>The standard extensibility interpreter for GNU software is Guile |
| (<a href="http://www.gnu.org/software/guile/">http://www.gnu.org/software/guile/</a>), which implements the |
| language Scheme (an especially clean and simple dialect of Lisp). |
| Guile also includes bindings for GTK+/GNOME, making it practical to |
| write modern GUI functionality within Guile. We don’t reject programs |
| written in other “scripting languages” such as Perl and Python, but |
| using Guile is very important for the overall consistency of the GNU |
| system. |
| </p> |
| |
| <hr> |
| <a name="Compatibility"></a> |
| <div class="header"> |
| <p> |
| Next: <a href="#Using-Extensions" accesskey="n" rel="next">Using Extensions</a>, Previous: <a href="#Source-Language" accesskey="p" rel="prev">Source Language</a>, Up: <a href="#Design-Advice" accesskey="u" rel="up">Design Advice</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p> |
| </div> |
| <a name="Compatibility-with-Other-Implementations"></a> |
| <h3 class="section">3.2 Compatibility with Other Implementations</h3> |
| <a name="index-compatibility-with-C-and-POSIX-standards"></a> |
| <a name="index-POSIX-compatibility"></a> |
| |
| <p>With occasional exceptions, utility programs and libraries for GNU |
| should be upward compatible with those in Berkeley Unix, and upward |
| compatible with Standard C if Standard C specifies their |
| behavior, and upward compatible with <small>POSIX</small> if <small>POSIX</small> specifies |
| their behavior. |
| </p> |
| <p>When these standards conflict, it is useful to offer compatibility |
| modes for each of them. |
| </p> |
| <a name="index-options-for-compatibility"></a> |
| <p>Standard C and <small>POSIX</small> prohibit many kinds of extensions. Feel |
| free to make the extensions anyway, and include a ‘<samp>--ansi</samp>’, |
| ‘<samp>--posix</samp>’, or ‘<samp>--compatible</samp>’ option to turn them off. |
| However, if the extension has a significant chance of breaking any real |
| programs or scripts, then it is not really upward compatible. So you |
| should try to redesign its interface to make it upward compatible. |
| </p> |
| <a name="index-POSIXLY_005fCORRECT_002c-environment-variable"></a> |
| <p>Many GNU programs suppress extensions that conflict with <small>POSIX</small> if the |
| environment variable <code>POSIXLY_CORRECT</code> is defined (even if it is |
| defined with a null value). Please make your program recognize this |
| variable if appropriate. |
| </p> |
| <p>When a feature is used only by users (not by programs or command |
| files), and it is done poorly in Unix, feel free to replace it |
| completely with something totally different and better. (For example, |
| <code>vi</code> is replaced with Emacs.) But it is nice to offer a compatible |
| feature as well. (There is a free <code>vi</code> clone, so we offer it.) |
| </p> |
| <p>Additional useful features are welcome regardless of whether |
| there is any precedent for them. |
| </p> |
| <hr> |
| <a name="Using-Extensions"></a> |
| <div class="header"> |
| <p> |
| Next: <a href="#Standard-C" accesskey="n" rel="next">Standard C</a>, Previous: <a href="#Compatibility" accesskey="p" rel="prev">Compatibility</a>, Up: <a href="#Design-Advice" accesskey="u" rel="up">Design Advice</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p> |
| </div> |
| <a name="Using-Non_002dstandard-Features"></a> |
| <h3 class="section">3.3 Using Non-standard Features</h3> |
| <a name="index-non_002dstandard-extensions"></a> |
| |
| <p>Many GNU facilities that already exist support a number of convenient |
| extensions over the comparable Unix facilities. Whether to use these |
| extensions in implementing your program is a difficult question. |
| </p> |
| <p>On the one hand, using the extensions can make a cleaner program. |
| On the other hand, people will not be able to build the program |
| unless the other GNU tools are available. This might cause the |
| program to work on fewer kinds of machines. |
| </p> |
| <p>With some extensions, it might be easy to provide both alternatives. |
| For example, you can define functions with a “keyword” <code>INLINE</code> |
| and define that as a macro to expand into either <code>inline</code> or |
| nothing, depending on the compiler. |
| </p> |
| <p>In general, perhaps it is best not to use the extensions if you can |
| straightforwardly do without them, but to use the extensions if they |
| are a big improvement. |
| </p> |
| <p>An exception to this rule are the large, established programs (such as |
| Emacs) which run on a great variety of systems. Using GNU extensions in |
| such programs would make many users unhappy, so we don’t do that. |
| </p> |
| <p>Another exception is for programs that are used as part of compilation: |
| anything that must be compiled with other compilers in order to |
| bootstrap the GNU compilation facilities. If these require the GNU |
| compiler, then no one can compile them without having them installed |
| already. That would be extremely troublesome in certain cases. |
| </p> |
| <hr> |
| <a name="Standard-C"></a> |
| <div class="header"> |
| <p> |
| Next: <a href="#Conditional-Compilation" accesskey="n" rel="next">Conditional Compilation</a>, Previous: <a href="#Using-Extensions" accesskey="p" rel="prev">Using Extensions</a>, Up: <a href="#Design-Advice" accesskey="u" rel="up">Design Advice</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p> |
| </div> |
| <a name="Standard-C-and-Pre_002dStandard-C"></a> |
| <h3 class="section">3.4 Standard C and Pre-Standard C</h3> |
| <a name="index-ANSI-C-standard"></a> |
| |
| <p>1989 Standard C is widespread enough now that it is ok to use its |
| features in new programs. There is one exception: do not ever use the |
| “trigraph” feature of Standard C. |
| </p> |
| <p>1999 Standard C is not widespread yet, so please do not require its |
| features in programs. It is ok to use its features if they are present. |
| </p> |
| <p>However, it is easy to support pre-standard compilers in most programs, |
| so if you know how to do that, feel free. If a program you are |
| maintaining has such support, you should try to keep it working. |
| </p> |
| <a name="index-function-prototypes"></a> |
| <p>To support pre-standard C, instead of writing function definitions in |
| standard prototype form, |
| </p> |
| <div class="example"> |
| <pre class="example">int |
| foo (int x, int y) |
| … |
| </pre></div> |
| |
| <p>write the definition in pre-standard style like this, |
| </p> |
| <div class="example"> |
| <pre class="example">int |
| foo (x, y) |
| int x, y; |
| … |
| </pre></div> |
| |
| <p>and use a separate declaration to specify the argument prototype: |
| </p> |
| <div class="example"> |
| <pre class="example">int foo (int, int); |
| </pre></div> |
| |
| <p>You need such a declaration anyway, in a header file, to get the benefit |
| of prototypes in all the files where the function is called. And once |
| you have the declaration, you normally lose nothing by writing the |
| function definition in the pre-standard style. |
| </p> |
| <p>This technique does not work for integer types narrower than <code>int</code>. |
| If you think of an argument as being of a type narrower than <code>int</code>, |
| declare it as <code>int</code> instead. |
| </p> |
| <p>There are a few special cases where this technique is hard to use. For |
| example, if a function argument needs to hold the system type |
| <code>dev_t</code>, you run into trouble, because <code>dev_t</code> is shorter than |
| <code>int</code> on some machines; but you cannot use <code>int</code> instead, |
| because <code>dev_t</code> is wider than <code>int</code> on some machines. There |
| is no type you can safely use on all machines in a non-standard |
| definition. The only way to support non-standard C and pass such an |
| argument is to check the width of <code>dev_t</code> using Autoconf and choose |
| the argument type accordingly. This may not be worth the trouble. |
| </p> |
| <p>In order to support pre-standard compilers that do not recognize |
| prototypes, you may want to use a preprocessor macro like this: |
| </p> |
| <div class="example"> |
| <pre class="example">/* Declare the prototype for a general external function. */ |
| #if defined (__STDC__) || defined (WINDOWSNT) |
| #define P_(proto) proto |
| #else |
| #define P_(proto) () |
| #endif |
| </pre></div> |
| |
| <hr> |
| <a name="Conditional-Compilation"></a> |
| <div class="header"> |
| <p> |
| Previous: <a href="#Standard-C" accesskey="p" rel="prev">Standard C</a>, Up: <a href="#Design-Advice" accesskey="u" rel="up">Design Advice</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p> |
| </div> |
| <a name="Conditional-Compilation-1"></a> |
| <h3 class="section">3.5 Conditional Compilation</h3> |
| |
| <p>When supporting configuration options already known when building your |
| program we prefer using <code>if (... )</code> over conditional compilation, |
| as in the former case the compiler is able to perform more extensive |
| checking of all possible code paths. |
| </p> |
| <p>For example, please write |
| </p> |
| <div class="smallexample"> |
| <pre class="smallexample"> if (HAS_FOO) |
| ... |
| else |
| ... |
| </pre></div> |
| |
| <p>instead of: |
| </p> |
| <div class="smallexample"> |
| <pre class="smallexample"> #ifdef HAS_FOO |
| ... |
| #else |
| ... |
| #endif |
| </pre></div> |
| |
| <p>A modern compiler such as GCC will generate exactly the same code in |
| both cases, and we have been using similar techniques with good success |
| in several projects. Of course, the former method assumes that |
| <code>HAS_FOO</code> is defined as either 0 or 1. |
| </p> |
| <p>While this is not a silver bullet solving all portability problems, |
| and is not always appropriate, following this policy would have saved |
| GCC developers many hours, or even days, per year. |
| </p> |
| <p>In the case of function-like macros like <code>REVERSIBLE_CC_MODE</code> in |
| GCC which cannot be simply used in <code>if (...)</code> statements, there is |
| an easy workaround. Simply introduce another macro |
| <code>HAS_REVERSIBLE_CC_MODE</code> as in the following example: |
| </p> |
| <div class="smallexample"> |
| <pre class="smallexample"> #ifdef REVERSIBLE_CC_MODE |
| #define HAS_REVERSIBLE_CC_MODE 1 |
| #else |
| #define HAS_REVERSIBLE_CC_MODE 0 |
| #endif |
| </pre></div> |
| |
| <hr> |
| <a name="Program-Behavior"></a> |
| <div class="header"> |
| <p> |
| Next: <a href="#Writing-C" accesskey="n" rel="next">Writing C</a>, Previous: <a href="#Design-Advice" accesskey="p" rel="prev">Design Advice</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p> |
| </div> |
| <a name="Program-Behavior-for-All-Programs"></a> |
| <h2 class="chapter">4 Program Behavior for All Programs</h2> |
| |
| <p>This chapter describes conventions for writing robust |
| software. It also describes general standards for error messages, the |
| command line interface, and how libraries should behave. |
| </p> |
| <table class="menu" border="0" cellspacing="0"> |
| <tr><td align="left" valign="top">• <a href="#Non_002dGNU-Standards" accesskey="1">Non-GNU Standards</a>:</td><td> </td><td align="left" valign="top">We consider standards such as POSIX; |
| we don’t "obey" them. |
| </td></tr> |
| <tr><td align="left" valign="top">• <a href="#Semantics" accesskey="2">Semantics</a>:</td><td> </td><td align="left" valign="top">Writing robust programs. |
| </td></tr> |
| <tr><td align="left" valign="top">• <a href="#Libraries" accesskey="3">Libraries</a>:</td><td> </td><td align="left" valign="top">Library behavior. |
| </td></tr> |
| <tr><td align="left" valign="top">• <a href="#Errors" accesskey="4">Errors</a>:</td><td> </td><td align="left" valign="top">Formatting error messages. |
| </td></tr> |
| <tr><td align="left" valign="top">• <a href="#User-Interfaces" accesskey="5">User Interfaces</a>:</td><td> </td><td align="left" valign="top">Standards about interfaces generally. |
| </td></tr> |
| <tr><td align="left" valign="top">• <a href="#Graphical-Interfaces" accesskey="6">Graphical Interfaces</a>:</td><td> </td><td align="left" valign="top">Standards for graphical interfaces. |
| </td></tr> |
| <tr><td align="left" valign="top">• <a href="#Command_002dLine-Interfaces" accesskey="7">Command-Line Interfaces</a>:</td><td> </td><td align="left" valign="top">Standards for command line interfaces. |
| </td></tr> |
| <tr><td align="left" valign="top">• <a href="#Option-Table" accesskey="8">Option Table</a>:</td><td> </td><td align="left" valign="top">Table of long options. |
| </td></tr> |
| <tr><td align="left" valign="top">• <a href="#OID-Allocations" accesskey="9">OID Allocations</a>:</td><td> </td><td align="left" valign="top">Table of OID slots for GNU. |
| </td></tr> |
| <tr><td align="left" valign="top">• <a href="#Memory-Usage">Memory Usage</a>:</td><td> </td><td align="left" valign="top">When and how to care about memory needs. |
| </td></tr> |
| <tr><td align="left" valign="top">• <a href="#File-Usage">File Usage</a>:</td><td> </td><td align="left" valign="top">Which files to use, and where. |
| </td></tr> |
| </table> |
| |
| <hr> |
| <a name="Non_002dGNU-Standards"></a> |
| <div class="header"> |
| <p> |
| Next: <a href="#Semantics" accesskey="n" rel="next">Semantics</a>, Up: <a href="#Program-Behavior" accesskey="u" rel="up">Program Behavior</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p> |
| </div> |
| <a name="Non_002dGNU-Standards-1"></a> |
| <h3 class="section">4.1 Non-GNU Standards</h3> |
| |
| <p>The GNU Project regards standards published by other organizations as |
| suggestions, not orders. We consider those standards, but we do not |
| “obey” them. In developing a GNU program, you should implement |
| an outside standard’s specifications when that makes the GNU system |
| better overall in an objective sense. When it doesn’t, you shouldn’t. |
| </p> |
| <p>In most cases, following published standards is convenient for |
| users—it means that their programs or scripts will work more |
| portably. For instance, GCC implements nearly all the features of |
| Standard C as specified by that standard. C program developers would |
| be unhappy if it did not. And GNU utilities mostly follow |
| specifications of POSIX.2; shell script writers and users would be |
| unhappy if our programs were incompatible. |
| </p> |
| <p>But we do not follow either of these specifications rigidly, and there |
| are specific points on which we decided not to follow them, so as to |
| make the GNU system better for users. |
| </p> |
| <p>For instance, Standard C says that nearly all extensions to C are |
| prohibited. How silly! GCC implements many extensions, some of which |
| were later adopted as part of the standard. If you want these |
| constructs to give an error message as “required” by the standard, |
| you must specify ‘<samp>--pedantic</samp>’, which was implemented only so that |
| we can say “GCC is a 100% implementation of the standard,” not |
| because there is any reason to actually use it. |
| </p> |
| <p>POSIX.2 specifies that ‘<samp>df</samp>’ and ‘<samp>du</samp>’ must output sizes by |
| default in units of 512 bytes. What users want is units of 1k, so |
| that is what we do by default. If you want the ridiculous behavior |
| “required” by POSIX, you must set the environment variable |
| ‘<samp>POSIXLY_CORRECT</samp>’ (which was originally going to be named |
| ‘<samp>POSIX_ME_HARDER</samp>’). |
| </p> |
| <p>GNU utilities also depart from the letter of the POSIX.2 specification |
| when they support long-named command-line options, and intermixing |
| options with ordinary arguments. This minor incompatibility with |
| POSIX is never a problem in practice, and it is very useful. |
| </p> |
| <p>In particular, don’t reject a new feature, or remove an old one, |
| merely because a standard says it is “forbidden” or “deprecated.” |
| </p> |
| <hr> |
| <a name="Semantics"></a> |
| <div class="header"> |
| <p> |
| Next: <a href="#Libraries" accesskey="n" rel="next">Libraries</a>, Previous: <a href="#Non_002dGNU-Standards" accesskey="p" rel="prev">Non-GNU Standards</a>, Up: <a href="#Program-Behavior" accesskey="u" rel="up">Program Behavior</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p> |
| </div> |
| <a name="Writing-Robust-Programs"></a> |
| <h3 class="section">4.2 Writing Robust Programs</h3> |
| |
| <a name="index-arbitrary-limits-on-data"></a> |
| <p>Avoid arbitrary limits on the length or number of <em>any</em> data |
| structure, including file names, lines, files, and symbols, by allocating |
| all data structures dynamically. In most Unix utilities, “long lines |
| are silently truncated”. This is not acceptable in a GNU utility. |
| </p> |
| <a name="index-NUL-characters"></a> |
| <p>Utilities reading files should not drop NUL characters, or any other |
| nonprinting characters <em>including those with codes above 0177</em>. |
| The only sensible exceptions would be utilities specifically intended |
| for interface to certain types of terminals or printers |
| that can’t handle those characters. |
| Whenever possible, try to make programs work properly with |
| sequences of bytes that represent multibyte characters, using encodings |
| such as UTF-8 and others. |
| </p> |
| <a name="index-error-messages"></a> |
| <p>Check every system call for an error return, unless you know you wish to |
| ignore errors. Include the system error text (from <code>perror</code> or |
| equivalent) in <em>every</em> error message resulting from a failing |
| system call, as well as the name of the file if any and the name of the |
| utility. Just “cannot open foo.c” or “stat failed” is not |
| sufficient. |
| </p> |
| <a name="index-malloc-return-value"></a> |
| <a name="index-memory-allocation-failure"></a> |
| <p>Check every call to <code>malloc</code> or <code>realloc</code> to see if it |
| returned zero. Check <code>realloc</code> even if you are making the block |
| smaller; in a system that rounds block sizes to a power of 2, |
| <code>realloc</code> may get a different block if you ask for less space. |
| </p> |
| <p>In Unix, <code>realloc</code> can destroy the storage block if it returns |
| zero. GNU <code>realloc</code> does not have this bug: if it fails, the |
| original block is unchanged. Feel free to assume the bug is fixed. If |
| you wish to run your program on Unix, and wish to avoid lossage in this |
| case, you can use the GNU <code>malloc</code>. |
| </p> |
| <p>You must expect <code>free</code> to alter the contents of the block that was |
| freed. Anything you want to fetch from the block, you must fetch before |
| calling <code>free</code>. |
| </p> |
| <p>If <code>malloc</code> fails in a noninteractive program, make that a fatal |
| error. In an interactive program (one that reads commands from the |
| user), it is better to abort the command and return to the command |
| reader loop. This allows the user to kill other processes to free up |
| virtual memory, and then try the command again. |
| </p> |
| <a name="index-command_002dline-arguments_002c-decoding"></a> |
| <p>Use <code>getopt_long</code> to decode arguments, unless the argument syntax |
| makes this unreasonable. |
| </p> |
| <p>When static storage is to be written in during program execution, use |
| explicit C code to initialize it. Reserve C initialized declarations |
| for data that will not be changed. |
| </p> |
| <p>Try to avoid low-level interfaces to obscure Unix data structures (such |
| as file directories, utmp, or the layout of kernel memory), since these |
| are less likely to work compatibly. If you need to find all the files |
| in a directory, use <code>readdir</code> or some other high-level interface. |
| These are supported compatibly by GNU. |
| </p> |
| <a name="index-signal-handling"></a> |
| <p>The preferred signal handling facilities are the BSD variant of |
| <code>signal</code>, and the <small>POSIX</small> <code>sigaction</code> function; the |
| alternative USG <code>signal</code> interface is an inferior design. |
| </p> |
| <p>Nowadays, using the <small>POSIX</small> signal functions may be the easiest way |
| to make a program portable. If you use <code>signal</code>, then on GNU/Linux |
| systems running GNU libc version 1, you should include |
| <samp>bsd/signal.h</samp> instead of <samp>signal.h</samp>, so as to get BSD |
| behavior. It is up to you whether to support systems where |
| <code>signal</code> has only the USG behavior, or give up on them. |
| </p> |
| <a name="index-impossible-conditions"></a> |
| <p>In error checks that detect “impossible” conditions, just abort. |
| There is usually no point in printing any message. These checks |
| indicate the existence of bugs. Whoever wants to fix the bugs will have |
| to read the source code and run a debugger. So explain the problem with |
| comments in the source. The relevant data will be in variables, which |
| are easy to examine with the debugger, so there is no point moving them |
| elsewhere. |
| </p> |
| <p>Do not use a count of errors as the exit status for a program. |
| <em>That does not work</em>, because exit status values are limited to 8 |
| bits (0 through 255). A single run of the program might have 256 |
| errors; if you try to return 256 as the exit status, the parent process |
| will see 0 as the status, and it will appear that the program succeeded. |
| </p> |
| <a name="index-temporary-files"></a> |
| <a name="index-TMPDIR-environment-variable"></a> |
| <p>If you make temporary files, check the <code>TMPDIR</code> environment |
| variable; if that variable is defined, use the specified directory |
| instead of <samp>/tmp</samp>. |
| </p> |
| <p>In addition, be aware that there is a possible security problem when |
| creating temporary files in world-writable directories. In C, you can |
| avoid this problem by creating temporary files in this manner: |
| </p> |
| <div class="example"> |
| <pre class="example">fd = open (filename, O_WRONLY | O_CREAT | O_EXCL, 0600); |
| </pre></div> |
| |
| <p>or by using the <code>mkstemps</code> function from libiberty. |
| </p> |
| <p>In bash, use <code>set -C</code> to avoid this problem. |
| </p> |
| <hr> |
| <a name="Libraries"></a> |
| <div class="header"> |
| <p> |
| Next: <a href="#Errors" accesskey="n" rel="next">Errors</a>, Previous: <a href="#Semantics" accesskey="p" rel="prev">Semantics</a>, Up: <a href="#Program-Behavior" accesskey="u" rel="up">Program Behavior</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p> |
| </div> |
| <a name="Library-Behavior"></a> |
| <h3 class="section">4.3 Library Behavior</h3> |
| <a name="index-libraries"></a> |
| |
| <p>Try to make library functions reentrant. If they need to do dynamic |
| storage allocation, at least try to avoid any nonreentrancy aside from |
| that of <code>malloc</code> itself. |
| </p> |
| <p>Here are certain name conventions for libraries, to avoid name |
| conflicts. |
| </p> |
| <p>Choose a name prefix for the library, more than two characters long. |
| All external function and variable names should start with this |
| prefix. In addition, there should only be one of these in any given |
| library member. This usually means putting each one in a separate |
| source file. |
| </p> |
| <p>An exception can be made when two external symbols are always used |
| together, so that no reasonable program could use one without the |
| other; then they can both go in the same file. |
| </p> |
| <p>External symbols that are not documented entry points for the user |
| should have names beginning with ‘<samp>_</samp>’. The ‘<samp>_</samp>’ should be |
| followed by the chosen name prefix for the library, to prevent |
| collisions with other libraries. These can go in the same files with |
| user entry points if you like. |
| </p> |
| <p>Static functions and variables can be used as you like and need not |
| fit any naming convention. |
| </p> |
| <hr> |
| <a name="Errors"></a> |
| <div class="header"> |
| <p> |
| Next: <a href="#User-Interfaces" accesskey="n" rel="next">User Interfaces</a>, Previous: <a href="#Libraries" accesskey="p" rel="prev">Libraries</a>, Up: <a href="#Program-Behavior" accesskey="u" rel="up">Program Behavior</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p> |
| </div> |
| <a name="Formatting-Error-Messages"></a> |
| <h3 class="section">4.4 Formatting Error Messages</h3> |
| <a name="index-formatting-error-messages"></a> |
| <a name="index-error-messages_002c-formatting"></a> |
| |
| <p>Error messages from compilers should look like this: |
| </p> |
| <div class="example"> |
| <pre class="example"><var>source-file-name</var>:<var>lineno</var>: <var>message</var> |
| </pre></div> |
| |
| <p>If you want to mention the column number, use one of these formats: |
| </p> |
| <div class="example"> |
| <pre class="example"><var>source-file-name</var>:<var>lineno</var>:<var>column</var>: <var>message</var> |
| <var>source-file-name</var>:<var>lineno</var>.<var>column</var>: <var>message</var> |
| |
| </pre></div> |
| |
| <p>Line numbers should start from 1 at the beginning of the file, and |
| column numbers should start from 1 at the beginning of the line. (Both |
| of these conventions are chosen for compatibility.) Calculate column |
| numbers assuming that space and all ASCII printing characters have |
| equal width, and assuming tab stops every 8 columns. |
| </p> |
| <p>The error message can also give both the starting and ending positions |
| of the erroneous text. There are several formats so that you can |
| avoid redundant information such as a duplicate line number. |
| Here are the possible formats: |
| </p> |
| <div class="example"> |
| <pre class="example"><var>source-file-name</var>:<var>lineno-1</var>.<var>column-1</var>-<var>lineno-2</var>.<var>column-2</var>: <var>message</var> |
| <var>source-file-name</var>:<var>lineno-1</var>.<var>column-1</var>-<var>column-2</var>: <var>message</var> |
| <var>source-file-name</var>:<var>lineno-1</var>-<var>lineno-2</var>: <var>message</var> |
| </pre></div> |
| |
| <p>When an error is spread over several files, you can use this format: |
| </p> |
| <div class="example"> |
| <pre class="example"><var>file-1</var>:<var>lineno-1</var>.<var>column-1</var>-<var>file-2</var>:<var>lineno-2</var>.<var>column-2</var>: <var>message</var> |
| </pre></div> |
| |
| <p>Error messages from other noninteractive programs should look like this: |
| </p> |
| <div class="example"> |
| <pre class="example"><var>program</var>:<var>source-file-name</var>:<var>lineno</var>: <var>message</var> |
| </pre></div> |
| |
| <p>when there is an appropriate source file, or like this: |
| </p> |
| <div class="example"> |
| <pre class="example"><var>program</var>: <var>message</var> |
| </pre></div> |
| |
| <p>when there is no relevant source file. |
| </p> |
| <p>If you want to mention the column number, use this format: |
| </p> |
| <div class="example"> |
| <pre class="example"><var>program</var>:<var>source-file-name</var>:<var>lineno</var>:<var>column</var>: <var>message</var> |
| </pre></div> |
| |
| <p>In an interactive program (one that is reading commands from a |
| terminal), it is better not to include the program name in an error |
| message. The place to indicate which program is running is in the |
| prompt or with the screen layout. (When the same program runs with |
| input from a source other than a terminal, it is not interactive and |
| would do best to print error messages using the noninteractive style.) |
| </p> |
| <p>The string <var>message</var> should not begin with a capital letter when |
| it follows a program name and/or file name, because that isn’t the |
| beginning of a sentence. (The sentence conceptually starts at the |
| beginning of the line.) Also, it should not end with a period. |
| </p> |
| <p>Error messages from interactive programs, and other messages such as |
| usage messages, should start with a capital letter. But they should not |
| end with a period. |
| </p> |
| <hr> |
| <a name="User-Interfaces"></a> |
| <div class="header"> |
| <p> |
| Next: <a href="#Graphical-Interfaces" accesskey="n" rel="next">Graphical Interfaces</a>, Previous: <a href="#Errors" accesskey="p" rel="prev">Errors</a>, Up: <a href="#Program-Behavior" accesskey="u" rel="up">Program Behavior</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p> |
| </div> |
| <a name="Standards-for-Interfaces-Generally"></a> |
| <h3 class="section">4.5 Standards for Interfaces Generally</h3> |
| |
| <a name="index-program-name-and-its-behavior"></a> |
| <a name="index-behavior_002c-dependent-on-program_0027s-name"></a> |
| <p>Please don’t make the behavior of a utility depend on the name used |
| to invoke it. It is useful sometimes to make a link to a utility |
| with a different name, and that should not change what it does. |
| </p> |
| <p>Instead, use a run time option or a compilation switch or both |
| to select among the alternate behaviors. |
| </p> |
| <a name="index-output-device-and-program_0027s-behavior"></a> |
| <p>Likewise, please don’t make the behavior of the program depend on the |
| type of output device it is used with. Device independence is an |
| important principle of the system’s design; do not compromise it merely |
| to save someone from typing an option now and then. (Variation in error |
| message syntax when using a terminal is ok, because that is a side issue |
| that people do not depend on.) |
| </p> |
| <p>If you think one behavior is most useful when the output is to a |
| terminal, and another is most useful when the output is a file or a |
| pipe, then it is usually best to make the default behavior the one that |
| is useful with output to a terminal, and have an option for the other |
| behavior. |
| </p> |
| <p>Compatibility requires certain programs to depend on the type of output |
| device. It would be disastrous if <code>ls</code> or <code>sh</code> did not do so |
| in the way all users expect. In some of these cases, we supplement the |
| program with a preferred alternate version that does not depend on the |
| output device type. For example, we provide a <code>dir</code> program much |
| like <code>ls</code> except that its default output format is always |
| multi-column format. |
| </p> |
| |
| <hr> |
| <a name="Graphical-Interfaces"></a> |
| <div class="header"> |
| <p> |
| Next: <a href="#Command_002dLine-Interfaces" accesskey="n" rel="next">Command-Line Interfaces</a>, Previous: <a href="#User-Interfaces" accesskey="p" rel="prev">User Interfaces</a>, Up: <a href="#Program-Behavior" accesskey="u" rel="up">Program Behavior</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p> |
| </div> |
| <a name="Standards-for-Graphical-Interfaces"></a> |
| <h3 class="section">4.6 Standards for Graphical Interfaces</h3> |
| <a name="index-graphical-user-interface"></a> |
| <a name="index-interface-styles"></a> |
| <a name="index-user-interface-styles"></a> |
| |
| <a name="index-GTK_002b"></a> |
| <p>When you write a program that provides a graphical user interface, |
| please make it work with the X Window System and the GTK+ toolkit |
| unless the functionality specifically requires some alternative (for |
| example, “displaying jpeg images while in console mode”). |
| </p> |
| <p>In addition, please provide a command-line interface to control the |
| functionality. (In many cases, the graphical user interface can be a |
| separate program which invokes the command-line program.) This is |
| so that the same jobs can be done from scripts. |
| </p> |
| <a name="index-CORBA"></a> |
| <a name="index-GNOME"></a> |
| <a name="index-D_002dbus"></a> |
| <a name="index-keyboard-interface"></a> |
| <a name="index-library-interface"></a> |
| <p>Please also consider providing a D-bus interface for use from other |
| running programs, such as within GNOME. (GNOME used to use CORBA |
| for this, but that is being phased out.) In addition, consider |
| providing a library interface (for use from C), and perhaps a |
| keyboard-driven console interface (for use by users from console |
| mode). Once you are doing the work to provide the functionality and |
| the graphical interface, these won’t be much extra work. |
| </p> |
| |
| <hr> |
| <a name="Command_002dLine-Interfaces"></a> |
| <div class="header"> |
| <p> |
| Next: <a href="#Option-Table" accesskey="n" rel="next">Option Table</a>, Previous: <a href="#Graphical-Interfaces" accesskey="p" rel="prev">Graphical Interfaces</a>, Up: <a href="#Program-Behavior" accesskey="u" rel="up">Program Behavior</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p> |
| </div> |
| <a name="Standards-for-Command-Line-Interfaces"></a> |
| <h3 class="section">4.7 Standards for Command Line Interfaces</h3> |
| <a name="index-command_002dline-interface"></a> |
| |
| <a name="index-getopt"></a> |
| <p>It is a good idea to follow the <small>POSIX</small> guidelines for the |
| command-line options of a program. The easiest way to do this is to use |
| <code>getopt</code> to parse them. Note that the GNU version of <code>getopt</code> |
| will normally permit options anywhere among the arguments unless the |
| special argument ‘<samp>--</samp>’ is used. This is not what <small>POSIX</small> |
| specifies; it is a GNU extension. |
| </p> |
| <a name="index-long_002dnamed-options"></a> |
| <p>Please define long-named options that are equivalent to the |
| single-letter Unix-style options. We hope to make GNU more user |
| friendly this way. This is easy to do with the GNU function |
| <code>getopt_long</code>. |
| </p> |
| <p>One of the advantages of long-named options is that they can be |
| consistent from program to program. For example, users should be able |
| to expect the “verbose” option of any GNU program which has one, to be |
| spelled precisely ‘<samp>--verbose</samp>’. To achieve this uniformity, look at |
| the table of common long-option names when you choose the option names |
| for your program (see <a href="#Option-Table">Option Table</a>). |
| </p> |
| <p>It is usually a good idea for file names given as ordinary arguments to |
| be input files only; any output files would be specified using options |
| (preferably ‘<samp>-o</samp>’ or ‘<samp>--output</samp>’). Even if you allow an output |
| file name as an ordinary argument for compatibility, try to provide an |
| option as another way to specify it. This will lead to more consistency |
| among GNU utilities, and fewer idiosyncrasies for users to remember. |
| </p> |
| <a name="index-standard-command_002dline-options"></a> |
| <a name="index-options_002c-standard-command_002dline"></a> |
| <a name="index-CGI-programs_002c-standard-options-for"></a> |
| <a name="index-PATH_005fINFO_002c-specifying-standard-options-as"></a> |
| <p>All programs should support two standard options: ‘<samp>--version</samp>’ |
| and ‘<samp>--help</samp>’. CGI programs should accept these as command-line |
| options, and also if given as the <code>PATH_INFO</code>; for instance, |
| visiting <a href="http://example.org/p.cgi/--help">http://example.org/p.cgi/--help</a> in a browser should |
| output the same information as invoking ‘<samp>p.cgi --help</samp>’ from the |
| command line. |
| </p> |
| <table class="menu" border="0" cellspacing="0"> |
| <tr><td align="left" valign="top">• <a href="#g_t_002d_002dversion" accesskey="1">--version</a>:</td><td> </td><td align="left" valign="top">The standard output for –version. |
| </td></tr> |
| <tr><td align="left" valign="top">• <a href="#g_t_002d_002dhelp" accesskey="2">--help</a>:</td><td> </td><td align="left" valign="top">The standard output for –help. |
| </td></tr> |
| </table> |
| |
| <hr> |
| <a name="g_t_002d_002dversion"></a> |
| <div class="header"> |
| <p> |
| Next: <a href="#g_t_002d_002dhelp" accesskey="n" rel="next">--help</a>, Up: <a href="#Command_002dLine-Interfaces" accesskey="u" rel="up">Command-Line Interfaces</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p> |
| </div> |
| <a name="g_t_002d_002dversion-1"></a> |
| <h4 class="subsection">4.7.1 <samp>--version</samp></h4> |
| |
| <a name="index-_002d_002dversion-output"></a> |
| |
| <p>The standard <code>--version</code> option should direct the program to |
| print information about its name, version, origin and legal status, |
| all on standard output, and then exit successfully. Other options and |
| arguments should be ignored once this is seen, and the program should |
| not perform its normal function. |
| </p> |
| <a name="index-canonical-name-of-a-program"></a> |
| <a name="index-program_0027s-canonical-name"></a> |
| <p>The first line is meant to be easy for a program to parse; the version |
| number proper starts after the last space. In addition, it contains |
| the canonical name for this program, in this format: |
| </p> |
| <div class="example"> |
| <pre class="example">GNU Emacs 19.30 |
| </pre></div> |
| |
| <p>The program’s name should be a constant string; <em>don’t</em> compute it |
| from <code>argv[0]</code>. The idea is to state the standard or canonical |
| name for the program, not its file name. There are other ways to find |
| out the precise file name where a command is found in <code>PATH</code>. |
| </p> |
| <p>If the program is a subsidiary part of a larger package, mention the |
| package name in parentheses, like this: |
| </p> |
| <div class="example"> |
| <pre class="example">emacsserver (GNU Emacs) 19.30 |
| </pre></div> |
| |
| <p>If the package has a version number which is different from this |
| program’s version number, you can mention the package version number |
| just before the close-parenthesis. |
| </p> |
| <p>If you <em>need</em> to mention the version numbers of libraries which |
| are distributed separately from the package which contains this program, |
| you can do so by printing an additional line of version info for each |
| library you want to mention. Use the same format for these lines as for |
| the first line. |
| </p> |
| <p>Please do not mention all of the libraries that the program uses “just |
| for completeness”—that would produce a lot of unhelpful clutter. |
| Please mention library version numbers only if you find in practice that |
| they are very important to you in debugging. |
| </p> |
| <p>The following line, after the version number line or lines, should be a |
| copyright notice. If more than one copyright notice is called for, put |
| each on a separate line. |
| </p> |
| <p>Next should follow a line stating the license, preferably using one of |
| abbrevations below, and a brief statement that the program is free |
| software, and that users are free to copy and change it. Also mention |
| that there is no warranty, to the extent permitted by law. See |
| recommended wording below. |
| </p> |
| <p>It is ok to finish the output with a list of the major authors of the |
| program, as a way of giving credit. |
| </p> |
| <p>Here’s an example of output that follows these rules: |
| </p> |
| <div class="smallexample"> |
| <pre class="smallexample">GNU hello 2.3 |
| Copyright (C) 2007 Free Software Foundation, Inc. |
| License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html> |
| This is free software: you are free to change and redistribute it. |
| There is NO WARRANTY, to the extent permitted by law. |
| </pre></div> |
| |
| <p>You should adapt this to your program, of course, filling in the proper |
| year, copyright holder, name of program, and the references to |
| distribution terms, and changing the rest of the wording as necessary. |
| </p> |
| <p>This copyright notice only needs to mention the most recent year in |
| which changes were made—there’s no need to list the years for previous |
| versions’ changes. You don’t have to mention the name of the program in |
| these notices, if that is inconvenient, since it appeared in the first |
| line. (The rules are different for copyright notices in source files; |
| see <a href="http://www.gnu.org/prep/maintain/maintain.html#Copyright-Notices">Copyright Notices</a> in <cite>Information for GNU Maintainers</cite>.) |
| </p> |
| <p>Translations of the above lines must preserve the validity of the |
| copyright notices (see <a href="#Internationalization">Internationalization</a>). If the translation’s |
| character set supports it, the ‘<samp>(C)</samp>’ should be replaced with the |
| copyright symbol, as follows: |
| </p> |
| <p>© |
| </p> |
| <p>Write the word “Copyright” exactly like that, in English. Do not |
| translate it into another language. International treaties recognize |
| the English word “Copyright”; translations into other languages do not |
| have legal significance. |
| </p> |
| <p>Finally, here is the table of our suggested license abbreviations. |
| Any abbreviation can be followed by ‘<samp>v<var>version</var>[+]</samp>’, meaning |
| that particular version, or later versions with the ‘<samp>+</samp>’, as shown |
| above. |
| </p> |
| <p>In the case of exceptions for extra permissions with the GPL, we use |
| ‘<samp>/</samp>’ for a separator; the version number can follow the license |
| abbreviation as usual, as in the examples below. |
| </p> |
| <dl compact="compact"> |
| <dt>GPL</dt> |
| <dd><p>GNU General Public License, <a href="http://www.gnu.org/licenses/gpl.html">http://www.gnu.org/licenses/gpl.html</a>. |
| </p> |
| </dd> |
| <dt>LGPL</dt> |
| <dd><p>GNU Lesser General Public License, <a href="http://www.gnu.org/licenses/lgpl.html">http://www.gnu.org/licenses/lgpl.html</a>. |
| </p> |
| </dd> |
| <dt>GPL/Ada</dt> |
| <dd><p>GNU GPL with the exception for Ada. |
| </p> |
| </dd> |
| <dt>Apache</dt> |
| <dd><p>The Apache Software Foundation license, |
| <a href="http://www.apache.org/licenses">http://www.apache.org/licenses</a>. |
| </p> |
| </dd> |
| <dt>Artistic</dt> |
| <dd><p>The Artistic license used for Perl, <a href="http://www.perlfoundation.org/legal">http://www.perlfoundation.org/legal</a>. |
| </p> |
| </dd> |
| <dt>Expat</dt> |
| <dd><p>The Expat license, <a href="http://www.jclark.com/xml/copying.txt">http://www.jclark.com/xml/copying.txt</a>. |
| </p> |
| </dd> |
| <dt>MPL</dt> |
| <dd><p>The Mozilla Public License, <a href="http://www.mozilla.org/MPL/">http://www.mozilla.org/MPL/</a>. |
| </p> |
| </dd> |
| <dt>OBSD</dt> |
| <dd><p>The original (4-clause) BSD license, incompatible with the GNU GPL |
| <a href="http://www.xfree86.org/3.3.6/COPYRIGHT2.html#6">http://www.xfree86.org/3.3.6/COPYRIGHT2.html#6</a>. |
| </p> |
| </dd> |
| <dt>PHP</dt> |
| <dd><p>The license used for PHP, <a href="http://www.php.net/license/">http://www.php.net/license/</a>. |
| </p> |
| </dd> |
| <dt>public domain</dt> |
| <dd><p>The non-license that is being in the public domain, |
| <a href="http://www.gnu.org/licenses/license-list.html#PublicDomain">http://www.gnu.org/licenses/license-list.html#PublicDomain</a>. |
| </p> |
| </dd> |
| <dt>Python</dt> |
| <dd><p>The license for Python, <a href="http://www.python.org/2.0.1/license.html">http://www.python.org/2.0.1/license.html</a>. |
| </p> |
| </dd> |
| <dt>RBSD</dt> |
| <dd><p>The revised (3-clause) BSD, compatible with the GNU GPL,<br> |
| <a href="http://www.xfree86.org/3.3.6/COPYRIGHT2.html#5">http://www.xfree86.org/3.3.6/COPYRIGHT2.html#5</a>. |
| </p> |
| </dd> |
| <dt>X11</dt> |
| <dd><p>The simple non-copyleft license used for most versions of the X Window |
| System, <a href="http://www.xfree86.org/3.3.6/COPYRIGHT2.html#3">http://www.xfree86.org/3.3.6/COPYRIGHT2.html#3</a>. |
| </p> |
| </dd> |
| <dt>Zlib</dt> |
| <dd><p>The license for Zlib, <a href="http://www.gzip.org/zlib/zlib_license.html">http://www.gzip.org/zlib/zlib_license.html</a>. |
| </p> |
| </dd> |
| </dl> |
| |
| <p>More information about these licenses and many more are on the GNU |
| licensing web pages, |
| <a href="http://www.gnu.org/licenses/license-list.html">http://www.gnu.org/licenses/license-list.html</a>. |
| </p> |
| |
| <hr> |
| <a name="g_t_002d_002dhelp"></a> |
| <div class="header"> |
| <p> |
| Previous: <a href="#g_t_002d_002dversion" accesskey="p" rel="prev">--version</a>, Up: <a href="#Command_002dLine-Interfaces" accesskey="u" rel="up">Command-Line Interfaces</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p> |
| </div> |
| <a name="g_t_002d_002dhelp-1"></a> |
| <h4 class="subsection">4.7.2 <samp>--help</samp></h4> |
| |
| <a name="index-_002d_002dhelp-output"></a> |
| |
| <p>The standard <code>--help</code> option should output brief documentation |
| for how to invoke the program, on standard output, then exit |
| successfully. Other options and arguments should be ignored once this |
| is seen, and the program should not perform its normal function. |
| </p> |
| <a name="index-address-for-bug-reports"></a> |
| <a name="index-bug-reports"></a> |
| <p>Near the end of the ‘<samp>--help</samp>’ option’s output, please place lines |
| giving the email address for bug reports, the package’s home page |
| (normally ‘<code>http://www.gnu.org/software/<var>pkg</var></code>’, and the |
| general page for help using GNU programs. The format should be like this: |
| </p> |
| <div class="example"> |
| <pre class="example">Report bugs to: <var>mailing-address</var> |
| <var>pkg</var> home page: <http://www.gnu.org/software/<var>pkg</var>/> |
| General help using GNU software: <http://www.gnu.org/gethelp/> |
| </pre></div> |
| |
| <p>It is ok to mention other appropriate mailing lists and web pages. |
| </p> |
| |
| <hr> |
| <a name="Option-Table"></a> |
| <div class="header"> |
| <p> |
| Next: <a href="#OID-Allocations" accesskey="n" rel="next">OID Allocations</a>, Previous: <a href="#Command_002dLine-Interfaces" accesskey="p" rel="prev">Command-Line Interfaces</a>, Up: <a href="#Program-Behavior" accesskey="u" rel="up">Program Behavior</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p> |
| </div> |
| <a name="Table-of-Long-Options"></a> |
| <h3 class="section">4.8 Table of Long Options</h3> |
| <a name="index-long-option-names"></a> |
| <a name="index-table-of-long-options"></a> |
| |
| <p>Here is a table of long options used by GNU programs. It is surely |
| incomplete, but we aim to list all the options that a new program might |
| want to be compatible with. If you use names not already in the table, |
| please send <a href="mailto:bug-standards@gnu.org">bug-standards@gnu.org</a> a list of them, with their |
| meanings, so we can update the table. |
| </p> |
| |
| <dl compact="compact"> |
| <dt>‘<samp>after-date</samp>’</dt> |
| <dd><p>‘<samp>-N</samp>’ in <code>tar</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>all</samp>’</dt> |
| <dd><p>‘<samp>-a</samp>’ in <code>du</code>, <code>ls</code>, <code>nm</code>, <code>stty</code>, <code>uname</code>, |
| and <code>unexpand</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>all-text</samp>’</dt> |
| <dd><p>‘<samp>-a</samp>’ in <code>diff</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>almost-all</samp>’</dt> |
| <dd><p>‘<samp>-A</samp>’ in <code>ls</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>append</samp>’</dt> |
| <dd><p>‘<samp>-a</samp>’ in <code>etags</code>, <code>tee</code>, <code>time</code>; |
| ‘<samp>-r</samp>’ in <code>tar</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>archive</samp>’</dt> |
| <dd><p>‘<samp>-a</samp>’ in <code>cp</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>archive-name</samp>’</dt> |
| <dd><p>‘<samp>-n</samp>’ in <code>shar</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>arglength</samp>’</dt> |
| <dd><p>‘<samp>-l</samp>’ in <code>m4</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>ascii</samp>’</dt> |
| <dd><p>‘<samp>-a</samp>’ in <code>diff</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>assign</samp>’</dt> |
| <dd><p>‘<samp>-v</samp>’ in <code>gawk</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>assume-new</samp>’</dt> |
| <dd><p>‘<samp>-W</samp>’ in <code>make</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>assume-old</samp>’</dt> |
| <dd><p>‘<samp>-o</samp>’ in <code>make</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>auto-check</samp>’</dt> |
| <dd><p>‘<samp>-a</samp>’ in <code>recode</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>auto-pager</samp>’</dt> |
| <dd><p>‘<samp>-a</samp>’ in <code>wdiff</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>auto-reference</samp>’</dt> |
| <dd><p>‘<samp>-A</samp>’ in <code>ptx</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>avoid-wraps</samp>’</dt> |
| <dd><p>‘<samp>-n</samp>’ in <code>wdiff</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>background</samp>’</dt> |
| <dd><p>For server programs, run in the background. |
| </p> |
| </dd> |
| <dt>‘<samp>backward-search</samp>’</dt> |
| <dd><p>‘<samp>-B</samp>’ in <code>ctags</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>basename</samp>’</dt> |
| <dd><p>‘<samp>-f</samp>’ in <code>shar</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>batch</samp>’</dt> |
| <dd><p>Used in GDB. |
| </p> |
| </dd> |
| <dt>‘<samp>baud</samp>’</dt> |
| <dd><p>Used in GDB. |
| </p> |
| </dd> |
| <dt>‘<samp>before</samp>’</dt> |
| <dd><p>‘<samp>-b</samp>’ in <code>tac</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>binary</samp>’</dt> |
| <dd><p>‘<samp>-b</samp>’ in <code>cpio</code> and <code>diff</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>bits-per-code</samp>’</dt> |
| <dd><p>‘<samp>-b</samp>’ in <code>shar</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>block-size</samp>’</dt> |
| <dd><p>Used in <code>cpio</code> and <code>tar</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>blocks</samp>’</dt> |
| <dd><p>‘<samp>-b</samp>’ in <code>head</code> and <code>tail</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>break-file</samp>’</dt> |
| <dd><p>‘<samp>-b</samp>’ in <code>ptx</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>brief</samp>’</dt> |
| <dd><p>Used in various programs to make output shorter. |
| </p> |
| </dd> |
| <dt>‘<samp>bytes</samp>’</dt> |
| <dd><p>‘<samp>-c</samp>’ in <code>head</code>, <code>split</code>, and <code>tail</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>c<tt>++</tt></samp>’</dt> |
| <dd><p>‘<samp>-C</samp>’ in <code>etags</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>catenate</samp>’</dt> |
| <dd><p>‘<samp>-A</samp>’ in <code>tar</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>cd</samp>’</dt> |
| <dd><p>Used in various programs to specify the directory to use. |
| </p> |
| </dd> |
| <dt>‘<samp>changes</samp>’</dt> |
| <dd><p>‘<samp>-c</samp>’ in <code>chgrp</code> and <code>chown</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>classify</samp>’</dt> |
| <dd><p>‘<samp>-F</samp>’ in <code>ls</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>colons</samp>’</dt> |
| <dd><p>‘<samp>-c</samp>’ in <code>recode</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>command</samp>’</dt> |
| <dd><p>‘<samp>-c</samp>’ in <code>su</code>; |
| ‘<samp>-x</samp>’ in GDB. |
| </p> |
| </dd> |
| <dt>‘<samp>compare</samp>’</dt> |
| <dd><p>‘<samp>-d</samp>’ in <code>tar</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>compat</samp>’</dt> |
| <dd><p>Used in <code>gawk</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>compress</samp>’</dt> |
| <dd><p>‘<samp>-Z</samp>’ in <code>tar</code> and <code>shar</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>concatenate</samp>’</dt> |
| <dd><p>‘<samp>-A</samp>’ in <code>tar</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>confirmation</samp>’</dt> |
| <dd><p>‘<samp>-w</samp>’ in <code>tar</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>context</samp>’</dt> |
| <dd><p>Used in <code>diff</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>copyleft</samp>’</dt> |
| <dd><p>‘<samp>-W copyleft</samp>’ in <code>gawk</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>copyright</samp>’</dt> |
| <dd><p>‘<samp>-C</samp>’ in <code>ptx</code>, <code>recode</code>, and <code>wdiff</code>; |
| ‘<samp>-W copyright</samp>’ in <code>gawk</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>core</samp>’</dt> |
| <dd><p>Used in GDB. |
| </p> |
| </dd> |
| <dt>‘<samp>count</samp>’</dt> |
| <dd><p>‘<samp>-q</samp>’ in <code>who</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>count-links</samp>’</dt> |
| <dd><p>‘<samp>-l</samp>’ in <code>du</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>create</samp>’</dt> |
| <dd><p>Used in <code>tar</code> and <code>cpio</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>cut-mark</samp>’</dt> |
| <dd><p>‘<samp>-c</samp>’ in <code>shar</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>cxref</samp>’</dt> |
| <dd><p>‘<samp>-x</samp>’ in <code>ctags</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>date</samp>’</dt> |
| <dd><p>‘<samp>-d</samp>’ in <code>touch</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>debug</samp>’</dt> |
| <dd><p>‘<samp>-d</samp>’ in <code>make</code> and <code>m4</code>; |
| ‘<samp>-t</samp>’ in Bison. |
| </p> |
| </dd> |
| <dt>‘<samp>define</samp>’</dt> |
| <dd><p>‘<samp>-D</samp>’ in <code>m4</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>defines</samp>’</dt> |
| <dd><p>‘<samp>-d</samp>’ in Bison and <code>ctags</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>delete</samp>’</dt> |
| <dd><p>‘<samp>-D</samp>’ in <code>tar</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>dereference</samp>’</dt> |
| <dd><p>‘<samp>-L</samp>’ in <code>chgrp</code>, <code>chown</code>, <code>cpio</code>, <code>du</code>, |
| <code>ls</code>, and <code>tar</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>dereference-args</samp>’</dt> |
| <dd><p>‘<samp>-D</samp>’ in <code>du</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>device</samp>’</dt> |
| <dd><p>Specify an I/O device (special file name). |
| </p> |
| </dd> |
| <dt>‘<samp>diacritics</samp>’</dt> |
| <dd><p>‘<samp>-d</samp>’ in <code>recode</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>dictionary-order</samp>’</dt> |
| <dd><p>‘<samp>-d</samp>’ in <code>look</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>diff</samp>’</dt> |
| <dd><p>‘<samp>-d</samp>’ in <code>tar</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>digits</samp>’</dt> |
| <dd><p>‘<samp>-n</samp>’ in <code>csplit</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>directory</samp>’</dt> |
| <dd><p>Specify the directory to use, in various programs. In <code>ls</code>, it |
| means to show directories themselves rather than their contents. In |
| <code>rm</code> and <code>ln</code>, it means to not treat links to directories |
| specially. |
| </p> |
| </dd> |
| <dt>‘<samp>discard-all</samp>’</dt> |
| <dd><p>‘<samp>-x</samp>’ in <code>strip</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>discard-locals</samp>’</dt> |
| <dd><p>‘<samp>-X</samp>’ in <code>strip</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>dry-run</samp>’</dt> |
| <dd><p>‘<samp>-n</samp>’ in <code>make</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>ed</samp>’</dt> |
| <dd><p>‘<samp>-e</samp>’ in <code>diff</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>elide-empty-files</samp>’</dt> |
| <dd><p>‘<samp>-z</samp>’ in <code>csplit</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>end-delete</samp>’</dt> |
| <dd><p>‘<samp>-x</samp>’ in <code>wdiff</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>end-insert</samp>’</dt> |
| <dd><p>‘<samp>-z</samp>’ in <code>wdiff</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>entire-new-file</samp>’</dt> |
| <dd><p>‘<samp>-N</samp>’ in <code>diff</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>environment-overrides</samp>’</dt> |
| <dd><p>‘<samp>-e</samp>’ in <code>make</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>eof</samp>’</dt> |
| <dd><p>‘<samp>-e</samp>’ in <code>xargs</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>epoch</samp>’</dt> |
| <dd><p>Used in GDB. |
| </p> |
| </dd> |
| <dt>‘<samp>error-limit</samp>’</dt> |
| <dd><p>Used in <code>makeinfo</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>error-output</samp>’</dt> |
| <dd><p>‘<samp>-o</samp>’ in <code>m4</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>escape</samp>’</dt> |
| <dd><p>‘<samp>-b</samp>’ in <code>ls</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>exclude-from</samp>’</dt> |
| <dd><p>‘<samp>-X</samp>’ in <code>tar</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>exec</samp>’</dt> |
| <dd><p>Used in GDB. |
| </p> |
| </dd> |
| <dt>‘<samp>exit</samp>’</dt> |
| <dd><p>‘<samp>-x</samp>’ in <code>xargs</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>exit-0</samp>’</dt> |
| <dd><p>‘<samp>-e</samp>’ in <code>unshar</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>expand-tabs</samp>’</dt> |
| <dd><p>‘<samp>-t</samp>’ in <code>diff</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>expression</samp>’</dt> |
| <dd><p>‘<samp>-e</samp>’ in <code>sed</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>extern-only</samp>’</dt> |
| <dd><p>‘<samp>-g</samp>’ in <code>nm</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>extract</samp>’</dt> |
| <dd><p>‘<samp>-i</samp>’ in <code>cpio</code>; |
| ‘<samp>-x</samp>’ in <code>tar</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>faces</samp>’</dt> |
| <dd><p>‘<samp>-f</samp>’ in <code>finger</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>fast</samp>’</dt> |
| <dd><p>‘<samp>-f</samp>’ in <code>su</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>fatal-warnings</samp>’</dt> |
| <dd><p>‘<samp>-E</samp>’ in <code>m4</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>file</samp>’</dt> |
| <dd><p>‘<samp>-f</samp>’ in <code>gawk</code>, <code>info</code>, <code>make</code>, <code>mt</code>, |
| <code>sed</code>, and <code>tar</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>field-separator</samp>’</dt> |
| <dd><p>‘<samp>-F</samp>’ in <code>gawk</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>file-prefix</samp>’</dt> |
| <dd><p>‘<samp>-b</samp>’ in Bison. |
| </p> |
| </dd> |
| <dt>‘<samp>file-type</samp>’</dt> |
| <dd><p>‘<samp>-F</samp>’ in <code>ls</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>files-from</samp>’</dt> |
| <dd><p>‘<samp>-T</samp>’ in <code>tar</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>fill-column</samp>’</dt> |
| <dd><p>Used in <code>makeinfo</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>flag-truncation</samp>’</dt> |
| <dd><p>‘<samp>-F</samp>’ in <code>ptx</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>fixed-output-files</samp>’</dt> |
| <dd><p>‘<samp>-y</samp>’ in Bison. |
| </p> |
| </dd> |
| <dt>‘<samp>follow</samp>’</dt> |
| <dd><p>‘<samp>-f</samp>’ in <code>tail</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>footnote-style</samp>’</dt> |
| <dd><p>Used in <code>makeinfo</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>force</samp>’</dt> |
| <dd><p>‘<samp>-f</samp>’ in <code>cp</code>, <code>ln</code>, <code>mv</code>, and <code>rm</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>force-prefix</samp>’</dt> |
| <dd><p>‘<samp>-F</samp>’ in <code>shar</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>foreground</samp>’</dt> |
| <dd><p>For server programs, run in the foreground; |
| in other words, don’t do anything special to run the server |
| in the background. |
| </p> |
| </dd> |
| <dt>‘<samp>format</samp>’</dt> |
| <dd><p>Used in <code>ls</code>, <code>time</code>, and <code>ptx</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>freeze-state</samp>’</dt> |
| <dd><p>‘<samp>-F</samp>’ in <code>m4</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>fullname</samp>’</dt> |
| <dd><p>Used in GDB. |
| </p> |
| </dd> |
| <dt>‘<samp>gap-size</samp>’</dt> |
| <dd><p>‘<samp>-g</samp>’ in <code>ptx</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>get</samp>’</dt> |
| <dd><p>‘<samp>-x</samp>’ in <code>tar</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>graphic</samp>’</dt> |
| <dd><p>‘<samp>-i</samp>’ in <code>ul</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>graphics</samp>’</dt> |
| <dd><p>‘<samp>-g</samp>’ in <code>recode</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>group</samp>’</dt> |
| <dd><p>‘<samp>-g</samp>’ in <code>install</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>gzip</samp>’</dt> |
| <dd><p>‘<samp>-z</samp>’ in <code>tar</code> and <code>shar</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>hashsize</samp>’</dt> |
| <dd><p>‘<samp>-H</samp>’ in <code>m4</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>header</samp>’</dt> |
| <dd><p>‘<samp>-h</samp>’ in <code>objdump</code> and <code>recode</code> |
| </p> |
| </dd> |
| <dt>‘<samp>heading</samp>’</dt> |
| <dd><p>‘<samp>-H</samp>’ in <code>who</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>help</samp>’</dt> |
| <dd><p>Used to ask for brief usage information. |
| </p> |
| </dd> |
| <dt>‘<samp>here-delimiter</samp>’</dt> |
| <dd><p>‘<samp>-d</samp>’ in <code>shar</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>hide-control-chars</samp>’</dt> |
| <dd><p>‘<samp>-q</samp>’ in <code>ls</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>html</samp>’</dt> |
| <dd><p>In <code>makeinfo</code>, output HTML. |
| </p> |
| </dd> |
| <dt>‘<samp>idle</samp>’</dt> |
| <dd><p>‘<samp>-u</samp>’ in <code>who</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>ifdef</samp>’</dt> |
| <dd><p>‘<samp>-D</samp>’ in <code>diff</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>ignore</samp>’</dt> |
| <dd><p>‘<samp>-I</samp>’ in <code>ls</code>; |
| ‘<samp>-x</samp>’ in <code>recode</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>ignore-all-space</samp>’</dt> |
| <dd><p>‘<samp>-w</samp>’ in <code>diff</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>ignore-backups</samp>’</dt> |
| <dd><p>‘<samp>-B</samp>’ in <code>ls</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>ignore-blank-lines</samp>’</dt> |
| <dd><p>‘<samp>-B</samp>’ in <code>diff</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>ignore-case</samp>’</dt> |
| <dd><p>‘<samp>-f</samp>’ in <code>look</code> and <code>ptx</code>; |
| ‘<samp>-i</samp>’ in <code>diff</code> and <code>wdiff</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>ignore-errors</samp>’</dt> |
| <dd><p>‘<samp>-i</samp>’ in <code>make</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>ignore-file</samp>’</dt> |
| <dd><p>‘<samp>-i</samp>’ in <code>ptx</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>ignore-indentation</samp>’</dt> |
| <dd><p>‘<samp>-I</samp>’ in <code>etags</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>ignore-init-file</samp>’</dt> |
| <dd><p>‘<samp>-f</samp>’ in Oleo. |
| </p> |
| </dd> |
| <dt>‘<samp>ignore-interrupts</samp>’</dt> |
| <dd><p>‘<samp>-i</samp>’ in <code>tee</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>ignore-matching-lines</samp>’</dt> |
| <dd><p>‘<samp>-I</samp>’ in <code>diff</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>ignore-space-change</samp>’</dt> |
| <dd><p>‘<samp>-b</samp>’ in <code>diff</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>ignore-zeros</samp>’</dt> |
| <dd><p>‘<samp>-i</samp>’ in <code>tar</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>include</samp>’</dt> |
| <dd><p>‘<samp>-i</samp>’ in <code>etags</code>; |
| ‘<samp>-I</samp>’ in <code>m4</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>include-dir</samp>’</dt> |
| <dd><p>‘<samp>-I</samp>’ in <code>make</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>incremental</samp>’</dt> |
| <dd><p>‘<samp>-G</samp>’ in <code>tar</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>info</samp>’</dt> |
| <dd><p>‘<samp>-i</samp>’, ‘<samp>-l</samp>’, and ‘<samp>-m</samp>’ in Finger. |
| </p> |
| </dd> |
| <dt>‘<samp>init-file</samp>’</dt> |
| <dd><p>In some programs, specify the name of the file to read as the user’s |
| init file. |
| </p> |
| </dd> |
| <dt>‘<samp>initial</samp>’</dt> |
| <dd><p>‘<samp>-i</samp>’ in <code>expand</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>initial-tab</samp>’</dt> |
| <dd><p>‘<samp>-T</samp>’ in <code>diff</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>inode</samp>’</dt> |
| <dd><p>‘<samp>-i</samp>’ in <code>ls</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>interactive</samp>’</dt> |
| <dd><p>‘<samp>-i</samp>’ in <code>cp</code>, <code>ln</code>, <code>mv</code>, <code>rm</code>; |
| ‘<samp>-e</samp>’ in <code>m4</code>; |
| ‘<samp>-p</samp>’ in <code>xargs</code>; |
| ‘<samp>-w</samp>’ in <code>tar</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>intermix-type</samp>’</dt> |
| <dd><p>‘<samp>-p</samp>’ in <code>shar</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>iso-8601</samp>’</dt> |
| <dd><p>Used in <code>date</code> |
| </p> |
| </dd> |
| <dt>‘<samp>jobs</samp>’</dt> |
| <dd><p>‘<samp>-j</samp>’ in <code>make</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>just-print</samp>’</dt> |
| <dd><p>‘<samp>-n</samp>’ in <code>make</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>keep-going</samp>’</dt> |
| <dd><p>‘<samp>-k</samp>’ in <code>make</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>keep-files</samp>’</dt> |
| <dd><p>‘<samp>-k</samp>’ in <code>csplit</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>kilobytes</samp>’</dt> |
| <dd><p>‘<samp>-k</samp>’ in <code>du</code> and <code>ls</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>language</samp>’</dt> |
| <dd><p>‘<samp>-l</samp>’ in <code>etags</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>less-mode</samp>’</dt> |
| <dd><p>‘<samp>-l</samp>’ in <code>wdiff</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>level-for-gzip</samp>’</dt> |
| <dd><p>‘<samp>-g</samp>’ in <code>shar</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>line-bytes</samp>’</dt> |
| <dd><p>‘<samp>-C</samp>’ in <code>split</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>lines</samp>’</dt> |
| <dd><p>Used in <code>split</code>, <code>head</code>, and <code>tail</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>link</samp>’</dt> |
| <dd><p>‘<samp>-l</samp>’ in <code>cpio</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>lint</samp>’</dt> |
| <dt>‘<samp>lint-old</samp>’</dt> |
| <dd><p>Used in <code>gawk</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>list</samp>’</dt> |
| <dd><p>‘<samp>-t</samp>’ in <code>cpio</code>; |
| ‘<samp>-l</samp>’ in <code>recode</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>list</samp>’</dt> |
| <dd><p>‘<samp>-t</samp>’ in <code>tar</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>literal</samp>’</dt> |
| <dd><p>‘<samp>-N</samp>’ in <code>ls</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>load-average</samp>’</dt> |
| <dd><p>‘<samp>-l</samp>’ in <code>make</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>login</samp>’</dt> |
| <dd><p>Used in <code>su</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>machine</samp>’</dt> |
| <dd><p>Used in <code>uname</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>macro-name</samp>’</dt> |
| <dd><p>‘<samp>-M</samp>’ in <code>ptx</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>mail</samp>’</dt> |
| <dd><p>‘<samp>-m</samp>’ in <code>hello</code> and <code>uname</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>make-directories</samp>’</dt> |
| <dd><p>‘<samp>-d</samp>’ in <code>cpio</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>makefile</samp>’</dt> |
| <dd><p>‘<samp>-f</samp>’ in <code>make</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>mapped</samp>’</dt> |
| <dd><p>Used in GDB. |
| </p> |
| </dd> |
| <dt>‘<samp>max-args</samp>’</dt> |
| <dd><p>‘<samp>-n</samp>’ in <code>xargs</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>max-chars</samp>’</dt> |
| <dd><p>‘<samp>-n</samp>’ in <code>xargs</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>max-lines</samp>’</dt> |
| <dd><p>‘<samp>-l</samp>’ in <code>xargs</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>max-load</samp>’</dt> |
| <dd><p>‘<samp>-l</samp>’ in <code>make</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>max-procs</samp>’</dt> |
| <dd><p>‘<samp>-P</samp>’ in <code>xargs</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>mesg</samp>’</dt> |
| <dd><p>‘<samp>-T</samp>’ in <code>who</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>message</samp>’</dt> |
| <dd><p>‘<samp>-T</samp>’ in <code>who</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>minimal</samp>’</dt> |
| <dd><p>‘<samp>-d</samp>’ in <code>diff</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>mixed-uuencode</samp>’</dt> |
| <dd><p>‘<samp>-M</samp>’ in <code>shar</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>mode</samp>’</dt> |
| <dd><p>‘<samp>-m</samp>’ in <code>install</code>, <code>mkdir</code>, and <code>mkfifo</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>modification-time</samp>’</dt> |
| <dd><p>‘<samp>-m</samp>’ in <code>tar</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>multi-volume</samp>’</dt> |
| <dd><p>‘<samp>-M</samp>’ in <code>tar</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>name-prefix</samp>’</dt> |
| <dd><p>‘<samp>-a</samp>’ in Bison. |
| </p> |
| </dd> |
| <dt>‘<samp>nesting-limit</samp>’</dt> |
| <dd><p>‘<samp>-L</samp>’ in <code>m4</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>net-headers</samp>’</dt> |
| <dd><p>‘<samp>-a</samp>’ in <code>shar</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>new-file</samp>’</dt> |
| <dd><p>‘<samp>-W</samp>’ in <code>make</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>no-builtin-rules</samp>’</dt> |
| <dd><p>‘<samp>-r</samp>’ in <code>make</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>no-character-count</samp>’</dt> |
| <dd><p>‘<samp>-w</samp>’ in <code>shar</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>no-check-existing</samp>’</dt> |
| <dd><p>‘<samp>-x</samp>’ in <code>shar</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>no-common</samp>’</dt> |
| <dd><p>‘<samp>-3</samp>’ in <code>wdiff</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>no-create</samp>’</dt> |
| <dd><p>‘<samp>-c</samp>’ in <code>touch</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>no-defines</samp>’</dt> |
| <dd><p>‘<samp>-D</samp>’ in <code>etags</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>no-deleted</samp>’</dt> |
| <dd><p>‘<samp>-1</samp>’ in <code>wdiff</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>no-dereference</samp>’</dt> |
| <dd><p>‘<samp>-d</samp>’ in <code>cp</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>no-inserted</samp>’</dt> |
| <dd><p>‘<samp>-2</samp>’ in <code>wdiff</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>no-keep-going</samp>’</dt> |
| <dd><p>‘<samp>-S</samp>’ in <code>make</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>no-lines</samp>’</dt> |
| <dd><p>‘<samp>-l</samp>’ in Bison. |
| </p> |
| </dd> |
| <dt>‘<samp>no-piping</samp>’</dt> |
| <dd><p>‘<samp>-P</samp>’ in <code>shar</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>no-prof</samp>’</dt> |
| <dd><p>‘<samp>-e</samp>’ in <code>gprof</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>no-regex</samp>’</dt> |
| <dd><p>‘<samp>-R</samp>’ in <code>etags</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>no-sort</samp>’</dt> |
| <dd><p>‘<samp>-p</samp>’ in <code>nm</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>no-splash</samp>’</dt> |
| <dd><p>Don’t print a startup splash screen. |
| </p> |
| </dd> |
| <dt>‘<samp>no-split</samp>’</dt> |
| <dd><p>Used in <code>makeinfo</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>no-static</samp>’</dt> |
| <dd><p>‘<samp>-a</samp>’ in <code>gprof</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>no-time</samp>’</dt> |
| <dd><p>‘<samp>-E</samp>’ in <code>gprof</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>no-timestamp</samp>’</dt> |
| <dd><p>‘<samp>-m</samp>’ in <code>shar</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>no-validate</samp>’</dt> |
| <dd><p>Used in <code>makeinfo</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>no-wait</samp>’</dt> |
| <dd><p>Used in <code>emacsclient</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>no-warn</samp>’</dt> |
| <dd><p>Used in various programs to inhibit warnings. |
| </p> |
| </dd> |
| <dt>‘<samp>node</samp>’</dt> |
| <dd><p>‘<samp>-n</samp>’ in <code>info</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>nodename</samp>’</dt> |
| <dd><p>‘<samp>-n</samp>’ in <code>uname</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>nonmatching</samp>’</dt> |
| <dd><p>‘<samp>-f</samp>’ in <code>cpio</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>nstuff</samp>’</dt> |
| <dd><p>‘<samp>-n</samp>’ in <code>objdump</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>null</samp>’</dt> |
| <dd><p>‘<samp>-0</samp>’ in <code>xargs</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>number</samp>’</dt> |
| <dd><p>‘<samp>-n</samp>’ in <code>cat</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>number-nonblank</samp>’</dt> |
| <dd><p>‘<samp>-b</samp>’ in <code>cat</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>numeric-sort</samp>’</dt> |
| <dd><p>‘<samp>-n</samp>’ in <code>nm</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>numeric-uid-gid</samp>’</dt> |
| <dd><p>‘<samp>-n</samp>’ in <code>cpio</code> and <code>ls</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>nx</samp>’</dt> |
| <dd><p>Used in GDB. |
| </p> |
| </dd> |
| <dt>‘<samp>old-archive</samp>’</dt> |
| <dd><p>‘<samp>-o</samp>’ in <code>tar</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>old-file</samp>’</dt> |
| <dd><p>‘<samp>-o</samp>’ in <code>make</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>one-file-system</samp>’</dt> |
| <dd><p>‘<samp>-l</samp>’ in <code>tar</code>, <code>cp</code>, and <code>du</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>only-file</samp>’</dt> |
| <dd><p>‘<samp>-o</samp>’ in <code>ptx</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>only-prof</samp>’</dt> |
| <dd><p>‘<samp>-f</samp>’ in <code>gprof</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>only-time</samp>’</dt> |
| <dd><p>‘<samp>-F</samp>’ in <code>gprof</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>options</samp>’</dt> |
| <dd><p>‘<samp>-o</samp>’ in <code>getopt</code>, <code>fdlist</code>, <code>fdmount</code>, |
| <code>fdmountd</code>, and <code>fdumount</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>output</samp>’</dt> |
| <dd><p>In various programs, specify the output file name. |
| </p> |
| </dd> |
| <dt>‘<samp>output-prefix</samp>’</dt> |
| <dd><p>‘<samp>-o</samp>’ in <code>shar</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>override</samp>’</dt> |
| <dd><p>‘<samp>-o</samp>’ in <code>rm</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>overwrite</samp>’</dt> |
| <dd><p>‘<samp>-c</samp>’ in <code>unshar</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>owner</samp>’</dt> |
| <dd><p>‘<samp>-o</samp>’ in <code>install</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>paginate</samp>’</dt> |
| <dd><p>‘<samp>-l</samp>’ in <code>diff</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>paragraph-indent</samp>’</dt> |
| <dd><p>Used in <code>makeinfo</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>parents</samp>’</dt> |
| <dd><p>‘<samp>-p</samp>’ in <code>mkdir</code> and <code>rmdir</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>pass-all</samp>’</dt> |
| <dd><p>‘<samp>-p</samp>’ in <code>ul</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>pass-through</samp>’</dt> |
| <dd><p>‘<samp>-p</samp>’ in <code>cpio</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>port</samp>’</dt> |
| <dd><p>‘<samp>-P</samp>’ in <code>finger</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>portability</samp>’</dt> |
| <dd><p>‘<samp>-c</samp>’ in <code>cpio</code> and <code>tar</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>posix</samp>’</dt> |
| <dd><p>Used in <code>gawk</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>prefix-builtins</samp>’</dt> |
| <dd><p>‘<samp>-P</samp>’ in <code>m4</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>prefix</samp>’</dt> |
| <dd><p>‘<samp>-f</samp>’ in <code>csplit</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>preserve</samp>’</dt> |
| <dd><p>Used in <code>tar</code> and <code>cp</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>preserve-environment</samp>’</dt> |
| <dd><p>‘<samp>-p</samp>’ in <code>su</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>preserve-modification-time</samp>’</dt> |
| <dd><p>‘<samp>-m</samp>’ in <code>cpio</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>preserve-order</samp>’</dt> |
| <dd><p>‘<samp>-s</samp>’ in <code>tar</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>preserve-permissions</samp>’</dt> |
| <dd><p>‘<samp>-p</samp>’ in <code>tar</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>print</samp>’</dt> |
| <dd><p>‘<samp>-l</samp>’ in <code>diff</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>print-chars</samp>’</dt> |
| <dd><p>‘<samp>-L</samp>’ in <code>cmp</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>print-data-base</samp>’</dt> |
| <dd><p>‘<samp>-p</samp>’ in <code>make</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>print-directory</samp>’</dt> |
| <dd><p>‘<samp>-w</samp>’ in <code>make</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>print-file-name</samp>’</dt> |
| <dd><p>‘<samp>-o</samp>’ in <code>nm</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>print-symdefs</samp>’</dt> |
| <dd><p>‘<samp>-s</samp>’ in <code>nm</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>printer</samp>’</dt> |
| <dd><p>‘<samp>-p</samp>’ in <code>wdiff</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>prompt</samp>’</dt> |
| <dd><p>‘<samp>-p</samp>’ in <code>ed</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>proxy</samp>’</dt> |
| <dd><p>Specify an HTTP proxy. |
| </p> |
| </dd> |
| <dt>‘<samp>query-user</samp>’</dt> |
| <dd><p>‘<samp>-X</samp>’ in <code>shar</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>question</samp>’</dt> |
| <dd><p>‘<samp>-q</samp>’ in <code>make</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>quiet</samp>’</dt> |
| <dd><p>Used in many programs to inhibit the usual output. Every |
| program accepting ‘<samp>--quiet</samp>’ should accept ‘<samp>--silent</samp>’ as a |
| synonym. |
| </p> |
| </dd> |
| <dt>‘<samp>quiet-unshar</samp>’</dt> |
| <dd><p>‘<samp>-Q</samp>’ in <code>shar</code> |
| </p> |
| </dd> |
| <dt>‘<samp>quote-name</samp>’</dt> |
| <dd><p>‘<samp>-Q</samp>’ in <code>ls</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>rcs</samp>’</dt> |
| <dd><p>‘<samp>-n</samp>’ in <code>diff</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>re-interval</samp>’</dt> |
| <dd><p>Used in <code>gawk</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>read-full-blocks</samp>’</dt> |
| <dd><p>‘<samp>-B</samp>’ in <code>tar</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>readnow</samp>’</dt> |
| <dd><p>Used in GDB. |
| </p> |
| </dd> |
| <dt>‘<samp>recon</samp>’</dt> |
| <dd><p>‘<samp>-n</samp>’ in <code>make</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>record-number</samp>’</dt> |
| <dd><p>‘<samp>-R</samp>’ in <code>tar</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>recursive</samp>’</dt> |
| <dd><p>Used in <code>chgrp</code>, <code>chown</code>, <code>cp</code>, <code>ls</code>, <code>diff</code>, |
| and <code>rm</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>reference</samp>’</dt> |
| <dd><p>‘<samp>-r</samp>’ in <code>touch</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>references</samp>’</dt> |
| <dd><p>‘<samp>-r</samp>’ in <code>ptx</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>regex</samp>’</dt> |
| <dd><p>‘<samp>-r</samp>’ in <code>tac</code> and <code>etags</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>release</samp>’</dt> |
| <dd><p>‘<samp>-r</samp>’ in <code>uname</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>reload-state</samp>’</dt> |
| <dd><p>‘<samp>-R</samp>’ in <code>m4</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>relocation</samp>’</dt> |
| <dd><p>‘<samp>-r</samp>’ in <code>objdump</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>rename</samp>’</dt> |
| <dd><p>‘<samp>-r</samp>’ in <code>cpio</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>replace</samp>’</dt> |
| <dd><p>‘<samp>-i</samp>’ in <code>xargs</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>report-identical-files</samp>’</dt> |
| <dd><p>‘<samp>-s</samp>’ in <code>diff</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>reset-access-time</samp>’</dt> |
| <dd><p>‘<samp>-a</samp>’ in <code>cpio</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>reverse</samp>’</dt> |
| <dd><p>‘<samp>-r</samp>’ in <code>ls</code> and <code>nm</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>reversed-ed</samp>’</dt> |
| <dd><p>‘<samp>-f</samp>’ in <code>diff</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>right-side-defs</samp>’</dt> |
| <dd><p>‘<samp>-R</samp>’ in <code>ptx</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>same-order</samp>’</dt> |
| <dd><p>‘<samp>-s</samp>’ in <code>tar</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>same-permissions</samp>’</dt> |
| <dd><p>‘<samp>-p</samp>’ in <code>tar</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>save</samp>’</dt> |
| <dd><p>‘<samp>-g</samp>’ in <code>stty</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>se</samp>’</dt> |
| <dd><p>Used in GDB. |
| </p> |
| </dd> |
| <dt>‘<samp>sentence-regexp</samp>’</dt> |
| <dd><p>‘<samp>-S</samp>’ in <code>ptx</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>separate-dirs</samp>’</dt> |
| <dd><p>‘<samp>-S</samp>’ in <code>du</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>separator</samp>’</dt> |
| <dd><p>‘<samp>-s</samp>’ in <code>tac</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>sequence</samp>’</dt> |
| <dd><p>Used by <code>recode</code> to chose files or pipes for sequencing passes. |
| </p> |
| </dd> |
| <dt>‘<samp>shell</samp>’</dt> |
| <dd><p>‘<samp>-s</samp>’ in <code>su</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>show-all</samp>’</dt> |
| <dd><p>‘<samp>-A</samp>’ in <code>cat</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>show-c-function</samp>’</dt> |
| <dd><p>‘<samp>-p</samp>’ in <code>diff</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>show-ends</samp>’</dt> |
| <dd><p>‘<samp>-E</samp>’ in <code>cat</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>show-function-line</samp>’</dt> |
| <dd><p>‘<samp>-F</samp>’ in <code>diff</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>show-tabs</samp>’</dt> |
| <dd><p>‘<samp>-T</samp>’ in <code>cat</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>silent</samp>’</dt> |
| <dd><p>Used in many programs to inhibit the usual output. |
| Every program accepting |
| ‘<samp>--silent</samp>’ should accept ‘<samp>--quiet</samp>’ as a synonym. |
| </p> |
| </dd> |
| <dt>‘<samp>size</samp>’</dt> |
| <dd><p>‘<samp>-s</samp>’ in <code>ls</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>socket</samp>’</dt> |
| <dd><p>Specify a file descriptor for a network server to use for its socket, |
| instead of opening and binding a new socket. This provides a way to |
| run, in a non-privileged process, a server that normally needs a |
| reserved port number. |
| </p> |
| </dd> |
| <dt>‘<samp>sort</samp>’</dt> |
| <dd><p>Used in <code>ls</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>source</samp>’</dt> |
| <dd><p>‘<samp>-W source</samp>’ in <code>gawk</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>sparse</samp>’</dt> |
| <dd><p>‘<samp>-S</samp>’ in <code>tar</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>speed-large-files</samp>’</dt> |
| <dd><p>‘<samp>-H</samp>’ in <code>diff</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>split-at</samp>’</dt> |
| <dd><p>‘<samp>-E</samp>’ in <code>unshar</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>split-size-limit</samp>’</dt> |
| <dd><p>‘<samp>-L</samp>’ in <code>shar</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>squeeze-blank</samp>’</dt> |
| <dd><p>‘<samp>-s</samp>’ in <code>cat</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>start-delete</samp>’</dt> |
| <dd><p>‘<samp>-w</samp>’ in <code>wdiff</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>start-insert</samp>’</dt> |
| <dd><p>‘<samp>-y</samp>’ in <code>wdiff</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>starting-file</samp>’</dt> |
| <dd><p>Used in <code>tar</code> and <code>diff</code> to specify which file within |
| a directory to start processing with. |
| </p> |
| </dd> |
| <dt>‘<samp>statistics</samp>’</dt> |
| <dd><p>‘<samp>-s</samp>’ in <code>wdiff</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>stdin-file-list</samp>’</dt> |
| <dd><p>‘<samp>-S</samp>’ in <code>shar</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>stop</samp>’</dt> |
| <dd><p>‘<samp>-S</samp>’ in <code>make</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>strict</samp>’</dt> |
| <dd><p>‘<samp>-s</samp>’ in <code>recode</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>strip</samp>’</dt> |
| <dd><p>‘<samp>-s</samp>’ in <code>install</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>strip-all</samp>’</dt> |
| <dd><p>‘<samp>-s</samp>’ in <code>strip</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>strip-debug</samp>’</dt> |
| <dd><p>‘<samp>-S</samp>’ in <code>strip</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>submitter</samp>’</dt> |
| <dd><p>‘<samp>-s</samp>’ in <code>shar</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>suffix</samp>’</dt> |
| <dd><p>‘<samp>-S</samp>’ in <code>cp</code>, <code>ln</code>, <code>mv</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>suffix-format</samp>’</dt> |
| <dd><p>‘<samp>-b</samp>’ in <code>csplit</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>sum</samp>’</dt> |
| <dd><p>‘<samp>-s</samp>’ in <code>gprof</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>summarize</samp>’</dt> |
| <dd><p>‘<samp>-s</samp>’ in <code>du</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>symbolic</samp>’</dt> |
| <dd><p>‘<samp>-s</samp>’ in <code>ln</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>symbols</samp>’</dt> |
| <dd><p>Used in GDB and <code>objdump</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>synclines</samp>’</dt> |
| <dd><p>‘<samp>-s</samp>’ in <code>m4</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>sysname</samp>’</dt> |
| <dd><p>‘<samp>-s</samp>’ in <code>uname</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>tabs</samp>’</dt> |
| <dd><p>‘<samp>-t</samp>’ in <code>expand</code> and <code>unexpand</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>tabsize</samp>’</dt> |
| <dd><p>‘<samp>-T</samp>’ in <code>ls</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>terminal</samp>’</dt> |
| <dd><p>‘<samp>-T</samp>’ in <code>tput</code> and <code>ul</code>. |
| ‘<samp>-t</samp>’ in <code>wdiff</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>text</samp>’</dt> |
| <dd><p>‘<samp>-a</samp>’ in <code>diff</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>text-files</samp>’</dt> |
| <dd><p>‘<samp>-T</samp>’ in <code>shar</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>time</samp>’</dt> |
| <dd><p>Used in <code>ls</code> and <code>touch</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>timeout</samp>’</dt> |
| <dd><p>Specify how long to wait before giving up on some operation. |
| </p> |
| </dd> |
| <dt>‘<samp>to-stdout</samp>’</dt> |
| <dd><p>‘<samp>-O</samp>’ in <code>tar</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>total</samp>’</dt> |
| <dd><p>‘<samp>-c</samp>’ in <code>du</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>touch</samp>’</dt> |
| <dd><p>‘<samp>-t</samp>’ in <code>make</code>, <code>ranlib</code>, and <code>recode</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>trace</samp>’</dt> |
| <dd><p>‘<samp>-t</samp>’ in <code>m4</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>traditional</samp>’</dt> |
| <dd><p>‘<samp>-t</samp>’ in <code>hello</code>; |
| ‘<samp>-W traditional</samp>’ in <code>gawk</code>; |
| ‘<samp>-G</samp>’ in <code>ed</code>, <code>m4</code>, and <code>ptx</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>tty</samp>’</dt> |
| <dd><p>Used in GDB. |
| </p> |
| </dd> |
| <dt>‘<samp>typedefs</samp>’</dt> |
| <dd><p>‘<samp>-t</samp>’ in <code>ctags</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>typedefs-and-c++</samp>’</dt> |
| <dd><p>‘<samp>-T</samp>’ in <code>ctags</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>typeset-mode</samp>’</dt> |
| <dd><p>‘<samp>-t</samp>’ in <code>ptx</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>uncompress</samp>’</dt> |
| <dd><p>‘<samp>-z</samp>’ in <code>tar</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>unconditional</samp>’</dt> |
| <dd><p>‘<samp>-u</samp>’ in <code>cpio</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>undefine</samp>’</dt> |
| <dd><p>‘<samp>-U</samp>’ in <code>m4</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>undefined-only</samp>’</dt> |
| <dd><p>‘<samp>-u</samp>’ in <code>nm</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>update</samp>’</dt> |
| <dd><p>‘<samp>-u</samp>’ in <code>cp</code>, <code>ctags</code>, <code>mv</code>, <code>tar</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>usage</samp>’</dt> |
| <dd><p>Used in <code>gawk</code>; same as ‘<samp>--help</samp>’. |
| </p> |
| </dd> |
| <dt>‘<samp>uuencode</samp>’</dt> |
| <dd><p>‘<samp>-B</samp>’ in <code>shar</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>vanilla-operation</samp>’</dt> |
| <dd><p>‘<samp>-V</samp>’ in <code>shar</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>verbose</samp>’</dt> |
| <dd><p>Print more information about progress. Many programs support this. |
| </p> |
| </dd> |
| <dt>‘<samp>verify</samp>’</dt> |
| <dd><p>‘<samp>-W</samp>’ in <code>tar</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>version</samp>’</dt> |
| <dd><p>Print the version number. |
| </p> |
| </dd> |
| <dt>‘<samp>version-control</samp>’</dt> |
| <dd><p>‘<samp>-V</samp>’ in <code>cp</code>, <code>ln</code>, <code>mv</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>vgrind</samp>’</dt> |
| <dd><p>‘<samp>-v</samp>’ in <code>ctags</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>volume</samp>’</dt> |
| <dd><p>‘<samp>-V</samp>’ in <code>tar</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>what-if</samp>’</dt> |
| <dd><p>‘<samp>-W</samp>’ in <code>make</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>whole-size-limit</samp>’</dt> |
| <dd><p>‘<samp>-l</samp>’ in <code>shar</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>width</samp>’</dt> |
| <dd><p>‘<samp>-w</samp>’ in <code>ls</code> and <code>ptx</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>word-regexp</samp>’</dt> |
| <dd><p>‘<samp>-W</samp>’ in <code>ptx</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>writable</samp>’</dt> |
| <dd><p>‘<samp>-T</samp>’ in <code>who</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>zeros</samp>’</dt> |
| <dd><p>‘<samp>-z</samp>’ in <code>gprof</code>. |
| </p></dd> |
| </dl> |
| |
| <hr> |
| <a name="OID-Allocations"></a> |
| <div class="header"> |
| <p> |
| Next: <a href="#Memory-Usage" accesskey="n" rel="next">Memory Usage</a>, Previous: <a href="#Option-Table" accesskey="p" rel="prev">Option Table</a>, Up: <a href="#Program-Behavior" accesskey="u" rel="up">Program Behavior</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p> |
| </div> |
| <a name="OID-Allocations-1"></a> |
| <h3 class="section">4.9 OID Allocations</h3> |
| <a name="index-OID-allocations-for-GNU"></a> |
| <a name="index-SNMP"></a> |
| <a name="index-LDAP"></a> |
| <a name="index-X_002e509"></a> |
| |
| <p>The OID (object identifier) 1.3.6.1.4.1.11591 has been assigned to the |
| GNU Project (thanks to Werner Koch). These are used for SNMP, LDAP, |
| X.509 certificates, and so on. The web site |
| <a href="http://www.alvestrand.no/objectid">http://www.alvestrand.no/objectid</a> has a (voluntary) listing of |
| many OID assignments. |
| </p> |
| <p>If you need a new slot for your GNU package, write |
| <a href="mailto:maintainers@gnu.org">maintainers@gnu.org</a>. Here is a list of arcs currently |
| assigned: |
| </p> |
| <div class="example"> |
| <pre class="example"> |
| 1.3.6.1.4.1.11591 GNU |
| |
| 1.3.6.1.4.1.11591.1 GNU Radius |
| |
| 1.3.6.1.4.1.11591.2 GnuPG |
| 1.3.6.1.4.1.11591.2.1 notation |
| 1.3.6.1.4.1.11591.2.1.1 pkaAddress |
| |
| 1.3.6.1.4.1.11591.3 GNU Radar |
| |
| 1.3.6.1.4.1.11591.4 GNU GSS |
| |
| 1.3.6.1.4.1.11591.5 GNU Mailutils |
| |
| 1.3.6.1.4.1.11591.6 GNU Shishi |
| |
| 1.3.6.1.4.1.11591.7 GNU Radio |
| |
| 1.3.6.1.4.1.11591.12 digestAlgorithm |
| 1.3.6.1.4.1.11591.12.2 TIGER/192 |
| 1.3.6.1.4.1.11591.13 encryptionAlgorithm |
| 1.3.6.1.4.1.11591.13.2 Serpent |
| 1.3.6.1.4.1.11591.13.2.1 Serpent-128-ECB |
| 1.3.6.1.4.1.11591.13.2.2 Serpent-128-CBC |
| 1.3.6.1.4.1.11591.13.2.3 Serpent-128-OFB |
| 1.3.6.1.4.1.11591.13.2.4 Serpent-128-CFB |
| 1.3.6.1.4.1.11591.13.2.21 Serpent-192-ECB |
| 1.3.6.1.4.1.11591.13.2.22 Serpent-192-CBC |
| 1.3.6.1.4.1.11591.13.2.23 Serpent-192-OFB |
| 1.3.6.1.4.1.11591.13.2.24 Serpent-192-CFB |
| 1.3.6.1.4.1.11591.13.2.41 Serpent-256-ECB |
| 1.3.6.1.4.1.11591.13.2.42 Serpent-256-CBC |
| 1.3.6.1.4.1.11591.13.2.43 Serpent-256-OFB |
| 1.3.6.1.4.1.11591.13.2.44 Serpent-256-CFB |
| 1.3.6.1.4.1.11591.14 CRC algorithms |
| 1.3.6.1.4.1.11591.14.1 CRC 32 |
| </pre></div> |
| |
| |
| <hr> |
| <a name="Memory-Usage"></a> |
| <div class="header"> |
| <p> |
| Next: <a href="#File-Usage" accesskey="n" rel="next">File Usage</a>, Previous: <a href="#OID-Allocations" accesskey="p" rel="prev">OID Allocations</a>, Up: <a href="#Program-Behavior" accesskey="u" rel="up">Program Behavior</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p> |
| </div> |
| <a name="Memory-Usage-1"></a> |
| <h3 class="section">4.10 Memory Usage</h3> |
| <a name="index-memory-usage"></a> |
| |
| <p>If a program typically uses just a few meg of memory, don’t bother making any |
| effort to reduce memory usage. For example, if it is impractical for |
| other reasons to operate on files more than a few meg long, it is |
| reasonable to read entire input files into memory to operate on them. |
| </p> |
| <p>However, for programs such as <code>cat</code> or <code>tail</code>, that can |
| usefully operate on very large files, it is important to avoid using a |
| technique that would artificially limit the size of files it can handle. |
| If a program works by lines and could be applied to arbitrary |
| user-supplied input files, it should keep only a line in memory, because |
| this is not very hard and users will want to be able to operate on input |
| files that are bigger than will fit in memory all at once. |
| </p> |
| <p>If your program creates complicated data structures, just make them in |
| memory and give a fatal error if <code>malloc</code> returns zero. |
| </p> |
| <hr> |
| <a name="File-Usage"></a> |
| <div class="header"> |
| <p> |
| Previous: <a href="#Memory-Usage" accesskey="p" rel="prev">Memory Usage</a>, Up: <a href="#Program-Behavior" accesskey="u" rel="up">Program Behavior</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p> |
| </div> |
| <a name="File-Usage-1"></a> |
| <h3 class="section">4.11 File Usage</h3> |
| <a name="index-file-usage"></a> |
| |
| <p>Programs should be prepared to operate when <samp>/usr</samp> and <samp>/etc</samp> |
| are read-only file systems. Thus, if the program manages log files, |
| lock files, backup files, score files, or any other files which are |
| modified for internal purposes, these files should not be stored in |
| <samp>/usr</samp> or <samp>/etc</samp>. |
| </p> |
| <p>There are two exceptions. <samp>/etc</samp> is used to store system |
| configuration information; it is reasonable for a program to modify |
| files in <samp>/etc</samp> when its job is to update the system configuration. |
| Also, if the user explicitly asks to modify one file in a directory, it |
| is reasonable for the program to store other files in the same |
| directory. |
| </p> |
| <hr> |
| <a name="Writing-C"></a> |
| <div class="header"> |
| <p> |
| Next: <a href="#Documentation" accesskey="n" rel="next">Documentation</a>, Previous: <a href="#Program-Behavior" accesskey="p" rel="prev">Program Behavior</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p> |
| </div> |
| <a name="Making-The-Best-Use-of-C"></a> |
| <h2 class="chapter">5 Making The Best Use of C</h2> |
| |
| <p>This chapter provides advice on how best to use the C language |
| when writing GNU software. |
| </p> |
| <table class="menu" border="0" cellspacing="0"> |
| <tr><td align="left" valign="top">• <a href="#Formatting" accesskey="1">Formatting</a>:</td><td> </td><td align="left" valign="top">Formatting your source code. |
| </td></tr> |
| <tr><td align="left" valign="top">• <a href="#Comments" accesskey="2">Comments</a>:</td><td> </td><td align="left" valign="top">Commenting your work. |
| </td></tr> |
| <tr><td align="left" valign="top">• <a href="#Syntactic-Conventions" accesskey="3">Syntactic Conventions</a>:</td><td> </td><td align="left" valign="top">Clean use of C constructs. |
| </td></tr> |
| <tr><td align="left" valign="top">• <a href="#Names" accesskey="4">Names</a>:</td><td> </td><td align="left" valign="top">Naming variables, functions, and files. |
| </td></tr> |
| <tr><td align="left" valign="top">• <a href="#System-Portability" accesskey="5">System Portability</a>:</td><td> </td><td align="left" valign="top">Portability among different operating systems. |
| </td></tr> |
| <tr><td align="left" valign="top">• <a href="#CPU-Portability" accesskey="6">CPU Portability</a>:</td><td> </td><td align="left" valign="top">Supporting the range of CPU types. |
| </td></tr> |
| <tr><td align="left" valign="top">• <a href="#System-Functions" accesskey="7">System Functions</a>:</td><td> </td><td align="left" valign="top">Portability and “standard” library functions. |
| </td></tr> |
| <tr><td align="left" valign="top">• <a href="#Internationalization" accesskey="8">Internationalization</a>:</td><td> </td><td align="left" valign="top">Techniques for internationalization. |
| </td></tr> |
| <tr><td align="left" valign="top">• <a href="#Character-Set" accesskey="9">Character Set</a>:</td><td> </td><td align="left" valign="top">Use ASCII by default. |
| </td></tr> |
| <tr><td align="left" valign="top">• <a href="#Quote-Characters">Quote Characters</a>:</td><td> </td><td align="left" valign="top">Use ‘...’ in the C locale. |
| </td></tr> |
| <tr><td align="left" valign="top">• <a href="#Mmap">Mmap</a>:</td><td> </td><td align="left" valign="top">How you can safely use <code>mmap</code>. |
| </td></tr> |
| </table> |
| |
| <hr> |
| <a name="Formatting"></a> |
| <div class="header"> |
| <p> |
| Next: <a href="#Comments" accesskey="n" rel="next">Comments</a>, Up: <a href="#Writing-C" accesskey="u" rel="up">Writing C</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p> |
| </div> |
| <a name="Formatting-Your-Source-Code"></a> |
| <h3 class="section">5.1 Formatting Your Source Code</h3> |
| <a name="index-formatting-source-code"></a> |
| |
| <a name="index-open-brace"></a> |
| <a name="index-braces_002c-in-C-source"></a> |
| <p>It is important to put the open-brace that starts the body of a C |
| function in column one, so that they will start a defun. Several |
| tools look for open-braces in column one to find the beginnings of C |
| functions. These tools will not work on code not formatted that way. |
| </p> |
| <p>Avoid putting open-brace, open-parenthesis or open-bracket in column |
| one when they are inside a function, so that they won’t start a defun. |
| The open-brace that starts a <code>struct</code> body can go in column one |
| if you find it useful to treat that definition as a defun. |
| </p> |
| <p>It is also important for function definitions to start the name of the |
| function in column one. This helps people to search for function |
| definitions, and may also help certain tools recognize them. Thus, |
| using Standard C syntax, the format is this: |
| </p> |
| <div class="example"> |
| <pre class="example">static char * |
| concat (char *s1, char *s2) |
| { |
| … |
| } |
| </pre></div> |
| |
| <p>or, if you want to use traditional C syntax, format the definition like |
| this: |
| </p> |
| <div class="example"> |
| <pre class="example">static char * |
| concat (s1, s2) /* Name starts in column one here */ |
| char *s1, *s2; |
| { /* Open brace in column one here */ |
| … |
| } |
| </pre></div> |
| |
| <p>In Standard C, if the arguments don’t fit nicely on one line, |
| split it like this: |
| </p> |
| <div class="example"> |
| <pre class="example">int |
| lots_of_args (int an_integer, long a_long, short a_short, |
| double a_double, float a_float) |
| … |
| </pre></div> |
| |
| <p>The rest of this section gives our recommendations for other aspects of |
| C formatting style, which is also the default style of the <code>indent</code> |
| program in version 1.2 and newer. It corresponds to the options |
| </p> |
| <div class="smallexample"> |
| <pre class="smallexample">-nbad -bap -nbc -bbo -bl -bli2 -bls -ncdb -nce -cp1 -cs -di2 |
| -ndj -nfc1 -nfca -hnl -i2 -ip5 -lp -pcs -psl -nsc -nsob |
| </pre></div> |
| |
| <p>We don’t think of these recommendations as requirements, because it |
| causes no problems for users if two different programs have different |
| formatting styles. |
| </p> |
| <p>But whatever style you use, please use it consistently, since a mixture |
| of styles within one program tends to look ugly. If you are |
| contributing changes to an existing program, please follow the style of |
| that program. |
| </p> |
| <p>For the body of the function, our recommended style looks like this: |
| </p> |
| <div class="example"> |
| <pre class="example">if (x < foo (y, z)) |
| haha = bar[4] + 5; |
| else |
| { |
| while (z) |
| { |
| haha += foo (z, z); |
| z--; |
| } |
| return ++x + bar (); |
| } |
| </pre></div> |
| |
| <a name="index-spaces-before-open_002dparen"></a> |
| <p>We find it easier to read a program when it has spaces before the |
| open-parentheses and after the commas. Especially after the commas. |
| </p> |
| <p>When you split an expression into multiple lines, split it |
| before an operator, not after one. Here is the right way: |
| </p> |
| <a name="index-expressions_002c-splitting"></a> |
| <div class="example"> |
| <pre class="example">if (foo_this_is_long && bar > win (x, y, z) |
| && remaining_condition) |
| </pre></div> |
| |
| <p>Try to avoid having two operators of different precedence at the same |
| level of indentation. For example, don’t write this: |
| </p> |
| <div class="example"> |
| <pre class="example">mode = (inmode[j] == VOIDmode |
| || GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j]) |
| ? outmode[j] : inmode[j]); |
| </pre></div> |
| |
| <p>Instead, use extra parentheses so that the indentation shows the nesting: |
| </p> |
| <div class="example"> |
| <pre class="example">mode = ((inmode[j] == VOIDmode |
| || (GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j]))) |
| ? outmode[j] : inmode[j]); |
| </pre></div> |
| |
| <p>Insert extra parentheses so that Emacs will indent the code properly. |
| For example, the following indentation looks nice if you do it by hand, |
| </p> |
| <div class="example"> |
| <pre class="example">v = rup->ru_utime.tv_sec*1000 + rup->ru_utime.tv_usec/1000 |
| + rup->ru_stime.tv_sec*1000 + rup->ru_stime.tv_usec/1000; |
| </pre></div> |
| |
| <p>but Emacs would alter it. Adding a set of parentheses produces |
| something that looks equally nice, and which Emacs will preserve: |
| </p> |
| <div class="example"> |
| <pre class="example">v = (rup->ru_utime.tv_sec*1000 + rup->ru_utime.tv_usec/1000 |
| + rup->ru_stime.tv_sec*1000 + rup->ru_stime.tv_usec/1000); |
| </pre></div> |
| |
| <p>Format do-while statements like this: |
| </p> |
| <div class="example"> |
| <pre class="example">do |
| { |
| a = foo (a); |
| } |
| while (a > 0); |
| </pre></div> |
| |
| <a name="index-formfeed"></a> |
| <a name="index-control_002dL"></a> |
| <p>Please use formfeed characters (control-L) to divide the program into |
| pages at logical places (but not within a function). It does not matter |
| just how long the pages are, since they do not have to fit on a printed |
| page. The formfeeds should appear alone on lines by themselves. |
| </p> |
| <hr> |
| <a name="Comments"></a> |
| <div class="header"> |
| <p> |
| Next: <a href="#Syntactic-Conventions" accesskey="n" rel="next">Syntactic Conventions</a>, Previous: <a href="#Formatting" accesskey="p" rel="prev">Formatting</a>, Up: <a href="#Writing-C" accesskey="u" rel="up">Writing C</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p> |
| </div> |
| <a name="Commenting-Your-Work"></a> |
| <h3 class="section">5.2 Commenting Your Work</h3> |
| <a name="index-commenting"></a> |
| |
| <p>Every program should start with a comment saying briefly what it is for. |
| Example: ‘<samp>fmt - filter for simple filling of text</samp>’. This comment |
| should be at the top of the source file containing the ‘<samp>main</samp>’ |
| function of the program. |
| </p> |
| <p>Also, please write a brief comment at the start of each source file, |
| with the file name and a line or two about the overall purpose of the |
| file. |
| </p> |
| <p>Please write the comments in a GNU program in English, because English |
| is the one language that nearly all programmers in all countries can |
| read. If you do not write English well, please write comments in |
| English as well as you can, then ask other people to help rewrite them. |
| If you can’t write comments in English, please find someone to work with |
| you and translate your comments into English. |
| </p> |
| <p>Please put a comment on each function saying what the function does, |
| what sorts of arguments it gets, and what the possible values of |
| arguments mean and are used for. It is not necessary to duplicate in |
| words the meaning of the C argument declarations, if a C type is being |
| used in its customary fashion. If there is anything nonstandard about |
| its use (such as an argument of type <code>char *</code> which is really the |
| address of the second character of a string, not the first), or any |
| possible values that would not work the way one would expect (such as, |
| that strings containing newlines are not guaranteed to work), be sure |
| to say so. |
| </p> |
| <p>Also explain the significance of the return value, if there is one. |
| </p> |
| <p>Please put two spaces after the end of a sentence in your comments, so |
| that the Emacs sentence commands will work. Also, please write |
| complete sentences and capitalize the first word. If a lower-case |
| identifier comes at the beginning of a sentence, don’t capitalize it! |
| Changing the spelling makes it a different identifier. If you don’t |
| like starting a sentence with a lower case letter, write the sentence |
| differently (e.g., “The identifier lower-case is …”). |
| </p> |
| <p>The comment on a function is much clearer if you use the argument |
| names to speak about the argument values. The variable name itself |
| should be lower case, but write it in upper case when you are speaking |
| about the value rather than the variable itself. Thus, “the inode |
| number NODE_NUM” rather than “an inode”. |
| </p> |
| <p>There is usually no purpose in restating the name of the function in |
| the comment before it, because the reader can see that for himself. |
| There might be an exception when the comment is so long that the function |
| itself would be off the bottom of the screen. |
| </p> |
| <p>There should be a comment on each static variable as well, like this: |
| </p> |
| <div class="example"> |
| <pre class="example">/* Nonzero means truncate lines in the display; |
| zero means continue them. */ |
| int truncate_lines; |
| </pre></div> |
| |
| <a name="index-conditionals_002c-comments-for"></a> |
| <a name="index-_0023endif_002c-commenting"></a> |
| <p>Every ‘<samp>#endif</samp>’ should have a comment, except in the case of short |
| conditionals (just a few lines) that are not nested. The comment should |
| state the condition of the conditional that is ending, <em>including |
| its sense</em>. ‘<samp>#else</samp>’ should have a comment describing the condition |
| <em>and sense</em> of the code that follows. For example: |
| </p> |
| <div class="example"> |
| <pre class="example">#ifdef foo |
| … |
| #else /* not foo */ |
| … |
| #endif /* not foo */ |
| </pre><pre class="example">#ifdef foo |
| … |
| #endif /* foo */ |
| </pre></div> |
| |
| <p>but, by contrast, write the comments this way for a ‘<samp>#ifndef</samp>’: |
| </p> |
| <div class="example"> |
| <pre class="example">#ifndef foo |
| … |
| #else /* foo */ |
| … |
| #endif /* foo */ |
| </pre><pre class="example">#ifndef foo |
| … |
| #endif /* not foo */ |
| </pre></div> |
| |
| <hr> |
| <a name="Syntactic-Conventions"></a> |
| <div class="header"> |
| <p> |
| Next: <a href="#Names" accesskey="n" rel="next">Names</a>, Previous: <a href="#Comments" accesskey="p" rel="prev">Comments</a>, Up: <a href="#Writing-C" accesskey="u" rel="up">Writing C</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p> |
| </div> |
| <a name="Clean-Use-of-C-Constructs"></a> |
| <h3 class="section">5.3 Clean Use of C Constructs</h3> |
| <a name="index-syntactic-conventions"></a> |
| |
| <a name="index-implicit-int"></a> |
| <a name="index-function-argument_002c-declaring"></a> |
| <p>Please explicitly declare the types of all objects. For example, you |
| should explicitly declare all arguments to functions, and you should |
| declare functions to return <code>int</code> rather than omitting the |
| <code>int</code>. |
| </p> |
| <a name="index-compiler-warnings"></a> |
| <a name="index-_002dWall-compiler-option"></a> |
| <p>Some programmers like to use the GCC ‘<samp>-Wall</samp>’ option, and change the |
| code whenever it issues a warning. If you want to do this, then do. |
| Other programmers prefer not to use ‘<samp>-Wall</samp>’, because it gives |
| warnings for valid and legitimate code which they do not want to change. |
| If you want to do this, then do. The compiler should be your servant, |
| not your master. |
| </p> |
| <p>Declarations of external functions and functions to appear later in the |
| source file should all go in one place near the beginning of the file |
| (somewhere before the first function definition in the file), or else |
| should go in a header file. Don’t put <code>extern</code> declarations inside |
| functions. |
| </p> |
| <a name="index-temporary-variables"></a> |
| <p>It used to be common practice to use the same local variables (with |
| names like <code>tem</code>) over and over for different values within one |
| function. Instead of doing this, it is better to declare a separate local |
| variable for each distinct purpose, and give it a name which is |
| meaningful. This not only makes programs easier to understand, it also |
| facilitates optimization by good compilers. You can also move the |
| declaration of each local variable into the smallest scope that includes |
| all its uses. This makes the program even cleaner. |
| </p> |
| <p>Don’t use local variables or parameters that shadow global identifiers. |
| </p> |
| <a name="index-multiple-variables-in-a-line"></a> |
| <p>Don’t declare multiple variables in one declaration that spans lines. |
| Start a new declaration on each line, instead. For example, instead |
| of this: |
| </p> |
| <div class="example"> |
| <pre class="example">int foo, |
| bar; |
| </pre></div> |
| |
| <p>write either this: |
| </p> |
| <div class="example"> |
| <pre class="example">int foo, bar; |
| </pre></div> |
| |
| <p>or this: |
| </p> |
| <div class="example"> |
| <pre class="example">int foo; |
| int bar; |
| </pre></div> |
| |
| <p>(If they are global variables, each should have a comment preceding it |
| anyway.) |
| </p> |
| <p>When you have an <code>if</code>-<code>else</code> statement nested in another |
| <code>if</code> statement, always put braces around the <code>if</code>-<code>else</code>. |
| Thus, never write like this: |
| </p> |
| <div class="example"> |
| <pre class="example">if (foo) |
| if (bar) |
| win (); |
| else |
| lose (); |
| </pre></div> |
| |
| <p>always like this: |
| </p> |
| <div class="example"> |
| <pre class="example">if (foo) |
| { |
| if (bar) |
| win (); |
| else |
| lose (); |
| } |
| </pre></div> |
| |
| <p>If you have an <code>if</code> statement nested inside of an <code>else</code> |
| statement, either write <code>else if</code> on one line, like this, |
| </p> |
| <div class="example"> |
| <pre class="example">if (foo) |
| … |
| else if (bar) |
| … |
| </pre></div> |
| |
| <p>with its <code>then</code>-part indented like the preceding <code>then</code>-part, |
| or write the nested <code>if</code> within braces like this: |
| </p> |
| <div class="example"> |
| <pre class="example">if (foo) |
| … |
| else |
| { |
| if (bar) |
| … |
| } |
| </pre></div> |
| |
| <p>Don’t declare both a structure tag and variables or typedefs in the |
| same declaration. Instead, declare the structure tag separately |
| and then use it to declare the variables or typedefs. |
| </p> |
| <p>Try to avoid assignments inside <code>if</code>-conditions (assignments |
| inside <code>while</code>-conditions are ok). For example, don’t write |
| this: |
| </p> |
| <div class="example"> |
| <pre class="example">if ((foo = (char *) malloc (sizeof *foo)) == 0) |
| fatal ("virtual memory exhausted"); |
| </pre></div> |
| |
| <p>instead, write this: |
| </p> |
| <div class="example"> |
| <pre class="example">foo = (char *) malloc (sizeof *foo); |
| if (foo == 0) |
| fatal ("virtual memory exhausted"); |
| </pre></div> |
| |
| <a name="index-lint"></a> |
| <p>Don’t make the program ugly to placate <code>lint</code>. Please don’t insert any |
| casts to <code>void</code>. Zero without a cast is perfectly fine as a null |
| pointer constant, except when calling a varargs function. |
| </p> |
| <hr> |
| <a name="Names"></a> |
| <div class="header"> |
| <p> |
| Next: <a href="#System-Portability" accesskey="n" rel="next">System Portability</a>, Previous: <a href="#Syntactic-Conventions" accesskey="p" rel="prev">Syntactic Conventions</a>, Up: <a href="#Writing-C" accesskey="u" rel="up">Writing C</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p> |
| </div> |
| <a name="Naming-Variables_002c-Functions_002c-and-Files"></a> |
| <h3 class="section">5.4 Naming Variables, Functions, and Files</h3> |
| |
| <a name="index-names-of-variables_002c-functions_002c-and-files"></a> |
| <p>The names of global variables and functions in a program serve as |
| comments of a sort. So don’t choose terse names—instead, look for |
| names that give useful information about the meaning of the variable or |
| function. In a GNU program, names should be English, like other |
| comments. |
| </p> |
| <p>Local variable names can be shorter, because they are used only within |
| one context, where (presumably) comments explain their purpose. |
| </p> |
| <p>Try to limit your use of abbreviations in symbol names. It is ok to |
| make a few abbreviations, explain what they mean, and then use them |
| frequently, but don’t use lots of obscure abbreviations. |
| </p> |
| <p>Please use underscores to separate words in a name, so that the Emacs |
| word commands can be useful within them. Stick to lower case; reserve |
| upper case for macros and <code>enum</code> constants, and for name-prefixes |
| that follow a uniform convention. |
| </p> |
| <p>For example, you should use names like <code>ignore_space_change_flag</code>; |
| don’t use names like <code>iCantReadThis</code>. |
| </p> |
| <p>Variables that indicate whether command-line options have been |
| specified should be named after the meaning of the option, not after |
| the option-letter. A comment should state both the exact meaning of |
| the option and its letter. For example, |
| </p> |
| <div class="example"> |
| <pre class="example">/* Ignore changes in horizontal whitespace (-b). */ |
| int ignore_space_change_flag; |
| </pre></div> |
| |
| <p>When you want to define names with constant integer values, use |
| <code>enum</code> rather than ‘<samp>#define</samp>’. GDB knows about enumeration |
| constants. |
| </p> |
| <a name="index-file_002dname-limitations"></a> |
| <a name="index-doschk"></a> |
| <p>You might want to make sure that none of the file names would conflict |
| if the files were loaded onto an MS-DOS file system which shortens the |
| names. You can use the program <code>doschk</code> to test for this. |
| </p> |
| <p>Some GNU programs were designed to limit themselves to file names of 14 |
| characters or less, to avoid file name conflicts if they are read into |
| older System V systems. Please preserve this feature in the existing |
| GNU programs that have it, but there is no need to do this in new GNU |
| programs. <code>doschk</code> also reports file names longer than 14 |
| characters. |
| </p> |
| <hr> |
| <a name="System-Portability"></a> |
| <div class="header"> |
| <p> |
| Next: <a href="#CPU-Portability" accesskey="n" rel="next">CPU Portability</a>, Previous: <a href="#Names" accesskey="p" rel="prev">Names</a>, Up: <a href="#Writing-C" accesskey="u" rel="up">Writing C</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p> |
| </div> |
| <a name="Portability-between-System-Types"></a> |
| <h3 class="section">5.5 Portability between System Types</h3> |
| <a name="index-portability_002c-between-system-types"></a> |
| |
| <p>In the Unix world, “portability” refers to porting to different Unix |
| versions. For a GNU program, this kind of portability is desirable, but |
| not paramount. |
| </p> |
| <p>The primary purpose of GNU software is to run on top of the GNU kernel, |
| compiled with the GNU C compiler, on various types of <small>CPU</small>. So the |
| kinds of portability that are absolutely necessary are quite limited. |
| But it is important to support Linux-based GNU systems, since they |
| are the form of GNU that is popular. |
| </p> |
| <p>Beyond that, it is good to support the other free operating systems |
| (*BSD), and it is nice to support other Unix-like systems if you want |
| to. Supporting a variety of Unix-like systems is desirable, although |
| not paramount. It is usually not too hard, so you may as well do it. |
| But you don’t have to consider it an obligation, if it does turn out to |
| be hard. |
| </p> |
| <a name="index-autoconf"></a> |
| <p>The easiest way to achieve portability to most Unix-like systems is to |
| use Autoconf. It’s unlikely that your program needs to know more |
| information about the host platform than Autoconf can provide, simply |
| because most of the programs that need such knowledge have already been |
| written. |
| </p> |
| <p>Avoid using the format of semi-internal data bases (e.g., directories) |
| when there is a higher-level alternative (<code>readdir</code>). |
| </p> |
| <a name="index-non_002dPOSIX-systems_002c-and-portability"></a> |
| <p>As for systems that are not like Unix, such as MSDOS, Windows, VMS, MVS, |
| and older Macintosh systems, supporting them is often a lot of work. |
| When that is the case, it is better to spend your time adding features |
| that will be useful on GNU and GNU/Linux, rather than on supporting |
| other incompatible systems. |
| </p> |
| <p>If you do support Windows, please do not abbreviate it as “win”. In |
| hacker terminology, calling something a “win” is a form of praise. |
| You’re free to praise Microsoft Windows on your own if you want, but |
| please don’t do this in GNU packages. Instead of abbreviating |
| “Windows” to “win”, you can write it in full or abbreviate it to |
| “woe” or “w”. In GNU Emacs, for instance, we use ‘<samp>w32</samp>’ in |
| file names of Windows-specific files, but the macro for Windows |
| conditionals is called <code>WINDOWSNT</code>. |
| </p> |
| <p>It is a good idea to define the “feature test macro” |
| <code>_GNU_SOURCE</code> when compiling your C files. When you compile on GNU |
| or GNU/Linux, this will enable the declarations of GNU library extension |
| functions, and that will usually give you a compiler error message if |
| you define the same function names in some other way in your program. |
| (You don’t have to actually <em>use</em> these functions, if you prefer |
| to make the program more portable to other systems.) |
| </p> |
| <p>But whether or not you use these GNU extensions, you should avoid |
| using their names for any other meanings. Doing so would make it hard |
| to move your code into other GNU programs. |
| </p> |
| <hr> |
| <a name="CPU-Portability"></a> |
| <div class="header"> |
| <p> |
| Next: <a href="#System-Functions" accesskey="n" rel="next">System Functions</a>, Previous: <a href="#System-Portability" accesskey="p" rel="prev">System Portability</a>, Up: <a href="#Writing-C" accesskey="u" rel="up">Writing C</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p> |
| </div> |
| <a name="Portability-between-CPUs"></a> |
| <h3 class="section">5.6 Portability between <small>CPU</small>s</h3> |
| |
| <a name="index-data-types_002c-and-portability"></a> |
| <a name="index-portability_002c-and-data-types"></a> |
| <p>Even GNU systems will differ because of differences among <small>CPU</small> |
| types—for example, difference in byte ordering and alignment |
| requirements. It is absolutely essential to handle these differences. |
| However, don’t make any effort to cater to the possibility that an |
| <code>int</code> will be less than 32 bits. We don’t support 16-bit machines |
| in GNU. |
| </p> |
| <p>Similarly, don’t make any effort to cater to the possibility that |
| <code>long</code> will be smaller than predefined types like <code>size_t</code>. |
| For example, the following code is ok: |
| </p> |
| <div class="example"> |
| <pre class="example">printf ("size = %lu\n", (unsigned long) sizeof array); |
| printf ("diff = %ld\n", (long) (pointer2 - pointer1)); |
| </pre></div> |
| |
| <p>1989 Standard C requires this to work, and we know of only one |
| counterexample: 64-bit programs on Microsoft Windows. We will |
| leave it to those who want to port GNU programs to that environment |
| to figure out how to do it. |
| </p> |
| <p>Predefined file-size types like <code>off_t</code> are an exception: they are |
| longer than <code>long</code> on many platforms, so code like the above won’t |
| work with them. One way to print an <code>off_t</code> value portably is to |
| print its digits yourself, one by one. |
| </p> |
| <p>Don’t assume that the address of an <code>int</code> object is also the |
| address of its least-significant byte. This is false on big-endian |
| machines. Thus, don’t make the following mistake: |
| </p> |
| <div class="example"> |
| <pre class="example">int c; |
| … |
| while ((c = getchar ()) != EOF) |
| write (file_descriptor, &c, 1); |
| </pre></div> |
| |
| <p>Instead, use <code>unsigned char</code> as follows. (The <code>unsigned</code> |
| is for portability to unusual systems where <code>char</code> is signed and |
| where there is integer overflow checking.) |
| </p> |
| <div class="example"> |
| <pre class="example">int c; |
| while ((c = getchar ()) != EOF) |
| { |
| unsigned char u = c; |
| write (file_descriptor, &u, 1); |
| } |
| </pre></div> |
| |
| <p>It used to be ok to not worry about the difference between pointers |
| and integers when passing arguments to functions. However, on most |
| modern 64-bit machines pointers are wider than <code>int</code>. |
| Conversely, integer types like <code>long long int</code> and <code>off_t</code> |
| are wider than pointers on most modern 32-bit machines. Hence it’s |
| often better nowadays to use prototypes to define functions whose |
| argument types are not trivial. |
| </p> |
| <p>In particular, if functions accept varying argument counts or types |
| they should be declared using prototypes containing ‘<samp>...</samp>’ and |
| defined using <samp>stdarg.h</samp>. For an example of this, please see the |
| <a href="http://www.gnu.org/software/gnulib/">Gnulib</a> error module, which |
| declares and defines the following function: |
| </p> |
| <div class="example"> |
| <pre class="example">/* Print a message with `fprintf (stderr, FORMAT, ...)'; |
| if ERRNUM is nonzero, follow it with ": " and strerror (ERRNUM). |
| If STATUS is nonzero, terminate the program with `exit (STATUS)'. */ |
| |
| void error (int status, int errnum, const char *format, ...); |
| </pre></div> |
| |
| <p>A simple way to use the Gnulib error module is to obtain the two |
| source files <samp>error.c</samp> and <samp>error.h</samp> from the Gnulib library |
| source code repository at |
| <a href="http://git.savannah.gnu.org/gitweb/?p=gnulib.git">http://git.savannah.gnu.org/gitweb/?p=gnulib.git</a>. |
| Here’s a sample use: |
| </p> |
| <div class="example"> |
| <pre class="example">#include "error.h" |
| #include <errno.h> |
| #include <stdio.h> |
| |
| char *program_name = "myprogram"; |
| |
| FILE * |
| xfopen (char const *name) |
| { |
| FILE *fp = fopen (name, "r"); |
| if (! fp) |
| error (1, errno, "cannot read %s", name); |
| return fp; |
| } |
| </pre></div> |
| |
| <a name="index-casting-pointers-to-integers"></a> |
| <p>Avoid casting pointers to integers if you can. Such casts greatly |
| reduce portability, and in most programs they are easy to avoid. In the |
| cases where casting pointers to integers is essential—such as, a Lisp |
| interpreter which stores type information as well as an address in one |
| word—you’ll have to make explicit provisions to handle different word |
| sizes. You will also need to make provision for systems in which the |
| normal range of addresses you can get from <code>malloc</code> starts far away |
| from zero. |
| </p> |
| <hr> |
| <a name="System-Functions"></a> |
| <div class="header"> |
| <p> |
| Next: <a href="#Internationalization" accesskey="n" rel="next">Internationalization</a>, Previous: <a href="#CPU-Portability" accesskey="p" rel="prev">CPU Portability</a>, Up: <a href="#Writing-C" accesskey="u" rel="up">Writing C</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p> |
| </div> |
| <a name="Calling-System-Functions"></a> |
| <h3 class="section">5.7 Calling System Functions</h3> |
| <a name="index-library-functions_002c-and-portability"></a> |
| <a name="index-portability_002c-and-library-functions"></a> |
| |
| <p>C implementations differ substantially. Standard C reduces but does |
| not eliminate the incompatibilities; meanwhile, many GNU packages still |
| support pre-standard compilers because this is not hard to do. This |
| chapter gives recommendations for how to use the more-or-less standard C |
| library functions to avoid unnecessary loss of portability. |
| </p> |
| <ul> |
| <li> Don’t use the return value of <code>sprintf</code>. It returns the number of |
| characters written on some systems, but not on all systems. |
| |
| </li><li> Be aware that <code>vfprintf</code> is not always available. |
| |
| </li><li> <code>main</code> should be declared to return type <code>int</code>. It should |
| terminate either by calling <code>exit</code> or by returning the integer |
| status code; make sure it cannot ever return an undefined value. |
| |
| </li><li> <a name="index-declaration-for-system-functions"></a> |
| Don’t declare system functions explicitly. |
| |
| <p>Almost any declaration for a system function is wrong on some system. |
| To minimize conflicts, leave it to the system header files to declare |
| system functions. If the headers don’t declare a function, let it |
| remain undeclared. |
| </p> |
| <p>While it may seem unclean to use a function without declaring it, in |
| practice this works fine for most system library functions on the |
| systems where this really happens; thus, the disadvantage is only |
| theoretical. By contrast, actual declarations have frequently caused |
| actual conflicts. |
| </p> |
| </li><li> If you must declare a system function, don’t specify the argument types. |
| Use an old-style declaration, not a Standard C prototype. The more you |
| specify about the function, the more likely a conflict. |
| |
| </li><li> In particular, don’t unconditionally declare <code>malloc</code> or |
| <code>realloc</code>. |
| |
| <p>Most GNU programs use those functions just once, in functions |
| conventionally named <code>xmalloc</code> and <code>xrealloc</code>. These |
| functions call <code>malloc</code> and <code>realloc</code>, respectively, and |
| check the results. |
| </p> |
| <p>Because <code>xmalloc</code> and <code>xrealloc</code> are defined in your program, |
| you can declare them in other files without any risk of type conflict. |
| </p> |
| <p>On most systems, <code>int</code> is the same length as a pointer; thus, the |
| calls to <code>malloc</code> and <code>realloc</code> work fine. For the few |
| exceptional systems (mostly 64-bit machines), you can use |
| <strong>conditionalized</strong> declarations of <code>malloc</code> and |
| <code>realloc</code>—or put these declarations in configuration files |
| specific to those systems. |
| </p> |
| </li><li> <a name="index-string-library-functions"></a> |
| The string functions require special treatment. Some Unix systems have |
| a header file <samp>string.h</samp>; others have <samp>strings.h</samp>. Neither |
| file name is portable. There are two things you can do: use Autoconf to |
| figure out which file to include, or don’t include either file. |
| |
| </li><li> If you don’t include either strings file, you can’t get declarations for |
| the string functions from the header file in the usual way. |
| |
| <p>That causes less of a problem than you might think. The newer standard |
| string functions should be avoided anyway because many systems still |
| don’t support them. The string functions you can use are these: |
| </p> |
| <div class="example"> |
| <pre class="example">strcpy strncpy strcat strncat |
| strlen strcmp strncmp |
| strchr strrchr |
| </pre></div> |
| |
| <p>The copy and concatenate functions work fine without a declaration as |
| long as you don’t use their values. Using their values without a |
| declaration fails on systems where the width of a pointer differs from |
| the width of <code>int</code>, and perhaps in other cases. It is trivial to |
| avoid using their values, so do that. |
| </p> |
| <p>The compare functions and <code>strlen</code> work fine without a declaration |
| on most systems, possibly all the ones that GNU software runs on. |
| You may find it necessary to declare them <strong>conditionally</strong> on a |
| few systems. |
| </p> |
| <p>The search functions must be declared to return <code>char *</code>. Luckily, |
| there is no variation in the data type they return. But there is |
| variation in their names. Some systems give these functions the names |
| <code>index</code> and <code>rindex</code>; other systems use the names |
| <code>strchr</code> and <code>strrchr</code>. Some systems support both pairs of |
| names, but neither pair works on all systems. |
| </p> |
| <p>You should pick a single pair of names and use it throughout your |
| program. (Nowadays, it is better to choose <code>strchr</code> and |
| <code>strrchr</code> for new programs, since those are the standard |
| names.) Declare both of those names as functions returning <code>char |
| *</code>. On systems which don’t support those names, define them as macros |
| in terms of the other pair. For example, here is what to put at the |
| beginning of your file (or in a header) if you want to use the names |
| <code>strchr</code> and <code>strrchr</code> throughout: |
| </p> |
| <div class="example"> |
| <pre class="example">#ifndef HAVE_STRCHR |
| #define strchr index |
| #endif |
| #ifndef HAVE_STRRCHR |
| #define strrchr rindex |
| #endif |
| |
| char *strchr (); |
| char *strrchr (); |
| </pre></div> |
| </li></ul> |
| |
| <p>Here we assume that <code>HAVE_STRCHR</code> and <code>HAVE_STRRCHR</code> are |
| macros defined in systems where the corresponding functions exist. |
| One way to get them properly defined is to use Autoconf. |
| </p> |
| <hr> |
| <a name="Internationalization"></a> |
| <div class="header"> |
| <p> |
| Next: <a href="#Character-Set" accesskey="n" rel="next">Character Set</a>, Previous: <a href="#System-Functions" accesskey="p" rel="prev">System Functions</a>, Up: <a href="#Writing-C" accesskey="u" rel="up">Writing C</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p> |
| </div> |
| <a name="Internationalization-1"></a> |
| <h3 class="section">5.8 Internationalization</h3> |
| <a name="index-internationalization"></a> |
| |
| <a name="index-gettext"></a> |
| <p>GNU has a library called GNU gettext that makes it easy to translate the |
| messages in a program into various languages. You should use this |
| library in every program. Use English for the messages as they appear |
| in the program, and let gettext provide the way to translate them into |
| other languages. |
| </p> |
| <p>Using GNU gettext involves putting a call to the <code>gettext</code> macro |
| around each string that might need translation—like this: |
| </p> |
| <div class="example"> |
| <pre class="example">printf (gettext ("Processing file `%s'...")); |
| </pre></div> |
| |
| <p>This permits GNU gettext to replace the string <code>"Processing file |
| `%s'..."</code> with a translated version. |
| </p> |
| <p>Once a program uses gettext, please make a point of writing calls to |
| <code>gettext</code> when you add new strings that call for translation. |
| </p> |
| <p>Using GNU gettext in a package involves specifying a <em>text domain |
| name</em> for the package. The text domain name is used to separate the |
| translations for this package from the translations for other packages. |
| Normally, the text domain name should be the same as the name of the |
| package—for example, ‘<samp>coreutils</samp>’ for the GNU core utilities. |
| </p> |
| <a name="index-message-text_002c-and-internationalization"></a> |
| <p>To enable gettext to work well, avoid writing code that makes |
| assumptions about the structure of words or sentences. When you want |
| the precise text of a sentence to vary depending on the data, use two or |
| more alternative string constants each containing a complete sentences, |
| rather than inserting conditionalized words or phrases into a single |
| sentence framework. |
| </p> |
| <p>Here is an example of what not to do: |
| </p> |
| <div class="smallexample"> |
| <pre class="smallexample">printf ("%s is full", capacity > 5000000 ? "disk" : "floppy disk"); |
| </pre></div> |
| |
| <p>If you apply gettext to all strings, like this, |
| </p> |
| <div class="smallexample"> |
| <pre class="smallexample">printf (gettext ("%s is full"), |
| capacity > 5000000 ? gettext ("disk") : gettext ("floppy disk")); |
| </pre></div> |
| |
| <p>the translator will hardly know that "disk" and "floppy disk" are meant to |
| be substituted in the other string. Worse, in some languages (like French) |
| the construction will not work: the translation of the word "full" depends |
| on the gender of the first part of the sentence; it happens to be not the |
| same for "disk" as for "floppy disk". |
| </p> |
| <p>Complete sentences can be translated without problems: |
| </p> |
| <div class="example"> |
| <pre class="example">printf (capacity > 5000000 ? gettext ("disk is full") |
| : gettext ("floppy disk is full")); |
| </pre></div> |
| |
| <p>A similar problem appears at the level of sentence structure with this |
| code: |
| </p> |
| <div class="example"> |
| <pre class="example">printf ("# Implicit rule search has%s been done.\n", |
| f->tried_implicit ? "" : " not"); |
| </pre></div> |
| |
| <p>Adding <code>gettext</code> calls to this code cannot give correct results for |
| all languages, because negation in some languages requires adding words |
| at more than one place in the sentence. By contrast, adding |
| <code>gettext</code> calls does the job straightforwardly if the code starts |
| out like this: |
| </p> |
| <div class="example"> |
| <pre class="example">printf (f->tried_implicit |
| ? "# Implicit rule search has been done.\n", |
| : "# Implicit rule search has not been done.\n"); |
| </pre></div> |
| |
| <p>Another example is this one: |
| </p> |
| <div class="example"> |
| <pre class="example">printf ("%d file%s processed", nfiles, |
| nfiles != 1 ? "s" : ""); |
| </pre></div> |
| |
| <p>The problem with this example is that it assumes that plurals are made |
| by adding ‘s’. If you apply gettext to the format string, like this, |
| </p> |
| <div class="example"> |
| <pre class="example">printf (gettext ("%d file%s processed"), nfiles, |
| nfiles != 1 ? "s" : ""); |
| </pre></div> |
| |
| <p>the message can use different words, but it will still be forced to use |
| ‘s’ for the plural. Here is a better way, with gettext being applied to |
| the two strings independently: |
| </p> |
| <div class="example"> |
| <pre class="example">printf ((nfiles != 1 ? gettext ("%d files processed") |
| : gettext ("%d file processed")), |
| nfiles); |
| </pre></div> |
| |
| <p>But this still doesn’t work for languages like Polish, which has three |
| plural forms: one for nfiles == 1, one for nfiles == 2, 3, 4, 22, 23, 24, ... |
| and one for the rest. The GNU <code>ngettext</code> function solves this problem: |
| </p> |
| <div class="example"> |
| <pre class="example">printf (ngettext ("%d files processed", "%d file processed", nfiles), |
| nfiles); |
| </pre></div> |
| |
| |
| <hr> |
| <a name="Character-Set"></a> |
| <div class="header"> |
| <p> |
| Next: <a href="#Quote-Characters" accesskey="n" rel="next">Quote Characters</a>, Previous: <a href="#Internationalization" accesskey="p" rel="prev">Internationalization</a>, Up: <a href="#Writing-C" accesskey="u" rel="up">Writing C</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p> |
| </div> |
| <a name="Character-Set-1"></a> |
| <h3 class="section">5.9 Character Set</h3> |
| <a name="index-character-set"></a> |
| <a name="index-encodings"></a> |
| <a name="index-ASCII-characters"></a> |
| <a name="index-non_002dASCII-characters"></a> |
| |
| <p>Sticking to the ASCII character set (plain text, 7-bit characters) is |
| preferred in GNU source code comments, text documents, and other |
| contexts, unless there is good reason to do something else because of |
| the application domain. For example, if source code deals with the |
| French Revolutionary calendar, it is OK if its literal strings contain |
| accented characters in month names like “Floréal”. Also, it is OK |
| to use non-ASCII characters to represent proper names of contributors in |
| change logs (see <a href="#Change-Logs">Change Logs</a>). |
| </p> |
| <p>If you need to use non-ASCII characters, you should normally stick with |
| one encoding, as one cannot in general mix encodings reliably. |
| </p> |
| |
| <hr> |
| <a name="Quote-Characters"></a> |
| <div class="header"> |
| <p> |
| Next: <a href="#Mmap" accesskey="n" rel="next">Mmap</a>, Previous: <a href="#Character-Set" accesskey="p" rel="prev">Character Set</a>, Up: <a href="#Writing-C" accesskey="u" rel="up">Writing C</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p> |
| </div> |
| <a name="Quote-Characters-1"></a> |
| <h3 class="section">5.10 Quote Characters</h3> |
| <a name="index-quote-characters"></a> |
| <a name="index-locale_002dspecific-quote-characters"></a> |
| <a name="index-left-quote"></a> |
| <a name="index-grave-accent"></a> |
| |
| <p>In the C locale, GNU programs should stick to plain ASCII for quotation |
| characters in messages to users: preferably 0x60 (‘<samp>`</samp>’) for left |
| quotes and 0x27 (‘<samp>'</samp>’) for right quotes. It is ok, but not |
| required, to use locale-specific quotes in other locales. |
| </p> |
| <p>The <a href="http://www.gnu.org/software/gnulib/">Gnulib</a> <code>quote</code> and |
| <code>quotearg</code> modules provide a reasonably straightforward way to |
| support locale-specific quote characters, as well as taking care of |
| other issues, such as quoting a filename that itself contains a quote |
| character. See the Gnulib documentation for usage details. |
| </p> |
| <p>In any case, the documentation for your program should clearly specify |
| how it does quoting, if different than the preferred method of ‘<samp>`</samp>’ |
| and ‘<samp>'</samp>’. This is especially important if the output of your |
| program is ever likely to be parsed by another program. |
| </p> |
| <p>Quotation characters are a difficult area in the computing world at |
| this time: there are no true left or right quote characters in Latin1; |
| the ‘<samp>`</samp>’ character we use was standardized there as a grave |
| accent. Moreover, Latin1 is still not universally usable. |
| </p> |
| <p>Unicode contains the unambiguous quote characters required, and its |
| common encoding UTF-8 is upward compatible with Latin1. However, |
| Unicode and UTF-8 are not universally well-supported, either. |
| </p> |
| <p>This may change over the next few years, and then we will revisit |
| this. |
| </p> |
| |
| <hr> |
| <a name="Mmap"></a> |
| <div class="header"> |
| <p> |
| Previous: <a href="#Quote-Characters" accesskey="p" rel="prev">Quote Characters</a>, Up: <a href="#Writing-C" accesskey="u" rel="up">Writing C</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p> |
| </div> |
| <a name="Mmap-1"></a> |
| <h3 class="section">5.11 Mmap</h3> |
| <a name="index-mmap"></a> |
| |
| <p>Don’t assume that <code>mmap</code> either works on all files or fails |
| for all files. It may work on some files and fail on others. |
| </p> |
| <p>The proper way to use <code>mmap</code> is to try it on the specific file for |
| which you want to use it—and if <code>mmap</code> doesn’t work, fall back on |
| doing the job in another way using <code>read</code> and <code>write</code>. |
| </p> |
| <p>The reason this precaution is needed is that the GNU kernel (the HURD) |
| provides a user-extensible file system, in which there can be many |
| different kinds of “ordinary files.” Many of them support |
| <code>mmap</code>, but some do not. It is important to make programs handle |
| all these kinds of files. |
| </p> |
| <hr> |
| <a name="Documentation"></a> |
| <div class="header"> |
| <p> |
| Next: <a href="#Managing-Releases" accesskey="n" rel="next">Managing Releases</a>, Previous: <a href="#Writing-C" accesskey="p" rel="prev">Writing C</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p> |
| </div> |
| <a name="Documenting-Programs"></a> |
| <h2 class="chapter">6 Documenting Programs</h2> |
| <a name="index-documentation"></a> |
| |
| <p>A GNU program should ideally come with full free documentation, adequate |
| for both reference and tutorial purposes. If the package can be |
| programmed or extended, the documentation should cover programming or |
| extending it, as well as just using it. |
| </p> |
| <table class="menu" border="0" cellspacing="0"> |
| <tr><td align="left" valign="top">• <a href="#GNU-Manuals" accesskey="1">GNU Manuals</a>:</td><td> </td><td align="left" valign="top">Writing proper manuals. |
| </td></tr> |
| <tr><td align="left" valign="top">• <a href="#Doc-Strings-and-Manuals" accesskey="2">Doc Strings and Manuals</a>:</td><td> </td><td align="left" valign="top">Compiling doc strings doesn’t make a manual. |
| </td></tr> |
| <tr><td align="left" valign="top">• <a href="#Manual-Structure-Details" accesskey="3">Manual Structure Details</a>:</td><td> </td><td align="left" valign="top">Specific structure conventions. |
| </td></tr> |
| <tr><td align="left" valign="top">• <a href="#License-for-Manuals" accesskey="4">License for Manuals</a>:</td><td> </td><td align="left" valign="top">Writing the distribution terms for a manual. |
| </td></tr> |
| <tr><td align="left" valign="top">• <a href="#Manual-Credits" accesskey="5">Manual Credits</a>:</td><td> </td><td align="left" valign="top">Giving credit to documentation contributors. |
| </td></tr> |
| <tr><td align="left" valign="top">• <a href="#Printed-Manuals" accesskey="6">Printed Manuals</a>:</td><td> </td><td align="left" valign="top">Mentioning the printed manual. |
| </td></tr> |
| <tr><td align="left" valign="top">• <a href="#NEWS-File" accesskey="7">NEWS File</a>:</td><td> </td><td align="left" valign="top">NEWS files supplement manuals. |
| </td></tr> |
| <tr><td align="left" valign="top">• <a href="#Change-Logs" accesskey="8">Change Logs</a>:</td><td> </td><td align="left" valign="top">Recording changes. |
| </td></tr> |
| <tr><td align="left" valign="top">• <a href="#Man-Pages" accesskey="9">Man Pages</a>:</td><td> </td><td align="left" valign="top">Man pages are secondary. |
| </td></tr> |
| <tr><td align="left" valign="top">• <a href="#Reading-other-Manuals">Reading other Manuals</a>:</td><td> </td><td align="left" valign="top">How far you can go in learning |
| from other manuals. |
| </td></tr> |
| </table> |
| |
| <hr> |
| <a name="GNU-Manuals"></a> |
| <div class="header"> |
| <p> |
| Next: <a href="#Doc-Strings-and-Manuals" accesskey="n" rel="next">Doc Strings and Manuals</a>, Up: <a href="#Documentation" accesskey="u" rel="up">Documentation</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p> |
| </div> |
| <a name="GNU-Manuals-1"></a> |
| <h3 class="section">6.1 GNU Manuals</h3> |
| |
| <p>The preferred document format for the GNU system is the Texinfo |
| formatting language. Every GNU package should (ideally) have |
| documentation in Texinfo both for reference and for learners. Texinfo |
| makes it possible to produce a good quality formatted book, using |
| TeX, and to generate an Info file. It is also possible to generate |
| HTML output from Texinfo source. See the Texinfo manual, either the |
| hardcopy, or the on-line version available through <code>info</code> or the |
| Emacs Info subsystem (<kbd>C-h i</kbd>). |
| </p> |
| <p>Nowadays some other formats such as Docbook and Sgmltexi can be |
| converted automatically into Texinfo. It is ok to produce the Texinfo |
| documentation by conversion this way, as long as it gives good results. |
| </p> |
| <p>Make sure your manual is clear to a reader who knows nothing about the |
| topic and reads it straight through. This means covering basic topics |
| at the beginning, and advanced topics only later. This also means |
| defining every specialized term when it is first used. |
| </p> |
| <p>Programmers tend to carry over the structure of the program as the |
| structure for its documentation. But this structure is not |
| necessarily good for explaining how to use the program; it may be |
| irrelevant and confusing for a user. |
| </p> |
| <p>Instead, the right way to structure documentation is according to the |
| concepts and questions that a user will have in mind when reading it. |
| This principle applies at every level, from the lowest (ordering |
| sentences in a paragraph) to the highest (ordering of chapter topics |
| within the manual). Sometimes this structure of ideas matches the |
| structure of the implementation of the software being documented—but |
| often they are different. An important part of learning to write good |
| documentation is to learn to notice when you have unthinkingly |
| structured the documentation like the implementation, stop yourself, |
| and look for better alternatives. |
| </p> |
| <p>For example, each program in the GNU system probably ought to be |
| documented in one manual; but this does not mean each program should |
| have its own manual. That would be following the structure of the |
| implementation, rather than the structure that helps the user |
| understand. |
| </p> |
| <p>Instead, each manual should cover a coherent <em>topic</em>. For example, |
| instead of a manual for <code>diff</code> and a manual for <code>diff3</code>, we |
| have one manual for “comparison of files” which covers both of those |
| programs, as well as <code>cmp</code>. By documenting these programs |
| together, we can make the whole subject clearer. |
| </p> |
| <p>The manual which discusses a program should certainly document all of |
| the program’s command-line options and all of its commands. It should |
| give examples of their use. But don’t organize the manual as a list |
| of features. Instead, organize it logically, by subtopics. Address |
| the questions that a user will ask when thinking about the job that |
| the program does. Don’t just tell the reader what each feature can |
| do—say what jobs it is good for, and show how to use it for those |
| jobs. Explain what is recommended usage, and what kinds of usage |
| users should avoid. |
| </p> |
| <p>In general, a GNU manual should serve both as tutorial and reference. |
| It should be set up for convenient access to each topic through Info, |
| and for reading straight through (appendixes aside). A GNU manual |
| should give a good introduction to a beginner reading through from the |
| start, and should also provide all the details that hackers want. |
| The Bison manual is a good example of this—please take a look at it |
| to see what we mean. |
| </p> |
| <p>That is not as hard as it first sounds. Arrange each chapter as a |
| logical breakdown of its topic, but order the sections, and write their |
| text, so that reading the chapter straight through makes sense. Do |
| likewise when structuring the book into chapters, and when structuring a |
| section into paragraphs. The watchword is, <em>at each point, address |
| the most fundamental and important issue raised by the preceding text.</em> |
| </p> |
| <p>If necessary, add extra chapters at the beginning of the manual which |
| are purely tutorial and cover the basics of the subject. These provide |
| the framework for a beginner to understand the rest of the manual. The |
| Bison manual provides a good example of how to do this. |
| </p> |
| <p>To serve as a reference, a manual should have an Index that list all the |
| functions, variables, options, and important concepts that are part of |
| the program. One combined Index should do for a short manual, but |
| sometimes for a complex package it is better to use multiple indices. |
| The Texinfo manual includes advice on preparing good index entries, see |
| <a href="http://www.gnu.org/software/texinfo/manual/texinfo/texinfo.html#Index-Entries">Making Index Entries</a> in <cite>GNU Texinfo</cite>, and |
| see <a href="http://www.gnu.org/software/texinfo/manual/texinfo/texinfo.html#Indexing-Commands">Defining the Entries of an |
| Index</a> in <cite>GNU Texinfo</cite>. |
| </p> |
| <p>Don’t use Unix man pages as a model for how to write GNU documentation; |
| most of them are terse, badly structured, and give inadequate |
| explanation of the underlying concepts. (There are, of course, some |
| exceptions.) Also, Unix man pages use a particular format which is |
| different from what we use in GNU manuals. |
| </p> |
| <p>Please include an email address in the manual for where to report |
| bugs <em>in the text of the manual</em>. |
| </p> |
| <p>Please do not use the term “pathname” that is used in Unix |
| documentation; use “file name” (two words) instead. We use the term |
| “path” only for search paths, which are lists of directory names. |
| </p> |
| <p>Please do not use the term “illegal” to refer to erroneous input to |
| a computer program. Please use “invalid” for this, and reserve the |
| term “illegal” for activities prohibited by law. |
| </p> |
| <p>Please do not write ‘<samp>()</samp>’ after a function name just to indicate |
| it is a function. <code>foo ()</code> is not a function, it is a function |
| call with no arguments. |
| </p> |
| <hr> |
| <a name="Doc-Strings-and-Manuals"></a> |
| <div class="header"> |
| <p> |
| Next: <a href="#Manual-Structure-Details" accesskey="n" rel="next">Manual Structure Details</a>, Previous: <a href="#GNU-Manuals" accesskey="p" rel="prev">GNU Manuals</a>, Up: <a href="#Documentation" accesskey="u" rel="up">Documentation</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p> |
| </div> |
| <a name="Doc-Strings-and-Manuals-1"></a> |
| <h3 class="section">6.2 Doc Strings and Manuals</h3> |
| |
| <p>Some programming systems, such as Emacs, provide a documentation string |
| for each function, command or variable. You may be tempted to write a |
| reference manual by compiling the documentation strings and writing a |
| little additional text to go around them—but you must not do it. That |
| approach is a fundamental mistake. The text of well-written |
| documentation strings will be entirely wrong for a manual. |
| </p> |
| <p>A documentation string needs to stand alone—when it appears on the |
| screen, there will be no other text to introduce or explain it. |
| Meanwhile, it can be rather informal in style. |
| </p> |
| <p>The text describing a function or variable in a manual must not stand |
| alone; it appears in the context of a section or subsection. Other text |
| at the beginning of the section should explain some of the concepts, and |
| should often make some general points that apply to several functions or |
| variables. The previous descriptions of functions and variables in the |
| section will also have given information about the topic. A description |
| written to stand alone would repeat some of that information; this |
| redundancy looks bad. Meanwhile, the informality that is acceptable in |
| a documentation string is totally unacceptable in a manual. |
| </p> |
| <p>The only good way to use documentation strings in writing a good manual |
| is to use them as a source of information for writing good text. |
| </p> |
| <hr> |
| <a name="Manual-Structure-Details"></a> |
| <div class="header"> |
| <p> |
| Next: <a href="#License-for-Manuals" accesskey="n" rel="next">License for Manuals</a>, Previous: <a href="#Doc-Strings-and-Manuals" accesskey="p" rel="prev">Doc Strings and Manuals</a>, Up: <a href="#Documentation" accesskey="u" rel="up">Documentation</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p> |
| </div> |
| <a name="Manual-Structure-Details-1"></a> |
| <h3 class="section">6.3 Manual Structure Details</h3> |
| <a name="index-manual-structure"></a> |
| |
| <p>The title page of the manual should state the version of the programs or |
| packages documented in the manual. The Top node of the manual should |
| also contain this information. If the manual is changing more |
| frequently than or independent of the program, also state a version |
| number for the manual in both of these places. |
| </p> |
| <p>Each program documented in the manual should have a node named |
| ‘<samp><var>program</var> Invocation</samp>’ or ‘<samp>Invoking <var>program</var></samp>’. This |
| node (together with its subnodes, if any) should describe the program’s |
| command line arguments and how to run it (the sort of information people |
| would look for in a man page). Start with an ‘<samp>@example</samp>’ |
| containing a template for all the options and arguments that the program |
| uses. |
| </p> |
| <p>Alternatively, put a menu item in some menu whose item name fits one of |
| the above patterns. This identifies the node which that item points to |
| as the node for this purpose, regardless of the node’s actual name. |
| </p> |
| <p>The ‘<samp>--usage</samp>’ feature of the Info reader looks for such a node |
| or menu item in order to find the relevant text, so it is essential |
| for every Texinfo file to have one. |
| </p> |
| <p>If one manual describes several programs, it should have such a node for |
| each program described in the manual. |
| </p> |
| <hr> |
| <a name="License-for-Manuals"></a> |
| <div class="header"> |
| <p> |
| Next: <a href="#Manual-Credits" accesskey="n" rel="next">Manual Credits</a>, Previous: <a href="#Manual-Structure-Details" accesskey="p" rel="prev">Manual Structure Details</a>, Up: <a href="#Documentation" accesskey="u" rel="up">Documentation</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p> |
| </div> |
| <a name="License-for-Manuals-1"></a> |
| <h3 class="section">6.4 License for Manuals</h3> |
| <a name="index-license-for-manuals"></a> |
| |
| <p>Please use the GNU Free Documentation License for all GNU manuals that |
| are more than a few pages long. Likewise for a collection of short |
| documents—you only need one copy of the GNU FDL for the whole |
| collection. For a single short document, you can use a very permissive |
| non-copyleft license, to avoid taking up space with a long license. |
| </p> |
| <p>See <a href="http://www.gnu.org/copyleft/fdl-howto.html">http://www.gnu.org/copyleft/fdl-howto.html</a> for more explanation |
| of how to employ the GFDL. |
| </p> |
| <p>Note that it is not obligatory to include a copy of the GNU GPL or GNU |
| LGPL in a manual whose license is neither the GPL nor the LGPL. It can |
| be a good idea to include the program’s license in a large manual; in a |
| short manual, whose size would be increased considerably by including |
| the program’s license, it is probably better not to include it. |
| </p> |
| <hr> |
| <a name="Manual-Credits"></a> |
| <div class="header"> |
| <p> |
| Next: <a href="#Printed-Manuals" accesskey="n" rel="next">Printed Manuals</a>, Previous: <a href="#License-for-Manuals" accesskey="p" rel="prev">License for Manuals</a>, Up: <a href="#Documentation" accesskey="u" rel="up">Documentation</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p> |
| </div> |
| <a name="Manual-Credits-1"></a> |
| <h3 class="section">6.5 Manual Credits</h3> |
| <a name="index-credits-for-manuals"></a> |
| |
| <p>Please credit the principal human writers of the manual as the authors, |
| on the title page of the manual. If a company sponsored the work, thank |
| the company in a suitable place in the manual, but do not cite the |
| company as an author. |
| </p> |
| <hr> |
| <a name="Printed-Manuals"></a> |
| <div class="header"> |
| <p> |
| Next: <a href="#NEWS-File" accesskey="n" rel="next">NEWS File</a>, Previous: <a href="#Manual-Credits" accesskey="p" rel="prev">Manual Credits</a>, Up: <a href="#Documentation" accesskey="u" rel="up">Documentation</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p> |
| </div> |
| <a name="Printed-Manuals-1"></a> |
| <h3 class="section">6.6 Printed Manuals</h3> |
| |
| <p>The FSF publishes some GNU manuals in printed form. To encourage sales |
| of these manuals, the on-line versions of the manual should mention at |
| the very start that the printed manual is available and should point at |
| information for getting it—for instance, with a link to the page |
| <a href="http://www.gnu.org/order/order.html">http://www.gnu.org/order/order.html</a>. This should not be included |
| in the printed manual, though, because there it is redundant. |
| </p> |
| <p>It is also useful to explain in the on-line forms of the manual how the |
| user can print out the manual from the sources. |
| </p> |
| <hr> |
| <a name="NEWS-File"></a> |
| <div class="header"> |
| <p> |
| Next: <a href="#Change-Logs" accesskey="n" rel="next">Change Logs</a>, Previous: <a href="#Printed-Manuals" accesskey="p" rel="prev">Printed Manuals</a>, Up: <a href="#Documentation" accesskey="u" rel="up">Documentation</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p> |
| </div> |
| <a name="The-NEWS-File"></a> |
| <h3 class="section">6.7 The NEWS File</h3> |
| <a name="index-NEWS-file"></a> |
| |
| <p>In addition to its manual, the package should have a file named |
| <samp>NEWS</samp> which contains a list of user-visible changes worth |
| mentioning. In each new release, add items to the front of the file and |
| identify the version they pertain to. Don’t discard old items; leave |
| them in the file after the newer items. This way, a user upgrading from |
| any previous version can see what is new. |
| </p> |
| <p>If the <samp>NEWS</samp> file gets very long, move some of the older items |
| into a file named <samp>ONEWS</samp> and put a note at the end referring the |
| user to that file. |
| </p> |
| <hr> |
| <a name="Change-Logs"></a> |
| <div class="header"> |
| <p> |
| Next: <a href="#Man-Pages" accesskey="n" rel="next">Man Pages</a>, Previous: <a href="#NEWS-File" accesskey="p" rel="prev">NEWS File</a>, Up: <a href="#Documentation" accesskey="u" rel="up">Documentation</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p> |
| </div> |
| <a name="Change-Logs-1"></a> |
| <h3 class="section">6.8 Change Logs</h3> |
| <a name="index-change-logs"></a> |
| |
| <p>Keep a change log to describe all the changes made to program source |
| files. The purpose of this is so that people investigating bugs in the |
| future will know about the changes that might have introduced the bug. |
| Often a new bug can be found by looking at what was recently changed. |
| More importantly, change logs can help you eliminate conceptual |
| inconsistencies between different parts of a program, by giving you a |
| history of how the conflicting concepts arose and who they came from. |
| </p> |
| <table class="menu" border="0" cellspacing="0"> |
| <tr><td align="left" valign="top">• <a href="#Change-Log-Concepts" accesskey="1">Change Log Concepts</a>:</td><td> </td><td align="left" valign="top"> |
| </td></tr> |
| <tr><td align="left" valign="top">• <a href="#Style-of-Change-Logs" accesskey="2">Style of Change Logs</a>:</td><td> </td><td align="left" valign="top"> |
| </td></tr> |
| <tr><td align="left" valign="top">• <a href="#Simple-Changes" accesskey="3">Simple Changes</a>:</td><td> </td><td align="left" valign="top"> |
| </td></tr> |
| <tr><td align="left" valign="top">• <a href="#Conditional-Changes" accesskey="4">Conditional Changes</a>:</td><td> </td><td align="left" valign="top"> |
| </td></tr> |
| <tr><td align="left" valign="top">• <a href="#Indicating-the-Part-Changed" accesskey="5">Indicating the Part Changed</a>:</td><td> </td><td align="left" valign="top"> |
| </td></tr> |
| </table> |
| |
| <hr> |
| <a name="Change-Log-Concepts"></a> |
| <div class="header"> |
| <p> |
| Next: <a href="#Style-of-Change-Logs" accesskey="n" rel="next">Style of Change Logs</a>, Up: <a href="#Change-Logs" accesskey="u" rel="up">Change Logs</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p> |
| </div> |
| <a name="Change-Log-Concepts-1"></a> |
| <h4 class="subsection">6.8.1 Change Log Concepts</h4> |
| |
| <p>You can think of the change log as a conceptual “undo list” which |
| explains how earlier versions were different from the current version. |
| People can see the current version; they don’t need the change log |
| to tell them what is in it. What they want from a change log is a |
| clear explanation of how the earlier version differed. |
| </p> |
| <p>The change log file is normally called <samp>ChangeLog</samp> and covers an |
| entire directory. Each directory can have its own change log, or a |
| directory can use the change log of its parent directory—it’s up to |
| you. |
| </p> |
| <p>Another alternative is to record change log information with a version |
| control system such as RCS or CVS. This can be converted automatically |
| to a <samp>ChangeLog</samp> file using <code>rcs2log</code>; in Emacs, the command |
| <kbd>C-x v a</kbd> (<code>vc-update-change-log</code>) does the job. |
| </p> |
| <p>There’s no need to describe the full purpose of the changes or how |
| they work together. However, sometimes it is useful to write one line |
| to describe the overall purpose of a change or a batch of changes. If |
| you think that a change calls for explanation, you’re probably right. |
| Please do explain it—but please put the full explanation in comments |
| in the code, where people will see it whenever they see the code. For |
| example, “New function” is enough for the change log when you add a |
| function, because there should be a comment before the function |
| definition to explain what it does. |
| </p> |
| <p>In the past, we recommended not mentioning changes in non-software |
| files (manuals, help files, etc.) in change logs. However, we’ve been |
| advised that it is a good idea to include them, for the sake of |
| copyright records. |
| </p> |
| <p>The easiest way to add an entry to <samp>ChangeLog</samp> is with the Emacs |
| command <kbd>M-x add-change-log-entry</kbd>. An entry should have an |
| asterisk, the name of the changed file, and then in parentheses the name |
| of the changed functions, variables or whatever, followed by a colon. |
| Then describe the changes you made to that function or variable. |
| </p> |
| <hr> |
| <a name="Style-of-Change-Logs"></a> |
| <div class="header"> |
| <p> |
| Next: <a href="#Simple-Changes" accesskey="n" rel="next">Simple Changes</a>, Previous: <a href="#Change-Log-Concepts" accesskey="p" rel="prev">Change Log Concepts</a>, Up: <a href="#Change-Logs" accesskey="u" rel="up">Change Logs</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p> |
| </div> |
| <a name="Style-of-Change-Logs-1"></a> |
| <h4 class="subsection">6.8.2 Style of Change Logs</h4> |
| <a name="index-change-logs_002c-style"></a> |
| |
| <p>Here are some simple examples of change log entries, starting with the |
| header line that says who made the change and when it was installed, |
| followed by descriptions of specific changes. (These examples are |
| drawn from Emacs and GCC.) |
| </p> |
| <div class="example"> |
| <pre class="example">1998-08-17 Richard Stallman <rms@gnu.org> |
| |
| * register.el (insert-register): Return nil. |
| (jump-to-register): Likewise. |
| |
| * sort.el (sort-subr): Return nil. |
| |
| * tex-mode.el (tex-bibtex-file, tex-file, tex-region): |
| Restart the tex shell if process is gone or stopped. |
| (tex-shell-running): New function. |
| |
| * expr.c (store_one_arg): Round size up for move_block_to_reg. |
| (expand_call): Round up when emitting USE insns. |
| * stmt.c (assign_parms): Round size up for move_block_from_reg. |
| </pre></div> |
| |
| <p>It’s important to name the changed function or variable in full. Don’t |
| abbreviate function or variable names, and don’t combine them. |
| Subsequent maintainers will often search for a function name to find all |
| the change log entries that pertain to it; if you abbreviate the name, |
| they won’t find it when they search. |
| </p> |
| <p>For example, some people are tempted to abbreviate groups of function |
| names by writing ‘<samp>* register.el ({insert,jump-to}-register)</samp>’; |
| this is not a good idea, since searching for <code>jump-to-register</code> or |
| <code>insert-register</code> would not find that entry. |
| </p> |
| <p>Separate unrelated change log entries with blank lines. When two |
| entries represent parts of the same change, so that they work together, |
| then don’t put blank lines between them. Then you can omit the file |
| name and the asterisk when successive entries are in the same file. |
| </p> |
| <p>Break long lists of function names by closing continued lines with |
| ‘<samp>)</samp>’, rather than ‘<samp>,</samp>’, and opening the continuation with |
| ‘<samp>(</samp>’ as in this example: |
| </p> |
| <div class="example"> |
| <pre class="example">* keyboard.c (menu_bar_items, tool_bar_items) |
| (Fexecute_extended_command): Deal with `keymap' property. |
| </pre></div> |
| |
| <p>When you install someone else’s changes, put the contributor’s name in |
| the change log entry rather than in the text of the entry. In other |
| words, write this: |
| </p> |
| <div class="example"> |
| <pre class="example">2002-07-14 John Doe <jdoe@gnu.org> |
| |
| * sewing.c: Make it sew. |
| </pre></div> |
| |
| <p>rather than this: |
| </p> |
| <div class="example"> |
| <pre class="example">2002-07-14 Usual Maintainer <usual@gnu.org> |
| |
| * sewing.c: Make it sew. Patch by jdoe@gnu.org. |
| </pre></div> |
| |
| <p>As for the date, that should be the date you applied the change. |
| </p> |
| <hr> |
| <a name="Simple-Changes"></a> |
| <div class="header"> |
| <p> |
| Next: <a href="#Conditional-Changes" accesskey="n" rel="next">Conditional Changes</a>, Previous: <a href="#Style-of-Change-Logs" accesskey="p" rel="prev">Style of Change Logs</a>, Up: <a href="#Change-Logs" accesskey="u" rel="up">Change Logs</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p> |
| </div> |
| <a name="Simple-Changes-1"></a> |
| <h4 class="subsection">6.8.3 Simple Changes</h4> |
| |
| <p>Certain simple kinds of changes don’t need much detail in the change |
| log. |
| </p> |
| <p>When you change the calling sequence of a function in a simple fashion, |
| and you change all the callers of the function to use the new calling |
| sequence, there is no need to make individual entries for all the |
| callers that you changed. Just write in the entry for the function |
| being called, “All callers changed”—like this: |
| </p> |
| <div class="example"> |
| <pre class="example">* keyboard.c (Fcommand_execute): New arg SPECIAL. |
| All callers changed. |
| </pre></div> |
| |
| <p>When you change just comments or doc strings, it is enough to write an |
| entry for the file, without mentioning the functions. Just “Doc |
| fixes” is enough for the change log. |
| </p> |
| <p>There’s no technical need to make change log entries for documentation |
| files. This is because documentation is not susceptible to bugs that |
| are hard to fix. Documentation does not consist of parts that must |
| interact in a precisely engineered fashion. To correct an error, you |
| need not know the history of the erroneous passage; it is enough to |
| compare what the documentation says with the way the program actually |
| works. |
| </p> |
| <p>However, you should keep change logs for documentation files when the |
| project gets copyright assignments from its contributors, so as to |
| make the records of authorship more accurate. |
| </p> |
| <hr> |
| <a name="Conditional-Changes"></a> |
| <div class="header"> |
| <p> |
| Next: <a href="#Indicating-the-Part-Changed" accesskey="n" rel="next">Indicating the Part Changed</a>, Previous: <a href="#Simple-Changes" accesskey="p" rel="prev">Simple Changes</a>, Up: <a href="#Change-Logs" accesskey="u" rel="up">Change Logs</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p> |
| </div> |
| <a name="Conditional-Changes-1"></a> |
| <h4 class="subsection">6.8.4 Conditional Changes</h4> |
| <a name="index-conditional-changes_002c-and-change-logs"></a> |
| <a name="index-change-logs_002c-conditional-changes"></a> |
| |
| <p>C programs often contain compile-time <code>#if</code> conditionals. Many |
| changes are conditional; sometimes you add a new definition which is |
| entirely contained in a conditional. It is very useful to indicate in |
| the change log the conditions for which the change applies. |
| </p> |
| <p>Our convention for indicating conditional changes is to use square |
| brackets around the name of the condition. |
| </p> |
| <p>Here is a simple example, describing a change which is conditional but |
| does not have a function or entity name associated with it: |
| </p> |
| <div class="example"> |
| <pre class="example">* xterm.c [SOLARIS2]: Include string.h. |
| </pre></div> |
| |
| <p>Here is an entry describing a new definition which is entirely |
| conditional. This new definition for the macro <code>FRAME_WINDOW_P</code> is |
| used only when <code>HAVE_X_WINDOWS</code> is defined: |
| </p> |
| <div class="example"> |
| <pre class="example">* frame.h [HAVE_X_WINDOWS] (FRAME_WINDOW_P): Macro defined. |
| </pre></div> |
| |
| <p>Here is an entry for a change within the function <code>init_display</code>, |
| whose definition as a whole is unconditional, but the changes themselves |
| are contained in a ‘<samp>#ifdef HAVE_LIBNCURSES</samp>’ conditional: |
| </p> |
| <div class="example"> |
| <pre class="example">* dispnew.c (init_display) [HAVE_LIBNCURSES]: If X, call tgetent. |
| </pre></div> |
| |
| <p>Here is an entry for a change that takes affect only when |
| a certain macro is <em>not</em> defined: |
| </p> |
| <div class="example"> |
| <pre class="example">(gethostname) [!HAVE_SOCKETS]: Replace with winsock version. |
| </pre></div> |
| |
| <hr> |
| <a name="Indicating-the-Part-Changed"></a> |
| <div class="header"> |
| <p> |
| Previous: <a href="#Conditional-Changes" accesskey="p" rel="prev">Conditional Changes</a>, Up: <a href="#Change-Logs" accesskey="u" rel="up">Change Logs</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p> |
| </div> |
| <a name="Indicating-the-Part-Changed-1"></a> |
| <h4 class="subsection">6.8.5 Indicating the Part Changed</h4> |
| |
| <p>Indicate the part of a function which changed by using angle brackets |
| enclosing an indication of what the changed part does. Here is an entry |
| for a change in the part of the function <code>sh-while-getopts</code> that |
| deals with <code>sh</code> commands: |
| </p> |
| <div class="example"> |
| <pre class="example">* progmodes/sh-script.el (sh-while-getopts) <sh>: Handle case that |
| user-specified option string is empty. |
| </pre></div> |
| |
| |
| <hr> |
| <a name="Man-Pages"></a> |
| <div class="header"> |
| <p> |
| Next: <a href="#Reading-other-Manuals" accesskey="n" rel="next">Reading other Manuals</a>, Previous: <a href="#Change-Logs" accesskey="p" rel="prev">Change Logs</a>, Up: <a href="#Documentation" accesskey="u" rel="up">Documentation</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p> |
| </div> |
| <a name="Man-Pages-1"></a> |
| <h3 class="section">6.9 Man Pages</h3> |
| <a name="index-man-pages"></a> |
| |
| <p>In the GNU project, man pages are secondary. It is not necessary or |
| expected for every GNU program to have a man page, but some of them do. |
| It’s your choice whether to include a man page in your program. |
| </p> |
| <p>When you make this decision, consider that supporting a man page |
| requires continual effort each time the program is changed. The time |
| you spend on the man page is time taken away from more useful work. |
| </p> |
| <p>For a simple program which changes little, updating the man page may be |
| a small job. Then there is little reason not to include a man page, if |
| you have one. |
| </p> |
| <p>For a large program that changes a great deal, updating a man page may |
| be a substantial burden. If a user offers to donate a man page, you may |
| find this gift costly to accept. It may be better to refuse the man |
| page unless the same person agrees to take full responsibility for |
| maintaining it—so that you can wash your hands of it entirely. If |
| this volunteer later ceases to do the job, then don’t feel obliged to |
| pick it up yourself; it may be better to withdraw the man page from the |
| distribution until someone else agrees to update it. |
| </p> |
| <p>When a program changes only a little, you may feel that the |
| discrepancies are small enough that the man page remains useful without |
| updating. If so, put a prominent note near the beginning of the man |
| page explaining that you don’t maintain it and that the Texinfo manual |
| is more authoritative. The note should say how to access the Texinfo |
| documentation. |
| </p> |
| <p>Be sure that man pages include a copyright statement and free license. |
| The simple all-permissive license is appropriate for simple man pages |
| (see <a href="http://www.gnu.org/prep/maintain/maintain.html#License-Notices-for-Other-Files">License Notices for Other Files</a> in <cite>Information for GNU |
| Maintainers</cite>). |
| </p> |
| <p>For long man pages, with enough explanation and documentation that |
| they can be considered true manuals, use the GFDL (see <a href="#License-for-Manuals">License for Manuals</a>). |
| </p> |
| <p>Finally, the GNU help2man program |
| (<a href="http://www.gnu.org/software/help2man/">http://www.gnu.org/software/help2man/</a>) is one way to automate |
| generation of a man page, in this case from <samp>--help</samp> output. |
| This is sufficient in many cases. |
| </p> |
| <hr> |
| <a name="Reading-other-Manuals"></a> |
| <div class="header"> |
| <p> |
| Previous: <a href="#Man-Pages" accesskey="p" rel="prev">Man Pages</a>, Up: <a href="#Documentation" accesskey="u" rel="up">Documentation</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p> |
| </div> |
| <a name="Reading-other-Manuals-1"></a> |
| <h3 class="section">6.10 Reading other Manuals</h3> |
| |
| <p>There may be non-free books or documentation files that describe the |
| program you are documenting. |
| </p> |
| <p>It is ok to use these documents for reference, just as the author of a |
| new algebra textbook can read other books on algebra. A large portion |
| of any non-fiction book consists of facts, in this case facts about how |
| a certain program works, and these facts are necessarily the same for |
| everyone who writes about the subject. But be careful not to copy your |
| outline structure, wording, tables or examples from preexisting non-free |
| documentation. Copying from free documentation may be ok; please check |
| with the FSF about the individual case. |
| </p> |
| <hr> |
| <a name="Managing-Releases"></a> |
| <div class="header"> |
| <p> |
| Next: <a href="#References" accesskey="n" rel="next">References</a>, Previous: <a href="#Documentation" accesskey="p" rel="prev">Documentation</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p> |
| </div> |
| <a name="The-Release-Process"></a> |
| <h2 class="chapter">7 The Release Process</h2> |
| <a name="index-releasing"></a> |
| |
| <p>Making a release is more than just bundling up your source files in a |
| tar file and putting it up for FTP. You should set up your software so |
| that it can be configured to run on a variety of systems. Your Makefile |
| should conform to the GNU standards described below, and your directory |
| layout should also conform to the standards discussed below. Doing so |
| makes it easy to include your package into the larger framework of |
| all GNU software. |
| </p> |
| <table class="menu" border="0" cellspacing="0"> |
| <tr><td align="left" valign="top">• <a href="#Configuration" accesskey="1">Configuration</a>:</td><td> </td><td align="left" valign="top">How configuration of GNU packages should work. |
| </td></tr> |
| <tr><td align="left" valign="top">• <a href="#Makefile-Conventions" accesskey="2">Makefile Conventions</a>:</td><td> </td><td align="left" valign="top">Makefile conventions. |
| </td></tr> |
| <tr><td align="left" valign="top">• <a href="#Releases" accesskey="3">Releases</a>:</td><td> </td><td align="left" valign="top">Making releases |
| </td></tr> |
| </table> |
| |
| <hr> |
| <a name="Configuration"></a> |
| <div class="header"> |
| <p> |
| Next: <a href="#Makefile-Conventions" accesskey="n" rel="next">Makefile Conventions</a>, Up: <a href="#Managing-Releases" accesskey="u" rel="up">Managing Releases</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p> |
| </div> |
| <a name="How-Configuration-Should-Work"></a> |
| <h3 class="section">7.1 How Configuration Should Work</h3> |
| <a name="index-program-configuration"></a> |
| |
| <a name="index-configure"></a> |
| <p>Each GNU distribution should come with a shell script named |
| <code>configure</code>. This script is given arguments which describe the |
| kind of machine and system you want to compile the program for. |
| The <code>configure</code> script must record the configuration options so |
| that they affect compilation. |
| </p> |
| <p>The description here is the specification of the interface for the |
| <code>configure</code> script in GNU packages. Many packages implement it |
| using GNU Autoconf (see <a href="http://www.gnu.org/software/autoconf/manual/autoconf.html#Top">Introduction</a> in <cite>Autoconf</cite>) |
| and/or GNU Automake (see <a href="http://www.gnu.org/software/automake/manual/automake.html#Top">Introduction</a> in <cite>Automake</cite>), |
| but you do not have to use these tools. You can implement it any way |
| you like; for instance, by making <code>configure</code> be a wrapper around |
| a completely different configuration system. |
| </p> |
| <p>Another way for the <code>configure</code> script to operate is to make a |
| link from a standard name such as <samp>config.h</samp> to the proper |
| configuration file for the chosen system. If you use this technique, |
| the distribution should <em>not</em> contain a file named |
| <samp>config.h</samp>. This is so that people won’t be able to build the |
| program without configuring it first. |
| </p> |
| <p>Another thing that <code>configure</code> can do is to edit the Makefile. If |
| you do this, the distribution should <em>not</em> contain a file named |
| <samp>Makefile</samp>. Instead, it should include a file <samp>Makefile.in</samp> which |
| contains the input used for editing. Once again, this is so that people |
| won’t be able to build the program without configuring it first. |
| </p> |
| <p>If <code>configure</code> does write the <samp>Makefile</samp>, then <samp>Makefile</samp> |
| should have a target named <samp>Makefile</samp> which causes <code>configure</code> |
| to be rerun, setting up the same configuration that was set up last |
| time. The files that <code>configure</code> reads should be listed as |
| dependencies of <samp>Makefile</samp>. |
| </p> |
| <p>All the files which are output from the <code>configure</code> script should |
| have comments at the beginning explaining that they were generated |
| automatically using <code>configure</code>. This is so that users won’t think |
| of trying to edit them by hand. |
| </p> |
| <p>The <code>configure</code> script should write a file named <samp>config.status</samp> |
| which describes which configuration options were specified when the |
| program was last configured. This file should be a shell script which, |
| if run, will recreate the same configuration. |
| </p> |
| <p>The <code>configure</code> script should accept an option of the form |
| ‘<samp>--srcdir=<var>dirname</var></samp>’ to specify the directory where sources are found |
| (if it is not the current directory). This makes it possible to build |
| the program in a separate directory, so that the actual source directory |
| is not modified. |
| </p> |
| <p>If the user does not specify ‘<samp>--srcdir</samp>’, then <code>configure</code> should |
| check both <samp>.</samp> and <samp>..</samp> to see if it can find the sources. If |
| it finds the sources in one of these places, it should use them from |
| there. Otherwise, it should report that it cannot find the sources, and |
| should exit with nonzero status. |
| </p> |
| <p>Usually the easy way to support ‘<samp>--srcdir</samp>’ is by editing a |
| definition of <code>VPATH</code> into the Makefile. Some rules may need to |
| refer explicitly to the specified source directory. To make this |
| possible, <code>configure</code> can add to the Makefile a variable named |
| <code>srcdir</code> whose value is precisely the specified directory. |
| </p> |
| <p>In addition, the ‘<samp>configure</samp>’ script should take options |
| corresponding to most of the standard directory variables |
| (see <a href="#Directory-Variables">Directory Variables</a>). Here is the list: |
| </p> |
| <div class="example"> |
| <pre class="example">--prefix --exec-prefix --bindir --sbindir --libexecdir --sysconfdir |
| --sharedstatedir --localstatedir --libdir --includedir --oldincludedir |
| --datarootdir --datadir --infodir --localedir --mandir --docdir |
| --htmldir --dvidir --pdfdir --psdir |
| </pre></div> |
| |
| <p>The <code>configure</code> script should also take an argument which specifies the |
| type of system to build the program for. This argument should look like |
| this: |
| </p> |
| <div class="example"> |
| <pre class="example"><var>cpu</var>-<var>company</var>-<var>system</var> |
| </pre></div> |
| |
| <p>For example, an Athlon-based GNU/Linux system might be |
| ‘<samp>i686-pc-linux-gnu</samp>’. |
| </p> |
| <p>The <code>configure</code> script needs to be able to decode all plausible |
| alternatives for how to describe a machine. Thus, |
| ‘<samp>athlon-pc-gnu/linux</samp>’ would be a valid alias. There is a shell |
| script called |
| <a href="http://git.savannah.gnu.org/gitweb/?p=config.git;a=blob_plain;f=config.sub;hb=HEAD"><samp>config.sub</samp></a> that you can use as a subroutine to validate system |
| types and canonicalize aliases. |
| </p> |
| <p>The <code>configure</code> script should also take the option |
| <samp>--build=<var>buildtype</var></samp>, which should be equivalent to a |
| plain <var>buildtype</var> argument. For example, ‘<samp>configure |
| --build=i686-pc-linux-gnu</samp>’ is equivalent to ‘<samp>configure |
| i686-pc-linux-gnu</samp>’. When the build type is not specified by an option |
| or argument, the <code>configure</code> script should normally guess it using |
| the shell script |
| <a href="http://git.savannah.gnu.org/gitweb/?p=config.git;a=blob_plain;f=config.guess;hb=HEAD"><samp>config.guess</samp></a>. |
| </p> |
| <a name="index-optional-features_002c-configure_002dtime"></a> |
| <p>Other options are permitted to specify in more detail the software |
| or hardware present on the machine, to include or exclude optional parts |
| of the package, or to adjust the name of some tools or arguments to them: |
| </p> |
| <dl compact="compact"> |
| <dt>‘<samp>--enable-<var>feature</var><span class="roman">[</span>=<var>parameter</var><span class="roman">]</span></samp>’</dt> |
| <dd><p>Configure the package to build and install an optional user-level |
| facility called <var>feature</var>. This allows users to choose which |
| optional features to include. Giving an optional <var>parameter</var> of |
| ‘<samp>no</samp>’ should omit <var>feature</var>, if it is built by default. |
| </p> |
| <p>No ‘<samp>--enable</samp>’ option should <strong>ever</strong> cause one feature to |
| replace another. No ‘<samp>--enable</samp>’ option should ever substitute one |
| useful behavior for another useful behavior. The only proper use for |
| ‘<samp>--enable</samp>’ is for questions of whether to build part of the program |
| or exclude it. |
| </p> |
| </dd> |
| <dt>‘<samp>--with-<var>package</var></samp>’</dt> |
| <dd><p>The package <var>package</var> will be installed, so configure this package |
| to work with <var>package</var>. |
| </p> |
| |
| <p>Possible values of <var>package</var> include |
| ‘<samp>gnu-as</samp>’ (or ‘<samp>gas</samp>’), ‘<samp>gnu-ld</samp>’, ‘<samp>gnu-libc</samp>’, |
| ‘<samp>gdb</samp>’, |
| ‘<samp>x</samp>’, |
| and |
| ‘<samp>x-toolkit</samp>’. |
| </p> |
| <p>Do not use a ‘<samp>--with</samp>’ option to specify the file name to use to |
| find certain files. That is outside the scope of what ‘<samp>--with</samp>’ |
| options are for. |
| </p> |
| </dd> |
| <dt>‘<samp><var>variable</var>=<var>value</var></samp>’</dt> |
| <dd><p>Set the value of the variable <var>variable</var> to <var>value</var>. This is |
| used to override the default values of commands or arguments in the |
| build process. For example, the user could issue ‘<samp>configure |
| CFLAGS=-g CXXFLAGS=-g</samp>’ to build with debugging information and without |
| the default optimization. |
| </p> |
| <p>Specifying variables as arguments to <code>configure</code>, like this: |
| </p><div class="example"> |
| <pre class="example">./configure CC=gcc |
| </pre></div> |
| <p>is preferable to setting them in environment variables: |
| </p><div class="example"> |
| <pre class="example">CC=gcc ./configure |
| </pre></div> |
| <p>as it helps to recreate the same configuration later with |
| <samp>config.status</samp>. However, both methods should be supported. |
| </p></dd> |
| </dl> |
| |
| <p>All <code>configure</code> scripts should accept all of the “detail” |
| options and the variable settings, whether or not they make any |
| difference to the particular package at hand. In particular, they |
| should accept any option that starts with ‘<samp>--with-</samp>’ or |
| ‘<samp>--enable-</samp>’. This is so users will be able to configure an |
| entire GNU source tree at once with a single set of options. |
| </p> |
| <p>You will note that the categories ‘<samp>--with-</samp>’ and ‘<samp>--enable-</samp>’ |
| are narrow: they <strong>do not</strong> provide a place for any sort of option |
| you might think of. That is deliberate. We want to limit the possible |
| configuration options in GNU software. We do not want GNU programs to |
| have idiosyncratic configuration options. |
| </p> |
| <p>Packages that perform part of the compilation process may support |
| cross-compilation. In such a case, the host and target machines for the |
| program may be different. |
| </p> |
| <p>The <code>configure</code> script should normally treat the specified type of |
| system as both the host and the target, thus producing a program which |
| works for the same type of machine that it runs on. |
| </p> |
| <p>To compile a program to run on a host type that differs from the build |
| type, use the configure option <samp>--host=<var>hosttype</var></samp>, where |
| <var>hosttype</var> uses the same syntax as <var>buildtype</var>. The host type |
| normally defaults to the build type. |
| </p> |
| <p>To configure a cross-compiler, cross-assembler, or what have you, you |
| should specify a target different from the host, using the configure |
| option ‘<samp>--target=<var>targettype</var></samp>’. The syntax for |
| <var>targettype</var> is the same as for the host type. So the command would |
| look like this: |
| </p> |
| <div class="example"> |
| <pre class="example">./configure --host=<var>hosttype</var> --target=<var>targettype</var> |
| </pre></div> |
| |
| <p>The target type normally defaults to the host type. |
| Programs for which cross-operation is not meaningful need not accept the |
| ‘<samp>--target</samp>’ option, because configuring an entire operating system for |
| cross-operation is not a meaningful operation. |
| </p> |
| <p>Some programs have ways of configuring themselves automatically. If |
| your program is set up to do this, your <code>configure</code> script can simply |
| ignore most of its arguments. |
| </p> |
| |
| <hr> |
| <a name="Makefile-Conventions"></a> |
| <div class="header"> |
| <p> |
| Next: <a href="#Releases" accesskey="n" rel="next">Releases</a>, Previous: <a href="#Configuration" accesskey="p" rel="prev">Configuration</a>, Up: <a href="#Managing-Releases" accesskey="u" rel="up">Managing Releases</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p> |
| </div> |
| <a name="Makefile-Conventions-1"></a> |
| <h3 class="section">7.2 Makefile Conventions</h3> |
| <a name="index-makefile_002c-conventions-for"></a> |
| <a name="index-conventions-for-makefiles"></a> |
| <a name="index-standards-for-makefiles"></a> |
| |
| |
| |
| <p>This |
| describes conventions for writing the Makefiles for GNU programs. |
| Using Automake will help you write a Makefile that follows these |
| conventions. |
| </p> |
| <table class="menu" border="0" cellspacing="0"> |
| <tr><td align="left" valign="top">• <a href="#Makefile-Basics" accesskey="1">Makefile Basics</a>:</td><td> </td><td align="left" valign="top">General conventions for Makefiles. |
| </td></tr> |
| <tr><td align="left" valign="top">• <a href="#Utilities-in-Makefiles" accesskey="2">Utilities in Makefiles</a>:</td><td> </td><td align="left" valign="top">Utilities to be used in Makefiles. |
| </td></tr> |
| <tr><td align="left" valign="top">• <a href="#Command-Variables" accesskey="3">Command Variables</a>:</td><td> </td><td align="left" valign="top">Variables for specifying commands. |
| </td></tr> |
| <tr><td align="left" valign="top">• <a href="#DESTDIR" accesskey="4">DESTDIR</a>:</td><td> </td><td align="left" valign="top">Supporting staged installs. |
| </td></tr> |
| <tr><td align="left" valign="top">• <a href="#Directory-Variables" accesskey="5">Directory Variables</a>:</td><td> </td><td align="left" valign="top">Variables for installation directories. |
| </td></tr> |
| <tr><td align="left" valign="top">• <a href="#Standard-Targets" accesskey="6">Standard Targets</a>:</td><td> </td><td align="left" valign="top">Standard targets for users. |
| </td></tr> |
| <tr><td align="left" valign="top">• <a href="#Install-Command-Categories" accesskey="7">Install Command Categories</a>:</td><td> </td><td align="left" valign="top">Three categories of commands in the ‘install’ |
| rule: normal, pre-install and post-install. |
| </td></tr> |
| </table> |
| |
| <hr> |
| <a name="Makefile-Basics"></a> |
| <div class="header"> |
| <p> |
| Next: <a href="#Utilities-in-Makefiles" accesskey="n" rel="next">Utilities in Makefiles</a>, Up: <a href="#Makefile-Conventions" accesskey="u" rel="up">Makefile Conventions</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p> |
| </div> |
| <a name="General-Conventions-for-Makefiles"></a> |
| <h4 class="subsection">7.2.1 General Conventions for Makefiles</h4> |
| |
| <p>Every Makefile should contain this line: |
| </p> |
| <div class="example"> |
| <pre class="example">SHELL = /bin/sh |
| </pre></div> |
| |
| <p>to avoid trouble on systems where the <code>SHELL</code> variable might be |
| inherited from the environment. (This is never a problem with GNU |
| <code>make</code>.) |
| </p> |
| <p>Different <code>make</code> programs have incompatible suffix lists and |
| implicit rules, and this sometimes creates confusion or misbehavior. So |
| it is a good idea to set the suffix list explicitly using only the |
| suffixes you need in the particular Makefile, like this: |
| </p> |
| <div class="example"> |
| <pre class="example">.SUFFIXES: |
| .SUFFIXES: .c .o |
| </pre></div> |
| |
| <p>The first line clears out the suffix list, the second introduces all |
| suffixes which may be subject to implicit rules in this Makefile. |
| </p> |
| <p>Don’t assume that <samp>.</samp> is in the path for command execution. When |
| you need to run programs that are a part of your package during the |
| make, please make sure that it uses <samp>./</samp> if the program is built as |
| part of the make or <samp>$(srcdir)/</samp> if the file is an unchanging part |
| of the source code. Without one of these prefixes, the current search |
| path is used. |
| </p> |
| <p>The distinction between <samp>./</samp> (the <em>build directory</em>) and |
| <samp>$(srcdir)/</samp> (the <em>source directory</em>) is important because |
| users can build in a separate directory using the ‘<samp>--srcdir</samp>’ option |
| to <samp>configure</samp>. A rule of the form: |
| </p> |
| <div class="smallexample"> |
| <pre class="smallexample">foo.1 : foo.man sedscript |
| sed -e sedscript foo.man > foo.1 |
| </pre></div> |
| |
| <p>will fail when the build directory is not the source directory, because |
| <samp>foo.man</samp> and <samp>sedscript</samp> are in the source directory. |
| </p> |
| <p>When using GNU <code>make</code>, relying on ‘<samp>VPATH</samp>’ to find the source |
| file will work in the case where there is a single dependency file, |
| since the <code>make</code> automatic variable ‘<samp>$<</samp>’ will represent the |
| source file wherever it is. (Many versions of <code>make</code> set ‘<samp>$<</samp>’ |
| only in implicit rules.) A Makefile target like |
| </p> |
| <div class="smallexample"> |
| <pre class="smallexample">foo.o : bar.c |
| $(CC) -I. -I$(srcdir) $(CFLAGS) -c bar.c -o foo.o |
| </pre></div> |
| |
| <p>should instead be written as |
| </p> |
| <div class="smallexample"> |
| <pre class="smallexample">foo.o : bar.c |
| $(CC) -I. -I$(srcdir) $(CFLAGS) -c $< -o $@ |
| </pre></div> |
| |
| <p>in order to allow ‘<samp>VPATH</samp>’ to work correctly. When the target has |
| multiple dependencies, using an explicit ‘<samp>$(srcdir)</samp>’ is the easiest |
| way to make the rule work well. For example, the target above for |
| <samp>foo.1</samp> is best written as: |
| </p> |
| <div class="smallexample"> |
| <pre class="smallexample">foo.1 : foo.man sedscript |
| sed -e $(srcdir)/sedscript $(srcdir)/foo.man > $@ |
| </pre></div> |
| |
| <p>GNU distributions usually contain some files which are not source |
| files—for example, Info files, and the output from Autoconf, Automake, |
| Bison or Flex. Since these files normally appear in the source |
| directory, they should always appear in the source directory, not in the |
| build directory. So Makefile rules to update them should put the |
| updated files in the source directory. |
| </p> |
| <p>However, if a file does not appear in the distribution, then the |
| Makefile should not put it in the source directory, because building a |
| program in ordinary circumstances should not modify the source directory |
| in any way. |
| </p> |
| <p>Try to make the build and installation targets, at least (and all their |
| subtargets) work correctly with a parallel <code>make</code>. |
| </p> |
| <hr> |
| <a name="Utilities-in-Makefiles"></a> |
| <div class="header"> |
| <p> |
| Next: <a href="#Command-Variables" accesskey="n" rel="next">Command Variables</a>, Previous: <a href="#Makefile-Basics" accesskey="p" rel="prev">Makefile Basics</a>, Up: <a href="#Makefile-Conventions" accesskey="u" rel="up">Makefile Conventions</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p> |
| </div> |
| <a name="Utilities-in-Makefiles-1"></a> |
| <h4 class="subsection">7.2.2 Utilities in Makefiles</h4> |
| |
| <p>Write the Makefile commands (and any shell scripts, such as |
| <code>configure</code>) to run in <code>sh</code>, not in <code>csh</code>. Don’t use any |
| special features of <code>ksh</code> or <code>bash</code>. |
| </p> |
| <p>The <code>configure</code> script and the Makefile rules for building and |
| installation should not use any utilities directly except these: |
| </p> |
| |
| <div class="example"> |
| <pre class="example">cat cmp cp diff echo egrep expr false grep install-info |
| ln ls mkdir mv pwd rm rmdir sed sleep sort tar test touch true |
| </pre></div> |
| |
| <p>The compression program <code>gzip</code> can be used in the <code>dist</code> rule. |
| </p> |
| <p>Stick to the generally supported options for these programs. For |
| example, don’t use ‘<samp>mkdir -p</samp>’, convenient as it may be, because |
| most systems don’t support it. |
| </p> |
| <p>It is a good idea to avoid creating symbolic links in makefiles, since a |
| few systems don’t support them. |
| </p> |
| <p>The Makefile rules for building and installation can also use compilers |
| and related programs, but should do so via <code>make</code> variables so that the |
| user can substitute alternatives. Here are some of the programs we |
| mean: |
| </p> |
| <div class="example"> |
| <pre class="example">ar bison cc flex install ld ldconfig lex |
| make makeinfo ranlib texi2dvi yacc |
| </pre></div> |
| |
| <p>Use the following <code>make</code> variables to run those programs: |
| </p> |
| <div class="example"> |
| <pre class="example">$(AR) $(BISON) $(CC) $(FLEX) $(INSTALL) $(LD) $(LDCONFIG) $(LEX) |
| $(MAKE) $(MAKEINFO) $(RANLIB) $(TEXI2DVI) $(YACC) |
| </pre></div> |
| |
| <p>When you use <code>ranlib</code> or <code>ldconfig</code>, you should make sure |
| nothing bad happens if the system does not have the program in question. |
| Arrange to ignore an error from that command, and print a message before |
| the command to tell the user that failure of this command does not mean |
| a problem. (The Autoconf ‘<samp>AC_PROG_RANLIB</samp>’ macro can help with |
| this.) |
| </p> |
| <p>If you use symbolic links, you should implement a fallback for systems |
| that don’t have symbolic links. |
| </p> |
| <p>Additional utilities that can be used via Make variables are: |
| </p> |
| <div class="example"> |
| <pre class="example">chgrp chmod chown mknod |
| </pre></div> |
| |
| <p>It is ok to use other utilities in Makefile portions (or scripts) |
| intended only for particular systems where you know those utilities |
| exist. |
| </p> |
| <hr> |
| <a name="Command-Variables"></a> |
| <div class="header"> |
| <p> |
| Next: <a href="#DESTDIR" accesskey="n" rel="next">DESTDIR</a>, Previous: <a href="#Utilities-in-Makefiles" accesskey="p" rel="prev">Utilities in Makefiles</a>, Up: <a href="#Makefile-Conventions" accesskey="u" rel="up">Makefile Conventions</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p> |
| </div> |
| <a name="Variables-for-Specifying-Commands"></a> |
| <h4 class="subsection">7.2.3 Variables for Specifying Commands</h4> |
| |
| <p>Makefiles should provide variables for overriding certain commands, options, |
| and so on. |
| </p> |
| <p>In particular, you should run most utility programs via variables. |
| Thus, if you use Bison, have a variable named <code>BISON</code> whose default |
| value is set with ‘<samp>BISON = bison</samp>’, and refer to it with |
| <code>$(BISON)</code> whenever you need to use Bison. |
| </p> |
| <p>File management utilities such as <code>ln</code>, <code>rm</code>, <code>mv</code>, and |
| so on, need not be referred to through variables in this way, since users |
| don’t need to replace them with other programs. |
| </p> |
| <p>Each program-name variable should come with an options variable that is |
| used to supply options to the program. Append ‘<samp>FLAGS</samp>’ to the |
| program-name variable name to get the options variable name—for |
| example, <code>BISONFLAGS</code>. (The names <code>CFLAGS</code> for the C |
| compiler, <code>YFLAGS</code> for yacc, and <code>LFLAGS</code> for lex, are |
| exceptions to this rule, but we keep them because they are standard.) |
| Use <code>CPPFLAGS</code> in any compilation command that runs the |
| preprocessor, and use <code>LDFLAGS</code> in any compilation command that |
| does linking as well as in any direct use of <code>ld</code>. |
| </p> |
| <p>If there are C compiler options that <em>must</em> be used for proper |
| compilation of certain files, do not include them in <code>CFLAGS</code>. |
| Users expect to be able to specify <code>CFLAGS</code> freely themselves. |
| Instead, arrange to pass the necessary options to the C compiler |
| independently of <code>CFLAGS</code>, by writing them explicitly in the |
| compilation commands or by defining an implicit rule, like this: |
| </p> |
| <div class="smallexample"> |
| <pre class="smallexample">CFLAGS = -g |
| ALL_CFLAGS = -I. $(CFLAGS) |
| .c.o: |
| $(CC) -c $(CPPFLAGS) $(ALL_CFLAGS) $< |
| </pre></div> |
| |
| <p>Do include the ‘<samp>-g</samp>’ option in <code>CFLAGS</code>, because that is not |
| <em>required</em> for proper compilation. You can consider it a default |
| that is only recommended. If the package is set up so that it is |
| compiled with GCC by default, then you might as well include ‘<samp>-O</samp>’ |
| in the default value of <code>CFLAGS</code> as well. |
| </p> |
| <p>Put <code>CFLAGS</code> last in the compilation command, after other variables |
| containing compiler options, so the user can use <code>CFLAGS</code> to |
| override the others. |
| </p> |
| <p><code>CFLAGS</code> should be used in every invocation of the C compiler, |
| both those which do compilation and those which do linking. |
| </p> |
| <p>Every Makefile should define the variable <code>INSTALL</code>, which is the |
| basic command for installing a file into the system. |
| </p> |
| <p>Every Makefile should also define the variables <code>INSTALL_PROGRAM</code> |
| and <code>INSTALL_DATA</code>. (The default for <code>INSTALL_PROGRAM</code> should |
| be <code>$(INSTALL)</code>; the default for <code>INSTALL_DATA</code> should be |
| <code>${INSTALL} -m 644</code>.) Then it should use those variables as the |
| commands for actual installation, for executables and non-executables |
| respectively. Minimal use of these variables is as follows: |
| </p> |
| <div class="example"> |
| <pre class="example">$(INSTALL_PROGRAM) foo $(bindir)/foo |
| $(INSTALL_DATA) libfoo.a $(libdir)/libfoo.a |
| </pre></div> |
| |
| <p>However, it is preferable to support a <code>DESTDIR</code> prefix on the |
| target files, as explained in the next section. |
| </p> |
| <p>Always use a file name, not a directory name, as the second argument of |
| the installation commands. Use a separate command for each file to be |
| installed. |
| </p> |
| |
| <hr> |
| <a name="DESTDIR"></a> |
| <div class="header"> |
| <p> |
| Next: <a href="#Directory-Variables" accesskey="n" rel="next">Directory Variables</a>, Previous: <a href="#Command-Variables" accesskey="p" rel="prev">Command Variables</a>, Up: <a href="#Makefile-Conventions" accesskey="u" rel="up">Makefile Conventions</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p> |
| </div> |
| <a name="DESTDIR_003a-support-for-staged-installs"></a> |
| <h4 class="subsection">7.2.4 <code>DESTDIR</code>: support for staged installs</h4> |
| |
| <a name="index-DESTDIR"></a> |
| <a name="index-staged-installs"></a> |
| <a name="index-installations_002c-staged"></a> |
| |
| <p><code>DESTDIR</code> is a variable prepended to each installed target file, |
| like this: |
| </p> |
| <div class="example"> |
| <pre class="example">$(INSTALL_PROGRAM) foo $(DESTDIR)$(bindir)/foo |
| $(INSTALL_DATA) libfoo.a $(DESTDIR)$(libdir)/libfoo.a |
| </pre></div> |
| |
| <p>The <code>DESTDIR</code> variable is specified by the user on the <code>make</code> |
| command line. For example: |
| </p> |
| <div class="example"> |
| <pre class="example">make DESTDIR=/tmp/stage install |
| </pre></div> |
| |
| <p><code>DESTDIR</code> should be supported only in the <code>install*</code> and |
| <code>uninstall*</code> targets, as those are the only targets where it is |
| useful. |
| </p> |
| <p>If your installation step would normally install |
| <samp>/usr/local/bin/foo</samp> and <samp>/usr/local/lib/libfoo.a</samp>, then an |
| installation invoked as in the example above would install |
| <samp>/tmp/stage/usr/local/bin/foo</samp> and |
| <samp>/tmp/stage/usr/local/lib/libfoo.a</samp> instead. |
| </p> |
| <p>Prepending the variable <code>DESTDIR</code> to each target in this way |
| provides for <em>staged installs</em>, where the installed files are not |
| placed directly into their expected location but are instead copied |
| into a temporary location (<code>DESTDIR</code>). However, installed files |
| maintain their relative directory structure and any embedded file names |
| will not be modified. |
| </p> |
| <p>You should not set the value of <code>DESTDIR</code> in your <samp>Makefile</samp> |
| at all; then the files are installed into their expected locations by |
| default. Also, specifying <code>DESTDIR</code> should not change the |
| operation of the software in any way, so its value should not be |
| included in any file contents. |
| </p> |
| <p><code>DESTDIR</code> support is commonly used in package creation. It is |
| also helpful to users who want to understand what a given package will |
| install where, and to allow users who don’t normally have permissions |
| to install into protected areas to build and install before gaining |
| those permissions. Finally, it can be useful with tools such as |
| <code>stow</code>, where code is installed in one place but made to appear |
| to be installed somewhere else using symbolic links or special mount |
| operations. So, we strongly recommend GNU packages support |
| <code>DESTDIR</code>, though it is not an absolute requirement. |
| </p> |
| |
| <hr> |
| <a name="Directory-Variables"></a> |
| <div class="header"> |
| <p> |
| Next: <a href="#Standard-Targets" accesskey="n" rel="next">Standard Targets</a>, Previous: <a href="#DESTDIR" accesskey="p" rel="prev">DESTDIR</a>, Up: <a href="#Makefile-Conventions" accesskey="u" rel="up">Makefile Conventions</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p> |
| </div> |
| <a name="Variables-for-Installation-Directories"></a> |
| <h4 class="subsection">7.2.5 Variables for Installation Directories</h4> |
| |
| <p>Installation directories should always be named by variables, so it is |
| easy to install in a nonstandard place. The standard names for these |
| variables and the values they should have in GNU packages are |
| described below. They are based on a standard file system layout; |
| variants of it are used in GNU/Linux and other modern operating |
| systems. |
| </p> |
| <p>Installers are expected to override these values when calling |
| <code>make</code> (e.g., <kbd>make prefix=/usr install</kbd> or |
| <code>configure</code> (e.g., <kbd>configure --prefix=/usr</kbd>). GNU |
| packages should not try to guess which value should be appropriate for |
| these variables on the system they are being installed onto: use the |
| default settings specified here so that all GNU packages behave |
| identically, allowing the installer to achieve any desired layout. |
| </p> |
| <p>These first two variables set the root for the installation. All the |
| other installation directories should be subdirectories of one of |
| these two, and nothing should be directly installed into these two |
| directories. |
| </p> |
| <dl compact="compact"> |
| <dt><code>prefix</code></dt> |
| <dd><a name="index-prefix"></a> |
| <p>A prefix used in constructing the default values of the variables listed |
| below. The default value of <code>prefix</code> should be <samp>/usr/local</samp>. |
| When building the complete GNU system, the prefix will be empty and |
| <samp>/usr</samp> will be a symbolic link to <samp>/</samp>. |
| (If you are using Autoconf, write it as ‘<samp>@prefix@</samp>’.) |
| </p> |
| <p>Running ‘<samp>make install</samp>’ with a different value of <code>prefix</code> from |
| the one used to build the program should <em>not</em> recompile the |
| program. |
| </p> |
| </dd> |
| <dt><code>exec_prefix</code></dt> |
| <dd><a name="index-exec_005fprefix"></a> |
| <p>A prefix used in constructing the default values of some of the |
| variables listed below. The default value of <code>exec_prefix</code> should |
| be <code>$(prefix)</code>. |
| (If you are using Autoconf, write it as ‘<samp>@exec_prefix@</samp>’.) |
| </p> |
| <p>Generally, <code>$(exec_prefix)</code> is used for directories that contain |
| machine-specific files (such as executables and subroutine libraries), |
| while <code>$(prefix)</code> is used directly for other directories. |
| </p> |
| <p>Running ‘<samp>make install</samp>’ with a different value of <code>exec_prefix</code> |
| from the one used to build the program should <em>not</em> recompile the |
| program. |
| </p></dd> |
| </dl> |
| |
| <p>Executable programs are installed in one of the following directories. |
| </p> |
| <dl compact="compact"> |
| <dt><code>bindir</code></dt> |
| <dd><a name="index-bindir"></a> |
| <p>The directory for installing executable programs that users can run. |
| This should normally be <samp>/usr/local/bin</samp>, but write it as |
| <samp>$(exec_prefix)/bin</samp>. |
| (If you are using Autoconf, write it as ‘<samp>@bindir@</samp>’.) |
| </p> |
| </dd> |
| <dt><code>sbindir</code></dt> |
| <dd><a name="index-sbindir"></a> |
| <p>The directory for installing executable programs that can be run from |
| the shell, but are only generally useful to system administrators. This |
| should normally be <samp>/usr/local/sbin</samp>, but write it as |
| <samp>$(exec_prefix)/sbin</samp>. |
| (If you are using Autoconf, write it as ‘<samp>@sbindir@</samp>’.) |
| </p> |
| </dd> |
| <dt><code>libexecdir</code></dt> |
| <dd><a name="index-libexecdir"></a> |
| <p>The directory for installing executable programs to be run by other |
| programs rather than by users. This directory should normally be |
| <samp>/usr/local/libexec</samp>, but write it as <samp>$(exec_prefix)/libexec</samp>. |
| (If you are using Autoconf, write it as ‘<samp>@libexecdir@</samp>’.) |
| </p> |
| <p>The definition of ‘<samp>libexecdir</samp>’ is the same for all packages, so |
| you should install your data in a subdirectory thereof. Most packages |
| install their data under <samp>$(libexecdir)/<var>package-name</var>/</samp>, |
| possibly within additional subdirectories thereof, such as |
| <samp>$(libexecdir)/<var>package-name</var>/<var>machine</var>/<var>version</var></samp>. |
| </p></dd> |
| </dl> |
| |
| <p>Data files used by the program during its execution are divided into |
| categories in two ways. |
| </p> |
| <ul> |
| <li> Some files are normally modified by programs; others are never normally |
| modified (though users may edit some of these). |
| |
| </li><li> Some files are architecture-independent and can be shared by all |
| machines at a site; some are architecture-dependent and can be shared |
| only by machines of the same kind and operating system; others may never |
| be shared between two machines. |
| </li></ul> |
| |
| <p>This makes for six different possibilities. However, we want to |
| discourage the use of architecture-dependent files, aside from object |
| files and libraries. It is much cleaner to make other data files |
| architecture-independent, and it is generally not hard. |
| </p> |
| <p>Here are the variables Makefiles should use to specify directories |
| to put these various kinds of files in: |
| </p> |
| <dl compact="compact"> |
| <dt>‘<samp>datarootdir</samp>’</dt> |
| <dd><p>The root of the directory tree for read-only architecture-independent |
| data files. This should normally be <samp>/usr/local/share</samp>, but |
| write it as <samp>$(prefix)/share</samp>. (If you are using Autoconf, write |
| it as ‘<samp>@datarootdir@</samp>’.) ‘<samp>datadir</samp>’’s default value is |
| based on this variable; so are ‘<samp>infodir</samp>’, ‘<samp>mandir</samp>’, and |
| others. |
| </p> |
| </dd> |
| <dt>‘<samp>datadir</samp>’</dt> |
| <dd><p>The directory for installing idiosyncratic read-only |
| architecture-independent data files for this program. This is usually |
| the same place as ‘<samp>datarootdir</samp>’, but we use the two separate |
| variables so that you can move these program-specific files without |
| altering the location for Info files, man pages, etc. |
| </p> |
| <p>This should normally be <samp>/usr/local/share</samp>, but write it as |
| <samp>$(datarootdir)</samp>. (If you are using Autoconf, write it as |
| ‘<samp>@datadir@</samp>’.) |
| </p> |
| <p>The definition of ‘<samp>datadir</samp>’ is the same for all packages, so you |
| should install your data in a subdirectory thereof. Most packages |
| install their data under <samp>$(datadir)/<var>package-name</var>/</samp>. |
| </p> |
| </dd> |
| <dt>‘<samp>sysconfdir</samp>’</dt> |
| <dd><p>The directory for installing read-only data files that pertain to a |
| single machine–that is to say, files for configuring a host. Mailer |
| and network configuration files, <samp>/etc/passwd</samp>, and so forth belong |
| here. All the files in this directory should be ordinary ASCII text |
| files. This directory should normally be <samp>/usr/local/etc</samp>, but |
| write it as <samp>$(prefix)/etc</samp>. |
| (If you are using Autoconf, write it as ‘<samp>@sysconfdir@</samp>’.) |
| </p> |
| <p>Do not install executables here in this directory (they probably belong |
| in <samp>$(libexecdir)</samp> or <samp>$(sbindir)</samp>). Also do not install |
| files that are modified in the normal course of their use (programs |
| whose purpose is to change the configuration of the system excluded). |
| Those probably belong in <samp>$(localstatedir)</samp>. |
| </p> |
| </dd> |
| <dt>‘<samp>sharedstatedir</samp>’</dt> |
| <dd><p>The directory for installing architecture-independent data files which |
| the programs modify while they run. This should normally be |
| <samp>/usr/local/com</samp>, but write it as <samp>$(prefix)/com</samp>. |
| (If you are using Autoconf, write it as ‘<samp>@sharedstatedir@</samp>’.) |
| </p> |
| </dd> |
| <dt>‘<samp>localstatedir</samp>’</dt> |
| <dd><p>The directory for installing data files which the programs modify while |
| they run, and that pertain to one specific machine. Users should never |
| need to modify files in this directory to configure the package’s |
| operation; put such configuration information in separate files that go |
| in <samp>$(datadir)</samp> or <samp>$(sysconfdir)</samp>. <samp>$(localstatedir)</samp> |
| should normally be <samp>/usr/local/var</samp>, but write it as |
| <samp>$(prefix)/var</samp>. |
| (If you are using Autoconf, write it as ‘<samp>@localstatedir@</samp>’.) |
| </p></dd> |
| </dl> |
| |
| <p>These variables specify the directory for installing certain specific |
| types of files, if your program has them. Every GNU package should |
| have Info files, so every program needs ‘<samp>infodir</samp>’, but not all |
| need ‘<samp>libdir</samp>’ or ‘<samp>lispdir</samp>’. |
| </p> |
| <dl compact="compact"> |
| <dt>‘<samp>includedir</samp>’</dt> |
| <dd><p>The directory for installing header files to be included by user |
| programs with the C ‘<samp>#include</samp>’ preprocessor directive. This |
| should normally be <samp>/usr/local/include</samp>, but write it as |
| <samp>$(prefix)/include</samp>. |
| (If you are using Autoconf, write it as ‘<samp>@includedir@</samp>’.) |
| </p> |
| <p>Most compilers other than GCC do not look for header files in directory |
| <samp>/usr/local/include</samp>. So installing the header files this way is |
| only useful with GCC. Sometimes this is not a problem because some |
| libraries are only really intended to work with GCC. But some libraries |
| are intended to work with other compilers. They should install their |
| header files in two places, one specified by <code>includedir</code> and one |
| specified by <code>oldincludedir</code>. |
| </p> |
| </dd> |
| <dt>‘<samp>oldincludedir</samp>’</dt> |
| <dd><p>The directory for installing ‘<samp>#include</samp>’ header files for use with |
| compilers other than GCC. This should normally be <samp>/usr/include</samp>. |
| (If you are using Autoconf, you can write it as ‘<samp>@oldincludedir@</samp>’.) |
| </p> |
| <p>The Makefile commands should check whether the value of |
| <code>oldincludedir</code> is empty. If it is, they should not try to use |
| it; they should cancel the second installation of the header files. |
| </p> |
| <p>A package should not replace an existing header in this directory unless |
| the header came from the same package. Thus, if your Foo package |
| provides a header file <samp>foo.h</samp>, then it should install the header |
| file in the <code>oldincludedir</code> directory if either (1) there is no |
| <samp>foo.h</samp> there or (2) the <samp>foo.h</samp> that exists came from the Foo |
| package. |
| </p> |
| <p>To tell whether <samp>foo.h</samp> came from the Foo package, put a magic |
| string in the file—part of a comment—and <code>grep</code> for that string. |
| </p> |
| </dd> |
| <dt>‘<samp>docdir</samp>’</dt> |
| <dd><p>The directory for installing documentation files (other than Info) for |
| this package. By default, it should be |
| <samp>/usr/local/share/doc/<var>yourpkg</var></samp>, but it should be written as |
| <samp>$(datarootdir)/doc/<var>yourpkg</var></samp>. (If you are using Autoconf, |
| write it as ‘<samp>@docdir@</samp>’.) The <var>yourpkg</var> subdirectory, which |
| may include a version number, prevents collisions among files with |
| common names, such as <samp>README</samp>. |
| </p> |
| </dd> |
| <dt>‘<samp>infodir</samp>’</dt> |
| <dd><p>The directory for installing the Info files for this package. By |
| default, it should be <samp>/usr/local/share/info</samp>, but it should be |
| written as <samp>$(datarootdir)/info</samp>. (If you are using Autoconf, |
| write it as ‘<samp>@infodir@</samp>’.) <code>infodir</code> is separate from |
| <code>docdir</code> for compatibility with existing practice. |
| </p> |
| </dd> |
| <dt>‘<samp>htmldir</samp>’</dt> |
| <dt>‘<samp>dvidir</samp>’</dt> |
| <dt>‘<samp>pdfdir</samp>’</dt> |
| <dt>‘<samp>psdir</samp>’</dt> |
| <dd><p>Directories for installing documentation files in the particular |
| format. They should all be set to <code>$(docdir)</code> by default. (If |
| you are using Autoconf, write them as ‘<samp>@htmldir@</samp>’, |
| ‘<samp>@dvidir@</samp>’, etc.) Packages which supply several translations |
| of their documentation should install them in |
| ‘<samp>$(htmldir)/</samp>’<var>ll</var>, ‘<samp>$(pdfdir)/</samp>’<var>ll</var>, etc. where |
| <var>ll</var> is a locale abbreviation such as ‘<samp>en</samp>’ or ‘<samp>pt_BR</samp>’. |
| </p> |
| </dd> |
| <dt>‘<samp>libdir</samp>’</dt> |
| <dd><p>The directory for object files and libraries of object code. Do not |
| install executables here, they probably ought to go in <samp>$(libexecdir)</samp> |
| instead. The value of <code>libdir</code> should normally be |
| <samp>/usr/local/lib</samp>, but write it as <samp>$(exec_prefix)/lib</samp>. |
| (If you are using Autoconf, write it as ‘<samp>@libdir@</samp>’.) |
| </p> |
| </dd> |
| <dt>‘<samp>lispdir</samp>’</dt> |
| <dd><p>The directory for installing any Emacs Lisp files in this package. By |
| default, it should be <samp>/usr/local/share/emacs/site-lisp</samp>, but it |
| should be written as <samp>$(datarootdir)/emacs/site-lisp</samp>. |
| </p> |
| <p>If you are using Autoconf, write the default as ‘<samp>@lispdir@</samp>’. |
| In order to make ‘<samp>@lispdir@</samp>’ work, you need the following lines |
| in your <samp>configure.in</samp> file: |
| </p> |
| <div class="example"> |
| <pre class="example">lispdir='${datarootdir}/emacs/site-lisp' |
| AC_SUBST(lispdir) |
| </pre></div> |
| |
| </dd> |
| <dt>‘<samp>localedir</samp>’</dt> |
| <dd><p>The directory for installing locale-specific message catalogs for this |
| package. By default, it should be <samp>/usr/local/share/locale</samp>, but |
| it should be written as <samp>$(datarootdir)/locale</samp>. (If you are |
| using Autoconf, write it as ‘<samp>@localedir@</samp>’.) This directory |
| usually has a subdirectory per locale. |
| </p></dd> |
| </dl> |
| |
| <p>Unix-style man pages are installed in one of the following: |
| </p> |
| <dl compact="compact"> |
| <dt>‘<samp>mandir</samp>’</dt> |
| <dd><p>The top-level directory for installing the man pages (if any) for this |
| package. It will normally be <samp>/usr/local/share/man</samp>, but you |
| should write it as <samp>$(datarootdir)/man</samp>. (If you are using |
| Autoconf, write it as ‘<samp>@mandir@</samp>’.) |
| </p> |
| </dd> |
| <dt>‘<samp>man1dir</samp>’</dt> |
| <dd><p>The directory for installing section 1 man pages. Write it as |
| <samp>$(mandir)/man1</samp>. |
| </p></dd> |
| <dt>‘<samp>man2dir</samp>’</dt> |
| <dd><p>The directory for installing section 2 man pages. Write it as |
| <samp>$(mandir)/man2</samp> |
| </p></dd> |
| <dt>‘<samp>…</samp>’</dt> |
| <dd> |
| <p><strong>Don’t make the primary documentation for any GNU software be a |
| man page. Write a manual in Texinfo instead. Man pages are just for |
| the sake of people running GNU software on Unix, which is a secondary |
| application only.</strong> |
| </p> |
| </dd> |
| <dt>‘<samp>manext</samp>’</dt> |
| <dd><p>The file name extension for the installed man page. This should contain |
| a period followed by the appropriate digit; it should normally be ‘<samp>.1</samp>’. |
| </p> |
| </dd> |
| <dt>‘<samp>man1ext</samp>’</dt> |
| <dd><p>The file name extension for installed section 1 man pages. |
| </p></dd> |
| <dt>‘<samp>man2ext</samp>’</dt> |
| <dd><p>The file name extension for installed section 2 man pages. |
| </p></dd> |
| <dt>‘<samp>…</samp>’</dt> |
| <dd><p>Use these names instead of ‘<samp>manext</samp>’ if the package needs to install man |
| pages in more than one section of the manual. |
| </p></dd> |
| </dl> |
| |
| <p>And finally, you should set the following variable: |
| </p> |
| <dl compact="compact"> |
| <dt>‘<samp>srcdir</samp>’</dt> |
| <dd><p>The directory for the sources being compiled. The value of this |
| variable is normally inserted by the <code>configure</code> shell script. |
| (If you are using Autoconf, use ‘<samp>srcdir = @srcdir@</samp>’.) |
| </p></dd> |
| </dl> |
| |
| <p>For example: |
| </p> |
| <div class="smallexample"> |
| <pre class="smallexample"># Common prefix for installation directories. |
| # NOTE: This directory must exist when you start the install. |
| prefix = /usr/local |
| datarootdir = $(prefix)/share |
| datadir = $(datarootdir) |
| exec_prefix = $(prefix) |
| # Where to put the executable for the command `gcc'. |
| bindir = $(exec_prefix)/bin |
| # Where to put the directories used by the compiler. |
| libexecdir = $(exec_prefix)/libexec |
| # Where to put the Info files. |
| infodir = $(datarootdir)/info |
| </pre></div> |
| |
| <p>If your program installs a large number of files into one of the |
| standard user-specified directories, it might be useful to group them |
| into a subdirectory particular to that program. If you do this, you |
| should write the <code>install</code> rule to create these subdirectories. |
| </p> |
| <p>Do not expect the user to include the subdirectory name in the value of |
| any of the variables listed above. The idea of having a uniform set of |
| variable names for installation directories is to enable the user to |
| specify the exact same values for several different GNU packages. In |
| order for this to be useful, all the packages must be designed so that |
| they will work sensibly when the user does so. |
| </p> |
| <p>At times, not all of these variables may be implemented in the current |
| release of Autoconf and/or Automake; but as of Autoconf 2.60, we |
| believe all of them are. When any are missing, the descriptions here |
| serve as specifications for what Autoconf will implement. As a |
| programmer, you can either use a development version of Autoconf or |
| avoid using these variables until a stable release is made which |
| supports them. |
| </p> |
| |
| <hr> |
| <a name="Standard-Targets"></a> |
| <div class="header"> |
| <p> |
| Next: <a href="#Install-Command-Categories" accesskey="n" rel="next">Install Command Categories</a>, Previous: <a href="#Directory-Variables" accesskey="p" rel="prev">Directory Variables</a>, Up: <a href="#Makefile-Conventions" accesskey="u" rel="up">Makefile Conventions</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p> |
| </div> |
| <a name="Standard-Targets-for-Users"></a> |
| <h4 class="subsection">7.2.6 Standard Targets for Users</h4> |
| |
| <p>All GNU programs should have the following targets in their Makefiles: |
| </p> |
| <dl compact="compact"> |
| <dt>‘<samp>all</samp>’</dt> |
| <dd><p>Compile the entire program. This should be the default target. This |
| target need not rebuild any documentation files; Info files should |
| normally be included in the distribution, and DVI (and other |
| documentation format) files should be made only when explicitly asked |
| for. |
| </p> |
| <p>By default, the Make rules should compile and link with ‘<samp>-g</samp>’, so |
| that executable programs have debugging symbols. Users who don’t mind |
| being helpless can strip the executables later if they wish. |
| </p> |
| </dd> |
| <dt>‘<samp>install</samp>’</dt> |
| <dd><p>Compile the program and copy the executables, libraries, and so on to |
| the file names where they should reside for actual use. If there is a |
| simple test to verify that a program is properly installed, this target |
| should run that test. |
| </p> |
| <p>Do not strip executables when installing them. Devil-may-care users can |
| use the <code>install-strip</code> target to do that. |
| </p> |
| <p>If possible, write the <code>install</code> target rule so that it does not |
| modify anything in the directory where the program was built, provided |
| ‘<samp>make all</samp>’ has just been done. This is convenient for building the |
| program under one user name and installing it under another. |
| </p> |
| <p>The commands should create all the directories in which files are to be |
| installed, if they don’t already exist. This includes the directories |
| specified as the values of the variables <code>prefix</code> and |
| <code>exec_prefix</code>, as well as all subdirectories that are needed. |
| One way to do this is by means of an <code>installdirs</code> target |
| as described below. |
| </p> |
| <p>Use ‘<samp>-</samp>’ before any command for installing a man page, so that |
| <code>make</code> will ignore any errors. This is in case there are systems |
| that don’t have the Unix man page documentation system installed. |
| </p> |
| <p>The way to install Info files is to copy them into <samp>$(infodir)</samp> |
| with <code>$(INSTALL_DATA)</code> (see <a href="#Command-Variables">Command Variables</a>), and then run |
| the <code>install-info</code> program if it is present. <code>install-info</code> |
| is a program that edits the Info <samp>dir</samp> file to add or update the |
| menu entry for the given Info file; it is part of the Texinfo package. |
| Here is a sample rule to install an Info file: |
| </p> |
| <div class="smallexample"> |
| <pre class="smallexample">$(DESTDIR)$(infodir)/foo.info: foo.info |
| $(POST_INSTALL) |
| # There may be a newer info file in . than in srcdir. |
| -if test -f foo.info; then d=.; \ |
| else d=$(srcdir); fi; \ |
| $(INSTALL_DATA) $$d/foo.info $(DESTDIR)$@; \ |
| # Run install-info only if it exists. |
| # Use `if' instead of just prepending `-' to the |
| # line so we notice real errors from install-info. |
| # We use `$(SHELL) -c' because some shells do not |
| # fail gracefully when there is an unknown command. |
| if $(SHELL) -c 'install-info --version' \ |
| >/dev/null 2>&1; then \ |
| install-info --dir-file=$(DESTDIR)$(infodir)/dir \ |
| $(DESTDIR)$(infodir)/foo.info; \ |
| else true; fi |
| </pre></div> |
| |
| <p>When writing the <code>install</code> target, you must classify all the |
| commands into three categories: normal ones, <em>pre-installation</em> |
| commands and <em>post-installation</em> commands. See <a href="#Install-Command-Categories">Install Command Categories</a>. |
| </p> |
| </dd> |
| <dt>‘<samp>install-html</samp>’</dt> |
| <dt>‘<samp>install-dvi</samp>’</dt> |
| <dt>‘<samp>install-pdf</samp>’</dt> |
| <dt>‘<samp>install-ps</samp>’</dt> |
| <dd><p>These targets install documentation in formats other than Info; |
| they’re intended to be called explicitly by the person installing the |
| package, if that format is desired. GNU prefers Info files, so these |
| must be installed by the <code>install</code> target. |
| </p> |
| <p>When you have many documentation files to install, we recommend that |
| you avoid collisions and clutter by arranging for these targets to |
| install in subdirectories of the appropriate installation directory, |
| such as <code>htmldir</code>. As one example, if your package has multiple |
| manuals, and you wish to install HTML documentation with many files |
| (such as the “split” mode output by <code>makeinfo --html</code>), you’ll |
| certainly want to use subdirectories, or two nodes with the same name |
| in different manuals will overwrite each other. |
| </p> |
| <p>Please make these <code>install-<var>format</var></code> targets invoke the |
| commands for the <var>format</var> target, for example, by making |
| <var>format</var> a dependency. |
| </p> |
| </dd> |
| <dt>‘<samp>uninstall</samp>’</dt> |
| <dd><p>Delete all the installed files—the copies that the ‘<samp>install</samp>’ |
| and ‘<samp>install-*</samp>’ targets create. |
| </p> |
| <p>This rule should not modify the directories where compilation is done, |
| only the directories where files are installed. |
| </p> |
| <p>The uninstallation commands are divided into three categories, just like |
| the installation commands. See <a href="#Install-Command-Categories">Install Command Categories</a>. |
| </p> |
| </dd> |
| <dt>‘<samp>install-strip</samp>’</dt> |
| <dd><p>Like <code>install</code>, but strip the executable files while installing |
| them. In simple cases, this target can use the <code>install</code> target in |
| a simple way: |
| </p> |
| <div class="smallexample"> |
| <pre class="smallexample">install-strip: |
| $(MAKE) INSTALL_PROGRAM='$(INSTALL_PROGRAM) -s' \ |
| install |
| </pre></div> |
| |
| <p>But if the package installs scripts as well as real executables, the |
| <code>install-strip</code> target can’t just refer to the <code>install</code> |
| target; it has to strip the executables but not the scripts. |
| </p> |
| <p><code>install-strip</code> should not strip the executables in the build |
| directory which are being copied for installation. It should only strip |
| the copies that are installed. |
| </p> |
| <p>Normally we do not recommend stripping an executable unless you are sure |
| the program has no bugs. However, it can be reasonable to install a |
| stripped executable for actual execution while saving the unstripped |
| executable elsewhere in case there is a bug. |
| </p> |
| </dd> |
| <dt>‘<samp>clean</samp>’</dt> |
| <dd> |
| <p>Delete all files in the current directory that are normally created by |
| building the program. Also delete files in other directories if they |
| are created by this makefile. However, don’t delete the files that |
| record the configuration. Also preserve files that could be made by |
| building, but normally aren’t because the distribution comes with |
| them. There is no need to delete parent directories that were created |
| with ‘<samp>mkdir -p</samp>’, since they could have existed anyway. |
| </p> |
| <p>Delete <samp>.dvi</samp> files here if they are not part of the distribution. |
| </p> |
| </dd> |
| <dt>‘<samp>distclean</samp>’</dt> |
| <dd><p>Delete all files in the current directory (or created by this |
| makefile) that are created by configuring or building the program. If |
| you have unpacked the source and built the program without creating |
| any other files, ‘<samp>make distclean</samp>’ should leave only the files |
| that were in the distribution. However, there is no need to delete |
| parent directories that were created with ‘<samp>mkdir -p</samp>’, since they |
| could have existed anyway. |
| </p> |
| </dd> |
| <dt>‘<samp>mostlyclean</samp>’</dt> |
| <dd><p>Like ‘<samp>clean</samp>’, but may refrain from deleting a few files that people |
| normally don’t want to recompile. For example, the ‘<samp>mostlyclean</samp>’ |
| target for GCC does not delete <samp>libgcc.a</samp>, because recompiling it |
| is rarely necessary and takes a lot of time. |
| </p> |
| </dd> |
| <dt>‘<samp>maintainer-clean</samp>’</dt> |
| <dd><p>Delete almost everything that can be reconstructed with this Makefile. |
| This typically includes everything deleted by <code>distclean</code>, plus |
| more: C source files produced by Bison, tags tables, Info files, and |
| so on. |
| </p> |
| <p>The reason we say “almost everything” is that running the command |
| ‘<samp>make maintainer-clean</samp>’ should not delete <samp>configure</samp> even |
| if <samp>configure</samp> can be remade using a rule in the Makefile. More |
| generally, ‘<samp>make maintainer-clean</samp>’ should not delete anything |
| that needs to exist in order to run <samp>configure</samp> and then begin to |
| build the program. Also, there is no need to delete parent |
| directories that were created with ‘<samp>mkdir -p</samp>’, since they could |
| have existed anyway. These are the only exceptions; |
| <code>maintainer-clean</code> should delete everything else that can be |
| rebuilt. |
| </p> |
| <p>The ‘<samp>maintainer-clean</samp>’ target is intended to be used by a maintainer of |
| the package, not by ordinary users. You may need special tools to |
| reconstruct some of the files that ‘<samp>make maintainer-clean</samp>’ deletes. |
| Since these files are normally included in the distribution, we don’t |
| take care to make them easy to reconstruct. If you find you need to |
| unpack the full distribution again, don’t blame us. |
| </p> |
| <p>To help make users aware of this, the commands for the special |
| <code>maintainer-clean</code> target should start with these two: |
| </p> |
| <div class="smallexample"> |
| <pre class="smallexample">@echo 'This command is intended for maintainers to use; it' |
| @echo 'deletes files that may need special tools to rebuild.' |
| </pre></div> |
| |
| </dd> |
| <dt>‘<samp>TAGS</samp>’</dt> |
| <dd><p>Update a tags table for this program. |
| </p> |
| </dd> |
| <dt>‘<samp>info</samp>’</dt> |
| <dd><p>Generate any Info files needed. The best way to write the rules is as |
| follows: |
| </p> |
| <div class="smallexample"> |
| <pre class="smallexample">info: foo.info |
| |
| foo.info: foo.texi chap1.texi chap2.texi |
| $(MAKEINFO) $(srcdir)/foo.texi |
| </pre></div> |
| |
| <p>You must define the variable <code>MAKEINFO</code> in the Makefile. It should |
| run the <code>makeinfo</code> program, which is part of the Texinfo |
| distribution. |
| </p> |
| <p>Normally a GNU distribution comes with Info files, and that means the |
| Info files are present in the source directory. Therefore, the Make |
| rule for an info file should update it in the source directory. When |
| users build the package, ordinarily Make will not update the Info files |
| because they will already be up to date. |
| </p> |
| </dd> |
| <dt>‘<samp>dvi</samp>’</dt> |
| <dt>‘<samp>html</samp>’</dt> |
| <dt>‘<samp>pdf</samp>’</dt> |
| <dt>‘<samp>ps</samp>’</dt> |
| <dd><p>Generate documentation files in the given format. These targets |
| should always exist, but any or all can be a no-op if the given output |
| format cannot be generated. These targets should not be dependencies |
| of the <code>all</code> target; the user must manually invoke them. |
| </p> |
| <p>Here’s an example rule for generating DVI files from Texinfo: |
| </p> |
| <div class="smallexample"> |
| <pre class="smallexample">dvi: foo.dvi |
| |
| foo.dvi: foo.texi chap1.texi chap2.texi |
| $(TEXI2DVI) $(srcdir)/foo.texi |
| </pre></div> |
| |
| <p>You must define the variable <code>TEXI2DVI</code> in the Makefile. It should |
| run the program <code>texi2dvi</code>, which is part of the Texinfo |
| distribution.<a name="DOCF1" href="#FOOT1"><sup>1</sup></a> Alternatively, |
| write just the dependencies, and allow GNU <code>make</code> to provide the command. |
| </p> |
| <p>Here’s another example, this one for generating HTML from Texinfo: |
| </p> |
| <div class="smallexample"> |
| <pre class="smallexample">html: foo.html |
| |
| foo.html: foo.texi chap1.texi chap2.texi |
| $(TEXI2HTML) $(srcdir)/foo.texi |
| </pre></div> |
| |
| <p>Again, you would define the variable <code>TEXI2HTML</code> in the Makefile; |
| for example, it might run <code>makeinfo --no-split --html</code> |
| (<code>makeinfo</code> is part of the Texinfo distribution). |
| </p> |
| </dd> |
| <dt>‘<samp>dist</samp>’</dt> |
| <dd><p>Create a distribution tar file for this program. The tar file should be |
| set up so that the file names in the tar file start with a subdirectory |
| name which is the name of the package it is a distribution for. This |
| name can include the version number. |
| </p> |
| <p>For example, the distribution tar file of GCC version 1.40 unpacks into |
| a subdirectory named <samp>gcc-1.40</samp>. |
| </p> |
| <p>The easiest way to do this is to create a subdirectory appropriately |
| named, use <code>ln</code> or <code>cp</code> to install the proper files in it, and |
| then <code>tar</code> that subdirectory. |
| </p> |
| <p>Compress the tar file with <code>gzip</code>. For example, the actual |
| distribution file for GCC version 1.40 is called <samp>gcc-1.40.tar.gz</samp>. |
| </p> |
| <p>The <code>dist</code> target should explicitly depend on all non-source files |
| that are in the distribution, to make sure they are up to date in the |
| distribution. |
| See <a href="#Releases">Making Releases</a>. |
| </p> |
| </dd> |
| <dt>‘<samp>check</samp>’</dt> |
| <dd><p>Perform self-tests (if any). The user must build the program before |
| running the tests, but need not install the program; you should write |
| the self-tests so that they work when the program is built but not |
| installed. |
| </p></dd> |
| </dl> |
| |
| <p>The following targets are suggested as conventional names, for programs |
| in which they are useful. |
| </p> |
| <dl compact="compact"> |
| <dt><code>installcheck</code></dt> |
| <dd><p>Perform installation tests (if any). The user must build and install |
| the program before running the tests. You should not assume that |
| <samp>$(bindir)</samp> is in the search path. |
| </p> |
| </dd> |
| <dt><code>installdirs</code></dt> |
| <dd><p>It’s useful to add a target named ‘<samp>installdirs</samp>’ to create the |
| directories where files are installed, and their parent directories. |
| There is a script called <samp>mkinstalldirs</samp> which is convenient for |
| this; you can find it in the Texinfo package. |
| You can use a rule like this: |
| </p> |
| <div class="smallexample"> |
| <pre class="smallexample"># Make sure all installation directories (e.g. $(bindir)) |
| # actually exist by making them if necessary. |
| installdirs: mkinstalldirs |
| $(srcdir)/mkinstalldirs $(bindir) $(datadir) \ |
| $(libdir) $(infodir) \ |
| $(mandir) |
| </pre></div> |
| |
| <p>or, if you wish to support <code>DESTDIR</code>, |
| </p> |
| <div class="smallexample"> |
| <pre class="smallexample"># Make sure all installation directories (e.g. $(bindir)) |
| # actually exist by making them if necessary. |
| installdirs: mkinstalldirs |
| $(srcdir)/mkinstalldirs \ |
| $(DESTDIR)$(bindir) $(DESTDIR)$(datadir) \ |
| $(DESTDIR)$(libdir) $(DESTDIR)$(infodir) \ |
| $(DESTDIR)$(mandir) |
| </pre></div> |
| |
| <p>This rule should not modify the directories where compilation is done. |
| It should do nothing but create installation directories. |
| </p></dd> |
| </dl> |
| |
| <hr> |
| <a name="Install-Command-Categories"></a> |
| <div class="header"> |
| <p> |
| Previous: <a href="#Standard-Targets" accesskey="p" rel="prev">Standard Targets</a>, Up: <a href="#Makefile-Conventions" accesskey="u" rel="up">Makefile Conventions</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p> |
| </div> |
| <a name="Install-Command-Categories-1"></a> |
| <h4 class="subsection">7.2.7 Install Command Categories</h4> |
| |
| <a name="index-pre_002dinstallation-commands"></a> |
| <a name="index-post_002dinstallation-commands"></a> |
| <p>When writing the <code>install</code> target, you must classify all the |
| commands into three categories: normal ones, <em>pre-installation</em> |
| commands and <em>post-installation</em> commands. |
| </p> |
| <p>Normal commands move files into their proper places, and set their |
| modes. They may not alter any files except the ones that come entirely |
| from the package they belong to. |
| </p> |
| <p>Pre-installation and post-installation commands may alter other files; |
| in particular, they can edit global configuration files or data bases. |
| </p> |
| <p>Pre-installation commands are typically executed before the normal |
| commands, and post-installation commands are typically run after the |
| normal commands. |
| </p> |
| <p>The most common use for a post-installation command is to run |
| <code>install-info</code>. This cannot be done with a normal command, since |
| it alters a file (the Info directory) which does not come entirely and |
| solely from the package being installed. It is a post-installation |
| command because it needs to be done after the normal command which |
| installs the package’s Info files. |
| </p> |
| <p>Most programs don’t need any pre-installation commands, but we have the |
| feature just in case it is needed. |
| </p> |
| <p>To classify the commands in the <code>install</code> rule into these three |
| categories, insert <em>category lines</em> among them. A category line |
| specifies the category for the commands that follow. |
| </p> |
| <p>A category line consists of a tab and a reference to a special Make |
| variable, plus an optional comment at the end. There are three |
| variables you can use, one for each category; the variable name |
| specifies the category. Category lines are no-ops in ordinary execution |
| because these three Make variables are normally undefined (and you |
| <em>should not</em> define them in the makefile). |
| </p> |
| <p>Here are the three possible category lines, each with a comment that |
| explains what it means: |
| </p> |
| <div class="smallexample"> |
| <pre class="smallexample"> $(PRE_INSTALL) # <span class="roman">Pre-install commands follow.</span> |
| $(POST_INSTALL) # <span class="roman">Post-install commands follow.</span> |
| $(NORMAL_INSTALL) # <span class="roman">Normal commands follow.</span> |
| </pre></div> |
| |
| <p>If you don’t use a category line at the beginning of the <code>install</code> |
| rule, all the commands are classified as normal until the first category |
| line. If you don’t use any category lines, all the commands are |
| classified as normal. |
| </p> |
| <p>These are the category lines for <code>uninstall</code>: |
| </p> |
| <div class="smallexample"> |
| <pre class="smallexample"> $(PRE_UNINSTALL) # <span class="roman">Pre-uninstall commands follow.</span> |
| $(POST_UNINSTALL) # <span class="roman">Post-uninstall commands follow.</span> |
| $(NORMAL_UNINSTALL) # <span class="roman">Normal commands follow.</span> |
| </pre></div> |
| |
| <p>Typically, a pre-uninstall command would be used for deleting entries |
| from the Info directory. |
| </p> |
| <p>If the <code>install</code> or <code>uninstall</code> target has any dependencies |
| which act as subroutines of installation, then you should start |
| <em>each</em> dependency’s commands with a category line, and start the |
| main target’s commands with a category line also. This way, you can |
| ensure that each command is placed in the right category regardless of |
| which of the dependencies actually run. |
| </p> |
| <p>Pre-installation and post-installation commands should not run any |
| programs except for these: |
| </p> |
| <div class="example"> |
| <pre class="example">[ basename bash cat chgrp chmod chown cmp cp dd diff echo |
| egrep expand expr false fgrep find getopt grep gunzip gzip |
| hostname install install-info kill ldconfig ln ls md5sum |
| mkdir mkfifo mknod mv printenv pwd rm rmdir sed sort tee |
| test touch true uname xargs yes |
| </pre></div> |
| |
| <a name="index-binary-packages"></a> |
| <p>The reason for distinguishing the commands in this way is for the sake |
| of making binary packages. Typically a binary package contains all the |
| executables and other files that need to be installed, and has its own |
| method of installing them—so it does not need to run the normal |
| installation commands. But installing the binary package does need to |
| execute the pre-installation and post-installation commands. |
| </p> |
| <p>Programs to build binary packages work by extracting the |
| pre-installation and post-installation commands. Here is one way of |
| extracting the pre-installation commands (the <samp>-s</samp> option to |
| <code>make</code> is needed to silence messages about entering |
| subdirectories): |
| </p> |
| <div class="smallexample"> |
| <pre class="smallexample">make -s -n install -o all \ |
| PRE_INSTALL=pre-install \ |
| POST_INSTALL=post-install \ |
| NORMAL_INSTALL=normal-install \ |
| | gawk -f pre-install.awk |
| </pre></div> |
| |
| <p>where the file <samp>pre-install.awk</samp> could contain this: |
| </p> |
| <div class="smallexample"> |
| <pre class="smallexample">$0 ~ /^(normal-install|post-install)[ \t]*$/ {on = 0} |
| on {print $0} |
| $0 ~ /^pre-install[ \t]*$/ {on = 1} |
| </pre></div> |
| |
| <hr> |
| <a name="Releases"></a> |
| <div class="header"> |
| <p> |
| Previous: <a href="#Makefile-Conventions" accesskey="p" rel="prev">Makefile Conventions</a>, Up: <a href="#Managing-Releases" accesskey="u" rel="up">Managing Releases</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p> |
| </div> |
| <a name="Making-Releases"></a> |
| <h3 class="section">7.3 Making Releases</h3> |
| <a name="index-packaging"></a> |
| |
| <p>You should identify each release with a pair of version numbers, a |
| major version and a minor. We have no objection to using more than |
| two numbers, but it is very unlikely that you really need them. |
| </p> |
| <p>Package the distribution of <code>Foo version 69.96</code> up in a gzipped tar |
| file with the name <samp>foo-69.96.tar.gz</samp>. It should unpack into a |
| subdirectory named <samp>foo-69.96</samp>. |
| </p> |
| <p>Building and installing the program should never modify any of the files |
| contained in the distribution. This means that all the files that form |
| part of the program in any way must be classified into <em>source |
| files</em> and <em>non-source files</em>. Source files are written by humans |
| and never changed automatically; non-source files are produced from |
| source files by programs under the control of the Makefile. |
| </p> |
| <a name="index-README-file"></a> |
| <p>The distribution should contain a file named <samp>README</samp> which gives |
| the name of the package, and a general description of what it does. It |
| is also good to explain the purpose of each of the first-level |
| subdirectories in the package, if there are any. The <samp>README</samp> file |
| should either state the version number of the package, or refer to where |
| in the package it can be found. |
| </p> |
| <p>The <samp>README</samp> file should refer to the file <samp>INSTALL</samp>, which |
| should contain an explanation of the installation procedure. |
| </p> |
| <p>The <samp>README</samp> file should also refer to the file which contains the |
| copying conditions. The GNU GPL, if used, should be in a file called |
| <samp>COPYING</samp>. If the GNU LGPL is used, it should be in a file called |
| <samp>COPYING.LESSER</samp>. |
| </p> |
| <p>Naturally, all the source files must be in the distribution. It is okay |
| to include non-source files in the distribution, provided they are |
| up-to-date and machine-independent, so that building the distribution |
| normally will never modify them. We commonly include non-source files |
| produced by Bison, <code>lex</code>, TeX, and <code>makeinfo</code>; this helps avoid |
| unnecessary dependencies between our distributions, so that users can |
| install whichever packages they want to install. |
| </p> |
| <p>Non-source files that might actually be modified by building and |
| installing the program should <strong>never</strong> be included in the |
| distribution. So if you do distribute non-source files, always make |
| sure they are up to date when you make a new distribution. |
| </p> |
| <p>Make sure that all the files in the distribution are world-readable, and |
| that directories are world-readable and world-searchable (octal mode 755). |
| We used to recommend that all directories in the distribution also be |
| world-writable (octal mode 777), because ancient versions of <code>tar</code> |
| would otherwise not cope when extracting the archive as an unprivileged |
| user. That can easily lead to security issues when creating the archive, |
| however, so now we recommend against that. |
| </p> |
| <p>Don’t include any symbolic links in the distribution itself. If the tar |
| file contains symbolic links, then people cannot even unpack it on |
| systems that don’t support symbolic links. Also, don’t use multiple |
| names for one file in different directories, because certain file |
| systems cannot handle this and that prevents unpacking the |
| distribution. |
| </p> |
| <p>Try to make sure that all the file names will be unique on MS-DOS. A |
| name on MS-DOS consists of up to 8 characters, optionally followed by a |
| period and up to three characters. MS-DOS will truncate extra |
| characters both before and after the period. Thus, |
| <samp>foobarhacker.c</samp> and <samp>foobarhacker.o</samp> are not ambiguous; they |
| are truncated to <samp>foobarha.c</samp> and <samp>foobarha.o</samp>, which are |
| distinct. |
| </p> |
| <a name="index-texinfo_002etex_002c-in-a-distribution"></a> |
| <p>Include in your distribution a copy of the <samp>texinfo.tex</samp> you used |
| to test print any <samp>*.texinfo</samp> or <samp>*.texi</samp> files. |
| </p> |
| <p>Likewise, if your program uses small GNU software packages like regex, |
| getopt, obstack, or termcap, include them in the distribution file. |
| Leaving them out would make the distribution file a little smaller at |
| the expense of possible inconvenience to a user who doesn’t know what |
| other files to get. |
| </p> |
| <hr> |
| <a name="References"></a> |
| <div class="header"> |
| <p> |
| Next: <a href="#GNU-Free-Documentation-License" accesskey="n" rel="next">GNU Free Documentation License</a>, Previous: <a href="#Managing-Releases" accesskey="p" rel="prev">Managing Releases</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p> |
| </div> |
| <a name="References-to-Non_002dFree-Software-and-Documentation"></a> |
| <h2 class="chapter">8 References to Non-Free Software and Documentation</h2> |
| <a name="index-references-to-non_002dfree-material"></a> |
| |
| <p>A GNU program should not recommend, promote, or grant legitimacy to |
| the use of any non-free program. Proprietary software is a social and |
| ethical problem, and our aim is to put an end to that problem. We |
| can’t stop some people from writing proprietary programs, or stop |
| other people from using them, but we can and should refuse to |
| advertise them to new potential customers, or to give the public the |
| idea that their existence is ethical. |
| </p> |
| <p>The GNU definition of free software is found on the GNU web site at |
| <a href="http://www.gnu.org/philosophy/free-sw.html">http://www.gnu.org/philosophy/free-sw.html</a>, and the definition |
| of free documentation is found at |
| <a href="http://www.gnu.org/philosophy/free-doc.html">http://www.gnu.org/philosophy/free-doc.html</a>. The terms “free” |
| and “non-free”, used in this document, refer to those definitions. |
| </p> |
| <p>A list of important licenses and whether they qualify as free is in |
| <a href="http://www.gnu.org/licenses/license-list.html">http://www.gnu.org/licenses/license-list.html</a>. If it is not |
| clear whether a license qualifies as free, please ask the GNU Project |
| by writing to <a href="mailto:licensing@gnu.org">licensing@gnu.org</a>. We will answer, and if the |
| license is an important one, we will add it to the list. |
| </p> |
| <p>When a non-free program or system is well known, you can mention it in |
| passing—that is harmless, since users who might want to use it |
| probably already know about it. For instance, it is fine to explain |
| how to build your package on top of some widely used non-free |
| operating system, or how to use it together with some widely used |
| non-free program. |
| </p> |
| <p>However, you should give only the necessary information to help those |
| who already use the non-free program to use your program with |
| it—don’t give, or refer to, any further information about the |
| proprietary program, and don’t imply that the proprietary program |
| enhances your program, or that its existence is in any way a good |
| thing. The goal should be that people already using the proprietary |
| program will get the advice they need about how to use your free |
| program with it, while people who don’t already use the proprietary |
| program will not see anything likely to lead them to take an interest |
| in it. |
| </p> |
| <p>If a non-free program or system is obscure in your program’s domain, |
| your program should not mention or support it at all, since doing so |
| would tend to popularize the non-free program more than it popularizes |
| your program. (You cannot hope to find many additional users for your |
| program among the users of Foobar, if the existence of Foobar is not |
| generally known among people who might want to use your program.) |
| </p> |
| <p>Sometimes a program is free software in itself but depends on a |
| non-free platform in order to run. For instance, many Java programs |
| depend on some non-free Java libraries. To recommend or promote such |
| a program is to promote the other programs it needs. This is why we |
| are careful about listing Java programs in the Free Software |
| Directory: we don’t want to promote the non-free Java libraries. |
| </p> |
| <p>We hope this particular problem with Java will be gone by and by, as |
| we replace the remaining non-free standard Java libraries with free |
| software, but the general principle will remain the same: don’t |
| recommend, promote or legitimize programs that depend on non-free |
| software to run. |
| </p> |
| <p>Some free programs strongly encourage the use of non-free software. A |
| typical example is <code>mplayer</code>. It is free software in itself, |
| and the free code can handle some kinds of files. However, |
| <code>mplayer</code> recommends use of non-free codecs for other kinds of |
| files, and users that install <code>mplayer</code> are very likely to |
| install those codecs along with it. To recommend <code>mplayer</code> |
| is, in effect, to promote use of the non-free codecs. |
| </p> |
| <p>Thus, you should not recommend programs that strongly encourage the |
| use of non-free software. This is why we do not list |
| <code>mplayer</code> in the Free Software Directory. |
| </p> |
| <p>A GNU package should not refer the user to any non-free documentation |
| for free software. Free documentation that can be included in free |
| operating systems is essential for completing the GNU system, or any |
| free operating system, so encouraging it is a priority; to recommend |
| use of documentation that we are not allowed to include undermines the |
| impetus for the community to produce documentation that we can |
| include. So GNU packages should never recommend non-free |
| documentation. |
| </p> |
| <p>By contrast, it is ok to refer to journal articles and textbooks in |
| the comments of a program for explanation of how it functions, even |
| though they are non-free. This is because we don’t include such |
| things in the GNU system even they are free—they are outside the |
| scope of what a software distribution needs to include. |
| </p> |
| <p>Referring to a web site that describes or recommends a non-free |
| program is promoting that program, so please do not make links (or |
| mention by name) web sites that contain such material. This policy is |
| relevant particularly for the web pages for a GNU package. |
| </p> |
| <p>Following links from nearly any web site can lead eventually to |
| non-free software; this is inherent in the nature of the web. So it |
| makes no sense to criticize a site for having such links. As long as |
| the site does not itself recommend a non-free program, there is no |
| need to consider the question of the sites that it links to for other |
| reasons. |
| </p> |
| <p>Thus, for example, you should not refer to AT&T’s web site if that |
| recommends AT&T’s non-free software packages; you should not refer to |
| a site that links to AT&T’s site presenting it as a place to get some |
| non-free program, because that link recommends and legitimizes the |
| non-free program. However, that a site contains a link to AT&T’s web |
| site for some other purpose (such as long-distance telephone service) |
| is not an objection against it. |
| </p> |
| <hr> |
| <a name="GNU-Free-Documentation-License"></a> |
| <div class="header"> |
| <p> |
| Next: <a href="#Index" accesskey="n" rel="next">Index</a>, Previous: <a href="#References" accesskey="p" rel="prev">References</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p> |
| </div> |
| <a name="GNU-Free-Documentation-License-1"></a> |
| <h2 class="appendix">Appendix A GNU Free Documentation License</h2> |
| |
| <a name="index-FDL_002c-GNU-Free-Documentation-License"></a> |
| <div align="center">Version 1.3, 3 November 2008 |
| </div> |
| |
| <div class="display"> |
| <pre class="display">Copyright © 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. |
| <a href="http://fsf.org/">http://fsf.org/</a> |
| |
| Everyone is permitted to copy and distribute verbatim copies |
| of this license document, but changing it is not allowed. |
| </pre></div> |
| |
| <ol> |
| <li> PREAMBLE |
| |
| <p>The purpose of this License is to make a manual, textbook, or other |
| functional and useful document <em>free</em> in the sense of freedom: to |
| assure everyone the effective freedom to copy and redistribute it, |
| with or without modifying it, either commercially or noncommercially. |
| Secondarily, this License preserves for the author and publisher a way |
| to get credit for their work, while not being considered responsible |
| for modifications made by others. |
| </p> |
| <p>This License is a kind of “copyleft”, which means that derivative |
| works of the document must themselves be free in the same sense. It |
| complements the GNU General Public License, which is a copyleft |
| license designed for free software. |
| </p> |
| <p>We have designed this License in order to use it for manuals for free |
| software, because free software needs free documentation: a free |
| program should come with manuals providing the same freedoms that the |
| software does. But this License is not limited to software manuals; |
| it can be used for any textual work, regardless of subject matter or |
| whether it is published as a printed book. We recommend this License |
| principally for works whose purpose is instruction or reference. |
| </p> |
| </li><li> APPLICABILITY AND DEFINITIONS |
| |
| <p>This License applies to any manual or other work, in any medium, that |
| contains a notice placed by the copyright holder saying it can be |
| distributed under the terms of this License. Such a notice grants a |
| world-wide, royalty-free license, unlimited in duration, to use that |
| work under the conditions stated herein. The “Document”, below, |
| refers to any such manual or work. Any member of the public is a |
| licensee, and is addressed as “you”. You accept the license if you |
| copy, modify or distribute the work in a way requiring permission |
| under copyright law. |
| </p> |
| <p>A “Modified Version” of the Document means any work containing the |
| Document or a portion of it, either copied verbatim, or with |
| modifications and/or translated into another language. |
| </p> |
| <p>A “Secondary Section” is a named appendix or a front-matter section |
| of the Document that deals exclusively with the relationship of the |
| publishers or authors of the Document to the Document’s overall |
| subject (or to related matters) and contains nothing that could fall |
| directly within that overall subject. (Thus, if the Document is in |
| part a textbook of mathematics, a Secondary Section may not explain |
| any mathematics.) The relationship could be a matter of historical |
| connection with the subject or with related matters, or of legal, |
| commercial, philosophical, ethical or political position regarding |
| them. |
| </p> |
| <p>The “Invariant Sections” are certain Secondary Sections whose titles |
| are designated, as being those of Invariant Sections, in the notice |
| that says that the Document is released under this License. If a |
| section does not fit the above definition of Secondary then it is not |
| allowed to be designated as Invariant. The Document may contain zero |
| Invariant Sections. If the Document does not identify any Invariant |
| Sections then there are none. |
| </p> |
| <p>The “Cover Texts” are certain short passages of text that are listed, |
| as Front-Cover Texts or Back-Cover Texts, in the notice that says that |
| the Document is released under this License. A Front-Cover Text may |
| be at most 5 words, and a Back-Cover Text may be at most 25 words. |
| </p> |
| <p>A “Transparent” copy of the Document means a machine-readable copy, |
| represented in a format whose specification is available to the |
| general public, that is suitable for revising the document |
| straightforwardly with generic text editors or (for images composed of |
| pixels) generic paint programs or (for drawings) some widely available |
| drawing editor, and that is suitable for input to text formatters or |
| for automatic translation to a variety of formats suitable for input |
| to text formatters. A copy made in an otherwise Transparent file |
| format whose markup, or absence of markup, has been arranged to thwart |
| or discourage subsequent modification by readers is not Transparent. |
| An image format is not Transparent if used for any substantial amount |
| of text. A copy that is not “Transparent” is called “Opaque”. |
| </p> |
| <p>Examples of suitable formats for Transparent copies include plain |
| <small>ASCII</small> without markup, Texinfo input format, LaTeX input |
| format, <acronym>SGML</acronym> or <acronym>XML</acronym> using a publicly available |
| <acronym>DTD</acronym>, and standard-conforming simple <acronym>HTML</acronym>, |
| PostScript or <acronym>PDF</acronym> designed for human modification. Examples |
| of transparent image formats include <acronym>PNG</acronym>, <acronym>XCF</acronym> and |
| <acronym>JPG</acronym>. Opaque formats include proprietary formats that can be |
| read and edited only by proprietary word processors, <acronym>SGML</acronym> or |
| <acronym>XML</acronym> for which the <acronym>DTD</acronym> and/or processing tools are |
| not generally available, and the machine-generated <acronym>HTML</acronym>, |
| PostScript or <acronym>PDF</acronym> produced by some word processors for |
| output purposes only. |
| </p> |
| <p>The “Title Page” means, for a printed book, the title page itself, |
| plus such following pages as are needed to hold, legibly, the material |
| this License requires to appear in the title page. For works in |
| formats which do not have any title page as such, “Title Page” means |
| the text near the most prominent appearance of the work’s title, |
| preceding the beginning of the body of the text. |
| </p> |
| <p>The “publisher” means any person or entity that distributes copies |
| of the Document to the public. |
| </p> |
| <p>A section “Entitled XYZ” means a named subunit of the Document whose |
| title either is precisely XYZ or contains XYZ in parentheses following |
| text that translates XYZ in another language. (Here XYZ stands for a |
| specific section name mentioned below, such as “Acknowledgements”, |
| “Dedications”, “Endorsements”, or “History”.) To “Preserve the Title” |
| of such a section when you modify the Document means that it remains a |
| section “Entitled XYZ” according to this definition. |
| </p> |
| <p>The Document may include Warranty Disclaimers next to the notice which |
| states that this License applies to the Document. These Warranty |
| Disclaimers are considered to be included by reference in this |
| License, but only as regards disclaiming warranties: any other |
| implication that these Warranty Disclaimers may have is void and has |
| no effect on the meaning of this License. |
| </p> |
| </li><li> VERBATIM COPYING |
| |
| <p>You may copy and distribute the Document in any medium, either |
| commercially or noncommercially, provided that this License, the |
| copyright notices, and the license notice saying this License applies |
| to the Document are reproduced in all copies, and that you add no other |
| conditions whatsoever to those of this License. You may not use |
| technical measures to obstruct or control the reading or further |
| copying of the copies you make or distribute. However, you may accept |
| compensation in exchange for copies. If you distribute a large enough |
| number of copies you must also follow the conditions in section 3. |
| </p> |
| <p>You may also lend copies, under the same conditions stated above, and |
| you may publicly display copies. |
| </p> |
| </li><li> COPYING IN QUANTITY |
| |
| <p>If you publish printed copies (or copies in media that commonly have |
| printed covers) of the Document, numbering more than 100, and the |
| Document’s license notice requires Cover Texts, you must enclose the |
| copies in covers that carry, clearly and legibly, all these Cover |
| Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on |
| the back cover. Both covers must also clearly and legibly identify |
| you as the publisher of these copies. The front cover must present |
| the full title with all words of the title equally prominent and |
| visible. You may add other material on the covers in addition. |
| Copying with changes limited to the covers, as long as they preserve |
| the title of the Document and satisfy these conditions, can be treated |
| as verbatim copying in other respects. |
| </p> |
| <p>If the required texts for either cover are too voluminous to fit |
| legibly, you should put the first ones listed (as many as fit |
| reasonably) on the actual cover, and continue the rest onto adjacent |
| pages. |
| </p> |
| <p>If you publish or distribute Opaque copies of the Document numbering |
| more than 100, you must either include a machine-readable Transparent |
| copy along with each Opaque copy, or state in or with each Opaque copy |
| a computer-network location from which the general network-using |
| public has access to download using public-standard network protocols |
| a complete Transparent copy of the Document, free of added material. |
| If you use the latter option, you must take reasonably prudent steps, |
| when you begin distribution of Opaque copies in quantity, to ensure |
| that this Transparent copy will remain thus accessible at the stated |
| location until at least one year after the last time you distribute an |
| Opaque copy (directly or through your agents or retailers) of that |
| edition to the public. |
| </p> |
| <p>It is requested, but not required, that you contact the authors of the |
| Document well before redistributing any large number of copies, to give |
| them a chance to provide you with an updated version of the Document. |
| </p> |
| </li><li> MODIFICATIONS |
| |
| <p>You may copy and distribute a Modified Version of the Document under |
| the conditions of sections 2 and 3 above, provided that you release |
| the Modified Version under precisely this License, with the Modified |
| Version filling the role of the Document, thus licensing distribution |
| and modification of the Modified Version to whoever possesses a copy |
| of it. In addition, you must do these things in the Modified Version: |
| </p> |
| <ol> |
| <li> Use in the Title Page (and on the covers, if any) a title distinct |
| from that of the Document, and from those of previous versions |
| (which should, if there were any, be listed in the History section |
| of the Document). You may use the same title as a previous version |
| if the original publisher of that version gives permission. |
| |
| </li><li> List on the Title Page, as authors, one or more persons or entities |
| responsible for authorship of the modifications in the Modified |
| Version, together with at least five of the principal authors of the |
| Document (all of its principal authors, if it has fewer than five), |
| unless they release you from this requirement. |
| |
| </li><li> State on the Title page the name of the publisher of the |
| Modified Version, as the publisher. |
| |
| </li><li> Preserve all the copyright notices of the Document. |
| |
| </li><li> Add an appropriate copyright notice for your modifications |
| adjacent to the other copyright notices. |
| |
| </li><li> Include, immediately after the copyright notices, a license notice |
| giving the public permission to use the Modified Version under the |
| terms of this License, in the form shown in the Addendum below. |
| |
| </li><li> Preserve in that license notice the full lists of Invariant Sections |
| and required Cover Texts given in the Document’s license notice. |
| |
| </li><li> Include an unaltered copy of this License. |
| |
| </li><li> Preserve the section Entitled “History”, Preserve its Title, and add |
| to it an item stating at least the title, year, new authors, and |
| publisher of the Modified Version as given on the Title Page. If |
| there is no section Entitled “History” in the Document, create one |
| stating the title, year, authors, and publisher of the Document as |
| given on its Title Page, then add an item describing the Modified |
| Version as stated in the previous sentence. |
| |
| </li><li> Preserve the network location, if any, given in the Document for |
| public access to a Transparent copy of the Document, and likewise |
| the network locations given in the Document for previous versions |
| it was based on. These may be placed in the “History” section. |
| You may omit a network location for a work that was published at |
| least four years before the Document itself, or if the original |
| publisher of the version it refers to gives permission. |
| |
| </li><li> For any section Entitled “Acknowledgements” or “Dedications”, Preserve |
| the Title of the section, and preserve in the section all the |
| substance and tone of each of the contributor acknowledgements and/or |
| dedications given therein. |
| |
| </li><li> Preserve all the Invariant Sections of the Document, |
| unaltered in their text and in their titles. Section numbers |
| or the equivalent are not considered part of the section titles. |
| |
| </li><li> Delete any section Entitled “Endorsements”. Such a section |
| may not be included in the Modified Version. |
| |
| </li><li> Do not retitle any existing section to be Entitled “Endorsements” or |
| to conflict in title with any Invariant Section. |
| |
| </li><li> Preserve any Warranty Disclaimers. |
| </li></ol> |
| |
| <p>If the Modified Version includes new front-matter sections or |
| appendices that qualify as Secondary Sections and contain no material |
| copied from the Document, you may at your option designate some or all |
| of these sections as invariant. To do this, add their titles to the |
| list of Invariant Sections in the Modified Version’s license notice. |
| These titles must be distinct from any other section titles. |
| </p> |
| <p>You may add a section Entitled “Endorsements”, provided it contains |
| nothing but endorsements of your Modified Version by various |
| parties—for example, statements of peer review or that the text has |
| been approved by an organization as the authoritative definition of a |
| standard. |
| </p> |
| <p>You may add a passage of up to five words as a Front-Cover Text, and a |
| passage of up to 25 words as a Back-Cover Text, to the end of the list |
| of Cover Texts in the Modified Version. Only one passage of |
| Front-Cover Text and one of Back-Cover Text may be added by (or |
| through arrangements made by) any one entity. If the Document already |
| includes a cover text for the same cover, previously added by you or |
| by arrangement made by the same entity you are acting on behalf of, |
| you may not add another; but you may replace the old one, on explicit |
| permission from the previous publisher that added the old one. |
| </p> |
| <p>The author(s) and publisher(s) of the Document do not by this License |
| give permission to use their names for publicity for or to assert or |
| imply endorsement of any Modified Version. |
| </p> |
| </li><li> COMBINING DOCUMENTS |
| |
| <p>You may combine the Document with other documents released under this |
| License, under the terms defined in section 4 above for modified |
| versions, provided that you include in the combination all of the |
| Invariant Sections of all of the original documents, unmodified, and |
| list them all as Invariant Sections of your combined work in its |
| license notice, and that you preserve all their Warranty Disclaimers. |
| </p> |
| <p>The combined work need only contain one copy of this License, and |
| multiple identical Invariant Sections may be replaced with a single |
| copy. If there are multiple Invariant Sections with the same name but |
| different contents, make the title of each such section unique by |
| adding at the end of it, in parentheses, the name of the original |
| author or publisher of that section if known, or else a unique number. |
| Make the same adjustment to the section titles in the list of |
| Invariant Sections in the license notice of the combined work. |
| </p> |
| <p>In the combination, you must combine any sections Entitled “History” |
| in the various original documents, forming one section Entitled |
| “History”; likewise combine any sections Entitled “Acknowledgements”, |
| and any sections Entitled “Dedications”. You must delete all |
| sections Entitled “Endorsements.” |
| </p> |
| </li><li> COLLECTIONS OF DOCUMENTS |
| |
| <p>You may make a collection consisting of the Document and other documents |
| released under this License, and replace the individual copies of this |
| License in the various documents with a single copy that is included in |
| the collection, provided that you follow the rules of this License for |
| verbatim copying of each of the documents in all other respects. |
| </p> |
| <p>You may extract a single document from such a collection, and distribute |
| it individually under this License, provided you insert a copy of this |
| License into the extracted document, and follow this License in all |
| other respects regarding verbatim copying of that document. |
| </p> |
| </li><li> AGGREGATION WITH INDEPENDENT WORKS |
| |
| <p>A compilation of the Document or its derivatives with other separate |
| and independent documents or works, in or on a volume of a storage or |
| distribution medium, is called an “aggregate” if the copyright |
| resulting from the compilation is not used to limit the legal rights |
| of the compilation’s users beyond what the individual works permit. |
| When the Document is included in an aggregate, this License does not |
| apply to the other works in the aggregate which are not themselves |
| derivative works of the Document. |
| </p> |
| <p>If the Cover Text requirement of section 3 is applicable to these |
| copies of the Document, then if the Document is less than one half of |
| the entire aggregate, the Document’s Cover Texts may be placed on |
| covers that bracket the Document within the aggregate, or the |
| electronic equivalent of covers if the Document is in electronic form. |
| Otherwise they must appear on printed covers that bracket the whole |
| aggregate. |
| </p> |
| </li><li> TRANSLATION |
| |
| <p>Translation is considered a kind of modification, so you may |
| distribute translations of the Document under the terms of section 4. |
| Replacing Invariant Sections with translations requires special |
| permission from their copyright holders, but you may include |
| translations of some or all Invariant Sections in addition to the |
| original versions of these Invariant Sections. You may include a |
| translation of this License, and all the license notices in the |
| Document, and any Warranty Disclaimers, provided that you also include |
| the original English version of this License and the original versions |
| of those notices and disclaimers. In case of a disagreement between |
| the translation and the original version of this License or a notice |
| or disclaimer, the original version will prevail. |
| </p> |
| <p>If a section in the Document is Entitled “Acknowledgements”, |
| “Dedications”, or “History”, the requirement (section 4) to Preserve |
| its Title (section 1) will typically require changing the actual |
| title. |
| </p> |
| </li><li> TERMINATION |
| |
| <p>You may not copy, modify, sublicense, or distribute the Document |
| except as expressly provided under this License. Any attempt |
| otherwise to copy, modify, sublicense, or distribute it is void, and |
| will automatically terminate your rights under this License. |
| </p> |
| <p>However, if you cease all violation of this License, then your license |
| from a particular copyright holder is reinstated (a) provisionally, |
| unless and until the copyright holder explicitly and finally |
| terminates your license, and (b) permanently, if the copyright holder |
| fails to notify you of the violation by some reasonable means prior to |
| 60 days after the cessation. |
| </p> |
| <p>Moreover, your license from a particular copyright holder is |
| reinstated permanently if the copyright holder notifies you of the |
| violation by some reasonable means, this is the first time you have |
| received notice of violation of this License (for any work) from that |
| copyright holder, and you cure the violation prior to 30 days after |
| your receipt of the notice. |
| </p> |
| <p>Termination of your rights under this section does not terminate the |
| licenses of parties who have received copies or rights from you under |
| this License. If your rights have been terminated and not permanently |
| reinstated, receipt of a copy of some or all of the same material does |
| not give you any rights to use it. |
| </p> |
| </li><li> FUTURE REVISIONS OF THIS LICENSE |
| |
| <p>The Free Software Foundation may publish new, revised versions |
| of the GNU Free Documentation License from time to time. Such new |
| versions will be similar in spirit to the present version, but may |
| differ in detail to address new problems or concerns. See |
| <a href="http://www.gnu.org/copyleft/">http://www.gnu.org/copyleft/</a>. |
| </p> |
| <p>Each version of the License is given a distinguishing version number. |
| If the Document specifies that a particular numbered version of this |
| License “or any later version” applies to it, you have the option of |
| following the terms and conditions either of that specified version or |
| of any later version that has been published (not as a draft) by the |
| Free Software Foundation. If the Document does not specify a version |
| number of this License, you may choose any version ever published (not |
| as a draft) by the Free Software Foundation. If the Document |
| specifies that a proxy can decide which future versions of this |
| License can be used, that proxy’s public statement of acceptance of a |
| version permanently authorizes you to choose that version for the |
| Document. |
| </p> |
| </li><li> RELICENSING |
| |
| <p>“Massive Multiauthor Collaboration Site” (or “MMC Site”) means any |
| World Wide Web server that publishes copyrightable works and also |
| provides prominent facilities for anybody to edit those works. A |
| public wiki that anybody can edit is an example of such a server. A |
| “Massive Multiauthor Collaboration” (or “MMC”) contained in the |
| site means any set of copyrightable works thus published on the MMC |
| site. |
| </p> |
| <p>“CC-BY-SA” means the Creative Commons Attribution-Share Alike 3.0 |
| license published by Creative Commons Corporation, a not-for-profit |
| corporation with a principal place of business in San Francisco, |
| California, as well as future copyleft versions of that license |
| published by that same organization. |
| </p> |
| <p>“Incorporate” means to publish or republish a Document, in whole or |
| in part, as part of another Document. |
| </p> |
| <p>An MMC is “eligible for relicensing” if it is licensed under this |
| License, and if all works that were first published under this License |
| somewhere other than this MMC, and subsequently incorporated in whole |
| or in part into the MMC, (1) had no cover texts or invariant sections, |
| and (2) were thus incorporated prior to November 1, 2008. |
| </p> |
| <p>The operator of an MMC Site may republish an MMC contained in the site |
| under CC-BY-SA on the same site at any time before August 1, 2009, |
| provided the MMC is eligible for relicensing. |
| </p> |
| </li></ol> |
| |
| <a name="ADDENDUM_003a-How-to-use-this-License-for-your-documents"></a> |
| <h3 class="heading">ADDENDUM: How to use this License for your documents</h3> |
| |
| <p>To use this License in a document you have written, include a copy of |
| the License in the document and put the following copyright and |
| license notices just after the title page: |
| </p> |
| <div class="smallexample"> |
| <pre class="smallexample"> Copyright (C) <var>year</var> <var>your name</var>. |
| 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 no Invariant Sections, no Front-Cover Texts, and no Back-Cover |
| Texts. A copy of the license is included in the section entitled ``GNU |
| Free Documentation License''. |
| </pre></div> |
| |
| <p>If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, |
| replace the “with…Texts.” line with this: |
| </p> |
| <div class="smallexample"> |
| <pre class="smallexample"> with the Invariant Sections being <var>list their titles</var>, with |
| the Front-Cover Texts being <var>list</var>, and with the Back-Cover Texts |
| being <var>list</var>. |
| </pre></div> |
| |
| <p>If you have Invariant Sections without Cover Texts, or some other |
| combination of the three, merge those two alternatives to suit the |
| situation. |
| </p> |
| <p>If your document contains nontrivial examples of program code, we |
| recommend releasing these examples in parallel under your choice of |
| free software license, such as the GNU General Public License, |
| to permit their use in free software. |
| </p> |
| |
| <hr> |
| <a name="Index"></a> |
| <div class="header"> |
| <p> |
| Previous: <a href="#GNU-Free-Documentation-License" accesskey="p" rel="prev">GNU Free Documentation License</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p> |
| </div> |
| <a name="Index-1"></a> |
| <h2 class="unnumbered">Index</h2> |
| <table><tr><th valign="top">Jump to: </th><td><a class="summary-letter" href="#Index_cp_symbol-1"><b>#</b></a> |
| |
| <a class="summary-letter" href="#Index_cp_symbol-2"><b>-</b></a> |
| |
| <br> |
| <a class="summary-letter" href="#Index_cp_letter-A"><b>A</b></a> |
| |
| <a class="summary-letter" href="#Index_cp_letter-B"><b>B</b></a> |
| |
| <a class="summary-letter" href="#Index_cp_letter-C"><b>C</b></a> |
| |
| <a class="summary-letter" href="#Index_cp_letter-D"><b>D</b></a> |
| |
| <a class="summary-letter" href="#Index_cp_letter-E"><b>E</b></a> |
| |
| <a class="summary-letter" href="#Index_cp_letter-F"><b>F</b></a> |
| |
| <a class="summary-letter" href="#Index_cp_letter-G"><b>G</b></a> |
| |
| <a class="summary-letter" href="#Index_cp_letter-I"><b>I</b></a> |
| |
| <a class="summary-letter" href="#Index_cp_letter-K"><b>K</b></a> |
| |
| <a class="summary-letter" href="#Index_cp_letter-L"><b>L</b></a> |
| |
| <a class="summary-letter" href="#Index_cp_letter-M"><b>M</b></a> |
| |
| <a class="summary-letter" href="#Index_cp_letter-N"><b>N</b></a> |
| |
| <a class="summary-letter" href="#Index_cp_letter-O"><b>O</b></a> |
| |
| <a class="summary-letter" href="#Index_cp_letter-P"><b>P</b></a> |
| |
| <a class="summary-letter" href="#Index_cp_letter-Q"><b>Q</b></a> |
| |
| <a class="summary-letter" href="#Index_cp_letter-R"><b>R</b></a> |
| |
| <a class="summary-letter" href="#Index_cp_letter-S"><b>S</b></a> |
| |
| <a class="summary-letter" href="#Index_cp_letter-T"><b>T</b></a> |
| |
| <a class="summary-letter" href="#Index_cp_letter-U"><b>U</b></a> |
| |
| <a class="summary-letter" href="#Index_cp_letter-W"><b>W</b></a> |
| |
| <a class="summary-letter" href="#Index_cp_letter-X"><b>X</b></a> |
| |
| </td></tr></table> |
| <table class="index-cp" border="0"> |
| <tr><td></td><th align="left">Index Entry</th><td> </td><th align="left"> Section</th></tr> |
| <tr><td colspan="4"> <hr></td></tr> |
| <tr><th><a name="Index_cp_symbol-1">#</a></th><td></td><td></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-_0023endif_002c-commenting"><code>#endif</code>, commenting</a>:</td><td> </td><td valign="top"><a href="#Comments">Comments</a></td></tr> |
| <tr><td colspan="4"> <hr></td></tr> |
| <tr><th><a name="Index_cp_symbol-2">-</a></th><td></td><td></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-_002d_002dhelp-output">‘<samp>--help</samp>’ output</a>:</td><td> </td><td valign="top"><a href="#g_t_002d_002dhelp">--help</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-_002d_002dversion-output">‘<samp>--version</samp>’ output</a>:</td><td> </td><td valign="top"><a href="#g_t_002d_002dversion">--version</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-_002dWall-compiler-option">‘<samp>-Wall</samp>’ compiler option</a>:</td><td> </td><td valign="top"><a href="#Syntactic-Conventions">Syntactic Conventions</a></td></tr> |
| <tr><td colspan="4"> <hr></td></tr> |
| <tr><th><a name="Index_cp_letter-A">A</a></th><td></td><td></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-accepting-contributions">accepting contributions</a>:</td><td> </td><td valign="top"><a href="#Contributions">Contributions</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-address-for-bug-reports">address for bug reports</a>:</td><td> </td><td valign="top"><a href="#g_t_002d_002dhelp">--help</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-ANSI-C-standard"><small>ANSI</small> C standard</a>:</td><td> </td><td valign="top"><a href="#Standard-C">Standard C</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-arbitrary-limits-on-data">arbitrary limits on data</a>:</td><td> </td><td valign="top"><a href="#Semantics">Semantics</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-ASCII-characters">ASCII characters</a>:</td><td> </td><td valign="top"><a href="#Character-Set">Character Set</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-autoconf"><code>autoconf</code></a>:</td><td> </td><td valign="top"><a href="#System-Portability">System Portability</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-avoiding-proprietary-code">avoiding proprietary code</a>:</td><td> </td><td valign="top"><a href="#Reading-Non_002dFree-Code">Reading Non-Free Code</a></td></tr> |
| <tr><td colspan="4"> <hr></td></tr> |
| <tr><th><a name="Index_cp_letter-B">B</a></th><td></td><td></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-behavior_002c-dependent-on-program_0027s-name">behavior, dependent on program’s name</a>:</td><td> </td><td valign="top"><a href="#User-Interfaces">User Interfaces</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-binary-packages">binary packages</a>:</td><td> </td><td valign="top"><a href="#Install-Command-Categories">Install Command Categories</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-bindir"><code>bindir</code></a>:</td><td> </td><td valign="top"><a href="#Directory-Variables">Directory Variables</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-braces_002c-in-C-source">braces, in C source</a>:</td><td> </td><td valign="top"><a href="#Formatting">Formatting</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-bug-reports">bug reports</a>:</td><td> </td><td valign="top"><a href="#g_t_002d_002dhelp">--help</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-bug_002dstandards_0040gnu_002eorg-email-address"><code>bug-standards@gnu.org</code> email address</a>:</td><td> </td><td valign="top"><a href="#Preface">Preface</a></td></tr> |
| <tr><td colspan="4"> <hr></td></tr> |
| <tr><th><a name="Index_cp_letter-C">C</a></th><td></td><td></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-canonical-name-of-a-program">canonical name of a program</a>:</td><td> </td><td valign="top"><a href="#g_t_002d_002dversion">--version</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-casting-pointers-to-integers">casting pointers to integers</a>:</td><td> </td><td valign="top"><a href="#CPU-Portability">CPU Portability</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-CGI-programs_002c-standard-options-for">CGI programs, standard options for</a>:</td><td> </td><td valign="top"><a href="#Command_002dLine-Interfaces">Command-Line Interfaces</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-change-logs">change logs</a>:</td><td> </td><td valign="top"><a href="#Change-Logs">Change Logs</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-change-logs_002c-conditional-changes">change logs, conditional changes</a>:</td><td> </td><td valign="top"><a href="#Conditional-Changes">Conditional Changes</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-change-logs_002c-style">change logs, style</a>:</td><td> </td><td valign="top"><a href="#Style-of-Change-Logs">Style of Change Logs</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-character-set">character set</a>:</td><td> </td><td valign="top"><a href="#Character-Set">Character Set</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-command_002dline-arguments_002c-decoding">command-line arguments, decoding</a>:</td><td> </td><td valign="top"><a href="#Semantics">Semantics</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-command_002dline-interface">command-line interface</a>:</td><td> </td><td valign="top"><a href="#Command_002dLine-Interfaces">Command-Line Interfaces</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-commenting">commenting</a>:</td><td> </td><td valign="top"><a href="#Comments">Comments</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-compatibility-with-C-and-POSIX-standards">compatibility with C and <small>POSIX</small> standards</a>:</td><td> </td><td valign="top"><a href="#Compatibility">Compatibility</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-compiler-warnings">compiler warnings</a>:</td><td> </td><td valign="top"><a href="#Syntactic-Conventions">Syntactic Conventions</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-conditional-changes_002c-and-change-logs">conditional changes, and change logs</a>:</td><td> </td><td valign="top"><a href="#Conditional-Changes">Conditional Changes</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-conditionals_002c-comments-for">conditionals, comments for</a>:</td><td> </td><td valign="top"><a href="#Comments">Comments</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-configure"><code>configure</code></a>:</td><td> </td><td valign="top"><a href="#Configuration">Configuration</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-control_002dL">control-L</a>:</td><td> </td><td valign="top"><a href="#Formatting">Formatting</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-conventions-for-makefiles">conventions for makefiles</a>:</td><td> </td><td valign="top"><a href="#Makefile-Conventions">Makefile Conventions</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-CORBA">CORBA</a>:</td><td> </td><td valign="top"><a href="#Graphical-Interfaces">Graphical Interfaces</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-credits-for-manuals">credits for manuals</a>:</td><td> </td><td valign="top"><a href="#Manual-Credits">Manual Credits</a></td></tr> |
| <tr><td colspan="4"> <hr></td></tr> |
| <tr><th><a name="Index_cp_letter-D">D</a></th><td></td><td></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-D_002dbus">D-bus</a>:</td><td> </td><td valign="top"><a href="#Graphical-Interfaces">Graphical Interfaces</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-data-types_002c-and-portability">data types, and portability</a>:</td><td> </td><td valign="top"><a href="#CPU-Portability">CPU Portability</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-declaration-for-system-functions">declaration for system functions</a>:</td><td> </td><td valign="top"><a href="#System-Functions">System Functions</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-DESTDIR"><code>DESTDIR</code></a>:</td><td> </td><td valign="top"><a href="#DESTDIR">DESTDIR</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-documentation">documentation</a>:</td><td> </td><td valign="top"><a href="#Documentation">Documentation</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-doschk"><code>doschk</code></a>:</td><td> </td><td valign="top"><a href="#Names">Names</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-downloading-this-manual">downloading this manual</a>:</td><td> </td><td valign="top"><a href="#Preface">Preface</a></td></tr> |
| <tr><td colspan="4"> <hr></td></tr> |
| <tr><th><a name="Index_cp_letter-E">E</a></th><td></td><td></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-encodings">encodings</a>:</td><td> </td><td valign="top"><a href="#Character-Set">Character Set</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-error-messages">error messages</a>:</td><td> </td><td valign="top"><a href="#Semantics">Semantics</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-error-messages_002c-formatting">error messages, formatting</a>:</td><td> </td><td valign="top"><a href="#Errors">Errors</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-exec_005fprefix"><code>exec_prefix</code></a>:</td><td> </td><td valign="top"><a href="#Directory-Variables">Directory Variables</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-expressions_002c-splitting">expressions, splitting</a>:</td><td> </td><td valign="top"><a href="#Formatting">Formatting</a></td></tr> |
| <tr><td colspan="4"> <hr></td></tr> |
| <tr><th><a name="Index_cp_letter-F">F</a></th><td></td><td></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-FDL_002c-GNU-Free-Documentation-License">FDL, GNU Free Documentation License</a>:</td><td> </td><td valign="top"><a href="#GNU-Free-Documentation-License">GNU Free Documentation License</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-file-usage">file usage</a>:</td><td> </td><td valign="top"><a href="#File-Usage">File Usage</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-file_002dname-limitations">file-name limitations</a>:</td><td> </td><td valign="top"><a href="#Names">Names</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-formatting-error-messages">formatting error messages</a>:</td><td> </td><td valign="top"><a href="#Errors">Errors</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-formatting-source-code">formatting source code</a>:</td><td> </td><td valign="top"><a href="#Formatting">Formatting</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-formfeed">formfeed</a>:</td><td> </td><td valign="top"><a href="#Formatting">Formatting</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-function-argument_002c-declaring">function argument, declaring</a>:</td><td> </td><td valign="top"><a href="#Syntactic-Conventions">Syntactic Conventions</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-function-prototypes">function prototypes</a>:</td><td> </td><td valign="top"><a href="#Standard-C">Standard C</a></td></tr> |
| <tr><td colspan="4"> <hr></td></tr> |
| <tr><th><a name="Index_cp_letter-G">G</a></th><td></td><td></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-getopt"><code>getopt</code></a>:</td><td> </td><td valign="top"><a href="#Command_002dLine-Interfaces">Command-Line Interfaces</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-gettext"><code>gettext</code></a>:</td><td> </td><td valign="top"><a href="#Internationalization">Internationalization</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-GNOME">GNOME</a>:</td><td> </td><td valign="top"><a href="#Graphical-Interfaces">Graphical Interfaces</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-GNOME-and-Guile">GNOME and Guile</a>:</td><td> </td><td valign="top"><a href="#Source-Language">Source Language</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-gnustandards-project-repository">gnustandards project repository</a>:</td><td> </td><td valign="top"><a href="#Preface">Preface</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-gnustandards_002dcommit_0040gnu_002eorg-mailing-list"><code>gnustandards-commit@gnu.org</code> mailing list</a>:</td><td> </td><td valign="top"><a href="#Preface">Preface</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-graphical-user-interface">graphical user interface</a>:</td><td> </td><td valign="top"><a href="#Graphical-Interfaces">Graphical Interfaces</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-grave-accent">grave accent</a>:</td><td> </td><td valign="top"><a href="#Quote-Characters">Quote Characters</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-GTK_002b">GTK+</a>:</td><td> </td><td valign="top"><a href="#Graphical-Interfaces">Graphical Interfaces</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-Guile">Guile</a>:</td><td> </td><td valign="top"><a href="#Source-Language">Source Language</a></td></tr> |
| <tr><td colspan="4"> <hr></td></tr> |
| <tr><th><a name="Index_cp_letter-I">I</a></th><td></td><td></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-implicit-int">implicit <code>int</code></a>:</td><td> </td><td valign="top"><a href="#Syntactic-Conventions">Syntactic Conventions</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-impossible-conditions">impossible conditions</a>:</td><td> </td><td valign="top"><a href="#Semantics">Semantics</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-installations_002c-staged">installations, staged</a>:</td><td> </td><td valign="top"><a href="#DESTDIR">DESTDIR</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-interface-styles">interface styles</a>:</td><td> </td><td valign="top"><a href="#Graphical-Interfaces">Graphical Interfaces</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-internationalization">internationalization</a>:</td><td> </td><td valign="top"><a href="#Internationalization">Internationalization</a></td></tr> |
| <tr><td colspan="4"> <hr></td></tr> |
| <tr><th><a name="Index_cp_letter-K">K</a></th><td></td><td></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-keyboard-interface">keyboard interface</a>:</td><td> </td><td valign="top"><a href="#Graphical-Interfaces">Graphical Interfaces</a></td></tr> |
| <tr><td colspan="4"> <hr></td></tr> |
| <tr><th><a name="Index_cp_letter-L">L</a></th><td></td><td></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-LDAP">LDAP</a>:</td><td> </td><td valign="top"><a href="#OID-Allocations">OID Allocations</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-left-quote">left quote</a>:</td><td> </td><td valign="top"><a href="#Quote-Characters">Quote Characters</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-legal-aspects">legal aspects</a>:</td><td> </td><td valign="top"><a href="#Legal-Issues">Legal Issues</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-legal-papers">legal papers</a>:</td><td> </td><td valign="top"><a href="#Contributions">Contributions</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-libexecdir"><code>libexecdir</code></a>:</td><td> </td><td valign="top"><a href="#Directory-Variables">Directory Variables</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-libraries">libraries</a>:</td><td> </td><td valign="top"><a href="#Libraries">Libraries</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-library-functions_002c-and-portability">library functions, and portability</a>:</td><td> </td><td valign="top"><a href="#System-Functions">System Functions</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-library-interface">library interface</a>:</td><td> </td><td valign="top"><a href="#Graphical-Interfaces">Graphical Interfaces</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-license-for-manuals">license for manuals</a>:</td><td> </td><td valign="top"><a href="#License-for-Manuals">License for Manuals</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-lint"><code>lint</code></a>:</td><td> </td><td valign="top"><a href="#Syntactic-Conventions">Syntactic Conventions</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-locale_002dspecific-quote-characters">locale-specific quote characters</a>:</td><td> </td><td valign="top"><a href="#Quote-Characters">Quote Characters</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-long-option-names">long option names</a>:</td><td> </td><td valign="top"><a href="#Option-Table">Option Table</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-long_002dnamed-options">long-named options</a>:</td><td> </td><td valign="top"><a href="#Command_002dLine-Interfaces">Command-Line Interfaces</a></td></tr> |
| <tr><td colspan="4"> <hr></td></tr> |
| <tr><th><a name="Index_cp_letter-M">M</a></th><td></td><td></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-makefile_002c-conventions-for">makefile, conventions for</a>:</td><td> </td><td valign="top"><a href="#Makefile-Conventions">Makefile Conventions</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-malloc-return-value"><code>malloc</code> return value</a>:</td><td> </td><td valign="top"><a href="#Semantics">Semantics</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-man-pages">man pages</a>:</td><td> </td><td valign="top"><a href="#Man-Pages">Man Pages</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-manual-structure">manual structure</a>:</td><td> </td><td valign="top"><a href="#Manual-Structure-Details">Manual Structure Details</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-memory-allocation-failure">memory allocation failure</a>:</td><td> </td><td valign="top"><a href="#Semantics">Semantics</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-memory-usage">memory usage</a>:</td><td> </td><td valign="top"><a href="#Memory-Usage">Memory Usage</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-message-text_002c-and-internationalization">message text, and internationalization</a>:</td><td> </td><td valign="top"><a href="#Internationalization">Internationalization</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-mmap"><code>mmap</code></a>:</td><td> </td><td valign="top"><a href="#Mmap">Mmap</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-multiple-variables-in-a-line">multiple variables in a line</a>:</td><td> </td><td valign="top"><a href="#Syntactic-Conventions">Syntactic Conventions</a></td></tr> |
| <tr><td colspan="4"> <hr></td></tr> |
| <tr><th><a name="Index_cp_letter-N">N</a></th><td></td><td></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-names-of-variables_002c-functions_002c-and-files">names of variables, functions, and files</a>:</td><td> </td><td valign="top"><a href="#Names">Names</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-NEWS-file"><samp>NEWS</samp> file</a>:</td><td> </td><td valign="top"><a href="#NEWS-File">NEWS File</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-non_002dASCII-characters">non-ASCII characters</a>:</td><td> </td><td valign="top"><a href="#Character-Set">Character Set</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-non_002dPOSIX-systems_002c-and-portability">non-<small>POSIX</small> systems, and portability</a>:</td><td> </td><td valign="top"><a href="#System-Portability">System Portability</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-non_002dstandard-extensions">non-standard extensions</a>:</td><td> </td><td valign="top"><a href="#Using-Extensions">Using Extensions</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-NUL-characters"><code>NUL</code> characters</a>:</td><td> </td><td valign="top"><a href="#Semantics">Semantics</a></td></tr> |
| <tr><td colspan="4"> <hr></td></tr> |
| <tr><th><a name="Index_cp_letter-O">O</a></th><td></td><td></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-OID-allocations-for-GNU">OID allocations for GNU</a>:</td><td> </td><td valign="top"><a href="#OID-Allocations">OID Allocations</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-open-brace">open brace</a>:</td><td> </td><td valign="top"><a href="#Formatting">Formatting</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-optional-features_002c-configure_002dtime">optional features, configure-time</a>:</td><td> </td><td valign="top"><a href="#Configuration">Configuration</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-options-for-compatibility">options for compatibility</a>:</td><td> </td><td valign="top"><a href="#Compatibility">Compatibility</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-options_002c-standard-command_002dline">options, standard command-line</a>:</td><td> </td><td valign="top"><a href="#Command_002dLine-Interfaces">Command-Line Interfaces</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-output-device-and-program_0027s-behavior">output device and program’s behavior</a>:</td><td> </td><td valign="top"><a href="#User-Interfaces">User Interfaces</a></td></tr> |
| <tr><td colspan="4"> <hr></td></tr> |
| <tr><th><a name="Index_cp_letter-P">P</a></th><td></td><td></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-packaging">packaging</a>:</td><td> </td><td valign="top"><a href="#Releases">Releases</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-PATH_005fINFO_002c-specifying-standard-options-as">PATH_INFO, specifying standard options as</a>:</td><td> </td><td valign="top"><a href="#Command_002dLine-Interfaces">Command-Line Interfaces</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-portability_002c-and-data-types">portability, and data types</a>:</td><td> </td><td valign="top"><a href="#CPU-Portability">CPU Portability</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-portability_002c-and-library-functions">portability, and library functions</a>:</td><td> </td><td valign="top"><a href="#System-Functions">System Functions</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-portability_002c-between-system-types">portability, between system types</a>:</td><td> </td><td valign="top"><a href="#System-Portability">System Portability</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-POSIX-compatibility"><small>POSIX</small> compatibility</a>:</td><td> </td><td valign="top"><a href="#Compatibility">Compatibility</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-POSIXLY_005fCORRECT_002c-environment-variable"><code>POSIXLY_CORRECT</code>, environment variable</a>:</td><td> </td><td valign="top"><a href="#Compatibility">Compatibility</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-post_002dinstallation-commands">post-installation commands</a>:</td><td> </td><td valign="top"><a href="#Install-Command-Categories">Install Command Categories</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-pre_002dinstallation-commands">pre-installation commands</a>:</td><td> </td><td valign="top"><a href="#Install-Command-Categories">Install Command Categories</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-prefix"><code>prefix</code></a>:</td><td> </td><td valign="top"><a href="#Directory-Variables">Directory Variables</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-program-configuration">program configuration</a>:</td><td> </td><td valign="top"><a href="#Configuration">Configuration</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-program-design">program design</a>:</td><td> </td><td valign="top"><a href="#Design-Advice">Design Advice</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-program-name-and-its-behavior">program name and its behavior</a>:</td><td> </td><td valign="top"><a href="#User-Interfaces">User Interfaces</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-program_0027s-canonical-name">program’s canonical name</a>:</td><td> </td><td valign="top"><a href="#g_t_002d_002dversion">--version</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-programming-languages">programming languages</a>:</td><td> </td><td valign="top"><a href="#Source-Language">Source Language</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-proprietary-programs">proprietary programs</a>:</td><td> </td><td valign="top"><a href="#Reading-Non_002dFree-Code">Reading Non-Free Code</a></td></tr> |
| <tr><td colspan="4"> <hr></td></tr> |
| <tr><th><a name="Index_cp_letter-Q">Q</a></th><td></td><td></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-quote-characters">quote characters</a>:</td><td> </td><td valign="top"><a href="#Quote-Characters">Quote Characters</a></td></tr> |
| <tr><td colspan="4"> <hr></td></tr> |
| <tr><th><a name="Index_cp_letter-R">R</a></th><td></td><td></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-README-file"><samp>README</samp> file</a>:</td><td> </td><td valign="top"><a href="#Releases">Releases</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-references-to-non_002dfree-material">references to non-free material</a>:</td><td> </td><td valign="top"><a href="#References">References</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-releasing">releasing</a>:</td><td> </td><td valign="top"><a href="#Managing-Releases">Managing Releases</a></td></tr> |
| <tr><td colspan="4"> <hr></td></tr> |
| <tr><th><a name="Index_cp_letter-S">S</a></th><td></td><td></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-Savannah-repository-for-gnustandards">Savannah repository for gnustandards</a>:</td><td> </td><td valign="top"><a href="#Preface">Preface</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-sbindir"><code>sbindir</code></a>:</td><td> </td><td valign="top"><a href="#Directory-Variables">Directory Variables</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-signal-handling">signal handling</a>:</td><td> </td><td valign="top"><a href="#Semantics">Semantics</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-SNMP">SNMP</a>:</td><td> </td><td valign="top"><a href="#OID-Allocations">OID Allocations</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-spaces-before-open_002dparen">spaces before open-paren</a>:</td><td> </td><td valign="top"><a href="#Formatting">Formatting</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-staged-installs">staged installs</a>:</td><td> </td><td valign="top"><a href="#DESTDIR">DESTDIR</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-standard-command_002dline-options">standard command-line options</a>:</td><td> </td><td valign="top"><a href="#Command_002dLine-Interfaces">Command-Line Interfaces</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-standards-for-makefiles">standards for makefiles</a>:</td><td> </td><td valign="top"><a href="#Makefile-Conventions">Makefile Conventions</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-string-library-functions">string library functions</a>:</td><td> </td><td valign="top"><a href="#System-Functions">System Functions</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-syntactic-conventions">syntactic conventions</a>:</td><td> </td><td valign="top"><a href="#Syntactic-Conventions">Syntactic Conventions</a></td></tr> |
| <tr><td colspan="4"> <hr></td></tr> |
| <tr><th><a name="Index_cp_letter-T">T</a></th><td></td><td></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-table-of-long-options">table of long options</a>:</td><td> </td><td valign="top"><a href="#Option-Table">Option Table</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-temporary-files">temporary files</a>:</td><td> </td><td valign="top"><a href="#Semantics">Semantics</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-temporary-variables">temporary variables</a>:</td><td> </td><td valign="top"><a href="#Syntactic-Conventions">Syntactic Conventions</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-texinfo_002etex_002c-in-a-distribution"><samp>texinfo.tex</samp>, in a distribution</a>:</td><td> </td><td valign="top"><a href="#Releases">Releases</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-TMPDIR-environment-variable"><code>TMPDIR</code> environment variable</a>:</td><td> </td><td valign="top"><a href="#Semantics">Semantics</a></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-trademarks">trademarks</a>:</td><td> </td><td valign="top"><a href="#Trademarks">Trademarks</a></td></tr> |
| <tr><td colspan="4"> <hr></td></tr> |
| <tr><th><a name="Index_cp_letter-U">U</a></th><td></td><td></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-user-interface-styles">user interface styles</a>:</td><td> </td><td valign="top"><a href="#Graphical-Interfaces">Graphical Interfaces</a></td></tr> |
| <tr><td colspan="4"> <hr></td></tr> |
| <tr><th><a name="Index_cp_letter-W">W</a></th><td></td><td></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-where-to-obtain-standards_002etexi">where to obtain <code>standards.texi</code></a>:</td><td> </td><td valign="top"><a href="#Preface">Preface</a></td></tr> |
| <tr><td colspan="4"> <hr></td></tr> |
| <tr><th><a name="Index_cp_letter-X">X</a></th><td></td><td></td></tr> |
| <tr><td></td><td valign="top"><a href="#index-X_002e509">X.509</a>:</td><td> </td><td valign="top"><a href="#OID-Allocations">OID Allocations</a></td></tr> |
| <tr><td colspan="4"> <hr></td></tr> |
| </table> |
| <table><tr><th valign="top">Jump to: </th><td><a class="summary-letter" href="#Index_cp_symbol-1"><b>#</b></a> |
| |
| <a class="summary-letter" href="#Index_cp_symbol-2"><b>-</b></a> |
| |
| <br> |
| <a class="summary-letter" href="#Index_cp_letter-A"><b>A</b></a> |
| |
| <a class="summary-letter" href="#Index_cp_letter-B"><b>B</b></a> |
| |
| <a class="summary-letter" href="#Index_cp_letter-C"><b>C</b></a> |
| |
| <a class="summary-letter" href="#Index_cp_letter-D"><b>D</b></a> |
| |
| <a class="summary-letter" href="#Index_cp_letter-E"><b>E</b></a> |
| |
| <a class="summary-letter" href="#Index_cp_letter-F"><b>F</b></a> |
| |
| <a class="summary-letter" href="#Index_cp_letter-G"><b>G</b></a> |
| |
| <a class="summary-letter" href="#Index_cp_letter-I"><b>I</b></a> |
| |
| <a class="summary-letter" href="#Index_cp_letter-K"><b>K</b></a> |
| |
| <a class="summary-letter" href="#Index_cp_letter-L"><b>L</b></a> |
| |
| <a class="summary-letter" href="#Index_cp_letter-M"><b>M</b></a> |
| |
| <a class="summary-letter" href="#Index_cp_letter-N"><b>N</b></a> |
| |
| <a class="summary-letter" href="#Index_cp_letter-O"><b>O</b></a> |
| |
| <a class="summary-letter" href="#Index_cp_letter-P"><b>P</b></a> |
| |
| <a class="summary-letter" href="#Index_cp_letter-Q"><b>Q</b></a> |
| |
| <a class="summary-letter" href="#Index_cp_letter-R"><b>R</b></a> |
| |
| <a class="summary-letter" href="#Index_cp_letter-S"><b>S</b></a> |
| |
| <a class="summary-letter" href="#Index_cp_letter-T"><b>T</b></a> |
| |
| <a class="summary-letter" href="#Index_cp_letter-U"><b>U</b></a> |
| |
| <a class="summary-letter" href="#Index_cp_letter-W"><b>W</b></a> |
| |
| <a class="summary-letter" href="#Index_cp_letter-X"><b>X</b></a> |
| |
| </td></tr></table> |
| |
| <div class="footnote"> |
| <hr> |
| <h4 class="footnotes-heading">Footnotes</h4> |
| |
| <h3><a name="FOOT1" href="#DOCF1">(1)</a></h3> |
| <p><code>texi2dvi</code> uses TeX to do the real work |
| of formatting. TeX is not distributed with Texinfo.</p> |
| </div> |
| <hr> |
| |
| |
| |
| </body> |
| </html> |
