You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
5543 lines
288 KiB
HTML
5543 lines
288 KiB
HTML
15 years ago
|
<html lang="en">
|
||
|
|
<head>
|
||
|
|
<title>GNU Coding Standards</title>
|
||
|
|
<meta http-equiv="Content-Type" content="text/html">
|
||
|
|
<meta name="description" content="GNU Coding Standards">
|
||
|
|
<meta name="generator" content="makeinfo 4.7">
|
||
|
|
<link title="Top" rel="top" href="#Top">
|
||
|
|
<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
|
||
|
|
<!--
|
||
|
|
The GNU coding standards, last updated July 22, 2007.
|
||
|
|
|
||
|
|
Copyright (C) 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999,
|
||
|
|
2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007 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.2
|
||
|
|
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".-->
|
||
|
|
<meta http-equiv="Content-Style-Type" content="text/css">
|
||
|
|
<style type="text/css"><!--
|
||
|
|
pre.display { font-family:inherit }
|
||
|
|
pre.format { font-family:inherit }
|
||
|
|
pre.smalldisplay { font-family:inherit; font-size:smaller }
|
||
|
|
pre.smallformat { font-family:inherit; font-size:smaller }
|
||
|
|
pre.smallexample { font-size:smaller }
|
||
|
|
pre.smalllisp { font-size:smaller }
|
||
|
|
span.sc { font-variant:small-caps }
|
||
|
|
span.roman { font-family: serif; font-weight: normal; }
|
||
|
|
--></style>
|
||
|
|
</head>
|
||
|
|
<body>
|
||
|
|
<h1 class="settitle">GNU Coding Standards</h1>
|
||
|
|
<div class="contents">
|
||
|
|
<h2>Table of Contents</h2>
|
||
|
|
<ul>
|
||
|
|
<li><a name="toc_Top" href="#Top">Version</a>
|
||
|
|
<li><a name="toc_Preface" href="#Preface">1 About the GNU Coding Standards</a>
|
||
|
|
<li><a name="toc_Legal-Issues" href="#Legal-Issues">2 Keeping Free Software Free</a>
|
||
|
|
<ul>
|
||
|
|
<li><a href="#Reading-Non_002dFree-Code">2.1 Referring to Proprietary Programs</a>
|
||
|
|
<li><a href="#Contributions">2.2 Accepting Contributions</a>
|
||
|
|
<li><a href="#Trademarks">2.3 Trademarks</a>
|
||
|
|
</li></ul>
|
||
|
|
<li><a name="toc_Design-Advice" href="#Design-Advice">3 General Program Design</a>
|
||
|
|
<ul>
|
||
|
|
<li><a href="#Source-Language">3.1 Which Languages to Use</a>
|
||
|
|
<li><a href="#Compatibility">3.2 Compatibility with Other Implementations</a>
|
||
|
|
<li><a href="#Using-Extensions">3.3 Using Non-standard Features</a>
|
||
|
|
<li><a href="#Standard-C">3.4 Standard C and Pre-Standard C</a>
|
||
|
|
<li><a href="#Conditional-Compilation">3.5 Conditional Compilation</a>
|
||
|
|
</li></ul>
|
||
|
|
<li><a name="toc_Program-Behavior" href="#Program-Behavior">4 Program Behavior for All Programs</a>
|
||
|
|
<ul>
|
||
|
|
<li><a href="#Non_002dGNU-Standards">4.1 Non-GNU Standards</a>
|
||
|
|
<li><a href="#Semantics">4.2 Writing Robust Programs</a>
|
||
|
|
<li><a href="#Libraries">4.3 Library Behavior</a>
|
||
|
|
<li><a href="#Errors">4.4 Formatting Error Messages</a>
|
||
|
|
<li><a href="#User-Interfaces">4.5 Standards for Interfaces Generally</a>
|
||
|
|
<li><a href="#Graphical-Interfaces">4.6 Standards for Graphical Interfaces</a>
|
||
|
|
<li><a href="#Command_002dLine-Interfaces">4.7 Standards for Command Line Interfaces</a>
|
||
|
|
<ul>
|
||
|
|
<li><a href="#_002d_002dversion">4.7.1 <span class="option">--version</span></a>
|
||
|
|
<li><a href="#_002d_002dhelp">4.7.2 <span class="option">--help</span></a>
|
||
|
|
</li></ul>
|
||
|
|
<li><a href="#Option-Table">4.8 Table of Long Options</a>
|
||
|
|
<li><a href="#Memory-Usage">4.9 Memory Usage</a>
|
||
|
|
<li><a href="#File-Usage">4.10 File Usage</a>
|
||
|
|
</li></ul>
|
||
|
|
<li><a name="toc_Writing-C" href="#Writing-C">5 Making The Best Use of C</a>
|
||
|
|
<ul>
|
||
|
|
<li><a href="#Formatting">5.1 Formatting Your Source Code</a>
|
||
|
|
<li><a href="#Comments">5.2 Commenting Your Work</a>
|
||
|
|
<li><a href="#Syntactic-Conventions">5.3 Clean Use of C Constructs</a>
|
||
|
|
<li><a href="#Names">5.4 Naming Variables, Functions, and Files</a>
|
||
|
|
<li><a href="#System-Portability">5.5 Portability between System Types</a>
|
||
|
|
<li><a href="#CPU-Portability">5.6 Portability between <span class="sc">cpu</span>s</a>
|
||
|
|
<li><a href="#System-Functions">5.7 Calling System Functions</a>
|
||
|
|
<li><a href="#Internationalization">5.8 Internationalization</a>
|
||
|
|
<li><a href="#Character-Set">5.9 Character Set</a>
|
||
|
|
<li><a href="#Quote-Characters">5.10 Quote Characters</a>
|
||
|
|
<li><a href="#Mmap">5.11 Mmap</a>
|
||
|
|
</li></ul>
|
||
|
|
<li><a name="toc_Documentation" href="#Documentation">6 Documenting Programs</a>
|
||
|
|
<ul>
|
||
|
|
<li><a href="#GNU-Manuals">6.1 GNU Manuals</a>
|
||
|
|
<li><a href="#Doc-Strings-and-Manuals">6.2 Doc Strings and Manuals</a>
|
||
|
|
<li><a href="#Manual-Structure-Details">6.3 Manual Structure Details</a>
|
||
|
|
<li><a href="#License-for-Manuals">6.4 License for Manuals</a>
|
||
|
|
<li><a href="#Manual-Credits">6.5 Manual Credits</a>
|
||
|
|
<li><a href="#Printed-Manuals">6.6 Printed Manuals</a>
|
||
|
|
<li><a href="#NEWS-File">6.7 The NEWS File</a>
|
||
|
|
<li><a href="#Change-Logs">6.8 Change Logs</a>
|
||
|
|
<ul>
|
||
|
|
<li><a href="#Change-Log-Concepts">6.8.1 Change Log Concepts</a>
|
||
|
|
<li><a href="#Style-of-Change-Logs">6.8.2 Style of Change Logs</a>
|
||
|
|
<li><a href="#Simple-Changes">6.8.3 Simple Changes</a>
|
||
|
|
<li><a href="#Conditional-Changes">6.8.4 Conditional Changes</a>
|
||
|
|
<li><a href="#Indicating-the-Part-Changed">6.8.5 Indicating the Part Changed</a>
|
||
|
|
</li></ul>
|
||
|
|
<li><a href="#Man-Pages">6.9 Man Pages</a>
|
||
|
|
<li><a href="#Reading-other-Manuals">6.10 Reading other Manuals</a>
|
||
|
|
</li></ul>
|
||
|
|
<li><a name="toc_Managing-Releases" href="#Managing-Releases">7 The Release Process</a>
|
||
|
|
<ul>
|
||
|
|
<li><a href="#Configuration">7.1 How Configuration Should Work</a>
|
||
|
|
<li><a href="#Makefile-Conventions">7.2 Makefile Conventions</a>
|
||
|
|
<ul>
|
||
|
|
<li><a href="#Makefile-Basics">7.2.1 General Conventions for Makefiles</a>
|
||
|
|
<li><a href="#Utilities-in-Makefiles">7.2.2 Utilities in Makefiles</a>
|
||
|
|
<li><a href="#Command-Variables">7.2.3 Variables for Specifying Commands</a>
|
||
|
|
<li><a href="#DESTDIR">7.2.4 <code>DESTDIR</code>: support for staged installs</a>
|
||
|
|
<li><a href="#Directory-Variables">7.2.5 Variables for Installation Directories</a>
|
||
|
|
<li><a href="#Standard-Targets">7.2.6 Standard Targets for Users</a>
|
||
|
|
<li><a href="#Install-Command-Categories">7.2.7 Install Command Categories</a>
|
||
|
|
</li></ul>
|
||
|
|
<li><a href="#Releases">7.3 Making Releases</a>
|
||
|
|
</li></ul>
|
||
|
|
<li><a name="toc_References" href="#References">8 References to Non-Free Software and Documentation</a>
|
||
|
|
<li><a name="toc_GNU-Free-Documentation-License" href="#GNU-Free-Documentation-License">Appendix A GNU Free Documentation License</a>
|
||
|
|
<li><a name="toc_Index" href="#Index">Index</a>
|
||
|
|
</li></ul>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
<div class="node">
|
||
|
|
<p><hr>
|
||
|
|
<a name="Top"></a>Next: <a rel="next" accesskey="n" href="#Preface">Preface</a>,
|
||
|
|
Previous: <a rel="previous" accesskey="p" href="#dir">(dir)</a>,
|
||
|
|
Up: <a rel="up" accesskey="u" href="#dir">(dir)</a>
|
||
|
|
<br>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<h2 class="unnumbered">Version</h2>
|
||
|
|
|
||
|
|
<p>The GNU coding standards, last updated July 22, 2007.
|
||
|
|
|
||
|
|
<p>Copyright © 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999,
|
||
|
|
2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007 Free Software
|
||
|
|
Foundation, Inc.
|
||
|
|
|
||
|
|
<p>Permission is granted to copy, distribute and/or modify this document
|
||
|
|
under the terms of the GNU Free Documentation License, Version 1.2
|
||
|
|
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”.
|
||
|
|
|
||
|
|
<ul class="menu">
|
||
|
|
<li><a accesskey="1" href="#Preface">Preface</a>: About the GNU Coding Standards.
|
||
|
|
<li><a accesskey="2" href="#Legal-Issues">Legal Issues</a>: Keeping free software free.
|
||
|
|
<li><a accesskey="3" href="#Design-Advice">Design Advice</a>: General program design.
|
||
|
|
<li><a accesskey="4" href="#Program-Behavior">Program Behavior</a>: Program behavior for all programs
|
||
|
|
<li><a accesskey="5" href="#Writing-C">Writing C</a>: Making the best use of C.
|
||
|
|
<li><a accesskey="6" href="#Documentation">Documentation</a>: Documenting programs.
|
||
|
|
<li><a accesskey="7" href="#Managing-Releases">Managing Releases</a>: The release process.
|
||
|
|
<li><a accesskey="8" href="#References">References</a>: Mentioning non-free software or documentation.
|
||
|
|
<li><a accesskey="9" href="#GNU-Free-Documentation-License">GNU Free Documentation License</a>: Copying and sharing this manual.
|
||
|
|
<li><a href="#Index">Index</a>
|
||
|
|
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<div class="node">
|
||
|
|
<p><hr>
|
||
|
|
<a name="Preface"></a>Next: <a rel="next" accesskey="n" href="#Legal-Issues">Legal Issues</a>,
|
||
|
|
Previous: <a rel="previous" accesskey="p" href="#Top">Top</a>,
|
||
|
|
Up: <a rel="up" accesskey="u" href="#Top">Top</a>
|
||
|
|
<br>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<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>This release of the GNU Coding Standards was last updated
|
||
|
|
July 22, 2007.
|
||
|
|
|
||
|
|
<p><a name="index-where-to-obtain-_0040code_007bstandards_002etexi_007d-1"></a><a name="index-downloading-this-manual-2"></a>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>Corrections or suggestions for this document should be sent 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; our time is limited. We prefer a context
|
||
|
|
diff to the <span class="file">standards.texi</span> or <span class="file">make-stds.texi</span> files, but if
|
||
|
|
you don't have those files, please mail your suggestion anyway.
|
||
|
|
|
||
|
|
<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>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>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>.
|
||
|
|
|
||
|
|
<div class="node">
|
||
|
|
<p><hr>
|
||
|
|
<a name="Legal-Issues"></a>Next: <a rel="next" accesskey="n" href="#Design-Advice">Design Advice</a>,
|
||
|
|
Previous: <a rel="previous" accesskey="p" href="#Preface">Preface</a>,
|
||
|
|
Up: <a rel="up" accesskey="u" href="#Top">Top</a>
|
||
|
|
<br>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<h2 class="chapter">2 Keeping Free Software Free</h2>
|
||
|
|
|
||
|
|
<p><a name="index-legal-aspects-3"></a>
|
||
|
|
This chapter discusses how you can make sure that GNU software
|
||
|
|
avoids legal difficulties, and other related issues.
|
||
|
|
|
||
|
|
<ul class="menu">
|
||
|
|
<li><a accesskey="1" href="#Reading-Non_002dFree-Code">Reading Non-Free Code</a>: Referring to proprietary programs.
|
||
|
|
<li><a accesskey="2" href="#Contributions">Contributions</a>: Accepting contributions.
|
||
|
|
<li><a accesskey="3" href="#Trademarks">Trademarks</a>: How we deal with trademark issues.
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<div class="node">
|
||
|
|
<p><hr>
|
||
|
|
<a name="Reading-Non_002dFree-Code"></a>Next: <a rel="next" accesskey="n" href="#Contributions">Contributions</a>,
|
||
|
|
Up: <a rel="up" accesskey="u" href="#Legal-Issues">Legal Issues</a>
|
||
|
|
<br>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<h3 class="section">2.1 Referring to Proprietary Programs</h3>
|
||
|
|
|
||
|
|
<p><a name="index-proprietary-programs-4"></a><a name="index-avoiding-proprietary-code-5"></a>
|
||
|
|
Don't in any circumstances refer to Unix source code for or during
|
||
|
|
your work on GNU! (Or to any other proprietary programs.)
|
||
|
|
|
||
|
|
<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>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>Or, on the contrary, emphasize simplicity instead of speed. For some
|
||
|
|
applications, the speed of today's computers makes simpler algorithms
|
||
|
|
adequate.
|
||
|
|
|
||
|
|
<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>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.
|
||
|
|
|
||
|
|
<div class="node">
|
||
|
|
<p><hr>
|
||
|
|
<a name="Contributions"></a>Next: <a rel="next" accesskey="n" href="#Trademarks">Trademarks</a>,
|
||
|
|
Previous: <a rel="previous" accesskey="p" href="#Reading-Non_002dFree-Code">Reading Non-Free Code</a>,
|
||
|
|
Up: <a rel="up" accesskey="u" href="#Legal-Issues">Legal Issues</a>
|
||
|
|
<br>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<h3 class="section">2.2 Accepting Contributions</h3>
|
||
|
|
|
||
|
|
<p><a name="index-legal-papers-6"></a><a name="index-accepting-contributions-7"></a>
|
||
|
|
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>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>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>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>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>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>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>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>.
|
||
|
|
|
||
|
|
<div class="node">
|
||
|
|
<p><hr>
|
||
|
|
<a name="Trademarks"></a>Previous: <a rel="previous" accesskey="p" href="#Contributions">Contributions</a>,
|
||
|
|
Up: <a rel="up" accesskey="u" href="#Legal-Issues">Legal Issues</a>
|
||
|
|
<br>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<h3 class="section">2.3 Trademarks</h3>
|
||
|
|
|
||
|
|
<p><a name="index-trademarks-8"></a>
|
||
|
|
Please do not include any trademark acknowledgements in GNU software
|
||
|
|
packages or documentation.
|
||
|
|
|
||
|
|
<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>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>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 <span class="samp">w32</span>.
|
||
|
|
|
||
|
|
<div class="node">
|
||
|
|
<p><hr>
|
||
|
|
<a name="Design-Advice"></a>Next: <a rel="next" accesskey="n" href="#Program-Behavior">Program Behavior</a>,
|
||
|
|
Previous: <a rel="previous" accesskey="p" href="#Legal-Issues">Legal Issues</a>,
|
||
|
|
Up: <a rel="up" accesskey="u" href="#Top">Top</a>
|
||
|
|
<br>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<h2 class="chapter">3 General Program Design</h2>
|
||
|
|
|
||
|
|
<p><a name="index-program-design-9"></a>
|
||
|
|
This chapter discusses some of the issues you should take into
|
||
|
|
account when designing your program.
|
||
|
|
|
||
|
|
<!-- Standard or ANSI C -->
|
||
|
|
<!-- In 1989 the American National Standards Institute (ANSI) standardized -->
|
||
|
|
<!-- C as standard X3.159-1989. In December of that year the -->
|
||
|
|
<!-- International Standards Organization ISO adopted the ANSI C standard -->
|
||
|
|
<!-- making minor changes. In 1990 ANSI then re-adopted ISO standard -->
|
||
|
|
<!-- C. This version of C is known as either ANSI C or Standard C. -->
|
||
|
|
<!-- A major revision of the C Standard appeared in 1999. -->
|
||
|
|
<ul class="menu">
|
||
|
|
<li><a accesskey="1" href="#Source-Language">Source Language</a>: Which languages to use.
|
||
|
|
<li><a accesskey="2" href="#Compatibility">Compatibility</a>: Compatibility with other implementations.
|
||
|
|
<li><a accesskey="3" href="#Using-Extensions">Using Extensions</a>: Using non-standard features.
|
||
|
|
<li><a accesskey="4" href="#Standard-C">Standard C</a>: Using standard C features.
|
||
|
|
<li><a accesskey="5" href="#Conditional-Compilation">Conditional Compilation</a>: Compiling code only if a conditional is true.
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<div class="node">
|
||
|
|
<p><hr>
|
||
|
|
<a name="Source-Language"></a>Next: <a rel="next" accesskey="n" href="#Compatibility">Compatibility</a>,
|
||
|
|
Up: <a rel="up" accesskey="u" href="#Design-Advice">Design Advice</a>
|
||
|
|
<br>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<h3 class="section">3.1 Which Languages to Use</h3>
|
||
|
|
|
||
|
|
<p><a name="index-programming-languages-10"></a>
|
||
|
|
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>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>So in general it is much better to use C, rather than the
|
||
|
|
comparable alternatives.
|
||
|
|
|
||
|
|
<p>But there are two exceptions to that conclusion:
|
||
|
|
|
||
|
|
<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>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.
|
||
|
|
</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-11"></a>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). 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.
|
||
|
|
|
||
|
|
<div class="node">
|
||
|
|
<p><hr>
|
||
|
|
<a name="Compatibility"></a>Next: <a rel="next" accesskey="n" href="#Using-Extensions">Using Extensions</a>,
|
||
|
|
Previous: <a rel="previous" accesskey="p" href="#Source-Language">Source Language</a>,
|
||
|
|
Up: <a rel="up" accesskey="u" href="#Design-Advice">Design Advice</a>
|
||
|
|
<br>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<h3 class="section">3.2 Compatibility with Other Implementations</h3>
|
||
|
|
|
||
|
|
<p><a name="index-compatibility-with-C-and-_0040sc_007bposix_007d-standards-12"></a><a name="index-_0040sc_007bposix_007d-compatibility-13"></a>
|
||
|
|
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 <span class="sc">posix</span> if <span class="sc">posix</span> specifies
|
||
|
|
their behavior.
|
||
|
|
|
||
|
|
<p>When these standards conflict, it is useful to offer compatibility
|
||
|
|
modes for each of them.
|
||
|
|
|
||
|
|
<p><a name="index-options-for-compatibility-14"></a>Standard C and <span class="sc">posix</span> prohibit many kinds of extensions. Feel
|
||
|
|
free to make the extensions anyway, and include a <span class="samp">--ansi</span>,
|
||
|
|
<span class="samp">--posix</span>, or <span class="samp">--compatible</span> 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-_0040code_007bPOSIXLY_005fCORRECT_007d_002c-environment-variable-15"></a>Many GNU programs suppress extensions that conflict with <span class="sc">posix</span> 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>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>Additional useful features are welcome regardless of whether
|
||
|
|
there is any precedent for them.
|
||
|
|
|
||
|
|
<div class="node">
|
||
|
|
<p><hr>
|
||
|
|
<a name="Using-Extensions"></a>Next: <a rel="next" accesskey="n" href="#Standard-C">Standard C</a>,
|
||
|
|
Previous: <a rel="previous" accesskey="p" href="#Compatibility">Compatibility</a>,
|
||
|
|
Up: <a rel="up" accesskey="u" href="#Design-Advice">Design Advice</a>
|
||
|
|
<br>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<h3 class="section">3.3 Using Non-standard Features</h3>
|
||
|
|
|
||
|
|
<p><a name="index-non_002dstandard-extensions-16"></a>
|
||
|
|
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>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>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>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>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>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.
|
||
|
|
|
||
|
|
<div class="node">
|
||
|
|
<p><hr>
|
||
|
|
<a name="Standard-C"></a>Next: <a rel="next" accesskey="n" href="#Conditional-Compilation">Conditional Compilation</a>,
|
||
|
|
Previous: <a rel="previous" accesskey="p" href="#Using-Extensions">Using Extensions</a>,
|
||
|
|
Up: <a rel="up" accesskey="u" href="#Design-Advice">Design Advice</a>
|
||
|
|
<br>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<h3 class="section">3.4 Standard C and Pre-Standard C</h3>
|
||
|
|
|
||
|
|
<p><a name="index-_0040sc_007bansi_007d-C-standard-17"></a>
|
||
|
|
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>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>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-18"></a>To support pre-standard C, instead of writing function definitions in
|
||
|
|
standard prototype form,
|
||
|
|
|
||
|
|
<pre class="example"> int
|
||
|
|
foo (int x, int y)
|
||
|
|
...
|
||
|
|
</pre>
|
||
|
|
<p class="noindent">write the definition in pre-standard style like this,
|
||
|
|
|
||
|
|
<pre class="example"> int
|
||
|
|
foo (x, y)
|
||
|
|
int x, y;
|
||
|
|
...
|
||
|
|
</pre>
|
||
|
|
<p class="noindent">and use a separate declaration to specify the argument prototype:
|
||
|
|
|
||
|
|
<pre class="example"> int foo (int, int);
|
||
|
|
</pre>
|
||
|
|
<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>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>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>In order to support pre-standard compilers that do not recognize
|
||
|
|
prototypes, you may want to use a preprocessor macro like this:
|
||
|
|
|
||
|
|
<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 class="node">
|
||
|
|
<p><hr>
|
||
|
|
<a name="Conditional-Compilation"></a>Previous: <a rel="previous" accesskey="p" href="#Standard-C">Standard C</a>,
|
||
|
|
Up: <a rel="up" accesskey="u" href="#Design-Advice">Design Advice</a>
|
||
|
|
<br>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<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>For example, please write
|
||
|
|
|
||
|
|
<pre class="smallexample"> if (HAS_FOO)
|
||
|
|
...
|
||
|
|
else
|
||
|
|
...
|
||
|
|
</pre>
|
||
|
|
<p class="noindent">instead of:
|
||
|
|
|
||
|
|
<pre class="smallexample"> #ifdef HAS_FOO
|
||
|
|
...
|
||
|
|
#else
|
||
|
|
...
|
||
|
|
#endif
|
||
|
|
</pre>
|
||
|
|
<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>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>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:
|
||
|
|
|
||
|
|
<pre class="smallexample"> #ifdef REVERSIBLE_CC_MODE
|
||
|
|
#define HAS_REVERSIBLE_CC_MODE 1
|
||
|
|
#else
|
||
|
|
#define HAS_REVERSIBLE_CC_MODE 0
|
||
|
|
#endif
|
||
|
|
</pre>
|
||
|
|
<div class="node">
|
||
|
|
<p><hr>
|
||
|
|
<a name="Program-Behavior"></a>Next: <a rel="next" accesskey="n" href="#Writing-C">Writing C</a>,
|
||
|
|
Previous: <a rel="previous" accesskey="p" href="#Design-Advice">Design Advice</a>,
|
||
|
|
Up: <a rel="up" accesskey="u" href="#Top">Top</a>
|
||
|
|
<br>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<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.
|
||
|
|
|
||
|
|
<ul class="menu">
|
||
|
|
<li><a accesskey="1" href="#Non_002dGNU-Standards">Non-GNU Standards</a>: We consider standards such as POSIX;
|
||
|
|
we don't "obey" them.
|
||
|
|
<li><a accesskey="2" href="#Semantics">Semantics</a>: Writing robust programs.
|
||
|
|
<li><a accesskey="3" href="#Libraries">Libraries</a>: Library behavior.
|
||
|
|
<li><a accesskey="4" href="#Errors">Errors</a>: Formatting error messages.
|
||
|
|
<li><a accesskey="5" href="#User-Interfaces">User Interfaces</a>: Standards about interfaces generally.
|
||
|
|
<li><a accesskey="6" href="#Graphical-Interfaces">Graphical Interfaces</a>: Standards for graphical interfaces.
|
||
|
|
<li><a accesskey="7" href="#Command_002dLine-Interfaces">Command-Line Interfaces</a>: Standards for command line interfaces.
|
||
|
|
<li><a accesskey="8" href="#Option-Table">Option Table</a>: Table of long options.
|
||
|
|
<li><a accesskey="9" href="#Memory-Usage">Memory Usage</a>: When and how to care about memory needs.
|
||
|
|
<li><a href="#File-Usage">File Usage</a>: Which files to use, and where.
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<div class="node">
|
||
|
|
<p><hr>
|
||
|
|
<a name="Non_002dGNU-Standards"></a>Next: <a rel="next" accesskey="n" href="#Semantics">Semantics</a>,
|
||
|
|
Up: <a rel="up" accesskey="u" href="#Program-Behavior">Program Behavior</a>
|
||
|
|
<br>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<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>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>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>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 <span class="samp">--pedantic</span>, 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>POSIX.2 specifies that <span class="samp">df</span> and <span class="samp">du</span> 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
|
||
|
|
<span class="samp">POSIXLY_CORRECT</span> (which was originally going to be named
|
||
|
|
<span class="samp">POSIX_ME_HARDER</span>).
|
||
|
|
|
||
|
|
<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>In particular, don't reject a new feature, or remove an old one,
|
||
|
|
merely because a standard says it is “forbidden” or “deprecated.”
|
||
|
|
|
||
|
|
<div class="node">
|
||
|
|
<p><hr>
|
||
|
|
<a name="Semantics"></a>Next: <a rel="next" accesskey="n" href="#Libraries">Libraries</a>,
|
||
|
|
Previous: <a rel="previous" accesskey="p" href="#Non_002dGNU-Standards">Non-GNU Standards</a>,
|
||
|
|
Up: <a rel="up" accesskey="u" href="#Program-Behavior">Program Behavior</a>
|
||
|
|
<br>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<h3 class="section">4.2 Writing Robust Programs</h3>
|
||
|
|
|
||
|
|
<p><a name="index-arbitrary-limits-on-data-19"></a>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-_0040code_007bNUL_007d-characters-20"></a>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-21"></a>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-_0040code_007bmalloc_007d-return-value-22"></a><a name="index-memory-allocation-failure-23"></a>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>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>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>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-24"></a>Use <code>getopt_long</code> to decode arguments, unless the argument syntax
|
||
|
|
makes this unreasonable.
|
||
|
|
|
||
|
|
<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.
|
||
|
|
<!-- ADR: why? -->
|
||
|
|
|
||
|
|
<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-25"></a>The preferred signal handling facilities are the BSD variant of
|
||
|
|
<code>signal</code>, and the <span class="sc">posix</span> <code>sigaction</code> function; the
|
||
|
|
alternative USG <code>signal</code> interface is an inferior design.
|
||
|
|
|
||
|
|
<p>Nowadays, using the <span class="sc">posix</span> 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
|
||
|
|
<span class="file">bsd/signal.h</span> instead of <span class="file">signal.h</span>, 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-26"></a>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>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-27"></a><a name="index-_0040code_007bTMPDIR_007d-environment-variable-28"></a>If you make temporary files, check the <code>TMPDIR</code> environment
|
||
|
|
variable; if that variable is defined, use the specified directory
|
||
|
|
instead of <span class="file">/tmp</span>.
|
||
|
|
|
||
|
|
<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:
|
||
|
|
|
||
|
|
<pre class="example"> fd = open(filename, O_WRONLY | O_CREAT | O_EXCL, 0600);
|
||
|
|
</pre>
|
||
|
|
<p class="noindent">or by using the <code>mkstemps</code> function from libiberty.
|
||
|
|
|
||
|
|
<p>In bash, use <code>set -C</code> to avoid this problem.
|
||
|
|
|
||
|
|
<div class="node">
|
||
|
|
<p><hr>
|
||
|
|
<a name="Libraries"></a>Next: <a rel="next" accesskey="n" href="#Errors">Errors</a>,
|
||
|
|
Previous: <a rel="previous" accesskey="p" href="#Semantics">Semantics</a>,
|
||
|
|
Up: <a rel="up" accesskey="u" href="#Program-Behavior">Program Behavior</a>
|
||
|
|
<br>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<h3 class="section">4.3 Library Behavior</h3>
|
||
|
|
|
||
|
|
<p><a name="index-libraries-29"></a>
|
||
|
|
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>Here are certain name conventions for libraries, to avoid name
|
||
|
|
conflicts.
|
||
|
|
|
||
|
|
<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>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>External symbols that are not documented entry points for the user
|
||
|
|
should have names beginning with <span class="samp">_</span>. The <span class="samp">_</span> 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>Static functions and variables can be used as you like and need not
|
||
|
|
fit any naming convention.
|
||
|
|
|
||
|
|
<div class="node">
|
||
|
|
<p><hr>
|
||
|
|
<a name="Errors"></a>Next: <a rel="next" accesskey="n" href="#User-Interfaces">User Interfaces</a>,
|
||
|
|
Previous: <a rel="previous" accesskey="p" href="#Libraries">Libraries</a>,
|
||
|
|
Up: <a rel="up" accesskey="u" href="#Program-Behavior">Program Behavior</a>
|
||
|
|
<br>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<h3 class="section">4.4 Formatting Error Messages</h3>
|
||
|
|
|
||
|
|
<p><a name="index-formatting-error-messages-30"></a><a name="index-error-messages_002c-formatting-31"></a>
|
||
|
|
Error messages from compilers should look like this:
|
||
|
|
|
||
|
|
<pre class="example"> <var>source-file-name</var>:<var>lineno</var>: <var>message</var>
|
||
|
|
</pre>
|
||
|
|
<p class="noindent">If you want to mention the column number, use one of these formats:
|
||
|
|
|
||
|
|
<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>
|
||
|
|
<p class="noindent">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>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:
|
||
|
|
|
||
|
|
<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>
|
||
|
|
<p class="noindent">When an error is spread over several files, you can use this format:
|
||
|
|
|
||
|
|
<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>
|
||
|
|
<p>Error messages from other noninteractive programs should look like this:
|
||
|
|
|
||
|
|
<pre class="example"> <var>program</var>:<var>source-file-name</var>:<var>lineno</var>: <var>message</var>
|
||
|
|
</pre>
|
||
|
|
<p class="noindent">when there is an appropriate source file, or like this:
|
||
|
|
|
||
|
|
<pre class="example"> <var>program</var>: <var>message</var>
|
||
|
|
</pre>
|
||
|
|
<p class="noindent">when there is no relevant source file.
|
||
|
|
|
||
|
|
<p>If you want to mention the column number, use this format:
|
||
|
|
|
||
|
|
<pre class="example"> <var>program</var>:<var>source-file-name</var>:<var>lineno</var>:<var>column</var>: <var>message</var>
|
||
|
|
</pre>
|
||
|
|
<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>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>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.
|
||
|
|
|
||
|
|
<div class="node">
|
||
|
|
<p><hr>
|
||
|
|
<a name="User-Interfaces"></a>Next: <a rel="next" accesskey="n" href="#Graphical-Interfaces">Graphical Interfaces</a>,
|
||
|
|
Previous: <a rel="previous" accesskey="p" href="#Errors">Errors</a>,
|
||
|
|
Up: <a rel="up" accesskey="u" href="#Program-Behavior">Program Behavior</a>
|
||
|
|
<br>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<h3 class="section">4.5 Standards for Interfaces Generally</h3>
|
||
|
|
|
||
|
|
<p><a name="index-program-name-and-its-behavior-32"></a><a name="index-behavior_002c-dependent-on-program_0027s-name-33"></a>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>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-34"></a>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>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>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.
|
||
|
|
|
||
|
|
<div class="node">
|
||
|
|
<p><hr>
|
||
|
|
<a name="Graphical-Interfaces"></a>Next: <a rel="next" accesskey="n" href="#Command_002dLine-Interfaces">Command-Line Interfaces</a>,
|
||
|
|
Previous: <a rel="previous" accesskey="p" href="#User-Interfaces">User Interfaces</a>,
|
||
|
|
Up: <a rel="up" accesskey="u" href="#Program-Behavior">Program Behavior</a>
|
||
|
|
<br>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<h3 class="section">4.6 Standards for Graphical Interfaces</h3>
|
||
|
|
|
||
|
|
<p><a name="index-graphical-user-interface-35"></a>
|
||
|
|
<a name="index-gtk_002b-36"></a>When you write a program that provides a graphical user interface,
|
||
|
|
please make it work with X Windows and the GTK+ toolkit unless the
|
||
|
|
functionality specifically requires some alternative (for example,
|
||
|
|
“displaying jpeg images while in console mode”).
|
||
|
|
|
||
|
|
<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-37"></a><a name="index-gnome-38"></a>Please also consider providing a CORBA interface (for use from GNOME), 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.
|
||
|
|
|
||
|
|
<div class="node">
|
||
|
|
<p><hr>
|
||
|
|
<a name="Command_002dLine-Interfaces"></a>Next: <a rel="next" accesskey="n" href="#Option-Table">Option Table</a>,
|
||
|
|
Previous: <a rel="previous" accesskey="p" href="#Graphical-Interfaces">Graphical Interfaces</a>,
|
||
|
|
Up: <a rel="up" accesskey="u" href="#Program-Behavior">Program Behavior</a>
|
||
|
|
<br>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<h3 class="section">4.7 Standards for Command Line Interfaces</h3>
|
||
|
|
|
||
|
|
<p><a name="index-command_002dline-interface-39"></a>
|
||
|
|
<a name="index-getopt-40"></a>It is a good idea to follow the <span class="sc">posix</span> 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 <span class="samp">--</span> is used. This is not what <span class="sc">posix</span>
|
||
|
|
specifies; it is a GNU extension.
|
||
|
|
|
||
|
|
<p><a name="index-long_002dnamed-options-41"></a>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>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 <span class="samp">--verbose</span>. 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>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 <span class="samp">-o</span> or <span class="samp">--output</span>). 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-42"></a><a name="index-options_002c-standard-command_002dline-43"></a><a name="index-CGI-programs_002c-standard-options-for-44"></a><a name="index-PATH_005fINFO_002c-specifying-standard-options-as-45"></a>All programs should support two standard options: <span class="samp">--version</span>
|
||
|
|
and <span class="samp">--help</span>. CGI programs should accept these as command-line
|
||
|
|
options, and also if given as the <span class="env">PATH_INFO</span>; 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 <span class="samp">p.cgi --help</span> from the
|
||
|
|
command line.
|
||
|
|
|
||
|
|
<ul class="menu">
|
||
|
|
<li><a accesskey="1" href="#_002d_002dversion">--version</a>: The standard output for --version.
|
||
|
|
<li><a accesskey="2" href="#_002d_002dhelp">--help</a>: The standard output for --help.
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<div class="node">
|
||
|
|
<p><hr>
|
||
|
|
<a name="_002d_002dversion"></a>Next: <a rel="next" accesskey="n" href="#_002d_002dhelp">--help</a>,
|
||
|
|
Up: <a rel="up" accesskey="u" href="#Command_002dLine-Interfaces">Command-Line Interfaces</a>
|
||
|
|
<br>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<h4 class="subsection">4.7.1 <span class="option">--version</span></h4>
|
||
|
|
|
||
|
|
<p><a name="index-_0040samp_007b_002d_002dversion_007d-output-46"></a>
|
||
|
|
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-47"></a><a name="index-program_0027s-canonical-name-48"></a>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:
|
||
|
|
|
||
|
|
<pre class="example"> GNU Emacs 19.30
|
||
|
|
</pre>
|
||
|
|
<p class="noindent">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>If the program is a subsidiary part of a larger package, mention the
|
||
|
|
package name in parentheses, like this:
|
||
|
|
|
||
|
|
<pre class="example"> emacsserver (GNU Emacs) 19.30
|
||
|
|
</pre>
|
||
|
|
<p class="noindent">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>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>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>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>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>It is ok to finish the output with a list of the major authors of the
|
||
|
|
program, as a way of giving credit.
|
||
|
|
|
||
|
|
<p>Here's an example of output that follows these rules:
|
||
|
|
|
||
|
|
<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>
|
||
|
|
<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>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="maintain.html#Copyright-Notices">Copyright Notices (Information for GNU Maintainers)</a>.)
|
||
|
|
|
||
|
|
<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 <span class="samp">(C)</span> should be replaced with the
|
||
|
|
copyright symbol, as follows:
|
||
|
|
|
||
|
|
<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>Finally, here is the table of our suggested license abbreviations.
|
||
|
|
Any abbreviation can be followed by <span class="samp">v</span><var>version</var><span class="samp">[+]</span>, meaning
|
||
|
|
that particular version, or later versions with the <span class="samp">+</span>, as shown
|
||
|
|
above.
|
||
|
|
|
||
|
|
<p>In the case of exceptions for extra permissions with the GPL, we use
|
||
|
|
<span class="samp">/</span> for a separator; the version number can follow the license
|
||
|
|
abbreviation as usual, as in the examples below.
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<dt>GPL<dd>GNU General Public License, <a href="http://www.gnu.org/licenses/gpl.html">http://www.gnu.org/licenses/gpl.html</a>.
|
||
|
|
|
||
|
|
<br><dt>LGPL<dd>GNU Lesser General Public License, <a href="http://www.gnu.org/licenses/lgpl.html">http://www.gnu.org/licenses/lgpl.html</a>.
|
||
|
|
|
||
|
|
<br><dt>GPL/Guile<dd>GNU GPL with the exception for Guile; for example, GPLv3+/Guile means
|
||
|
|
the GNU GPL version 3 or later, with the extra exception for Guile.
|
||
|
|
|
||
|
|
<p>GNU GPL with the exception for Ada.
|
||
|
|
|
||
|
|
<br><dt>Apache<dd>The Apache Software Foundation license,
|
||
|
|
<a href="http://www.apache.org/licenses">http://www.apache.org/licenses</a>.
|
||
|
|
|
||
|
|
<br><dt>Artistic<dd>The Artistic license used for Perl, <a href="http://www.perlfoundation.org/legal">http://www.perlfoundation.org/legal</a>.
|
||
|
|
|
||
|
|
<br><dt>Expat<dd>The Expat license, <a href="http://www.jclark.com/xml/copying.txt">http://www.jclark.com/xml/copying.txt</a>.
|
||
|
|
|
||
|
|
<br><dt>MPL<dd>The Mozilla Public License, <a href="http://www.mozilla.org/MPL/">http://www.mozilla.org/MPL/</a>.
|
||
|
|
|
||
|
|
<br><dt>OBSD<dd>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>.
|
||
|
|
|
||
|
|
<br><dt>PHP<dd>The license used for PHP, <a href="http://www.php.net/license/">http://www.php.net/license/</a>.
|
||
|
|
|
||
|
|
<br><dt>public domain<dd>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>.
|
||
|
|
|
||
|
|
<br><dt>Python<dd>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>.
|
||
|
|
|
||
|
|
<br><dt>RBSD<dd>The revised (3-clause) BSD, compatible with the GNU GPL,
|
||
|
|
<a href="http://www.xfree86.org/3.3.6/COPYRIGHT2.html#5">http://www.xfree86.org/3.3.6/COPYRIGHT2.html#5</a>.
|
||
|
|
|
||
|
|
<br><dt>X11<dd>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>.
|
||
|
|
|
||
|
|
<br><dt>Zlib<dd>The license for Zlib, <a href="http://www.gzip.org/zlib/zlib_license.html">http://www.gzip.org/zlib/zlib_license.html</a>.
|
||
|
|
|
||
|
|
</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>.
|
||
|
|
|
||
|
|
<div class="node">
|
||
|
|
<p><hr>
|
||
|
|
<a name="_002d_002dhelp"></a>Previous: <a rel="previous" accesskey="p" href="#_002d_002dversion">--version</a>,
|
||
|
|
Up: <a rel="up" accesskey="u" href="#Command_002dLine-Interfaces">Command-Line Interfaces</a>
|
||
|
|
<br>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<h4 class="subsection">4.7.2 <span class="option">--help</span></h4>
|
||
|
|
|
||
|
|
<p><a name="index-_0040samp_007b_002d_002dhelp_007d-output-49"></a>
|
||
|
|
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-50"></a><a name="index-bug-reports-51"></a>Near the end of the <span class="samp">--help</span> option's output there should be a line
|
||
|
|
that says where to mail bug reports. It should have this format:
|
||
|
|
|
||
|
|
<pre class="example"> Report bugs to <var>mailing-address</var>.
|
||
|
|
</pre>
|
||
|
|
<div class="node">
|
||
|
|
<p><hr>
|
||
|
|
<a name="Option-Table"></a>Next: <a rel="next" accesskey="n" href="#Memory-Usage">Memory Usage</a>,
|
||
|
|
Previous: <a rel="previous" accesskey="p" href="#Command_002dLine-Interfaces">Command-Line Interfaces</a>,
|
||
|
|
Up: <a rel="up" accesskey="u" href="#Program-Behavior">Program Behavior</a>
|
||
|
|
<br>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<h3 class="section">4.8 Table of Long Options</h3>
|
||
|
|
|
||
|
|
<p><a name="index-long-option-names-52"></a><a name="index-table-of-long-options-53"></a>
|
||
|
|
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.
|
||
|
|
|
||
|
|
<!-- Please leave newlines between items in this table; it's much easier -->
|
||
|
|
<!-- to update when it isn't completely squashed together and unreadable. -->
|
||
|
|
<!-- When there is more than one short option for a long option name, put -->
|
||
|
|
<!-- a semicolon between the lists of the programs that use them, not a -->
|
||
|
|
<!-- period. -friedman -->
|
||
|
|
<dl>
|
||
|
|
<dt><span class="samp">after-date</span><dd><span class="samp">-N</span> in <code>tar</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">all</span><dd><span class="samp">-a</span> in <code>du</code>, <code>ls</code>, <code>nm</code>, <code>stty</code>, <code>uname</code>,
|
||
|
|
and <code>unexpand</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">all-text</span><dd><span class="samp">-a</span> in <code>diff</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">almost-all</span><dd><span class="samp">-A</span> in <code>ls</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">append</span><dd><span class="samp">-a</span> in <code>etags</code>, <code>tee</code>, <code>time</code>;
|
||
|
|
<span class="samp">-r</span> in <code>tar</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">archive</span><dd><span class="samp">-a</span> in <code>cp</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">archive-name</span><dd><span class="samp">-n</span> in <code>shar</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">arglength</span><dd><span class="samp">-l</span> in <code>m4</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">ascii</span><dd><span class="samp">-a</span> in <code>diff</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">assign</span><dd><span class="samp">-v</span> in <code>gawk</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">assume-new</span><dd><span class="samp">-W</span> in Make.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">assume-old</span><dd><span class="samp">-o</span> in Make.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">auto-check</span><dd><span class="samp">-a</span> in <code>recode</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">auto-pager</span><dd><span class="samp">-a</span> in <code>wdiff</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">auto-reference</span><dd><span class="samp">-A</span> in <code>ptx</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">avoid-wraps</span><dd><span class="samp">-n</span> in <code>wdiff</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">background</span><dd>For server programs, run in the background.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">backward-search</span><dd><span class="samp">-B</span> in <code>ctags</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">basename</span><dd><span class="samp">-f</span> in <code>shar</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">batch</span><dd>Used in GDB.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">baud</span><dd>Used in GDB.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">before</span><dd><span class="samp">-b</span> in <code>tac</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">binary</span><dd><span class="samp">-b</span> in <code>cpio</code> and <code>diff</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">bits-per-code</span><dd><span class="samp">-b</span> in <code>shar</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">block-size</span><dd>Used in <code>cpio</code> and <code>tar</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">blocks</span><dd><span class="samp">-b</span> in <code>head</code> and <code>tail</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">break-file</span><dd><span class="samp">-b</span> in <code>ptx</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">brief</span><dd>Used in various programs to make output shorter.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">bytes</span><dd><span class="samp">-c</span> in <code>head</code>, <code>split</code>, and <code>tail</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">c</span><tt>++</tt><dd><span class="samp">-C</span> in <code>etags</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">catenate</span><dd><span class="samp">-A</span> in <code>tar</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">cd</span><dd>Used in various programs to specify the directory to use.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">changes</span><dd><span class="samp">-c</span> in <code>chgrp</code> and <code>chown</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">classify</span><dd><span class="samp">-F</span> in <code>ls</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">colons</span><dd><span class="samp">-c</span> in <code>recode</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">command</span><dd><span class="samp">-c</span> in <code>su</code>;
|
||
|
|
<span class="samp">-x</span> in GDB.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">compare</span><dd><span class="samp">-d</span> in <code>tar</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">compat</span><dd>Used in <code>gawk</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">compress</span><dd><span class="samp">-Z</span> in <code>tar</code> and <code>shar</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">concatenate</span><dd><span class="samp">-A</span> in <code>tar</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">confirmation</span><dd><span class="samp">-w</span> in <code>tar</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">context</span><dd>Used in <code>diff</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">copyleft</span><dd><span class="samp">-W copyleft</span> in <code>gawk</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">copyright</span><dd><span class="samp">-C</span> in <code>ptx</code>, <code>recode</code>, and <code>wdiff</code>;
|
||
|
|
<span class="samp">-W copyright</span> in <code>gawk</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">core</span><dd>Used in GDB.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">count</span><dd><span class="samp">-q</span> in <code>who</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">count-links</span><dd><span class="samp">-l</span> in <code>du</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">create</span><dd>Used in <code>tar</code> and <code>cpio</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">cut-mark</span><dd><span class="samp">-c</span> in <code>shar</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">cxref</span><dd><span class="samp">-x</span> in <code>ctags</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">date</span><dd><span class="samp">-d</span> in <code>touch</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">debug</span><dd><span class="samp">-d</span> in Make and <code>m4</code>;
|
||
|
|
<span class="samp">-t</span> in Bison.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">define</span><dd><span class="samp">-D</span> in <code>m4</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">defines</span><dd><span class="samp">-d</span> in Bison and <code>ctags</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">delete</span><dd><span class="samp">-D</span> in <code>tar</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">dereference</span><dd><span class="samp">-L</span> in <code>chgrp</code>, <code>chown</code>, <code>cpio</code>, <code>du</code>,
|
||
|
|
<code>ls</code>, and <code>tar</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">dereference-args</span><dd><span class="samp">-D</span> in <code>du</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">device</span><dd>Specify an I/O device (special file name).
|
||
|
|
|
||
|
|
<br><dt><span class="samp">diacritics</span><dd><span class="samp">-d</span> in <code>recode</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">dictionary-order</span><dd><span class="samp">-d</span> in <code>look</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">diff</span><dd><span class="samp">-d</span> in <code>tar</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">digits</span><dd><span class="samp">-n</span> in <code>csplit</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">directory</span><dd>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.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">discard-all</span><dd><span class="samp">-x</span> in <code>strip</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">discard-locals</span><dd><span class="samp">-X</span> in <code>strip</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">dry-run</span><dd><span class="samp">-n</span> in Make.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">ed</span><dd><span class="samp">-e</span> in <code>diff</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">elide-empty-files</span><dd><span class="samp">-z</span> in <code>csplit</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">end-delete</span><dd><span class="samp">-x</span> in <code>wdiff</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">end-insert</span><dd><span class="samp">-z</span> in <code>wdiff</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">entire-new-file</span><dd><span class="samp">-N</span> in <code>diff</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">environment-overrides</span><dd><span class="samp">-e</span> in Make.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">eof</span><dd><span class="samp">-e</span> in <code>xargs</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">epoch</span><dd>Used in GDB.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">error-limit</span><dd>Used in <code>makeinfo</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">error-output</span><dd><span class="samp">-o</span> in <code>m4</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">escape</span><dd><span class="samp">-b</span> in <code>ls</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">exclude-from</span><dd><span class="samp">-X</span> in <code>tar</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">exec</span><dd>Used in GDB.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">exit</span><dd><span class="samp">-x</span> in <code>xargs</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">exit-0</span><dd><span class="samp">-e</span> in <code>unshar</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">expand-tabs</span><dd><span class="samp">-t</span> in <code>diff</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">expression</span><dd><span class="samp">-e</span> in <code>sed</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">extern-only</span><dd><span class="samp">-g</span> in <code>nm</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">extract</span><dd><span class="samp">-i</span> in <code>cpio</code>;
|
||
|
|
<span class="samp">-x</span> in <code>tar</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">faces</span><dd><span class="samp">-f</span> in <code>finger</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">fast</span><dd><span class="samp">-f</span> in <code>su</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">fatal-warnings</span><dd><span class="samp">-E</span> in <code>m4</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">file</span><dd><span class="samp">-f</span> in <code>info</code>, <code>gawk</code>, Make, <code>mt</code>, and <code>tar</code>;
|
||
|
|
<span class="samp">-n</span> in <code>sed</code>;
|
||
|
|
<span class="samp">-r</span> in <code>touch</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">field-separator</span><dd><span class="samp">-F</span> in <code>gawk</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">file-prefix</span><dd><span class="samp">-b</span> in Bison.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">file-type</span><dd><span class="samp">-F</span> in <code>ls</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">files-from</span><dd><span class="samp">-T</span> in <code>tar</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">fill-column</span><dd>Used in <code>makeinfo</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">flag-truncation</span><dd><span class="samp">-F</span> in <code>ptx</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">fixed-output-files</span><dd><span class="samp">-y</span> in Bison.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">follow</span><dd><span class="samp">-f</span> in <code>tail</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">footnote-style</span><dd>Used in <code>makeinfo</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">force</span><dd><span class="samp">-f</span> in <code>cp</code>, <code>ln</code>, <code>mv</code>, and <code>rm</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">force-prefix</span><dd><span class="samp">-F</span> in <code>shar</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">foreground</span><dd>For server programs, run in the foreground;
|
||
|
|
in other words, don't do anything special to run the server
|
||
|
|
in the background.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">format</span><dd>Used in <code>ls</code>, <code>time</code>, and <code>ptx</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">freeze-state</span><dd><span class="samp">-F</span> in <code>m4</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">fullname</span><dd>Used in GDB.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">gap-size</span><dd><span class="samp">-g</span> in <code>ptx</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">get</span><dd><span class="samp">-x</span> in <code>tar</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">graphic</span><dd><span class="samp">-i</span> in <code>ul</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">graphics</span><dd><span class="samp">-g</span> in <code>recode</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">group</span><dd><span class="samp">-g</span> in <code>install</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">gzip</span><dd><span class="samp">-z</span> in <code>tar</code> and <code>shar</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">hashsize</span><dd><span class="samp">-H</span> in <code>m4</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">header</span><dd><span class="samp">-h</span> in <code>objdump</code> and <code>recode</code>
|
||
|
|
|
||
|
|
<br><dt><span class="samp">heading</span><dd><span class="samp">-H</span> in <code>who</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">help</span><dd>Used to ask for brief usage information.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">here-delimiter</span><dd><span class="samp">-d</span> in <code>shar</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">hide-control-chars</span><dd><span class="samp">-q</span> in <code>ls</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">html</span><dd>In <code>makeinfo</code>, output HTML.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">idle</span><dd><span class="samp">-u</span> in <code>who</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">ifdef</span><dd><span class="samp">-D</span> in <code>diff</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">ignore</span><dd><span class="samp">-I</span> in <code>ls</code>;
|
||
|
|
<span class="samp">-x</span> in <code>recode</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">ignore-all-space</span><dd><span class="samp">-w</span> in <code>diff</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">ignore-backups</span><dd><span class="samp">-B</span> in <code>ls</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">ignore-blank-lines</span><dd><span class="samp">-B</span> in <code>diff</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">ignore-case</span><dd><span class="samp">-f</span> in <code>look</code> and <code>ptx</code>;
|
||
|
|
<span class="samp">-i</span> in <code>diff</code> and <code>wdiff</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">ignore-errors</span><dd><span class="samp">-i</span> in Make.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">ignore-file</span><dd><span class="samp">-i</span> in <code>ptx</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">ignore-indentation</span><dd><span class="samp">-I</span> in <code>etags</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">ignore-init-file</span><dd><span class="samp">-f</span> in Oleo.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">ignore-interrupts</span><dd><span class="samp">-i</span> in <code>tee</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">ignore-matching-lines</span><dd><span class="samp">-I</span> in <code>diff</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">ignore-space-change</span><dd><span class="samp">-b</span> in <code>diff</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">ignore-zeros</span><dd><span class="samp">-i</span> in <code>tar</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">include</span><dd><span class="samp">-i</span> in <code>etags</code>;
|
||
|
|
<span class="samp">-I</span> in <code>m4</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">include-dir</span><dd><span class="samp">-I</span> in Make.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">incremental</span><dd><span class="samp">-G</span> in <code>tar</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">info</span><dd><span class="samp">-i</span>, <span class="samp">-l</span>, and <span class="samp">-m</span> in Finger.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">init-file</span><dd>In some programs, specify the name of the file to read as the user's
|
||
|
|
init file.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">initial</span><dd><span class="samp">-i</span> in <code>expand</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">initial-tab</span><dd><span class="samp">-T</span> in <code>diff</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">inode</span><dd><span class="samp">-i</span> in <code>ls</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">interactive</span><dd><span class="samp">-i</span> in <code>cp</code>, <code>ln</code>, <code>mv</code>, <code>rm</code>;
|
||
|
|
<span class="samp">-e</span> in <code>m4</code>;
|
||
|
|
<span class="samp">-p</span> in <code>xargs</code>;
|
||
|
|
<span class="samp">-w</span> in <code>tar</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">intermix-type</span><dd><span class="samp">-p</span> in <code>shar</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">iso-8601</span><dd>Used in <code>date</code>
|
||
|
|
|
||
|
|
<br><dt><span class="samp">jobs</span><dd><span class="samp">-j</span> in Make.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">just-print</span><dd><span class="samp">-n</span> in Make.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">keep-going</span><dd><span class="samp">-k</span> in Make.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">keep-files</span><dd><span class="samp">-k</span> in <code>csplit</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">kilobytes</span><dd><span class="samp">-k</span> in <code>du</code> and <code>ls</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">language</span><dd><span class="samp">-l</span> in <code>etags</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">less-mode</span><dd><span class="samp">-l</span> in <code>wdiff</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">level-for-gzip</span><dd><span class="samp">-g</span> in <code>shar</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">line-bytes</span><dd><span class="samp">-C</span> in <code>split</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">lines</span><dd>Used in <code>split</code>, <code>head</code>, and <code>tail</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">link</span><dd><span class="samp">-l</span> in <code>cpio</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">lint</span><dt><span class="samp">lint-old</span><dd>Used in <code>gawk</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">list</span><dd><span class="samp">-t</span> in <code>cpio</code>;
|
||
|
|
<span class="samp">-l</span> in <code>recode</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">list</span><dd><span class="samp">-t</span> in <code>tar</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">literal</span><dd><span class="samp">-N</span> in <code>ls</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">load-average</span><dd><span class="samp">-l</span> in Make.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">login</span><dd>Used in <code>su</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">machine</span><dd>Used in <code>uname</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">macro-name</span><dd><span class="samp">-M</span> in <code>ptx</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">mail</span><dd><span class="samp">-m</span> in <code>hello</code> and <code>uname</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">make-directories</span><dd><span class="samp">-d</span> in <code>cpio</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">makefile</span><dd><span class="samp">-f</span> in Make.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">mapped</span><dd>Used in GDB.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">max-args</span><dd><span class="samp">-n</span> in <code>xargs</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">max-chars</span><dd><span class="samp">-n</span> in <code>xargs</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">max-lines</span><dd><span class="samp">-l</span> in <code>xargs</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">max-load</span><dd><span class="samp">-l</span> in Make.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">max-procs</span><dd><span class="samp">-P</span> in <code>xargs</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">mesg</span><dd><span class="samp">-T</span> in <code>who</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">message</span><dd><span class="samp">-T</span> in <code>who</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">minimal</span><dd><span class="samp">-d</span> in <code>diff</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">mixed-uuencode</span><dd><span class="samp">-M</span> in <code>shar</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">mode</span><dd><span class="samp">-m</span> in <code>install</code>, <code>mkdir</code>, and <code>mkfifo</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">modification-time</span><dd><span class="samp">-m</span> in <code>tar</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">multi-volume</span><dd><span class="samp">-M</span> in <code>tar</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">name-prefix</span><dd><span class="samp">-a</span> in Bison.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">nesting-limit</span><dd><span class="samp">-L</span> in <code>m4</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">net-headers</span><dd><span class="samp">-a</span> in <code>shar</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">new-file</span><dd><span class="samp">-W</span> in Make.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">no-builtin-rules</span><dd><span class="samp">-r</span> in Make.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">no-character-count</span><dd><span class="samp">-w</span> in <code>shar</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">no-check-existing</span><dd><span class="samp">-x</span> in <code>shar</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">no-common</span><dd><span class="samp">-3</span> in <code>wdiff</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">no-create</span><dd><span class="samp">-c</span> in <code>touch</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">no-defines</span><dd><span class="samp">-D</span> in <code>etags</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">no-deleted</span><dd><span class="samp">-1</span> in <code>wdiff</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">no-dereference</span><dd><span class="samp">-d</span> in <code>cp</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">no-inserted</span><dd><span class="samp">-2</span> in <code>wdiff</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">no-keep-going</span><dd><span class="samp">-S</span> in Make.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">no-lines</span><dd><span class="samp">-l</span> in Bison.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">no-piping</span><dd><span class="samp">-P</span> in <code>shar</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">no-prof</span><dd><span class="samp">-e</span> in <code>gprof</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">no-regex</span><dd><span class="samp">-R</span> in <code>etags</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">no-sort</span><dd><span class="samp">-p</span> in <code>nm</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">no-splash</span><dd>Don't print a startup splash screen.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">no-split</span><dd>Used in <code>makeinfo</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">no-static</span><dd><span class="samp">-a</span> in <code>gprof</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">no-time</span><dd><span class="samp">-E</span> in <code>gprof</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">no-timestamp</span><dd><span class="samp">-m</span> in <code>shar</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">no-validate</span><dd>Used in <code>makeinfo</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">no-wait</span><dd>Used in <code>emacsclient</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">no-warn</span><dd>Used in various programs to inhibit warnings.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">node</span><dd><span class="samp">-n</span> in <code>info</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">nodename</span><dd><span class="samp">-n</span> in <code>uname</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">nonmatching</span><dd><span class="samp">-f</span> in <code>cpio</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">nstuff</span><dd><span class="samp">-n</span> in <code>objdump</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">null</span><dd><span class="samp">-0</span> in <code>xargs</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">number</span><dd><span class="samp">-n</span> in <code>cat</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">number-nonblank</span><dd><span class="samp">-b</span> in <code>cat</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">numeric-sort</span><dd><span class="samp">-n</span> in <code>nm</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">numeric-uid-gid</span><dd><span class="samp">-n</span> in <code>cpio</code> and <code>ls</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">nx</span><dd>Used in GDB.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">old-archive</span><dd><span class="samp">-o</span> in <code>tar</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">old-file</span><dd><span class="samp">-o</span> in Make.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">one-file-system</span><dd><span class="samp">-l</span> in <code>tar</code>, <code>cp</code>, and <code>du</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">only-file</span><dd><span class="samp">-o</span> in <code>ptx</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">only-prof</span><dd><span class="samp">-f</span> in <code>gprof</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">only-time</span><dd><span class="samp">-F</span> in <code>gprof</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">options</span><dd><span class="samp">-o</span> in <code>getopt</code>, <code>fdlist</code>, <code>fdmount</code>,
|
||
|
|
<code>fdmountd</code>, and <code>fdumount</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">output</span><dd>In various programs, specify the output file name.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">output-prefix</span><dd><span class="samp">-o</span> in <code>shar</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">override</span><dd><span class="samp">-o</span> in <code>rm</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">overwrite</span><dd><span class="samp">-c</span> in <code>unshar</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">owner</span><dd><span class="samp">-o</span> in <code>install</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">paginate</span><dd><span class="samp">-l</span> in <code>diff</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">paragraph-indent</span><dd>Used in <code>makeinfo</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">parents</span><dd><span class="samp">-p</span> in <code>mkdir</code> and <code>rmdir</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">pass-all</span><dd><span class="samp">-p</span> in <code>ul</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">pass-through</span><dd><span class="samp">-p</span> in <code>cpio</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">port</span><dd><span class="samp">-P</span> in <code>finger</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">portability</span><dd><span class="samp">-c</span> in <code>cpio</code> and <code>tar</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">posix</span><dd>Used in <code>gawk</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">prefix-builtins</span><dd><span class="samp">-P</span> in <code>m4</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">prefix</span><dd><span class="samp">-f</span> in <code>csplit</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">preserve</span><dd>Used in <code>tar</code> and <code>cp</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">preserve-environment</span><dd><span class="samp">-p</span> in <code>su</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">preserve-modification-time</span><dd><span class="samp">-m</span> in <code>cpio</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">preserve-order</span><dd><span class="samp">-s</span> in <code>tar</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">preserve-permissions</span><dd><span class="samp">-p</span> in <code>tar</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">print</span><dd><span class="samp">-l</span> in <code>diff</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">print-chars</span><dd><span class="samp">-L</span> in <code>cmp</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">print-data-base</span><dd><span class="samp">-p</span> in Make.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">print-directory</span><dd><span class="samp">-w</span> in Make.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">print-file-name</span><dd><span class="samp">-o</span> in <code>nm</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">print-symdefs</span><dd><span class="samp">-s</span> in <code>nm</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">printer</span><dd><span class="samp">-p</span> in <code>wdiff</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">prompt</span><dd><span class="samp">-p</span> in <code>ed</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">proxy</span><dd>Specify an HTTP proxy.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">query-user</span><dd><span class="samp">-X</span> in <code>shar</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">question</span><dd><span class="samp">-q</span> in Make.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">quiet</span><dd>Used in many programs to inhibit the usual output. Every
|
||
|
|
program accepting <span class="samp">--quiet</span> should accept <span class="samp">--silent</span> as a
|
||
|
|
synonym.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">quiet-unshar</span><dd><span class="samp">-Q</span> in <code>shar</code>
|
||
|
|
|
||
|
|
<br><dt><span class="samp">quote-name</span><dd><span class="samp">-Q</span> in <code>ls</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">rcs</span><dd><span class="samp">-n</span> in <code>diff</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">re-interval</span><dd>Used in <code>gawk</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">read-full-blocks</span><dd><span class="samp">-B</span> in <code>tar</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">readnow</span><dd>Used in GDB.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">recon</span><dd><span class="samp">-n</span> in Make.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">record-number</span><dd><span class="samp">-R</span> in <code>tar</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">recursive</span><dd>Used in <code>chgrp</code>, <code>chown</code>, <code>cp</code>, <code>ls</code>, <code>diff</code>,
|
||
|
|
and <code>rm</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">reference-limit</span><dd>Used in <code>makeinfo</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">references</span><dd><span class="samp">-r</span> in <code>ptx</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">regex</span><dd><span class="samp">-r</span> in <code>tac</code> and <code>etags</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">release</span><dd><span class="samp">-r</span> in <code>uname</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">reload-state</span><dd><span class="samp">-R</span> in <code>m4</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">relocation</span><dd><span class="samp">-r</span> in <code>objdump</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">rename</span><dd><span class="samp">-r</span> in <code>cpio</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">replace</span><dd><span class="samp">-i</span> in <code>xargs</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">report-identical-files</span><dd><span class="samp">-s</span> in <code>diff</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">reset-access-time</span><dd><span class="samp">-a</span> in <code>cpio</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">reverse</span><dd><span class="samp">-r</span> in <code>ls</code> and <code>nm</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">reversed-ed</span><dd><span class="samp">-f</span> in <code>diff</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">right-side-defs</span><dd><span class="samp">-R</span> in <code>ptx</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">same-order</span><dd><span class="samp">-s</span> in <code>tar</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">same-permissions</span><dd><span class="samp">-p</span> in <code>tar</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">save</span><dd><span class="samp">-g</span> in <code>stty</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">se</span><dd>Used in GDB.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">sentence-regexp</span><dd><span class="samp">-S</span> in <code>ptx</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">separate-dirs</span><dd><span class="samp">-S</span> in <code>du</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">separator</span><dd><span class="samp">-s</span> in <code>tac</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">sequence</span><dd>Used by <code>recode</code> to chose files or pipes for sequencing passes.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">shell</span><dd><span class="samp">-s</span> in <code>su</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">show-all</span><dd><span class="samp">-A</span> in <code>cat</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">show-c-function</span><dd><span class="samp">-p</span> in <code>diff</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">show-ends</span><dd><span class="samp">-E</span> in <code>cat</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">show-function-line</span><dd><span class="samp">-F</span> in <code>diff</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">show-tabs</span><dd><span class="samp">-T</span> in <code>cat</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">silent</span><dd>Used in many programs to inhibit the usual output.
|
||
|
|
Every program accepting
|
||
|
|
<span class="samp">--silent</span> should accept <span class="samp">--quiet</span> as a synonym.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">size</span><dd><span class="samp">-s</span> in <code>ls</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">socket</span><dd>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.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">sort</span><dd>Used in <code>ls</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">source</span><dd><span class="samp">-W source</span> in <code>gawk</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">sparse</span><dd><span class="samp">-S</span> in <code>tar</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">speed-large-files</span><dd><span class="samp">-H</span> in <code>diff</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">split-at</span><dd><span class="samp">-E</span> in <code>unshar</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">split-size-limit</span><dd><span class="samp">-L</span> in <code>shar</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">squeeze-blank</span><dd><span class="samp">-s</span> in <code>cat</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">start-delete</span><dd><span class="samp">-w</span> in <code>wdiff</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">start-insert</span><dd><span class="samp">-y</span> in <code>wdiff</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">starting-file</span><dd>Used in <code>tar</code> and <code>diff</code> to specify which file within
|
||
|
|
a directory to start processing with.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">statistics</span><dd><span class="samp">-s</span> in <code>wdiff</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">stdin-file-list</span><dd><span class="samp">-S</span> in <code>shar</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">stop</span><dd><span class="samp">-S</span> in Make.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">strict</span><dd><span class="samp">-s</span> in <code>recode</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">strip</span><dd><span class="samp">-s</span> in <code>install</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">strip-all</span><dd><span class="samp">-s</span> in <code>strip</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">strip-debug</span><dd><span class="samp">-S</span> in <code>strip</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">submitter</span><dd><span class="samp">-s</span> in <code>shar</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">suffix</span><dd><span class="samp">-S</span> in <code>cp</code>, <code>ln</code>, <code>mv</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">suffix-format</span><dd><span class="samp">-b</span> in <code>csplit</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">sum</span><dd><span class="samp">-s</span> in <code>gprof</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">summarize</span><dd><span class="samp">-s</span> in <code>du</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">symbolic</span><dd><span class="samp">-s</span> in <code>ln</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">symbols</span><dd>Used in GDB and <code>objdump</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">synclines</span><dd><span class="samp">-s</span> in <code>m4</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">sysname</span><dd><span class="samp">-s</span> in <code>uname</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">tabs</span><dd><span class="samp">-t</span> in <code>expand</code> and <code>unexpand</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">tabsize</span><dd><span class="samp">-T</span> in <code>ls</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">terminal</span><dd><span class="samp">-T</span> in <code>tput</code> and <code>ul</code>.
|
||
|
|
<span class="samp">-t</span> in <code>wdiff</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">text</span><dd><span class="samp">-a</span> in <code>diff</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">text-files</span><dd><span class="samp">-T</span> in <code>shar</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">time</span><dd>Used in <code>ls</code> and <code>touch</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">timeout</span><dd>Specify how long to wait before giving up on some operation.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">to-stdout</span><dd><span class="samp">-O</span> in <code>tar</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">total</span><dd><span class="samp">-c</span> in <code>du</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">touch</span><dd><span class="samp">-t</span> in Make, <code>ranlib</code>, and <code>recode</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">trace</span><dd><span class="samp">-t</span> in <code>m4</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">traditional</span><dd><span class="samp">-t</span> in <code>hello</code>;
|
||
|
|
<span class="samp">-W traditional</span> in <code>gawk</code>;
|
||
|
|
<span class="samp">-G</span> in <code>ed</code>, <code>m4</code>, and <code>ptx</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">tty</span><dd>Used in GDB.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">typedefs</span><dd><span class="samp">-t</span> in <code>ctags</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">typedefs-and-c++</span><dd><span class="samp">-T</span> in <code>ctags</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">typeset-mode</span><dd><span class="samp">-t</span> in <code>ptx</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">uncompress</span><dd><span class="samp">-z</span> in <code>tar</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">unconditional</span><dd><span class="samp">-u</span> in <code>cpio</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">undefine</span><dd><span class="samp">-U</span> in <code>m4</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">undefined-only</span><dd><span class="samp">-u</span> in <code>nm</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">update</span><dd><span class="samp">-u</span> in <code>cp</code>, <code>ctags</code>, <code>mv</code>, <code>tar</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">usage</span><dd>Used in <code>gawk</code>; same as <span class="samp">--help</span>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">uuencode</span><dd><span class="samp">-B</span> in <code>shar</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">vanilla-operation</span><dd><span class="samp">-V</span> in <code>shar</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">verbose</span><dd>Print more information about progress. Many programs support this.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">verify</span><dd><span class="samp">-W</span> in <code>tar</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">version</span><dd>Print the version number.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">version-control</span><dd><span class="samp">-V</span> in <code>cp</code>, <code>ln</code>, <code>mv</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">vgrind</span><dd><span class="samp">-v</span> in <code>ctags</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">volume</span><dd><span class="samp">-V</span> in <code>tar</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">what-if</span><dd><span class="samp">-W</span> in Make.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">whole-size-limit</span><dd><span class="samp">-l</span> in <code>shar</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">width</span><dd><span class="samp">-w</span> in <code>ls</code> and <code>ptx</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">word-regexp</span><dd><span class="samp">-W</span> in <code>ptx</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">writable</span><dd><span class="samp">-T</span> in <code>who</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">zeros</span><dd><span class="samp">-z</span> in <code>gprof</code>.
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<div class="node">
|
||
|
|
<p><hr>
|
||
|
|
<a name="Memory-Usage"></a>Next: <a rel="next" accesskey="n" href="#File-Usage">File Usage</a>,
|
||
|
|
Previous: <a rel="previous" accesskey="p" href="#Option-Table">Option Table</a>,
|
||
|
|
Up: <a rel="up" accesskey="u" href="#Program-Behavior">Program Behavior</a>
|
||
|
|
<br>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<h3 class="section">4.9 Memory Usage</h3>
|
||
|
|
|
||
|
|
<p><a name="index-memory-usage-54"></a>
|
||
|
|
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>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>If your program creates complicated data structures, just make them in
|
||
|
|
memory and give a fatal error if <code>malloc</code> returns zero.
|
||
|
|
|
||
|
|
<div class="node">
|
||
|
|
<p><hr>
|
||
|
|
<a name="File-Usage"></a>Previous: <a rel="previous" accesskey="p" href="#Memory-Usage">Memory Usage</a>,
|
||
|
|
Up: <a rel="up" accesskey="u" href="#Program-Behavior">Program Behavior</a>
|
||
|
|
<br>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<h3 class="section">4.10 File Usage</h3>
|
||
|
|
|
||
|
|
<p><a name="index-file-usage-55"></a>
|
||
|
|
Programs should be prepared to operate when <span class="file">/usr</span> and <span class="file">/etc</span>
|
||
|
|
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
|
||
|
|
<span class="file">/usr</span> or <span class="file">/etc</span>.
|
||
|
|
|
||
|
|
<p>There are two exceptions. <span class="file">/etc</span> is used to store system
|
||
|
|
configuration information; it is reasonable for a program to modify
|
||
|
|
files in <span class="file">/etc</span> 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.
|
||
|
|
|
||
|
|
<div class="node">
|
||
|
|
<p><hr>
|
||
|
|
<a name="Writing-C"></a>Next: <a rel="next" accesskey="n" href="#Documentation">Documentation</a>,
|
||
|
|
Previous: <a rel="previous" accesskey="p" href="#Program-Behavior">Program Behavior</a>,
|
||
|
|
Up: <a rel="up" accesskey="u" href="#Top">Top</a>
|
||
|
|
<br>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<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.
|
||
|
|
|
||
|
|
<ul class="menu">
|
||
|
|
<li><a accesskey="1" href="#Formatting">Formatting</a>: Formatting your source code.
|
||
|
|
<li><a accesskey="2" href="#Comments">Comments</a>: Commenting your work.
|
||
|
|
<li><a accesskey="3" href="#Syntactic-Conventions">Syntactic Conventions</a>: Clean use of C constructs.
|
||
|
|
<li><a accesskey="4" href="#Names">Names</a>: Naming variables, functions, and files.
|
||
|
|
<li><a accesskey="5" href="#System-Portability">System Portability</a>: Portability among different operating systems.
|
||
|
|
<li><a accesskey="6" href="#CPU-Portability">CPU Portability</a>: Supporting the range of CPU types.
|
||
|
|
<li><a accesskey="7" href="#System-Functions">System Functions</a>: Portability and ``standard'' library functions.
|
||
|
|
<li><a accesskey="8" href="#Internationalization">Internationalization</a>: Techniques for internationalization.
|
||
|
|
<li><a accesskey="9" href="#Character-Set">Character Set</a>: Use ASCII by default.
|
||
|
|
<li><a href="#Quote-Characters">Quote Characters</a>: Use `...' in the C locale.
|
||
|
|
<li><a href="#Mmap">Mmap</a>: How you can safely use <code>mmap</code>.
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<div class="node">
|
||
|
|
<p><hr>
|
||
|
|
<a name="Formatting"></a>Next: <a rel="next" accesskey="n" href="#Comments">Comments</a>,
|
||
|
|
Up: <a rel="up" accesskey="u" href="#Writing-C">Writing C</a>
|
||
|
|
<br>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<h3 class="section">5.1 Formatting Your Source Code</h3>
|
||
|
|
|
||
|
|
<p><a name="index-formatting-source-code-56"></a>
|
||
|
|
<a name="index-open-brace-57"></a><a name="index-braces_002c-in-C-source-58"></a>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>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>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:
|
||
|
|
|
||
|
|
<pre class="example"> static char *
|
||
|
|
concat (char *s1, char *s2)
|
||
|
|
{
|
||
|
|
...
|
||
|
|
}
|
||
|
|
</pre>
|
||
|
|
<p class="noindent">or, if you want to use traditional C syntax, format the definition like
|
||
|
|
this:
|
||
|
|
|
||
|
|
<pre class="example"> static char *
|
||
|
|
concat (s1, s2) /* Name starts in column one here */
|
||
|
|
char *s1, *s2;
|
||
|
|
{ /* Open brace in column one here */
|
||
|
|
...
|
||
|
|
}
|
||
|
|
</pre>
|
||
|
|
<p>In Standard C, if the arguments don't fit nicely on one line,
|
||
|
|
split it like this:
|
||
|
|
|
||
|
|
<pre class="example"> int
|
||
|
|
lots_of_args (int an_integer, long a_long, short a_short,
|
||
|
|
double a_double, float a_float)
|
||
|
|
...
|
||
|
|
</pre>
|
||
|
|
<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
|
||
|
|
|
||
|
|
<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>
|
||
|
|
<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>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>For the body of the function, our recommended style looks like this:
|
||
|
|
|
||
|
|
<pre class="example"> if (x < foo (y, z))
|
||
|
|
haha = bar[4] + 5;
|
||
|
|
else
|
||
|
|
{
|
||
|
|
while (z)
|
||
|
|
{
|
||
|
|
haha += foo (z, z);
|
||
|
|
z--;
|
||
|
|
}
|
||
|
|
return ++x + bar ();
|
||
|
|
}
|
||
|
|
</pre>
|
||
|
|
<p><a name="index-spaces-before-open_002dparen-59"></a>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>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-60"></a>
|
||
|
|
<pre class="example"> if (foo_this_is_long && bar > win (x, y, z)
|
||
|
|
&& remaining_condition)
|
||
|
|
</pre>
|
||
|
|
<p>Try to avoid having two operators of different precedence at the same
|
||
|
|
level of indentation. For example, don't write this:
|
||
|
|
|
||
|
|
<pre class="example"> mode = (inmode[j] == VOIDmode
|
||
|
|
|| GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j])
|
||
|
|
? outmode[j] : inmode[j]);
|
||
|
|
</pre>
|
||
|
|
<p>Instead, use extra parentheses so that the indentation shows the nesting:
|
||
|
|
|
||
|
|
<pre class="example"> mode = ((inmode[j] == VOIDmode
|
||
|
|
|| (GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j])))
|
||
|
|
? outmode[j] : inmode[j]);
|
||
|
|
</pre>
|
||
|
|
<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,
|
||
|
|
|
||
|
|
<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>
|
||
|
|
<p class="noindent">but Emacs would alter it. Adding a set of parentheses produces
|
||
|
|
something that looks equally nice, and which Emacs will preserve:
|
||
|
|
|
||
|
|
<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>
|
||
|
|
<p>Format do-while statements like this:
|
||
|
|
|
||
|
|
<pre class="example"> do
|
||
|
|
{
|
||
|
|
a = foo (a);
|
||
|
|
}
|
||
|
|
while (a > 0);
|
||
|
|
</pre>
|
||
|
|
<p><a name="index-formfeed-61"></a><a name="index-control_002dL-62"></a>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.
|
||
|
|
|
||
|
|
<div class="node">
|
||
|
|
<p><hr>
|
||
|
|
<a name="Comments"></a>Next: <a rel="next" accesskey="n" href="#Syntactic-Conventions">Syntactic Conventions</a>,
|
||
|
|
Previous: <a rel="previous" accesskey="p" href="#Formatting">Formatting</a>,
|
||
|
|
Up: <a rel="up" accesskey="u" href="#Writing-C">Writing C</a>
|
||
|
|
<br>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<h3 class="section">5.2 Commenting Your Work</h3>
|
||
|
|
|
||
|
|
<p><a name="index-commenting-63"></a>
|
||
|
|
Every program should start with a comment saying briefly what it is for.
|
||
|
|
Example: <span class="samp">fmt - filter for simple filling of text</span>. This comment
|
||
|
|
should be at the top of the source file containing the <span class="samp">main</span>
|
||
|
|
function of the program.
|
||
|
|
|
||
|
|
<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>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>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>Also explain the significance of the return value, if there is one.
|
||
|
|
|
||
|
|
<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 <small class="dots">...</small>”).
|
||
|
|
|
||
|
|
<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>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>There should be a comment on each static variable as well, like this:
|
||
|
|
|
||
|
|
<pre class="example"> /* Nonzero means truncate lines in the display;
|
||
|
|
zero means continue them. */
|
||
|
|
int truncate_lines;
|
||
|
|
</pre>
|
||
|
|
<p><a name="index-conditionals_002c-comments-for-64"></a><a name="index-_0040code_007b_0023endif_007d_002c-commenting-65"></a>Every <span class="samp">#endif</span> 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>. <span class="samp">#else</span> should have a comment describing the condition
|
||
|
|
<em>and sense</em> of the code that follows. For example:
|
||
|
|
|
||
|
|
<pre class="example"> #ifdef foo
|
||
|
|
...
|
||
|
|
#else /* not foo */
|
||
|
|
...
|
||
|
|
#endif /* not foo */
|
||
|
|
#ifdef foo
|
||
|
|
...
|
||
|
|
#endif /* foo */
|
||
|
|
</pre>
|
||
|
|
<p class="noindent">but, by contrast, write the comments this way for a <span class="samp">#ifndef</span>:
|
||
|
|
|
||
|
|
<pre class="example"> #ifndef foo
|
||
|
|
...
|
||
|
|
#else /* foo */
|
||
|
|
...
|
||
|
|
#endif /* foo */
|
||
|
|
#ifndef foo
|
||
|
|
...
|
||
|
|
#endif /* not foo */
|
||
|
|
</pre>
|
||
|
|
<div class="node">
|
||
|
|
<p><hr>
|
||
|
|
<a name="Syntactic-Conventions"></a>Next: <a rel="next" accesskey="n" href="#Names">Names</a>,
|
||
|
|
Previous: <a rel="previous" accesskey="p" href="#Comments">Comments</a>,
|
||
|
|
Up: <a rel="up" accesskey="u" href="#Writing-C">Writing C</a>
|
||
|
|
<br>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<h3 class="section">5.3 Clean Use of C Constructs</h3>
|
||
|
|
|
||
|
|
<p><a name="index-syntactic-conventions-66"></a>
|
||
|
|
<a name="index-implicit-_0040code_007bint_007d-67"></a><a name="index-function-argument_002c-declaring-68"></a>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-69"></a><a name="index-_0040samp_007b_002dWall_007d-compiler-option-70"></a>Some programmers like to use the GCC <span class="samp">-Wall</span> option, and change the
|
||
|
|
code whenever it issues a warning. If you want to do this, then do.
|
||
|
|
Other programmers prefer not to use <span class="samp">-Wall</span>, 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>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-71"></a>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>Don't use local variables or parameters that shadow global identifiers.
|
||
|
|
|
||
|
|
<p><a name="index-multiple-variables-in-a-line-72"></a>Don't declare multiple variables in one declaration that spans lines.
|
||
|
|
Start a new declaration on each line, instead. For example, instead
|
||
|
|
of this:
|
||
|
|
|
||
|
|
<pre class="example"> int foo,
|
||
|
|
bar;
|
||
|
|
</pre>
|
||
|
|
<p class="noindent">write either this:
|
||
|
|
|
||
|
|
<pre class="example"> int foo, bar;
|
||
|
|
</pre>
|
||
|
|
<p class="noindent">or this:
|
||
|
|
|
||
|
|
<pre class="example"> int foo;
|
||
|
|
int bar;
|
||
|
|
</pre>
|
||
|
|
<p class="noindent">(If they are global variables, each should have a comment preceding it
|
||
|
|
anyway.)
|
||
|
|
|
||
|
|
<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:
|
||
|
|
|
||
|
|
<pre class="example"> if (foo)
|
||
|
|
if (bar)
|
||
|
|
win ();
|
||
|
|
else
|
||
|
|
lose ();
|
||
|
|
</pre>
|
||
|
|
<p class="noindent">always like this:
|
||
|
|
|
||
|
|
<pre class="example"> if (foo)
|
||
|
|
{
|
||
|
|
if (bar)
|
||
|
|
win ();
|
||
|
|
else
|
||
|
|
lose ();
|
||
|
|
}
|
||
|
|
</pre>
|
||
|
|
<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,
|
||
|
|
|
||
|
|
<pre class="example"> if (foo)
|
||
|
|
...
|
||
|
|
else if (bar)
|
||
|
|
...
|
||
|
|
</pre>
|
||
|
|
<p class="noindent">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:
|
||
|
|
|
||
|
|
<pre class="example"> if (foo)
|
||
|
|
...
|
||
|
|
else
|
||
|
|
{
|
||
|
|
if (bar)
|
||
|
|
...
|
||
|
|
}
|
||
|
|
</pre>
|
||
|
|
<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>Try to avoid assignments inside <code>if</code>-conditions (assignments
|
||
|
|
inside <code>while</code>-conditions are ok). For example, don't write
|
||
|
|
this:
|
||
|
|
|
||
|
|
<pre class="example"> if ((foo = (char *) malloc (sizeof *foo)) == 0)
|
||
|
|
fatal ("virtual memory exhausted");
|
||
|
|
</pre>
|
||
|
|
<p class="noindent">instead, write this:
|
||
|
|
|
||
|
|
<pre class="example"> foo = (char *) malloc (sizeof *foo);
|
||
|
|
if (foo == 0)
|
||
|
|
fatal ("virtual memory exhausted");
|
||
|
|
</pre>
|
||
|
|
<p><a name="index-lint-73"></a>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.
|
||
|
|
|
||
|
|
<div class="node">
|
||
|
|
<p><hr>
|
||
|
|
<a name="Names"></a>Next: <a rel="next" accesskey="n" href="#System-Portability">System Portability</a>,
|
||
|
|
Previous: <a rel="previous" accesskey="p" href="#Syntactic-Conventions">Syntactic Conventions</a>,
|
||
|
|
Up: <a rel="up" accesskey="u" href="#Writing-C">Writing C</a>
|
||
|
|
<br>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<h3 class="section">5.4 Naming Variables, Functions, and Files</h3>
|
||
|
|
|
||
|
|
<p><a name="index-names-of-variables_002c-functions_002c-and-files-74"></a>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>Local variable names can be shorter, because they are used only within
|
||
|
|
one context, where (presumably) comments explain their purpose.
|
||
|
|
|
||
|
|
<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>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>For example, you should use names like <code>ignore_space_change_flag</code>;
|
||
|
|
don't use names like <code>iCantReadThis</code>.
|
||
|
|
|
||
|
|
<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,
|
||
|
|
|
||
|
|
<pre class="example"> /* Ignore changes in horizontal whitespace (-b). */
|
||
|
|
int ignore_space_change_flag;
|
||
|
|
</pre>
|
||
|
|
<p>When you want to define names with constant integer values, use
|
||
|
|
<code>enum</code> rather than <span class="samp">#define</span>. GDB knows about enumeration
|
||
|
|
constants.
|
||
|
|
|
||
|
|
<p><a name="index-file_002dname-limitations-75"></a><a name="index-doschk-76"></a>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>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.
|
||
|
|
|
||
|
|
<div class="node">
|
||
|
|
<p><hr>
|
||
|
|
<a name="System-Portability"></a>Next: <a rel="next" accesskey="n" href="#CPU-Portability">CPU Portability</a>,
|
||
|
|
Previous: <a rel="previous" accesskey="p" href="#Names">Names</a>,
|
||
|
|
Up: <a rel="up" accesskey="u" href="#Writing-C">Writing C</a>
|
||
|
|
<br>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<h3 class="section">5.5 Portability between System Types</h3>
|
||
|
|
|
||
|
|
<p><a name="index-portability_002c-between-system-types-77"></a>
|
||
|
|
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>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 <span class="sc">cpu</span>. 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>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-78"></a>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>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_002d_0040sc_007bposix_007d-systems_002c-and-portability-79"></a>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>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 “un”, you can write it in full or abbreviate it to
|
||
|
|
“woe” or “w”. In GNU Emacs, for instance, we use <span class="samp">w32</span> in
|
||
|
|
file names of Windows-specific files, but the macro for Windows
|
||
|
|
conditionals is called <code>WINDOWSNT</code>.
|
||
|
|
|
||
|
|
<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>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.
|
||
|
|
|
||
|
|
<div class="node">
|
||
|
|
<p><hr>
|
||
|
|
<a name="CPU-Portability"></a>Next: <a rel="next" accesskey="n" href="#System-Functions">System Functions</a>,
|
||
|
|
Previous: <a rel="previous" accesskey="p" href="#System-Portability">System Portability</a>,
|
||
|
|
Up: <a rel="up" accesskey="u" href="#Writing-C">Writing C</a>
|
||
|
|
<br>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<h3 class="section">5.6 Portability between <span class="sc">cpu</span>s</h3>
|
||
|
|
|
||
|
|
<p><a name="index-data-types_002c-and-portability-80"></a><a name="index-portability_002c-and-data-types-81"></a>Even GNU systems will differ because of differences among <span class="sc">cpu</span>
|
||
|
|
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>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:
|
||
|
|
|
||
|
|
<pre class="example"> printf ("size = %lu\n", (unsigned long) sizeof array);
|
||
|
|
printf ("diff = %ld\n", (long) (pointer2 - pointer1));
|
||
|
|
</pre>
|
||
|
|
<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>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>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:
|
||
|
|
|
||
|
|
<pre class="example"> int c;
|
||
|
|
...
|
||
|
|
while ((c = getchar ()) != EOF)
|
||
|
|
write (file_descriptor, &c, 1);
|
||
|
|
</pre>
|
||
|
|
<p class="noindent">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.)
|
||
|
|
|
||
|
|
<pre class="example"> int c;
|
||
|
|
while ((c = getchar ()) != EOF)
|
||
|
|
{
|
||
|
|
unsigned char u = c;
|
||
|
|
write (file_descriptor, &u, 1);
|
||
|
|
}
|
||
|
|
</pre>
|
||
|
|
<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>In particular, if functions accept varying argument counts or types
|
||
|
|
they should be declared using prototypes containing <span class="samp">...</span> and
|
||
|
|
defined using <span class="file">stdarg.h</span>. 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:
|
||
|
|
|
||
|
|
<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>
|
||
|
|
<p>A simple way to use the Gnulib error module is to obtain the two
|
||
|
|
source files <span class="file">error.c</span> and <span class="file">error.h</span> from the Gnulib library
|
||
|
|
source code repository at
|
||
|
|
<a href="http://savannah.gnu.org/cgi-bin/viewcvs/gnulib/gnulib/lib/">http://savannah.gnu.org/cgi-bin/viewcvs/gnulib/gnulib/lib/</a>.
|
||
|
|
Here's a sample use:
|
||
|
|
|
||
|
|
<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>
|
||
|
|
<p><a name="index-casting-pointers-to-integers-82"></a>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.
|
||
|
|
|
||
|
|
<div class="node">
|
||
|
|
<p><hr>
|
||
|
|
<a name="System-Functions"></a>Next: <a rel="next" accesskey="n" href="#Internationalization">Internationalization</a>,
|
||
|
|
Previous: <a rel="previous" accesskey="p" href="#CPU-Portability">CPU Portability</a>,
|
||
|
|
Up: <a rel="up" accesskey="u" href="#Writing-C">Writing C</a>
|
||
|
|
<br>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<h3 class="section">5.7 Calling System Functions</h3>
|
||
|
|
|
||
|
|
<p><a name="index-library-functions_002c-and-portability-83"></a><a name="index-portability_002c-and-library-functions-84"></a>
|
||
|
|
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.
|
||
|
|
|
||
|
|
<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>Be aware that <code>vfprintf</code> is not always available.
|
||
|
|
|
||
|
|
<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.
|
||
|
|
|
||
|
|
<p><a name="index-declaration-for-system-functions-85"></a><li>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>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.
|
||
|
|
|
||
|
|
<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>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>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>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><a name="index-string-library-functions-86"></a><li>The string functions require special treatment. Some Unix systems have
|
||
|
|
a header file <span class="file">string.h</span>; others have <span class="file">strings.h</span>. 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>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:
|
||
|
|
|
||
|
|
<pre class="example"> strcpy strncpy strcat strncat
|
||
|
|
strlen strcmp strncmp
|
||
|
|
strchr strrchr
|
||
|
|
</pre>
|
||
|
|
<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>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>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>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:
|
||
|
|
|
||
|
|
<pre class="example"> #ifndef HAVE_STRCHR
|
||
|
|
#define strchr index
|
||
|
|
#endif
|
||
|
|
#ifndef HAVE_STRRCHR
|
||
|
|
#define strrchr rindex
|
||
|
|
#endif
|
||
|
|
|
||
|
|
char *strchr ();
|
||
|
|
char *strrchr ();
|
||
|
|
</pre>
|
||
|
|
</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.
|
||
|
|
|
||
|
|
<div class="node">
|
||
|
|
<p><hr>
|
||
|
|
<a name="Internationalization"></a>Next: <a rel="next" accesskey="n" href="#Character-Set">Character Set</a>,
|
||
|
|
Previous: <a rel="previous" accesskey="p" href="#System-Functions">System Functions</a>,
|
||
|
|
Up: <a rel="up" accesskey="u" href="#Writing-C">Writing C</a>
|
||
|
|
<br>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<h3 class="section">5.8 Internationalization</h3>
|
||
|
|
|
||
|
|
<p><a name="index-internationalization-87"></a>
|
||
|
|
<a name="index-gettext-88"></a>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>Using GNU gettext involves putting a call to the <code>gettext</code> macro
|
||
|
|
around each string that might need translation—like this:
|
||
|
|
|
||
|
|
<pre class="example"> printf (gettext ("Processing file `%s'..."));
|
||
|
|
</pre>
|
||
|
|
<p class="noindent">This permits GNU gettext to replace the string <code>"Processing file
|
||
|
|
`%s'..."</code> with a translated version.
|
||
|
|
|
||
|
|
<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>Using GNU gettext in a package involves specifying a <dfn>text domain
|
||
|
|
name</dfn> 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, <span class="samp">coreutils</span> for the GNU core utilities.
|
||
|
|
|
||
|
|
<p><a name="index-message-text_002c-and-internationalization-89"></a>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>Here is an example of what not to do:
|
||
|
|
|
||
|
|
<pre class="smallexample"> printf ("%s is full", capacity > 5000000 ? "disk" : "floppy disk");
|
||
|
|
</pre>
|
||
|
|
<p>If you apply gettext to all strings, like this,
|
||
|
|
|
||
|
|
<pre class="smallexample"> printf (gettext ("%s is full"),
|
||
|
|
capacity > 5000000 ? gettext ("disk") : gettext ("floppy disk"));
|
||
|
|
</pre>
|
||
|
|
<p class="noindent">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>Complete sentences can be translated without problems:
|
||
|
|
|
||
|
|
<pre class="example"> printf (capacity > 5000000 ? gettext ("disk is full")
|
||
|
|
: gettext ("floppy disk is full"));
|
||
|
|
</pre>
|
||
|
|
<p>A similar problem appears at the level of sentence structure with this
|
||
|
|
code:
|
||
|
|
|
||
|
|
<pre class="example"> printf ("# Implicit rule search has%s been done.\n",
|
||
|
|
f->tried_implicit ? "" : " not");
|
||
|
|
</pre>
|
||
|
|
<p class="noindent">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:
|
||
|
|
|
||
|
|
<pre class="example"> printf (f->tried_implicit
|
||
|
|
? "# Implicit rule search has been done.\n",
|
||
|
|
: "# Implicit rule search has not been done.\n");
|
||
|
|
</pre>
|
||
|
|
<p>Another example is this one:
|
||
|
|
|
||
|
|
<pre class="example"> printf ("%d file%s processed", nfiles,
|
||
|
|
nfiles != 1 ? "s" : "");
|
||
|
|
</pre>
|
||
|
|
<p class="noindent">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,
|
||
|
|
|
||
|
|
<pre class="example"> printf (gettext ("%d file%s processed"), nfiles,
|
||
|
|
nfiles != 1 ? "s" : "");
|
||
|
|
</pre>
|
||
|
|
<p class="noindent">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:
|
||
|
|
|
||
|
|
<pre class="example"> printf ((nfiles != 1 ? gettext ("%d files processed")
|
||
|
|
: gettext ("%d file processed")),
|
||
|
|
nfiles);
|
||
|
|
</pre>
|
||
|
|
<p class="noindent">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:
|
||
|
|
|
||
|
|
<pre class="example"> printf (ngettext ("%d files processed", "%d file processed", nfiles),
|
||
|
|
nfiles);
|
||
|
|
</pre>
|
||
|
|
<div class="node">
|
||
|
|
<p><hr>
|
||
|
|
<a name="Character-Set"></a>Next: <a rel="next" accesskey="n" href="#Quote-Characters">Quote Characters</a>,
|
||
|
|
Previous: <a rel="previous" accesskey="p" href="#Internationalization">Internationalization</a>,
|
||
|
|
Up: <a rel="up" accesskey="u" href="#Writing-C">Writing C</a>
|
||
|
|
<br>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<h3 class="section">5.9 Character Set</h3>
|
||
|
|
|
||
|
|
<p><a name="index-character-set-90"></a><a name="index-encodings-91"></a><a name="index-ASCII-characters-92"></a><a name="index-non_002dASCII-characters-93"></a>
|
||
|
|
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>If you need to use non-ASCII characters, you should normally stick with
|
||
|
|
one encoding, as one cannot in general mix encodings reliably.
|
||
|
|
|
||
|
|
<div class="node">
|
||
|
|
<p><hr>
|
||
|
|
<a name="Quote-Characters"></a>Next: <a rel="next" accesskey="n" href="#Mmap">Mmap</a>,
|
||
|
|
Previous: <a rel="previous" accesskey="p" href="#Character-Set">Character Set</a>,
|
||
|
|
Up: <a rel="up" accesskey="u" href="#Writing-C">Writing C</a>
|
||
|
|
<br>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<h3 class="section">5.10 Quote Characters</h3>
|
||
|
|
|
||
|
|
<p><a name="index-quote-characters-94"></a><a name="index-locale_002dspecific-quote-characters-95"></a><a name="index-left-quote-96"></a><a name="index-grave-accent-97"></a>
|
||
|
|
In the C locale, GNU programs should stick to plain ASCII for quotation
|
||
|
|
characters in messages to users: preferably 0x60 (<span class="samp">`</span>) for left
|
||
|
|
quotes and 0x27 (<span class="samp">'</span>) for right quotes. It is ok, but not
|
||
|
|
required, to use locale-specific quotes in other locales.
|
||
|
|
|
||
|
|
<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>In any case, the documentation for your program should clearly specify
|
||
|
|
how it does quoting, if different than the preferred method of <span class="samp">`</span>
|
||
|
|
and <span class="samp">'</span>. This is especially important if the output of your
|
||
|
|
program is ever likely to be parsed by another program.
|
||
|
|
|
||
|
|
<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 <span class="samp">`</span> character we use was standardized there as a grave
|
||
|
|
accent. Moreover, Latin1 is still not universally usable.
|
||
|
|
|
||
|
|
<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>This may change over the next few years, and then we will revisit
|
||
|
|
this.
|
||
|
|
|
||
|
|
<div class="node">
|
||
|
|
<p><hr>
|
||
|
|
<a name="Mmap"></a>Previous: <a rel="previous" accesskey="p" href="#Quote-Characters">Quote Characters</a>,
|
||
|
|
Up: <a rel="up" accesskey="u" href="#Writing-C">Writing C</a>
|
||
|
|
<br>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<h3 class="section">5.11 Mmap</h3>
|
||
|
|
|
||
|
|
<p><a name="index-mmap-98"></a>
|
||
|
|
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>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>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.
|
||
|
|
|
||
|
|
<div class="node">
|
||
|
|
<p><hr>
|
||
|
|
<a name="Documentation"></a>Next: <a rel="next" accesskey="n" href="#Managing-Releases">Managing Releases</a>,
|
||
|
|
Previous: <a rel="previous" accesskey="p" href="#Writing-C">Writing C</a>,
|
||
|
|
Up: <a rel="up" accesskey="u" href="#Top">Top</a>
|
||
|
|
<br>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<h2 class="chapter">6 Documenting Programs</h2>
|
||
|
|
|
||
|
|
<p><a name="index-documentation-99"></a>
|
||
|
|
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.
|
||
|
|
|
||
|
|
<ul class="menu">
|
||
|
|
<li><a accesskey="1" href="#GNU-Manuals">GNU Manuals</a>: Writing proper manuals.
|
||
|
|
<li><a accesskey="2" href="#Doc-Strings-and-Manuals">Doc Strings and Manuals</a>: Compiling doc strings doesn't make a manual.
|
||
|
|
<li><a accesskey="3" href="#Manual-Structure-Details">Manual Structure Details</a>: Specific structure conventions.
|
||
|
|
<li><a accesskey="4" href="#License-for-Manuals">License for Manuals</a>: Writing the distribution terms for a manual.
|
||
|
|
<li><a accesskey="5" href="#Manual-Credits">Manual Credits</a>: Giving credit to documentation contributors.
|
||
|
|
<li><a accesskey="6" href="#Printed-Manuals">Printed Manuals</a>: Mentioning the printed manual.
|
||
|
|
<li><a accesskey="7" href="#NEWS-File">NEWS File</a>: NEWS files supplement manuals.
|
||
|
|
<li><a accesskey="8" href="#Change-Logs">Change Logs</a>: Recording changes.
|
||
|
|
<li><a accesskey="9" href="#Man-Pages">Man Pages</a>: Man pages are secondary.
|
||
|
|
<li><a href="#Reading-other-Manuals">Reading other Manuals</a>: How far you can go in learning
|
||
|
|
from other manuals.
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<div class="node">
|
||
|
|
<p><hr>
|
||
|
|
<a name="GNU-Manuals"></a>Next: <a rel="next" accesskey="n" href="#Doc-Strings-and-Manuals">Doc Strings and Manuals</a>,
|
||
|
|
Up: <a rel="up" accesskey="u" href="#Documentation">Documentation</a>
|
||
|
|
<br>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<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>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>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>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>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>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>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>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>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>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>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>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="texinfo.html#Index-Entries">Making Index Entries (GNU Texinfo)</a>, and
|
||
|
|
see <a href="texinfo.html#Indexing-Commands">Defining the Entries of an Index (GNU Texinfo)</a>.
|
||
|
|
|
||
|
|
<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>Please include an email address in the manual for where to report
|
||
|
|
bugs <em>in the text of the manual</em>.
|
||
|
|
|
||
|
|
<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>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>Please do not write <span class="samp">()</span> 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.
|
||
|
|
|
||
|
|
<div class="node">
|
||
|
|
<p><hr>
|
||
|
|
<a name="Doc-Strings-and-Manuals"></a>Next: <a rel="next" accesskey="n" href="#Manual-Structure-Details">Manual Structure Details</a>,
|
||
|
|
Previous: <a rel="previous" accesskey="p" href="#GNU-Manuals">GNU Manuals</a>,
|
||
|
|
Up: <a rel="up" accesskey="u" href="#Documentation">Documentation</a>
|
||
|
|
<br>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<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>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>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>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.
|
||
|
|
|
||
|
|
<div class="node">
|
||
|
|
<p><hr>
|
||
|
|
<a name="Manual-Structure-Details"></a>Next: <a rel="next" accesskey="n" href="#License-for-Manuals">License for Manuals</a>,
|
||
|
|
Previous: <a rel="previous" accesskey="p" href="#Doc-Strings-and-Manuals">Doc Strings and Manuals</a>,
|
||
|
|
Up: <a rel="up" accesskey="u" href="#Documentation">Documentation</a>
|
||
|
|
<br>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<h3 class="section">6.3 Manual Structure Details</h3>
|
||
|
|
|
||
|
|
<p><a name="index-manual-structure-100"></a>
|
||
|
|
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>Each program documented in the manual should have a node named
|
||
|
|
<var>program</var><span class="samp"> Invocation</span> or <span class="samp">Invoking </span><var>program</var>. 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 <span class="samp">@example</span>
|
||
|
|
containing a template for all the options and arguments that the program
|
||
|
|
uses.
|
||
|
|
|
||
|
|
<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>The <span class="samp">--usage</span> 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>If one manual describes several programs, it should have such a node for
|
||
|
|
each program described in the manual.
|
||
|
|
|
||
|
|
<div class="node">
|
||
|
|
<p><hr>
|
||
|
|
<a name="License-for-Manuals"></a>Next: <a rel="next" accesskey="n" href="#Manual-Credits">Manual Credits</a>,
|
||
|
|
Previous: <a rel="previous" accesskey="p" href="#Manual-Structure-Details">Manual Structure Details</a>,
|
||
|
|
Up: <a rel="up" accesskey="u" href="#Documentation">Documentation</a>
|
||
|
|
<br>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<h3 class="section">6.4 License for Manuals</h3>
|
||
|
|
|
||
|
|
<p><a name="index-license-for-manuals-101"></a>
|
||
|
|
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>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>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.
|
||
|
|
|
||
|
|
<div class="node">
|
||
|
|
<p><hr>
|
||
|
|
<a name="Manual-Credits"></a>Next: <a rel="next" accesskey="n" href="#Printed-Manuals">Printed Manuals</a>,
|
||
|
|
Previous: <a rel="previous" accesskey="p" href="#License-for-Manuals">License for Manuals</a>,
|
||
|
|
Up: <a rel="up" accesskey="u" href="#Documentation">Documentation</a>
|
||
|
|
<br>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<h3 class="section">6.5 Manual Credits</h3>
|
||
|
|
|
||
|
|
<p><a name="index-credits-for-manuals-102"></a>
|
||
|
|
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.
|
||
|
|
|
||
|
|
<div class="node">
|
||
|
|
<p><hr>
|
||
|
|
<a name="Printed-Manuals"></a>Next: <a rel="next" accesskey="n" href="#NEWS-File">NEWS File</a>,
|
||
|
|
Previous: <a rel="previous" accesskey="p" href="#Manual-Credits">Manual Credits</a>,
|
||
|
|
Up: <a rel="up" accesskey="u" href="#Documentation">Documentation</a>
|
||
|
|
<br>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<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>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.
|
||
|
|
|
||
|
|
<div class="node">
|
||
|
|
<p><hr>
|
||
|
|
<a name="NEWS-File"></a>Next: <a rel="next" accesskey="n" href="#Change-Logs">Change Logs</a>,
|
||
|
|
Previous: <a rel="previous" accesskey="p" href="#Printed-Manuals">Printed Manuals</a>,
|
||
|
|
Up: <a rel="up" accesskey="u" href="#Documentation">Documentation</a>
|
||
|
|
<br>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<h3 class="section">6.7 The NEWS File</h3>
|
||
|
|
|
||
|
|
<p><a name="index-_0040file_007bNEWS_007d-file-103"></a>
|
||
|
|
In addition to its manual, the package should have a file named
|
||
|
|
<span class="file">NEWS</span> 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>If the <span class="file">NEWS</span> file gets very long, move some of the older items
|
||
|
|
into a file named <span class="file">ONEWS</span> and put a note at the end referring the
|
||
|
|
user to that file.
|
||
|
|
|
||
|
|
<div class="node">
|
||
|
|
<p><hr>
|
||
|
|
<a name="Change-Logs"></a>Next: <a rel="next" accesskey="n" href="#Man-Pages">Man Pages</a>,
|
||
|
|
Previous: <a rel="previous" accesskey="p" href="#NEWS-File">NEWS File</a>,
|
||
|
|
Up: <a rel="up" accesskey="u" href="#Documentation">Documentation</a>
|
||
|
|
<br>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<h3 class="section">6.8 Change Logs</h3>
|
||
|
|
|
||
|
|
<p><a name="index-change-logs-104"></a>
|
||
|
|
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.
|
||
|
|
|
||
|
|
<ul class="menu">
|
||
|
|
<li><a accesskey="1" href="#Change-Log-Concepts">Change Log Concepts</a>
|
||
|
|
<li><a accesskey="2" href="#Style-of-Change-Logs">Style of Change Logs</a>
|
||
|
|
<li><a accesskey="3" href="#Simple-Changes">Simple Changes</a>
|
||
|
|
<li><a accesskey="4" href="#Conditional-Changes">Conditional Changes</a>
|
||
|
|
<li><a accesskey="5" href="#Indicating-the-Part-Changed">Indicating the Part Changed</a>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<div class="node">
|
||
|
|
<p><hr>
|
||
|
|
<a name="Change-Log-Concepts"></a>Next: <a rel="next" accesskey="n" href="#Style-of-Change-Logs">Style of Change Logs</a>,
|
||
|
|
Up: <a rel="up" accesskey="u" href="#Change-Logs">Change Logs</a>
|
||
|
|
<br>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<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>The change log file is normally called <span class="file">ChangeLog</span> 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>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 <span class="file">ChangeLog</span> 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>There's no need to describe the full purpose of the changes or how they
|
||
|
|
work together. If you think that a change calls for explanation, you're
|
||
|
|
probably right. Please do explain it—but please put the 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>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>However, sometimes it is useful to write one line to describe the
|
||
|
|
overall purpose of a batch of changes.
|
||
|
|
|
||
|
|
<p>The easiest way to add an entry to <span class="file">ChangeLog</span> 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.
|
||
|
|
|
||
|
|
<div class="node">
|
||
|
|
<p><hr>
|
||
|
|
<a name="Style-of-Change-Logs"></a>Next: <a rel="next" accesskey="n" href="#Simple-Changes">Simple Changes</a>,
|
||
|
|
Previous: <a rel="previous" accesskey="p" href="#Change-Log-Concepts">Change Log Concepts</a>,
|
||
|
|
Up: <a rel="up" accesskey="u" href="#Change-Logs">Change Logs</a>
|
||
|
|
<br>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<h4 class="subsection">6.8.2 Style of Change Logs</h4>
|
||
|
|
|
||
|
|
<p><a name="index-change-logs_002c-style-105"></a>
|
||
|
|
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.)
|
||
|
|
|
||
|
|
<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>
|
||
|
|
<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>For example, some people are tempted to abbreviate groups of function
|
||
|
|
names by writing <span class="samp">* register.el ({insert,jump-to}-register)</span>;
|
||
|
|
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>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>Break long lists of function names by closing continued lines with
|
||
|
|
<span class="samp">)</span>, rather than <span class="samp">,</span>, and opening the continuation with
|
||
|
|
<span class="samp">(</span> as in this example:
|
||
|
|
|
||
|
|
<pre class="example"> * keyboard.c (menu_bar_items, tool_bar_items)
|
||
|
|
(Fexecute_extended_command): Deal with `keymap' property.
|
||
|
|
</pre>
|
||
|
|
<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:
|
||
|
|
|
||
|
|
<pre class="example"> 2002-07-14 John Doe <jdoe@gnu.org>
|
||
|
|
|
||
|
|
* sewing.c: Make it sew.
|
||
|
|
</pre>
|
||
|
|
<p class="noindent">rather than this:
|
||
|
|
|
||
|
|
<pre class="example"> 2002-07-14 Usual Maintainer <usual@gnu.org>
|
||
|
|
|
||
|
|
* sewing.c: Make it sew. Patch by jdoe@gnu.org.
|
||
|
|
</pre>
|
||
|
|
<p>As for the date, that should be the date you applied the change.
|
||
|
|
|
||
|
|
<div class="node">
|
||
|
|
<p><hr>
|
||
|
|
<a name="Simple-Changes"></a>Next: <a rel="next" accesskey="n" href="#Conditional-Changes">Conditional Changes</a>,
|
||
|
|
Previous: <a rel="previous" accesskey="p" href="#Style-of-Change-Logs">Style of Change Logs</a>,
|
||
|
|
Up: <a rel="up" accesskey="u" href="#Change-Logs">Change Logs</a>
|
||
|
|
<br>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<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>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:
|
||
|
|
|
||
|
|
<pre class="example"> * keyboard.c (Fcommand_execute): New arg SPECIAL.
|
||
|
|
All callers changed.
|
||
|
|
</pre>
|
||
|
|
<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>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>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.
|
||
|
|
|
||
|
|
<div class="node">
|
||
|
|
<p><hr>
|
||
|
|
<a name="Conditional-Changes"></a>Next: <a rel="next" accesskey="n" href="#Indicating-the-Part-Changed">Indicating the Part Changed</a>,
|
||
|
|
Previous: <a rel="previous" accesskey="p" href="#Simple-Changes">Simple Changes</a>,
|
||
|
|
Up: <a rel="up" accesskey="u" href="#Change-Logs">Change Logs</a>
|
||
|
|
<br>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<h4 class="subsection">6.8.4 Conditional Changes</h4>
|
||
|
|
|
||
|
|
<p><a name="index-conditional-changes_002c-and-change-logs-106"></a><a name="index-change-logs_002c-conditional-changes-107"></a>
|
||
|
|
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>Our convention for indicating conditional changes is to use square
|
||
|
|
brackets around the name of the condition.
|
||
|
|
|
||
|
|
<p>Here is a simple example, describing a change which is conditional but
|
||
|
|
does not have a function or entity name associated with it:
|
||
|
|
|
||
|
|
<pre class="example"> * xterm.c [SOLARIS2]: Include string.h.
|
||
|
|
</pre>
|
||
|
|
<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:
|
||
|
|
|
||
|
|
<pre class="example"> * frame.h [HAVE_X_WINDOWS] (FRAME_WINDOW_P): Macro defined.
|
||
|
|
</pre>
|
||
|
|
<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 <span class="samp">#ifdef HAVE_LIBNCURSES</span> conditional:
|
||
|
|
|
||
|
|
<pre class="example"> * dispnew.c (init_display) [HAVE_LIBNCURSES]: If X, call tgetent.
|
||
|
|
</pre>
|
||
|
|
<p>Here is an entry for a change that takes affect only when
|
||
|
|
a certain macro is <em>not</em> defined:
|
||
|
|
|
||
|
|
<pre class="example"> (gethostname) [!HAVE_SOCKETS]: Replace with winsock version.
|
||
|
|
</pre>
|
||
|
|
<div class="node">
|
||
|
|
<p><hr>
|
||
|
|
<a name="Indicating-the-Part-Changed"></a>Previous: <a rel="previous" accesskey="p" href="#Conditional-Changes">Conditional Changes</a>,
|
||
|
|
Up: <a rel="up" accesskey="u" href="#Change-Logs">Change Logs</a>
|
||
|
|
<br>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<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:
|
||
|
|
|
||
|
|
<pre class="example"> * progmodes/sh-script.el (sh-while-getopts) <sh>: Handle case that
|
||
|
|
user-specified option string is empty.
|
||
|
|
</pre>
|
||
|
|
<div class="node">
|
||
|
|
<p><hr>
|
||
|
|
<a name="Man-Pages"></a>Next: <a rel="next" accesskey="n" href="#Reading-other-Manuals">Reading other Manuals</a>,
|
||
|
|
Previous: <a rel="previous" accesskey="p" href="#Change-Logs">Change Logs</a>,
|
||
|
|
Up: <a rel="up" accesskey="u" href="#Documentation">Documentation</a>
|
||
|
|
<br>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<h3 class="section">6.9 Man Pages</h3>
|
||
|
|
|
||
|
|
<p><a name="index-man-pages-108"></a>
|
||
|
|
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>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>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>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>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>Be sure that man pages include a copyright statement and free
|
||
|
|
license. The simple all-permissive license is appropriate for simple
|
||
|
|
man pages:
|
||
|
|
|
||
|
|
<pre class="example"> Copying and distribution of this file, with or without modification,
|
||
|
|
are permitted in any medium without royalty provided the copyright
|
||
|
|
notice and this notice are preserved.
|
||
|
|
</pre>
|
||
|
|
<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>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 <span class="option">--help</span> output.
|
||
|
|
This is sufficient in many cases.
|
||
|
|
|
||
|
|
<div class="node">
|
||
|
|
<p><hr>
|
||
|
|
<a name="Reading-other-Manuals"></a>Previous: <a rel="previous" accesskey="p" href="#Man-Pages">Man Pages</a>,
|
||
|
|
Up: <a rel="up" accesskey="u" href="#Documentation">Documentation</a>
|
||
|
|
<br>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<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>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.
|
||
|
|
|
||
|
|
<div class="node">
|
||
|
|
<p><hr>
|
||
|
|
<a name="Managing-Releases"></a>Next: <a rel="next" accesskey="n" href="#References">References</a>,
|
||
|
|
Previous: <a rel="previous" accesskey="p" href="#Documentation">Documentation</a>,
|
||
|
|
Up: <a rel="up" accesskey="u" href="#Top">Top</a>
|
||
|
|
<br>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<h2 class="chapter">7 The Release Process</h2>
|
||
|
|
|
||
|
|
<p><a name="index-releasing-109"></a>
|
||
|
|
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.
|
||
|
|
|
||
|
|
<ul class="menu">
|
||
|
|
<li><a accesskey="1" href="#Configuration">Configuration</a>: How configuration of GNU packages should work.
|
||
|
|
<li><a accesskey="2" href="#Makefile-Conventions">Makefile Conventions</a>: Makefile conventions.
|
||
|
|
<li><a accesskey="3" href="#Releases">Releases</a>: Making releases
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<div class="node">
|
||
|
|
<p><hr>
|
||
|
|
<a name="Configuration"></a>Next: <a rel="next" accesskey="n" href="#Makefile-Conventions">Makefile Conventions</a>,
|
||
|
|
Up: <a rel="up" accesskey="u" href="#Managing-Releases">Managing Releases</a>
|
||
|
|
<br>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<h3 class="section">7.1 How Configuration Should Work</h3>
|
||
|
|
|
||
|
|
<p><a name="index-program-configuration-110"></a>
|
||
|
|
<a name="index-configure-111"></a>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.
|
||
|
|
|
||
|
|
<p>The <code>configure</code> script must record the configuration options so
|
||
|
|
that they affect compilation.
|
||
|
|
|
||
|
|
<p>One way to do this is to make a link from a standard name such as
|
||
|
|
<span class="file">config.h</span> to the proper configuration file for the chosen system.
|
||
|
|
If you use this technique, the distribution should <em>not</em> contain a
|
||
|
|
file named <span class="file">config.h</span>. This is so that people won't be able to
|
||
|
|
build the program without configuring it first.
|
||
|
|
|
||
|
|
<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
|
||
|
|
<span class="file">Makefile</span>. Instead, it should include a file <span class="file">Makefile.in</span> 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>If <code>configure</code> does write the <span class="file">Makefile</span>, then <span class="file">Makefile</span>
|
||
|
|
should have a target named <span class="file">Makefile</span> 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 <span class="file">Makefile</span>.
|
||
|
|
|
||
|
|
<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>The <code>configure</code> script should write a file named <span class="file">config.status</span>
|
||
|
|
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>The <code>configure</code> script should accept an option of the form
|
||
|
|
<span class="samp">--srcdir=</span><var>dirname</var> 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>If the user does not specify <span class="samp">--srcdir</span>, then <code>configure</code> should
|
||
|
|
check both <span class="file">.</span> and <span class="file">..</span> 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>Usually the easy way to support <span class="samp">--srcdir</span> 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>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:
|
||
|
|
|
||
|
|
<pre class="example"> <var>cpu</var>-<var>company</var>-<var>system</var>
|
||
|
|
</pre>
|
||
|
|
<p>For example, an Athlon-based GNU/Linux system might be
|
||
|
|
<span class="samp">i686-pc-linux-gnu</span>.
|
||
|
|
|
||
|
|
<p>The <code>configure</code> script needs to be able to decode all plausible
|
||
|
|
alternatives for how to describe a machine. Thus,
|
||
|
|
<span class="samp">athlon-pc-gnu/linux</span> would be a valid alias. There is a shell
|
||
|
|
script called
|
||
|
|
<a href="http://savannah.gnu.org/cgi-bin/viewcvs/*checkout*/config/config/config.sub"><span class="file">config.sub</span></a> that you can use as a subroutine to validate system
|
||
|
|
types and canonicalize aliases.
|
||
|
|
|
||
|
|
<p>The <code>configure</code> script should also take the option
|
||
|
|
<span class="option">--build=</span><var>buildtype</var>, which should be equivalent to a
|
||
|
|
plain <var>buildtype</var> argument. For example, <span class="samp">configure
|
||
|
|
--build=i686-pc-linux-gnu</span> is equivalent to <span class="samp">configure
|
||
|
|
i686-pc-linux-gnu</span>. 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://savannah.gnu.org/cgi-bin/viewcvs/*checkout*/config/config/config.guess"><span class="file">config.guess</span></a>.
|
||
|
|
|
||
|
|
<p><a name="index-optional-features_002c-configure_002dtime-112"></a>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:
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<dt><span class="samp">--enable-</span><var>feature</var><span class="samp">[=</span><var>parameter</var><span class="samp">]</span><dd>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
|
||
|
|
<span class="samp">no</span> should omit <var>feature</var>, if it is built by default.
|
||
|
|
|
||
|
|
<p>No <span class="samp">--enable</span> option should <strong>ever</strong> cause one feature to
|
||
|
|
replace another. No <span class="samp">--enable</span> option should ever substitute one
|
||
|
|
useful behavior for another useful behavior. The only proper use for
|
||
|
|
<span class="samp">--enable</span> is for questions of whether to build part of the program
|
||
|
|
or exclude it.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">--with-</span><var>package</var><dd><!-- @r{[}=@var{parameter}@r{]} -->
|
||
|
|
The package <var>package</var> will be installed, so configure this package
|
||
|
|
to work with <var>package</var>.
|
||
|
|
|
||
|
|
<!-- Giving an optional @var{parameter} of -->
|
||
|
|
<!-- @samp{no} should omit @var{package}, if it is used by default. -->
|
||
|
|
<p>Possible values of <var>package</var> include
|
||
|
|
<span class="samp">gnu-as</span> (or <span class="samp">gas</span>), <span class="samp">gnu-ld</span>, <span class="samp">gnu-libc</span>,
|
||
|
|
<span class="samp">gdb</span>,
|
||
|
|
<span class="samp">x</span>,
|
||
|
|
and
|
||
|
|
<span class="samp">x-toolkit</span>.
|
||
|
|
|
||
|
|
<p>Do not use a <span class="samp">--with</span> option to specify the file name to use to
|
||
|
|
find certain files. That is outside the scope of what <span class="samp">--with</span>
|
||
|
|
options are for.
|
||
|
|
|
||
|
|
<br><dt><var>variable</var><span class="samp">=</span><var>value</var><dd>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 <span class="samp">configure
|
||
|
|
CFLAGS=-g CXXFLAGS=-g</span> to build with debugging information and without
|
||
|
|
the default optimization.
|
||
|
|
|
||
|
|
<p>Specifying variables as arguments to <code>configure</code>, like this:
|
||
|
|
<pre class="example"> ./configure CC=gcc
|
||
|
|
</pre>
|
||
|
|
<p>is preferable to setting them in environment variables:
|
||
|
|
<pre class="example"> CC=gcc ./configure
|
||
|
|
</pre>
|
||
|
|
<p>as it helps to recreate the same configuration later with
|
||
|
|
<span class="file">config.status</span>.
|
||
|
|
</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 <span class="samp">--with-</span> or
|
||
|
|
<span class="samp">--enable-</span>. This is so users will be able to configure an
|
||
|
|
entire GNU source tree at once with a single set of options.
|
||
|
|
|
||
|
|
<p>You will note that the categories <span class="samp">--with-</span> and <span class="samp">--enable-</span>
|
||
|
|
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>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>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>To compile a program to run on a host type that differs from the build
|
||
|
|
type, use the configure option <span class="option">--host=</span><var>hosttype</var>, where
|
||
|
|
<var>hosttype</var> uses the same syntax as <var>buildtype</var>. The host type
|
||
|
|
normally defaults to the build type.
|
||
|
|
|
||
|
|
<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 <span class="samp">--target=</span><var>targettype</var>. The syntax for
|
||
|
|
<var>targettype</var> is the same as for the host type. So the command would
|
||
|
|
look like this:
|
||
|
|
|
||
|
|
<pre class="example"> ./configure --host=<var>hosttype</var> --target=<var>targettype</var>
|
||
|
|
</pre>
|
||
|
|
<p>The target type normally defaults to the host type.
|
||
|
|
Programs for which cross-operation is not meaningful need not accept the
|
||
|
|
<span class="samp">--target</span> option, because configuring an entire operating system for
|
||
|
|
cross-operation is not a meaningful operation.
|
||
|
|
|
||
|
|
<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.
|
||
|
|
|
||
|
|
<!-- The makefile standards are in a separate file that is also -->
|
||
|
|
<!-- included by make.texinfo. Done by roland@gnu.ai.mit.edu on 1/6/93. -->
|
||
|
|
<!-- For this document, turn chapters into sections, etc. -->
|
||
|
|
<!-- This file is included by both standards.texi and make.texinfo. -->
|
||
|
|
<!-- It was broken out of standards.texi on 1/6/93 by roland. -->
|
||
|
|
<div class="node">
|
||
|
|
<p><hr>
|
||
|
|
<a name="Makefile-Conventions"></a>Next: <a rel="next" accesskey="n" href="#Releases">Releases</a>,
|
||
|
|
Previous: <a rel="previous" accesskey="p" href="#Configuration">Configuration</a>,
|
||
|
|
Up: <a rel="up" accesskey="u" href="#Managing-Releases">Managing Releases</a>
|
||
|
|
<br>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<h3 class="section">7.2 Makefile Conventions</h3>
|
||
|
|
|
||
|
|
<!-- standards.texi does not print an index, but make.texinfo does. -->
|
||
|
|
<p><a name="index-makefile_002c-conventions-for-113"></a><a name="index-conventions-for-makefiles-114"></a><a name="index-standards-for-makefiles-115"></a>
|
||
|
|
<!-- Copyright (C) 1992, 1993, 1994, 1995, 1996, 1997, 1998, 2000, 2001, -->
|
||
|
|
<!-- 2004, 2005, 2006 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.2 -->
|
||
|
|
<!-- 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>This
|
||
|
|
describes conventions for writing the Makefiles for GNU programs.
|
||
|
|
Using Automake will help you write a Makefile that follows these
|
||
|
|
conventions.
|
||
|
|
|
||
|
|
<ul class="menu">
|
||
|
|
<li><a accesskey="1" href="#Makefile-Basics">Makefile Basics</a>: General conventions for Makefiles.
|
||
|
|
<li><a accesskey="2" href="#Utilities-in-Makefiles">Utilities in Makefiles</a>: Utilities to be used in Makefiles.
|
||
|
|
<li><a accesskey="3" href="#Command-Variables">Command Variables</a>: Variables for specifying commands.
|
||
|
|
<li><a accesskey="4" href="#DESTDIR">DESTDIR</a>: Supporting staged installs.
|
||
|
|
<li><a accesskey="5" href="#Directory-Variables">Directory Variables</a>: Variables for installation directories.
|
||
|
|
<li><a accesskey="6" href="#Standard-Targets">Standard Targets</a>: Standard targets for users.
|
||
|
|
<li><a accesskey="7" href="#Install-Command-Categories">Install Command Categories</a>: Three categories of commands in the `install'
|
||
|
|
rule: normal, pre-install and post-install.
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<div class="node">
|
||
|
|
<p><hr>
|
||
|
|
<a name="Makefile-Basics"></a>Next: <a rel="next" accesskey="n" href="#Utilities-in-Makefiles">Utilities in Makefiles</a>,
|
||
|
|
Up: <a rel="up" accesskey="u" href="#Makefile-Conventions">Makefile Conventions</a>
|
||
|
|
<br>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<h4 class="subsection">7.2.1 General Conventions for Makefiles</h4>
|
||
|
|
|
||
|
|
<p>Every Makefile should contain this line:
|
||
|
|
|
||
|
|
<pre class="example"> SHELL = /bin/sh
|
||
|
|
</pre>
|
||
|
|
<p class="noindent">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>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:
|
||
|
|
|
||
|
|
<pre class="example"> .SUFFIXES:
|
||
|
|
.SUFFIXES: .c .o
|
||
|
|
</pre>
|
||
|
|
<p class="noindent">The first line clears out the suffix list, the second introduces all
|
||
|
|
suffixes which may be subject to implicit rules in this Makefile.
|
||
|
|
|
||
|
|
<p>Don't assume that <span class="file">.</span> 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 <span class="file">./</span> if the program is built as
|
||
|
|
part of the make or <span class="file">$(srcdir)/</span> if the file is an unchanging part
|
||
|
|
of the source code. Without one of these prefixes, the current search
|
||
|
|
path is used.
|
||
|
|
|
||
|
|
<p>The distinction between <span class="file">./</span> (the <dfn>build directory</dfn>) and
|
||
|
|
<span class="file">$(srcdir)/</span> (the <dfn>source directory</dfn>) is important because
|
||
|
|
users can build in a separate directory using the <span class="samp">--srcdir</span> option
|
||
|
|
to <span class="file">configure</span>. A rule of the form:
|
||
|
|
|
||
|
|
<pre class="smallexample"> foo.1 : foo.man sedscript
|
||
|
|
sed -e sedscript foo.man > foo.1
|
||
|
|
</pre>
|
||
|
|
<p class="noindent">will fail when the build directory is not the source directory, because
|
||
|
|
<span class="file">foo.man</span> and <span class="file">sedscript</span> are in the source directory.
|
||
|
|
|
||
|
|
<p>When using GNU <code>make</code>, relying on <span class="samp">VPATH</span> to find the source
|
||
|
|
file will work in the case where there is a single dependency file,
|
||
|
|
since the <code>make</code> automatic variable <span class="samp">$<</span> will represent the
|
||
|
|
source file wherever it is. (Many versions of <code>make</code> set <span class="samp">$<</span>
|
||
|
|
only in implicit rules.) A Makefile target like
|
||
|
|
|
||
|
|
<pre class="smallexample"> foo.o : bar.c
|
||
|
|
$(CC) -I. -I$(srcdir) $(CFLAGS) -c bar.c -o foo.o
|
||
|
|
</pre>
|
||
|
|
<p class="noindent">should instead be written as
|
||
|
|
|
||
|
|
<pre class="smallexample"> foo.o : bar.c
|
||
|
|
$(CC) -I. -I$(srcdir) $(CFLAGS) -c $< -o $@
|
||
|
|
</pre>
|
||
|
|
<p class="noindent">in order to allow <span class="samp">VPATH</span> to work correctly. When the target has
|
||
|
|
multiple dependencies, using an explicit <span class="samp">$(srcdir)</span> is the easiest
|
||
|
|
way to make the rule work well. For example, the target above for
|
||
|
|
<span class="file">foo.1</span> is best written as:
|
||
|
|
|
||
|
|
<pre class="smallexample"> foo.1 : foo.man sedscript
|
||
|
|
sed -e $(srcdir)/sedscript $(srcdir)/foo.man > $@
|
||
|
|
</pre>
|
||
|
|
<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>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>Try to make the build and installation targets, at least (and all their
|
||
|
|
subtargets) work correctly with a parallel <code>make</code>.
|
||
|
|
|
||
|
|
<div class="node">
|
||
|
|
<p><hr>
|
||
|
|
<a name="Utilities-in-Makefiles"></a>Next: <a rel="next" accesskey="n" href="#Command-Variables">Command Variables</a>,
|
||
|
|
Previous: <a rel="previous" accesskey="p" href="#Makefile-Basics">Makefile Basics</a>,
|
||
|
|
Up: <a rel="up" accesskey="u" href="#Makefile-Conventions">Makefile Conventions</a>
|
||
|
|
<br>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<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>The <code>configure</code> script and the Makefile rules for building and
|
||
|
|
installation should not use any utilities directly except these:
|
||
|
|
|
||
|
|
<!-- dd find -->
|
||
|
|
<!-- gunzip gzip md5sum -->
|
||
|
|
<!-- mkfifo mknod tee uname -->
|
||
|
|
<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>
|
||
|
|
<p>The compression program <code>gzip</code> can be used in the <code>dist</code> rule.
|
||
|
|
|
||
|
|
<p>Stick to the generally supported options for these programs. For
|
||
|
|
example, don't use <span class="samp">mkdir -p</span>, convenient as it may be, because
|
||
|
|
most systems don't support it.
|
||
|
|
|
||
|
|
<p>It is a good idea to avoid creating symbolic links in makefiles, since a
|
||
|
|
few systems don't support them.
|
||
|
|
|
||
|
|
<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:
|
||
|
|
|
||
|
|
<pre class="example"> ar bison cc flex install ld ldconfig lex
|
||
|
|
make makeinfo ranlib texi2dvi yacc
|
||
|
|
</pre>
|
||
|
|
<p>Use the following <code>make</code> variables to run those programs:
|
||
|
|
|
||
|
|
<pre class="example"> $(AR) $(BISON) $(CC) $(FLEX) $(INSTALL) $(LD) $(LDCONFIG) $(LEX)
|
||
|
|
$(MAKE) $(MAKEINFO) $(RANLIB) $(TEXI2DVI) $(YACC)
|
||
|
|
</pre>
|
||
|
|
<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 <span class="samp">AC_PROG_RANLIB</span> macro can help with
|
||
|
|
this.)
|
||
|
|
|
||
|
|
<p>If you use symbolic links, you should implement a fallback for systems
|
||
|
|
that don't have symbolic links.
|
||
|
|
|
||
|
|
<p>Additional utilities that can be used via Make variables are:
|
||
|
|
|
||
|
|
<pre class="example"> chgrp chmod chown mknod
|
||
|
|
</pre>
|
||
|
|
<p>It is ok to use other utilities in Makefile portions (or scripts)
|
||
|
|
intended only for particular systems where you know those utilities
|
||
|
|
exist.
|
||
|
|
|
||
|
|
<div class="node">
|
||
|
|
<p><hr>
|
||
|
|
<a name="Command-Variables"></a>Next: <a rel="next" accesskey="n" href="#DESTDIR">DESTDIR</a>,
|
||
|
|
Previous: <a rel="previous" accesskey="p" href="#Utilities-in-Makefiles">Utilities in Makefiles</a>,
|
||
|
|
Up: <a rel="up" accesskey="u" href="#Makefile-Conventions">Makefile Conventions</a>
|
||
|
|
<br>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<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>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 <span class="samp">BISON = bison</span>, and refer to it with
|
||
|
|
<code>$(BISON)</code> whenever you need to use Bison.
|
||
|
|
|
||
|
|
<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>Each program-name variable should come with an options variable that is
|
||
|
|
used to supply options to the program. Append <span class="samp">FLAGS</span> 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>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:
|
||
|
|
|
||
|
|
<pre class="smallexample"> CFLAGS = -g
|
||
|
|
ALL_CFLAGS = -I. $(CFLAGS)
|
||
|
|
.c.o:
|
||
|
|
$(CC) -c $(CPPFLAGS) $(ALL_CFLAGS) $<
|
||
|
|
</pre>
|
||
|
|
<p>Do include the <span class="samp">-g</span> 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 <span class="samp">-O</span>
|
||
|
|
in the default value of <code>CFLAGS</code> as well.
|
||
|
|
|
||
|
|
<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><code>CFLAGS</code> should be used in every invocation of the C compiler,
|
||
|
|
both those which do compilation and those which do linking.
|
||
|
|
|
||
|
|
<p>Every Makefile should define the variable <code>INSTALL</code>, which is the
|
||
|
|
basic command for installing a file into the system.
|
||
|
|
|
||
|
|
<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:
|
||
|
|
|
||
|
|
<pre class="example"> $(INSTALL_PROGRAM) foo $(bindir)/foo
|
||
|
|
$(INSTALL_DATA) libfoo.a $(libdir)/libfoo.a
|
||
|
|
</pre>
|
||
|
|
<p>However, it is preferable to support a <code>DESTDIR</code> prefix on the
|
||
|
|
target files, as explained in the next section.
|
||
|
|
|
||
|
|
<p class="noindent">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.
|
||
|
|
|
||
|
|
<div class="node">
|
||
|
|
<p><hr>
|
||
|
|
<a name="DESTDIR"></a>Next: <a rel="next" accesskey="n" href="#Directory-Variables">Directory Variables</a>,
|
||
|
|
Previous: <a rel="previous" accesskey="p" href="#Command-Variables">Command Variables</a>,
|
||
|
|
Up: <a rel="up" accesskey="u" href="#Makefile-Conventions">Makefile Conventions</a>
|
||
|
|
<br>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<h4 class="subsection">7.2.4 <code>DESTDIR</code>: support for staged installs</h4>
|
||
|
|
|
||
|
|
<p><a name="index-DESTDIR-116"></a><a name="index-staged-installs-117"></a><a name="index-installations_002c-staged-118"></a>
|
||
|
|
<code>DESTDIR</code> is a variable prepended to each installed target file,
|
||
|
|
like this:
|
||
|
|
|
||
|
|
<pre class="example"> $(INSTALL_PROGRAM) foo $(DESTDIR)$(bindir)/foo
|
||
|
|
$(INSTALL_DATA) libfoo.a $(DESTDIR)$(libdir)/libfoo.a
|
||
|
|
</pre>
|
||
|
|
<p>The <code>DESTDIR</code> variable is specified by the user on the <code>make</code>
|
||
|
|
command line. For example:
|
||
|
|
|
||
|
|
<pre class="example"> make DESTDIR=/tmp/stage install
|
||
|
|
</pre>
|
||
|
|
<p class="noindent"><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>If your installation step would normally install
|
||
|
|
<span class="file">/usr/local/bin/foo</span> and <span class="file">/usr/local/lib/libfoo.a</span>, then an
|
||
|
|
installation invoked as in the example above would install
|
||
|
|
<span class="file">/tmp/stage/usr/local/bin/foo</span> and
|
||
|
|
<span class="file">/tmp/stage/usr/local/lib/libfoo.a</span> instead.
|
||
|
|
|
||
|
|
<p>Prepending the variable <code>DESTDIR</code> to each target in this way
|
||
|
|
provides for <dfn>staged installs</dfn>, 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>You should not set the value of <code>DESTDIR</code> in your <span class="file">Makefile</span>
|
||
|
|
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><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.
|
||
|
|
|
||
|
|
<div class="node">
|
||
|
|
<p><hr>
|
||
|
|
<a name="Directory-Variables"></a>Next: <a rel="next" accesskey="n" href="#Standard-Targets">Standard Targets</a>,
|
||
|
|
Previous: <a rel="previous" accesskey="p" href="#DESTDIR">DESTDIR</a>,
|
||
|
|
Up: <a rel="up" accesskey="u" href="#Makefile-Conventions">Makefile Conventions</a>
|
||
|
|
<br>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<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>Installers are expected to override these values when calling
|
||
|
|
<span class="command">make</span> (e.g., <kbd>make prefix=/usr install</kbd> or
|
||
|
|
<span class="command">configure</span> (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>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.
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<dt><code>prefix</code><dd><a name="index-prefix-119"></a>A prefix used in constructing the default values of the variables listed
|
||
|
|
below. The default value of <code>prefix</code> should be <span class="file">/usr/local</span>.
|
||
|
|
When building the complete GNU system, the prefix will be empty and
|
||
|
|
<span class="file">/usr</span> will be a symbolic link to <span class="file">/</span>.
|
||
|
|
(If you are using Autoconf, write it as <span class="samp">@prefix@</span>.)
|
||
|
|
|
||
|
|
<p>Running <span class="samp">make install</span> with a different value of <code>prefix</code> from
|
||
|
|
the one used to build the program should <em>not</em> recompile the
|
||
|
|
program.
|
||
|
|
|
||
|
|
<br><dt><code>exec_prefix</code><dd><a name="index-exec_005fprefix-120"></a>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 <span class="samp">@exec_prefix@</span>.)
|
||
|
|
|
||
|
|
<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>Running <span class="samp">make install</span> with a different value of <code>exec_prefix</code>
|
||
|
|
from the one used to build the program should <em>not</em> recompile the
|
||
|
|
program.
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<p>Executable programs are installed in one of the following directories.
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<dt><code>bindir</code><dd><a name="index-bindir-121"></a>The directory for installing executable programs that users can run.
|
||
|
|
This should normally be <span class="file">/usr/local/bin</span>, but write it as
|
||
|
|
<span class="file">$(exec_prefix)/bin</span>.
|
||
|
|
(If you are using Autoconf, write it as <span class="samp">@bindir@</span>.)
|
||
|
|
|
||
|
|
<br><dt><code>sbindir</code><dd><a name="index-sbindir-122"></a>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 <span class="file">/usr/local/sbin</span>, but write it as
|
||
|
|
<span class="file">$(exec_prefix)/sbin</span>.
|
||
|
|
(If you are using Autoconf, write it as <span class="samp">@sbindir@</span>.)
|
||
|
|
|
||
|
|
<br><dt><code>libexecdir</code><dd><a name="index-libexecdir-123"></a><!-- This paragraph adjusted to avoid overfull hbox -roland 5jul94 -->
|
||
|
|
The directory for installing executable programs to be run by other
|
||
|
|
programs rather than by users. This directory should normally be
|
||
|
|
<span class="file">/usr/local/libexec</span>, but write it as <span class="file">$(exec_prefix)/libexec</span>.
|
||
|
|
(If you are using Autoconf, write it as <span class="samp">@libexecdir@</span>.)
|
||
|
|
|
||
|
|
<p>The definition of <span class="samp">libexecdir</span> is the same for all packages, so
|
||
|
|
you should install your data in a subdirectory thereof. Most packages
|
||
|
|
install their data under <span class="file">$(libexecdir)/</span><var>package-name</var><span class="file">/</span>,
|
||
|
|
possibly within additional subdirectories thereof, such as
|
||
|
|
<span class="file">$(libexecdir)/</span><var>package-name</var><span class="file">/</span><var>machine</var><span class="file">/</span><var>version</var>.
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<p>Data files used by the program during its execution are divided into
|
||
|
|
categories in two ways.
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>Some files are normally modified by programs; others are never normally
|
||
|
|
modified (though users may edit some of these).
|
||
|
|
|
||
|
|
<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.
|
||
|
|
</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>Here are the variables Makefiles should use to specify directories
|
||
|
|
to put these various kinds of files in:
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<dt><span class="samp">datarootdir</span><dd>The root of the directory tree for read-only architecture-independent
|
||
|
|
data files. This should normally be <span class="file">/usr/local/share</span>, but
|
||
|
|
write it as <span class="file">$(prefix)/share</span>. (If you are using Autoconf, write
|
||
|
|
it as <span class="samp">@datarootdir@</span>.) <span class="samp">datadir</span>'s default value is
|
||
|
|
based on this variable; so are <span class="samp">infodir</span>, <span class="samp">mandir</span>, and
|
||
|
|
others.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">datadir</span><dd>The directory for installing idiosyncratic read-only
|
||
|
|
architecture-independent data files for this program. This is usually
|
||
|
|
the same place as <span class="samp">datarootdir</span>, 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>This should normally be <span class="file">/usr/local/share</span>, but write it as
|
||
|
|
<span class="file">$(datarootdir)</span>. (If you are using Autoconf, write it as
|
||
|
|
<span class="samp">@datadir@</span>.)
|
||
|
|
|
||
|
|
<p>The definition of <span class="samp">datadir</span> is the same for all packages, so you
|
||
|
|
should install your data in a subdirectory thereof. Most packages
|
||
|
|
install their data under <span class="file">$(datadir)/</span><var>package-name</var><span class="file">/</span>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">sysconfdir</span><dd>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, <span class="file">/etc/passwd</span>, and so forth belong
|
||
|
|
here. All the files in this directory should be ordinary ASCII text
|
||
|
|
files. This directory should normally be <span class="file">/usr/local/etc</span>, but
|
||
|
|
write it as <span class="file">$(prefix)/etc</span>.
|
||
|
|
(If you are using Autoconf, write it as <span class="samp">@sysconfdir@</span>.)
|
||
|
|
|
||
|
|
<p>Do not install executables here in this directory (they probably belong
|
||
|
|
in <span class="file">$(libexecdir)</span> or <span class="file">$(sbindir)</span>). 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 <span class="file">$(localstatedir)</span>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">sharedstatedir</span><dd>The directory for installing architecture-independent data files which
|
||
|
|
the programs modify while they run. This should normally be
|
||
|
|
<span class="file">/usr/local/com</span>, but write it as <span class="file">$(prefix)/com</span>.
|
||
|
|
(If you are using Autoconf, write it as <span class="samp">@sharedstatedir@</span>.)
|
||
|
|
|
||
|
|
<br><dt><span class="samp">localstatedir</span><dd>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 <span class="file">$(datadir)</span> or <span class="file">$(sysconfdir)</span>. <span class="file">$(localstatedir)</span>
|
||
|
|
should normally be <span class="file">/usr/local/var</span>, but write it as
|
||
|
|
<span class="file">$(prefix)/var</span>.
|
||
|
|
(If you are using Autoconf, write it as <span class="samp">@localstatedir@</span>.)
|
||
|
|
</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 <span class="samp">infodir</span>, but not all
|
||
|
|
need <span class="samp">libdir</span> or <span class="samp">lispdir</span>.
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<dt><span class="samp">includedir</span><dd><!-- rewritten to avoid overfull hbox -roland -->
|
||
|
|
The directory for installing header files to be included by user
|
||
|
|
programs with the C <span class="samp">#include</span> preprocessor directive. This
|
||
|
|
should normally be <span class="file">/usr/local/include</span>, but write it as
|
||
|
|
<span class="file">$(prefix)/include</span>.
|
||
|
|
(If you are using Autoconf, write it as <span class="samp">@includedir@</span>.)
|
||
|
|
|
||
|
|
<p>Most compilers other than GCC do not look for header files in directory
|
||
|
|
<span class="file">/usr/local/include</span>. 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>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">oldincludedir</span><dd>The directory for installing <span class="samp">#include</span> header files for use with
|
||
|
|
compilers other than GCC. This should normally be <span class="file">/usr/include</span>.
|
||
|
|
(If you are using Autoconf, you can write it as <span class="samp">@oldincludedir@</span>.)
|
||
|
|
|
||
|
|
<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>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 <span class="file">foo.h</span>, then it should install the header
|
||
|
|
file in the <code>oldincludedir</code> directory if either (1) there is no
|
||
|
|
<span class="file">foo.h</span> there or (2) the <span class="file">foo.h</span> that exists came from the Foo
|
||
|
|
package.
|
||
|
|
|
||
|
|
<p>To tell whether <span class="file">foo.h</span> came from the Foo package, put a magic
|
||
|
|
string in the file—part of a comment—and <code>grep</code> for that string.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">docdir</span><dd>The directory for installing documentation files (other than Info) for
|
||
|
|
this package. By default, it should be
|
||
|
|
<span class="file">/usr/local/share/doc/</span><var>yourpkg</var>, but it should be written as
|
||
|
|
<span class="file">$(datarootdir)/doc/</span><var>yourpkg</var>. (If you are using Autoconf,
|
||
|
|
write it as <span class="samp">@docdir@</span>.) The <var>yourpkg</var> subdirectory, which
|
||
|
|
may include a version number, prevents collisions among files with
|
||
|
|
common names, such as <span class="file">README</span>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">infodir</span><dd>The directory for installing the Info files for this package. By
|
||
|
|
default, it should be <span class="file">/usr/local/share/info</span>, but it should be
|
||
|
|
written as <span class="file">$(datarootdir)/info</span>. (If you are using Autoconf,
|
||
|
|
write it as <span class="samp">@infodir@</span>.) <code>infodir</code> is separate from
|
||
|
|
<code>docdir</code> for compatibility with existing practice.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">htmldir</span><dt><span class="samp">dvidir</span><dt><span class="samp">pdfdir</span><dt><span class="samp">psdir</span><dd>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 <span class="samp">@htmldir@</span>,
|
||
|
|
<span class="samp">@dvidir@</span>, etc.) Packages which supply several translations
|
||
|
|
of their documentation should install them in
|
||
|
|
<span class="samp">$(htmldir)/</span><var>ll</var>, <span class="samp">$(pdfdir)/</span><var>ll</var>, etc. where
|
||
|
|
<var>ll</var> is a locale abbreviation such as <span class="samp">en</span> or <span class="samp">pt_BR</span>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">libdir</span><dd>The directory for object files and libraries of object code. Do not
|
||
|
|
install executables here, they probably ought to go in <span class="file">$(libexecdir)</span>
|
||
|
|
instead. The value of <code>libdir</code> should normally be
|
||
|
|
<span class="file">/usr/local/lib</span>, but write it as <span class="file">$(exec_prefix)/lib</span>.
|
||
|
|
(If you are using Autoconf, write it as <span class="samp">@libdir@</span>.)
|
||
|
|
|
||
|
|
<br><dt><span class="samp">lispdir</span><dd>The directory for installing any Emacs Lisp files in this package. By
|
||
|
|
default, it should be <span class="file">/usr/local/share/emacs/site-lisp</span>, but it
|
||
|
|
should be written as <span class="file">$(datarootdir)/emacs/site-lisp</span>.
|
||
|
|
|
||
|
|
<p>If you are using Autoconf, write the default as <span class="samp">@lispdir@</span>.
|
||
|
|
In order to make <span class="samp">@lispdir@</span> work, you need the following lines
|
||
|
|
in your <span class="file">configure.in</span> file:
|
||
|
|
|
||
|
|
<pre class="example"> lispdir='${datarootdir}/emacs/site-lisp'
|
||
|
|
AC_SUBST(lispdir)
|
||
|
|
</pre>
|
||
|
|
<br><dt><span class="samp">localedir</span><dd>The directory for installing locale-specific message catalogs for this
|
||
|
|
package. By default, it should be <span class="file">/usr/local/share/locale</span>, but
|
||
|
|
it should be written as <span class="file">$(datarootdir)/locale</span>. (If you are
|
||
|
|
using Autoconf, write it as <span class="samp">@localedir@</span>.) This directory
|
||
|
|
usually has a subdirectory per locale.
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<p>Unix-style man pages are installed in one of the following:
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<dt><span class="samp">mandir</span><dd>The top-level directory for installing the man pages (if any) for this
|
||
|
|
package. It will normally be <span class="file">/usr/local/share/man</span>, but you
|
||
|
|
should write it as <span class="file">$(datarootdir)/man</span>. (If you are using
|
||
|
|
Autoconf, write it as <span class="samp">@mandir@</span>.)
|
||
|
|
|
||
|
|
<br><dt><span class="samp">man1dir</span><dd>The directory for installing section 1 man pages. Write it as
|
||
|
|
<span class="file">$(mandir)/man1</span>.
|
||
|
|
<br><dt><span class="samp">man2dir</span><dd>The directory for installing section 2 man pages. Write it as
|
||
|
|
<span class="file">$(mandir)/man2</span>
|
||
|
|
<br><dt><span class="samp">...</span><dd>
|
||
|
|
<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>
|
||
|
|
|
||
|
|
<br><dt><span class="samp">manext</span><dd>The file name extension for the installed man page. This should contain
|
||
|
|
a period followed by the appropriate digit; it should normally be <span class="samp">.1</span>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">man1ext</span><dd>The file name extension for installed section 1 man pages.
|
||
|
|
<br><dt><span class="samp">man2ext</span><dd>The file name extension for installed section 2 man pages.
|
||
|
|
<br><dt><span class="samp">...</span><dd>Use these names instead of <span class="samp">manext</span> if the package needs to install man
|
||
|
|
pages in more than one section of the manual.
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<p>And finally, you should set the following variable:
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<dt><span class="samp">srcdir</span><dd>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 <span class="samp">srcdir = @srcdir@</span>.)
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<p>For example:
|
||
|
|
|
||
|
|
<pre class="smallexample"> <!-- I have changed some of the comments here slightly to fix an overfull -->
|
||
|
|
<!-- hbox, so the make manual can format correctly. -roland -->
|
||
|
|
# 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>
|
||
|
|
<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>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>At times, not all of these variables may be implemented in the current
|
||
|
|
release of Autoconf and/or Automake; but as of Autoconf <!-- /@w -->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.
|
||
|
|
|
||
|
|
<div class="node">
|
||
|
|
<p><hr>
|
||
|
|
<a name="Standard-Targets"></a>Next: <a rel="next" accesskey="n" href="#Install-Command-Categories">Install Command Categories</a>,
|
||
|
|
Previous: <a rel="previous" accesskey="p" href="#Directory-Variables">Directory Variables</a>,
|
||
|
|
Up: <a rel="up" accesskey="u" href="#Makefile-Conventions">Makefile Conventions</a>
|
||
|
|
<br>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<h4 class="subsection">7.2.6 Standard Targets for Users</h4>
|
||
|
|
|
||
|
|
<p>All GNU programs should have the following targets in their Makefiles:
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<dt><span class="samp">all</span><dd>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>By default, the Make rules should compile and link with <span class="samp">-g</span>, so
|
||
|
|
that executable programs have debugging symbols. Users who don't mind
|
||
|
|
being helpless can strip the executables later if they wish.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">install</span><dd>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>Do not strip executables when installing them. Devil-may-care users can
|
||
|
|
use the <code>install-strip</code> target to do that.
|
||
|
|
|
||
|
|
<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
|
||
|
|
<span class="samp">make all</span> has just been done. This is convenient for building the
|
||
|
|
program under one user name and installing it under another.
|
||
|
|
|
||
|
|
<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>Use <span class="samp">-</span> 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>The way to install Info files is to copy them into <span class="file">$(infodir)</span>
|
||
|
|
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 <span class="file">dir</span> 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:
|
||
|
|
|
||
|
|
<!-- This example has been carefully formatted for the Make manual. -->
|
||
|
|
<!-- Please do not reformat it without talking to bug-make@gnu.org. -->
|
||
|
|
<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>
|
||
|
|
<p>When writing the <code>install</code> target, you must classify all the
|
||
|
|
commands into three categories: normal ones, <dfn>pre-installation</dfn>
|
||
|
|
commands and <dfn>post-installation</dfn> commands. See <a href="#Install-Command-Categories">Install Command Categories</a>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">install-html</span><dt><span class="samp">install-dvi</span><dt><span class="samp">install-pdf</span><dt><span class="samp">install-ps</span><dd>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>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>Please make these <code>install-</code><var>format</var> targets invoke the
|
||
|
|
commands for the <var>format</var> target, for example, by making
|
||
|
|
<var>format</var> a dependency.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">uninstall</span><dd>Delete all the installed files—the copies that the <span class="samp">install</span>
|
||
|
|
and <span class="samp">install-*</span> targets create.
|
||
|
|
|
||
|
|
<p>This rule should not modify the directories where compilation is done,
|
||
|
|
only the directories where files are installed.
|
||
|
|
|
||
|
|
<p>The uninstallation commands are divided into three categories, just like
|
||
|
|
the installation commands. See <a href="#Install-Command-Categories">Install Command Categories</a>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">install-strip</span><dd>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:
|
||
|
|
|
||
|
|
<pre class="smallexample"> install-strip:
|
||
|
|
$(MAKE) INSTALL_PROGRAM='$(INSTALL_PROGRAM) -s' \
|
||
|
|
install
|
||
|
|
</pre>
|
||
|
|
<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><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>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.
|
||
|
|
|
||
|
|
<!-- The gratuitous blank line here is to make the table look better -->
|
||
|
|
<!-- in the printed Make manual. Please leave it in. -->
|
||
|
|
<br><dt><span class="samp">clean</span><dd>
|
||
|
|
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 <span class="samp">mkdir -p</span>, since they could have existed anyway.
|
||
|
|
|
||
|
|
<p>Delete <span class="file">.dvi</span> files here if they are not part of the distribution.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">distclean</span><dd>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, <span class="samp">make distclean</span> should leave only the files
|
||
|
|
that were in the distribution. However, there is no need to delete
|
||
|
|
parent directories that were created with <span class="samp">mkdir -p</span>, since they
|
||
|
|
could have existed anyway.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">mostlyclean</span><dd>Like <span class="samp">clean</span>, but may refrain from deleting a few files that people
|
||
|
|
normally don't want to recompile. For example, the <span class="samp">mostlyclean</span>
|
||
|
|
target for GCC does not delete <span class="file">libgcc.a</span>, because recompiling it
|
||
|
|
is rarely necessary and takes a lot of time.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">maintainer-clean</span><dd>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>The reason we say “almost everything” is that running the command
|
||
|
|
<span class="samp">make maintainer-clean</span> should not delete <span class="file">configure</span> even
|
||
|
|
if <span class="file">configure</span> can be remade using a rule in the Makefile. More
|
||
|
|
generally, <span class="samp">make maintainer-clean</span> should not delete anything
|
||
|
|
that needs to exist in order to run <span class="file">configure</span> and then begin to
|
||
|
|
build the program. Also, there is no need to delete parent
|
||
|
|
directories that were created with <span class="samp">mkdir -p</span>, since they could
|
||
|
|
have existed anyway. These are the only exceptions;
|
||
|
|
<code>maintainer-clean</code> should delete everything else that can be
|
||
|
|
rebuilt.
|
||
|
|
|
||
|
|
<p>The <span class="samp">maintainer-clean</span> 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 <span class="samp">make maintainer-clean</span> 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>To help make users aware of this, the commands for the special
|
||
|
|
<code>maintainer-clean</code> target should start with these two:
|
||
|
|
|
||
|
|
<pre class="smallexample"> @echo 'This command is intended for maintainers to use; it'
|
||
|
|
@echo 'deletes files that may need special tools to rebuild.'
|
||
|
|
</pre>
|
||
|
|
<br><dt><span class="samp">TAGS</span><dd>Update a tags table for this program.
|
||
|
|
<!-- ADR: how? -->
|
||
|
|
|
||
|
|
<br><dt><span class="samp">info</span><dd>Generate any Info files needed. The best way to write the rules is as
|
||
|
|
follows:
|
||
|
|
|
||
|
|
<pre class="smallexample"> info: foo.info
|
||
|
|
|
||
|
|
foo.info: foo.texi chap1.texi chap2.texi
|
||
|
|
$(MAKEINFO) $(srcdir)/foo.texi
|
||
|
|
</pre>
|
||
|
|
<p class="noindent">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>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.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">dvi</span><dt><span class="samp">html</span><dt><span class="samp">pdf</span><dt><span class="samp">ps</span><dd>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>Here's an example rule for generating DVI files from Texinfo:
|
||
|
|
|
||
|
|
<pre class="smallexample"> dvi: foo.dvi
|
||
|
|
|
||
|
|
foo.dvi: foo.texi chap1.texi chap2.texi
|
||
|
|
$(TEXI2DVI) $(srcdir)/foo.texi
|
||
|
|
</pre>
|
||
|
|
<p class="noindent">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 rel="footnote" href="#fn-1" name="fnd-1"><sup>1</sup></a> Alternatively,
|
||
|
|
write just the dependencies, and allow GNU <code>make</code> to provide the command.
|
||
|
|
|
||
|
|
<p>Here's another example, this one for generating HTML from Texinfo:
|
||
|
|
|
||
|
|
<pre class="smallexample"> html: foo.html
|
||
|
|
|
||
|
|
foo.html: foo.texi chap1.texi chap2.texi
|
||
|
|
$(TEXI2HTML) $(srcdir)/foo.texi
|
||
|
|
</pre>
|
||
|
|
<p class="noindent">Again, you would define the variable <code>TEXI2HTML</code> in the Makefile;
|
||
|
|
for example, it might run <code>makeinfo --no-split --html</code>
|
||
|
|
(<span class="command">makeinfo</span> is part of the Texinfo distribution).
|
||
|
|
|
||
|
|
<br><dt><span class="samp">dist</span><dd>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>For example, the distribution tar file of GCC version 1.40 unpacks into
|
||
|
|
a subdirectory named <span class="file">gcc-1.40</span>.
|
||
|
|
|
||
|
|
<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>Compress the tar file with <code>gzip</code>. For example, the actual
|
||
|
|
distribution file for GCC version 1.40 is called <span class="file">gcc-1.40.tar.gz</span>.
|
||
|
|
|
||
|
|
<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>.
|
||
|
|
|
||
|
|
<br><dt><span class="samp">check</span><dd>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.
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<p>The following targets are suggested as conventional names, for programs
|
||
|
|
in which they are useful.
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<dt><code>installcheck</code><dd>Perform installation tests (if any). The user must build and install
|
||
|
|
the program before running the tests. You should not assume that
|
||
|
|
<span class="file">$(bindir)</span> is in the search path.
|
||
|
|
|
||
|
|
<br><dt><code>installdirs</code><dd>It's useful to add a target named <span class="samp">installdirs</span> to create the
|
||
|
|
directories where files are installed, and their parent directories.
|
||
|
|
There is a script called <span class="file">mkinstalldirs</span> which is convenient for
|
||
|
|
this; you can find it in the Texinfo package.
|
||
|
|
<!-- It's in /gd/gnu/lib/mkinstalldirs. -->
|
||
|
|
You can use a rule like this:
|
||
|
|
|
||
|
|
<!-- This has been carefully formatted to look decent in the Make manual. -->
|
||
|
|
<!-- Please be sure not to make it extend any further to the right.-roland -->
|
||
|
|
<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>
|
||
|
|
<p class="noindent">or, if you wish to support <span class="env">DESTDIR</span>,
|
||
|
|
|
||
|
|
<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>
|
||
|
|
<p>This rule should not modify the directories where compilation is done.
|
||
|
|
It should do nothing but create installation directories.
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<div class="node">
|
||
|
|
<p><hr>
|
||
|
|
<a name="Install-Command-Categories"></a>Previous: <a rel="previous" accesskey="p" href="#Standard-Targets">Standard Targets</a>,
|
||
|
|
Up: <a rel="up" accesskey="u" href="#Makefile-Conventions">Makefile Conventions</a>
|
||
|
|
<br>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<h4 class="subsection">7.2.7 Install Command Categories</h4>
|
||
|
|
|
||
|
|
<p><a name="index-pre_002dinstallation-commands-124"></a><a name="index-post_002dinstallation-commands-125"></a>When writing the <code>install</code> target, you must classify all the
|
||
|
|
commands into three categories: normal ones, <dfn>pre-installation</dfn>
|
||
|
|
commands and <dfn>post-installation</dfn> commands.
|
||
|
|
|
||
|
|
<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>Pre-installation and post-installation commands may alter other files;
|
||
|
|
in particular, they can edit global configuration files or data bases.
|
||
|
|
|
||
|
|
<p>Pre-installation commands are typically executed before the normal
|
||
|
|
commands, and post-installation commands are typically run after the
|
||
|
|
normal commands.
|
||
|
|
|
||
|
|
<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>Most programs don't need any pre-installation commands, but we have the
|
||
|
|
feature just in case it is needed.
|
||
|
|
|
||
|
|
<p>To classify the commands in the <code>install</code> rule into these three
|
||
|
|
categories, insert <dfn>category lines</dfn> among them. A category line
|
||
|
|
specifies the category for the commands that follow.
|
||
|
|
|
||
|
|
<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>Here are the three possible category lines, each with a comment that
|
||
|
|
explains what it means:
|
||
|
|
|
||
|
|
<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>
|
||
|
|
<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>These are the category lines for <code>uninstall</code>:
|
||
|
|
|
||
|
|
<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>
|
||
|
|
<p>Typically, a pre-uninstall command would be used for deleting entries
|
||
|
|
from the Info directory.
|
||
|
|
|
||
|
|
<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>Pre-installation and post-installation commands should not run any
|
||
|
|
programs except for these:
|
||
|
|
|
||
|
|
<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>
|
||
|
|
<p><a name="index-binary-packages-126"></a>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>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 <span class="option">-s</span> option to
|
||
|
|
<span class="command">make</span> is needed to silence messages about entering
|
||
|
|
subdirectories):
|
||
|
|
|
||
|
|
<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>
|
||
|
|
<p class="noindent">where the file <span class="file">pre-install.awk</span> could contain this:
|
||
|
|
|
||
|
|
<pre class="smallexample"> $0 ~ /^(normal-install|post-install)[ \t]*$/ {on = 0}
|
||
|
|
on {print $0}
|
||
|
|
$0 ~ /^pre-install[ \t]*$/ {on = 1}
|
||
|
|
</pre>
|
||
|
|
<div class="node">
|
||
|
|
<p><hr>
|
||
|
|
<a name="Releases"></a>Previous: <a rel="previous" accesskey="p" href="#Makefile-Conventions">Makefile Conventions</a>,
|
||
|
|
Up: <a rel="up" accesskey="u" href="#Managing-Releases">Managing Releases</a>
|
||
|
|
<br>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<h3 class="section">7.3 Making Releases</h3>
|
||
|
|
|
||
|
|
<p><a name="index-packaging-127"></a>
|
||
|
|
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>Package the distribution of <code>Foo version 69.96</code> up in a gzipped tar
|
||
|
|
file with the name <span class="file">foo-69.96.tar.gz</span>. It should unpack into a
|
||
|
|
subdirectory named <span class="file">foo-69.96</span>.
|
||
|
|
|
||
|
|
<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 <dfn>source
|
||
|
|
files</dfn> and <dfn>non-source files</dfn>. 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-_0040file_007bREADME_007d-file-128"></a>The distribution should contain a file named <span class="file">README</span> 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 <span class="file">README</span> file
|
||
|
|
should either state the version number of the package, or refer to where
|
||
|
|
in the package it can be found.
|
||
|
|
|
||
|
|
<p>The <span class="file">README</span> file should refer to the file <span class="file">INSTALL</span>, which
|
||
|
|
should contain an explanation of the installation procedure.
|
||
|
|
|
||
|
|
<p>The <span class="file">README</span> file should also refer to the file which contains the
|
||
|
|
copying conditions. The GNU GPL, if used, should be in a file called
|
||
|
|
<span class="file">COPYING</span>. If the GNU LGPL is used, it should be in a file called
|
||
|
|
<span class="file">COPYING.LIB</span>.
|
||
|
|
|
||
|
|
<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>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>Make sure that the directory into which the distribution unpacks (as
|
||
|
|
well as any subdirectories) are all world-writable (octal mode 777).
|
||
|
|
This is so that old versions of <code>tar</code> which preserve the
|
||
|
|
ownership and permissions of the files from the tar archive will be
|
||
|
|
able to extract all the files even if the user is unprivileged.
|
||
|
|
|
||
|
|
<p>Make sure that all the files in the distribution are world-readable.
|
||
|
|
|
||
|
|
<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>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,
|
||
|
|
<span class="file">foobarhacker.c</span> and <span class="file">foobarhacker.o</span> are not ambiguous; they
|
||
|
|
are truncated to <span class="file">foobarha.c</span> and <span class="file">foobarha.o</span>, which are
|
||
|
|
distinct.
|
||
|
|
|
||
|
|
<p><a name="index-_0040file_007btexinfo_002etex_007d_002c-in-a-distribution-129"></a>Include in your distribution a copy of the <span class="file">texinfo.tex</span> you used
|
||
|
|
to test print any <span class="file">*.texinfo</span> or <span class="file">*.texi</span> files.
|
||
|
|
|
||
|
|
<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.
|
||
|
|
|
||
|
|
<div class="node">
|
||
|
|
<p><hr>
|
||
|
|
<a name="References"></a>Next: <a rel="next" accesskey="n" href="#GNU-Free-Documentation-License">GNU Free Documentation License</a>,
|
||
|
|
Previous: <a rel="previous" accesskey="p" href="#Managing-Releases">Managing Releases</a>,
|
||
|
|
Up: <a rel="up" accesskey="u" href="#Top">Top</a>
|
||
|
|
<br>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<h2 class="chapter">8 References to Non-Free Software and Documentation</h2>
|
||
|
|
|
||
|
|
<p><a name="index-references-to-non_002dfree-material-130"></a>
|
||
|
|
A GNU program should not recommend use of any non-free program. 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. Proprietary software is a
|
||
|
|
social and ethical problem, and the point of GNU is to solve that
|
||
|
|
problem.
|
||
|
|
|
||
|
|
<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>. 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>. The terms
|
||
|
|
“free” and “non-free”, used in this document, refer to that
|
||
|
|
definition. If it is not clear whether a license qualifies as free
|
||
|
|
under this definition, 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>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>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 to lead them to take an interest in it.
|
||
|
|
|
||
|
|
<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 among
|
||
|
|
the users of Foobar if the users of Foobar are few.)
|
||
|
|
|
||
|
|
<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 the parts of Sun's Java implementation which are not yet
|
||
|
|
free software, and won't run on the GNU Java Compiler (which does not
|
||
|
|
yet have all the features) or won't run with the GNU Java libraries.
|
||
|
|
We hope this particular problem will be gone in a few months, when Sun
|
||
|
|
makes the standard Java libraries free software, but of course the
|
||
|
|
general principle remains: you should not recommend programs that
|
||
|
|
depend on non-free software to run.
|
||
|
|
|
||
|
|
<p>Some free programs encourage the use of non-free software. A typical
|
||
|
|
example is <span class="command">mplayer</span>. It is free software in itself, and the
|
||
|
|
free code can handle some kinds of files. However, <span class="command">mplayer</span>
|
||
|
|
recommends use of non-free codecs for other kinds of files, and users
|
||
|
|
that install <span class="command">mplayer</span> are very likely to install those codecs
|
||
|
|
along with it. To recommend <span class="command">mplayer</span> is, in effect, to
|
||
|
|
recommend the non-free codecs. We must not do that, so we cannot
|
||
|
|
recommend <span class="command">mplayer</span> either.
|
||
|
|
|
||
|
|
<p>In general, you should also not recommend programs that themselves
|
||
|
|
strongly recommend the use of non-free software.
|
||
|
|
|
||
|
|
<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 it is a major focus of the GNU Project; to
|
||
|
|
recommend use of documentation that we are not allowed to use in GNU
|
||
|
|
would weaken the impetus for the community to produce documentation
|
||
|
|
that we can include. So GNU packages should never recommend non-free
|
||
|
|
documentation.
|
||
|
|
|
||
|
|
<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 be non-free. This is because we don't include such things
|
||
|
|
in the GNU system even if we are allowed to—they are outside the
|
||
|
|
scope of an operating system project.
|
||
|
|
|
||
|
|
<p>Referring to a web site that describes or recommends a non-free
|
||
|
|
program is in effect promoting that software, 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>Following links from nearly any web site can lead to non-free
|
||
|
|
software; this is an inescapable aspect of the nature of the web, and
|
||
|
|
in itself is no objection to linking to a site. As long as the site
|
||
|
|
does not itself recommend a non-free program, there is no need be
|
||
|
|
concerned about the sites it links to for other reasons.
|
||
|
|
|
||
|
|
<p>Thus, for example, you should not make a link to AT&T's web site,
|
||
|
|
because that recommends AT&T's non-free software packages; you should
|
||
|
|
not make a link to a site that links to AT&T's site saying it is a
|
||
|
|
place to get a non-free program; but if a site you want to link to
|
||
|
|
refers to AT&T's web site in some other context (such as long-distance
|
||
|
|
telephone service), that is not a problem.
|
||
|
|
|
||
|
|
<div class="node">
|
||
|
|
<p><hr>
|
||
|
|
<a name="GNU-Free-Documentation-License"></a>Next: <a rel="next" accesskey="n" href="#Index">Index</a>,
|
||
|
|
Previous: <a rel="previous" accesskey="p" href="#References">References</a>,
|
||
|
|
Up: <a rel="up" accesskey="u" href="#Top">Top</a>
|
||
|
|
<br>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<h2 class="appendix">Appendix A GNU Free Documentation License</h2>
|
||
|
|
|
||
|
|
<p><a name="index-FDL_002c-GNU-Free-Documentation-License-131"></a>
|
||
|
|
|
||
|
|
<!-- The GNU Free Documentation License. -->
|
||
|
|
<div align="center">Version 1.2, November 2002</div>
|
||
|
|
|
||
|
|
<!-- This file is intended to be included within another document, -->
|
||
|
|
<!-- hence no sectioning command or @node. -->
|
||
|
|
<pre class="display"> Copyright © 2000,2001,2002 Free Software Foundation, Inc.
|
||
|
|
51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA
|
||
|
|
|
||
|
|
Everyone is permitted to copy and distribute verbatim copies
|
||
|
|
of this license document, but changing it is not allowed.
|
||
|
|
</pre>
|
||
|
|
<ol type=1 start=0>
|
||
|
|
<li>PREAMBLE
|
||
|
|
|
||
|
|
<p>The purpose of this License is to make a manual, textbook, or other
|
||
|
|
functional and useful document <dfn>free</dfn> 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>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>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.
|
||
|
|
|
||
|
|
<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>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>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>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>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>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>Examples of suitable formats for Transparent copies include plain
|
||
|
|
<span class="sc">ascii</span> 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>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>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>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.
|
||
|
|
|
||
|
|
<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>You may also lend copies, under the same conditions stated above, and
|
||
|
|
you may publicly display copies.
|
||
|
|
|
||
|
|
<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>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>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>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.
|
||
|
|
|
||
|
|
<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:
|
||
|
|
|
||
|
|
<ol type=A start=1>
|
||
|
|
<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>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>State on the Title page the name of the publisher of the
|
||
|
|
Modified Version, as the publisher.
|
||
|
|
|
||
|
|
<li>Preserve all the copyright notices of the Document.
|
||
|
|
|
||
|
|
<li>Add an appropriate copyright notice for your modifications
|
||
|
|
adjacent to the other copyright notices.
|
||
|
|
|
||
|
|
<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>Preserve in that license notice the full lists of Invariant Sections
|
||
|
|
and required Cover Texts given in the Document's license notice.
|
||
|
|
|
||
|
|
<li>Include an unaltered copy of this License.
|
||
|
|
|
||
|
|
<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>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>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>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>Delete any section Entitled “Endorsements”. Such a section
|
||
|
|
may not be included in the Modified Version.
|
||
|
|
|
||
|
|
<li>Do not retitle any existing section to be Entitled “Endorsements” or
|
||
|
|
to conflict in title with any Invariant Section.
|
||
|
|
|
||
|
|
<li>Preserve any Warranty Disclaimers.
|
||
|
|
</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>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>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>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.
|
||
|
|
|
||
|
|
<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>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>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.”
|
||
|
|
|
||
|
|
<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>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.
|
||
|
|
|
||
|
|
<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>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.
|
||
|
|
|
||
|
|
<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>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.
|
||
|
|
|
||
|
|
<li>TERMINATION
|
||
|
|
|
||
|
|
<p>You may not copy, modify, sublicense, or distribute the Document except
|
||
|
|
as expressly provided for under this License. Any other attempt to
|
||
|
|
copy, modify, sublicense or distribute the Document is void, and will
|
||
|
|
automatically terminate your rights under this License. However,
|
||
|
|
parties who have received copies, or rights, from you under this
|
||
|
|
License will not have their licenses terminated so long as such
|
||
|
|
parties remain in full compliance.
|
||
|
|
|
||
|
|
<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>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.
|
||
|
|
</ol>
|
||
|
|
|
||
|
|
<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:
|
||
|
|
|
||
|
|
<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.2
|
||
|
|
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>
|
||
|
|
<p>If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
|
||
|
|
replace the “with<small class="dots">...</small>Texts.” line with this:
|
||
|
|
|
||
|
|
<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>
|
||
|
|
<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>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.
|
||
|
|
|
||
|
|
<!-- Local Variables: -->
|
||
|
|
<!-- ispell-local-pdict: "ispell-dict" -->
|
||
|
|
<!-- End: -->
|
||
|
|
<div class="node">
|
||
|
|
<p><hr>
|
||
|
|
<a name="Index"></a>Previous: <a rel="previous" accesskey="p" href="#GNU-Free-Documentation-License">GNU Free Documentation License</a>,
|
||
|
|
Up: <a rel="up" accesskey="u" href="#Top">Top</a>
|
||
|
|
<br>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<h2 class="unnumbered">Index</h2>
|
||
|
|
|
||
|
|
<ul class="index-cp" compact>
|
||
|
|
<li><a href="#index-_0040code_007b_0023endif_007d_002c-commenting-65"><code>#endif</code>, commenting</a>: <a href="#Comments">Comments</a></li>
|
||
|
|
<li><a href="#index-_0040samp_007b_002d_002dhelp_007d-output-49"><span class="samp">--help</span> output</a>: <a href="#_002d_002dhelp">--help</a></li>
|
||
|
|
<li><a href="#index-_0040samp_007b_002d_002dversion_007d-output-46"><span class="samp">--version</span> output</a>: <a href="#_002d_002dversion">--version</a></li>
|
||
|
|
<li><a href="#index-_0040samp_007b_002dWall_007d-compiler-option-70"><span class="samp">-Wall</span> compiler option</a>: <a href="#Syntactic-Conventions">Syntactic Conventions</a></li>
|
||
|
|
<li><a href="#index-accepting-contributions-7">accepting contributions</a>: <a href="#Contributions">Contributions</a></li>
|
||
|
|
<li><a href="#index-address-for-bug-reports-50">address for bug reports</a>: <a href="#_002d_002dhelp">--help</a></li>
|
||
|
|
<li><a href="#index-_0040sc_007bansi_007d-C-standard-17"><span class="sc">ansi</span> C standard</a>: <a href="#Standard-C">Standard C</a></li>
|
||
|
|
<li><a href="#index-arbitrary-limits-on-data-19">arbitrary limits on data</a>: <a href="#Semantics">Semantics</a></li>
|
||
|
|
<li><a href="#index-ASCII-characters-92">ASCII characters</a>: <a href="#Character-Set">Character Set</a></li>
|
||
|
|
<li><a href="#index-autoconf-78"><code>autoconf</code></a>: <a href="#System-Portability">System Portability</a></li>
|
||
|
|
<li><a href="#index-avoiding-proprietary-code-5">avoiding proprietary code</a>: <a href="#Reading-Non_002dFree-Code">Reading Non-Free Code</a></li>
|
||
|
|
<li><a href="#index-behavior_002c-dependent-on-program_0027s-name-33">behavior, dependent on program's name</a>: <a href="#User-Interfaces">User Interfaces</a></li>
|
||
|
|
<li><a href="#index-binary-packages-126">binary packages</a>: <a href="#Install-Command-Categories">Install Command Categories</a></li>
|
||
|
|
<li><a href="#index-bindir-121"><code>bindir</code></a>: <a href="#Directory-Variables">Directory Variables</a></li>
|
||
|
|
<li><a href="#index-braces_002c-in-C-source-58">braces, in C source</a>: <a href="#Formatting">Formatting</a></li>
|
||
|
|
<li><a href="#index-bug-reports-51">bug reports</a>: <a href="#_002d_002dhelp">--help</a></li>
|
||
|
|
<li><a href="#index-canonical-name-of-a-program-47">canonical name of a program</a>: <a href="#_002d_002dversion">--version</a></li>
|
||
|
|
<li><a href="#index-casting-pointers-to-integers-82">casting pointers to integers</a>: <a href="#CPU-Portability">CPU Portability</a></li>
|
||
|
|
<li><a href="#index-CGI-programs_002c-standard-options-for-44">CGI programs, standard options for</a>: <a href="#Command_002dLine-Interfaces">Command-Line Interfaces</a></li>
|
||
|
|
<li><a href="#index-change-logs-104">change logs</a>: <a href="#Change-Logs">Change Logs</a></li>
|
||
|
|
<li><a href="#index-change-logs_002c-conditional-changes-107">change logs, conditional changes</a>: <a href="#Conditional-Changes">Conditional Changes</a></li>
|
||
|
|
<li><a href="#index-change-logs_002c-style-105">change logs, style</a>: <a href="#Style-of-Change-Logs">Style of Change Logs</a></li>
|
||
|
|
<li><a href="#index-character-set-90">character set</a>: <a href="#Character-Set">Character Set</a></li>
|
||
|
|
<li><a href="#index-command_002dline-arguments_002c-decoding-24">command-line arguments, decoding</a>: <a href="#Semantics">Semantics</a></li>
|
||
|
|
<li><a href="#index-command_002dline-interface-39">command-line interface</a>: <a href="#Command_002dLine-Interfaces">Command-Line Interfaces</a></li>
|
||
|
|
<li><a href="#index-commenting-63">commenting</a>: <a href="#Comments">Comments</a></li>
|
||
|
|
<li><a href="#index-compatibility-with-C-and-_0040sc_007bposix_007d-standards-12">compatibility with C and <span class="sc">posix</span> standards</a>: <a href="#Compatibility">Compatibility</a></li>
|
||
|
|
<li><a href="#index-compiler-warnings-69">compiler warnings</a>: <a href="#Syntactic-Conventions">Syntactic Conventions</a></li>
|
||
|
|
<li><a href="#index-conditional-changes_002c-and-change-logs-106">conditional changes, and change logs</a>: <a href="#Conditional-Changes">Conditional Changes</a></li>
|
||
|
|
<li><a href="#index-conditionals_002c-comments-for-64">conditionals, comments for</a>: <a href="#Comments">Comments</a></li>
|
||
|
|
<li><a href="#index-configure-111"><code>configure</code></a>: <a href="#Configuration">Configuration</a></li>
|
||
|
|
<li><a href="#index-control_002dL-62">control-L</a>: <a href="#Formatting">Formatting</a></li>
|
||
|
|
<li><a href="#index-conventions-for-makefiles-114">conventions for makefiles</a>: <a href="#Makefile-Conventions">Makefile Conventions</a></li>
|
||
|
|
<li><a href="#index-corba-37">corba</a>: <a href="#Graphical-Interfaces">Graphical Interfaces</a></li>
|
||
|
|
<li><a href="#index-credits-for-manuals-102">credits for manuals</a>: <a href="#Manual-Credits">Manual Credits</a></li>
|
||
|
|
<li><a href="#index-data-types_002c-and-portability-80">data types, and portability</a>: <a href="#CPU-Portability">CPU Portability</a></li>
|
||
|
|
<li><a href="#index-declaration-for-system-functions-85">declaration for system functions</a>: <a href="#System-Functions">System Functions</a></li>
|
||
|
|
<li><a href="#index-DESTDIR-116"><code>DESTDIR</code></a>: <a href="#DESTDIR">DESTDIR</a></li>
|
||
|
|
<li><a href="#index-documentation-99">documentation</a>: <a href="#Documentation">Documentation</a></li>
|
||
|
|
<li><a href="#index-doschk-76"><code>doschk</code></a>: <a href="#Names">Names</a></li>
|
||
|
|
<li><a href="#index-downloading-this-manual-2">downloading this manual</a>: <a href="#Preface">Preface</a></li>
|
||
|
|
<li><a href="#index-encodings-91">encodings</a>: <a href="#Character-Set">Character Set</a></li>
|
||
|
|
<li><a href="#index-error-messages-21">error messages</a>: <a href="#Semantics">Semantics</a></li>
|
||
|
|
<li><a href="#index-error-messages_002c-formatting-31">error messages, formatting</a>: <a href="#Errors">Errors</a></li>
|
||
|
|
<li><a href="#index-exec_005fprefix-120"><code>exec_prefix</code></a>: <a href="#Directory-Variables">Directory Variables</a></li>
|
||
|
|
<li><a href="#index-expressions_002c-splitting-60">expressions, splitting</a>: <a href="#Formatting">Formatting</a></li>
|
||
|
|
<li><a href="#index-FDL_002c-GNU-Free-Documentation-License-131">FDL, GNU Free Documentation License</a>: <a href="#GNU-Free-Documentation-License">GNU Free Documentation License</a></li>
|
||
|
|
<li><a href="#index-file-usage-55">file usage</a>: <a href="#File-Usage">File Usage</a></li>
|
||
|
|
<li><a href="#index-file_002dname-limitations-75">file-name limitations</a>: <a href="#Names">Names</a></li>
|
||
|
|
<li><a href="#index-formatting-error-messages-30">formatting error messages</a>: <a href="#Errors">Errors</a></li>
|
||
|
|
<li><a href="#index-formatting-source-code-56">formatting source code</a>: <a href="#Formatting">Formatting</a></li>
|
||
|
|
<li><a href="#index-formfeed-61">formfeed</a>: <a href="#Formatting">Formatting</a></li>
|
||
|
|
<li><a href="#index-function-argument_002c-declaring-68">function argument, declaring</a>: <a href="#Syntactic-Conventions">Syntactic Conventions</a></li>
|
||
|
|
<li><a href="#index-function-prototypes-18">function prototypes</a>: <a href="#Standard-C">Standard C</a></li>
|
||
|
|
<li><a href="#index-getopt-40"><code>getopt</code></a>: <a href="#Command_002dLine-Interfaces">Command-Line Interfaces</a></li>
|
||
|
|
<li><a href="#index-gettext-88"><code>gettext</code></a>: <a href="#Internationalization">Internationalization</a></li>
|
||
|
|
<li><a href="#index-gnome-38">gnome</a>: <a href="#Graphical-Interfaces">Graphical Interfaces</a></li>
|
||
|
|
<li><a href="#index-graphical-user-interface-35">graphical user interface</a>: <a href="#Graphical-Interfaces">Graphical Interfaces</a></li>
|
||
|
|
<li><a href="#index-grave-accent-97">grave accent</a>: <a href="#Quote-Characters">Quote Characters</a></li>
|
||
|
|
<li><a href="#index-gtk_002b-36">gtk+</a>: <a href="#Graphical-Interfaces">Graphical Interfaces</a></li>
|
||
|
|
<li><a href="#index-GUILE-11">GUILE</a>: <a href="#Source-Language">Source Language</a></li>
|
||
|
|
<li><a href="#index-implicit-_0040code_007bint_007d-67">implicit <code>int</code></a>: <a href="#Syntactic-Conventions">Syntactic Conventions</a></li>
|
||
|
|
<li><a href="#index-impossible-conditions-26">impossible conditions</a>: <a href="#Semantics">Semantics</a></li>
|
||
|
|
<li><a href="#index-installations_002c-staged-118">installations, staged</a>: <a href="#DESTDIR">DESTDIR</a></li>
|
||
|
|
<li><a href="#index-internationalization-87">internationalization</a>: <a href="#Internationalization">Internationalization</a></li>
|
||
|
|
<li><a href="#index-left-quote-96">left quote</a>: <a href="#Quote-Characters">Quote Characters</a></li>
|
||
|
|
<li><a href="#index-legal-aspects-3">legal aspects</a>: <a href="#Legal-Issues">Legal Issues</a></li>
|
||
|
|
<li><a href="#index-legal-papers-6">legal papers</a>: <a href="#Contributions">Contributions</a></li>
|
||
|
|
<li><a href="#index-libexecdir-123"><code>libexecdir</code></a>: <a href="#Directory-Variables">Directory Variables</a></li>
|
||
|
|
<li><a href="#index-libraries-29">libraries</a>: <a href="#Libraries">Libraries</a></li>
|
||
|
|
<li><a href="#index-library-functions_002c-and-portability-83">library functions, and portability</a>: <a href="#System-Functions">System Functions</a></li>
|
||
|
|
<li><a href="#index-license-for-manuals-101">license for manuals</a>: <a href="#License-for-Manuals">License for Manuals</a></li>
|
||
|
|
<li><a href="#index-lint-73"><code>lint</code></a>: <a href="#Syntactic-Conventions">Syntactic Conventions</a></li>
|
||
|
|
<li><a href="#index-locale_002dspecific-quote-characters-95">locale-specific quote characters</a>: <a href="#Quote-Characters">Quote Characters</a></li>
|
||
|
|
<li><a href="#index-long-option-names-52">long option names</a>: <a href="#Option-Table">Option Table</a></li>
|
||
|
|
<li><a href="#index-long_002dnamed-options-41">long-named options</a>: <a href="#Command_002dLine-Interfaces">Command-Line Interfaces</a></li>
|
||
|
|
<li><a href="#index-makefile_002c-conventions-for-113">makefile, conventions for</a>: <a href="#Makefile-Conventions">Makefile Conventions</a></li>
|
||
|
|
<li><a href="#index-_0040code_007bmalloc_007d-return-value-22"><code>malloc</code> return value</a>: <a href="#Semantics">Semantics</a></li>
|
||
|
|
<li><a href="#index-man-pages-108">man pages</a>: <a href="#Man-Pages">Man Pages</a></li>
|
||
|
|
<li><a href="#index-manual-structure-100">manual structure</a>: <a href="#Manual-Structure-Details">Manual Structure Details</a></li>
|
||
|
|
<li><a href="#index-memory-allocation-failure-23">memory allocation failure</a>: <a href="#Semantics">Semantics</a></li>
|
||
|
|
<li><a href="#index-memory-usage-54">memory usage</a>: <a href="#Memory-Usage">Memory Usage</a></li>
|
||
|
|
<li><a href="#index-message-text_002c-and-internationalization-89">message text, and internationalization</a>: <a href="#Internationalization">Internationalization</a></li>
|
||
|
|
<li><a href="#index-mmap-98"><code>mmap</code></a>: <a href="#Mmap">Mmap</a></li>
|
||
|
|
<li><a href="#index-multiple-variables-in-a-line-72">multiple variables in a line</a>: <a href="#Syntactic-Conventions">Syntactic Conventions</a></li>
|
||
|
|
<li><a href="#index-names-of-variables_002c-functions_002c-and-files-74">names of variables, functions, and files</a>: <a href="#Names">Names</a></li>
|
||
|
|
<li><a href="#index-_0040file_007bNEWS_007d-file-103"><span class="file">NEWS</span> file</a>: <a href="#NEWS-File">NEWS File</a></li>
|
||
|
|
<li><a href="#index-non_002dASCII-characters-93">non-ASCII characters</a>: <a href="#Character-Set">Character Set</a></li>
|
||
|
|
<li><a href="#index-non_002d_0040sc_007bposix_007d-systems_002c-and-portability-79">non-<span class="sc">posix</span> systems, and portability</a>: <a href="#System-Portability">System Portability</a></li>
|
||
|
|
<li><a href="#index-non_002dstandard-extensions-16">non-standard extensions</a>: <a href="#Using-Extensions">Using Extensions</a></li>
|
||
|
|
<li><a href="#index-_0040code_007bNUL_007d-characters-20"><code>NUL</code> characters</a>: <a href="#Semantics">Semantics</a></li>
|
||
|
|
<li><a href="#index-open-brace-57">open brace</a>: <a href="#Formatting">Formatting</a></li>
|
||
|
|
<li><a href="#index-optional-features_002c-configure_002dtime-112">optional features, configure-time</a>: <a href="#Configuration">Configuration</a></li>
|
||
|
|
<li><a href="#index-options-for-compatibility-14">options for compatibility</a>: <a href="#Compatibility">Compatibility</a></li>
|
||
|
|
<li><a href="#index-options_002c-standard-command_002dline-43">options, standard command-line</a>: <a href="#Command_002dLine-Interfaces">Command-Line Interfaces</a></li>
|
||
|
|
<li><a href="#index-output-device-and-program_0027s-behavior-34">output device and program's behavior</a>: <a href="#User-Interfaces">User Interfaces</a></li>
|
||
|
|
<li><a href="#index-packaging-127">packaging</a>: <a href="#Releases">Releases</a></li>
|
||
|
|
<li><a href="#index-PATH_005fINFO_002c-specifying-standard-options-as-45">PATH_INFO, specifying standard options as</a>: <a href="#Command_002dLine-Interfaces">Command-Line Interfaces</a></li>
|
||
|
|
<li><a href="#index-portability_002c-and-data-types-81">portability, and data types</a>: <a href="#CPU-Portability">CPU Portability</a></li>
|
||
|
|
<li><a href="#index-portability_002c-and-library-functions-84">portability, and library functions</a>: <a href="#System-Functions">System Functions</a></li>
|
||
|
|
<li><a href="#index-portability_002c-between-system-types-77">portability, between system types</a>: <a href="#System-Portability">System Portability</a></li>
|
||
|
|
<li><a href="#index-_0040sc_007bposix_007d-compatibility-13"><span class="sc">posix</span> compatibility</a>: <a href="#Compatibility">Compatibility</a></li>
|
||
|
|
<li><a href="#index-_0040code_007bPOSIXLY_005fCORRECT_007d_002c-environment-variable-15"><code>POSIXLY_CORRECT</code>, environment variable</a>: <a href="#Compatibility">Compatibility</a></li>
|
||
|
|
<li><a href="#index-post_002dinstallation-commands-125">post-installation commands</a>: <a href="#Install-Command-Categories">Install Command Categories</a></li>
|
||
|
|
<li><a href="#index-pre_002dinstallation-commands-124">pre-installation commands</a>: <a href="#Install-Command-Categories">Install Command Categories</a></li>
|
||
|
|
<li><a href="#index-prefix-119"><code>prefix</code></a>: <a href="#Directory-Variables">Directory Variables</a></li>
|
||
|
|
<li><a href="#index-program-configuration-110">program configuration</a>: <a href="#Configuration">Configuration</a></li>
|
||
|
|
<li><a href="#index-program-design-9">program design</a>: <a href="#Design-Advice">Design Advice</a></li>
|
||
|
|
<li><a href="#index-program-name-and-its-behavior-32">program name and its behavior</a>: <a href="#User-Interfaces">User Interfaces</a></li>
|
||
|
|
<li><a href="#index-program_0027s-canonical-name-48">program's canonical name</a>: <a href="#_002d_002dversion">--version</a></li>
|
||
|
|
<li><a href="#index-programming-languages-10">programming languages</a>: <a href="#Source-Language">Source Language</a></li>
|
||
|
|
<li><a href="#index-proprietary-programs-4">proprietary programs</a>: <a href="#Reading-Non_002dFree-Code">Reading Non-Free Code</a></li>
|
||
|
|
<li><a href="#index-quote-characters-94">quote characters</a>: <a href="#Quote-Characters">Quote Characters</a></li>
|
||
|
|
<li><a href="#index-_0040file_007bREADME_007d-file-128"><span class="file">README</span> file</a>: <a href="#Releases">Releases</a></li>
|
||
|
|
<li><a href="#index-references-to-non_002dfree-material-130">references to non-free material</a>: <a href="#References">References</a></li>
|
||
|
|
<li><a href="#index-releasing-109">releasing</a>: <a href="#Managing-Releases">Managing Releases</a></li>
|
||
|
|
<li><a href="#index-sbindir-122"><code>sbindir</code></a>: <a href="#Directory-Variables">Directory Variables</a></li>
|
||
|
|
<li><a href="#index-signal-handling-25">signal handling</a>: <a href="#Semantics">Semantics</a></li>
|
||
|
|
<li><a href="#index-spaces-before-open_002dparen-59">spaces before open-paren</a>: <a href="#Formatting">Formatting</a></li>
|
||
|
|
<li><a href="#index-staged-installs-117">staged installs</a>: <a href="#DESTDIR">DESTDIR</a></li>
|
||
|
|
<li><a href="#index-standard-command_002dline-options-42">standard command-line options</a>: <a href="#Command_002dLine-Interfaces">Command-Line Interfaces</a></li>
|
||
|
|
<li><a href="#index-standards-for-makefiles-115">standards for makefiles</a>: <a href="#Makefile-Conventions">Makefile Conventions</a></li>
|
||
|
|
<li><a href="#index-string-library-functions-86">string library functions</a>: <a href="#System-Functions">System Functions</a></li>
|
||
|
|
<li><a href="#index-syntactic-conventions-66">syntactic conventions</a>: <a href="#Syntactic-Conventions">Syntactic Conventions</a></li>
|
||
|
|
<li><a href="#index-table-of-long-options-53">table of long options</a>: <a href="#Option-Table">Option Table</a></li>
|
||
|
|
<li><a href="#index-temporary-files-27">temporary files</a>: <a href="#Semantics">Semantics</a></li>
|
||
|
|
<li><a href="#index-temporary-variables-71">temporary variables</a>: <a href="#Syntactic-Conventions">Syntactic Conventions</a></li>
|
||
|
|
<li><a href="#index-_0040file_007btexinfo_002etex_007d_002c-in-a-distribution-129"><span class="file">texinfo.tex</span>, in a distribution</a>: <a href="#Releases">Releases</a></li>
|
||
|
|
<li><a href="#index-_0040code_007bTMPDIR_007d-environment-variable-28"><code>TMPDIR</code> environment variable</a>: <a href="#Semantics">Semantics</a></li>
|
||
|
|
<li><a href="#index-trademarks-8">trademarks</a>: <a href="#Trademarks">Trademarks</a></li>
|
||
|
|
<li><a href="#index-where-to-obtain-_0040code_007bstandards_002etexi_007d-1">where to obtain <code>standards.texi</code></a>: <a href="#Preface">Preface</a></li>
|
||
|
|
</ul><div class="footnote">
|
||
|
|
<hr>
|
||
|
|
<a name="texinfo-footnotes-in-document"></a><h4>Footnotes</h4><p class="footnote"><small>[<a name="fn-1" href="#fnd-1">1</a>]</small> <code>texi2dvi</code> uses TeX to do the real work
|
||
|
|
of formatting. TeX is not distributed with Texinfo.</p>
|
||
|
|
|
||
|
|
<p><hr></div>
|
||
|
|
|
||
|
|
</body></html>
|
||
|
|
|