This is standards.info, produced by makeinfo version 4.8 from
|
This is standards.info, produced by makeinfo version 4.8 from
|
./standards.texi.
|
./standards.texi.
|
|
|
INFO-DIR-SECTION GNU organization
|
INFO-DIR-SECTION GNU organization
|
START-INFO-DIR-ENTRY
|
START-INFO-DIR-ENTRY
|
* Standards: (standards). GNU coding standards.
|
* Standards: (standards). GNU coding standards.
|
END-INFO-DIR-ENTRY
|
END-INFO-DIR-ENTRY
|
|
|
The GNU coding standards, last updated July 22, 2007.
|
The GNU coding standards, last updated July 22, 2007.
|
|
|
Copyright (C) 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000,
|
Copyright (C) 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000,
|
2001, 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
|
2001, 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
|
|
|
Permission is granted to copy, distribute and/or modify this document
|
Permission is granted to copy, distribute and/or modify this document
|
under the terms of the GNU Free Documentation License, Version 1.2 or
|
under the terms of the GNU Free Documentation License, Version 1.2 or
|
any later version published by the Free Software Foundation; with no
|
any later version published by the Free Software Foundation; with no
|
Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
|
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
|
Texts. A copy of the license is included in the section entitled "GNU
|
Free Documentation License".
|
Free Documentation License".
|
|
|
|
|
File: standards.info, Node: Top, Next: Preface, Prev: (dir), Up: (dir)
|
File: standards.info, Node: Top, Next: Preface, Prev: (dir), Up: (dir)
|
|
|
Version
|
Version
|
*******
|
*******
|
|
|
The GNU coding standards, last updated July 22, 2007.
|
The GNU coding standards, last updated July 22, 2007.
|
|
|
Copyright (C) 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000,
|
Copyright (C) 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000,
|
2001, 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
|
2001, 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
|
|
|
Permission is granted to copy, distribute and/or modify this document
|
Permission is granted to copy, distribute and/or modify this document
|
under the terms of the GNU Free Documentation License, Version 1.2 or
|
under the terms of the GNU Free Documentation License, Version 1.2 or
|
any later version published by the Free Software Foundation; with no
|
any later version published by the Free Software Foundation; with no
|
Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
|
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
|
Texts. A copy of the license is included in the section entitled "GNU
|
Free Documentation License".
|
Free Documentation License".
|
|
|
* Menu:
|
* Menu:
|
|
|
* Preface:: About the GNU Coding Standards.
|
* Preface:: About the GNU Coding Standards.
|
* Legal Issues:: Keeping free software free.
|
* Legal Issues:: Keeping free software free.
|
* Design Advice:: General program design.
|
* Design Advice:: General program design.
|
* Program Behavior:: Program behavior for all programs
|
* Program Behavior:: Program behavior for all programs
|
* Writing C:: Making the best use of C.
|
* Writing C:: Making the best use of C.
|
* Documentation:: Documenting programs.
|
* Documentation:: Documenting programs.
|
* Managing Releases:: The release process.
|
* Managing Releases:: The release process.
|
* References:: Mentioning non-free software or documentation.
|
* References:: Mentioning non-free software or documentation.
|
* GNU Free Documentation License:: Copying and sharing this manual.
|
* GNU Free Documentation License:: Copying and sharing this manual.
|
* Index::
|
* Index::
|
|
|
|
|
File: standards.info, Node: Preface, Next: Legal Issues, Prev: Top, Up: Top
|
File: standards.info, Node: Preface, Next: Legal Issues, Prev: Top, Up: Top
|
|
|
1 About the GNU Coding Standards
|
1 About the GNU Coding Standards
|
********************************
|
********************************
|
|
|
The GNU Coding Standards were written by Richard Stallman and other GNU
|
The GNU Coding Standards were written by Richard Stallman and other GNU
|
Project volunteers. Their purpose is to make the GNU system clean,
|
Project volunteers. Their purpose is to make the GNU system clean,
|
consistent, and easy to install. This document can also be read as a
|
consistent, and easy to install. This document can also be read as a
|
guide to writing portable, robust and reliable programs. It focuses on
|
guide to writing portable, robust and reliable programs. It focuses on
|
programs written in C, but many of the rules and principles are useful
|
programs written in C, but many of the rules and principles are useful
|
even if you write in another programming language. The rules often
|
even if you write in another programming language. The rules often
|
state reasons for writing in a certain way.
|
state reasons for writing in a certain way.
|
|
|
This release of the GNU Coding Standards was last updated July 22,
|
This release of the GNU Coding Standards was last updated July 22,
|
2007.
|
2007.
|
|
|
If you did not obtain this file directly from the GNU project and
|
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
|
recently, please check for a newer version. You can get the GNU Coding
|
Standards from the GNU web server in many different formats, including
|
Standards from the GNU web server in many different formats, including
|
the Texinfo source, PDF, HTML, DVI, plain text, and more, at:
|
the Texinfo source, PDF, HTML, DVI, plain text, and more, at:
|
`http://www.gnu.org/prep/standards/'.
|
`http://www.gnu.org/prep/standards/'.
|
|
|
Corrections or suggestions for this document should be sent to
|
Corrections or suggestions for this document should be sent to
|
. If you make a suggestion, please include a
|
. If you make a suggestion, please include a
|
suggested new wording for it; our time is limited. We prefer a context
|
suggested new wording for it; our time is limited. We prefer a context
|
diff to the `standards.texi' or `make-stds.texi' files, but if you
|
diff to the `standards.texi' or `make-stds.texi' files, but if you
|
don't have those files, please mail your suggestion anyway.
|
don't have those files, please mail your suggestion anyway.
|
|
|
These standards cover the minimum of what is important when writing a
|
These standards cover the minimum of what is important when writing a
|
GNU package. Likely, the need for additional standards will come up.
|
GNU package. Likely, the need for additional standards will come up.
|
Sometimes, you might suggest that such standards be added to this
|
Sometimes, you might suggest that such standards be added to this
|
document. If you think your standards would be generally useful, please
|
document. If you think your standards would be generally useful, please
|
do suggest them.
|
do suggest them.
|
|
|
You should also set standards for your package on many questions not
|
You should also set standards for your package on many questions not
|
addressed or not firmly specified here. The most important point is to
|
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
|
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
|
to document them as much as possible. That way, your program will be
|
more maintainable by others.
|
more maintainable by others.
|
|
|
The GNU Hello program serves as an example of how to follow the GNU
|
The GNU Hello program serves as an example of how to follow the GNU
|
coding standards for a trivial program.
|
coding standards for a trivial program.
|
`http://www.gnu.org/software/hello/hello.html'.
|
`http://www.gnu.org/software/hello/hello.html'.
|
|
|
|
|
File: standards.info, Node: Legal Issues, Next: Design Advice, Prev: Preface, Up: Top
|
File: standards.info, Node: Legal Issues, Next: Design Advice, Prev: Preface, Up: Top
|
|
|
2 Keeping Free Software Free
|
2 Keeping Free Software Free
|
****************************
|
****************************
|
|
|
This chapter discusses how you can make sure that GNU software avoids
|
This chapter discusses how you can make sure that GNU software avoids
|
legal difficulties, and other related issues.
|
legal difficulties, and other related issues.
|
|
|
* Menu:
|
* Menu:
|
|
|
* Reading Non-Free Code:: Referring to proprietary programs.
|
* Reading Non-Free Code:: Referring to proprietary programs.
|
* Contributions:: Accepting contributions.
|
* Contributions:: Accepting contributions.
|
* Trademarks:: How we deal with trademark issues.
|
* Trademarks:: How we deal with trademark issues.
|
|
|
|
|
File: standards.info, Node: Reading Non-Free Code, Next: Contributions, Up: Legal Issues
|
File: standards.info, Node: Reading Non-Free Code, Next: Contributions, Up: Legal Issues
|
|
|
2.1 Referring to Proprietary Programs
|
2.1 Referring to Proprietary Programs
|
=====================================
|
=====================================
|
|
|
Don't in any circumstances refer to Unix source code for or during your
|
Don't in any circumstances refer to Unix source code for or during your
|
work on GNU! (Or to any other proprietary programs.)
|
work on GNU! (Or to any other proprietary programs.)
|
|
|
If you have a vague recollection of the internals of a Unix program,
|
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
|
this does not absolutely mean you can't write an imitation of it, but
|
do try to organize the imitation internally along different lines,
|
do try to organize the imitation internally along different lines,
|
because this is likely to make the details of the Unix version
|
because this is likely to make the details of the Unix version
|
irrelevant and dissimilar to your results.
|
irrelevant and dissimilar to your results.
|
|
|
For example, Unix utilities were generally optimized to minimize
|
For example, Unix utilities were generally optimized to minimize
|
memory use; if you go for speed instead, your program will be very
|
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
|
different. You could keep the entire input file in memory and scan it
|
there instead of using stdio. Use a smarter algorithm discovered more
|
there instead of using stdio. Use a smarter algorithm discovered more
|
recently than the Unix program. Eliminate use of temporary files. Do
|
recently than the Unix program. Eliminate use of temporary files. Do
|
it in one pass instead of two (we did this in the assembler).
|
it in one pass instead of two (we did this in the assembler).
|
|
|
Or, on the contrary, emphasize simplicity instead of speed. For some
|
Or, on the contrary, emphasize simplicity instead of speed. For some
|
applications, the speed of today's computers makes simpler algorithms
|
applications, the speed of today's computers makes simpler algorithms
|
adequate.
|
adequate.
|
|
|
Or go for generality. For example, Unix programs often have static
|
Or go for generality. For example, Unix programs often have static
|
tables or fixed-size strings, which make for arbitrary limits; use
|
tables or fixed-size strings, which make for arbitrary limits; use
|
dynamic allocation instead. Make sure your program handles NULs and
|
dynamic allocation instead. Make sure your program handles NULs and
|
other funny characters in the input files. Add a programming language
|
other funny characters in the input files. Add a programming language
|
for extensibility and write part of the program in that language.
|
for extensibility and write part of the program in that language.
|
|
|
Or turn some parts of the program into independently usable
|
Or turn some parts of the program into independently usable
|
libraries. Or use a simple garbage collector instead of tracking
|
libraries. Or use a simple garbage collector instead of tracking
|
precisely when to free memory, or use a new GNU facility such as
|
precisely when to free memory, or use a new GNU facility such as
|
obstacks.
|
obstacks.
|
|
|
|
|
File: standards.info, Node: Contributions, Next: Trademarks, Prev: Reading Non-Free Code, Up: Legal Issues
|
File: standards.info, Node: Contributions, Next: Trademarks, Prev: Reading Non-Free Code, Up: Legal Issues
|
|
|
2.2 Accepting Contributions
|
2.2 Accepting Contributions
|
===========================
|
===========================
|
|
|
If the program you are working on is copyrighted by the Free Software
|
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
|
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
|
the program, we need legal papers to use it--just as we asked you to
|
sign papers initially. _Each_ person who makes a nontrivial
|
sign papers initially. _Each_ person who makes a nontrivial
|
contribution to a program must sign some sort of legal papers in order
|
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
|
for us to have clear title to the program; the main author alone is not
|
enough.
|
enough.
|
|
|
So, before adding in any contributions from other people, please tell
|
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
|
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
|
that we have received the signed papers, before you actually use the
|
contribution.
|
contribution.
|
|
|
This applies both before you release the program and afterward. If
|
This applies both before you release the program and afterward. If
|
you receive diffs to fix a bug, and they make significant changes, we
|
you receive diffs to fix a bug, and they make significant changes, we
|
need legal papers for that change.
|
need legal papers for that change.
|
|
|
This also applies to comments and documentation files. For copyright
|
This also applies to comments and documentation files. For copyright
|
law, comments and code are just text. Copyright applies to all kinds of
|
law, comments and code are just text. Copyright applies to all kinds of
|
text, so we need legal papers for all kinds.
|
text, so we need legal papers for all kinds.
|
|
|
We know it is frustrating to ask for legal papers; it's frustrating
|
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
|
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?
|
example, what if the contributor's employer won't sign a disclaimer?
|
You might have to take that code out again!
|
You might have to take that code out again!
|
|
|
You don't need papers for changes of a few lines here or there, since
|
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
|
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
|
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
|
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
|
you write a different implementation of the same idea, you don't need to
|
get papers.
|
get papers.
|
|
|
The very worst thing is if you forget to tell us about the other
|
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
|
contributor. We could be very embarrassed in court some day as a
|
result.
|
result.
|
|
|
We have more detailed advice for maintainers of programs; if you have
|
We have more detailed advice for maintainers of programs; if you have
|
reached the stage of actually maintaining a program for GNU (whether
|
reached the stage of actually maintaining a program for GNU (whether
|
released or not), please ask us for a copy. It is also available
|
released or not), please ask us for a copy. It is also available
|
online for your perusal: `http://www.gnu.org/prep/maintain/'.
|
online for your perusal: `http://www.gnu.org/prep/maintain/'.
|
|
|
|
|
File: standards.info, Node: Trademarks, Prev: Contributions, Up: Legal Issues
|
File: standards.info, Node: Trademarks, Prev: Contributions, Up: Legal Issues
|
|
|
2.3 Trademarks
|
2.3 Trademarks
|
==============
|
==============
|
|
|
Please do not include any trademark acknowledgements in GNU software
|
Please do not include any trademark acknowledgements in GNU software
|
packages or documentation.
|
packages or documentation.
|
|
|
Trademark acknowledgements are the statements that such-and-such is a
|
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
|
trademark of so-and-so. The GNU Project has no objection to the basic
|
idea of trademarks, but these acknowledgements feel like kowtowing, and
|
idea of trademarks, but these acknowledgements feel like kowtowing, and
|
there is no legal requirement for them, so we don't use them.
|
there is no legal requirement for them, so we don't use them.
|
|
|
What is legally required, as regards other people's trademarks, is to
|
What is legally required, as regards other people's trademarks, is to
|
avoid using them in ways which a reader might reasonably understand as
|
avoid using them in ways which a reader might reasonably understand as
|
naming or labeling our own programs or activities. For example, since
|
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
|
"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
|
that we provide a "compiler for the Objective C language" rather than
|
an "Objective C compiler". The latter would have been meant as a
|
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
|
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
|
relationship, so it could be misinterpreted as using "Objective C" as a
|
label for the compiler rather than for the language.
|
label for the compiler rather than for the language.
|
|
|
Please don't use "win" as an abbreviation for Microsoft Windows in
|
Please don't use "win" as an abbreviation for Microsoft Windows in
|
GNU software or documentation. In hacker terminology, calling
|
GNU software or documentation. In hacker terminology, calling
|
something a "win" is a form of praise. If you wish to praise Microsoft
|
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
|
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
|
software. Usually we write the name "Windows" in full, but when
|
brevity is very important (as in file names and sometimes symbol
|
brevity is very important (as in file names and sometimes symbol
|
names), we abbreviate it to "w". For instance, the files and functions
|
names), we abbreviate it to "w". For instance, the files and functions
|
in Emacs that deal with Windows start with `w32'.
|
in Emacs that deal with Windows start with `w32'.
|
|
|
|
|
File: standards.info, Node: Design Advice, Next: Program Behavior, Prev: Legal Issues, Up: Top
|
File: standards.info, Node: Design Advice, Next: Program Behavior, Prev: Legal Issues, Up: Top
|
|
|
3 General Program Design
|
3 General Program Design
|
************************
|
************************
|
|
|
This chapter discusses some of the issues you should take into account
|
This chapter discusses some of the issues you should take into account
|
when designing your program.
|
when designing your program.
|
|
|
* Menu:
|
* Menu:
|
|
|
* Source Language:: Which languages to use.
|
* Source Language:: Which languages to use.
|
* Compatibility:: Compatibility with other implementations.
|
* Compatibility:: Compatibility with other implementations.
|
* Using Extensions:: Using non-standard features.
|
* Using Extensions:: Using non-standard features.
|
* Standard C:: Using standard C features.
|
* Standard C:: Using standard C features.
|
* Conditional Compilation:: Compiling code only if a conditional is true.
|
* Conditional Compilation:: Compiling code only if a conditional is true.
|
|
|
|
|
File: standards.info, Node: Source Language, Next: Compatibility, Up: Design Advice
|
File: standards.info, Node: Source Language, Next: Compatibility, Up: Design Advice
|
|
|
3.1 Which Languages to Use
|
3.1 Which Languages to Use
|
==========================
|
==========================
|
|
|
When you want to use a language that gets compiled and runs at high
|
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
|
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
|
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
|
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
|
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
|
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.
|
have to install the GNU C++ compiler in order to compile your program.
|
|
|
C has one other advantage over C++ and other compiled languages: more
|
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
|
people know C, so more people will find it easy to read and modify the
|
program if it is written in C.
|
program if it is written in C.
|
|
|
So in general it is much better to use C, rather than the comparable
|
So in general it is much better to use C, rather than the comparable
|
alternatives.
|
alternatives.
|
|
|
But there are two exceptions to that conclusion:
|
But there are two exceptions to that conclusion:
|
|
|
* It is no problem to use another language to write a tool
|
* It is no problem to use another language to write a tool
|
specifically intended for use with that language. That is because
|
specifically intended for use with that language. That is because
|
the only people who want to build the tool will be those who have
|
the only people who want to build the tool will be those who have
|
installed the other language anyway.
|
installed the other language anyway.
|
|
|
* If an application is of interest only to a narrow part of the
|
* If an application is of interest only to a narrow part of the
|
community, then the question of which language it is written in
|
community, then the question of which language it is written in
|
has less effect on other people, so you may as well please
|
has less effect on other people, so you may as well please
|
yourself.
|
yourself.
|
|
|
Many programs are designed to be extensible: they include an
|
Many programs are designed to be extensible: they include an
|
interpreter for a language that is higher level than C. Often much of
|
interpreter for a language that is higher level than C. Often much of
|
the program is written in that language, too. The Emacs editor
|
the program is written in that language, too. The Emacs editor
|
pioneered this technique.
|
pioneered this technique.
|
|
|
The standard extensibility interpreter for GNU software is GUILE
|
The standard extensibility interpreter for GNU software is GUILE
|
(`http://www.gnu.org/software/guile/'), which implements the language
|
(`http://www.gnu.org/software/guile/'), which implements the language
|
Scheme (an especially clean and simple dialect of Lisp). We don't
|
Scheme (an especially clean and simple dialect of Lisp). We don't
|
reject programs written in other "scripting languages" such as Perl and
|
reject programs written in other "scripting languages" such as Perl and
|
Python, but using GUILE is very important for the overall consistency
|
Python, but using GUILE is very important for the overall consistency
|
of the GNU system.
|
of the GNU system.
|
|
|
|
|
File: standards.info, Node: Compatibility, Next: Using Extensions, Prev: Source Language, Up: Design Advice
|
File: standards.info, Node: Compatibility, Next: Using Extensions, Prev: Source Language, Up: Design Advice
|
|
|
3.2 Compatibility with Other Implementations
|
3.2 Compatibility with Other Implementations
|
============================================
|
============================================
|
|
|
With occasional exceptions, utility programs and libraries for GNU
|
With occasional exceptions, utility programs and libraries for GNU
|
should be upward compatible with those in Berkeley Unix, and upward
|
should be upward compatible with those in Berkeley Unix, and upward
|
compatible with Standard C if Standard C specifies their behavior, and
|
compatible with Standard C if Standard C specifies their behavior, and
|
upward compatible with POSIX if POSIX specifies their behavior.
|
upward compatible with POSIX if POSIX specifies their behavior.
|
|
|
When these standards conflict, it is useful to offer compatibility
|
When these standards conflict, it is useful to offer compatibility
|
modes for each of them.
|
modes for each of them.
|
|
|
Standard C and POSIX prohibit many kinds of extensions. Feel free
|
Standard C and POSIX prohibit many kinds of extensions. Feel free
|
to make the extensions anyway, and include a `--ansi', `--posix', or
|
to make the extensions anyway, and include a `--ansi', `--posix', or
|
`--compatible' option to turn them off. However, if the extension has
|
`--compatible' option to turn them off. However, if the extension has
|
a significant chance of breaking any real programs or scripts, then it
|
a significant chance of breaking any real programs or scripts, then it
|
is not really upward compatible. So you should try to redesign its
|
is not really upward compatible. So you should try to redesign its
|
interface to make it upward compatible.
|
interface to make it upward compatible.
|
|
|
Many GNU programs suppress extensions that conflict with POSIX if the
|
Many GNU programs suppress extensions that conflict with POSIX if the
|
environment variable `POSIXLY_CORRECT' is defined (even if it is
|
environment variable `POSIXLY_CORRECT' is defined (even if it is
|
defined with a null value). Please make your program recognize this
|
defined with a null value). Please make your program recognize this
|
variable if appropriate.
|
variable if appropriate.
|
|
|
When a feature is used only by users (not by programs or command
|
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
|
files), and it is done poorly in Unix, feel free to replace it
|
completely with something totally different and better. (For example,
|
completely with something totally different and better. (For example,
|
`vi' is replaced with Emacs.) But it is nice to offer a compatible
|
`vi' is replaced with Emacs.) But it is nice to offer a compatible
|
feature as well. (There is a free `vi' clone, so we offer it.)
|
feature as well. (There is a free `vi' clone, so we offer it.)
|
|
|
Additional useful features are welcome regardless of whether there
|
Additional useful features are welcome regardless of whether there
|
is any precedent for them.
|
is any precedent for them.
|
|
|
|
|
File: standards.info, Node: Using Extensions, Next: Standard C, Prev: Compatibility, Up: Design Advice
|
File: standards.info, Node: Using Extensions, Next: Standard C, Prev: Compatibility, Up: Design Advice
|
|
|
3.3 Using Non-standard Features
|
3.3 Using Non-standard Features
|
===============================
|
===============================
|
|
|
Many GNU facilities that already exist support a number of convenient
|
Many GNU facilities that already exist support a number of convenient
|
extensions over the comparable Unix facilities. Whether to use these
|
extensions over the comparable Unix facilities. Whether to use these
|
extensions in implementing your program is a difficult question.
|
extensions in implementing your program is a difficult question.
|
|
|
On the one hand, using the extensions can make a cleaner program.
|
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
|
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
|
the other GNU tools are available. This might cause the program to
|
work on fewer kinds of machines.
|
work on fewer kinds of machines.
|
|
|
With some extensions, it might be easy to provide both alternatives.
|
With some extensions, it might be easy to provide both alternatives.
|
For example, you can define functions with a "keyword" `INLINE' and
|
For example, you can define functions with a "keyword" `INLINE' and
|
define that as a macro to expand into either `inline' or nothing,
|
define that as a macro to expand into either `inline' or nothing,
|
depending on the compiler.
|
depending on the compiler.
|
|
|
In general, perhaps it is best not to use the extensions if you can
|
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
|
straightforwardly do without them, but to use the extensions if they
|
are a big improvement.
|
are a big improvement.
|
|
|
An exception to this rule are the large, established programs (such
|
An exception to this rule are the large, established programs (such
|
as Emacs) which run on a great variety of systems. Using GNU
|
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
|
extensions in such programs would make many users unhappy, so we don't
|
do that.
|
do that.
|
|
|
Another exception is for programs that are used as part of
|
Another exception is for programs that are used as part of
|
compilation: anything that must be compiled with other compilers in
|
compilation: anything that must be compiled with other compilers in
|
order to bootstrap the GNU compilation facilities. If these require
|
order to bootstrap the GNU compilation facilities. If these require
|
the GNU compiler, then no one can compile them without having them
|
the GNU compiler, then no one can compile them without having them
|
installed already. That would be extremely troublesome in certain
|
installed already. That would be extremely troublesome in certain
|
cases.
|
cases.
|
|
|
|
|
File: standards.info, Node: Standard C, Next: Conditional Compilation, Prev: Using Extensions, Up: Design Advice
|
File: standards.info, Node: Standard C, Next: Conditional Compilation, Prev: Using Extensions, Up: Design Advice
|
|
|
3.4 Standard C and Pre-Standard C
|
3.4 Standard C and Pre-Standard C
|
=================================
|
=================================
|
|
|
1989 Standard C is widespread enough now that it is ok to use its
|
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
|
features in new programs. There is one exception: do not ever use the
|
"trigraph" feature of Standard C.
|
"trigraph" feature of Standard C.
|
|
|
1999 Standard C is not widespread yet, so please do not require its
|
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.
|
features in programs. It is ok to use its features if they are present.
|
|
|
However, it is easy to support pre-standard compilers in most
|
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
|
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.
|
are maintaining has such support, you should try to keep it working.
|
|
|
To support pre-standard C, instead of writing function definitions in
|
To support pre-standard C, instead of writing function definitions in
|
standard prototype form,
|
standard prototype form,
|
|
|
int
|
int
|
foo (int x, int y)
|
foo (int x, int y)
|
...
|
...
|
|
|
write the definition in pre-standard style like this,
|
write the definition in pre-standard style like this,
|
|
|
int
|
int
|
foo (x, y)
|
foo (x, y)
|
int x, y;
|
int x, y;
|
...
|
...
|
|
|
and use a separate declaration to specify the argument prototype:
|
and use a separate declaration to specify the argument prototype:
|
|
|
int foo (int, int);
|
int foo (int, int);
|
|
|
You need such a declaration anyway, in a header file, to get the
|
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.
|
benefit of prototypes in all the files where the function is called.
|
And once you have the declaration, you normally lose nothing by writing
|
And once you have the declaration, you normally lose nothing by writing
|
the function definition in the pre-standard style.
|
the function definition in the pre-standard style.
|
|
|
This technique does not work for integer types narrower than `int'.
|
This technique does not work for integer types narrower than `int'.
|
If you think of an argument as being of a type narrower than `int',
|
If you think of an argument as being of a type narrower than `int',
|
declare it as `int' instead.
|
declare it as `int' instead.
|
|
|
There are a few special cases where this technique is hard to use.
|
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
|
For example, if a function argument needs to hold the system type
|
`dev_t', you run into trouble, because `dev_t' is shorter than `int' on
|
`dev_t', you run into trouble, because `dev_t' is shorter than `int' on
|
some machines; but you cannot use `int' instead, because `dev_t' is
|
some machines; but you cannot use `int' instead, because `dev_t' is
|
wider than `int' on some machines. There is no type you can safely use
|
wider than `int' on some machines. There is no type you can safely use
|
on all machines in a non-standard definition. The only way to support
|
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
|
non-standard C and pass such an argument is to check the width of
|
`dev_t' using Autoconf and choose the argument type accordingly. This
|
`dev_t' using Autoconf and choose the argument type accordingly. This
|
may not be worth the trouble.
|
may not be worth the trouble.
|
|
|
In order to support pre-standard compilers that do not recognize
|
In order to support pre-standard compilers that do not recognize
|
prototypes, you may want to use a preprocessor macro like this:
|
prototypes, you may want to use a preprocessor macro like this:
|
|
|
/* Declare the prototype for a general external function. */
|
/* Declare the prototype for a general external function. */
|
#if defined (__STDC__) || defined (WINDOWSNT)
|
#if defined (__STDC__) || defined (WINDOWSNT)
|
#define P_(proto) proto
|
#define P_(proto) proto
|
#else
|
#else
|
#define P_(proto) ()
|
#define P_(proto) ()
|
#endif
|
#endif
|
|
|
|
|
File: standards.info, Node: Conditional Compilation, Prev: Standard C, Up: Design Advice
|
File: standards.info, Node: Conditional Compilation, Prev: Standard C, Up: Design Advice
|
|
|
3.5 Conditional Compilation
|
3.5 Conditional Compilation
|
===========================
|
===========================
|
|
|
When supporting configuration options already known when building your
|
When supporting configuration options already known when building your
|
program we prefer using `if (... )' over conditional compilation, as in
|
program we prefer using `if (... )' over conditional compilation, as in
|
the former case the compiler is able to perform more extensive checking
|
the former case the compiler is able to perform more extensive checking
|
of all possible code paths.
|
of all possible code paths.
|
|
|
For example, please write
|
For example, please write
|
|
|
if (HAS_FOO)
|
if (HAS_FOO)
|
...
|
...
|
else
|
else
|
...
|
...
|
|
|
instead of:
|
instead of:
|
|
|
#ifdef HAS_FOO
|
#ifdef HAS_FOO
|
...
|
...
|
#else
|
#else
|
...
|
...
|
#endif
|
#endif
|
|
|
A modern compiler such as GCC will generate exactly the same code in
|
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
|
both cases, and we have been using similar techniques with good success
|
in several projects. Of course, the former method assumes that
|
in several projects. Of course, the former method assumes that
|
`HAS_FOO' is defined as either 0 or 1.
|
`HAS_FOO' is defined as either 0 or 1.
|
|
|
While this is not a silver bullet solving all portability problems,
|
While this is not a silver bullet solving all portability problems,
|
and is not always appropriate, following this policy would have saved
|
and is not always appropriate, following this policy would have saved
|
GCC developers many hours, or even days, per year.
|
GCC developers many hours, or even days, per year.
|
|
|
In the case of function-like macros like `REVERSIBLE_CC_MODE' in GCC
|
In the case of function-like macros like `REVERSIBLE_CC_MODE' in GCC
|
which cannot be simply used in `if( ...)' statements, there is an easy
|
which cannot be simply used in `if( ...)' statements, there is an easy
|
workaround. Simply introduce another macro `HAS_REVERSIBLE_CC_MODE' as
|
workaround. Simply introduce another macro `HAS_REVERSIBLE_CC_MODE' as
|
in the following example:
|
in the following example:
|
|
|
#ifdef REVERSIBLE_CC_MODE
|
#ifdef REVERSIBLE_CC_MODE
|
#define HAS_REVERSIBLE_CC_MODE 1
|
#define HAS_REVERSIBLE_CC_MODE 1
|
#else
|
#else
|
#define HAS_REVERSIBLE_CC_MODE 0
|
#define HAS_REVERSIBLE_CC_MODE 0
|
#endif
|
#endif
|
|
|
|
|
File: standards.info, Node: Program Behavior, Next: Writing C, Prev: Design Advice, Up: Top
|
File: standards.info, Node: Program Behavior, Next: Writing C, Prev: Design Advice, Up: Top
|
|
|
4 Program Behavior for All Programs
|
4 Program Behavior for All Programs
|
***********************************
|
***********************************
|
|
|
This chapter describes conventions for writing robust software. It
|
This chapter describes conventions for writing robust software. It
|
also describes general standards for error messages, the command line
|
also describes general standards for error messages, the command line
|
interface, and how libraries should behave.
|
interface, and how libraries should behave.
|
|
|
* Menu:
|
* Menu:
|
|
|
* Non-GNU Standards:: We consider standards such as POSIX;
|
* Non-GNU Standards:: We consider standards such as POSIX;
|
we don't "obey" them.
|
we don't "obey" them.
|
* Semantics:: Writing robust programs.
|
* Semantics:: Writing robust programs.
|
* Libraries:: Library behavior.
|
* Libraries:: Library behavior.
|
* Errors:: Formatting error messages.
|
* Errors:: Formatting error messages.
|
* User Interfaces:: Standards about interfaces generally.
|
* User Interfaces:: Standards about interfaces generally.
|
* Graphical Interfaces:: Standards for graphical interfaces.
|
* Graphical Interfaces:: Standards for graphical interfaces.
|
* Command-Line Interfaces:: Standards for command line interfaces.
|
* Command-Line Interfaces:: Standards for command line interfaces.
|
* Option Table:: Table of long options.
|
* Option Table:: Table of long options.
|
* Memory Usage:: When and how to care about memory needs.
|
* Memory Usage:: When and how to care about memory needs.
|
* File Usage:: Which files to use, and where.
|
* File Usage:: Which files to use, and where.
|
|
|
|
|
File: standards.info, Node: Non-GNU Standards, Next: Semantics, Up: Program Behavior
|
File: standards.info, Node: Non-GNU Standards, Next: Semantics, Up: Program Behavior
|
|
|
4.1 Non-GNU Standards
|
4.1 Non-GNU Standards
|
=====================
|
=====================
|
|
|
The GNU Project regards standards published by other organizations as
|
The GNU Project regards standards published by other organizations as
|
suggestions, not orders. We consider those standards, but we do not
|
suggestions, not orders. We consider those standards, but we do not
|
"obey" them. In developing a GNU program, you should implement an
|
"obey" them. In developing a GNU program, you should implement an
|
outside standard's specifications when that makes the GNU system better
|
outside standard's specifications when that makes the GNU system better
|
overall in an objective sense. When it doesn't, you shouldn't.
|
overall in an objective sense. When it doesn't, you shouldn't.
|
|
|
In most cases, following published standards is convenient for
|
In most cases, following published standards is convenient for
|
users--it means that their programs or scripts will work more portably.
|
users--it means that their programs or scripts will work more portably.
|
For instance, GCC implements nearly all the features of Standard C as
|
For instance, GCC implements nearly all the features of Standard C as
|
specified by that standard. C program developers would be unhappy if
|
specified by that standard. C program developers would be unhappy if
|
it did not. And GNU utilities mostly follow specifications of POSIX.2;
|
it did not. And GNU utilities mostly follow specifications of POSIX.2;
|
shell script writers and users would be unhappy if our programs were
|
shell script writers and users would be unhappy if our programs were
|
incompatible.
|
incompatible.
|
|
|
But we do not follow either of these specifications rigidly, and
|
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
|
there are specific points on which we decided not to follow them, so as
|
to make the GNU system better for users.
|
to make the GNU system better for users.
|
|
|
For instance, Standard C says that nearly all extensions to C are
|
For instance, Standard C says that nearly all extensions to C are
|
prohibited. How silly! GCC implements many extensions, some of which
|
prohibited. How silly! GCC implements many extensions, some of which
|
were later adopted as part of the standard. If you want these
|
were later adopted as part of the standard. If you want these
|
constructs to give an error message as "required" by the standard, you
|
constructs to give an error message as "required" by the standard, you
|
must specify `--pedantic', which was implemented only so that we can
|
must specify `--pedantic', which was implemented only so that we can
|
say "GCC is a 100% implementation of the standard," not because there
|
say "GCC is a 100% implementation of the standard," not because there
|
is any reason to actually use it.
|
is any reason to actually use it.
|
|
|
POSIX.2 specifies that `df' and `du' must output sizes by default in
|
POSIX.2 specifies that `df' and `du' must output sizes by default in
|
units of 512 bytes. What users want is units of 1k, so that is what we
|
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
|
do by default. If you want the ridiculous behavior "required" by
|
POSIX, you must set the environment variable `POSIXLY_CORRECT' (which
|
POSIX, you must set the environment variable `POSIXLY_CORRECT' (which
|
was originally going to be named `POSIX_ME_HARDER').
|
was originally going to be named `POSIX_ME_HARDER').
|
|
|
GNU utilities also depart from the letter of the POSIX.2
|
GNU utilities also depart from the letter of the POSIX.2
|
specification when they support long-named command-line options, and
|
specification when they support long-named command-line options, and
|
intermixing options with ordinary arguments. This minor
|
intermixing options with ordinary arguments. This minor
|
incompatibility with POSIX is never a problem in practice, and it is
|
incompatibility with POSIX is never a problem in practice, and it is
|
very useful.
|
very useful.
|
|
|
In particular, don't reject a new feature, or remove an old one,
|
In particular, don't reject a new feature, or remove an old one,
|
merely because a standard says it is "forbidden" or "deprecated."
|
merely because a standard says it is "forbidden" or "deprecated."
|
|
|
|
|
File: standards.info, Node: Semantics, Next: Libraries, Prev: Non-GNU Standards, Up: Program Behavior
|
File: standards.info, Node: Semantics, Next: Libraries, Prev: Non-GNU Standards, Up: Program Behavior
|
|
|
4.2 Writing Robust Programs
|
4.2 Writing Robust Programs
|
===========================
|
===========================
|
|
|
Avoid arbitrary limits on the length or number of _any_ data structure,
|
Avoid arbitrary limits on the length or number of _any_ data structure,
|
including file names, lines, files, and symbols, by allocating all data
|
including file names, lines, files, and symbols, by allocating all data
|
structures dynamically. In most Unix utilities, "long lines are
|
structures dynamically. In most Unix utilities, "long lines are
|
silently truncated". This is not acceptable in a GNU utility.
|
silently truncated". This is not acceptable in a GNU utility.
|
|
|
Utilities reading files should not drop NUL characters, or any other
|
Utilities reading files should not drop NUL characters, or any other
|
nonprinting characters _including those with codes above 0177_. The
|
nonprinting characters _including those with codes above 0177_. The
|
only sensible exceptions would be utilities specifically intended for
|
only sensible exceptions would be utilities specifically intended for
|
interface to certain types of terminals or printers that can't handle
|
interface to certain types of terminals or printers that can't handle
|
those characters. Whenever possible, try to make programs work
|
those characters. Whenever possible, try to make programs work
|
properly with sequences of bytes that represent multibyte characters,
|
properly with sequences of bytes that represent multibyte characters,
|
using encodings such as UTF-8 and others.
|
using encodings such as UTF-8 and others.
|
|
|
Check every system call for an error return, unless you know you
|
Check every system call for an error return, unless you know you
|
wish to ignore errors. Include the system error text (from `perror' or
|
wish to ignore errors. Include the system error text (from `perror' or
|
equivalent) in _every_ error message resulting from a failing system
|
equivalent) in _every_ error message resulting from a failing system
|
call, as well as the name of the file if any and the name of the
|
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.
|
utility. Just "cannot open foo.c" or "stat failed" is not sufficient.
|
|
|
Check every call to `malloc' or `realloc' to see if it returned
|
Check every call to `malloc' or `realloc' to see if it returned
|
zero. Check `realloc' even if you are making the block smaller; in a
|
zero. Check `realloc' even if you are making the block smaller; in a
|
system that rounds block sizes to a power of 2, `realloc' may get a
|
system that rounds block sizes to a power of 2, `realloc' may get a
|
different block if you ask for less space.
|
different block if you ask for less space.
|
|
|
In Unix, `realloc' can destroy the storage block if it returns zero.
|
In Unix, `realloc' can destroy the storage block if it returns zero.
|
GNU `realloc' does not have this bug: if it fails, the original block
|
GNU `realloc' 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
|
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
|
run your program on Unix, and wish to avoid lossage in this case, you
|
can use the GNU `malloc'.
|
can use the GNU `malloc'.
|
|
|
You must expect `free' to alter the contents of the block that was
|
You must expect `free' to alter the contents of the block that was
|
freed. Anything you want to fetch from the block, you must fetch before
|
freed. Anything you want to fetch from the block, you must fetch before
|
calling `free'.
|
calling `free'.
|
|
|
If `malloc' fails in a noninteractive program, make that a fatal
|
If `malloc' fails in a noninteractive program, make that a fatal
|
error. In an interactive program (one that reads commands from the
|
error. In an interactive program (one that reads commands from the
|
user), it is better to abort the command and return to the command
|
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
|
reader loop. This allows the user to kill other processes to free up
|
virtual memory, and then try the command again.
|
virtual memory, and then try the command again.
|
|
|
Use `getopt_long' to decode arguments, unless the argument syntax
|
Use `getopt_long' to decode arguments, unless the argument syntax
|
makes this unreasonable.
|
makes this unreasonable.
|
|
|
When static storage is to be written in during program execution, use
|
When static storage is to be written in during program execution, use
|
explicit C code to initialize it. Reserve C initialized declarations
|
explicit C code to initialize it. Reserve C initialized declarations
|
for data that will not be changed.
|
for data that will not be changed.
|
|
|
Try to avoid low-level interfaces to obscure Unix data structures
|
Try to avoid low-level interfaces to obscure Unix data structures
|
(such as file directories, utmp, or the layout of kernel memory), since
|
(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
|
these are less likely to work compatibly. If you need to find all the
|
files in a directory, use `readdir' or some other high-level interface.
|
files in a directory, use `readdir' or some other high-level interface.
|
These are supported compatibly by GNU.
|
These are supported compatibly by GNU.
|
|
|
The preferred signal handling facilities are the BSD variant of
|
The preferred signal handling facilities are the BSD variant of
|
`signal', and the POSIX `sigaction' function; the alternative USG
|
`signal', and the POSIX `sigaction' function; the alternative USG
|
`signal' interface is an inferior design.
|
`signal' interface is an inferior design.
|
|
|
Nowadays, using the POSIX signal functions may be the easiest way to
|
Nowadays, using the POSIX signal functions may be the easiest way to
|
make a program portable. If you use `signal', then on GNU/Linux
|
make a program portable. If you use `signal', then on GNU/Linux
|
systems running GNU libc version 1, you should include `bsd/signal.h'
|
systems running GNU libc version 1, you should include `bsd/signal.h'
|
instead of `signal.h', so as to get BSD behavior. It is up to you
|
instead of `signal.h', so as to get BSD behavior. It is up to you
|
whether to support systems where `signal' has only the USG behavior, or
|
whether to support systems where `signal' has only the USG behavior, or
|
give up on them.
|
give up on them.
|
|
|
In error checks that detect "impossible" conditions, just abort.
|
In error checks that detect "impossible" conditions, just abort.
|
There is usually no point in printing any message. These checks
|
There is usually no point in printing any message. These checks
|
indicate the existence of bugs. Whoever wants to fix the bugs will have
|
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
|
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
|
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
|
are easy to examine with the debugger, so there is no point moving them
|
elsewhere.
|
elsewhere.
|
|
|
Do not use a count of errors as the exit status for a program.
|
Do not use a count of errors as the exit status for a program.
|
_That does not work_, because exit status values are limited to 8 bits
|
_That does not work_, because exit status values are limited to 8 bits
|
(0 through 255). A single run of the program might have 256 errors; if
|
(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
|
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.
|
as the status, and it will appear that the program succeeded.
|
|
|
If you make temporary files, check the `TMPDIR' environment
|
If you make temporary files, check the `TMPDIR' environment
|
variable; if that variable is defined, use the specified directory
|
variable; if that variable is defined, use the specified directory
|
instead of `/tmp'.
|
instead of `/tmp'.
|
|
|
In addition, be aware that there is a possible security problem when
|
In addition, be aware that there is a possible security problem when
|
creating temporary files in world-writable directories. In C, you can
|
creating temporary files in world-writable directories. In C, you can
|
avoid this problem by creating temporary files in this manner:
|
avoid this problem by creating temporary files in this manner:
|
|
|
fd = open(filename, O_WRONLY | O_CREAT | O_EXCL, 0600);
|
fd = open(filename, O_WRONLY | O_CREAT | O_EXCL, 0600);
|
|
|
or by using the `mkstemps' function from libiberty.
|
or by using the `mkstemps' function from libiberty.
|
|
|
In bash, use `set -C' to avoid this problem.
|
In bash, use `set -C' to avoid this problem.
|
|
|
|
|
File: standards.info, Node: Libraries, Next: Errors, Prev: Semantics, Up: Program Behavior
|
File: standards.info, Node: Libraries, Next: Errors, Prev: Semantics, Up: Program Behavior
|
|
|
4.3 Library Behavior
|
4.3 Library Behavior
|
====================
|
====================
|
|
|
Try to make library functions reentrant. If they need to do dynamic
|
Try to make library functions reentrant. If they need to do dynamic
|
storage allocation, at least try to avoid any nonreentrancy aside from
|
storage allocation, at least try to avoid any nonreentrancy aside from
|
that of `malloc' itself.
|
that of `malloc' itself.
|
|
|
Here are certain name conventions for libraries, to avoid name
|
Here are certain name conventions for libraries, to avoid name
|
conflicts.
|
conflicts.
|
|
|
Choose a name prefix for the library, more than two characters long.
|
Choose a name prefix for the library, more than two characters long.
|
All external function and variable names should start with this prefix.
|
All external function and variable names should start with this prefix.
|
In addition, there should only be one of these in any given library
|
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.
|
member. This usually means putting each one in a separate source file.
|
|
|
An exception can be made when two external symbols are always used
|
An exception can be made when two external symbols are always used
|
together, so that no reasonable program could use one without the
|
together, so that no reasonable program could use one without the
|
other; then they can both go in the same file.
|
other; then they can both go in the same file.
|
|
|
External symbols that are not documented entry points for the user
|
External symbols that are not documented entry points for the user
|
should have names beginning with `_'. The `_' should be followed by
|
should have names beginning with `_'. The `_' should be followed by
|
the chosen name prefix for the library, to prevent collisions with
|
the chosen name prefix for the library, to prevent collisions with
|
other libraries. These can go in the same files with user entry points
|
other libraries. These can go in the same files with user entry points
|
if you like.
|
if you like.
|
|
|
Static functions and variables can be used as you like and need not
|
Static functions and variables can be used as you like and need not
|
fit any naming convention.
|
fit any naming convention.
|
|
|
|
|
File: standards.info, Node: Errors, Next: User Interfaces, Prev: Libraries, Up: Program Behavior
|
File: standards.info, Node: Errors, Next: User Interfaces, Prev: Libraries, Up: Program Behavior
|
|
|
4.4 Formatting Error Messages
|
4.4 Formatting Error Messages
|
=============================
|
=============================
|
|
|
Error messages from compilers should look like this:
|
Error messages from compilers should look like this:
|
|
|
SOURCE-FILE-NAME:LINENO: MESSAGE
|
SOURCE-FILE-NAME:LINENO: MESSAGE
|
|
|
If you want to mention the column number, use one of these formats:
|
If you want to mention the column number, use one of these formats:
|
|
|
SOURCE-FILE-NAME:LINENO:COLUMN: MESSAGE
|
SOURCE-FILE-NAME:LINENO:COLUMN: MESSAGE
|
SOURCE-FILE-NAME:LINENO.COLUMN: MESSAGE
|
SOURCE-FILE-NAME:LINENO.COLUMN: MESSAGE
|
|
|
Line numbers should start from 1 at the beginning of the file, and
|
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
|
column numbers should start from 1 at the beginning of the line. (Both
|
of these conventions are chosen for compatibility.) Calculate column
|
of these conventions are chosen for compatibility.) Calculate column
|
numbers assuming that space and all ASCII printing characters have
|
numbers assuming that space and all ASCII printing characters have
|
equal width, and assuming tab stops every 8 columns.
|
equal width, and assuming tab stops every 8 columns.
|
|
|
The error message can also give both the starting and ending
|
The error message can also give both the starting and ending
|
positions of the erroneous text. There are several formats so that you
|
positions of the erroneous text. There are several formats so that you
|
can avoid redundant information such as a duplicate line number. Here
|
can avoid redundant information such as a duplicate line number. Here
|
are the possible formats:
|
are the possible formats:
|
|
|
SOURCE-FILE-NAME:LINENO-1.COLUMN-1-LINENO-2.COLUMN-2: MESSAGE
|
SOURCE-FILE-NAME:LINENO-1.COLUMN-1-LINENO-2.COLUMN-2: MESSAGE
|
SOURCE-FILE-NAME:LINENO-1.COLUMN-1-COLUMN-2: MESSAGE
|
SOURCE-FILE-NAME:LINENO-1.COLUMN-1-COLUMN-2: MESSAGE
|
SOURCE-FILE-NAME:LINENO-1-LINENO-2: MESSAGE
|
SOURCE-FILE-NAME:LINENO-1-LINENO-2: MESSAGE
|
|
|
When an error is spread over several files, you can use this format:
|
When an error is spread over several files, you can use this format:
|
|
|
FILE-1:LINENO-1.COLUMN-1-FILE-2:LINENO-2.COLUMN-2: MESSAGE
|
FILE-1:LINENO-1.COLUMN-1-FILE-2:LINENO-2.COLUMN-2: MESSAGE
|
|
|
Error messages from other noninteractive programs should look like
|
Error messages from other noninteractive programs should look like
|
this:
|
this:
|
|
|
PROGRAM:SOURCE-FILE-NAME:LINENO: MESSAGE
|
PROGRAM:SOURCE-FILE-NAME:LINENO: MESSAGE
|
|
|
when there is an appropriate source file, or like this:
|
when there is an appropriate source file, or like this:
|
|
|
PROGRAM: MESSAGE
|
PROGRAM: MESSAGE
|
|
|
when there is no relevant source file.
|
when there is no relevant source file.
|
|
|
If you want to mention the column number, use this format:
|
If you want to mention the column number, use this format:
|
|
|
PROGRAM:SOURCE-FILE-NAME:LINENO:COLUMN: MESSAGE
|
PROGRAM:SOURCE-FILE-NAME:LINENO:COLUMN: MESSAGE
|
|
|
In an interactive program (one that is reading commands from a
|
In an interactive program (one that is reading commands from a
|
terminal), it is better not to include the program name in an error
|
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
|
message. The place to indicate which program is running is in the
|
prompt or with the screen layout. (When the same program runs with
|
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
|
input from a source other than a terminal, it is not interactive and
|
would do best to print error messages using the noninteractive style.)
|
would do best to print error messages using the noninteractive style.)
|
|
|
The string MESSAGE should not begin with a capital letter when it
|
The string MESSAGE should not begin with a capital letter when it
|
follows a program name and/or file name, because that isn't the
|
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 a sentence. (The sentence conceptually starts at the
|
beginning of the line.) Also, it should not end with a period.
|
beginning of the line.) Also, it should not end with a period.
|
|
|
Error messages from interactive programs, and other messages such as
|
Error messages from interactive programs, and other messages such as
|
usage messages, should start with a capital letter. But they should not
|
usage messages, should start with a capital letter. But they should not
|
end with a period.
|
end with a period.
|
|
|
|
|
File: standards.info, Node: User Interfaces, Next: Graphical Interfaces, Prev: Errors, Up: Program Behavior
|
File: standards.info, Node: User Interfaces, Next: Graphical Interfaces, Prev: Errors, Up: Program Behavior
|
|
|
4.5 Standards for Interfaces Generally
|
4.5 Standards for Interfaces Generally
|
======================================
|
======================================
|
|
|
Please don't make the behavior of a utility depend on the name used to
|
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
|
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.
|
different name, and that should not change what it does.
|
|
|
Instead, use a run time option or a compilation switch or both to
|
Instead, use a run time option or a compilation switch or both to
|
select among the alternate behaviors.
|
select among the alternate behaviors.
|
|
|
Likewise, please don't make the behavior of the program depend on the
|
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
|
type of output device it is used with. Device independence is an
|
important principle of the system's design; do not compromise it merely
|
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
|
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
|
message syntax when using a terminal is ok, because that is a side issue
|
that people do not depend on.)
|
that people do not depend on.)
|
|
|
If you think one behavior is most useful when the output is to a
|
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
|
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
|
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
|
is useful with output to a terminal, and have an option for the other
|
behavior.
|
behavior.
|
|
|
Compatibility requires certain programs to depend on the type of
|
Compatibility requires certain programs to depend on the type of
|
output device. It would be disastrous if `ls' or `sh' did not do so in
|
output device. It would be disastrous if `ls' or `sh' did not do so in
|
the way all users expect. In some of these cases, we supplement the
|
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
|
program with a preferred alternate version that does not depend on the
|
output device type. For example, we provide a `dir' program much like
|
output device type. For example, we provide a `dir' program much like
|
`ls' except that its default output format is always multi-column
|
`ls' except that its default output format is always multi-column
|
format.
|
format.
|
|
|
|
|
File: standards.info, Node: Graphical Interfaces, Next: Command-Line Interfaces, Prev: User Interfaces, Up: Program Behavior
|
File: standards.info, Node: Graphical Interfaces, Next: Command-Line Interfaces, Prev: User Interfaces, Up: Program Behavior
|
|
|
4.6 Standards for Graphical Interfaces
|
4.6 Standards for Graphical Interfaces
|
======================================
|
======================================
|
|
|
When you write a program that provides a graphical user interface,
|
When you write a program that provides a graphical user interface,
|
please make it work with X Windows and the GTK+ toolkit unless the
|
please make it work with X Windows and the GTK+ toolkit unless the
|
functionality specifically requires some alternative (for example,
|
functionality specifically requires some alternative (for example,
|
"displaying jpeg images while in console mode").
|
"displaying jpeg images while in console mode").
|
|
|
In addition, please provide a command-line interface to control the
|
In addition, please provide a command-line interface to control the
|
functionality. (In many cases, the graphical user interface can be a
|
functionality. (In many cases, the graphical user interface can be a
|
separate program which invokes the command-line program.) This is so
|
separate program which invokes the command-line program.) This is so
|
that the same jobs can be done from scripts.
|
that the same jobs can be done from scripts.
|
|
|
Please also consider providing a CORBA interface (for use from
|
Please also consider providing a CORBA interface (for use from
|
GNOME), a library interface (for use from C), and perhaps a
|
GNOME), a library interface (for use from C), and perhaps a
|
keyboard-driven console interface (for use by users from console mode).
|
keyboard-driven console interface (for use by users from console mode).
|
Once you are doing the work to provide the functionality and the
|
Once you are doing the work to provide the functionality and the
|
graphical interface, these won't be much extra work.
|
graphical interface, these won't be much extra work.
|
|
|
|
|
File: standards.info, Node: Command-Line Interfaces, Next: Option Table, Prev: Graphical Interfaces, Up: Program Behavior
|
File: standards.info, Node: Command-Line Interfaces, Next: Option Table, Prev: Graphical Interfaces, Up: Program Behavior
|
|
|
4.7 Standards for Command Line Interfaces
|
4.7 Standards for Command Line Interfaces
|
=========================================
|
=========================================
|
|
|
It is a good idea to follow the POSIX guidelines for the command-line
|
It is a good idea to follow the POSIX guidelines for the command-line
|
options of a program. The easiest way to do this is to use `getopt' to
|
options of a program. The easiest way to do this is to use `getopt' to
|
parse them. Note that the GNU version of `getopt' will normally permit
|
parse them. Note that the GNU version of `getopt' will normally permit
|
options anywhere among the arguments unless the special argument `--'
|
options anywhere among the arguments unless the special argument `--'
|
is used. This is not what POSIX specifies; it is a GNU extension.
|
is used. This is not what POSIX specifies; it is a GNU extension.
|
|
|
Please define long-named options that are equivalent to the
|
Please define long-named options that are equivalent to the
|
single-letter Unix-style options. We hope to make GNU more user
|
single-letter Unix-style options. We hope to make GNU more user
|
friendly this way. This is easy to do with the GNU function
|
friendly this way. This is easy to do with the GNU function
|
`getopt_long'.
|
`getopt_long'.
|
|
|
One of the advantages of long-named options is that they can be
|
One of the advantages of long-named options is that they can be
|
consistent from program to program. For example, users should be able
|
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
|
to expect the "verbose" option of any GNU program which has one, to be
|
spelled precisely `--verbose'. To achieve this uniformity, look at the
|
spelled precisely `--verbose'. To achieve this uniformity, look at the
|
table of common long-option names when you choose the option names for
|
table of common long-option names when you choose the option names for
|
your program (*note Option Table::).
|
your program (*note Option Table::).
|
|
|
It is usually a good idea for file names given as ordinary arguments
|
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
|
to be input files only; any output files would be specified using
|
options (preferably `-o' or `--output'). Even if you allow an output
|
options (preferably `-o' or `--output'). Even if you allow an output
|
file name as an ordinary argument for compatibility, try to provide an
|
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
|
option as another way to specify it. This will lead to more consistency
|
among GNU utilities, and fewer idiosyncrasies for users to remember.
|
among GNU utilities, and fewer idiosyncrasies for users to remember.
|
|
|
All programs should support two standard options: `--version' and
|
All programs should support two standard options: `--version' and
|
`--help'. CGI programs should accept these as command-line options,
|
`--help'. CGI programs should accept these as command-line options,
|
and also if given as the `PATH_INFO'; for instance, visiting
|
and also if given as the `PATH_INFO'; for instance, visiting
|
`http://example.org/p.cgi/--help' in a browser should output the same
|
`http://example.org/p.cgi/--help' in a browser should output the same
|
information as invoking `p.cgi --help' from the command line.
|
information as invoking `p.cgi --help' from the command line.
|
|
|
* Menu:
|
* Menu:
|
|
|
* --version:: The standard output for --version.
|
* --version:: The standard output for --version.
|
* --help:: The standard output for --help.
|
* --help:: The standard output for --help.
|
|
|
|
|
File: standards.info, Node: --version, Next: --help, Up: Command-Line Interfaces
|
File: standards.info, Node: --version, Next: --help, Up: Command-Line Interfaces
|
|
|
4.7.1 `--version'
|
4.7.1 `--version'
|
-----------------
|
-----------------
|
|
|
The standard `--version' option should direct the program to print
|
The standard `--version' option should direct the program to print
|
information about its name, version, origin and legal status, all on
|
information about its name, version, origin and legal status, all on
|
standard output, and then exit successfully. Other options and
|
standard output, and then exit successfully. Other options and
|
arguments should be ignored once this is seen, and the program should
|
arguments should be ignored once this is seen, and the program should
|
not perform its normal function.
|
not perform its normal function.
|
|
|
The first line is meant to be easy for a program to parse; the
|
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
|
version number proper starts after the last space. In addition, it
|
contains the canonical name for this program, in this format:
|
contains the canonical name for this program, in this format:
|
|
|
GNU Emacs 19.30
|
GNU Emacs 19.30
|
|
|
The program's name should be a constant string; _don't_ compute it from
|
The program's name should be a constant string; _don't_ compute it from
|
`argv[0]'. The idea is to state the standard or canonical name for the
|
`argv[0]'. 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
|
program, not its file name. There are other ways to find out the
|
precise file name where a command is found in `PATH'.
|
precise file name where a command is found in `PATH'.
|
|
|
If the program is a subsidiary part of a larger package, mention the
|
If the program is a subsidiary part of a larger package, mention the
|
package name in parentheses, like this:
|
package name in parentheses, like this:
|
|
|
emacsserver (GNU Emacs) 19.30
|
emacsserver (GNU Emacs) 19.30
|
|
|
If the package has a version number which is different from this
|
If the package has a version number which is different from this
|
program's version number, you can mention the package version number
|
program's version number, you can mention the package version number
|
just before the close-parenthesis.
|
just before the close-parenthesis.
|
|
|
If you _need_ to mention the version numbers of libraries which are
|
If you _need_ to mention the version numbers of libraries which are
|
distributed separately from the package which contains this program,
|
distributed separately from the package which contains this program,
|
you can do so by printing an additional line of version info for each
|
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
|
library you want to mention. Use the same format for these lines as for
|
the first line.
|
the first line.
|
|
|
Please do not mention all of the libraries that the program uses
|
Please do not mention all of the libraries that the program uses
|
"just for completeness"--that would produce a lot of unhelpful clutter.
|
"just for completeness"--that would produce a lot of unhelpful clutter.
|
Please mention library version numbers only if you find in practice that
|
Please mention library version numbers only if you find in practice that
|
they are very important to you in debugging.
|
they are very important to you in debugging.
|
|
|
The following line, after the version number line or lines, should
|
The following line, after the version number line or lines, should
|
be a copyright notice. If more than one copyright notice is called
|
be a copyright notice. If more than one copyright notice is called
|
for, put each on a separate line.
|
for, put each on a separate line.
|
|
|
Next should follow a line stating the license, preferably using one
|
Next should follow a line stating the license, preferably using one
|
of abbrevations below, and a brief statement that the program is free
|
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
|
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
|
that there is no warranty, to the extent permitted by law. See
|
recommended wording below.
|
recommended wording below.
|
|
|
It is ok to finish the output with a list of the major authors of the
|
It is ok to finish the output with a list of the major authors of the
|
program, as a way of giving credit.
|
program, as a way of giving credit.
|
|
|
Here's an example of output that follows these rules:
|
Here's an example of output that follows these rules:
|
|
|
GNU hello 2.3
|
GNU hello 2.3
|
Copyright (C) 2007 Free Software Foundation, Inc.
|
Copyright (C) 2007 Free Software Foundation, Inc.
|
License GPLv3+: GNU GPL version 3 or later
|
License GPLv3+: GNU GPL version 3 or later
|
This is free software: you are free to change and redistribute it.
|
This is free software: you are free to change and redistribute it.
|
There is NO WARRANTY, to the extent permitted by law.
|
There is NO WARRANTY, to the extent permitted by law.
|
|
|
You should adapt this to your program, of course, filling in the
|
You should adapt this to your program, of course, filling in the
|
proper year, copyright holder, name of program, and the references to
|
proper year, copyright holder, name of program, and the references to
|
distribution terms, and changing the rest of the wording as necessary.
|
distribution terms, and changing the rest of the wording as necessary.
|
|
|
This copyright notice only needs to mention the most recent year in
|
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
|
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
|
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
|
these notices, if that is inconvenient, since it appeared in the first
|
line. (The rules are different for copyright notices in source files;
|
line. (The rules are different for copyright notices in source files;
|
*note Copyright Notices: (maintain)Copyright Notices.)
|
*note Copyright Notices: (maintain)Copyright Notices.)
|
|
|
Translations of the above lines must preserve the validity of the
|
Translations of the above lines must preserve the validity of the
|
copyright notices (*note Internationalization::). If the translation's
|
copyright notices (*note Internationalization::). If the translation's
|
character set supports it, the `(C)' should be replaced with the
|
character set supports it, the `(C)' should be replaced with the
|
copyright symbol, as follows:
|
copyright symbol, as follows:
|
|
|
(the official copyright symbol, which is the letter C in a circle);
|
(the official copyright symbol, which is the letter C in a circle);
|
|
|
Write the word "Copyright" exactly like that, in English. Do not
|
Write the word "Copyright" exactly like that, in English. Do not
|
translate it into another language. International treaties recognize
|
translate it into another language. International treaties recognize
|
the English word "Copyright"; translations into other languages do not
|
the English word "Copyright"; translations into other languages do not
|
have legal significance.
|
have legal significance.
|
|
|
Finally, here is the table of our suggested license abbreviations.
|
Finally, here is the table of our suggested license abbreviations.
|
Any abbreviation can be followed by `vVERSION[+]', meaning that
|
Any abbreviation can be followed by `vVERSION[+]', meaning that
|
particular version, or later versions with the `+', as shown above.
|
particular version, or later versions with the `+', as shown above.
|
|
|
In the case of exceptions for extra permissions with the GPL, we use
|
In the case of exceptions for extra permissions with the GPL, we use
|
`/' for a separator; the version number can follow the license
|
`/' for a separator; the version number can follow the license
|
abbreviation as usual, as in the examples below.
|
abbreviation as usual, as in the examples below.
|
|
|
GPL
|
GPL
|
GNU General Public License, `http://www.gnu.org/licenses/gpl.html'.
|
GNU General Public License, `http://www.gnu.org/licenses/gpl.html'.
|
|
|
LGPL
|
LGPL
|
GNU Lesser General Public License,
|
GNU Lesser General Public License,
|
`http://www.gnu.org/licenses/lgpl.html'.
|
`http://www.gnu.org/licenses/lgpl.html'.
|
|
|
GPL/Guile
|
GPL/Guile
|
GNU GPL with the exception for Guile; for example, GPLv3+/Guile
|
GNU GPL with the exception for Guile; for example, GPLv3+/Guile
|
means the GNU GPL version 3 or later, with the extra exception for
|
means the GNU GPL version 3 or later, with the extra exception for
|
Guile.
|
Guile.
|
|
|
GNU GPL with the exception for Ada.
|
GNU GPL with the exception for Ada.
|
|
|
Apache
|
Apache
|
The Apache Software Foundation license,
|
The Apache Software Foundation license,
|
`http://www.apache.org/licenses'.
|
`http://www.apache.org/licenses'.
|
|
|
Artistic
|
Artistic
|
The Artistic license used for Perl,
|
The Artistic license used for Perl,
|
`http://www.perlfoundation.org/legal'.
|
`http://www.perlfoundation.org/legal'.
|
|
|
Expat
|
Expat
|
The Expat license, `http://www.jclark.com/xml/copying.txt'.
|
The Expat license, `http://www.jclark.com/xml/copying.txt'.
|
|
|
MPL
|
MPL
|
The Mozilla Public License, `http://www.mozilla.org/MPL/'.
|
The Mozilla Public License, `http://www.mozilla.org/MPL/'.
|
|
|
OBSD
|
OBSD
|
The original (4-clause) BSD license, incompatible with the GNU GPL
|
The original (4-clause) BSD license, incompatible with the GNU GPL
|
`http://www.xfree86.org/3.3.6/COPYRIGHT2.html#6'.
|
`http://www.xfree86.org/3.3.6/COPYRIGHT2.html#6'.
|
|
|
PHP
|
PHP
|
The license used for PHP, `http://www.php.net/license/'.
|
The license used for PHP, `http://www.php.net/license/'.
|
|
|
public domain
|
public domain
|
The non-license that is being in the public domain,
|
The non-license that is being in the public domain,
|
`http://www.gnu.org/licenses/license-list.html#PublicDomain'.
|
`http://www.gnu.org/licenses/license-list.html#PublicDomain'.
|
|
|
Python
|
Python
|
The license for Python, `http://www.python.org/2.0.1/license.html'.
|
The license for Python, `http://www.python.org/2.0.1/license.html'.
|
|
|
RBSD
|
RBSD
|
The revised (3-clause) BSD, compatible with the GNU GPL,
|
The revised (3-clause) BSD, compatible with the GNU GPL,
|
`http://www.xfree86.org/3.3.6/COPYRIGHT2.html#5'.
|
`http://www.xfree86.org/3.3.6/COPYRIGHT2.html#5'.
|
|
|
X11
|
X11
|
The simple non-copyleft license used for most versions of the X
|
The simple non-copyleft license used for most versions of the X
|
Window system, `http://www.xfree86.org/3.3.6/COPYRIGHT2.html#3'.
|
Window system, `http://www.xfree86.org/3.3.6/COPYRIGHT2.html#3'.
|
|
|
Zlib
|
Zlib
|
The license for Zlib, `http://www.gzip.org/zlib/zlib_license.html'.
|
The license for Zlib, `http://www.gzip.org/zlib/zlib_license.html'.
|
|
|
|
|
More information about these licenses and many more are on the GNU
|
More information about these licenses and many more are on the GNU
|
licensing web pages, `http://www.gnu.org/licenses/license-list.html'.
|
licensing web pages, `http://www.gnu.org/licenses/license-list.html'.
|
|
|
|
|
File: standards.info, Node: --help, Prev: --version, Up: Command-Line Interfaces
|
File: standards.info, Node: --help, Prev: --version, Up: Command-Line Interfaces
|
|
|
4.7.2 `--help'
|
4.7.2 `--help'
|
--------------
|
--------------
|
|
|
The standard `--help' option should output brief documentation for how
|
The standard `--help' option should output brief documentation for how
|
to invoke the program, on standard output, then exit successfully.
|
to invoke the program, on standard output, then exit successfully.
|
Other options and arguments should be ignored once this is seen, and
|
Other options and arguments should be ignored once this is seen, and
|
the program should not perform its normal function.
|
the program should not perform its normal function.
|
|
|
Near the end of the `--help' option's output there should be a line
|
Near the end of the `--help' option's output there should be a line
|
that says where to mail bug reports. It should have this format:
|
that says where to mail bug reports. It should have this format:
|
|
|
Report bugs to MAILING-ADDRESS.
|
Report bugs to MAILING-ADDRESS.
|
|
|
|
|
File: standards.info, Node: Option Table, Next: Memory Usage, Prev: Command-Line Interfaces, Up: Program Behavior
|
File: standards.info, Node: Option Table, Next: Memory Usage, Prev: Command-Line Interfaces, Up: Program Behavior
|
|
|
4.8 Table of Long Options
|
4.8 Table of Long Options
|
=========================
|
=========================
|
|
|
Here is a table of long options used by GNU programs. It is surely
|
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
|
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,
|
want to be compatible with. If you use names not already in the table,
|
please send a list of them, with their
|
please send a list of them, with their
|
meanings, so we can update the table.
|
meanings, so we can update the table.
|
|
|
`after-date'
|
`after-date'
|
`-N' in `tar'.
|
`-N' in `tar'.
|
|
|
`all'
|
`all'
|
`-a' in `du', `ls', `nm', `stty', `uname', and `unexpand'.
|
`-a' in `du', `ls', `nm', `stty', `uname', and `unexpand'.
|
|
|
`all-text'
|
`all-text'
|
`-a' in `diff'.
|
`-a' in `diff'.
|
|
|
`almost-all'
|
`almost-all'
|
`-A' in `ls'.
|
`-A' in `ls'.
|
|
|
`append'
|
`append'
|
`-a' in `etags', `tee', `time'; `-r' in `tar'.
|
`-a' in `etags', `tee', `time'; `-r' in `tar'.
|
|
|
`archive'
|
`archive'
|
`-a' in `cp'.
|
`-a' in `cp'.
|
|
|
`archive-name'
|
`archive-name'
|
`-n' in `shar'.
|
`-n' in `shar'.
|
|
|
`arglength'
|
`arglength'
|
`-l' in `m4'.
|
`-l' in `m4'.
|
|
|
`ascii'
|
`ascii'
|
`-a' in `diff'.
|
`-a' in `diff'.
|
|
|
`assign'
|
`assign'
|
`-v' in `gawk'.
|
`-v' in `gawk'.
|
|
|
`assume-new'
|
`assume-new'
|
`-W' in Make.
|
`-W' in Make.
|
|
|
`assume-old'
|
`assume-old'
|
`-o' in Make.
|
`-o' in Make.
|
|
|
`auto-check'
|
`auto-check'
|
`-a' in `recode'.
|
`-a' in `recode'.
|
|
|
`auto-pager'
|
`auto-pager'
|
`-a' in `wdiff'.
|
`-a' in `wdiff'.
|
|
|
`auto-reference'
|
`auto-reference'
|
`-A' in `ptx'.
|
`-A' in `ptx'.
|
|
|
`avoid-wraps'
|
`avoid-wraps'
|
`-n' in `wdiff'.
|
`-n' in `wdiff'.
|
|
|
`background'
|
`background'
|
For server programs, run in the background.
|
For server programs, run in the background.
|
|
|
`backward-search'
|
`backward-search'
|
`-B' in `ctags'.
|
`-B' in `ctags'.
|
|
|
`basename'
|
`basename'
|
`-f' in `shar'.
|
`-f' in `shar'.
|
|
|
`batch'
|
`batch'
|
Used in GDB.
|
Used in GDB.
|
|
|
`baud'
|
`baud'
|
Used in GDB.
|
Used in GDB.
|
|
|
`before'
|
`before'
|
`-b' in `tac'.
|
`-b' in `tac'.
|
|
|
`binary'
|
`binary'
|
`-b' in `cpio' and `diff'.
|
`-b' in `cpio' and `diff'.
|
|
|
`bits-per-code'
|
`bits-per-code'
|
`-b' in `shar'.
|
`-b' in `shar'.
|
|
|
`block-size'
|
`block-size'
|
Used in `cpio' and `tar'.
|
Used in `cpio' and `tar'.
|
|
|
`blocks'
|
`blocks'
|
`-b' in `head' and `tail'.
|
`-b' in `head' and `tail'.
|
|
|
`break-file'
|
`break-file'
|
`-b' in `ptx'.
|
`-b' in `ptx'.
|
|
|
`brief'
|
`brief'
|
Used in various programs to make output shorter.
|
Used in various programs to make output shorter.
|
|
|
`bytes'
|
`bytes'
|
`-c' in `head', `split', and `tail'.
|
`-c' in `head', `split', and `tail'.
|
|
|
`c++'
|
`c++'
|
`-C' in `etags'.
|
`-C' in `etags'.
|
|
|
`catenate'
|
`catenate'
|
`-A' in `tar'.
|
`-A' in `tar'.
|
|
|
`cd'
|
`cd'
|
Used in various programs to specify the directory to use.
|
Used in various programs to specify the directory to use.
|
|
|
`changes'
|
`changes'
|
`-c' in `chgrp' and `chown'.
|
`-c' in `chgrp' and `chown'.
|
|
|
`classify'
|
`classify'
|
`-F' in `ls'.
|
`-F' in `ls'.
|
|
|
`colons'
|
`colons'
|
`-c' in `recode'.
|
`-c' in `recode'.
|
|
|
`command'
|
`command'
|
`-c' in `su'; `-x' in GDB.
|
`-c' in `su'; `-x' in GDB.
|
|
|
`compare'
|
`compare'
|
`-d' in `tar'.
|
`-d' in `tar'.
|
|
|
`compat'
|
`compat'
|
Used in `gawk'.
|
Used in `gawk'.
|
|
|
`compress'
|
`compress'
|
`-Z' in `tar' and `shar'.
|
`-Z' in `tar' and `shar'.
|
|
|
`concatenate'
|
`concatenate'
|
`-A' in `tar'.
|
`-A' in `tar'.
|
|
|
`confirmation'
|
`confirmation'
|
`-w' in `tar'.
|
`-w' in `tar'.
|
|
|
`context'
|
`context'
|
Used in `diff'.
|
Used in `diff'.
|
|
|
`copyleft'
|
`copyleft'
|
`-W copyleft' in `gawk'.
|
`-W copyleft' in `gawk'.
|
|
|
`copyright'
|
`copyright'
|
`-C' in `ptx', `recode', and `wdiff'; `-W copyright' in `gawk'.
|
`-C' in `ptx', `recode', and `wdiff'; `-W copyright' in `gawk'.
|
|
|
`core'
|
`core'
|
Used in GDB.
|
Used in GDB.
|
|
|
`count'
|
`count'
|
`-q' in `who'.
|
`-q' in `who'.
|
|
|
`count-links'
|
`count-links'
|
`-l' in `du'.
|
`-l' in `du'.
|
|
|
`create'
|
`create'
|
Used in `tar' and `cpio'.
|
Used in `tar' and `cpio'.
|
|
|
`cut-mark'
|
`cut-mark'
|
`-c' in `shar'.
|
`-c' in `shar'.
|
|
|
`cxref'
|
`cxref'
|
`-x' in `ctags'.
|
`-x' in `ctags'.
|
|
|
`date'
|
`date'
|
`-d' in `touch'.
|
`-d' in `touch'.
|
|
|
`debug'
|
`debug'
|
`-d' in Make and `m4'; `-t' in Bison.
|
`-d' in Make and `m4'; `-t' in Bison.
|
|
|
`define'
|
`define'
|
`-D' in `m4'.
|
`-D' in `m4'.
|
|
|
`defines'
|
`defines'
|
`-d' in Bison and `ctags'.
|
`-d' in Bison and `ctags'.
|
|
|
`delete'
|
`delete'
|
`-D' in `tar'.
|
`-D' in `tar'.
|
|
|
`dereference'
|
`dereference'
|
`-L' in `chgrp', `chown', `cpio', `du', `ls', and `tar'.
|
`-L' in `chgrp', `chown', `cpio', `du', `ls', and `tar'.
|
|
|
`dereference-args'
|
`dereference-args'
|
`-D' in `du'.
|
`-D' in `du'.
|
|
|
`device'
|
`device'
|
Specify an I/O device (special file name).
|
Specify an I/O device (special file name).
|
|
|
`diacritics'
|
`diacritics'
|
`-d' in `recode'.
|
`-d' in `recode'.
|
|
|
`dictionary-order'
|
`dictionary-order'
|
`-d' in `look'.
|
`-d' in `look'.
|
|
|
`diff'
|
`diff'
|
`-d' in `tar'.
|
`-d' in `tar'.
|
|
|
`digits'
|
`digits'
|
`-n' in `csplit'.
|
`-n' in `csplit'.
|
|
|
`directory'
|
`directory'
|
Specify the directory to use, in various programs. In `ls', it
|
Specify the directory to use, in various programs. In `ls', it
|
means to show directories themselves rather than their contents.
|
means to show directories themselves rather than their contents.
|
In `rm' and `ln', it means to not treat links to directories
|
In `rm' and `ln', it means to not treat links to directories
|
specially.
|
specially.
|
|
|
`discard-all'
|
`discard-all'
|
`-x' in `strip'.
|
`-x' in `strip'.
|
|
|
`discard-locals'
|
`discard-locals'
|
`-X' in `strip'.
|
`-X' in `strip'.
|
|
|
`dry-run'
|
`dry-run'
|
`-n' in Make.
|
`-n' in Make.
|
|
|
`ed'
|
`ed'
|
`-e' in `diff'.
|
`-e' in `diff'.
|
|
|
`elide-empty-files'
|
`elide-empty-files'
|
`-z' in `csplit'.
|
`-z' in `csplit'.
|
|
|
`end-delete'
|
`end-delete'
|
`-x' in `wdiff'.
|
`-x' in `wdiff'.
|
|
|
`end-insert'
|
`end-insert'
|
`-z' in `wdiff'.
|
`-z' in `wdiff'.
|
|
|
`entire-new-file'
|
`entire-new-file'
|
`-N' in `diff'.
|
`-N' in `diff'.
|
|
|
`environment-overrides'
|
`environment-overrides'
|
`-e' in Make.
|
`-e' in Make.
|
|
|
`eof'
|
`eof'
|
`-e' in `xargs'.
|
`-e' in `xargs'.
|
|
|
`epoch'
|
`epoch'
|
Used in GDB.
|
Used in GDB.
|
|
|
`error-limit'
|
`error-limit'
|
Used in `makeinfo'.
|
Used in `makeinfo'.
|
|
|
`error-output'
|
`error-output'
|
`-o' in `m4'.
|
`-o' in `m4'.
|
|
|
`escape'
|
`escape'
|
`-b' in `ls'.
|
`-b' in `ls'.
|
|
|
`exclude-from'
|
`exclude-from'
|
`-X' in `tar'.
|
`-X' in `tar'.
|
|
|
`exec'
|
`exec'
|
Used in GDB.
|
Used in GDB.
|
|
|
`exit'
|
`exit'
|
`-x' in `xargs'.
|
`-x' in `xargs'.
|
|
|
`exit-0'
|
`exit-0'
|
`-e' in `unshar'.
|
`-e' in `unshar'.
|
|
|
`expand-tabs'
|
`expand-tabs'
|
`-t' in `diff'.
|
`-t' in `diff'.
|
|
|
`expression'
|
`expression'
|
`-e' in `sed'.
|
`-e' in `sed'.
|
|
|
`extern-only'
|
`extern-only'
|
`-g' in `nm'.
|
`-g' in `nm'.
|
|
|
`extract'
|
`extract'
|
`-i' in `cpio'; `-x' in `tar'.
|
`-i' in `cpio'; `-x' in `tar'.
|
|
|
`faces'
|
`faces'
|
`-f' in `finger'.
|
`-f' in `finger'.
|
|
|
`fast'
|
`fast'
|
`-f' in `su'.
|
`-f' in `su'.
|
|
|
`fatal-warnings'
|
`fatal-warnings'
|
`-E' in `m4'.
|
`-E' in `m4'.
|
|
|
`file'
|
`file'
|
`-f' in `info', `gawk', Make, `mt', and `tar'; `-n' in `sed'; `-r'
|
`-f' in `info', `gawk', Make, `mt', and `tar'; `-n' in `sed'; `-r'
|
in `touch'.
|
in `touch'.
|
|
|
`field-separator'
|
`field-separator'
|
`-F' in `gawk'.
|
`-F' in `gawk'.
|
|
|
`file-prefix'
|
`file-prefix'
|
`-b' in Bison.
|
`-b' in Bison.
|
|
|
`file-type'
|
`file-type'
|
`-F' in `ls'.
|
`-F' in `ls'.
|
|
|
`files-from'
|
`files-from'
|
`-T' in `tar'.
|
`-T' in `tar'.
|
|
|
`fill-column'
|
`fill-column'
|
Used in `makeinfo'.
|
Used in `makeinfo'.
|
|
|
`flag-truncation'
|
`flag-truncation'
|
`-F' in `ptx'.
|
`-F' in `ptx'.
|
|
|
`fixed-output-files'
|
`fixed-output-files'
|
`-y' in Bison.
|
`-y' in Bison.
|
|
|
`follow'
|
`follow'
|
`-f' in `tail'.
|
`-f' in `tail'.
|
|
|
`footnote-style'
|
`footnote-style'
|
Used in `makeinfo'.
|
Used in `makeinfo'.
|
|
|
`force'
|
`force'
|
`-f' in `cp', `ln', `mv', and `rm'.
|
`-f' in `cp', `ln', `mv', and `rm'.
|
|
|
`force-prefix'
|
`force-prefix'
|
`-F' in `shar'.
|
`-F' in `shar'.
|
|
|
`foreground'
|
`foreground'
|
For server programs, run in the foreground; in other words, don't
|
For server programs, run in the foreground; in other words, don't
|
do anything special to run the server in the background.
|
do anything special to run the server in the background.
|
|
|
`format'
|
`format'
|
Used in `ls', `time', and `ptx'.
|
Used in `ls', `time', and `ptx'.
|
|
|
`freeze-state'
|
`freeze-state'
|
`-F' in `m4'.
|
`-F' in `m4'.
|
|
|
`fullname'
|
`fullname'
|
Used in GDB.
|
Used in GDB.
|
|
|
`gap-size'
|
`gap-size'
|
`-g' in `ptx'.
|
`-g' in `ptx'.
|
|
|
`get'
|
`get'
|
`-x' in `tar'.
|
`-x' in `tar'.
|
|
|
`graphic'
|
`graphic'
|
`-i' in `ul'.
|
`-i' in `ul'.
|
|
|
`graphics'
|
`graphics'
|
`-g' in `recode'.
|
`-g' in `recode'.
|
|
|
`group'
|
`group'
|
`-g' in `install'.
|
`-g' in `install'.
|
|
|
`gzip'
|
`gzip'
|
`-z' in `tar' and `shar'.
|
`-z' in `tar' and `shar'.
|
|
|
`hashsize'
|
`hashsize'
|
`-H' in `m4'.
|
`-H' in `m4'.
|
|
|
`header'
|
`header'
|
`-h' in `objdump' and `recode'
|
`-h' in `objdump' and `recode'
|
|
|
`heading'
|
`heading'
|
`-H' in `who'.
|
`-H' in `who'.
|
|
|
`help'
|
`help'
|
Used to ask for brief usage information.
|
Used to ask for brief usage information.
|
|
|
`here-delimiter'
|
`here-delimiter'
|
`-d' in `shar'.
|
`-d' in `shar'.
|
|
|
`hide-control-chars'
|
`hide-control-chars'
|
`-q' in `ls'.
|
`-q' in `ls'.
|
|
|
`html'
|
`html'
|
In `makeinfo', output HTML.
|
In `makeinfo', output HTML.
|
|
|
`idle'
|
`idle'
|
`-u' in `who'.
|
`-u' in `who'.
|
|
|
`ifdef'
|
`ifdef'
|
`-D' in `diff'.
|
`-D' in `diff'.
|
|
|
`ignore'
|
`ignore'
|
`-I' in `ls'; `-x' in `recode'.
|
`-I' in `ls'; `-x' in `recode'.
|
|
|
`ignore-all-space'
|
`ignore-all-space'
|
`-w' in `diff'.
|
`-w' in `diff'.
|
|
|
`ignore-backups'
|
`ignore-backups'
|
`-B' in `ls'.
|
`-B' in `ls'.
|
|
|
`ignore-blank-lines'
|
`ignore-blank-lines'
|
`-B' in `diff'.
|
`-B' in `diff'.
|
|
|
`ignore-case'
|
`ignore-case'
|
`-f' in `look' and `ptx'; `-i' in `diff' and `wdiff'.
|
`-f' in `look' and `ptx'; `-i' in `diff' and `wdiff'.
|
|
|
`ignore-errors'
|
`ignore-errors'
|
`-i' in Make.
|
`-i' in Make.
|
|
|
`ignore-file'
|
`ignore-file'
|
`-i' in `ptx'.
|
`-i' in `ptx'.
|
|
|
`ignore-indentation'
|
`ignore-indentation'
|
`-I' in `etags'.
|
`-I' in `etags'.
|
|
|
`ignore-init-file'
|
`ignore-init-file'
|
`-f' in Oleo.
|
`-f' in Oleo.
|
|
|
`ignore-interrupts'
|
`ignore-interrupts'
|
`-i' in `tee'.
|
`-i' in `tee'.
|
|
|
`ignore-matching-lines'
|
`ignore-matching-lines'
|
`-I' in `diff'.
|
`-I' in `diff'.
|
|
|
`ignore-space-change'
|
`ignore-space-change'
|
`-b' in `diff'.
|
`-b' in `diff'.
|
|
|
`ignore-zeros'
|
`ignore-zeros'
|
`-i' in `tar'.
|
`-i' in `tar'.
|
|
|
`include'
|
`include'
|
`-i' in `etags'; `-I' in `m4'.
|
`-i' in `etags'; `-I' in `m4'.
|
|
|
`include-dir'
|
`include-dir'
|
`-I' in Make.
|
`-I' in Make.
|
|
|
`incremental'
|
`incremental'
|
`-G' in `tar'.
|
`-G' in `tar'.
|
|
|
`info'
|
`info'
|
`-i', `-l', and `-m' in Finger.
|
`-i', `-l', and `-m' in Finger.
|
|
|
`init-file'
|
`init-file'
|
In some programs, specify the name of the file to read as the
|
In some programs, specify the name of the file to read as the
|
user's init file.
|
user's init file.
|
|
|
`initial'
|
`initial'
|
`-i' in `expand'.
|
`-i' in `expand'.
|
|
|
`initial-tab'
|
`initial-tab'
|
`-T' in `diff'.
|
`-T' in `diff'.
|
|
|
`inode'
|
`inode'
|
`-i' in `ls'.
|
`-i' in `ls'.
|
|
|
`interactive'
|
`interactive'
|
`-i' in `cp', `ln', `mv', `rm'; `-e' in `m4'; `-p' in `xargs';
|
`-i' in `cp', `ln', `mv', `rm'; `-e' in `m4'; `-p' in `xargs';
|
`-w' in `tar'.
|
`-w' in `tar'.
|
|
|
`intermix-type'
|
`intermix-type'
|
`-p' in `shar'.
|
`-p' in `shar'.
|
|
|
`iso-8601'
|
`iso-8601'
|
Used in `date'
|
Used in `date'
|
|
|
`jobs'
|
`jobs'
|
`-j' in Make.
|
`-j' in Make.
|
|
|
`just-print'
|
`just-print'
|
`-n' in Make.
|
`-n' in Make.
|
|
|
`keep-going'
|
`keep-going'
|
`-k' in Make.
|
`-k' in Make.
|
|
|
`keep-files'
|
`keep-files'
|
`-k' in `csplit'.
|
`-k' in `csplit'.
|
|
|
`kilobytes'
|
`kilobytes'
|
`-k' in `du' and `ls'.
|
`-k' in `du' and `ls'.
|
|
|
`language'
|
`language'
|
`-l' in `etags'.
|
`-l' in `etags'.
|
|
|
`less-mode'
|
`less-mode'
|
`-l' in `wdiff'.
|
`-l' in `wdiff'.
|
|
|
`level-for-gzip'
|
`level-for-gzip'
|
`-g' in `shar'.
|
`-g' in `shar'.
|
|
|
`line-bytes'
|
`line-bytes'
|
`-C' in `split'.
|
`-C' in `split'.
|
|
|
`lines'
|
`lines'
|
Used in `split', `head', and `tail'.
|
Used in `split', `head', and `tail'.
|
|
|
`link'
|
`link'
|
`-l' in `cpio'.
|
`-l' in `cpio'.
|
|
|
`lint'
|
`lint'
|
`lint-old'
|
`lint-old'
|
Used in `gawk'.
|
Used in `gawk'.
|
|
|
`list'
|
`list'
|
`-t' in `cpio'; `-l' in `recode'.
|
`-t' in `cpio'; `-l' in `recode'.
|
|
|
`list'
|
`list'
|
`-t' in `tar'.
|
`-t' in `tar'.
|
|
|
`literal'
|
`literal'
|
`-N' in `ls'.
|
`-N' in `ls'.
|
|
|
`load-average'
|
`load-average'
|
`-l' in Make.
|
`-l' in Make.
|
|
|
`login'
|
`login'
|
Used in `su'.
|
Used in `su'.
|
|
|
`machine'
|
`machine'
|
Used in `uname'.
|
Used in `uname'.
|
|
|
`macro-name'
|
`macro-name'
|
`-M' in `ptx'.
|
`-M' in `ptx'.
|
|
|
`mail'
|
`mail'
|
`-m' in `hello' and `uname'.
|
`-m' in `hello' and `uname'.
|
|
|
`make-directories'
|
`make-directories'
|
`-d' in `cpio'.
|
`-d' in `cpio'.
|
|
|
`makefile'
|
`makefile'
|
`-f' in Make.
|
`-f' in Make.
|
|
|
`mapped'
|
`mapped'
|
Used in GDB.
|
Used in GDB.
|
|
|
`max-args'
|
`max-args'
|
`-n' in `xargs'.
|
`-n' in `xargs'.
|
|
|
`max-chars'
|
`max-chars'
|
`-n' in `xargs'.
|
`-n' in `xargs'.
|
|
|
`max-lines'
|
`max-lines'
|
`-l' in `xargs'.
|
`-l' in `xargs'.
|
|
|
`max-load'
|
`max-load'
|
`-l' in Make.
|
`-l' in Make.
|
|
|
`max-procs'
|
`max-procs'
|
`-P' in `xargs'.
|
`-P' in `xargs'.
|
|
|
`mesg'
|
`mesg'
|
`-T' in `who'.
|
`-T' in `who'.
|
|
|
`message'
|
`message'
|
`-T' in `who'.
|
`-T' in `who'.
|
|
|
`minimal'
|
`minimal'
|
`-d' in `diff'.
|
`-d' in `diff'.
|
|
|
`mixed-uuencode'
|
`mixed-uuencode'
|
`-M' in `shar'.
|
`-M' in `shar'.
|
|
|
`mode'
|
`mode'
|
`-m' in `install', `mkdir', and `mkfifo'.
|
`-m' in `install', `mkdir', and `mkfifo'.
|
|
|
`modification-time'
|
`modification-time'
|
`-m' in `tar'.
|
`-m' in `tar'.
|
|
|
`multi-volume'
|
`multi-volume'
|
`-M' in `tar'.
|
`-M' in `tar'.
|
|
|
`name-prefix'
|
`name-prefix'
|
`-a' in Bison.
|
`-a' in Bison.
|
|
|
`nesting-limit'
|
`nesting-limit'
|
`-L' in `m4'.
|
`-L' in `m4'.
|
|
|
`net-headers'
|
`net-headers'
|
`-a' in `shar'.
|
`-a' in `shar'.
|
|
|
`new-file'
|
`new-file'
|
`-W' in Make.
|
`-W' in Make.
|
|
|
`no-builtin-rules'
|
`no-builtin-rules'
|
`-r' in Make.
|
`-r' in Make.
|
|
|
`no-character-count'
|
`no-character-count'
|
`-w' in `shar'.
|
`-w' in `shar'.
|
|
|
`no-check-existing'
|
`no-check-existing'
|
`-x' in `shar'.
|
`-x' in `shar'.
|
|
|
`no-common'
|
`no-common'
|
`-3' in `wdiff'.
|
`-3' in `wdiff'.
|
|
|
`no-create'
|
`no-create'
|
`-c' in `touch'.
|
`-c' in `touch'.
|
|
|
`no-defines'
|
`no-defines'
|
`-D' in `etags'.
|
`-D' in `etags'.
|
|
|
`no-deleted'
|
`no-deleted'
|
`-1' in `wdiff'.
|
`-1' in `wdiff'.
|
|
|
`no-dereference'
|
`no-dereference'
|
`-d' in `cp'.
|
`-d' in `cp'.
|
|
|
`no-inserted'
|
`no-inserted'
|
`-2' in `wdiff'.
|
`-2' in `wdiff'.
|
|
|
`no-keep-going'
|
`no-keep-going'
|
`-S' in Make.
|
`-S' in Make.
|
|
|
`no-lines'
|
`no-lines'
|
`-l' in Bison.
|
`-l' in Bison.
|
|
|
`no-piping'
|
`no-piping'
|
`-P' in `shar'.
|
`-P' in `shar'.
|
|
|
`no-prof'
|
`no-prof'
|
`-e' in `gprof'.
|
`-e' in `gprof'.
|
|
|
`no-regex'
|
`no-regex'
|
`-R' in `etags'.
|
`-R' in `etags'.
|
|
|
`no-sort'
|
`no-sort'
|
`-p' in `nm'.
|
`-p' in `nm'.
|
|
|
`no-splash'
|
`no-splash'
|
Don't print a startup splash screen.
|
Don't print a startup splash screen.
|
|
|
`no-split'
|
`no-split'
|
Used in `makeinfo'.
|
Used in `makeinfo'.
|
|
|
`no-static'
|
`no-static'
|
`-a' in `gprof'.
|
`-a' in `gprof'.
|
|
|
`no-time'
|
`no-time'
|
`-E' in `gprof'.
|
`-E' in `gprof'.
|
|
|
`no-timestamp'
|
`no-timestamp'
|
`-m' in `shar'.
|
`-m' in `shar'.
|
|
|
`no-validate'
|
`no-validate'
|
Used in `makeinfo'.
|
Used in `makeinfo'.
|
|
|
`no-wait'
|
`no-wait'
|
Used in `emacsclient'.
|
Used in `emacsclient'.
|
|
|
`no-warn'
|
`no-warn'
|
Used in various programs to inhibit warnings.
|
Used in various programs to inhibit warnings.
|
|
|
`node'
|
`node'
|
`-n' in `info'.
|
`-n' in `info'.
|
|
|
`nodename'
|
`nodename'
|
`-n' in `uname'.
|
`-n' in `uname'.
|
|
|
`nonmatching'
|
`nonmatching'
|
`-f' in `cpio'.
|
`-f' in `cpio'.
|
|
|
`nstuff'
|
`nstuff'
|
`-n' in `objdump'.
|
`-n' in `objdump'.
|
|
|
`null'
|
`null'
|
`-0' in `xargs'.
|
`-0' in `xargs'.
|
|
|
`number'
|
`number'
|
`-n' in `cat'.
|
`-n' in `cat'.
|
|
|
`number-nonblank'
|
`number-nonblank'
|
`-b' in `cat'.
|
`-b' in `cat'.
|
|
|
`numeric-sort'
|
`numeric-sort'
|
`-n' in `nm'.
|
`-n' in `nm'.
|
|
|
`numeric-uid-gid'
|
`numeric-uid-gid'
|
`-n' in `cpio' and `ls'.
|
`-n' in `cpio' and `ls'.
|
|
|
`nx'
|
`nx'
|
Used in GDB.
|
Used in GDB.
|
|
|
`old-archive'
|
`old-archive'
|
`-o' in `tar'.
|
`-o' in `tar'.
|
|
|
`old-file'
|
`old-file'
|
`-o' in Make.
|
`-o' in Make.
|
|
|
`one-file-system'
|
`one-file-system'
|
`-l' in `tar', `cp', and `du'.
|
`-l' in `tar', `cp', and `du'.
|
|
|
`only-file'
|
`only-file'
|
`-o' in `ptx'.
|
`-o' in `ptx'.
|
|
|
`only-prof'
|
`only-prof'
|
`-f' in `gprof'.
|
`-f' in `gprof'.
|
|
|
`only-time'
|
`only-time'
|
`-F' in `gprof'.
|
`-F' in `gprof'.
|
|
|
`options'
|
`options'
|
`-o' in `getopt', `fdlist', `fdmount', `fdmountd', and `fdumount'.
|
`-o' in `getopt', `fdlist', `fdmount', `fdmountd', and `fdumount'.
|
|
|
`output'
|
`output'
|
In various programs, specify the output file name.
|
In various programs, specify the output file name.
|
|
|
`output-prefix'
|
`output-prefix'
|
`-o' in `shar'.
|
`-o' in `shar'.
|
|
|
`override'
|
`override'
|
`-o' in `rm'.
|
`-o' in `rm'.
|
|
|
`overwrite'
|
`overwrite'
|
`-c' in `unshar'.
|
`-c' in `unshar'.
|
|
|
`owner'
|
`owner'
|
`-o' in `install'.
|
`-o' in `install'.
|
|
|
`paginate'
|
`paginate'
|
`-l' in `diff'.
|
`-l' in `diff'.
|
|
|
`paragraph-indent'
|
`paragraph-indent'
|
Used in `makeinfo'.
|
Used in `makeinfo'.
|
|
|
`parents'
|
`parents'
|
`-p' in `mkdir' and `rmdir'.
|
`-p' in `mkdir' and `rmdir'.
|
|
|
`pass-all'
|
`pass-all'
|
`-p' in `ul'.
|
`-p' in `ul'.
|
|
|
`pass-through'
|
`pass-through'
|
`-p' in `cpio'.
|
`-p' in `cpio'.
|
|
|
`port'
|
`port'
|
`-P' in `finger'.
|
`-P' in `finger'.
|
|
|
`portability'
|
`portability'
|
`-c' in `cpio' and `tar'.
|
`-c' in `cpio' and `tar'.
|
|
|
`posix'
|
`posix'
|
Used in `gawk'.
|
Used in `gawk'.
|
|
|
`prefix-builtins'
|
`prefix-builtins'
|
`-P' in `m4'.
|
`-P' in `m4'.
|
|
|
`prefix'
|
`prefix'
|
`-f' in `csplit'.
|
`-f' in `csplit'.
|
|
|
`preserve'
|
`preserve'
|
Used in `tar' and `cp'.
|
Used in `tar' and `cp'.
|
|
|
`preserve-environment'
|
`preserve-environment'
|
`-p' in `su'.
|
`-p' in `su'.
|
|
|
`preserve-modification-time'
|
`preserve-modification-time'
|
`-m' in `cpio'.
|
`-m' in `cpio'.
|
|
|
`preserve-order'
|
`preserve-order'
|
`-s' in `tar'.
|
`-s' in `tar'.
|
|
|
`preserve-permissions'
|
`preserve-permissions'
|
`-p' in `tar'.
|
`-p' in `tar'.
|
|
|
`print'
|
`print'
|
`-l' in `diff'.
|
`-l' in `diff'.
|
|
|
`print-chars'
|
`print-chars'
|
`-L' in `cmp'.
|
`-L' in `cmp'.
|
|
|
`print-data-base'
|
`print-data-base'
|
`-p' in Make.
|
`-p' in Make.
|
|
|
`print-directory'
|
`print-directory'
|
`-w' in Make.
|
`-w' in Make.
|
|
|
`print-file-name'
|
`print-file-name'
|
`-o' in `nm'.
|
`-o' in `nm'.
|
|
|
`print-symdefs'
|
`print-symdefs'
|
`-s' in `nm'.
|
`-s' in `nm'.
|
|
|
`printer'
|
`printer'
|
`-p' in `wdiff'.
|
`-p' in `wdiff'.
|
|
|
`prompt'
|
`prompt'
|
`-p' in `ed'.
|
`-p' in `ed'.
|
|
|
`proxy'
|
`proxy'
|
Specify an HTTP proxy.
|
Specify an HTTP proxy.
|
|
|
`query-user'
|
`query-user'
|
`-X' in `shar'.
|
`-X' in `shar'.
|
|
|
`question'
|
`question'
|
`-q' in Make.
|
`-q' in Make.
|
|
|
`quiet'
|
`quiet'
|
Used in many programs to inhibit the usual output. Every program
|
Used in many programs to inhibit the usual output. Every program
|
accepting `--quiet' should accept `--silent' as a synonym.
|
accepting `--quiet' should accept `--silent' as a synonym.
|
|
|
`quiet-unshar'
|
`quiet-unshar'
|
`-Q' in `shar'
|
`-Q' in `shar'
|
|
|
`quote-name'
|
`quote-name'
|
`-Q' in `ls'.
|
`-Q' in `ls'.
|
|
|
`rcs'
|
`rcs'
|
`-n' in `diff'.
|
`-n' in `diff'.
|
|
|
`re-interval'
|
`re-interval'
|
Used in `gawk'.
|
Used in `gawk'.
|
|
|
`read-full-blocks'
|
`read-full-blocks'
|
`-B' in `tar'.
|
`-B' in `tar'.
|
|
|
`readnow'
|
`readnow'
|
Used in GDB.
|
Used in GDB.
|
|
|
`recon'
|
`recon'
|
`-n' in Make.
|
`-n' in Make.
|
|
|
`record-number'
|
`record-number'
|
`-R' in `tar'.
|
`-R' in `tar'.
|
|
|
`recursive'
|
`recursive'
|
Used in `chgrp', `chown', `cp', `ls', `diff', and `rm'.
|
Used in `chgrp', `chown', `cp', `ls', `diff', and `rm'.
|
|
|
`reference-limit'
|
`reference-limit'
|
Used in `makeinfo'.
|
Used in `makeinfo'.
|
|
|
`references'
|
`references'
|
`-r' in `ptx'.
|
`-r' in `ptx'.
|
|
|
`regex'
|
`regex'
|
`-r' in `tac' and `etags'.
|
`-r' in `tac' and `etags'.
|
|
|
`release'
|
`release'
|
`-r' in `uname'.
|
`-r' in `uname'.
|
|
|
`reload-state'
|
`reload-state'
|
`-R' in `m4'.
|
`-R' in `m4'.
|
|
|
`relocation'
|
`relocation'
|
`-r' in `objdump'.
|
`-r' in `objdump'.
|
|
|
`rename'
|
`rename'
|
`-r' in `cpio'.
|
`-r' in `cpio'.
|
|
|
`replace'
|
`replace'
|
`-i' in `xargs'.
|
`-i' in `xargs'.
|
|
|
`report-identical-files'
|
`report-identical-files'
|
`-s' in `diff'.
|
`-s' in `diff'.
|
|
|
`reset-access-time'
|
`reset-access-time'
|
`-a' in `cpio'.
|
`-a' in `cpio'.
|
|
|
`reverse'
|
`reverse'
|
`-r' in `ls' and `nm'.
|
`-r' in `ls' and `nm'.
|
|
|
`reversed-ed'
|
`reversed-ed'
|
`-f' in `diff'.
|
`-f' in `diff'.
|
|
|
`right-side-defs'
|
`right-side-defs'
|
`-R' in `ptx'.
|
`-R' in `ptx'.
|
|
|
`same-order'
|
`same-order'
|
`-s' in `tar'.
|
`-s' in `tar'.
|
|
|
`same-permissions'
|
`same-permissions'
|
`-p' in `tar'.
|
`-p' in `tar'.
|
|
|
`save'
|
`save'
|
`-g' in `stty'.
|
`-g' in `stty'.
|
|
|
`se'
|
`se'
|
Used in GDB.
|
Used in GDB.
|
|
|
`sentence-regexp'
|
`sentence-regexp'
|
`-S' in `ptx'.
|
`-S' in `ptx'.
|
|
|
`separate-dirs'
|
`separate-dirs'
|
`-S' in `du'.
|
`-S' in `du'.
|
|
|
`separator'
|
`separator'
|
`-s' in `tac'.
|
`-s' in `tac'.
|
|
|
`sequence'
|
`sequence'
|
Used by `recode' to chose files or pipes for sequencing passes.
|
Used by `recode' to chose files or pipes for sequencing passes.
|
|
|
`shell'
|
`shell'
|
`-s' in `su'.
|
`-s' in `su'.
|
|
|
`show-all'
|
`show-all'
|
`-A' in `cat'.
|
`-A' in `cat'.
|
|
|
`show-c-function'
|
`show-c-function'
|
`-p' in `diff'.
|
`-p' in `diff'.
|
|
|
`show-ends'
|
`show-ends'
|
`-E' in `cat'.
|
`-E' in `cat'.
|
|
|
`show-function-line'
|
`show-function-line'
|
`-F' in `diff'.
|
`-F' in `diff'.
|
|
|
`show-tabs'
|
`show-tabs'
|
`-T' in `cat'.
|
`-T' in `cat'.
|
|
|
`silent'
|
`silent'
|
Used in many programs to inhibit the usual output. Every program
|
Used in many programs to inhibit the usual output. Every program
|
accepting `--silent' should accept `--quiet' as a synonym.
|
accepting `--silent' should accept `--quiet' as a synonym.
|
|
|
`size'
|
`size'
|
`-s' in `ls'.
|
`-s' in `ls'.
|
|
|
`socket'
|
`socket'
|
Specify a file descriptor for a network server to use for its
|
Specify a file descriptor for a network server to use for its
|
socket, instead of opening and binding a new socket. This
|
socket, instead of opening and binding a new socket. This
|
provides a way to run, in a non-privileged process, a server that
|
provides a way to run, in a non-privileged process, a server that
|
normally needs a reserved port number.
|
normally needs a reserved port number.
|
|
|
`sort'
|
`sort'
|
Used in `ls'.
|
Used in `ls'.
|
|
|
`source'
|
`source'
|
`-W source' in `gawk'.
|
`-W source' in `gawk'.
|
|
|
`sparse'
|
`sparse'
|
`-S' in `tar'.
|
`-S' in `tar'.
|
|
|
`speed-large-files'
|
`speed-large-files'
|
`-H' in `diff'.
|
`-H' in `diff'.
|
|
|
`split-at'
|
`split-at'
|
`-E' in `unshar'.
|
`-E' in `unshar'.
|
|
|
`split-size-limit'
|
`split-size-limit'
|
`-L' in `shar'.
|
`-L' in `shar'.
|
|
|
`squeeze-blank'
|
`squeeze-blank'
|
`-s' in `cat'.
|
`-s' in `cat'.
|
|
|
`start-delete'
|
`start-delete'
|
`-w' in `wdiff'.
|
`-w' in `wdiff'.
|
|
|
`start-insert'
|
`start-insert'
|
`-y' in `wdiff'.
|
`-y' in `wdiff'.
|
|
|
`starting-file'
|
`starting-file'
|
Used in `tar' and `diff' to specify which file within a directory
|
Used in `tar' and `diff' to specify which file within a directory
|
to start processing with.
|
to start processing with.
|
|
|
`statistics'
|
`statistics'
|
`-s' in `wdiff'.
|
`-s' in `wdiff'.
|
|
|
`stdin-file-list'
|
`stdin-file-list'
|
`-S' in `shar'.
|
`-S' in `shar'.
|
|
|
`stop'
|
`stop'
|
`-S' in Make.
|
`-S' in Make.
|
|
|
`strict'
|
`strict'
|
`-s' in `recode'.
|
`-s' in `recode'.
|
|
|
`strip'
|
`strip'
|
`-s' in `install'.
|
`-s' in `install'.
|
|
|
`strip-all'
|
`strip-all'
|
`-s' in `strip'.
|
`-s' in `strip'.
|
|
|
`strip-debug'
|
`strip-debug'
|
`-S' in `strip'.
|
`-S' in `strip'.
|
|
|
`submitter'
|
`submitter'
|
`-s' in `shar'.
|
`-s' in `shar'.
|
|
|
`suffix'
|
`suffix'
|
`-S' in `cp', `ln', `mv'.
|
`-S' in `cp', `ln', `mv'.
|
|
|
`suffix-format'
|
`suffix-format'
|
`-b' in `csplit'.
|
`-b' in `csplit'.
|
|
|
`sum'
|
`sum'
|
`-s' in `gprof'.
|
`-s' in `gprof'.
|
|
|
`summarize'
|
`summarize'
|
`-s' in `du'.
|
`-s' in `du'.
|
|
|
`symbolic'
|
`symbolic'
|
`-s' in `ln'.
|
`-s' in `ln'.
|
|
|
`symbols'
|
`symbols'
|
Used in GDB and `objdump'.
|
Used in GDB and `objdump'.
|
|
|
`synclines'
|
`synclines'
|
`-s' in `m4'.
|
`-s' in `m4'.
|
|
|
`sysname'
|
`sysname'
|
`-s' in `uname'.
|
`-s' in `uname'.
|
|
|
`tabs'
|
`tabs'
|
`-t' in `expand' and `unexpand'.
|
`-t' in `expand' and `unexpand'.
|
|
|
`tabsize'
|
`tabsize'
|
`-T' in `ls'.
|
`-T' in `ls'.
|
|
|
`terminal'
|
`terminal'
|
`-T' in `tput' and `ul'. `-t' in `wdiff'.
|
`-T' in `tput' and `ul'. `-t' in `wdiff'.
|
|
|
`text'
|
`text'
|
`-a' in `diff'.
|
`-a' in `diff'.
|
|
|
`text-files'
|
`text-files'
|
`-T' in `shar'.
|
`-T' in `shar'.
|
|
|
`time'
|
`time'
|
Used in `ls' and `touch'.
|
Used in `ls' and `touch'.
|
|
|
`timeout'
|
`timeout'
|
Specify how long to wait before giving up on some operation.
|
Specify how long to wait before giving up on some operation.
|
|
|
`to-stdout'
|
`to-stdout'
|
`-O' in `tar'.
|
`-O' in `tar'.
|
|
|
`total'
|
`total'
|
`-c' in `du'.
|
`-c' in `du'.
|
|
|
`touch'
|
`touch'
|
`-t' in Make, `ranlib', and `recode'.
|
`-t' in Make, `ranlib', and `recode'.
|
|
|
`trace'
|
`trace'
|
`-t' in `m4'.
|
`-t' in `m4'.
|
|
|
`traditional'
|
`traditional'
|
`-t' in `hello'; `-W traditional' in `gawk'; `-G' in `ed', `m4',
|
`-t' in `hello'; `-W traditional' in `gawk'; `-G' in `ed', `m4',
|
and `ptx'.
|
and `ptx'.
|
|
|
`tty'
|
`tty'
|
Used in GDB.
|
Used in GDB.
|
|
|
`typedefs'
|
`typedefs'
|
`-t' in `ctags'.
|
`-t' in `ctags'.
|
|
|
`typedefs-and-c++'
|
`typedefs-and-c++'
|
`-T' in `ctags'.
|
`-T' in `ctags'.
|
|
|
`typeset-mode'
|
`typeset-mode'
|
`-t' in `ptx'.
|
`-t' in `ptx'.
|
|
|
`uncompress'
|
`uncompress'
|
`-z' in `tar'.
|
`-z' in `tar'.
|
|
|
`unconditional'
|
`unconditional'
|
`-u' in `cpio'.
|
`-u' in `cpio'.
|
|
|
`undefine'
|
`undefine'
|
`-U' in `m4'.
|
`-U' in `m4'.
|
|
|
`undefined-only'
|
`undefined-only'
|
`-u' in `nm'.
|
`-u' in `nm'.
|
|
|
`update'
|
`update'
|
`-u' in `cp', `ctags', `mv', `tar'.
|
`-u' in `cp', `ctags', `mv', `tar'.
|
|
|
`usage'
|
`usage'
|
Used in `gawk'; same as `--help'.
|
Used in `gawk'; same as `--help'.
|
|
|
`uuencode'
|
`uuencode'
|
`-B' in `shar'.
|
`-B' in `shar'.
|
|
|
`vanilla-operation'
|
`vanilla-operation'
|
`-V' in `shar'.
|
`-V' in `shar'.
|
|
|
`verbose'
|
`verbose'
|
Print more information about progress. Many programs support this.
|
Print more information about progress. Many programs support this.
|
|
|
`verify'
|
`verify'
|
`-W' in `tar'.
|
`-W' in `tar'.
|
|
|
`version'
|
`version'
|
Print the version number.
|
Print the version number.
|
|
|
`version-control'
|
`version-control'
|
`-V' in `cp', `ln', `mv'.
|
`-V' in `cp', `ln', `mv'.
|
|
|
`vgrind'
|
`vgrind'
|
`-v' in `ctags'.
|
`-v' in `ctags'.
|
|
|
`volume'
|
`volume'
|
`-V' in `tar'.
|
`-V' in `tar'.
|
|
|
`what-if'
|
`what-if'
|
`-W' in Make.
|
`-W' in Make.
|
|
|
`whole-size-limit'
|
`whole-size-limit'
|
`-l' in `shar'.
|
`-l' in `shar'.
|
|
|
`width'
|
`width'
|
`-w' in `ls' and `ptx'.
|
`-w' in `ls' and `ptx'.
|
|
|
`word-regexp'
|
`word-regexp'
|
`-W' in `ptx'.
|
`-W' in `ptx'.
|
|
|
`writable'
|
`writable'
|
`-T' in `who'.
|
`-T' in `who'.
|
|
|
`zeros'
|
`zeros'
|
`-z' in `gprof'.
|
`-z' in `gprof'.
|
|
|
|
|
File: standards.info, Node: Memory Usage, Next: File Usage, Prev: Option Table, Up: Program Behavior
|
File: standards.info, Node: Memory Usage, Next: File Usage, Prev: Option Table, Up: Program Behavior
|
|
|
4.9 Memory Usage
|
4.9 Memory Usage
|
================
|
================
|
|
|
If a program typically uses just a few meg of memory, don't bother
|
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
|
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
|
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
|
long, it is reasonable to read entire input files into memory to
|
operate on them.
|
operate on them.
|
|
|
However, for programs such as `cat' or `tail', that can usefully
|
However, for programs such as `cat' or `tail', that can usefully
|
operate on very large files, it is important to avoid using a technique
|
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
|
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
|
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
|
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
|
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.
|
are bigger than will fit in memory all at once.
|
|
|
If your program creates complicated data structures, just make them
|
If your program creates complicated data structures, just make them
|
in memory and give a fatal error if `malloc' returns zero.
|
in memory and give a fatal error if `malloc' returns zero.
|
|
|
|
|
File: standards.info, Node: File Usage, Prev: Memory Usage, Up: Program Behavior
|
File: standards.info, Node: File Usage, Prev: Memory Usage, Up: Program Behavior
|
|
|
4.10 File Usage
|
4.10 File Usage
|
===============
|
===============
|
|
|
Programs should be prepared to operate when `/usr' and `/etc' are
|
Programs should be prepared to operate when `/usr' and `/etc' are
|
read-only file systems. Thus, if the program manages log files, lock
|
read-only file systems. Thus, if the program manages log files, lock
|
files, backup files, score files, or any other files which are modified
|
files, backup files, score files, or any other files which are modified
|
for internal purposes, these files should not be stored in `/usr' or
|
for internal purposes, these files should not be stored in `/usr' or
|
`/etc'.
|
`/etc'.
|
|
|
There are two exceptions. `/etc' is used to store system
|
There are two exceptions. `/etc' is used to store system
|
configuration information; it is reasonable for a program to modify
|
configuration information; it is reasonable for a program to modify
|
files in `/etc' when its job is to update the system configuration.
|
files in `/etc' when its job is to update the system configuration.
|
Also, if the user explicitly asks to modify one file in a directory, it
|
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
|
is reasonable for the program to store other files in the same
|
directory.
|
directory.
|
|
|
|
|
File: standards.info, Node: Writing C, Next: Documentation, Prev: Program Behavior, Up: Top
|
File: standards.info, Node: Writing C, Next: Documentation, Prev: Program Behavior, Up: Top
|
|
|
5 Making The Best Use of C
|
5 Making The Best Use of C
|
**************************
|
**************************
|
|
|
This chapter provides advice on how best to use the C language when
|
This chapter provides advice on how best to use the C language when
|
writing GNU software.
|
writing GNU software.
|
|
|
* Menu:
|
* Menu:
|
|
|
* Formatting:: Formatting your source code.
|
* Formatting:: Formatting your source code.
|
* Comments:: Commenting your work.
|
* Comments:: Commenting your work.
|
* Syntactic Conventions:: Clean use of C constructs.
|
* Syntactic Conventions:: Clean use of C constructs.
|
* Names:: Naming variables, functions, and files.
|
* Names:: Naming variables, functions, and files.
|
* System Portability:: Portability among different operating systems.
|
* System Portability:: Portability among different operating systems.
|
* CPU Portability:: Supporting the range of CPU types.
|
* CPU Portability:: Supporting the range of CPU types.
|
* System Functions:: Portability and ``standard'' library functions.
|
* System Functions:: Portability and ``standard'' library functions.
|
* Internationalization:: Techniques for internationalization.
|
* Internationalization:: Techniques for internationalization.
|
* Character Set:: Use ASCII by default.
|
* Character Set:: Use ASCII by default.
|
* Quote Characters:: Use `...' in the C locale.
|
* Quote Characters:: Use `...' in the C locale.
|
* Mmap:: How you can safely use `mmap'.
|
* Mmap:: How you can safely use `mmap'.
|
|
|
|
|
File: standards.info, Node: Formatting, Next: Comments, Up: Writing C
|
File: standards.info, Node: Formatting, Next: Comments, Up: Writing C
|
|
|
5.1 Formatting Your Source Code
|
5.1 Formatting Your Source Code
|
===============================
|
===============================
|
|
|
It is important to put the open-brace that starts the body of a C
|
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
|
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
|
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.
|
functions. These tools will not work on code not formatted that way.
|
|
|
Avoid putting open-brace, open-parenthesis or open-bracket in column
|
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.
|
one when they are inside a function, so that they won't start a defun.
|
The open-brace that starts a `struct' body can go in column one if you
|
The open-brace that starts a `struct' body can go in column one if you
|
find it useful to treat that definition as a defun.
|
find it useful to treat that definition as a defun.
|
|
|
It is also important for function definitions to start the name of
|
It is also important for function definitions to start the name of
|
the function in column one. This helps people to search for function
|
the function in column one. This helps people to search for function
|
definitions, and may also help certain tools recognize them. Thus,
|
definitions, and may also help certain tools recognize them. Thus,
|
using Standard C syntax, the format is this:
|
using Standard C syntax, the format is this:
|
|
|
static char *
|
static char *
|
concat (char *s1, char *s2)
|
concat (char *s1, char *s2)
|
{
|
{
|
...
|
...
|
}
|
}
|
|
|
or, if you want to use traditional C syntax, format the definition like
|
or, if you want to use traditional C syntax, format the definition like
|
this:
|
this:
|
|
|
static char *
|
static char *
|
concat (s1, s2) /* Name starts in column one here */
|
concat (s1, s2) /* Name starts in column one here */
|
char *s1, *s2;
|
char *s1, *s2;
|
{ /* Open brace in column one here */
|
{ /* Open brace in column one here */
|
...
|
...
|
}
|
}
|
|
|
In Standard C, if the arguments don't fit nicely on one line, split
|
In Standard C, if the arguments don't fit nicely on one line, split
|
it like this:
|
it like this:
|
|
|
int
|
int
|
lots_of_args (int an_integer, long a_long, short a_short,
|
lots_of_args (int an_integer, long a_long, short a_short,
|
double a_double, float a_float)
|
double a_double, float a_float)
|
...
|
...
|
|
|
The rest of this section gives our recommendations for other aspects
|
The rest of this section gives our recommendations for other aspects
|
of C formatting style, which is also the default style of the `indent'
|
of C formatting style, which is also the default style of the `indent'
|
program in version 1.2 and newer. It corresponds to the options
|
program in version 1.2 and newer. It corresponds to the options
|
|
|
-nbad -bap -nbc -bbo -bl -bli2 -bls -ncdb -nce -cp1 -cs -di2
|
-nbad -bap -nbc -bbo -bl -bli2 -bls -ncdb -nce -cp1 -cs -di2
|
-ndj -nfc1 -nfca -hnl -i2 -ip5 -lp -pcs -psl -nsc -nsob
|
-ndj -nfc1 -nfca -hnl -i2 -ip5 -lp -pcs -psl -nsc -nsob
|
|
|
We don't think of these recommendations as requirements, because it
|
We don't think of these recommendations as requirements, because it
|
causes no problems for users if two different programs have different
|
causes no problems for users if two different programs have different
|
formatting styles.
|
formatting styles.
|
|
|
But whatever style you use, please use it consistently, since a
|
But whatever style you use, please use it consistently, since a
|
mixture of styles within one program tends to look ugly. If you are
|
mixture of styles within one program tends to look ugly. If you are
|
contributing changes to an existing program, please follow the style of
|
contributing changes to an existing program, please follow the style of
|
that program.
|
that program.
|
|
|
For the body of the function, our recommended style looks like this:
|
For the body of the function, our recommended style looks like this:
|
|
|
if (x < foo (y, z))
|
if (x < foo (y, z))
|
haha = bar[4] + 5;
|
haha = bar[4] + 5;
|
else
|
else
|
{
|
{
|
while (z)
|
while (z)
|
{
|
{
|
haha += foo (z, z);
|
haha += foo (z, z);
|
z--;
|
z--;
|
}
|
}
|
return ++x + bar ();
|
return ++x + bar ();
|
}
|
}
|
|
|
We find it easier to read a program when it has spaces before the
|
We find it easier to read a program when it has spaces before the
|
open-parentheses and after the commas. Especially after the commas.
|
open-parentheses and after the commas. Especially after the commas.
|
|
|
When you split an expression into multiple lines, split it before an
|
When you split an expression into multiple lines, split it before an
|
operator, not after one. Here is the right way:
|
operator, not after one. Here is the right way:
|
|
|
if (foo_this_is_long && bar > win (x, y, z)
|
if (foo_this_is_long && bar > win (x, y, z)
|
&& remaining_condition)
|
&& remaining_condition)
|
|
|
Try to avoid having two operators of different precedence at the same
|
Try to avoid having two operators of different precedence at the same
|
level of indentation. For example, don't write this:
|
level of indentation. For example, don't write this:
|
|
|
mode = (inmode[j] == VOIDmode
|
mode = (inmode[j] == VOIDmode
|
|| GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j])
|
|| GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j])
|
? outmode[j] : inmode[j]);
|
? outmode[j] : inmode[j]);
|
|
|
Instead, use extra parentheses so that the indentation shows the
|
Instead, use extra parentheses so that the indentation shows the
|
nesting:
|
nesting:
|
|
|
mode = ((inmode[j] == VOIDmode
|
mode = ((inmode[j] == VOIDmode
|
|| (GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j])))
|
|| (GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j])))
|
? outmode[j] : inmode[j]);
|
? outmode[j] : inmode[j]);
|
|
|
Insert extra parentheses so that Emacs will indent the code properly.
|
Insert extra parentheses so that Emacs will indent the code properly.
|
For example, the following indentation looks nice if you do it by hand,
|
For example, the following indentation looks nice if you do it by hand,
|
|
|
v = rup->ru_utime.tv_sec*1000 + rup->ru_utime.tv_usec/1000
|
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;
|
+ rup->ru_stime.tv_sec*1000 + rup->ru_stime.tv_usec/1000;
|
|
|
but Emacs would alter it. Adding a set of parentheses produces
|
but Emacs would alter it. Adding a set of parentheses produces
|
something that looks equally nice, and which Emacs will preserve:
|
something that looks equally nice, and which Emacs will preserve:
|
|
|
v = (rup->ru_utime.tv_sec*1000 + rup->ru_utime.tv_usec/1000
|
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);
|
+ rup->ru_stime.tv_sec*1000 + rup->ru_stime.tv_usec/1000);
|
|
|
Format do-while statements like this:
|
Format do-while statements like this:
|
|
|
do
|
do
|
{
|
{
|
a = foo (a);
|
a = foo (a);
|
}
|
}
|
while (a > 0);
|
while (a > 0);
|
|
|
Please use formfeed characters (control-L) to divide the program into
|
Please use formfeed characters (control-L) to divide the program into
|
pages at logical places (but not within a function). It does not matter
|
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
|
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.
|
page. The formfeeds should appear alone on lines by themselves.
|
|
|
|
|
File: standards.info, Node: Comments, Next: Syntactic Conventions, Prev: Formatting, Up: Writing C
|
File: standards.info, Node: Comments, Next: Syntactic Conventions, Prev: Formatting, Up: Writing C
|
|
|
5.2 Commenting Your Work
|
5.2 Commenting Your Work
|
========================
|
========================
|
|
|
Every program should start with a comment saying briefly what it is for.
|
Every program should start with a comment saying briefly what it is for.
|
Example: `fmt - filter for simple filling of text'. This comment
|
Example: `fmt - filter for simple filling of text'. This comment
|
should be at the top of the source file containing the `main' function
|
should be at the top of the source file containing the `main' function
|
of the program.
|
of the program.
|
|
|
Also, please write a brief comment at the start of each source file,
|
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
|
with the file name and a line or two about the overall purpose of the
|
file.
|
file.
|
|
|
Please write the comments in a GNU program in English, because
|
Please write the comments in a GNU program in English, because
|
English is the one language that nearly all programmers in all
|
English is the one language that nearly all programmers in all
|
countries can read. If you do not write English well, please write
|
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
|
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
|
rewrite them. If you can't write comments in English, please find
|
someone to work with you and translate your comments into English.
|
someone to work with you and translate your comments into English.
|
|
|
Please put a comment on each function saying what the function does,
|
Please put a comment on each function saying what the function does,
|
what sorts of arguments it gets, and what the possible values of
|
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
|
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
|
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
|
used in its customary fashion. If there is anything nonstandard about
|
its use (such as an argument of type `char *' which is really the
|
its use (such as an argument of type `char *' which is really the
|
address of the second character of a string, not the first), or any
|
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,
|
possible values that would not work the way one would expect (such as,
|
that strings containing newlines are not guaranteed to work), be sure
|
that strings containing newlines are not guaranteed to work), be sure
|
to say so.
|
to say so.
|
|
|
Also explain the significance of the return value, if there is one.
|
Also explain the significance of the return value, if there is one.
|
|
|
Please put two spaces after the end of a sentence in your comments,
|
Please put two spaces after the end of a sentence in your comments,
|
so that the Emacs sentence commands will work. Also, please write
|
so that the Emacs sentence commands will work. Also, please write
|
complete sentences and capitalize the first word. If a lower-case
|
complete sentences and capitalize the first word. If a lower-case
|
identifier comes at the beginning of a sentence, don't capitalize it!
|
identifier comes at the beginning of a sentence, don't capitalize it!
|
Changing the spelling makes it a different identifier. If you don't
|
Changing the spelling makes it a different identifier. If you don't
|
like starting a sentence with a lower case letter, write the sentence
|
like starting a sentence with a lower case letter, write the sentence
|
differently (e.g., "The identifier lower-case is ...").
|
differently (e.g., "The identifier lower-case is ...").
|
|
|
The comment on a function is much clearer if you use the argument
|
The comment on a function is much clearer if you use the argument
|
names to speak about the argument values. The variable name itself
|
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
|
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
|
about the value rather than the variable itself. Thus, "the inode
|
number NODE_NUM" rather than "an inode".
|
number NODE_NUM" rather than "an inode".
|
|
|
There is usually no purpose in restating the name of the function in
|
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.
|
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
|
There might be an exception when the comment is so long that the
|
function itself would be off the bottom of the screen.
|
function itself would be off the bottom of the screen.
|
|
|
There should be a comment on each static variable as well, like this:
|
There should be a comment on each static variable as well, like this:
|
|
|
/* Nonzero means truncate lines in the display;
|
/* Nonzero means truncate lines in the display;
|
zero means continue them. */
|
zero means continue them. */
|
int truncate_lines;
|
int truncate_lines;
|
|
|
Every `#endif' should have a comment, except in the case of short
|
Every `#endif' should have a comment, except in the case of short
|
conditionals (just a few lines) that are not nested. The comment should
|
conditionals (just a few lines) that are not nested. The comment should
|
state the condition of the conditional that is ending, _including its
|
state the condition of the conditional that is ending, _including its
|
sense_. `#else' should have a comment describing the condition _and
|
sense_. `#else' should have a comment describing the condition _and
|
sense_ of the code that follows. For example:
|
sense_ of the code that follows. For example:
|
|
|
#ifdef foo
|
#ifdef foo
|
...
|
...
|
#else /* not foo */
|
#else /* not foo */
|
...
|
...
|
#endif /* not foo */
|
#endif /* not foo */
|
#ifdef foo
|
#ifdef foo
|
...
|
...
|
#endif /* foo */
|
#endif /* foo */
|
|
|
but, by contrast, write the comments this way for a `#ifndef':
|
but, by contrast, write the comments this way for a `#ifndef':
|
|
|
#ifndef foo
|
#ifndef foo
|
...
|
...
|
#else /* foo */
|
#else /* foo */
|
...
|
...
|
#endif /* foo */
|
#endif /* foo */
|
#ifndef foo
|
#ifndef foo
|
...
|
...
|
#endif /* not foo */
|
#endif /* not foo */
|
|
|
|
|
File: standards.info, Node: Syntactic Conventions, Next: Names, Prev: Comments, Up: Writing C
|
File: standards.info, Node: Syntactic Conventions, Next: Names, Prev: Comments, Up: Writing C
|
|
|
5.3 Clean Use of C Constructs
|
5.3 Clean Use of C Constructs
|
=============================
|
=============================
|
|
|
Please explicitly declare the types of all objects. For example, you
|
Please explicitly declare the types of all objects. For example, you
|
should explicitly declare all arguments to functions, and you should
|
should explicitly declare all arguments to functions, and you should
|
declare functions to return `int' rather than omitting the `int'.
|
declare functions to return `int' rather than omitting the `int'.
|
|
|
Some programmers like to use the GCC `-Wall' option, and change the
|
Some programmers like to use the GCC `-Wall' option, and change the
|
code whenever it issues a warning. If you want to do this, then do.
|
code whenever it issues a warning. If you want to do this, then do.
|
Other programmers prefer not to use `-Wall', because it gives warnings
|
Other programmers prefer not to use `-Wall', because it gives warnings
|
for valid and legitimate code which they do not want to change. If you
|
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
|
want to do this, then do. The compiler should be your servant, not
|
your master.
|
your master.
|
|
|
Declarations of external functions and functions to appear later in
|
Declarations of external functions and functions to appear later in
|
the source file should all go in one place near the beginning of the
|
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
|
file (somewhere before the first function definition in the file), or
|
else should go in a header file. Don't put `extern' declarations inside
|
else should go in a header file. Don't put `extern' declarations inside
|
functions.
|
functions.
|
|
|
It used to be common practice to use the same local variables (with
|
It used to be common practice to use the same local variables (with
|
names like `tem') over and over for different values within one
|
names like `tem') over and over for different values within one
|
function. Instead of doing this, it is better to declare a separate
|
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
|
local variable for each distinct purpose, and give it a name which is
|
meaningful. This not only makes programs easier to understand, it also
|
meaningful. This not only makes programs easier to understand, it also
|
facilitates optimization by good compilers. You can also move the
|
facilitates optimization by good compilers. You can also move the
|
declaration of each local variable into the smallest scope that includes
|
declaration of each local variable into the smallest scope that includes
|
all its uses. This makes the program even cleaner.
|
all its uses. This makes the program even cleaner.
|
|
|
Don't use local variables or parameters that shadow global
|
Don't use local variables or parameters that shadow global
|
identifiers.
|
identifiers.
|
|
|
Don't declare multiple variables in one declaration that spans lines.
|
Don't declare multiple variables in one declaration that spans lines.
|
Start a new declaration on each line, instead. For example, instead of
|
Start a new declaration on each line, instead. For example, instead of
|
this:
|
this:
|
|
|
int foo,
|
int foo,
|
bar;
|
bar;
|
|
|
write either this:
|
write either this:
|
|
|
int foo, bar;
|
int foo, bar;
|
|
|
or this:
|
or this:
|
|
|
int foo;
|
int foo;
|
int bar;
|
int bar;
|
|
|
(If they are global variables, each should have a comment preceding it
|
(If they are global variables, each should have a comment preceding it
|
anyway.)
|
anyway.)
|
|
|
When you have an `if'-`else' statement nested in another `if'
|
When you have an `if'-`else' statement nested in another `if'
|
statement, always put braces around the `if'-`else'. Thus, never write
|
statement, always put braces around the `if'-`else'. Thus, never write
|
like this:
|
like this:
|
|
|
if (foo)
|
if (foo)
|
if (bar)
|
if (bar)
|
win ();
|
win ();
|
else
|
else
|
lose ();
|
lose ();
|
|
|
always like this:
|
always like this:
|
|
|
if (foo)
|
if (foo)
|
{
|
{
|
if (bar)
|
if (bar)
|
win ();
|
win ();
|
else
|
else
|
lose ();
|
lose ();
|
}
|
}
|
|
|
If you have an `if' statement nested inside of an `else' statement,
|
If you have an `if' statement nested inside of an `else' statement,
|
either write `else if' on one line, like this,
|
either write `else if' on one line, like this,
|
|
|
if (foo)
|
if (foo)
|
...
|
...
|
else if (bar)
|
else if (bar)
|
...
|
...
|
|
|
with its `then'-part indented like the preceding `then'-part, or write
|
with its `then'-part indented like the preceding `then'-part, or write
|
the nested `if' within braces like this:
|
the nested `if' within braces like this:
|
|
|
if (foo)
|
if (foo)
|
...
|
...
|
else
|
else
|
{
|
{
|
if (bar)
|
if (bar)
|
...
|
...
|
}
|
}
|
|
|
Don't declare both a structure tag and variables or typedefs in the
|
Don't declare both a structure tag and variables or typedefs in the
|
same declaration. Instead, declare the structure tag separately and
|
same declaration. Instead, declare the structure tag separately and
|
then use it to declare the variables or typedefs.
|
then use it to declare the variables or typedefs.
|
|
|
Try to avoid assignments inside `if'-conditions (assignments inside
|
Try to avoid assignments inside `if'-conditions (assignments inside
|
`while'-conditions are ok). For example, don't write this:
|
`while'-conditions are ok). For example, don't write this:
|
|
|
if ((foo = (char *) malloc (sizeof *foo)) == 0)
|
if ((foo = (char *) malloc (sizeof *foo)) == 0)
|
fatal ("virtual memory exhausted");
|
fatal ("virtual memory exhausted");
|
|
|
instead, write this:
|
instead, write this:
|
|
|
foo = (char *) malloc (sizeof *foo);
|
foo = (char *) malloc (sizeof *foo);
|
if (foo == 0)
|
if (foo == 0)
|
fatal ("virtual memory exhausted");
|
fatal ("virtual memory exhausted");
|
|
|
Don't make the program ugly to placate `lint'. Please don't insert
|
Don't make the program ugly to placate `lint'. Please don't insert
|
any casts to `void'. Zero without a cast is perfectly fine as a null
|
any casts to `void'. Zero without a cast is perfectly fine as a null
|
pointer constant, except when calling a varargs function.
|
pointer constant, except when calling a varargs function.
|
|
|
|
|
File: standards.info, Node: Names, Next: System Portability, Prev: Syntactic Conventions, Up: Writing C
|
File: standards.info, Node: Names, Next: System Portability, Prev: Syntactic Conventions, Up: Writing C
|
|
|
5.4 Naming Variables, Functions, and Files
|
5.4 Naming Variables, Functions, and Files
|
==========================================
|
==========================================
|
|
|
The names of global variables and functions in a program serve as
|
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
|
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
|
names that give useful information about the meaning of the variable or
|
function. In a GNU program, names should be English, like other
|
function. In a GNU program, names should be English, like other
|
comments.
|
comments.
|
|
|
Local variable names can be shorter, because they are used only
|
Local variable names can be shorter, because they are used only
|
within one context, where (presumably) comments explain their purpose.
|
within one context, where (presumably) comments explain their purpose.
|
|
|
Try to limit your use of abbreviations in symbol names. It is ok to
|
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
|
make a few abbreviations, explain what they mean, and then use them
|
frequently, but don't use lots of obscure abbreviations.
|
frequently, but don't use lots of obscure abbreviations.
|
|
|
Please use underscores to separate words in a name, so that the Emacs
|
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
|
word commands can be useful within them. Stick to lower case; reserve
|
upper case for macros and `enum' constants, and for name-prefixes that
|
upper case for macros and `enum' constants, and for name-prefixes that
|
follow a uniform convention.
|
follow a uniform convention.
|
|
|
For example, you should use names like `ignore_space_change_flag';
|
For example, you should use names like `ignore_space_change_flag';
|
don't use names like `iCantReadThis'.
|
don't use names like `iCantReadThis'.
|
|
|
Variables that indicate whether command-line options have been
|
Variables that indicate whether command-line options have been
|
specified should be named after the meaning of the option, not after
|
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-letter. A comment should state both the exact meaning of
|
the option and its letter. For example,
|
the option and its letter. For example,
|
|
|
/* Ignore changes in horizontal whitespace (-b). */
|
/* Ignore changes in horizontal whitespace (-b). */
|
int ignore_space_change_flag;
|
int ignore_space_change_flag;
|
|
|
When you want to define names with constant integer values, use
|
When you want to define names with constant integer values, use
|
`enum' rather than `#define'. GDB knows about enumeration constants.
|
`enum' rather than `#define'. GDB knows about enumeration constants.
|
|
|
You might want to make sure that none of the file names would
|
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
|
conflict if the files were loaded onto an MS-DOS file system which
|
shortens the names. You can use the program `doschk' to test for this.
|
shortens the names. You can use the program `doschk' to test for this.
|
|
|
Some GNU programs were designed to limit themselves to file names of
|
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
|
14 characters or less, to avoid file name conflicts if they are read
|
into older System V systems. Please preserve this feature in the
|
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
|
existing GNU programs that have it, but there is no need to do this in
|
new GNU programs. `doschk' also reports file names longer than 14
|
new GNU programs. `doschk' also reports file names longer than 14
|
characters.
|
characters.
|
|
|
|
|
File: standards.info, Node: System Portability, Next: CPU Portability, Prev: Names, Up: Writing C
|
File: standards.info, Node: System Portability, Next: CPU Portability, Prev: Names, Up: Writing C
|
|
|
5.5 Portability between System Types
|
5.5 Portability between System Types
|
====================================
|
====================================
|
|
|
In the Unix world, "portability" refers to porting to different Unix
|
In the Unix world, "portability" refers to porting to different Unix
|
versions. For a GNU program, this kind of portability is desirable, but
|
versions. For a GNU program, this kind of portability is desirable, but
|
not paramount.
|
not paramount.
|
|
|
The primary purpose of GNU software is to run on top of the GNU
|
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 CPU. So
|
kernel, compiled with the GNU C compiler, on various types of CPU. So
|
the kinds of portability that are absolutely necessary are quite
|
the kinds of portability that are absolutely necessary are quite
|
limited. But it is important to support Linux-based GNU systems, since
|
limited. But it is important to support Linux-based GNU systems, since
|
they are the form of GNU that is popular.
|
they are the form of GNU that is popular.
|
|
|
Beyond that, it is good to support the other free operating systems
|
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
|
(*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
|
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.
|
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
|
But you don't have to consider it an obligation, if it does turn out to
|
be hard.
|
be hard.
|
|
|
The easiest way to achieve portability to most Unix-like systems is
|
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
|
to use Autoconf. It's unlikely that your program needs to know more
|
information about the host platform than Autoconf can provide, simply
|
information about the host platform than Autoconf can provide, simply
|
because most of the programs that need such knowledge have already been
|
because most of the programs that need such knowledge have already been
|
written.
|
written.
|
|
|
Avoid using the format of semi-internal data bases (e.g.,
|
Avoid using the format of semi-internal data bases (e.g.,
|
directories) when there is a higher-level alternative (`readdir').
|
directories) when there is a higher-level alternative (`readdir').
|
|
|
As for systems that are not like Unix, such as MSDOS, Windows, VMS,
|
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
|
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
|
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
|
features that will be useful on GNU and GNU/Linux, rather than on
|
supporting other incompatible systems.
|
supporting other incompatible systems.
|
|
|
If you do support Windows, please do not abbreviate it as "win". In
|
If you do support Windows, please do not abbreviate it as "win". In
|
hacker terminology, calling something a "win" is a form of praise.
|
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
|
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
|
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"
|
"Windows" to "un", you can write it in full or abbreviate it to "woe"
|
or "w". In GNU Emacs, for instance, we use `w32' in file names of
|
or "w". In GNU Emacs, for instance, we use `w32' in file names of
|
Windows-specific files, but the macro for Windows conditionals is
|
Windows-specific files, but the macro for Windows conditionals is
|
called `WINDOWSNT'.
|
called `WINDOWSNT'.
|
|
|
It is a good idea to define the "feature test macro" `_GNU_SOURCE'
|
It is a good idea to define the "feature test macro" `_GNU_SOURCE'
|
when compiling your C files. When you compile on GNU or GNU/Linux,
|
when compiling your C files. When you compile on GNU or GNU/Linux,
|
this will enable the declarations of GNU library extension functions,
|
this will enable the declarations of GNU library extension functions,
|
and that will usually give you a compiler error message if you define
|
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
|
the same function names in some other way in your program. (You don't
|
have to actually _use_ these functions, if you prefer to make the
|
have to actually _use_ these functions, if you prefer to make the
|
program more portable to other systems.)
|
program more portable to other systems.)
|
|
|
But whether or not you use these GNU extensions, you should avoid
|
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
|
using their names for any other meanings. Doing so would make it hard
|
to move your code into other GNU programs.
|
to move your code into other GNU programs.
|
|
|
|
|
File: standards.info, Node: CPU Portability, Next: System Functions, Prev: System Portability, Up: Writing C
|
File: standards.info, Node: CPU Portability, Next: System Functions, Prev: System Portability, Up: Writing C
|
|
|
5.6 Portability between CPUs
|
5.6 Portability between CPUs
|
============================
|
============================
|
|
|
Even GNU systems will differ because of differences among CPU
|
Even GNU systems will differ because of differences among CPU
|
types--for example, difference in byte ordering and alignment
|
types--for example, difference in byte ordering and alignment
|
requirements. It is absolutely essential to handle these differences.
|
requirements. It is absolutely essential to handle these differences.
|
However, don't make any effort to cater to the possibility that an
|
However, don't make any effort to cater to the possibility that an
|
`int' will be less than 32 bits. We don't support 16-bit machines in
|
`int' will be less than 32 bits. We don't support 16-bit machines in
|
GNU.
|
GNU.
|
|
|
Similarly, don't make any effort to cater to the possibility that
|
Similarly, don't make any effort to cater to the possibility that
|
`long' will be smaller than predefined types like `size_t'. For
|
`long' will be smaller than predefined types like `size_t'. For
|
example, the following code is ok:
|
example, the following code is ok:
|
|
|
printf ("size = %lu\n", (unsigned long) sizeof array);
|
printf ("size = %lu\n", (unsigned long) sizeof array);
|
printf ("diff = %ld\n", (long) (pointer2 - pointer1));
|
printf ("diff = %ld\n", (long) (pointer2 - pointer1));
|
|
|
1989 Standard C requires this to work, and we know of only one
|
1989 Standard C requires this to work, and we know of only one
|
counterexample: 64-bit programs on Microsoft Windows. We will leave it
|
counterexample: 64-bit programs on Microsoft Windows. We will leave it
|
to those who want to port GNU programs to that environment to figure
|
to those who want to port GNU programs to that environment to figure
|
out how to do it.
|
out how to do it.
|
|
|
Predefined file-size types like `off_t' are an exception: they are
|
Predefined file-size types like `off_t' are an exception: they are
|
longer than `long' on many platforms, so code like the above won't work
|
longer than `long' on many platforms, so code like the above won't work
|
with them. One way to print an `off_t' value portably is to print its
|
with them. One way to print an `off_t' value portably is to print its
|
digits yourself, one by one.
|
digits yourself, one by one.
|
|
|
Don't assume that the address of an `int' object is also the address
|
Don't assume that the address of an `int' object is also the address
|
of its least-significant byte. This is false on big-endian machines.
|
of its least-significant byte. This is false on big-endian machines.
|
Thus, don't make the following mistake:
|
Thus, don't make the following mistake:
|
|
|
int c;
|
int c;
|
...
|
...
|
while ((c = getchar ()) != EOF)
|
while ((c = getchar ()) != EOF)
|
write (file_descriptor, &c, 1);
|
write (file_descriptor, &c, 1);
|
|
|
Instead, use `unsigned char' as follows. (The `unsigned' is for
|
Instead, use `unsigned char' as follows. (The `unsigned' is for
|
portability to unusual systems where `char' is signed and where there
|
portability to unusual systems where `char' is signed and where there
|
is integer overflow checking.)
|
is integer overflow checking.)
|
|
|
int c;
|
int c;
|
while ((c = getchar ()) != EOF)
|
while ((c = getchar ()) != EOF)
|
{
|
{
|
unsigned char u = c;
|
unsigned char u = c;
|
write (file_descriptor, &u, 1);
|
write (file_descriptor, &u, 1);
|
}
|
}
|
|
|
It used to be ok to not worry about the difference between pointers
|
It used to be ok to not worry about the difference between pointers
|
and integers when passing arguments to functions. However, on most
|
and integers when passing arguments to functions. However, on most
|
modern 64-bit machines pointers are wider than `int'. Conversely,
|
modern 64-bit machines pointers are wider than `int'. Conversely,
|
integer types like `long long int' and `off_t' are wider than pointers
|
integer types like `long long int' and `off_t' are wider than pointers
|
on most modern 32-bit machines. Hence it's often better nowadays to
|
on most modern 32-bit machines. Hence it's often better nowadays to
|
use prototypes to define functions whose argument types are not trivial.
|
use prototypes to define functions whose argument types are not trivial.
|
|
|
In particular, if functions accept varying argument counts or types
|
In particular, if functions accept varying argument counts or types
|
they should be declared using prototypes containing `...' and defined
|
they should be declared using prototypes containing `...' and defined
|
using `stdarg.h'. For an example of this, please see the Gnulib
|
using `stdarg.h'. For an example of this, please see the Gnulib
|
(http://www.gnu.org/software/gnulib/) error module, which declares and
|
(http://www.gnu.org/software/gnulib/) error module, which declares and
|
defines the following function:
|
defines the following function:
|
|
|
/* Print a message with `fprintf (stderr, FORMAT, ...)';
|
/* Print a message with `fprintf (stderr, FORMAT, ...)';
|
if ERRNUM is nonzero, follow it with ": " and strerror (ERRNUM).
|
if ERRNUM is nonzero, follow it with ": " and strerror (ERRNUM).
|
If STATUS is nonzero, terminate the program with `exit (STATUS)'. */
|
If STATUS is nonzero, terminate the program with `exit (STATUS)'. */
|
|
|
void error (int status, int errnum, const char *format, ...);
|
void error (int status, int errnum, const char *format, ...);
|
|
|
A simple way to use the Gnulib error module is to obtain the two
|
A simple way to use the Gnulib error module is to obtain the two
|
source files `error.c' and `error.h' from the Gnulib library source
|
source files `error.c' and `error.h' from the Gnulib library source
|
code repository at
|
code repository at
|
`http://savannah.gnu.org/cgi-bin/viewcvs/gnulib/gnulib/lib/'. Here's a
|
`http://savannah.gnu.org/cgi-bin/viewcvs/gnulib/gnulib/lib/'. Here's a
|
sample use:
|
sample use:
|
|
|
#include "error.h"
|
#include "error.h"
|
#include
|
#include
|
#include
|
#include
|
|
|
char *program_name = "myprogram";
|
char *program_name = "myprogram";
|
|
|
FILE *
|
FILE *
|
xfopen (char const *name)
|
xfopen (char const *name)
|
{
|
{
|
FILE *fp = fopen (name, "r");
|
FILE *fp = fopen (name, "r");
|
if (! fp)
|
if (! fp)
|
error (1, errno, "cannot read %s", name);
|
error (1, errno, "cannot read %s", name);
|
return fp;
|
return fp;
|
}
|
}
|
|
|
Avoid casting pointers to integers if you can. Such casts greatly
|
Avoid casting pointers to integers if you can. Such casts greatly
|
reduce portability, and in most programs they are easy to avoid. In the
|
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
|
cases where casting pointers to integers is essential--such as, a Lisp
|
interpreter which stores type information as well as an address in one
|
interpreter which stores type information as well as an address in one
|
word--you'll have to make explicit provisions to handle different word
|
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
|
sizes. You will also need to make provision for systems in which the
|
normal range of addresses you can get from `malloc' starts far away
|
normal range of addresses you can get from `malloc' starts far away
|
from zero.
|
from zero.
|
|
|
|
|
File: standards.info, Node: System Functions, Next: Internationalization, Prev: CPU Portability, Up: Writing C
|
File: standards.info, Node: System Functions, Next: Internationalization, Prev: CPU Portability, Up: Writing C
|
|
|
5.7 Calling System Functions
|
5.7 Calling System Functions
|
============================
|
============================
|
|
|
C implementations differ substantially. Standard C reduces but does
|
C implementations differ substantially. Standard C reduces but does
|
not eliminate the incompatibilities; meanwhile, many GNU packages still
|
not eliminate the incompatibilities; meanwhile, many GNU packages still
|
support pre-standard compilers because this is not hard to do. This
|
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
|
chapter gives recommendations for how to use the more-or-less standard C
|
library functions to avoid unnecessary loss of portability.
|
library functions to avoid unnecessary loss of portability.
|
|
|
* Don't use the return value of `sprintf'. It returns the number of
|
* Don't use the return value of `sprintf'. It returns the number of
|
characters written on some systems, but not on all systems.
|
characters written on some systems, but not on all systems.
|
|
|
* Be aware that `vfprintf' is not always available.
|
* Be aware that `vfprintf' is not always available.
|
|
|
* `main' should be declared to return type `int'. It should
|
* `main' should be declared to return type `int'. It should
|
terminate either by calling `exit' or by returning the integer
|
terminate either by calling `exit' or by returning the integer
|
status code; make sure it cannot ever return an undefined value.
|
status code; make sure it cannot ever return an undefined value.
|
|
|
* Don't declare system functions explicitly.
|
* Don't declare system functions explicitly.
|
|
|
Almost any declaration for a system function is wrong on some
|
Almost any declaration for a system function is wrong on some
|
system. To minimize conflicts, leave it to the system header
|
system. To minimize conflicts, leave it to the system header
|
files to declare system functions. If the headers don't declare a
|
files to declare system functions. If the headers don't declare a
|
function, let it remain undeclared.
|
function, let it remain undeclared.
|
|
|
While it may seem unclean to use a function without declaring it,
|
While it may seem unclean to use a function without declaring it,
|
in practice this works fine for most system library functions on
|
in practice this works fine for most system library functions on
|
the systems where this really happens; thus, the disadvantage is
|
the systems where this really happens; thus, the disadvantage is
|
only theoretical. By contrast, actual declarations have
|
only theoretical. By contrast, actual declarations have
|
frequently caused actual conflicts.
|
frequently caused actual conflicts.
|
|
|
* If you must declare a system function, don't specify the argument
|
* If you must declare a system function, don't specify the argument
|
types. Use an old-style declaration, not a Standard C prototype.
|
types. Use an old-style declaration, not a Standard C prototype.
|
The more you specify about the function, the more likely a
|
The more you specify about the function, the more likely a
|
conflict.
|
conflict.
|
|
|
* In particular, don't unconditionally declare `malloc' or `realloc'.
|
* In particular, don't unconditionally declare `malloc' or `realloc'.
|
|
|
Most GNU programs use those functions just once, in functions
|
Most GNU programs use those functions just once, in functions
|
conventionally named `xmalloc' and `xrealloc'. These functions
|
conventionally named `xmalloc' and `xrealloc'. These functions
|
call `malloc' and `realloc', respectively, and check the results.
|
call `malloc' and `realloc', respectively, and check the results.
|
|
|
Because `xmalloc' and `xrealloc' are defined in your program, you
|
Because `xmalloc' and `xrealloc' are defined in your program, you
|
can declare them in other files without any risk of type conflict.
|
can declare them in other files without any risk of type conflict.
|
|
|
On most systems, `int' is the same length as a pointer; thus, the
|
On most systems, `int' is the same length as a pointer; thus, the
|
calls to `malloc' and `realloc' work fine. For the few
|
calls to `malloc' and `realloc' work fine. For the few
|
exceptional systems (mostly 64-bit machines), you can use
|
exceptional systems (mostly 64-bit machines), you can use
|
*conditionalized* declarations of `malloc' and `realloc'--or put
|
*conditionalized* declarations of `malloc' and `realloc'--or put
|
these declarations in configuration files specific to those
|
these declarations in configuration files specific to those
|
systems.
|
systems.
|
|
|
* The string functions require special treatment. Some Unix systems
|
* The string functions require special treatment. Some Unix systems
|
have a header file `string.h'; others have `strings.h'. Neither
|
have a header file `string.h'; others have `strings.h'. Neither
|
file name is portable. There are two things you can do: use
|
file name is portable. There are two things you can do: use
|
Autoconf to figure out which file to include, or don't include
|
Autoconf to figure out which file to include, or don't include
|
either file.
|
either file.
|
|
|
* If you don't include either strings file, you can't get
|
* If you don't include either strings file, you can't get
|
declarations for the string functions from the header file in the
|
declarations for the string functions from the header file in the
|
usual way.
|
usual way.
|
|
|
That causes less of a problem than you might think. The newer
|
That causes less of a problem than you might think. The newer
|
standard string functions should be avoided anyway because many
|
standard string functions should be avoided anyway because many
|
systems still don't support them. The string functions you can
|
systems still don't support them. The string functions you can
|
use are these:
|
use are these:
|
|
|
strcpy strncpy strcat strncat
|
strcpy strncpy strcat strncat
|
strlen strcmp strncmp
|
strlen strcmp strncmp
|
strchr strrchr
|
strchr strrchr
|
|
|
The copy and concatenate functions work fine without a declaration
|
The copy and concatenate functions work fine without a declaration
|
as long as you don't use their values. Using their values without
|
as long as you don't use their values. Using their values without
|
a declaration fails on systems where the width of a pointer
|
a declaration fails on systems where the width of a pointer
|
differs from the width of `int', and perhaps in other cases. It
|
differs from the width of `int', and perhaps in other cases. It
|
is trivial to avoid using their values, so do that.
|
is trivial to avoid using their values, so do that.
|
|
|
The compare functions and `strlen' work fine without a declaration
|
The compare functions and `strlen' work fine without a declaration
|
on most systems, possibly all the ones that GNU software runs on.
|
on most systems, possibly all the ones that GNU software runs on.
|
You may find it necessary to declare them *conditionally* on a few
|
You may find it necessary to declare them *conditionally* on a few
|
systems.
|
systems.
|
|
|
The search functions must be declared to return `char *'. Luckily,
|
The search functions must be declared to return `char *'. Luckily,
|
there is no variation in the data type they return. But there is
|
there is no variation in the data type they return. But there is
|
variation in their names. Some systems give these functions the
|
variation in their names. Some systems give these functions the
|
names `index' and `rindex'; other systems use the names `strchr'
|
names `index' and `rindex'; other systems use the names `strchr'
|
and `strrchr'. Some systems support both pairs of names, but
|
and `strrchr'. Some systems support both pairs of names, but
|
neither pair works on all systems.
|
neither pair works on all systems.
|
|
|
You should pick a single pair of names and use it throughout your
|
You should pick a single pair of names and use it throughout your
|
program. (Nowadays, it is better to choose `strchr' and `strrchr'
|
program. (Nowadays, it is better to choose `strchr' and `strrchr'
|
for new programs, since those are the standard names.) Declare
|
for new programs, since those are the standard names.) Declare
|
both of those names as functions returning `char *'. On systems
|
both of those names as functions returning `char *'. On systems
|
which don't support those names, define them as macros in terms of
|
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
|
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
|
of your file (or in a header) if you want to use the names
|
`strchr' and `strrchr' throughout:
|
`strchr' and `strrchr' throughout:
|
|
|
#ifndef HAVE_STRCHR
|
#ifndef HAVE_STRCHR
|
#define strchr index
|
#define strchr index
|
#endif
|
#endif
|
#ifndef HAVE_STRRCHR
|
#ifndef HAVE_STRRCHR
|
#define strrchr rindex
|
#define strrchr rindex
|
#endif
|
#endif
|
|
|
char *strchr ();
|
char *strchr ();
|
char *strrchr ();
|
char *strrchr ();
|
|
|
Here we assume that `HAVE_STRCHR' and `HAVE_STRRCHR' are macros
|
Here we assume that `HAVE_STRCHR' and `HAVE_STRRCHR' are macros
|
defined in systems where the corresponding functions exist. One way to
|
defined in systems where the corresponding functions exist. One way to
|
get them properly defined is to use Autoconf.
|
get them properly defined is to use Autoconf.
|
|
|
|
|
File: standards.info, Node: Internationalization, Next: Character Set, Prev: System Functions, Up: Writing C
|
File: standards.info, Node: Internationalization, Next: Character Set, Prev: System Functions, Up: Writing C
|
|
|
5.8 Internationalization
|
5.8 Internationalization
|
========================
|
========================
|
|
|
GNU has a library called GNU gettext that makes it easy to translate the
|
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
|
messages in a program into various languages. You should use this
|
library in every program. Use English for the messages as they appear
|
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
|
in the program, and let gettext provide the way to translate them into
|
other languages.
|
other languages.
|
|
|
Using GNU gettext involves putting a call to the `gettext' macro
|
Using GNU gettext involves putting a call to the `gettext' macro
|
around each string that might need translation--like this:
|
around each string that might need translation--like this:
|
|
|
printf (gettext ("Processing file `%s'..."));
|
printf (gettext ("Processing file `%s'..."));
|
|
|
This permits GNU gettext to replace the string `"Processing file
|
This permits GNU gettext to replace the string `"Processing file
|
`%s'..."' with a translated version.
|
`%s'..."' with a translated version.
|
|
|
Once a program uses gettext, please make a point of writing calls to
|
Once a program uses gettext, please make a point of writing calls to
|
`gettext' when you add new strings that call for translation.
|
`gettext' when you add new strings that call for translation.
|
|
|
Using GNU gettext in a package involves specifying a "text domain
|
Using GNU gettext in a package involves specifying a "text domain
|
name" for the package. The text domain name is used to separate the
|
name" for the package. The text domain name is used to separate the
|
translations for this package from the translations for other packages.
|
translations for this package from the translations for other packages.
|
Normally, the text domain name should be the same as the name of the
|
Normally, the text domain name should be the same as the name of the
|
package--for example, `coreutils' for the GNU core utilities.
|
package--for example, `coreutils' for the GNU core utilities.
|
|
|
To enable gettext to work well, avoid writing code that makes
|
To enable gettext to work well, avoid writing code that makes
|
assumptions about the structure of words or sentences. When you want
|
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
|
the precise text of a sentence to vary depending on the data, use two or
|
more alternative string constants each containing a complete sentences,
|
more alternative string constants each containing a complete sentences,
|
rather than inserting conditionalized words or phrases into a single
|
rather than inserting conditionalized words or phrases into a single
|
sentence framework.
|
sentence framework.
|
|
|
Here is an example of what not to do:
|
Here is an example of what not to do:
|
|
|
printf ("%s is full", capacity > 5000000 ? "disk" : "floppy disk");
|
printf ("%s is full", capacity > 5000000 ? "disk" : "floppy disk");
|
|
|
If you apply gettext to all strings, like this,
|
If you apply gettext to all strings, like this,
|
|
|
printf (gettext ("%s is full"),
|
printf (gettext ("%s is full"),
|
capacity > 5000000 ? gettext ("disk") : gettext ("floppy disk"));
|
capacity > 5000000 ? gettext ("disk") : gettext ("floppy disk"));
|
|
|
the translator will hardly know that "disk" and "floppy disk" are meant
|
the translator will hardly know that "disk" and "floppy disk" are meant
|
to be substituted in the other string. Worse, in some languages (like
|
to be substituted in the other string. Worse, in some languages (like
|
French) the construction will not work: the translation of the word
|
French) the construction will not work: the translation of the word
|
"full" depends on the gender of the first part of the sentence; it
|
"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".
|
happens to be not the same for "disk" as for "floppy disk".
|
|
|
Complete sentences can be translated without problems:
|
Complete sentences can be translated without problems:
|
|
|
printf (capacity > 5000000 ? gettext ("disk is full")
|
printf (capacity > 5000000 ? gettext ("disk is full")
|
: gettext ("floppy disk is full"));
|
: gettext ("floppy disk is full"));
|
|
|
A similar problem appears at the level of sentence structure with
|
A similar problem appears at the level of sentence structure with
|
this code:
|
this code:
|
|
|
printf ("# Implicit rule search has%s been done.\n",
|
printf ("# Implicit rule search has%s been done.\n",
|
f->tried_implicit ? "" : " not");
|
f->tried_implicit ? "" : " not");
|
|
|
Adding `gettext' calls to this code cannot give correct results for all
|
Adding `gettext' calls to this code cannot give correct results for all
|
languages, because negation in some languages requires adding words at
|
languages, because negation in some languages requires adding words at
|
more than one place in the sentence. By contrast, adding `gettext'
|
more than one place in the sentence. By contrast, adding `gettext'
|
calls does the job straightforwardly if the code starts out like this:
|
calls does the job straightforwardly if the code starts out like this:
|
|
|
printf (f->tried_implicit
|
printf (f->tried_implicit
|
? "# Implicit rule search has been done.\n",
|
? "# Implicit rule search has been done.\n",
|
: "# Implicit rule search has not been done.\n");
|
: "# Implicit rule search has not been done.\n");
|
|
|
Another example is this one:
|
Another example is this one:
|
|
|
printf ("%d file%s processed", nfiles,
|
printf ("%d file%s processed", nfiles,
|
nfiles != 1 ? "s" : "");
|
nfiles != 1 ? "s" : "");
|
|
|
The problem with this example is that it assumes that plurals are made
|
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,
|
by adding `s'. If you apply gettext to the format string, like this,
|
|
|
printf (gettext ("%d file%s processed"), nfiles,
|
printf (gettext ("%d file%s processed"), nfiles,
|
nfiles != 1 ? "s" : "");
|
nfiles != 1 ? "s" : "");
|
|
|
the message can use different words, but it will still be forced to use
|
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
|
`s' for the plural. Here is a better way, with gettext being applied to
|
the two strings independently:
|
the two strings independently:
|
|
|
printf ((nfiles != 1 ? gettext ("%d files processed")
|
printf ((nfiles != 1 ? gettext ("%d files processed")
|
: gettext ("%d file processed")),
|
: gettext ("%d file processed")),
|
nfiles);
|
nfiles);
|
|
|
But this still doesn't work for languages like Polish, which has three
|
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,
|
plural forms: one for nfiles == 1, one for nfiles == 2, 3, 4, 22, 23,
|
24, ... and one for the rest. The GNU `ngettext' function solves this
|
24, ... and one for the rest. The GNU `ngettext' function solves this
|
problem:
|
problem:
|
|
|
printf (ngettext ("%d files processed", "%d file processed", nfiles),
|
printf (ngettext ("%d files processed", "%d file processed", nfiles),
|
nfiles);
|
nfiles);
|
|
|
|
|
File: standards.info, Node: Character Set, Next: Quote Characters, Prev: Internationalization, Up: Writing C
|
File: standards.info, Node: Character Set, Next: Quote Characters, Prev: Internationalization, Up: Writing C
|
|
|
5.9 Character Set
|
5.9 Character Set
|
=================
|
=================
|
|
|
Sticking to the ASCII character set (plain text, 7-bit characters) is
|
Sticking to the ASCII character set (plain text, 7-bit characters) is
|
preferred in GNU source code comments, text documents, and other
|
preferred in GNU source code comments, text documents, and other
|
contexts, unless there is good reason to do something else because of
|
contexts, unless there is good reason to do something else because of
|
the application domain. For example, if source code deals with the
|
the application domain. For example, if source code deals with the
|
French Revolutionary calendar, it is OK if its literal strings contain
|
French Revolutionary calendar, it is OK if its literal strings contain
|
accented characters in month names like "Flore'al". Also, it is OK to
|
accented characters in month names like "Flore'al". Also, it is OK to
|
use non-ASCII characters to represent proper names of contributors in
|
use non-ASCII characters to represent proper names of contributors in
|
change logs (*note Change Logs::).
|
change logs (*note Change Logs::).
|
|
|
If you need to use non-ASCII characters, you should normally stick
|
If you need to use non-ASCII characters, you should normally stick
|
with one encoding, as one cannot in general mix encodings reliably.
|
with one encoding, as one cannot in general mix encodings reliably.
|
|
|
|
|
File: standards.info, Node: Quote Characters, Next: Mmap, Prev: Character Set, Up: Writing C
|
File: standards.info, Node: Quote Characters, Next: Mmap, Prev: Character Set, Up: Writing C
|
|
|
5.10 Quote Characters
|
5.10 Quote Characters
|
=====================
|
=====================
|
|
|
In the C locale, GNU programs should stick to plain ASCII for quotation
|
In the C locale, GNU programs should stick to plain ASCII for quotation
|
characters in messages to users: preferably 0x60 (``') for left quotes
|
characters in messages to users: preferably 0x60 (``') for left quotes
|
and 0x27 (`'') for right quotes. It is ok, but not required, to use
|
and 0x27 (`'') for right quotes. It is ok, but not required, to use
|
locale-specific quotes in other locales.
|
locale-specific quotes in other locales.
|
|
|
The Gnulib (http://www.gnu.org/software/gnulib/) `quote' and
|
The Gnulib (http://www.gnu.org/software/gnulib/) `quote' and
|
`quotearg' modules provide a reasonably straightforward way to support
|
`quotearg' modules provide a reasonably straightforward way to support
|
locale-specific quote characters, as well as taking care of other
|
locale-specific quote characters, as well as taking care of other
|
issues, such as quoting a filename that itself contains a quote
|
issues, such as quoting a filename that itself contains a quote
|
character. See the Gnulib documentation for usage details.
|
character. See the Gnulib documentation for usage details.
|
|
|
In any case, the documentation for your program should clearly
|
In any case, the documentation for your program should clearly
|
specify how it does quoting, if different than the preferred method of
|
specify how it does quoting, if different than the preferred method of
|
``' and `''. This is especially important if the output of your
|
``' and `''. This is especially important if the output of your
|
program is ever likely to be parsed by another program.
|
program is ever likely to be parsed by another program.
|
|
|
Quotation characters are a difficult area in the computing world at
|
Quotation characters are a difficult area in the computing world at
|
this time: there are no true left or right quote characters in Latin1;
|
this time: there are no true left or right quote characters in Latin1;
|
the ``' character we use was standardized there as a grave accent.
|
the ``' character we use was standardized there as a grave accent.
|
Moreover, Latin1 is still not universally usable.
|
Moreover, Latin1 is still not universally usable.
|
|
|
Unicode contains the unambiguous quote characters required, and its
|
Unicode contains the unambiguous quote characters required, and its
|
common encoding UTF-8 is upward compatible with Latin1. However,
|
common encoding UTF-8 is upward compatible with Latin1. However,
|
Unicode and UTF-8 are not universally well-supported, either.
|
Unicode and UTF-8 are not universally well-supported, either.
|
|
|
This may change over the next few years, and then we will revisit
|
This may change over the next few years, and then we will revisit
|
this.
|
this.
|
|
|
|
|
File: standards.info, Node: Mmap, Prev: Quote Characters, Up: Writing C
|
File: standards.info, Node: Mmap, Prev: Quote Characters, Up: Writing C
|
|
|
5.11 Mmap
|
5.11 Mmap
|
=========
|
=========
|
|
|
Don't assume that `mmap' either works on all files or fails for all
|
Don't assume that `mmap' either works on all files or fails for all
|
files. It may work on some files and fail on others.
|
files. It may work on some files and fail on others.
|
|
|
The proper way to use `mmap' is to try it on the specific file for
|
The proper way to use `mmap' is to try it on the specific file for
|
which you want to use it--and if `mmap' doesn't work, fall back on
|
which you want to use it--and if `mmap' doesn't work, fall back on
|
doing the job in another way using `read' and `write'.
|
doing the job in another way using `read' and `write'.
|
|
|
The reason this precaution is needed is that the GNU kernel (the
|
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
|
HURD) provides a user-extensible file system, in which there can be many
|
different kinds of "ordinary files." Many of them support `mmap', but
|
different kinds of "ordinary files." Many of them support `mmap', but
|
some do not. It is important to make programs handle all these kinds
|
some do not. It is important to make programs handle all these kinds
|
of files.
|
of files.
|
|
|
|
|
File: standards.info, Node: Documentation, Next: Managing Releases, Prev: Writing C, Up: Top
|
File: standards.info, Node: Documentation, Next: Managing Releases, Prev: Writing C, Up: Top
|
|
|
6 Documenting Programs
|
6 Documenting Programs
|
**********************
|
**********************
|
|
|
A GNU program should ideally come with full free documentation, adequate
|
A GNU program should ideally come with full free documentation, adequate
|
for both reference and tutorial purposes. If the package can be
|
for both reference and tutorial purposes. If the package can be
|
programmed or extended, the documentation should cover programming or
|
programmed or extended, the documentation should cover programming or
|
extending it, as well as just using it.
|
extending it, as well as just using it.
|
|
|
* Menu:
|
* Menu:
|
|
|
* GNU Manuals:: Writing proper manuals.
|
* GNU Manuals:: Writing proper manuals.
|
* Doc Strings and Manuals:: Compiling doc strings doesn't make a manual.
|
* Doc Strings and Manuals:: Compiling doc strings doesn't make a manual.
|
* Manual Structure Details:: Specific structure conventions.
|
* Manual Structure Details:: Specific structure conventions.
|
* License for Manuals:: Writing the distribution terms for a manual.
|
* License for Manuals:: Writing the distribution terms for a manual.
|
* Manual Credits:: Giving credit to documentation contributors.
|
* Manual Credits:: Giving credit to documentation contributors.
|
* Printed Manuals:: Mentioning the printed manual.
|
* Printed Manuals:: Mentioning the printed manual.
|
* NEWS File:: NEWS files supplement manuals.
|
* NEWS File:: NEWS files supplement manuals.
|
* Change Logs:: Recording changes.
|
* Change Logs:: Recording changes.
|
* Man Pages:: Man pages are secondary.
|
* Man Pages:: Man pages are secondary.
|
* Reading other Manuals:: How far you can go in learning
|
* Reading other Manuals:: How far you can go in learning
|
from other manuals.
|
from other manuals.
|
|
|
|
|
File: standards.info, Node: GNU Manuals, Next: Doc Strings and Manuals, Up: Documentation
|
File: standards.info, Node: GNU Manuals, Next: Doc Strings and Manuals, Up: Documentation
|
|
|
6.1 GNU Manuals
|
6.1 GNU Manuals
|
===============
|
===============
|
|
|
The preferred document format for the GNU system is the Texinfo
|
The preferred document format for the GNU system is the Texinfo
|
formatting language. Every GNU package should (ideally) have
|
formatting language. Every GNU package should (ideally) have
|
documentation in Texinfo both for reference and for learners. Texinfo
|
documentation in Texinfo both for reference and for learners. Texinfo
|
makes it possible to produce a good quality formatted book, using TeX,
|
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
|
and to generate an Info file. It is also possible to generate HTML
|
output from Texinfo source. See the Texinfo manual, either the
|
output from Texinfo source. See the Texinfo manual, either the
|
hardcopy, or the on-line version available through `info' or the Emacs
|
hardcopy, or the on-line version available through `info' or the Emacs
|
Info subsystem (`C-h i').
|
Info subsystem (`C-h i').
|
|
|
Nowadays some other formats such as Docbook and Sgmltexi can be
|
Nowadays some other formats such as Docbook and Sgmltexi can be
|
converted automatically into Texinfo. It is ok to produce the Texinfo
|
converted automatically into Texinfo. It is ok to produce the Texinfo
|
documentation by conversion this way, as long as it gives good results.
|
documentation by conversion this way, as long as it gives good results.
|
|
|
Make sure your manual is clear to a reader who knows nothing about
|
Make sure your manual is clear to a reader who knows nothing about
|
the topic and reads it straight through. This means covering basic
|
the topic and reads it straight through. This means covering basic
|
topics at the beginning, and advanced topics only later. This also
|
topics at the beginning, and advanced topics only later. This also
|
means defining every specialized term when it is first used.
|
means defining every specialized term when it is first used.
|
|
|
Programmers tend to carry over the structure of the program as the
|
Programmers tend to carry over the structure of the program as the
|
structure for its documentation. But this structure is not necessarily
|
structure for its documentation. But this structure is not necessarily
|
good for explaining how to use the program; it may be irrelevant and
|
good for explaining how to use the program; it may be irrelevant and
|
confusing for a user.
|
confusing for a user.
|
|
|
Instead, the right way to structure documentation is according to the
|
Instead, the right way to structure documentation is according to the
|
concepts and questions that a user will have in mind when reading it.
|
concepts and questions that a user will have in mind when reading it.
|
This principle applies at every level, from the lowest (ordering
|
This principle applies at every level, from the lowest (ordering
|
sentences in a paragraph) to the highest (ordering of chapter topics
|
sentences in a paragraph) to the highest (ordering of chapter topics
|
within the manual). Sometimes this structure of ideas matches the
|
within the manual). Sometimes this structure of ideas matches the
|
structure of the implementation of the software being documented--but
|
structure of the implementation of the software being documented--but
|
often they are different. An important part of learning to write good
|
often they are different. An important part of learning to write good
|
documentation is to learn to notice when you have unthinkingly
|
documentation is to learn to notice when you have unthinkingly
|
structured the documentation like the implementation, stop yourself,
|
structured the documentation like the implementation, stop yourself,
|
and look for better alternatives.
|
and look for better alternatives.
|
|
|
For example, each program in the GNU system probably ought to be
|
For example, each program in the GNU system probably ought to be
|
documented in one manual; but this does not mean each program should
|
documented in one manual; but this does not mean each program should
|
have its own manual. That would be following the structure of the
|
have its own manual. That would be following the structure of the
|
implementation, rather than the structure that helps the user
|
implementation, rather than the structure that helps the user
|
understand.
|
understand.
|
|
|
Instead, each manual should cover a coherent _topic_. For example,
|
Instead, each manual should cover a coherent _topic_. For example,
|
instead of a manual for `diff' and a manual for `diff3', we have one
|
instead of a manual for `diff' and a manual for `diff3', we have one
|
manual for "comparison of files" which covers both of those programs,
|
manual for "comparison of files" which covers both of those programs,
|
as well as `cmp'. By documenting these programs together, we can make
|
as well as `cmp'. By documenting these programs together, we can make
|
the whole subject clearer.
|
the whole subject clearer.
|
|
|
The manual which discusses a program should certainly document all of
|
The manual which discusses a program should certainly document all of
|
the program's command-line options and all of its commands. It should
|
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
|
give examples of their use. But don't organize the manual as a list of
|
features. Instead, organize it logically, by subtopics. Address the
|
features. Instead, organize it logically, by subtopics. Address the
|
questions that a user will ask when thinking about the job that 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
|
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.
|
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
|
Explain what is recommended usage, and what kinds of usage users should
|
avoid.
|
avoid.
|
|
|
In general, a GNU manual should serve both as tutorial and reference.
|
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,
|
It should be set up for convenient access to each topic through Info,
|
and for reading straight through (appendixes aside). A GNU manual
|
and for reading straight through (appendixes aside). A GNU manual
|
should give a good introduction to a beginner reading through from the
|
should give a good introduction to a beginner reading through from the
|
start, and should also provide all the details that hackers want. 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
|
Bison manual is a good example of this--please take a look at it to see
|
what we mean.
|
what we mean.
|
|
|
That is not as hard as it first sounds. Arrange each chapter as a
|
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
|
logical breakdown of its topic, but order the sections, and write their
|
text, so that reading the chapter straight through makes sense. Do
|
text, so that reading the chapter straight through makes sense. Do
|
likewise when structuring the book into chapters, and when structuring a
|
likewise when structuring the book into chapters, and when structuring a
|
section into paragraphs. The watchword is, _at each point, address the
|
section into paragraphs. The watchword is, _at each point, address the
|
most fundamental and important issue raised by the preceding text._
|
most fundamental and important issue raised by the preceding text._
|
|
|
If necessary, add extra chapters at the beginning of the manual which
|
If necessary, add extra chapters at the beginning of the manual which
|
are purely tutorial and cover the basics of the subject. These provide
|
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
|
the framework for a beginner to understand the rest of the manual. The
|
Bison manual provides a good example of how to do this.
|
Bison manual provides a good example of how to do this.
|
|
|
To serve as a reference, a manual should have an Index that list all
|
To serve as a reference, a manual should have an Index that list all
|
the functions, variables, options, and important concepts that are part
|
the functions, variables, options, and important concepts that are part
|
of the program. One combined Index should do for a short manual, but
|
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.
|
sometimes for a complex package it is better to use multiple indices.
|
The Texinfo manual includes advice on preparing good index entries, see
|
The Texinfo manual includes advice on preparing good index entries, see
|
*Note Making Index Entries: (texinfo)Index Entries, and see *Note
|
*Note Making Index Entries: (texinfo)Index Entries, and see *Note
|
Defining the Entries of an Index: (texinfo)Indexing Commands.
|
Defining the Entries of an Index: (texinfo)Indexing Commands.
|
|
|
Don't use Unix man pages as a model for how to write GNU
|
Don't use Unix man pages as a model for how to write GNU
|
documentation; most of them are terse, badly structured, and give
|
documentation; most of them are terse, badly structured, and give
|
inadequate explanation of the underlying concepts. (There are, of
|
inadequate explanation of the underlying concepts. (There are, of
|
course, some exceptions.) Also, Unix man pages use a particular format
|
course, some exceptions.) Also, Unix man pages use a particular format
|
which is different from what we use in GNU manuals.
|
which is different from what we use in GNU manuals.
|
|
|
Please include an email address in the manual for where to report
|
Please include an email address in the manual for where to report
|
bugs _in the text of the manual_.
|
bugs _in the text of the manual_.
|
|
|
Please do not use the term "pathname" that is used in Unix
|
Please do not use the term "pathname" that is used in Unix
|
documentation; use "file name" (two words) instead. We use the term
|
documentation; use "file name" (two words) instead. We use the term
|
"path" only for search paths, which are lists of directory names.
|
"path" only for search paths, which are lists of directory names.
|
|
|
Please do not use the term "illegal" to refer to erroneous input to
|
Please do not use the term "illegal" to refer to erroneous input to
|
a computer program. Please use "invalid" for this, and reserve the
|
a computer program. Please use "invalid" for this, and reserve the
|
term "illegal" for activities prohibited by law.
|
term "illegal" for activities prohibited by law.
|
|
|
Please do not write `()' after a function name just to indicate it
|
Please do not write `()' after a function name just to indicate it
|
is a function. `foo ()' is not a function, it is a function call with
|
is a function. `foo ()' is not a function, it is a function call with
|
no arguments.
|
no arguments.
|
|
|
|
|
File: standards.info, Node: Doc Strings and Manuals, Next: Manual Structure Details, Prev: GNU Manuals, Up: Documentation
|
File: standards.info, Node: Doc Strings and Manuals, Next: Manual Structure Details, Prev: GNU Manuals, Up: Documentation
|
|
|
6.2 Doc Strings and Manuals
|
6.2 Doc Strings and Manuals
|
===========================
|
===========================
|
|
|
Some programming systems, such as Emacs, provide a documentation string
|
Some programming systems, such as Emacs, provide a documentation string
|
for each function, command or variable. You may be tempted to write a
|
for each function, command or variable. You may be tempted to write a
|
reference manual by compiling the documentation strings and writing 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
|
little additional text to go around them--but you must not do it. That
|
approach is a fundamental mistake. The text of well-written
|
approach is a fundamental mistake. The text of well-written
|
documentation strings will be entirely wrong for a manual.
|
documentation strings will be entirely wrong for a manual.
|
|
|
A documentation string needs to stand alone--when it appears on the
|
A documentation string needs to stand alone--when it appears on the
|
screen, there will be no other text to introduce or explain it.
|
screen, there will be no other text to introduce or explain it.
|
Meanwhile, it can be rather informal in style.
|
Meanwhile, it can be rather informal in style.
|
|
|
The text describing a function or variable in a manual must not stand
|
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
|
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
|
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
|
should often make some general points that apply to several functions or
|
variables. The previous descriptions of functions and variables in the
|
variables. The previous descriptions of functions and variables in the
|
section will also have given information about the topic. A description
|
section will also have given information about the topic. A description
|
written to stand alone would repeat some of that information; this
|
written to stand alone would repeat some of that information; this
|
redundancy looks bad. Meanwhile, the informality that is acceptable in
|
redundancy looks bad. Meanwhile, the informality that is acceptable in
|
a documentation string is totally unacceptable in a manual.
|
a documentation string is totally unacceptable in a manual.
|
|
|
The only good way to use documentation strings in writing a good
|
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.
|
manual is to use them as a source of information for writing good text.
|
|
|
|
|
File: standards.info, Node: Manual Structure Details, Next: License for Manuals, Prev: Doc Strings and Manuals, Up: Documentation
|
File: standards.info, Node: Manual Structure Details, Next: License for Manuals, Prev: Doc Strings and Manuals, Up: Documentation
|
|
|
6.3 Manual Structure Details
|
6.3 Manual Structure Details
|
============================
|
============================
|
|
|
The title page of the manual should state the version of the programs or
|
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
|
packages documented in the manual. The Top node of the manual should
|
also contain this information. If the manual is changing more
|
also contain this information. If the manual is changing more
|
frequently than or independent of the program, also state a version
|
frequently than or independent of the program, also state a version
|
number for the manual in both of these places.
|
number for the manual in both of these places.
|
|
|
Each program documented in the manual should have a node named
|
Each program documented in the manual should have a node named
|
`PROGRAM Invocation' or `Invoking PROGRAM'. This node (together with
|
`PROGRAM Invocation' or `Invoking PROGRAM'. This node (together with
|
its subnodes, if any) should describe the program's command line
|
its subnodes, if any) should describe the program's command line
|
arguments and how to run it (the sort of information people would look
|
arguments and how to run it (the sort of information people would look
|
for in a man page). Start with an `@example' containing a template for
|
for in a man page). Start with an `@example' containing a template for
|
all the options and arguments that the program uses.
|
all the options and arguments that the program uses.
|
|
|
Alternatively, put a menu item in some menu whose item name fits one
|
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
|
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.
|
to as the node for this purpose, regardless of the node's actual name.
|
|
|
The `--usage' feature of the Info reader looks for such a node or
|
The `--usage' 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
|
menu item in order to find the relevant text, so it is essential for
|
every Texinfo file to have one.
|
every Texinfo file to have one.
|
|
|
If one manual describes several programs, it should have such a node
|
If one manual describes several programs, it should have such a node
|
for each program described in the manual.
|
for each program described in the manual.
|
|
|
|
|
File: standards.info, Node: License for Manuals, Next: Manual Credits, Prev: Manual Structure Details, Up: Documentation
|
File: standards.info, Node: License for Manuals, Next: Manual Credits, Prev: Manual Structure Details, Up: Documentation
|
|
|
6.4 License for Manuals
|
6.4 License for Manuals
|
=======================
|
=======================
|
|
|
Please use the GNU Free Documentation License for all GNU manuals that
|
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
|
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
|
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
|
collection. For a single short document, you can use a very permissive
|
non-copyleft license, to avoid taking up space with a long license.
|
non-copyleft license, to avoid taking up space with a long license.
|
|
|
See `http://www.gnu.org/copyleft/fdl-howto.html' for more explanation
|
See `http://www.gnu.org/copyleft/fdl-howto.html' for more explanation
|
of how to employ the GFDL.
|
of how to employ the GFDL.
|
|
|
Note that it is not obligatory to include a copy of the GNU GPL or
|
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
|
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;
|
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
|
in a short manual, whose size would be increased considerably by
|
including the program's license, it is probably better not to include
|
including the program's license, it is probably better not to include
|
it.
|
it.
|
|
|
|
|
File: standards.info, Node: Manual Credits, Next: Printed Manuals, Prev: License for Manuals, Up: Documentation
|
File: standards.info, Node: Manual Credits, Next: Printed Manuals, Prev: License for Manuals, Up: Documentation
|
|
|
6.5 Manual Credits
|
6.5 Manual Credits
|
==================
|
==================
|
|
|
Please credit the principal human writers of the manual as the authors,
|
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
|
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
|
the company in a suitable place in the manual, but do not cite the
|
company as an author.
|
company as an author.
|
|
|
|
|
File: standards.info, Node: Printed Manuals, Next: NEWS File, Prev: Manual Credits, Up: Documentation
|
File: standards.info, Node: Printed Manuals, Next: NEWS File, Prev: Manual Credits, Up: Documentation
|
|
|
6.6 Printed Manuals
|
6.6 Printed Manuals
|
===================
|
===================
|
|
|
The FSF publishes some GNU manuals in printed form. To encourage sales
|
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
|
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
|
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
|
information for getting it--for instance, with a link to the page
|
`http://www.gnu.org/order/order.html'. This should not be included in
|
`http://www.gnu.org/order/order.html'. This should not be included in
|
the printed manual, though, because there it is redundant.
|
the printed manual, though, because there it is redundant.
|
|
|
It is also useful to explain in the on-line forms of the manual how
|
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.
|
the user can print out the manual from the sources.
|
|
|
|
|
File: standards.info, Node: NEWS File, Next: Change Logs, Prev: Printed Manuals, Up: Documentation
|
File: standards.info, Node: NEWS File, Next: Change Logs, Prev: Printed Manuals, Up: Documentation
|
|
|
6.7 The NEWS File
|
6.7 The NEWS File
|
=================
|
=================
|
|
|
In addition to its manual, the package should have a file named `NEWS'
|
In addition to its manual, the package should have a file named `NEWS'
|
which contains a list of user-visible changes worth mentioning. In
|
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
|
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
|
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
|
file after the newer items. This way, a user upgrading from any
|
previous version can see what is new.
|
previous version can see what is new.
|
|
|
If the `NEWS' file gets very long, move some of the older items into
|
If the `NEWS' file gets very long, move some of the older items into
|
a file named `ONEWS' and put a note at the end referring the user to
|
a file named `ONEWS' and put a note at the end referring the user to
|
that file.
|
that file.
|
|
|
|
|
File: standards.info, Node: Change Logs, Next: Man Pages, Prev: NEWS File, Up: Documentation
|
File: standards.info, Node: Change Logs, Next: Man Pages, Prev: NEWS File, Up: Documentation
|
|
|
6.8 Change Logs
|
6.8 Change Logs
|
===============
|
===============
|
|
|
Keep a change log to describe all the changes made to program source
|
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
|
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.
|
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.
|
Often a new bug can be found by looking at what was recently changed.
|
More importantly, change logs can help you eliminate conceptual
|
More importantly, change logs can help you eliminate conceptual
|
inconsistencies between different parts of a program, by giving you a
|
inconsistencies between different parts of a program, by giving you a
|
history of how the conflicting concepts arose and who they came from.
|
history of how the conflicting concepts arose and who they came from.
|
|
|
* Menu:
|
* Menu:
|
|
|
* Change Log Concepts::
|
* Change Log Concepts::
|
* Style of Change Logs::
|
* Style of Change Logs::
|
* Simple Changes::
|
* Simple Changes::
|
* Conditional Changes::
|
* Conditional Changes::
|
* Indicating the Part Changed::
|
* Indicating the Part Changed::
|
|
|
|
|
File: standards.info, Node: Change Log Concepts, Next: Style of Change Logs, Up: Change Logs
|
File: standards.info, Node: Change Log Concepts, Next: Style of Change Logs, Up: Change Logs
|
|
|
6.8.1 Change Log Concepts
|
6.8.1 Change Log Concepts
|
-------------------------
|
-------------------------
|
|
|
You can think of the change log as a conceptual "undo list" which
|
You can think of the change log as a conceptual "undo list" which
|
explains how earlier versions were different from the current version.
|
explains how earlier versions were different from the current version.
|
People can see the current version; they don't need the change log to
|
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
|
tell them what is in it. What they want from a change log is a clear
|
explanation of how the earlier version differed.
|
explanation of how the earlier version differed.
|
|
|
The change log file is normally called `ChangeLog' and covers an
|
The change log file is normally called `ChangeLog' and covers an
|
entire directory. Each directory can have its own change log, or a
|
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.
|
directory can use the change log of its parent directory-it's up to you.
|
|
|
Another alternative is to record change log information with a
|
Another alternative is to record change log information with a
|
version control system such as RCS or CVS. This can be converted
|
version control system such as RCS or CVS. This can be converted
|
automatically to a `ChangeLog' file using `rcs2log'; in Emacs, the
|
automatically to a `ChangeLog' file using `rcs2log'; in Emacs, the
|
command `C-x v a' (`vc-update-change-log') does the job.
|
command `C-x v a' (`vc-update-change-log') does the job.
|
|
|
There's no need to describe the full purpose of the changes or how
|
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,
|
they work together. If you think that a change calls for explanation,
|
you're probably right. Please do explain it--but please put the
|
you're probably right. Please do explain it--but please put the
|
explanation in comments in the code, where people will see it whenever
|
explanation in comments in the code, where people will see it whenever
|
they see the code. For example, "New function" is enough for the
|
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
|
change log when you add a function, because there should be a comment
|
before the function definition to explain what it does.
|
before the function definition to explain what it does.
|
|
|
In the past, we recommended not mentioning changes in non-software
|
In the past, we recommended not mentioning changes in non-software
|
files (manuals, help files, etc.) in change logs. However, we've been
|
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
|
advised that it is a good idea to include them, for the sake of
|
copyright records.
|
copyright records.
|
|
|
However, sometimes it is useful to write one line to describe the
|
However, sometimes it is useful to write one line to describe the
|
overall purpose of a batch of changes.
|
overall purpose of a batch of changes.
|
|
|
The easiest way to add an entry to `ChangeLog' is with the Emacs
|
The easiest way to add an entry to `ChangeLog' is with the Emacs
|
command `M-x add-change-log-entry'. An entry should have an asterisk,
|
command `M-x add-change-log-entry'. An entry should have an asterisk,
|
the name of the changed file, and then in parentheses the name of the
|
the name of the changed file, and then in parentheses the name of the
|
changed functions, variables or whatever, followed by a colon. Then
|
changed functions, variables or whatever, followed by a colon. Then
|
describe the changes you made to that function or variable.
|
describe the changes you made to that function or variable.
|
|
|
|
|
File: standards.info, Node: Style of Change Logs, Next: Simple Changes, Prev: Change Log Concepts, Up: Change Logs
|
File: standards.info, Node: Style of Change Logs, Next: Simple Changes, Prev: Change Log Concepts, Up: Change Logs
|
|
|
6.8.2 Style of Change Logs
|
6.8.2 Style of Change Logs
|
--------------------------
|
--------------------------
|
|
|
Here are some simple examples of change log entries, starting with the
|
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,
|
header line that says who made the change and when it was installed,
|
followed by descriptions of specific changes. (These examples are
|
followed by descriptions of specific changes. (These examples are
|
drawn from Emacs and GCC.)
|
drawn from Emacs and GCC.)
|
|
|
1998-08-17 Richard Stallman
|
1998-08-17 Richard Stallman
|
|
|
* register.el (insert-register): Return nil.
|
* register.el (insert-register): Return nil.
|
(jump-to-register): Likewise.
|
(jump-to-register): Likewise.
|
|
|
* sort.el (sort-subr): Return nil.
|
* sort.el (sort-subr): Return nil.
|
|
|
* tex-mode.el (tex-bibtex-file, tex-file, tex-region):
|
* tex-mode.el (tex-bibtex-file, tex-file, tex-region):
|
Restart the tex shell if process is gone or stopped.
|
Restart the tex shell if process is gone or stopped.
|
(tex-shell-running): New function.
|
(tex-shell-running): New function.
|
|
|
* expr.c (store_one_arg): Round size up for move_block_to_reg.
|
* expr.c (store_one_arg): Round size up for move_block_to_reg.
|
(expand_call): Round up when emitting USE insns.
|
(expand_call): Round up when emitting USE insns.
|
* stmt.c (assign_parms): Round size up for move_block_from_reg.
|
* stmt.c (assign_parms): Round size up for move_block_from_reg.
|
|
|
It's important to name the changed function or variable in full.
|
It's important to name the changed function or variable in full.
|
Don't abbreviate function or variable names, and don't combine them.
|
Don't abbreviate function or variable names, and don't combine them.
|
Subsequent maintainers will often search for a function name to find all
|
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,
|
the change log entries that pertain to it; if you abbreviate the name,
|
they won't find it when they search.
|
they won't find it when they search.
|
|
|
For example, some people are tempted to abbreviate groups of function
|
For example, some people are tempted to abbreviate groups of function
|
names by writing `* register.el ({insert,jump-to}-register)'; this is
|
names by writing `* register.el ({insert,jump-to}-register)'; this is
|
not a good idea, since searching for `jump-to-register' or
|
not a good idea, since searching for `jump-to-register' or
|
`insert-register' would not find that entry.
|
`insert-register' would not find that entry.
|
|
|
Separate unrelated change log entries with blank lines. When two
|
Separate unrelated change log entries with blank lines. When two
|
entries represent parts of the same change, so that they work together,
|
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
|
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.
|
name and the asterisk when successive entries are in the same file.
|
|
|
Break long lists of function names by closing continued lines with
|
Break long lists of function names by closing continued lines with
|
`)', rather than `,', and opening the continuation with `(' as in this
|
`)', rather than `,', and opening the continuation with `(' as in this
|
example:
|
example:
|
|
|
* keyboard.c (menu_bar_items, tool_bar_items)
|
* keyboard.c (menu_bar_items, tool_bar_items)
|
(Fexecute_extended_command): Deal with `keymap' property.
|
(Fexecute_extended_command): Deal with `keymap' property.
|
|
|
When you install someone else's changes, put the contributor's name
|
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
|
in the change log entry rather than in the text of the entry. In other
|
words, write this:
|
words, write this:
|
|
|
2002-07-14 John Doe
|
2002-07-14 John Doe
|
|
|
* sewing.c: Make it sew.
|
* sewing.c: Make it sew.
|
|
|
rather than this:
|
rather than this:
|
|
|
2002-07-14 Usual Maintainer
|
2002-07-14 Usual Maintainer
|
|
|
* sewing.c: Make it sew. Patch by jdoe@gnu.org.
|
* sewing.c: Make it sew. Patch by jdoe@gnu.org.
|
|
|
As for the date, that should be the date you applied the change.
|
As for the date, that should be the date you applied the change.
|
|
|
|
|
File: standards.info, Node: Simple Changes, Next: Conditional Changes, Prev: Style of Change Logs, Up: Change Logs
|
File: standards.info, Node: Simple Changes, Next: Conditional Changes, Prev: Style of Change Logs, Up: Change Logs
|
|
|
6.8.3 Simple Changes
|
6.8.3 Simple Changes
|
--------------------
|
--------------------
|
|
|
Certain simple kinds of changes don't need much detail in the change
|
Certain simple kinds of changes don't need much detail in the change
|
log.
|
log.
|
|
|
When you change the calling sequence of a function in a simple
|
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
|
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
|
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
|
the callers that you changed. Just write in the entry for the function
|
being called, "All callers changed"--like this:
|
being called, "All callers changed"--like this:
|
|
|
* keyboard.c (Fcommand_execute): New arg SPECIAL.
|
* keyboard.c (Fcommand_execute): New arg SPECIAL.
|
All callers changed.
|
All callers changed.
|
|
|
When you change just comments or doc strings, it is enough to write
|
When you change just comments or doc strings, it is enough to write
|
an entry for the file, without mentioning the functions. Just "Doc
|
an entry for the file, without mentioning the functions. Just "Doc
|
fixes" is enough for the change log.
|
fixes" is enough for the change log.
|
|
|
There's no technical need to make change log entries for
|
There's no technical need to make change log entries for
|
documentation files. This is because documentation is not susceptible
|
documentation files. This is because documentation is not susceptible
|
to bugs that are hard to fix. Documentation does not consist of parts
|
to bugs that are hard to fix. Documentation does not consist of parts
|
that must interact in a precisely engineered fashion. To correct an
|
that must interact in a precisely engineered fashion. To correct an
|
error, you need not know the history of the erroneous passage; it is
|
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
|
enough to compare what the documentation says with the way the program
|
actually works.
|
actually works.
|
|
|
However, you should keep change logs for documentation files when the
|
However, you should keep change logs for documentation files when the
|
project gets copyright assignments from its contributors, so as to make
|
project gets copyright assignments from its contributors, so as to make
|
the records of authorship more accurate.
|
the records of authorship more accurate.
|
|
|
|
|
File: standards.info, Node: Conditional Changes, Next: Indicating the Part Changed, Prev: Simple Changes, Up: Change Logs
|
File: standards.info, Node: Conditional Changes, Next: Indicating the Part Changed, Prev: Simple Changes, Up: Change Logs
|
|
|
6.8.4 Conditional Changes
|
6.8.4 Conditional Changes
|
-------------------------
|
-------------------------
|
|
|
C programs often contain compile-time `#if' conditionals. Many changes
|
C programs often contain compile-time `#if' conditionals. Many changes
|
are conditional; sometimes you add a new definition which is entirely
|
are conditional; sometimes you add a new definition which is entirely
|
contained in a conditional. It is very useful to indicate in the
|
contained in a conditional. It is very useful to indicate in the
|
change log the conditions for which the change applies.
|
change log the conditions for which the change applies.
|
|
|
Our convention for indicating conditional changes is to use square
|
Our convention for indicating conditional changes is to use square
|
brackets around the name of the condition.
|
brackets around the name of the condition.
|
|
|
Here is a simple example, describing a change which is conditional
|
Here is a simple example, describing a change which is conditional
|
but does not have a function or entity name associated with it:
|
but does not have a function or entity name associated with it:
|
|
|
* xterm.c [SOLARIS2]: Include string.h.
|
* xterm.c [SOLARIS2]: Include string.h.
|
|
|
Here is an entry describing a new definition which is entirely
|
Here is an entry describing a new definition which is entirely
|
conditional. This new definition for the macro `FRAME_WINDOW_P' is
|
conditional. This new definition for the macro `FRAME_WINDOW_P' is
|
used only when `HAVE_X_WINDOWS' is defined:
|
used only when `HAVE_X_WINDOWS' is defined:
|
|
|
* frame.h [HAVE_X_WINDOWS] (FRAME_WINDOW_P): Macro defined.
|
* frame.h [HAVE_X_WINDOWS] (FRAME_WINDOW_P): Macro defined.
|
|
|
Here is an entry for a change within the function `init_display',
|
Here is an entry for a change within the function `init_display',
|
whose definition as a whole is unconditional, but the changes themselves
|
whose definition as a whole is unconditional, but the changes themselves
|
are contained in a `#ifdef HAVE_LIBNCURSES' conditional:
|
are contained in a `#ifdef HAVE_LIBNCURSES' conditional:
|
|
|
* dispnew.c (init_display) [HAVE_LIBNCURSES]: If X, call tgetent.
|
* dispnew.c (init_display) [HAVE_LIBNCURSES]: If X, call tgetent.
|
|
|
Here is an entry for a change that takes affect only when a certain
|
Here is an entry for a change that takes affect only when a certain
|
macro is _not_ defined:
|
macro is _not_ defined:
|
|
|
(gethostname) [!HAVE_SOCKETS]: Replace with winsock version.
|
(gethostname) [!HAVE_SOCKETS]: Replace with winsock version.
|
|
|
|
|
File: standards.info, Node: Indicating the Part Changed, Prev: Conditional Changes, Up: Change Logs
|
File: standards.info, Node: Indicating the Part Changed, Prev: Conditional Changes, Up: Change Logs
|
|
|
6.8.5 Indicating the Part Changed
|
6.8.5 Indicating the Part Changed
|
---------------------------------
|
---------------------------------
|
|
|
Indicate the part of a function which changed by using angle brackets
|
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
|
enclosing an indication of what the changed part does. Here is an entry
|
for a change in the part of the function `sh-while-getopts' that deals
|
for a change in the part of the function `sh-while-getopts' that deals
|
with `sh' commands:
|
with `sh' commands:
|
|
|
* progmodes/sh-script.el (sh-while-getopts) : Handle case that
|
* progmodes/sh-script.el (sh-while-getopts) : Handle case that
|
user-specified option string is empty.
|
user-specified option string is empty.
|
|
|
|
|
File: standards.info, Node: Man Pages, Next: Reading other Manuals, Prev: Change Logs, Up: Documentation
|
File: standards.info, Node: Man Pages, Next: Reading other Manuals, Prev: Change Logs, Up: Documentation
|
|
|
6.9 Man Pages
|
6.9 Man Pages
|
=============
|
=============
|
|
|
In the GNU project, man pages are secondary. It is not necessary or
|
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.
|
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.
|
It's your choice whether to include a man page in your program.
|
|
|
When you make this decision, consider that supporting a man page
|
When you make this decision, consider that supporting a man page
|
requires continual effort each time the program is changed. The time
|
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.
|
you spend on the man page is time taken away from more useful work.
|
|
|
For a simple program which changes little, updating the man page may
|
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,
|
be a small job. Then there is little reason not to include a man page,
|
if you have one.
|
if you have one.
|
|
|
For a large program that changes a great deal, updating a man page
|
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,
|
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
|
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
|
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
|
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
|
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
|
pick it up yourself; it may be better to withdraw the man page from the
|
distribution until someone else agrees to update it.
|
distribution until someone else agrees to update it.
|
|
|
When a program changes only a little, you may feel that the
|
When a program changes only a little, you may feel that the
|
discrepancies are small enough that the man page remains useful without
|
discrepancies are small enough that the man page remains useful without
|
updating. If so, put a prominent note near the beginning of the man
|
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
|
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
|
is more authoritative. The note should say how to access the Texinfo
|
documentation.
|
documentation.
|
|
|
Be sure that man pages include a copyright statement and free
|
Be sure that man pages include a copyright statement and free
|
license. The simple all-permissive license is appropriate for simple
|
license. The simple all-permissive license is appropriate for simple
|
man pages:
|
man pages:
|
|
|
Copying and distribution of this file, with or without modification,
|
Copying and distribution of this file, with or without modification,
|
are permitted in any medium without royalty provided the copyright
|
are permitted in any medium without royalty provided the copyright
|
notice and this notice are preserved.
|
notice and this notice are preserved.
|
|
|
For long man pages, with enough explanation and documentation that
|
For long man pages, with enough explanation and documentation that
|
they can be considered true manuals, use the GFDL (*note License for
|
they can be considered true manuals, use the GFDL (*note License for
|
Manuals::).
|
Manuals::).
|
|
|
Finally, the GNU help2man program
|
Finally, the GNU help2man program
|
(`http://www.gnu.org/software/help2man/') is one way to automate
|
(`http://www.gnu.org/software/help2man/') is one way to automate
|
generation of a man page, in this case from `--help' output. This is
|
generation of a man page, in this case from `--help' output. This is
|
sufficient in many cases.
|
sufficient in many cases.
|
|
|
|
|
File: standards.info, Node: Reading other Manuals, Prev: Man Pages, Up: Documentation
|
File: standards.info, Node: Reading other Manuals, Prev: Man Pages, Up: Documentation
|
|
|
6.10 Reading other Manuals
|
6.10 Reading other Manuals
|
==========================
|
==========================
|
|
|
There may be non-free books or documentation files that describe the
|
There may be non-free books or documentation files that describe the
|
program you are documenting.
|
program you are documenting.
|
|
|
It is ok to use these documents for reference, just as the author of
|
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
|
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
|
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
|
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
|
everyone who writes about the subject. But be careful not to copy your
|
outline structure, wording, tables or examples from preexisting non-free
|
outline structure, wording, tables or examples from preexisting non-free
|
documentation. Copying from free documentation may be ok; please check
|
documentation. Copying from free documentation may be ok; please check
|
with the FSF about the individual case.
|
with the FSF about the individual case.
|
|
|
|
|
File: standards.info, Node: Managing Releases, Next: References, Prev: Documentation, Up: Top
|
File: standards.info, Node: Managing Releases, Next: References, Prev: Documentation, Up: Top
|
|
|
7 The Release Process
|
7 The Release Process
|
*********************
|
*********************
|
|
|
Making a release is more than just bundling up your source files in 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
|
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
|
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
|
should conform to the GNU standards described below, and your directory
|
layout should also conform to the standards discussed below. Doing so
|
layout should also conform to the standards discussed below. Doing so
|
makes it easy to include your package into the larger framework of all
|
makes it easy to include your package into the larger framework of all
|
GNU software.
|
GNU software.
|
|
|
* Menu:
|
* Menu:
|
|
|
* Configuration:: How configuration of GNU packages should work.
|
* Configuration:: How configuration of GNU packages should work.
|
* Makefile Conventions:: Makefile conventions.
|
* Makefile Conventions:: Makefile conventions.
|
* Releases:: Making releases
|
* Releases:: Making releases
|
|
|
|
|
File: standards.info, Node: Configuration, Next: Makefile Conventions, Up: Managing Releases
|
File: standards.info, Node: Configuration, Next: Makefile Conventions, Up: Managing Releases
|
|
|
7.1 How Configuration Should Work
|
7.1 How Configuration Should Work
|
=================================
|
=================================
|
|
|
Each GNU distribution should come with a shell script named
|
Each GNU distribution should come with a shell script named
|
`configure'. This script is given arguments which describe the kind of
|
`configure'. This script is given arguments which describe the kind of
|
machine and system you want to compile the program for.
|
machine and system you want to compile the program for.
|
|
|
The `configure' script must record the configuration options so that
|
The `configure' script must record the configuration options so that
|
they affect compilation.
|
they affect compilation.
|
|
|
One way to do this is to make a link from a standard name such as
|
One way to do this is to make a link from a standard name such as
|
`config.h' to the proper configuration file for the chosen system. If
|
`config.h' to the proper configuration file for the chosen system. If
|
you use this technique, the distribution should _not_ contain a file
|
you use this technique, the distribution should _not_ contain a file
|
named `config.h'. This is so that people won't be able to build the
|
named `config.h'. This is so that people won't be able to build the
|
program without configuring it first.
|
program without configuring it first.
|
|
|
Another thing that `configure' can do is to edit the Makefile. If
|
Another thing that `configure' can do is to edit the Makefile. If
|
you do this, the distribution should _not_ contain a file named
|
you do this, the distribution should _not_ contain a file named
|
`Makefile'. Instead, it should include a file `Makefile.in' which
|
`Makefile'. Instead, it should include a file `Makefile.in' which
|
contains the input used for editing. Once again, this is so that people
|
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.
|
won't be able to build the program without configuring it first.
|
|
|
If `configure' does write the `Makefile', then `Makefile' should
|
If `configure' does write the `Makefile', then `Makefile' should
|
have a target named `Makefile' which causes `configure' to be rerun,
|
have a target named `Makefile' which causes `configure' to be rerun,
|
setting up the same configuration that was set up last time. The files
|
setting up the same configuration that was set up last time. The files
|
that `configure' reads should be listed as dependencies of `Makefile'.
|
that `configure' reads should be listed as dependencies of `Makefile'.
|
|
|
All the files which are output from the `configure' script should
|
All the files which are output from the `configure' script should
|
have comments at the beginning explaining that they were generated
|
have comments at the beginning explaining that they were generated
|
automatically using `configure'. This is so that users won't think of
|
automatically using `configure'. This is so that users won't think of
|
trying to edit them by hand.
|
trying to edit them by hand.
|
|
|
The `configure' script should write a file named `config.status'
|
The `configure' script should write a file named `config.status'
|
which describes which configuration options were specified when the
|
which describes which configuration options were specified when the
|
program was last configured. This file should be a shell script which,
|
program was last configured. This file should be a shell script which,
|
if run, will recreate the same configuration.
|
if run, will recreate the same configuration.
|
|
|
The `configure' script should accept an option of the form
|
The `configure' script should accept an option of the form
|
`--srcdir=DIRNAME' to specify the directory where sources are found (if
|
`--srcdir=DIRNAME' to specify the directory where sources are found (if
|
it is not the current directory). This makes it possible to build the
|
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
|
program in a separate directory, so that the actual source directory is
|
not modified.
|
not modified.
|
|
|
If the user does not specify `--srcdir', then `configure' should
|
If the user does not specify `--srcdir', then `configure' should
|
check both `.' and `..' to see if it can find the sources. If it finds
|
check both `.' and `..' to see if it can find the sources. If it finds
|
the sources in one of these places, it should use them from there.
|
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
|
Otherwise, it should report that it cannot find the sources, and should
|
exit with nonzero status.
|
exit with nonzero status.
|
|
|
Usually the easy way to support `--srcdir' is by editing a
|
Usually the easy way to support `--srcdir' is by editing a
|
definition of `VPATH' into the Makefile. Some rules may need to refer
|
definition of `VPATH' into the Makefile. Some rules may need to refer
|
explicitly to the specified source directory. To make this possible,
|
explicitly to the specified source directory. To make this possible,
|
`configure' can add to the Makefile a variable named `srcdir' whose
|
`configure' can add to the Makefile a variable named `srcdir' whose
|
value is precisely the specified directory.
|
value is precisely the specified directory.
|
|
|
The `configure' script should also take an argument which specifies
|
The `configure' script should also take an argument which specifies
|
the type of system to build the program for. This argument should look
|
the type of system to build the program for. This argument should look
|
like this:
|
like this:
|
|
|
CPU-COMPANY-SYSTEM
|
CPU-COMPANY-SYSTEM
|
|
|
For example, an Athlon-based GNU/Linux system might be
|
For example, an Athlon-based GNU/Linux system might be
|
`i686-pc-linux-gnu'.
|
`i686-pc-linux-gnu'.
|
|
|
The `configure' script needs to be able to decode all plausible
|
The `configure' script needs to be able to decode all plausible
|
alternatives for how to describe a machine. Thus,
|
alternatives for how to describe a machine. Thus,
|
`athlon-pc-gnu/linux' would be a valid alias. There is a shell script
|
`athlon-pc-gnu/linux' would be a valid alias. There is a shell script
|
called `config.sub'
|
called `config.sub'
|
(http://savannah.gnu.org/cgi-bin/viewcvs/*checkout*/config/config/config.sub)
|
(http://savannah.gnu.org/cgi-bin/viewcvs/*checkout*/config/config/config.sub)
|
that you can use as a subroutine to validate system types and
|
that you can use as a subroutine to validate system types and
|
canonicalize aliases.
|
canonicalize aliases.
|
|
|
The `configure' script should also take the option
|
The `configure' script should also take the option
|
`--build=BUILDTYPE', which should be equivalent to a plain BUILDTYPE
|
`--build=BUILDTYPE', which should be equivalent to a plain BUILDTYPE
|
argument. For example, `configure --build=i686-pc-linux-gnu' is
|
argument. For example, `configure --build=i686-pc-linux-gnu' is
|
equivalent to `configure i686-pc-linux-gnu'. When the build type is
|
equivalent to `configure i686-pc-linux-gnu'. When the build type is
|
not specified by an option or argument, the `configure' script should
|
not specified by an option or argument, the `configure' script should
|
normally guess it using the shell script `config.guess'
|
normally guess it using the shell script `config.guess'
|
(http://savannah.gnu.org/cgi-bin/viewcvs/*checkout*/config/config/config.guess).
|
(http://savannah.gnu.org/cgi-bin/viewcvs/*checkout*/config/config/config.guess).
|
|
|
Other options are permitted to specify in more detail the software
|
Other options are permitted to specify in more detail the software
|
or hardware present on the machine, to include or exclude optional parts
|
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
|
of the package, or to adjust the name of some tools or arguments to
|
them:
|
them:
|
|
|
`--enable-FEATURE[=PARAMETER]'
|
`--enable-FEATURE[=PARAMETER]'
|
Configure the package to build and install an optional user-level
|
Configure the package to build and install an optional user-level
|
facility called FEATURE. This allows users to choose which
|
facility called FEATURE. This allows users to choose which
|
optional features to include. Giving an optional PARAMETER of
|
optional features to include. Giving an optional PARAMETER of
|
`no' should omit FEATURE, if it is built by default.
|
`no' should omit FEATURE, if it is built by default.
|
|
|
No `--enable' option should *ever* cause one feature to replace
|
No `--enable' option should *ever* cause one feature to replace
|
another. No `--enable' option should ever substitute one useful
|
another. No `--enable' option should ever substitute one useful
|
behavior for another useful behavior. The only proper use for
|
behavior for another useful behavior. The only proper use for
|
`--enable' is for questions of whether to build part of the program
|
`--enable' is for questions of whether to build part of the program
|
or exclude it.
|
or exclude it.
|
|
|
`--with-PACKAGE'
|
`--with-PACKAGE'
|
The package PACKAGE will be installed, so configure this package
|
The package PACKAGE will be installed, so configure this package
|
to work with PACKAGE.
|
to work with PACKAGE.
|
|
|
Possible values of PACKAGE include `gnu-as' (or `gas'), `gnu-ld',
|
Possible values of PACKAGE include `gnu-as' (or `gas'), `gnu-ld',
|
`gnu-libc', `gdb', `x', and `x-toolkit'.
|
`gnu-libc', `gdb', `x', and `x-toolkit'.
|
|
|
Do not use a `--with' option to specify the file name to use to
|
Do not use a `--with' option to specify the file name to use to
|
find certain files. That is outside the scope of what `--with'
|
find certain files. That is outside the scope of what `--with'
|
options are for.
|
options are for.
|
|
|
`VARIABLE=VALUE'
|
`VARIABLE=VALUE'
|
Set the value of the variable VARIABLE to VALUE. This is used to
|
Set the value of the variable VARIABLE to VALUE. This is used to
|
override the default values of commands or arguments in the build
|
override the default values of commands or arguments in the build
|
process. For example, the user could issue `configure CFLAGS=-g
|
process. For example, the user could issue `configure CFLAGS=-g
|
CXXFLAGS=-g' to build with debugging information and without the
|
CXXFLAGS=-g' to build with debugging information and without the
|
default optimization.
|
default optimization.
|
|
|
Specifying variables as arguments to `configure', like this:
|
Specifying variables as arguments to `configure', like this:
|
./configure CC=gcc
|
./configure CC=gcc
|
is preferable to setting them in environment variables:
|
is preferable to setting them in environment variables:
|
CC=gcc ./configure
|
CC=gcc ./configure
|
as it helps to recreate the same configuration later with
|
as it helps to recreate the same configuration later with
|
`config.status'.
|
`config.status'.
|
|
|
All `configure' scripts should accept all of the "detail" options
|
All `configure' scripts should accept all of the "detail" options
|
and the variable settings, whether or not they make any difference to
|
and the variable settings, whether or not they make any difference to
|
the particular package at hand. In particular, they should accept any
|
the particular package at hand. In particular, they should accept any
|
option that starts with `--with-' or `--enable-'. This is so users
|
option that starts with `--with-' or `--enable-'. This is so users
|
will be able to configure an entire GNU source tree at once with a
|
will be able to configure an entire GNU source tree at once with a
|
single set of options.
|
single set of options.
|
|
|
You will note that the categories `--with-' and `--enable-' are
|
You will note that the categories `--with-' and `--enable-' are
|
narrow: they *do not* provide a place for any sort of option you might
|
narrow: they *do not* provide a place for any sort of option you might
|
think of. That is deliberate. We want to limit the possible
|
think of. That is deliberate. We want to limit the possible
|
configuration options in GNU software. We do not want GNU programs to
|
configuration options in GNU software. We do not want GNU programs to
|
have idiosyncratic configuration options.
|
have idiosyncratic configuration options.
|
|
|
Packages that perform part of the compilation process may support
|
Packages that perform part of the compilation process may support
|
cross-compilation. In such a case, the host and target machines for the
|
cross-compilation. In such a case, the host and target machines for the
|
program may be different.
|
program may be different.
|
|
|
The `configure' script should normally treat the specified type of
|
The `configure' script should normally treat the specified type of
|
system as both the host and the target, thus producing a program which
|
system as both the host and the target, thus producing a program which
|
works for the same type of machine that it runs on.
|
works for the same type of machine that it runs on.
|
|
|
To compile a program to run on a host type that differs from the
|
To compile a program to run on a host type that differs from the
|
build type, use the configure option `--host=HOSTTYPE', where HOSTTYPE
|
build type, use the configure option `--host=HOSTTYPE', where HOSTTYPE
|
uses the same syntax as BUILDTYPE. The host type normally defaults to
|
uses the same syntax as BUILDTYPE. The host type normally defaults to
|
the build type.
|
the build type.
|
|
|
To configure a cross-compiler, cross-assembler, or what have you, you
|
To configure a cross-compiler, cross-assembler, or what have you, you
|
should specify a target different from the host, using the configure
|
should specify a target different from the host, using the configure
|
option `--target=TARGETTYPE'. The syntax for TARGETTYPE is the same as
|
option `--target=TARGETTYPE'. The syntax for TARGETTYPE is the same as
|
for the host type. So the command would look like this:
|
for the host type. So the command would look like this:
|
|
|
./configure --host=HOSTTYPE --target=TARGETTYPE
|
./configure --host=HOSTTYPE --target=TARGETTYPE
|
|
|
The target type normally defaults to the host type. Programs for
|
The target type normally defaults to the host type. Programs for
|
which cross-operation is not meaningful need not accept the `--target'
|
which cross-operation is not meaningful need not accept the `--target'
|
option, because configuring an entire operating system for
|
option, because configuring an entire operating system for
|
cross-operation is not a meaningful operation.
|
cross-operation is not a meaningful operation.
|
|
|
Some programs have ways of configuring themselves automatically. If
|
Some programs have ways of configuring themselves automatically. If
|
your program is set up to do this, your `configure' script can simply
|
your program is set up to do this, your `configure' script can simply
|
ignore most of its arguments.
|
ignore most of its arguments.
|
|
|
|
|
File: standards.info, Node: Makefile Conventions, Next: Releases, Prev: Configuration, Up: Managing Releases
|
File: standards.info, Node: Makefile Conventions, Next: Releases, Prev: Configuration, Up: Managing Releases
|
|
|
7.2 Makefile Conventions
|
7.2 Makefile Conventions
|
========================
|
========================
|
|
|
This node describes conventions for writing the Makefiles for GNU
|
This node describes conventions for writing the Makefiles for GNU
|
programs. Using Automake will help you write a Makefile that follows
|
programs. Using Automake will help you write a Makefile that follows
|
these conventions.
|
these conventions.
|
|
|
* Menu:
|
* Menu:
|
|
|
* Makefile Basics:: General conventions for Makefiles.
|
* Makefile Basics:: General conventions for Makefiles.
|
* Utilities in Makefiles:: Utilities to be used in Makefiles.
|
* Utilities in Makefiles:: Utilities to be used in Makefiles.
|
* Command Variables:: Variables for specifying commands.
|
* Command Variables:: Variables for specifying commands.
|
* DESTDIR:: Supporting staged installs.
|
* DESTDIR:: Supporting staged installs.
|
* Directory Variables:: Variables for installation directories.
|
* Directory Variables:: Variables for installation directories.
|
* Standard Targets:: Standard targets for users.
|
* Standard Targets:: Standard targets for users.
|
* Install Command Categories:: Three categories of commands in the `install'
|
* Install Command Categories:: Three categories of commands in the `install'
|
rule: normal, pre-install and post-install.
|
rule: normal, pre-install and post-install.
|
|
|
|
|
File: standards.info, Node: Makefile Basics, Next: Utilities in Makefiles, Up: Makefile Conventions
|
File: standards.info, Node: Makefile Basics, Next: Utilities in Makefiles, Up: Makefile Conventions
|
|
|
7.2.1 General Conventions for Makefiles
|
7.2.1 General Conventions for Makefiles
|
---------------------------------------
|
---------------------------------------
|
|
|
Every Makefile should contain this line:
|
Every Makefile should contain this line:
|
|
|
SHELL = /bin/sh
|
SHELL = /bin/sh
|
|
|
to avoid trouble on systems where the `SHELL' variable might be
|
to avoid trouble on systems where the `SHELL' variable might be
|
inherited from the environment. (This is never a problem with GNU
|
inherited from the environment. (This is never a problem with GNU
|
`make'.)
|
`make'.)
|
|
|
Different `make' programs have incompatible suffix lists and
|
Different `make' programs have incompatible suffix lists and
|
implicit rules, and this sometimes creates confusion or misbehavior. So
|
implicit rules, and this sometimes creates confusion or misbehavior. So
|
it is a good idea to set the suffix list explicitly using only the
|
it is a good idea to set the suffix list explicitly using only the
|
suffixes you need in the particular Makefile, like this:
|
suffixes you need in the particular Makefile, like this:
|
|
|
.SUFFIXES:
|
.SUFFIXES:
|
.SUFFIXES: .c .o
|
.SUFFIXES: .c .o
|
|
|
The first line clears out the suffix list, the second introduces all
|
The first line clears out the suffix list, the second introduces all
|
suffixes which may be subject to implicit rules in this Makefile.
|
suffixes which may be subject to implicit rules in this Makefile.
|
|
|
Don't assume that `.' is in the path for command execution. When
|
Don't assume that `.' is in the path for command execution. When
|
you need to run programs that are a part of your package during the
|
you need to run programs that are a part of your package during the
|
make, please make sure that it uses `./' if the program is built as
|
make, please make sure that it uses `./' if the program is built as
|
part of the make or `$(srcdir)/' if the file is an unchanging part of
|
part of the make or `$(srcdir)/' if the file is an unchanging part of
|
the source code. Without one of these prefixes, the current search
|
the source code. Without one of these prefixes, the current search
|
path is used.
|
path is used.
|
|
|
The distinction between `./' (the "build directory") and
|
The distinction between `./' (the "build directory") and
|
`$(srcdir)/' (the "source directory") is important because users can
|
`$(srcdir)/' (the "source directory") is important because users can
|
build in a separate directory using the `--srcdir' option to
|
build in a separate directory using the `--srcdir' option to
|
`configure'. A rule of the form:
|
`configure'. A rule of the form:
|
|
|
foo.1 : foo.man sedscript
|
foo.1 : foo.man sedscript
|
sed -e sedscript foo.man > foo.1
|
sed -e sedscript foo.man > foo.1
|
|
|
will fail when the build directory is not the source directory, because
|
will fail when the build directory is not the source directory, because
|
`foo.man' and `sedscript' are in the source directory.
|
`foo.man' and `sedscript' are in the source directory.
|
|
|
When using GNU `make', relying on `VPATH' to find the source file
|
When using GNU `make', relying on `VPATH' to find the source file
|
will work in the case where there is a single dependency file, since
|
will work in the case where there is a single dependency file, since
|
the `make' automatic variable `$<' will represent the source file
|
the `make' automatic variable `$<' will represent the source file
|
wherever it is. (Many versions of `make' set `$<' only in implicit
|
wherever it is. (Many versions of `make' set `$<' only in implicit
|
rules.) A Makefile target like
|
rules.) A Makefile target like
|
|
|
foo.o : bar.c
|
foo.o : bar.c
|
$(CC) -I. -I$(srcdir) $(CFLAGS) -c bar.c -o foo.o
|
$(CC) -I. -I$(srcdir) $(CFLAGS) -c bar.c -o foo.o
|
|
|
should instead be written as
|
should instead be written as
|
|
|
foo.o : bar.c
|
foo.o : bar.c
|
$(CC) -I. -I$(srcdir) $(CFLAGS) -c $< -o $@
|
$(CC) -I. -I$(srcdir) $(CFLAGS) -c $< -o $@
|
|
|
in order to allow `VPATH' to work correctly. When the target has
|
in order to allow `VPATH' to work correctly. When the target has
|
multiple dependencies, using an explicit `$(srcdir)' is the easiest way
|
multiple dependencies, using an explicit `$(srcdir)' is the easiest way
|
to make the rule work well. For example, the target above for `foo.1'
|
to make the rule work well. For example, the target above for `foo.1'
|
is best written as:
|
is best written as:
|
|
|
foo.1 : foo.man sedscript
|
foo.1 : foo.man sedscript
|
sed -e $(srcdir)/sedscript $(srcdir)/foo.man > $@
|
sed -e $(srcdir)/sedscript $(srcdir)/foo.man > $@
|
|
|
GNU distributions usually contain some files which are not source
|
GNU distributions usually contain some files which are not source
|
files--for example, Info files, and the output from Autoconf, Automake,
|
files--for example, Info files, and the output from Autoconf, Automake,
|
Bison or Flex. Since these files normally appear in the source
|
Bison or Flex. Since these files normally appear in the source
|
directory, they should always appear in the source directory, not in the
|
directory, they should always appear in the source directory, not in the
|
build directory. So Makefile rules to update them should put the
|
build directory. So Makefile rules to update them should put the
|
updated files in the source directory.
|
updated files in the source directory.
|
|
|
However, if a file does not appear in the distribution, then the
|
However, if a file does not appear in the distribution, then the
|
Makefile should not put it in the source directory, because building a
|
Makefile should not put it in the source directory, because building a
|
program in ordinary circumstances should not modify the source directory
|
program in ordinary circumstances should not modify the source directory
|
in any way.
|
in any way.
|
|
|
Try to make the build and installation targets, at least (and all
|
Try to make the build and installation targets, at least (and all
|
their subtargets) work correctly with a parallel `make'.
|
their subtargets) work correctly with a parallel `make'.
|
|
|
|
|
File: standards.info, Node: Utilities in Makefiles, Next: Command Variables, Prev: Makefile Basics, Up: Makefile Conventions
|
File: standards.info, Node: Utilities in Makefiles, Next: Command Variables, Prev: Makefile Basics, Up: Makefile Conventions
|
|
|
7.2.2 Utilities in Makefiles
|
7.2.2 Utilities in Makefiles
|
----------------------------
|
----------------------------
|
|
|
Write the Makefile commands (and any shell scripts, such as
|
Write the Makefile commands (and any shell scripts, such as
|
`configure') to run in `sh', not in `csh'. Don't use any special
|
`configure') to run in `sh', not in `csh'. Don't use any special
|
features of `ksh' or `bash'.
|
features of `ksh' or `bash'.
|
|
|
The `configure' script and the Makefile rules for building and
|
The `configure' script and the Makefile rules for building and
|
installation should not use any utilities directly except these:
|
installation should not use any utilities directly except these:
|
|
|
cat cmp cp diff echo egrep expr false grep install-info
|
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
|
ln ls mkdir mv pwd rm rmdir sed sleep sort tar test touch true
|
|
|
The compression program `gzip' can be used in the `dist' rule.
|
The compression program `gzip' can be used in the `dist' rule.
|
|
|
Stick to the generally supported options for these programs. For
|
Stick to the generally supported options for these programs. For
|
example, don't use `mkdir -p', convenient as it may be, because most
|
example, don't use `mkdir -p', convenient as it may be, because most
|
systems don't support it.
|
systems don't support it.
|
|
|
It is a good idea to avoid creating symbolic links in makefiles,
|
It is a good idea to avoid creating symbolic links in makefiles,
|
since a few systems don't support them.
|
since a few systems don't support them.
|
|
|
The Makefile rules for building and installation can also use
|
The Makefile rules for building and installation can also use
|
compilers and related programs, but should do so via `make' variables
|
compilers and related programs, but should do so via `make' variables
|
so that the user can substitute alternatives. Here are some of the
|
so that the user can substitute alternatives. Here are some of the
|
programs we mean:
|
programs we mean:
|
|
|
ar bison cc flex install ld ldconfig lex
|
ar bison cc flex install ld ldconfig lex
|
make makeinfo ranlib texi2dvi yacc
|
make makeinfo ranlib texi2dvi yacc
|
|
|
Use the following `make' variables to run those programs:
|
Use the following `make' variables to run those programs:
|
|
|
$(AR) $(BISON) $(CC) $(FLEX) $(INSTALL) $(LD) $(LDCONFIG) $(LEX)
|
$(AR) $(BISON) $(CC) $(FLEX) $(INSTALL) $(LD) $(LDCONFIG) $(LEX)
|
$(MAKE) $(MAKEINFO) $(RANLIB) $(TEXI2DVI) $(YACC)
|
$(MAKE) $(MAKEINFO) $(RANLIB) $(TEXI2DVI) $(YACC)
|
|
|
When you use `ranlib' or `ldconfig', you should make sure nothing
|
When you use `ranlib' or `ldconfig', you should make sure nothing
|
bad happens if the system does not have the program in question.
|
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
|
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
|
the command to tell the user that failure of this command does not mean
|
a problem. (The Autoconf `AC_PROG_RANLIB' macro can help with this.)
|
a problem. (The Autoconf `AC_PROG_RANLIB' macro can help with this.)
|
|
|
If you use symbolic links, you should implement a fallback for
|
If you use symbolic links, you should implement a fallback for
|
systems that don't have symbolic links.
|
systems that don't have symbolic links.
|
|
|
Additional utilities that can be used via Make variables are:
|
Additional utilities that can be used via Make variables are:
|
|
|
chgrp chmod chown mknod
|
chgrp chmod chown mknod
|
|
|
It is ok to use other utilities in Makefile portions (or scripts)
|
It is ok to use other utilities in Makefile portions (or scripts)
|
intended only for particular systems where you know those utilities
|
intended only for particular systems where you know those utilities
|
exist.
|
exist.
|
|
|
|
|
File: standards.info, Node: Command Variables, Next: DESTDIR, Prev: Utilities in Makefiles, Up: Makefile Conventions
|
File: standards.info, Node: Command Variables, Next: DESTDIR, Prev: Utilities in Makefiles, Up: Makefile Conventions
|
|
|
7.2.3 Variables for Specifying Commands
|
7.2.3 Variables for Specifying Commands
|
---------------------------------------
|
---------------------------------------
|
|
|
Makefiles should provide variables for overriding certain commands,
|
Makefiles should provide variables for overriding certain commands,
|
options, and so on.
|
options, and so on.
|
|
|
In particular, you should run most utility programs via variables.
|
In particular, you should run most utility programs via variables.
|
Thus, if you use Bison, have a variable named `BISON' whose default
|
Thus, if you use Bison, have a variable named `BISON' whose default
|
value is set with `BISON = bison', and refer to it with `$(BISON)'
|
value is set with `BISON = bison', and refer to it with `$(BISON)'
|
whenever you need to use Bison.
|
whenever you need to use Bison.
|
|
|
File management utilities such as `ln', `rm', `mv', and so on, need
|
File management utilities such as `ln', `rm', `mv', and so on, need
|
not be referred to through variables in this way, since users don't
|
not be referred to through variables in this way, since users don't
|
need to replace them with other programs.
|
need to replace them with other programs.
|
|
|
Each program-name variable should come with an options variable that
|
Each program-name variable should come with an options variable that
|
is used to supply options to the program. Append `FLAGS' to the
|
is used to supply options to the program. Append `FLAGS' to the
|
program-name variable name to get the options variable name--for
|
program-name variable name to get the options variable name--for
|
example, `BISONFLAGS'. (The names `CFLAGS' for the C compiler,
|
example, `BISONFLAGS'. (The names `CFLAGS' for the C compiler,
|
`YFLAGS' for yacc, and `LFLAGS' for lex, are exceptions to this rule,
|
`YFLAGS' for yacc, and `LFLAGS' for lex, are exceptions to this rule,
|
but we keep them because they are standard.) Use `CPPFLAGS' in any
|
but we keep them because they are standard.) Use `CPPFLAGS' in any
|
compilation command that runs the preprocessor, and use `LDFLAGS' in
|
compilation command that runs the preprocessor, and use `LDFLAGS' in
|
any compilation command that does linking as well as in any direct use
|
any compilation command that does linking as well as in any direct use
|
of `ld'.
|
of `ld'.
|
|
|
If there are C compiler options that _must_ be used for proper
|
If there are C compiler options that _must_ be used for proper
|
compilation of certain files, do not include them in `CFLAGS'. Users
|
compilation of certain files, do not include them in `CFLAGS'. Users
|
expect to be able to specify `CFLAGS' freely themselves. Instead,
|
expect to be able to specify `CFLAGS' freely themselves. Instead,
|
arrange to pass the necessary options to the C compiler independently
|
arrange to pass the necessary options to the C compiler independently
|
of `CFLAGS', by writing them explicitly in the compilation commands or
|
of `CFLAGS', by writing them explicitly in the compilation commands or
|
by defining an implicit rule, like this:
|
by defining an implicit rule, like this:
|
|
|
CFLAGS = -g
|
CFLAGS = -g
|
ALL_CFLAGS = -I. $(CFLAGS)
|
ALL_CFLAGS = -I. $(CFLAGS)
|
.c.o:
|
.c.o:
|
$(CC) -c $(CPPFLAGS) $(ALL_CFLAGS) $<
|
$(CC) -c $(CPPFLAGS) $(ALL_CFLAGS) $<
|
|
|
Do include the `-g' option in `CFLAGS', because that is not
|
Do include the `-g' option in `CFLAGS', because that is not
|
_required_ for proper compilation. You can consider it a default that
|
_required_ for proper compilation. You can consider it a default that
|
is only recommended. If the package is set up so that it is compiled
|
is only recommended. If the package is set up so that it is compiled
|
with GCC by default, then you might as well include `-O' in the default
|
with GCC by default, then you might as well include `-O' in the default
|
value of `CFLAGS' as well.
|
value of `CFLAGS' as well.
|
|
|
Put `CFLAGS' last in the compilation command, after other variables
|
Put `CFLAGS' last in the compilation command, after other variables
|
containing compiler options, so the user can use `CFLAGS' to override
|
containing compiler options, so the user can use `CFLAGS' to override
|
the others.
|
the others.
|
|
|
`CFLAGS' should be used in every invocation of the C compiler, both
|
`CFLAGS' should be used in every invocation of the C compiler, both
|
those which do compilation and those which do linking.
|
those which do compilation and those which do linking.
|
|
|
Every Makefile should define the variable `INSTALL', which is the
|
Every Makefile should define the variable `INSTALL', which is the
|
basic command for installing a file into the system.
|
basic command for installing a file into the system.
|
|
|
Every Makefile should also define the variables `INSTALL_PROGRAM'
|
Every Makefile should also define the variables `INSTALL_PROGRAM'
|
and `INSTALL_DATA'. (The default for `INSTALL_PROGRAM' should be
|
and `INSTALL_DATA'. (The default for `INSTALL_PROGRAM' should be
|
`$(INSTALL)'; the default for `INSTALL_DATA' should be `${INSTALL} -m
|
`$(INSTALL)'; the default for `INSTALL_DATA' should be `${INSTALL} -m
|
644'.) Then it should use those variables as the commands for actual
|
644'.) Then it should use those variables as the commands for actual
|
installation, for executables and non-executables respectively.
|
installation, for executables and non-executables respectively.
|
Minimal use of these variables is as follows:
|
Minimal use of these variables is as follows:
|
|
|
$(INSTALL_PROGRAM) foo $(bindir)/foo
|
$(INSTALL_PROGRAM) foo $(bindir)/foo
|
$(INSTALL_DATA) libfoo.a $(libdir)/libfoo.a
|
$(INSTALL_DATA) libfoo.a $(libdir)/libfoo.a
|
|
|
However, it is preferable to support a `DESTDIR' prefix on the
|
However, it is preferable to support a `DESTDIR' prefix on the
|
target files, as explained in the next section.
|
target files, as explained in the next section.
|
|
|
Always use a file name, not a directory name, as the second argument of
|
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
|
the installation commands. Use a separate command for each file to be
|
installed.
|
installed.
|
|
|
|
|
File: standards.info, Node: DESTDIR, Next: Directory Variables, Prev: Command Variables, Up: Makefile Conventions
|
File: standards.info, Node: DESTDIR, Next: Directory Variables, Prev: Command Variables, Up: Makefile Conventions
|
|
|
7.2.4 `DESTDIR': support for staged installs
|
7.2.4 `DESTDIR': support for staged installs
|
--------------------------------------------
|
--------------------------------------------
|
|
|
`DESTDIR' is a variable prepended to each installed target file, like
|
`DESTDIR' is a variable prepended to each installed target file, like
|
this:
|
this:
|
|
|
$(INSTALL_PROGRAM) foo $(DESTDIR)$(bindir)/foo
|
$(INSTALL_PROGRAM) foo $(DESTDIR)$(bindir)/foo
|
$(INSTALL_DATA) libfoo.a $(DESTDIR)$(libdir)/libfoo.a
|
$(INSTALL_DATA) libfoo.a $(DESTDIR)$(libdir)/libfoo.a
|
|
|
The `DESTDIR' variable is specified by the user on the `make'
|
The `DESTDIR' variable is specified by the user on the `make'
|
command line. For example:
|
command line. For example:
|
|
|
make DESTDIR=/tmp/stage install
|
make DESTDIR=/tmp/stage install
|
|
|
`DESTDIR' should be supported only in the `install*' and `uninstall*'
|
`DESTDIR' should be supported only in the `install*' and `uninstall*'
|
targets, as those are the only targets where it is useful.
|
targets, as those are the only targets where it is useful.
|
|
|
If your installation step would normally install
|
If your installation step would normally install
|
`/usr/local/bin/foo' and `/usr/local/lib/libfoo.a', then an
|
`/usr/local/bin/foo' and `/usr/local/lib/libfoo.a', then an
|
installation invoked as in the example above would install
|
installation invoked as in the example above would install
|
`/tmp/stage/usr/local/bin/foo' and `/tmp/stage/usr/local/lib/libfoo.a'
|
`/tmp/stage/usr/local/bin/foo' and `/tmp/stage/usr/local/lib/libfoo.a'
|
instead.
|
instead.
|
|
|
Prepending the variable `DESTDIR' to each target in this way
|
Prepending the variable `DESTDIR' to each target in this way
|
provides for "staged installs", where the installed files are not
|
provides for "staged installs", where the installed files are not
|
placed directly into their expected location but are instead copied
|
placed directly into their expected location but are instead copied
|
into a temporary location (`DESTDIR'). However, installed files
|
into a temporary location (`DESTDIR'). However, installed files
|
maintain their relative directory structure and any embedded file names
|
maintain their relative directory structure and any embedded file names
|
will not be modified.
|
will not be modified.
|
|
|
You should not set the value of `DESTDIR' in your `Makefile' at all;
|
You should not set the value of `DESTDIR' in your `Makefile' at all;
|
then the files are installed into their expected locations by default.
|
then the files are installed into their expected locations by default.
|
Also, specifying `DESTDIR' should not change the operation of the
|
Also, specifying `DESTDIR' should not change the operation of the
|
software in any way, so its value should not be included in any file
|
software in any way, so its value should not be included in any file
|
contents.
|
contents.
|
|
|
`DESTDIR' support is commonly used in package creation. It is also
|
`DESTDIR' support is commonly used in package creation. It is also
|
helpful to users who want to understand what a given package will
|
helpful to users who want to understand what a given package will
|
install where, and to allow users who don't normally have permissions
|
install where, and to allow users who don't normally have permissions
|
to install into protected areas to build and install before gaining
|
to install into protected areas to build and install before gaining
|
those permissions. Finally, it can be useful with tools such as
|
those permissions. Finally, it can be useful with tools such as
|
`stow', where code is installed in one place but made to appear to be
|
`stow', where code is installed in one place but made to appear to be
|
installed somewhere else using symbolic links or special mount
|
installed somewhere else using symbolic links or special mount
|
operations. So, we strongly recommend GNU packages support `DESTDIR',
|
operations. So, we strongly recommend GNU packages support `DESTDIR',
|
though it is not an absolute requirement.
|
though it is not an absolute requirement.
|
|
|
|
|
File: standards.info, Node: Directory Variables, Next: Standard Targets, Prev: DESTDIR, Up: Makefile Conventions
|
File: standards.info, Node: Directory Variables, Next: Standard Targets, Prev: DESTDIR, Up: Makefile Conventions
|
|
|
7.2.5 Variables for Installation Directories
|
7.2.5 Variables for Installation Directories
|
--------------------------------------------
|
--------------------------------------------
|
|
|
Installation directories should always be named by variables, so it is
|
Installation directories should always be named by variables, so it is
|
easy to install in a nonstandard place. The standard names for these
|
easy to install in a nonstandard place. The standard names for these
|
variables and the values they should have in GNU packages are described
|
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
|
below. They are based on a standard file system layout; variants of it
|
are used in GNU/Linux and other modern operating systems.
|
are used in GNU/Linux and other modern operating systems.
|
|
|
Installers are expected to override these values when calling `make'
|
Installers are expected to override these values when calling `make'
|
(e.g., `make prefix=/usr install' or `configure' (e.g., `configure
|
(e.g., `make prefix=/usr install' or `configure' (e.g., `configure
|
--prefix=/usr'). GNU packages should not try to guess which value
|
--prefix=/usr'). GNU packages should not try to guess which value
|
should be appropriate for these variables on the system they are being
|
should be appropriate for these variables on the system they are being
|
installed onto: use the default settings specified here so that all GNU
|
installed onto: use the default settings specified here so that all GNU
|
packages behave identically, allowing the installer to achieve any
|
packages behave identically, allowing the installer to achieve any
|
desired layout.
|
desired layout.
|
|
|
These first two variables set the root for the installation. All the
|
These first two variables set the root for the installation. All the
|
other installation directories should be subdirectories of one of these
|
other installation directories should be subdirectories of one of these
|
two, and nothing should be directly installed into these two
|
two, and nothing should be directly installed into these two
|
directories.
|
directories.
|
|
|
`prefix'
|
`prefix'
|
A prefix used in constructing the default values of the variables
|
A prefix used in constructing the default values of the variables
|
listed below. The default value of `prefix' should be
|
listed below. The default value of `prefix' should be
|
`/usr/local'. When building the complete GNU system, the prefix
|
`/usr/local'. When building the complete GNU system, the prefix
|
will be empty and `/usr' will be a symbolic link to `/'. (If you
|
will be empty and `/usr' will be a symbolic link to `/'. (If you
|
are using Autoconf, write it as `@prefix@'.)
|
are using Autoconf, write it as `@prefix@'.)
|
|
|
Running `make install' with a different value of `prefix' from the
|
Running `make install' with a different value of `prefix' from the
|
one used to build the program should _not_ recompile the program.
|
one used to build the program should _not_ recompile the program.
|
|
|
`exec_prefix'
|
`exec_prefix'
|
A prefix used in constructing the default values of some of the
|
A prefix used in constructing the default values of some of the
|
variables listed below. The default value of `exec_prefix' should
|
variables listed below. The default value of `exec_prefix' should
|
be `$(prefix)'. (If you are using Autoconf, write it as
|
be `$(prefix)'. (If you are using Autoconf, write it as
|
`@exec_prefix@'.)
|
`@exec_prefix@'.)
|
|
|
Generally, `$(exec_prefix)' is used for directories that contain
|
Generally, `$(exec_prefix)' is used for directories that contain
|
machine-specific files (such as executables and subroutine
|
machine-specific files (such as executables and subroutine
|
libraries), while `$(prefix)' is used directly for other
|
libraries), while `$(prefix)' is used directly for other
|
directories.
|
directories.
|
|
|
Running `make install' with a different value of `exec_prefix'
|
Running `make install' with a different value of `exec_prefix'
|
from the one used to build the program should _not_ recompile the
|
from the one used to build the program should _not_ recompile the
|
program.
|
program.
|
|
|
Executable programs are installed in one of the following
|
Executable programs are installed in one of the following
|
directories.
|
directories.
|
|
|
`bindir'
|
`bindir'
|
The directory for installing executable programs that users can
|
The directory for installing executable programs that users can
|
run. This should normally be `/usr/local/bin', but write it as
|
run. This should normally be `/usr/local/bin', but write it as
|
`$(exec_prefix)/bin'. (If you are using Autoconf, write it as
|
`$(exec_prefix)/bin'. (If you are using Autoconf, write it as
|
`@bindir@'.)
|
`@bindir@'.)
|
|
|
`sbindir'
|
`sbindir'
|
The directory for installing executable programs that can be run
|
The directory for installing executable programs that can be run
|
from the shell, but are only generally useful to system
|
from the shell, but are only generally useful to system
|
administrators. This should normally be `/usr/local/sbin', but
|
administrators. This should normally be `/usr/local/sbin', but
|
write it as `$(exec_prefix)/sbin'. (If you are using Autoconf,
|
write it as `$(exec_prefix)/sbin'. (If you are using Autoconf,
|
write it as `@sbindir@'.)
|
write it as `@sbindir@'.)
|
|
|
`libexecdir'
|
`libexecdir'
|
The directory for installing executable programs to be run by other
|
The directory for installing executable programs to be run by other
|
programs rather than by users. This directory should normally be
|
programs rather than by users. This directory should normally be
|
`/usr/local/libexec', but write it as `$(exec_prefix)/libexec'.
|
`/usr/local/libexec', but write it as `$(exec_prefix)/libexec'.
|
(If you are using Autoconf, write it as `@libexecdir@'.)
|
(If you are using Autoconf, write it as `@libexecdir@'.)
|
|
|
The definition of `libexecdir' is the same for all packages, so
|
The definition of `libexecdir' is the same for all packages, so
|
you should install your data in a subdirectory thereof. Most
|
you should install your data in a subdirectory thereof. Most
|
packages install their data under `$(libexecdir)/PACKAGE-NAME/',
|
packages install their data under `$(libexecdir)/PACKAGE-NAME/',
|
possibly within additional subdirectories thereof, such as
|
possibly within additional subdirectories thereof, such as
|
`$(libexecdir)/PACKAGE-NAME/MACHINE/VERSION'.
|
`$(libexecdir)/PACKAGE-NAME/MACHINE/VERSION'.
|
|
|
Data files used by the program during its execution are divided into
|
Data files used by the program during its execution are divided into
|
categories in two ways.
|
categories in two ways.
|
|
|
* Some files are normally modified by programs; others are never
|
* Some files are normally modified by programs; others are never
|
normally modified (though users may edit some of these).
|
normally modified (though users may edit some of these).
|
|
|
* Some files are architecture-independent and can be shared by all
|
* Some files are architecture-independent and can be shared by all
|
machines at a site; some are architecture-dependent and can be
|
machines at a site; some are architecture-dependent and can be
|
shared only by machines of the same kind and operating system;
|
shared only by machines of the same kind and operating system;
|
others may never be shared between two machines.
|
others may never be shared between two machines.
|
|
|
This makes for six different possibilities. However, we want to
|
This makes for six different possibilities. However, we want to
|
discourage the use of architecture-dependent files, aside from object
|
discourage the use of architecture-dependent files, aside from object
|
files and libraries. It is much cleaner to make other data files
|
files and libraries. It is much cleaner to make other data files
|
architecture-independent, and it is generally not hard.
|
architecture-independent, and it is generally not hard.
|
|
|
Here are the variables Makefiles should use to specify directories
|
Here are the variables Makefiles should use to specify directories
|
to put these various kinds of files in:
|
to put these various kinds of files in:
|
|
|
`datarootdir'
|
`datarootdir'
|
The root of the directory tree for read-only
|
The root of the directory tree for read-only
|
architecture-independent data files. This should normally be
|
architecture-independent data files. This should normally be
|
`/usr/local/share', but write it as `$(prefix)/share'. (If you
|
`/usr/local/share', but write it as `$(prefix)/share'. (If you
|
are using Autoconf, write it as `@datarootdir@'.) `datadir''s
|
are using Autoconf, write it as `@datarootdir@'.) `datadir''s
|
default value is based on this variable; so are `infodir',
|
default value is based on this variable; so are `infodir',
|
`mandir', and others.
|
`mandir', and others.
|
|
|
`datadir'
|
`datadir'
|
The directory for installing idiosyncratic read-only
|
The directory for installing idiosyncratic read-only
|
architecture-independent data files for this program. This is
|
architecture-independent data files for this program. This is
|
usually the same place as `datarootdir', but we use the two
|
usually the same place as `datarootdir', but we use the two
|
separate variables so that you can move these program-specific
|
separate variables so that you can move these program-specific
|
files without altering the location for Info files, man pages, etc.
|
files without altering the location for Info files, man pages, etc.
|
|
|
This should normally be `/usr/local/share', but write it as
|
This should normally be `/usr/local/share', but write it as
|
`$(datarootdir)'. (If you are using Autoconf, write it as
|
`$(datarootdir)'. (If you are using Autoconf, write it as
|
`@datadir@'.)
|
`@datadir@'.)
|
|
|
The definition of `datadir' is the same for all packages, so you
|
The definition of `datadir' is the same for all packages, so you
|
should install your data in a subdirectory thereof. Most packages
|
should install your data in a subdirectory thereof. Most packages
|
install their data under `$(datadir)/PACKAGE-NAME/'.
|
install their data under `$(datadir)/PACKAGE-NAME/'.
|
|
|
`sysconfdir'
|
`sysconfdir'
|
The directory for installing read-only data files that pertain to a
|
The directory for installing read-only data files that pertain to a
|
single machine-that is to say, files for configuring a host.
|
single machine-that is to say, files for configuring a host.
|
Mailer and network configuration files, `/etc/passwd', and so
|
Mailer and network configuration files, `/etc/passwd', and so
|
forth belong here. All the files in this directory should be
|
forth belong here. All the files in this directory should be
|
ordinary ASCII text files. This directory should normally be
|
ordinary ASCII text files. This directory should normally be
|
`/usr/local/etc', but write it as `$(prefix)/etc'. (If you are
|
`/usr/local/etc', but write it as `$(prefix)/etc'. (If you are
|
using Autoconf, write it as `@sysconfdir@'.)
|
using Autoconf, write it as `@sysconfdir@'.)
|
|
|
Do not install executables here in this directory (they probably
|
Do not install executables here in this directory (they probably
|
belong in `$(libexecdir)' or `$(sbindir)'). Also do not install
|
belong in `$(libexecdir)' or `$(sbindir)'). Also do not install
|
files that are modified in the normal course of their use (programs
|
files that are modified in the normal course of their use (programs
|
whose purpose is to change the configuration of the system
|
whose purpose is to change the configuration of the system
|
excluded). Those probably belong in `$(localstatedir)'.
|
excluded). Those probably belong in `$(localstatedir)'.
|
|
|
`sharedstatedir'
|
`sharedstatedir'
|
The directory for installing architecture-independent data files
|
The directory for installing architecture-independent data files
|
which the programs modify while they run. This should normally be
|
which the programs modify while they run. This should normally be
|
`/usr/local/com', but write it as `$(prefix)/com'. (If you are
|
`/usr/local/com', but write it as `$(prefix)/com'. (If you are
|
using Autoconf, write it as `@sharedstatedir@'.)
|
using Autoconf, write it as `@sharedstatedir@'.)
|
|
|
`localstatedir'
|
`localstatedir'
|
The directory for installing data files which the programs modify
|
The directory for installing data files which the programs modify
|
while they run, and that pertain to one specific machine. Users
|
while they run, and that pertain to one specific machine. Users
|
should never need to modify files in this directory to configure
|
should never need to modify files in this directory to configure
|
the package's operation; put such configuration information in
|
the package's operation; put such configuration information in
|
separate files that go in `$(datadir)' or `$(sysconfdir)'.
|
separate files that go in `$(datadir)' or `$(sysconfdir)'.
|
`$(localstatedir)' should normally be `/usr/local/var', but write
|
`$(localstatedir)' should normally be `/usr/local/var', but write
|
it as `$(prefix)/var'. (If you are using Autoconf, write it as
|
it as `$(prefix)/var'. (If you are using Autoconf, write it as
|
`@localstatedir@'.)
|
`@localstatedir@'.)
|
|
|
These variables specify the directory for installing certain specific
|
These variables specify the directory for installing certain specific
|
types of files, if your program has them. Every GNU package should
|
types of files, if your program has them. Every GNU package should
|
have Info files, so every program needs `infodir', but not all need
|
have Info files, so every program needs `infodir', but not all need
|
`libdir' or `lispdir'.
|
`libdir' or `lispdir'.
|
|
|
`includedir'
|
`includedir'
|
The directory for installing header files to be included by user
|
The directory for installing header files to be included by user
|
programs with the C `#include' preprocessor directive. This
|
programs with the C `#include' preprocessor directive. This
|
should normally be `/usr/local/include', but write it as
|
should normally be `/usr/local/include', but write it as
|
`$(prefix)/include'. (If you are using Autoconf, write it as
|
`$(prefix)/include'. (If you are using Autoconf, write it as
|
`@includedir@'.)
|
`@includedir@'.)
|
|
|
Most compilers other than GCC do not look for header files in
|
Most compilers other than GCC do not look for header files in
|
directory `/usr/local/include'. So installing the header files
|
directory `/usr/local/include'. So installing the header files
|
this way is only useful with GCC. Sometimes this is not a problem
|
this way is only useful with GCC. Sometimes this is not a problem
|
because some libraries are only really intended to work with GCC.
|
because some libraries are only really intended to work with GCC.
|
But some libraries are intended to work with other compilers.
|
But some libraries are intended to work with other compilers.
|
They should install their header files in two places, one
|
They should install their header files in two places, one
|
specified by `includedir' and one specified by `oldincludedir'.
|
specified by `includedir' and one specified by `oldincludedir'.
|
|
|
`oldincludedir'
|
`oldincludedir'
|
The directory for installing `#include' header files for use with
|
The directory for installing `#include' header files for use with
|
compilers other than GCC. This should normally be `/usr/include'.
|
compilers other than GCC. This should normally be `/usr/include'.
|
(If you are using Autoconf, you can write it as `@oldincludedir@'.)
|
(If you are using Autoconf, you can write it as `@oldincludedir@'.)
|
|
|
The Makefile commands should check whether the value of
|
The Makefile commands should check whether the value of
|
`oldincludedir' is empty. If it is, they should not try to use
|
`oldincludedir' is empty. If it is, they should not try to use
|
it; they should cancel the second installation of the header files.
|
it; they should cancel the second installation of the header files.
|
|
|
A package should not replace an existing header in this directory
|
A package should not replace an existing header in this directory
|
unless the header came from the same package. Thus, if your Foo
|
unless the header came from the same package. Thus, if your Foo
|
package provides a header file `foo.h', then it should install the
|
package provides a header file `foo.h', then it should install the
|
header file in the `oldincludedir' directory if either (1) there
|
header file in the `oldincludedir' directory if either (1) there
|
is no `foo.h' there or (2) the `foo.h' that exists came from the
|
is no `foo.h' there or (2) the `foo.h' that exists came from the
|
Foo package.
|
Foo package.
|
|
|
To tell whether `foo.h' came from the Foo package, put a magic
|
To tell whether `foo.h' came from the Foo package, put a magic
|
string in the file--part of a comment--and `grep' for that string.
|
string in the file--part of a comment--and `grep' for that string.
|
|
|
`docdir'
|
`docdir'
|
The directory for installing documentation files (other than Info)
|
The directory for installing documentation files (other than Info)
|
for this package. By default, it should be
|
for this package. By default, it should be
|
`/usr/local/share/doc/YOURPKG', but it should be written as
|
`/usr/local/share/doc/YOURPKG', but it should be written as
|
`$(datarootdir)/doc/YOURPKG'. (If you are using Autoconf, write
|
`$(datarootdir)/doc/YOURPKG'. (If you are using Autoconf, write
|
it as `@docdir@'.) The YOURPKG subdirectory, which may include a
|
it as `@docdir@'.) The YOURPKG subdirectory, which may include a
|
version number, prevents collisions among files with common names,
|
version number, prevents collisions among files with common names,
|
such as `README'.
|
such as `README'.
|
|
|
`infodir'
|
`infodir'
|
The directory for installing the Info files for this package. By
|
The directory for installing the Info files for this package. By
|
default, it should be `/usr/local/share/info', but it should be
|
default, it should be `/usr/local/share/info', but it should be
|
written as `$(datarootdir)/info'. (If you are using Autoconf,
|
written as `$(datarootdir)/info'. (If you are using Autoconf,
|
write it as `@infodir@'.) `infodir' is separate from `docdir' for
|
write it as `@infodir@'.) `infodir' is separate from `docdir' for
|
compatibility with existing practice.
|
compatibility with existing practice.
|
|
|
`htmldir'
|
`htmldir'
|
`dvidir'
|
`dvidir'
|
`pdfdir'
|
`pdfdir'
|
`psdir'
|
`psdir'
|
Directories for installing documentation files in the particular
|
Directories for installing documentation files in the particular
|
format. They should all be set to `$(docdir)' by default. (If
|
format. They should all be set to `$(docdir)' by default. (If
|
you are using Autoconf, write them as `@htmldir@', `@dvidir@',
|
you are using Autoconf, write them as `@htmldir@', `@dvidir@',
|
etc.) Packages which supply several translations of their
|
etc.) Packages which supply several translations of their
|
documentation should install them in `$(htmldir)/'LL,
|
documentation should install them in `$(htmldir)/'LL,
|
`$(pdfdir)/'LL, etc. where LL is a locale abbreviation such as
|
`$(pdfdir)/'LL, etc. where LL is a locale abbreviation such as
|
`en' or `pt_BR'.
|
`en' or `pt_BR'.
|
|
|
`libdir'
|
`libdir'
|
The directory for object files and libraries of object code. Do
|
The directory for object files and libraries of object code. Do
|
not install executables here, they probably ought to go in
|
not install executables here, they probably ought to go in
|
`$(libexecdir)' instead. The value of `libdir' should normally be
|
`$(libexecdir)' instead. The value of `libdir' should normally be
|
`/usr/local/lib', but write it as `$(exec_prefix)/lib'. (If you
|
`/usr/local/lib', but write it as `$(exec_prefix)/lib'. (If you
|
are using Autoconf, write it as `@libdir@'.)
|
are using Autoconf, write it as `@libdir@'.)
|
|
|
`lispdir'
|
`lispdir'
|
The directory for installing any Emacs Lisp files in this package.
|
The directory for installing any Emacs Lisp files in this package.
|
By default, it should be `/usr/local/share/emacs/site-lisp', but
|
By default, it should be `/usr/local/share/emacs/site-lisp', but
|
it should be written as `$(datarootdir)/emacs/site-lisp'.
|
it should be written as `$(datarootdir)/emacs/site-lisp'.
|
|
|
If you are using Autoconf, write the default as `@lispdir@'. In
|
If you are using Autoconf, write the default as `@lispdir@'. In
|
order to make `@lispdir@' work, you need the following lines in
|
order to make `@lispdir@' work, you need the following lines in
|
your `configure.in' file:
|
your `configure.in' file:
|
|
|
lispdir='${datarootdir}/emacs/site-lisp'
|
lispdir='${datarootdir}/emacs/site-lisp'
|
AC_SUBST(lispdir)
|
AC_SUBST(lispdir)
|
|
|
`localedir'
|
`localedir'
|
The directory for installing locale-specific message catalogs for
|
The directory for installing locale-specific message catalogs for
|
this package. By default, it should be `/usr/local/share/locale',
|
this package. By default, it should be `/usr/local/share/locale',
|
but it should be written as `$(datarootdir)/locale'. (If you are
|
but it should be written as `$(datarootdir)/locale'. (If you are
|
using Autoconf, write it as `@localedir@'.) This directory
|
using Autoconf, write it as `@localedir@'.) This directory
|
usually has a subdirectory per locale.
|
usually has a subdirectory per locale.
|
|
|
Unix-style man pages are installed in one of the following:
|
Unix-style man pages are installed in one of the following:
|
|
|
`mandir'
|
`mandir'
|
The top-level directory for installing the man pages (if any) for
|
The top-level directory for installing the man pages (if any) for
|
this package. It will normally be `/usr/local/share/man', but you
|
this package. It will normally be `/usr/local/share/man', but you
|
should write it as `$(datarootdir)/man'. (If you are using
|
should write it as `$(datarootdir)/man'. (If you are using
|
Autoconf, write it as `@mandir@'.)
|
Autoconf, write it as `@mandir@'.)
|
|
|
`man1dir'
|
`man1dir'
|
The directory for installing section 1 man pages. Write it as
|
The directory for installing section 1 man pages. Write it as
|
`$(mandir)/man1'.
|
`$(mandir)/man1'.
|
|
|
`man2dir'
|
`man2dir'
|
The directory for installing section 2 man pages. Write it as
|
The directory for installing section 2 man pages. Write it as
|
`$(mandir)/man2'
|
`$(mandir)/man2'
|
|
|
`...'
|
`...'
|
*Don't make the primary documentation for any GNU software be a
|
*Don't make the primary documentation for any GNU software be a
|
man page. Write a manual in Texinfo instead. Man pages are just
|
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
|
for the sake of people running GNU software on Unix, which is a
|
secondary application only.*
|
secondary application only.*
|
|
|
`manext'
|
`manext'
|
The file name extension for the installed man page. This should
|
The file name extension for the installed man page. This should
|
contain a period followed by the appropriate digit; it should
|
contain a period followed by the appropriate digit; it should
|
normally be `.1'.
|
normally be `.1'.
|
|
|
`man1ext'
|
`man1ext'
|
The file name extension for installed section 1 man pages.
|
The file name extension for installed section 1 man pages.
|
|
|
`man2ext'
|
`man2ext'
|
The file name extension for installed section 2 man pages.
|
The file name extension for installed section 2 man pages.
|
|
|
`...'
|
`...'
|
Use these names instead of `manext' if the package needs to
|
Use these names instead of `manext' if the package needs to
|
install man pages in more than one section of the manual.
|
install man pages in more than one section of the manual.
|
|
|
And finally, you should set the following variable:
|
And finally, you should set the following variable:
|
|
|
`srcdir'
|
`srcdir'
|
The directory for the sources being compiled. The value of this
|
The directory for the sources being compiled. The value of this
|
variable is normally inserted by the `configure' shell script.
|
variable is normally inserted by the `configure' shell script.
|
(If you are using Autoconf, use `srcdir = @srcdir@'.)
|
(If you are using Autoconf, use `srcdir = @srcdir@'.)
|
|
|
For example:
|
For example:
|
|
|
# Common prefix for installation directories.
|
# Common prefix for installation directories.
|
# NOTE: This directory must exist when you start the install.
|
# NOTE: This directory must exist when you start the install.
|
prefix = /usr/local
|
prefix = /usr/local
|
datarootdir = $(prefix)/share
|
datarootdir = $(prefix)/share
|
datadir = $(datarootdir)
|
datadir = $(datarootdir)
|
exec_prefix = $(prefix)
|
exec_prefix = $(prefix)
|
# Where to put the executable for the command `gcc'.
|
# Where to put the executable for the command `gcc'.
|
bindir = $(exec_prefix)/bin
|
bindir = $(exec_prefix)/bin
|
# Where to put the directories used by the compiler.
|
# Where to put the directories used by the compiler.
|
libexecdir = $(exec_prefix)/libexec
|
libexecdir = $(exec_prefix)/libexec
|
# Where to put the Info files.
|
# Where to put the Info files.
|
infodir = $(datarootdir)/info
|
infodir = $(datarootdir)/info
|
|
|
If your program installs a large number of files into one of the
|
If your program installs a large number of files into one of the
|
standard user-specified directories, it might be useful to group them
|
standard user-specified directories, it might be useful to group them
|
into a subdirectory particular to that program. If you do this, you
|
into a subdirectory particular to that program. If you do this, you
|
should write the `install' rule to create these subdirectories.
|
should write the `install' rule to create these subdirectories.
|
|
|
Do not expect the user to include the subdirectory name in the value
|
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 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
|
of variable names for installation directories is to enable the user to
|
specify the exact same values for several different GNU packages. In
|
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
|
order for this to be useful, all the packages must be designed so that
|
they will work sensibly when the user does so.
|
they will work sensibly when the user does so.
|
|
|
At times, not all of these variables may be implemented in the
|
At times, not all of these variables may be implemented in the
|
current release of Autoconf and/or Automake; but as of Autoconf 2.60, we
|
current release of Autoconf and/or Automake; but as of Autoconf 2.60, we
|
believe all of them are. When any are missing, the descriptions here
|
believe all of them are. When any are missing, the descriptions here
|
serve as specifications for what Autoconf will implement. As a
|
serve as specifications for what Autoconf will implement. As a
|
programmer, you can either use a development version of Autoconf or
|
programmer, you can either use a development version of Autoconf or
|
avoid using these variables until a stable release is made which
|
avoid using these variables until a stable release is made which
|
supports them.
|
supports them.
|
|
|
|
|
File: standards.info, Node: Standard Targets, Next: Install Command Categories, Prev: Directory Variables, Up: Makefile Conventions
|
File: standards.info, Node: Standard Targets, Next: Install Command Categories, Prev: Directory Variables, Up: Makefile Conventions
|
|
|
7.2.6 Standard Targets for Users
|
7.2.6 Standard Targets for Users
|
--------------------------------
|
--------------------------------
|
|
|
All GNU programs should have the following targets in their Makefiles:
|
All GNU programs should have the following targets in their Makefiles:
|
|
|
`all'
|
`all'
|
Compile the entire program. This should be the default target.
|
Compile the entire program. This should be the default target.
|
This target need not rebuild any documentation files; Info files
|
This target need not rebuild any documentation files; Info files
|
should normally be included in the distribution, and DVI (and other
|
should normally be included in the distribution, and DVI (and other
|
documentation format) files should be made only when explicitly
|
documentation format) files should be made only when explicitly
|
asked for.
|
asked for.
|
|
|
By default, the Make rules should compile and link with `-g', so
|
By default, the Make rules should compile and link with `-g', so
|
that executable programs have debugging symbols. Users who don't
|
that executable programs have debugging symbols. Users who don't
|
mind being helpless can strip the executables later if they wish.
|
mind being helpless can strip the executables later if they wish.
|
|
|
`install'
|
`install'
|
Compile the program and copy the executables, libraries, and so on
|
Compile the program and copy the executables, libraries, and so on
|
to the file names where they should reside for actual use. If
|
to the file names where they should reside for actual use. If
|
there is a simple test to verify that a program is properly
|
there is a simple test to verify that a program is properly
|
installed, this target should run that test.
|
installed, this target should run that test.
|
|
|
Do not strip executables when installing them. Devil-may-care
|
Do not strip executables when installing them. Devil-may-care
|
users can use the `install-strip' target to do that.
|
users can use the `install-strip' target to do that.
|
|
|
If possible, write the `install' target rule so that it does not
|
If possible, write the `install' target rule so that it does not
|
modify anything in the directory where the program was built,
|
modify anything in the directory where the program was built,
|
provided `make all' has just been done. This is convenient for
|
provided `make all' has just been done. This is convenient for
|
building the program under one user name and installing it under
|
building the program under one user name and installing it under
|
another.
|
another.
|
|
|
The commands should create all the directories in which files are
|
The commands should create all the directories in which files are
|
to be installed, if they don't already exist. This includes the
|
to be installed, if they don't already exist. This includes the
|
directories specified as the values of the variables `prefix' and
|
directories specified as the values of the variables `prefix' and
|
`exec_prefix', as well as all subdirectories that are needed. One
|
`exec_prefix', as well as all subdirectories that are needed. One
|
way to do this is by means of an `installdirs' target as described
|
way to do this is by means of an `installdirs' target as described
|
below.
|
below.
|
|
|
Use `-' before any command for installing a man page, so that
|
Use `-' before any command for installing a man page, so that
|
`make' will ignore any errors. This is in case there are systems
|
`make' will ignore any errors. This is in case there are systems
|
that don't have the Unix man page documentation system installed.
|
that don't have the Unix man page documentation system installed.
|
|
|
The way to install Info files is to copy them into `$(infodir)'
|
The way to install Info files is to copy them into `$(infodir)'
|
with `$(INSTALL_DATA)' (*note Command Variables::), and then run
|
with `$(INSTALL_DATA)' (*note Command Variables::), and then run
|
the `install-info' program if it is present. `install-info' is a
|
the `install-info' program if it is present. `install-info' is a
|
program that edits the Info `dir' file to add or update the menu
|
program that edits the Info `dir' file to add or update the menu
|
entry for the given Info file; it is part of the Texinfo package.
|
entry for the given Info file; it is part of the Texinfo package.
|
Here is a sample rule to install an Info file:
|
Here is a sample rule to install an Info file:
|
|
|
$(DESTDIR)$(infodir)/foo.info: foo.info
|
$(DESTDIR)$(infodir)/foo.info: foo.info
|
$(POST_INSTALL)
|
$(POST_INSTALL)
|
# There may be a newer info file in . than in srcdir.
|
# There may be a newer info file in . than in srcdir.
|
-if test -f foo.info; then d=.; \
|
-if test -f foo.info; then d=.; \
|
else d=$(srcdir); fi; \
|
else d=$(srcdir); fi; \
|
$(INSTALL_DATA) $$d/foo.info $(DESTDIR)$@; \
|
$(INSTALL_DATA) $$d/foo.info $(DESTDIR)$@; \
|
# Run install-info only if it exists.
|
# Run install-info only if it exists.
|
# Use `if' instead of just prepending `-' to the
|
# Use `if' instead of just prepending `-' to the
|
# line so we notice real errors from install-info.
|
# line so we notice real errors from install-info.
|
# We use `$(SHELL) -c' because some shells do not
|
# We use `$(SHELL) -c' because some shells do not
|
# fail gracefully when there is an unknown command.
|
# fail gracefully when there is an unknown command.
|
if $(SHELL) -c 'install-info --version' \
|
if $(SHELL) -c 'install-info --version' \
|
>/dev/null 2>&1; then \
|
>/dev/null 2>&1; then \
|
install-info --dir-file=$(DESTDIR)$(infodir)/dir \
|
install-info --dir-file=$(DESTDIR)$(infodir)/dir \
|
$(DESTDIR)$(infodir)/foo.info; \
|
$(DESTDIR)$(infodir)/foo.info; \
|
else true; fi
|
else true; fi
|
|
|
When writing the `install' target, you must classify all the
|
When writing the `install' target, you must classify all the
|
commands into three categories: normal ones, "pre-installation"
|
commands into three categories: normal ones, "pre-installation"
|
commands and "post-installation" commands. *Note Install Command
|
commands and "post-installation" commands. *Note Install Command
|
Categories::.
|
Categories::.
|
|
|
`install-html'
|
`install-html'
|
`install-dvi'
|
`install-dvi'
|
`install-pdf'
|
`install-pdf'
|
`install-ps'
|
`install-ps'
|
These targets install documentation in formats other than Info;
|
These targets install documentation in formats other than Info;
|
they're intended to be called explicitly by the person installing
|
they're intended to be called explicitly by the person installing
|
the package, if that format is desired. GNU prefers Info files,
|
the package, if that format is desired. GNU prefers Info files,
|
so these must be installed by the `install' target.
|
so these must be installed by the `install' target.
|
|
|
When you have many documentation files to install, we recommend
|
When you have many documentation files to install, we recommend
|
that you avoid collisions and clutter by arranging for these
|
that you avoid collisions and clutter by arranging for these
|
targets to install in subdirectories of the appropriate
|
targets to install in subdirectories of the appropriate
|
installation directory, such as `htmldir'. As one example, if
|
installation directory, such as `htmldir'. As one example, if
|
your package has multiple manuals, and you wish to install HTML
|
your package has multiple manuals, and you wish to install HTML
|
documentation with many files (such as the "split" mode output by
|
documentation with many files (such as the "split" mode output by
|
`makeinfo --html'), you'll certainly want to use subdirectories,
|
`makeinfo --html'), you'll certainly want to use subdirectories,
|
or two nodes with the same name in different manuals will
|
or two nodes with the same name in different manuals will
|
overwrite each other.
|
overwrite each other.
|
|
|
Please make these `install-FORMAT' targets invoke the commands for
|
Please make these `install-FORMAT' targets invoke the commands for
|
the FORMAT target, for example, by making FORMAT a dependency.
|
the FORMAT target, for example, by making FORMAT a dependency.
|
|
|
`uninstall'
|
`uninstall'
|
Delete all the installed files--the copies that the `install' and
|
Delete all the installed files--the copies that the `install' and
|
`install-*' targets create.
|
`install-*' targets create.
|
|
|
This rule should not modify the directories where compilation is
|
This rule should not modify the directories where compilation is
|
done, only the directories where files are installed.
|
done, only the directories where files are installed.
|
|
|
The uninstallation commands are divided into three categories,
|
The uninstallation commands are divided into three categories,
|
just like the installation commands. *Note Install Command
|
just like the installation commands. *Note Install Command
|
Categories::.
|
Categories::.
|
|
|
`install-strip'
|
`install-strip'
|
Like `install', but strip the executable files while installing
|
Like `install', but strip the executable files while installing
|
them. In simple cases, this target can use the `install' target in
|
them. In simple cases, this target can use the `install' target in
|
a simple way:
|
a simple way:
|
|
|
install-strip:
|
install-strip:
|
$(MAKE) INSTALL_PROGRAM='$(INSTALL_PROGRAM) -s' \
|
$(MAKE) INSTALL_PROGRAM='$(INSTALL_PROGRAM) -s' \
|
install
|
install
|
|
|
But if the package installs scripts as well as real executables,
|
But if the package installs scripts as well as real executables,
|
the `install-strip' target can't just refer to the `install'
|
the `install-strip' target can't just refer to the `install'
|
target; it has to strip the executables but not the scripts.
|
target; it has to strip the executables but not the scripts.
|
|
|
`install-strip' should not strip the executables in the build
|
`install-strip' should not strip the executables in the build
|
directory which are being copied for installation. It should only
|
directory which are being copied for installation. It should only
|
strip the copies that are installed.
|
strip the copies that are installed.
|
|
|
Normally we do not recommend stripping an executable unless you
|
Normally we do not recommend stripping an executable unless you
|
are sure the program has no bugs. However, it can be reasonable
|
are sure the program has no bugs. However, it can be reasonable
|
to install a stripped executable for actual execution while saving
|
to install a stripped executable for actual execution while saving
|
the unstripped executable elsewhere in case there is a bug.
|
the unstripped executable elsewhere in case there is a bug.
|
|
|
`clean'
|
`clean'
|
Delete all files in the current directory that are normally
|
Delete all files in the current directory that are normally
|
created by building the program. Also delete files in other
|
created by building the program. Also delete files in other
|
directories if they are created by this makefile. However, don't
|
directories if they are created by this makefile. However, don't
|
delete the files that record the configuration. Also preserve
|
delete the files that record the configuration. Also preserve
|
files that could be made by building, but normally aren't because
|
files that could be made by building, but normally aren't because
|
the distribution comes with them. There is no need to delete
|
the distribution comes with them. There is no need to delete
|
parent directories that were created with `mkdir -p', since they
|
parent directories that were created with `mkdir -p', since they
|
could have existed anyway.
|
could have existed anyway.
|
|
|
Delete `.dvi' files here if they are not part of the distribution.
|
Delete `.dvi' files here if they are not part of the distribution.
|
|
|
`distclean'
|
`distclean'
|
Delete all files in the current directory (or created by this
|
Delete all files in the current directory (or created by this
|
makefile) that are created by configuring or building the program.
|
makefile) that are created by configuring or building the program.
|
If you have unpacked the source and built the program without
|
If you have unpacked the source and built the program without
|
creating any other files, `make distclean' should leave only the
|
creating any other files, `make distclean' should leave only the
|
files that were in the distribution. However, there is no need to
|
files that were in the distribution. However, there is no need to
|
delete parent directories that were created with `mkdir -p', since
|
delete parent directories that were created with `mkdir -p', since
|
they could have existed anyway.
|
they could have existed anyway.
|
|
|
`mostlyclean'
|
`mostlyclean'
|
Like `clean', but may refrain from deleting a few files that people
|
Like `clean', but may refrain from deleting a few files that people
|
normally don't want to recompile. For example, the `mostlyclean'
|
normally don't want to recompile. For example, the `mostlyclean'
|
target for GCC does not delete `libgcc.a', because recompiling it
|
target for GCC does not delete `libgcc.a', because recompiling it
|
is rarely necessary and takes a lot of time.
|
is rarely necessary and takes a lot of time.
|
|
|
`maintainer-clean'
|
`maintainer-clean'
|
Delete almost everything that can be reconstructed with this
|
Delete almost everything that can be reconstructed with this
|
Makefile. This typically includes everything deleted by
|
Makefile. This typically includes everything deleted by
|
`distclean', plus more: C source files produced by Bison, tags
|
`distclean', plus more: C source files produced by Bison, tags
|
tables, Info files, and so on.
|
tables, Info files, and so on.
|
|
|
The reason we say "almost everything" is that running the command
|
The reason we say "almost everything" is that running the command
|
`make maintainer-clean' should not delete `configure' even if
|
`make maintainer-clean' should not delete `configure' even if
|
`configure' can be remade using a rule in the Makefile. More
|
`configure' can be remade using a rule in the Makefile. More
|
generally, `make maintainer-clean' should not delete anything that
|
generally, `make maintainer-clean' should not delete anything that
|
needs to exist in order to run `configure' and then begin to build
|
needs to exist in order to run `configure' and then begin to build
|
the program. Also, there is no need to delete parent directories
|
the program. Also, there is no need to delete parent directories
|
that were created with `mkdir -p', since they could have existed
|
that were created with `mkdir -p', since they could have existed
|
anyway. These are the only exceptions; `maintainer-clean' should
|
anyway. These are the only exceptions; `maintainer-clean' should
|
delete everything else that can be rebuilt.
|
delete everything else that can be rebuilt.
|
|
|
The `maintainer-clean' target is intended to be used by a
|
The `maintainer-clean' target is intended to be used by a
|
maintainer of the package, not by ordinary users. You may need
|
maintainer of the package, not by ordinary users. You may need
|
special tools to reconstruct some of the files that `make
|
special tools to reconstruct some of the files that `make
|
maintainer-clean' deletes. Since these files are normally
|
maintainer-clean' deletes. Since these files are normally
|
included in the distribution, we don't take care to make them easy
|
included in the distribution, we don't take care to make them easy
|
to reconstruct. If you find you need to unpack the full
|
to reconstruct. If you find you need to unpack the full
|
distribution again, don't blame us.
|
distribution again, don't blame us.
|
|
|
To help make users aware of this, the commands for the special
|
To help make users aware of this, the commands for the special
|
`maintainer-clean' target should start with these two:
|
`maintainer-clean' target should start with these two:
|
|
|
@echo 'This command is intended for maintainers to use; it'
|
@echo 'This command is intended for maintainers to use; it'
|
@echo 'deletes files that may need special tools to rebuild.'
|
@echo 'deletes files that may need special tools to rebuild.'
|
|
|
`TAGS'
|
`TAGS'
|
Update a tags table for this program.
|
Update a tags table for this program.
|
|
|
`info'
|
`info'
|
Generate any Info files needed. The best way to write the rules
|
Generate any Info files needed. The best way to write the rules
|
is as follows:
|
is as follows:
|
|
|
info: foo.info
|
info: foo.info
|
|
|
foo.info: foo.texi chap1.texi chap2.texi
|
foo.info: foo.texi chap1.texi chap2.texi
|
$(MAKEINFO) $(srcdir)/foo.texi
|
$(MAKEINFO) $(srcdir)/foo.texi
|
|
|
You must define the variable `MAKEINFO' in the Makefile. It should
|
You must define the variable `MAKEINFO' in the Makefile. It should
|
run the `makeinfo' program, which is part of the Texinfo
|
run the `makeinfo' program, which is part of the Texinfo
|
distribution.
|
distribution.
|
|
|
Normally a GNU distribution comes with Info files, and that means
|
Normally a GNU distribution comes with Info files, and that means
|
the Info files are present in the source directory. Therefore,
|
the Info files are present in the source directory. Therefore,
|
the Make rule for an info file should update it in the source
|
the Make rule for an info file should update it in the source
|
directory. When users build the package, ordinarily Make will not
|
directory. When users build the package, ordinarily Make will not
|
update the Info files because they will already be up to date.
|
update the Info files because they will already be up to date.
|
|
|
`dvi'
|
`dvi'
|
`html'
|
`html'
|
`pdf'
|
`pdf'
|
`ps'
|
`ps'
|
Generate documentation files in the given format. These targets
|
Generate documentation files in the given format. These targets
|
should always exist, but any or all can be a no-op if the given
|
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
|
output format cannot be generated. These targets should not be
|
dependencies of the `all' target; the user must manually invoke
|
dependencies of the `all' target; the user must manually invoke
|
them.
|
them.
|
|
|
Here's an example rule for generating DVI files from Texinfo:
|
Here's an example rule for generating DVI files from Texinfo:
|
|
|
dvi: foo.dvi
|
dvi: foo.dvi
|
|
|
foo.dvi: foo.texi chap1.texi chap2.texi
|
foo.dvi: foo.texi chap1.texi chap2.texi
|
$(TEXI2DVI) $(srcdir)/foo.texi
|
$(TEXI2DVI) $(srcdir)/foo.texi
|
|
|
You must define the variable `TEXI2DVI' in the Makefile. It should
|
You must define the variable `TEXI2DVI' in the Makefile. It should
|
run the program `texi2dvi', which is part of the Texinfo
|
run the program `texi2dvi', which is part of the Texinfo
|
distribution.(1) Alternatively, write just the dependencies, and
|
distribution.(1) Alternatively, write just the dependencies, and
|
allow GNU `make' to provide the command.
|
allow GNU `make' to provide the command.
|
|
|
Here's another example, this one for generating HTML from Texinfo:
|
Here's another example, this one for generating HTML from Texinfo:
|
|
|
html: foo.html
|
html: foo.html
|
|
|
foo.html: foo.texi chap1.texi chap2.texi
|
foo.html: foo.texi chap1.texi chap2.texi
|
$(TEXI2HTML) $(srcdir)/foo.texi
|
$(TEXI2HTML) $(srcdir)/foo.texi
|
|
|
Again, you would define the variable `TEXI2HTML' in the Makefile;
|
Again, you would define the variable `TEXI2HTML' in the Makefile;
|
for example, it might run `makeinfo --no-split --html' (`makeinfo'
|
for example, it might run `makeinfo --no-split --html' (`makeinfo'
|
is part of the Texinfo distribution).
|
is part of the Texinfo distribution).
|
|
|
`dist'
|
`dist'
|
Create a distribution tar file for this program. The tar file
|
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
|
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
|
a subdirectory name which is the name of the package it is a
|
distribution for. This name can include the version number.
|
distribution for. This name can include the version number.
|
|
|
For example, the distribution tar file of GCC version 1.40 unpacks
|
For example, the distribution tar file of GCC version 1.40 unpacks
|
into a subdirectory named `gcc-1.40'.
|
into a subdirectory named `gcc-1.40'.
|
|
|
The easiest way to do this is to create a subdirectory
|
The easiest way to do this is to create a subdirectory
|
appropriately named, use `ln' or `cp' to install the proper files
|
appropriately named, use `ln' or `cp' to install the proper files
|
in it, and then `tar' that subdirectory.
|
in it, and then `tar' that subdirectory.
|
|
|
Compress the tar file with `gzip'. For example, the actual
|
Compress the tar file with `gzip'. For example, the actual
|
distribution file for GCC version 1.40 is called `gcc-1.40.tar.gz'.
|
distribution file for GCC version 1.40 is called `gcc-1.40.tar.gz'.
|
|
|
The `dist' target should explicitly depend on all non-source files
|
The `dist' target should explicitly depend on all non-source files
|
that are in the distribution, to make sure they are up to date in
|
that are in the distribution, to make sure they are up to date in
|
the distribution. *Note Making Releases: Releases.
|
the distribution. *Note Making Releases: Releases.
|
|
|
`check'
|
`check'
|
Perform self-tests (if any). The user must build the program
|
Perform self-tests (if any). The user must build the program
|
before running the tests, but need not install the program; you
|
before running the tests, but need not install the program; you
|
should write the self-tests so that they work when the program is
|
should write the self-tests so that they work when the program is
|
built but not installed.
|
built but not installed.
|
|
|
The following targets are suggested as conventional names, for
|
The following targets are suggested as conventional names, for
|
programs in which they are useful.
|
programs in which they are useful.
|
|
|
`installcheck'
|
`installcheck'
|
Perform installation tests (if any). The user must build and
|
Perform installation tests (if any). The user must build and
|
install the program before running the tests. You should not
|
install the program before running the tests. You should not
|
assume that `$(bindir)' is in the search path.
|
assume that `$(bindir)' is in the search path.
|
|
|
`installdirs'
|
`installdirs'
|
It's useful to add a target named `installdirs' to create the
|
It's useful to add a target named `installdirs' to create the
|
directories where files are installed, and their parent
|
directories where files are installed, and their parent
|
directories. There is a script called `mkinstalldirs' which is
|
directories. There is a script called `mkinstalldirs' which is
|
convenient for this; you can find it in the Texinfo package. You
|
convenient for this; you can find it in the Texinfo package. You
|
can use a rule like this:
|
can use a rule like this:
|
|
|
# Make sure all installation directories (e.g. $(bindir))
|
# Make sure all installation directories (e.g. $(bindir))
|
# actually exist by making them if necessary.
|
# actually exist by making them if necessary.
|
installdirs: mkinstalldirs
|
installdirs: mkinstalldirs
|
$(srcdir)/mkinstalldirs $(bindir) $(datadir) \
|
$(srcdir)/mkinstalldirs $(bindir) $(datadir) \
|
$(libdir) $(infodir) \
|
$(libdir) $(infodir) \
|
$(mandir)
|
$(mandir)
|
|
|
or, if you wish to support `DESTDIR',
|
or, if you wish to support `DESTDIR',
|
|
|
# Make sure all installation directories (e.g. $(bindir))
|
# Make sure all installation directories (e.g. $(bindir))
|
# actually exist by making them if necessary.
|
# actually exist by making them if necessary.
|
installdirs: mkinstalldirs
|
installdirs: mkinstalldirs
|
$(srcdir)/mkinstalldirs \
|
$(srcdir)/mkinstalldirs \
|
$(DESTDIR)$(bindir) $(DESTDIR)$(datadir) \
|
$(DESTDIR)$(bindir) $(DESTDIR)$(datadir) \
|
$(DESTDIR)$(libdir) $(DESTDIR)$(infodir) \
|
$(DESTDIR)$(libdir) $(DESTDIR)$(infodir) \
|
$(DESTDIR)$(mandir)
|
$(DESTDIR)$(mandir)
|
|
|
This rule should not modify the directories where compilation is
|
This rule should not modify the directories where compilation is
|
done. It should do nothing but create installation directories.
|
done. It should do nothing but create installation directories.
|
|
|
---------- Footnotes ----------
|
---------- Footnotes ----------
|
|
|
(1) `texi2dvi' uses TeX to do the real work of formatting. TeX is
|
(1) `texi2dvi' uses TeX to do the real work of formatting. TeX is
|
not distributed with Texinfo.
|
not distributed with Texinfo.
|
|
|
|
|
File: standards.info, Node: Install Command Categories, Prev: Standard Targets, Up: Makefile Conventions
|
File: standards.info, Node: Install Command Categories, Prev: Standard Targets, Up: Makefile Conventions
|
|
|
7.2.7 Install Command Categories
|
7.2.7 Install Command Categories
|
--------------------------------
|
--------------------------------
|
|
|
When writing the `install' target, you must classify all the commands
|
When writing the `install' target, you must classify all the commands
|
into three categories: normal ones, "pre-installation" commands and
|
into three categories: normal ones, "pre-installation" commands and
|
"post-installation" commands.
|
"post-installation" commands.
|
|
|
Normal commands move files into their proper places, and set their
|
Normal commands move files into their proper places, and set their
|
modes. They may not alter any files except the ones that come entirely
|
modes. They may not alter any files except the ones that come entirely
|
from the package they belong to.
|
from the package they belong to.
|
|
|
Pre-installation and post-installation commands may alter other
|
Pre-installation and post-installation commands may alter other
|
files; in particular, they can edit global configuration files or data
|
files; in particular, they can edit global configuration files or data
|
bases.
|
bases.
|
|
|
Pre-installation commands are typically executed before the normal
|
Pre-installation commands are typically executed before the normal
|
commands, and post-installation commands are typically run after the
|
commands, and post-installation commands are typically run after the
|
normal commands.
|
normal commands.
|
|
|
The most common use for a post-installation command is to run
|
The most common use for a post-installation command is to run
|
`install-info'. This cannot be done with a normal command, since it
|
`install-info'. This cannot be done with a normal command, since it
|
alters a file (the Info directory) which does not come entirely and
|
alters a file (the Info directory) which does not come entirely and
|
solely from the package being installed. It is a post-installation
|
solely from the package being installed. It is a post-installation
|
command because it needs to be done after the normal command which
|
command because it needs to be done after the normal command which
|
installs the package's Info files.
|
installs the package's Info files.
|
|
|
Most programs don't need any pre-installation commands, but we have
|
Most programs don't need any pre-installation commands, but we have
|
the feature just in case it is needed.
|
the feature just in case it is needed.
|
|
|
To classify the commands in the `install' rule into these three
|
To classify the commands in the `install' rule into these three
|
categories, insert "category lines" among them. A category line
|
categories, insert "category lines" among them. A category line
|
specifies the category for the commands that follow.
|
specifies the category for the commands that follow.
|
|
|
A category line consists of a tab and a reference to a special Make
|
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
|
variable, plus an optional comment at the end. There are three
|
variables you can use, one for each category; the variable name
|
variables you can use, one for each category; the variable name
|
specifies the category. Category lines are no-ops in ordinary execution
|
specifies the category. Category lines are no-ops in ordinary execution
|
because these three Make variables are normally undefined (and you
|
because these three Make variables are normally undefined (and you
|
_should not_ define them in the makefile).
|
_should not_ define them in the makefile).
|
|
|
Here are the three possible category lines, each with a comment that
|
Here are the three possible category lines, each with a comment that
|
explains what it means:
|
explains what it means:
|
|
|
$(PRE_INSTALL) # Pre-install commands follow.
|
$(PRE_INSTALL) # Pre-install commands follow.
|
$(POST_INSTALL) # Post-install commands follow.
|
$(POST_INSTALL) # Post-install commands follow.
|
$(NORMAL_INSTALL) # Normal commands follow.
|
$(NORMAL_INSTALL) # Normal commands follow.
|
|
|
If you don't use a category line at the beginning of the `install'
|
If you don't use a category line at the beginning of the `install'
|
rule, all the commands are classified as normal until the first category
|
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
|
line. If you don't use any category lines, all the commands are
|
classified as normal.
|
classified as normal.
|
|
|
These are the category lines for `uninstall':
|
These are the category lines for `uninstall':
|
|
|
$(PRE_UNINSTALL) # Pre-uninstall commands follow.
|
$(PRE_UNINSTALL) # Pre-uninstall commands follow.
|
$(POST_UNINSTALL) # Post-uninstall commands follow.
|
$(POST_UNINSTALL) # Post-uninstall commands follow.
|
$(NORMAL_UNINSTALL) # Normal commands follow.
|
$(NORMAL_UNINSTALL) # Normal commands follow.
|
|
|
Typically, a pre-uninstall command would be used for deleting entries
|
Typically, a pre-uninstall command would be used for deleting entries
|
from the Info directory.
|
from the Info directory.
|
|
|
If the `install' or `uninstall' target has any dependencies which
|
If the `install' or `uninstall' target has any dependencies which
|
act as subroutines of installation, then you should start _each_
|
act as subroutines of installation, then you should start _each_
|
dependency's commands with a category line, and start the main target's
|
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
|
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
|
command is placed in the right category regardless of which of the
|
dependencies actually run.
|
dependencies actually run.
|
|
|
Pre-installation and post-installation commands should not run any
|
Pre-installation and post-installation commands should not run any
|
programs except for these:
|
programs except for these:
|
|
|
[ basename bash cat chgrp chmod chown cmp cp dd diff echo
|
[ basename bash cat chgrp chmod chown cmp cp dd diff echo
|
egrep expand expr false fgrep find getopt grep gunzip gzip
|
egrep expand expr false fgrep find getopt grep gunzip gzip
|
hostname install install-info kill ldconfig ln ls md5sum
|
hostname install install-info kill ldconfig ln ls md5sum
|
mkdir mkfifo mknod mv printenv pwd rm rmdir sed sort tee
|
mkdir mkfifo mknod mv printenv pwd rm rmdir sed sort tee
|
test touch true uname xargs yes
|
test touch true uname xargs yes
|
|
|
The reason for distinguishing the commands in this way is for the
|
The reason for distinguishing the commands in this way is for the
|
sake of making binary packages. Typically a binary package contains
|
sake of making binary packages. Typically a binary package contains
|
all the executables and other files that need to be installed, and has
|
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
|
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
|
installation commands. But installing the binary package does need to
|
execute the pre-installation and post-installation commands.
|
execute the pre-installation and post-installation commands.
|
|
|
Programs to build binary packages work by extracting the
|
Programs to build binary packages work by extracting the
|
pre-installation and post-installation commands. Here is one way of
|
pre-installation and post-installation commands. Here is one way of
|
extracting the pre-installation commands (the `-s' option to `make' is
|
extracting the pre-installation commands (the `-s' option to `make' is
|
needed to silence messages about entering subdirectories):
|
needed to silence messages about entering subdirectories):
|
|
|
make -s -n install -o all \
|
make -s -n install -o all \
|
PRE_INSTALL=pre-install \
|
PRE_INSTALL=pre-install \
|
POST_INSTALL=post-install \
|
POST_INSTALL=post-install \
|
NORMAL_INSTALL=normal-install \
|
NORMAL_INSTALL=normal-install \
|
| gawk -f pre-install.awk
|
| gawk -f pre-install.awk
|
|
|
where the file `pre-install.awk' could contain this:
|
where the file `pre-install.awk' could contain this:
|
|
|
$0 ~ /^(normal-install|post-install)[ \t]*$/ {on = 0}
|
$0 ~ /^(normal-install|post-install)[ \t]*$/ {on = 0}
|
on {print $0}
|
on {print $0}
|
$0 ~ /^pre-install[ \t]*$/ {on = 1}
|
$0 ~ /^pre-install[ \t]*$/ {on = 1}
|
|
|
|
|
File: standards.info, Node: Releases, Prev: Makefile Conventions, Up: Managing Releases
|
File: standards.info, Node: Releases, Prev: Makefile Conventions, Up: Managing Releases
|
|
|
7.3 Making Releases
|
7.3 Making Releases
|
===================
|
===================
|
|
|
You should identify each release with a pair of version numbers, 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
|
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.
|
numbers, but it is very unlikely that you really need them.
|
|
|
Package the distribution of `Foo version 69.96' up in a gzipped tar
|
Package the distribution of `Foo version 69.96' up in a gzipped tar
|
file with the name `foo-69.96.tar.gz'. It should unpack into a
|
file with the name `foo-69.96.tar.gz'. It should unpack into a
|
subdirectory named `foo-69.96'.
|
subdirectory named `foo-69.96'.
|
|
|
Building and installing the program should never modify any of the
|
Building and installing the program should never modify any of the
|
files contained in the distribution. This means that all the files
|
files contained in the distribution. This means that all the files
|
that form part of the program in any way must be classified into "source
|
that form part of the program in any way must be classified into "source
|
files" and "non-source files". Source files are written by humans and
|
files" and "non-source files". Source files are written by humans and
|
never changed automatically; non-source files are produced from source
|
never changed automatically; non-source files are produced from source
|
files by programs under the control of the Makefile.
|
files by programs under the control of the Makefile.
|
|
|
The distribution should contain a file named `README' which gives
|
The distribution should contain a file named `README' which gives
|
the name of the package, and a general description of what it does. It
|
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
|
is also good to explain the purpose of each of the first-level
|
subdirectories in the package, if there are any. The `README' file
|
subdirectories in the package, if there are any. The `README' file
|
should either state the version number of the package, or refer to where
|
should either state the version number of the package, or refer to where
|
in the package it can be found.
|
in the package it can be found.
|
|
|
The `README' file should refer to the file `INSTALL', which should
|
The `README' file should refer to the file `INSTALL', which should
|
contain an explanation of the installation procedure.
|
contain an explanation of the installation procedure.
|
|
|
The `README' file should also refer to the file which contains the
|
The `README' file should also refer to the file which contains the
|
copying conditions. The GNU GPL, if used, should be in a file called
|
copying conditions. The GNU GPL, if used, should be in a file called
|
`COPYING'. If the GNU LGPL is used, it should be in a file called
|
`COPYING'. If the GNU LGPL is used, it should be in a file called
|
`COPYING.LIB'.
|
`COPYING.LIB'.
|
|
|
Naturally, all the source files must be in the distribution. It is
|
Naturally, all the source files must be in the distribution. It is
|
okay to include non-source files in the distribution, provided they are
|
okay to include non-source files in the distribution, provided they are
|
up-to-date and machine-independent, so that building the distribution
|
up-to-date and machine-independent, so that building the distribution
|
normally will never modify them. We commonly include non-source files
|
normally will never modify them. We commonly include non-source files
|
produced by Bison, `lex', TeX, and `makeinfo'; this helps avoid
|
produced by Bison, `lex', TeX, and `makeinfo'; this helps avoid
|
unnecessary dependencies between our distributions, so that users can
|
unnecessary dependencies between our distributions, so that users can
|
install whichever packages they want to install.
|
install whichever packages they want to install.
|
|
|
Non-source files that might actually be modified by building and
|
Non-source files that might actually be modified by building and
|
installing the program should *never* be included in the distribution.
|
installing the program should *never* be included in the distribution.
|
So if you do distribute non-source files, always make sure they are up
|
So if you do distribute non-source files, always make sure they are up
|
to date when you make a new distribution.
|
to date when you make a new distribution.
|
|
|
Make sure that the directory into which the distribution unpacks (as
|
Make sure that the directory into which the distribution unpacks (as
|
well as any subdirectories) are all world-writable (octal mode 777).
|
well as any subdirectories) are all world-writable (octal mode 777).
|
This is so that old versions of `tar' which preserve the ownership and
|
This is so that old versions of `tar' which preserve the ownership and
|
permissions of the files from the tar archive will be able to extract
|
permissions of the files from the tar archive will be able to extract
|
all the files even if the user is unprivileged.
|
all the files even if the user is unprivileged.
|
|
|
Make sure that all the files in the distribution are world-readable.
|
Make sure that all the files in the distribution are world-readable.
|
|
|
Don't include any symbolic links in the distribution itself. If the
|
Don't include any symbolic links in the distribution itself. If the
|
tar file contains symbolic links, then people cannot even unpack it on
|
tar file contains symbolic links, then people cannot even unpack it on
|
systems that don't support symbolic links. Also, don't use multiple
|
systems that don't support symbolic links. Also, don't use multiple
|
names for one file in different directories, because certain file
|
names for one file in different directories, because certain file
|
systems cannot handle this and that prevents unpacking the distribution.
|
systems cannot handle this and that prevents unpacking the distribution.
|
|
|
Try to make sure that all the file names will be unique on MS-DOS. A
|
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
|
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
|
period and up to three characters. MS-DOS will truncate extra
|
characters both before and after the period. Thus, `foobarhacker.c'
|
characters both before and after the period. Thus, `foobarhacker.c'
|
and `foobarhacker.o' are not ambiguous; they are truncated to
|
and `foobarhacker.o' are not ambiguous; they are truncated to
|
`foobarha.c' and `foobarha.o', which are distinct.
|
`foobarha.c' and `foobarha.o', which are distinct.
|
|
|
Include in your distribution a copy of the `texinfo.tex' you used to
|
Include in your distribution a copy of the `texinfo.tex' you used to
|
test print any `*.texinfo' or `*.texi' files.
|
test print any `*.texinfo' or `*.texi' files.
|
|
|
Likewise, if your program uses small GNU software packages like
|
Likewise, if your program uses small GNU software packages like
|
regex, getopt, obstack, or termcap, include them in the distribution
|
regex, getopt, obstack, or termcap, include them in the distribution
|
file. Leaving them out would make the distribution file a little
|
file. Leaving them out would make the distribution file a little
|
smaller at the expense of possible inconvenience to a user who doesn't
|
smaller at the expense of possible inconvenience to a user who doesn't
|
know what other files to get.
|
know what other files to get.
|
|
|
|
|
File: standards.info, Node: References, Next: GNU Free Documentation License, Prev: Managing Releases, Up: Top
|
File: standards.info, Node: References, Next: GNU Free Documentation License, Prev: Managing Releases, Up: Top
|
|
|
8 References to Non-Free Software and Documentation
|
8 References to Non-Free Software and Documentation
|
***************************************************
|
***************************************************
|
|
|
A GNU program should not recommend use of any non-free program. We
|
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
|
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
|
people from using them, but we can and should refuse to advertise them
|
to new potential customers. Proprietary software is a social and
|
to new potential customers. Proprietary software is a social and
|
ethical problem, and the point of GNU is to solve that problem.
|
ethical problem, and the point of GNU is to solve that problem.
|
|
|
The GNU definition of free software is found on the GNU web site at
|
The GNU definition of free software is found on the GNU web site at
|
`http://www.gnu.org/philosophy/free-sw.html', and the definition of
|
`http://www.gnu.org/philosophy/free-sw.html', and the definition of
|
free documentation is found at
|
free documentation is found at
|
`http://www.gnu.org/philosophy/free-doc.html'. A list of important
|
`http://www.gnu.org/philosophy/free-doc.html'. A list of important
|
licenses and whether they qualify as free is in
|
licenses and whether they qualify as free is in
|
`http://www.gnu.org/licenses/license-list.html'. The terms "free" and
|
`http://www.gnu.org/licenses/license-list.html'. The terms "free" and
|
"non-free", used in this document, refer to that definition. If it is
|
"non-free", used in this document, refer to that definition. If it is
|
not clear whether a license qualifies as free under this definition,
|
not clear whether a license qualifies as free under this definition,
|
please ask the GNU Project by writing to . We will
|
please ask the GNU Project by writing to . We will
|
answer, and if the license is an important one, we will add it to the
|
answer, and if the license is an important one, we will add it to the
|
list.
|
list.
|
|
|
When a non-free program or system is well known, you can mention it
|
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
|
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
|
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
|
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
|
system, or how to use it together with some widely used non-free
|
program.
|
program.
|
|
|
However, you should give only the necessary information to help those
|
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
|
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
|
give, or refer to, any further information about the proprietary
|
program, and don't imply that the proprietary program enhances your
|
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
|
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
|
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
|
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
|
people who don't already use the proprietary program will not see
|
anything to lead them to take an interest in it.
|
anything to lead them to take an interest in it.
|
|
|
If a non-free program or system is obscure in your program's domain,
|
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
|
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
|
would tend to popularize the non-free program more than it popularizes
|
your program. (You cannot hope to find many additional users among the
|
your program. (You cannot hope to find many additional users among the
|
users of Foobar if the users of Foobar are few.)
|
users of Foobar if the users of Foobar are few.)
|
|
|
Sometimes a program is free software in itself but depends on a
|
Sometimes a program is free software in itself but depends on a
|
non-free platform in order to run. For instance, many Java programs
|
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
|
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
|
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
|
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
|
hope this particular problem will be gone in a few months, when Sun
|
makes the standard Java libraries free software, but of course the
|
makes the standard Java libraries free software, but of course the
|
general principle remains: you should not recommend programs that
|
general principle remains: you should not recommend programs that
|
depend on non-free software to run.
|
depend on non-free software to run.
|
|
|
Some free programs encourage the use of non-free software. A typical
|
Some free programs encourage the use of non-free software. A typical
|
example is `mplayer'. It is free software in itself, and the free code
|
example is `mplayer'. It is free software in itself, and the free code
|
can handle some kinds of files. However, `mplayer' recommends use of
|
can handle some kinds of files. However, `mplayer' recommends use of
|
non-free codecs for other kinds of files, and users that install
|
non-free codecs for other kinds of files, and users that install
|
`mplayer' are very likely to install those codecs along with it. To
|
`mplayer' are very likely to install those codecs along with it. To
|
recommend `mplayer' is, in effect, to recommend the non-free codecs.
|
recommend `mplayer' is, in effect, to recommend the non-free codecs.
|
We must not do that, so we cannot recommend `mplayer' either.
|
We must not do that, so we cannot recommend `mplayer' either.
|
|
|
In general, you should also not recommend programs that themselves
|
In general, you should also not recommend programs that themselves
|
strongly recommend the use of non-free software.
|
strongly recommend the use of non-free software.
|
|
|
A GNU package should not refer the user to any non-free documentation
|
A GNU package should not refer the user to any non-free documentation
|
for free software. Free documentation that can be included in free
|
for free software. Free documentation that can be included in free
|
operating systems is essential for completing the GNU system, or any
|
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
|
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
|
recommend use of documentation that we are not allowed to use in GNU
|
would weaken the impetus for the community to produce documentation
|
would weaken the impetus for the community to produce documentation
|
that we can include. So GNU packages should never recommend non-free
|
that we can include. So GNU packages should never recommend non-free
|
documentation.
|
documentation.
|
|
|
By contrast, it is ok to refer to journal articles and textbooks in
|
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
|
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
|
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
|
in the GNU system even if we are allowed to--they are outside the scope
|
of an operating system project.
|
of an operating system project.
|
|
|
Referring to a web site that describes or recommends a non-free
|
Referring to a web site that describes or recommends a non-free
|
program is in effect promoting that software, so please do not make
|
program is in effect promoting that software, so please do not make
|
links (or mention by name) web sites that contain such material. This
|
links (or mention by name) web sites that contain such material. This
|
policy is relevant particularly for the web pages for a GNU package.
|
policy is relevant particularly for the web pages for a GNU package.
|
|
|
Following links from nearly any web site can lead to non-free
|
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
|
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
|
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
|
does not itself recommend a non-free program, there is no need be
|
concerned about the sites it links to for other reasons.
|
concerned about the sites it links to for other reasons.
|
|
|
Thus, for example, you should not make a link to AT&T's web site,
|
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
|
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
|
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
|
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
|
refers to AT&T's web site in some other context (such as long-distance
|
telephone service), that is not a problem.
|
telephone service), that is not a problem.
|
|
|
|
|
File: standards.info, Node: GNU Free Documentation License, Next: Index, Prev: References, Up: Top
|
File: standards.info, Node: GNU Free Documentation License, Next: Index, Prev: References, Up: Top
|
|
|
Appendix A GNU Free Documentation License
|
Appendix A GNU Free Documentation License
|
*****************************************
|
*****************************************
|
|
|
Version 1.2, November 2002
|
Version 1.2, November 2002
|
|
|
Copyright (C) 2000,2001,2002 Free Software Foundation, Inc.
|
Copyright (C) 2000,2001,2002 Free Software Foundation, Inc.
|
51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA
|
51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA
|
|
|
Everyone is permitted to copy and distribute verbatim copies
|
Everyone is permitted to copy and distribute verbatim copies
|
of this license document, but changing it is not allowed.
|
of this license document, but changing it is not allowed.
|
|
|
0. PREAMBLE
|
0. PREAMBLE
|
|
|
The purpose of this License is to make a manual, textbook, or other
|
The purpose of this License is to make a manual, textbook, or other
|
functional and useful document "free" in the sense of freedom: to
|
functional and useful document "free" in the sense of freedom: to
|
assure everyone the effective freedom to copy and redistribute it,
|
assure everyone the effective freedom to copy and redistribute it,
|
with or without modifying it, either commercially or
|
with or without modifying it, either commercially or
|
noncommercially. Secondarily, this License preserves for the
|
noncommercially. Secondarily, this License preserves for the
|
author and publisher a way to get credit for their work, while not
|
author and publisher a way to get credit for their work, while not
|
being considered responsible for modifications made by others.
|
being considered responsible for modifications made by others.
|
|
|
This License is a kind of "copyleft", which means that derivative
|
This License is a kind of "copyleft", which means that derivative
|
works of the document must themselves be free in the same sense.
|
works of the document must themselves be free in the same sense.
|
It complements the GNU General Public License, which is a copyleft
|
It complements the GNU General Public License, which is a copyleft
|
license designed for free software.
|
license designed for free software.
|
|
|
We have designed this License in order to use it for manuals for
|
We have designed this License in order to use it for manuals for
|
free software, because free software needs free documentation: a
|
free software, because free software needs free documentation: a
|
free program should come with manuals providing the same freedoms
|
free program should come with manuals providing the same freedoms
|
that the software does. But this License is not limited to
|
that the software does. But this License is not limited to
|
software manuals; it can be used for any textual work, regardless
|
software manuals; it can be used for any textual work, regardless
|
of subject matter or whether it is published as a printed book.
|
of subject matter or whether it is published as a printed book.
|
We recommend this License principally for works whose purpose is
|
We recommend this License principally for works whose purpose is
|
instruction or reference.
|
instruction or reference.
|
|
|
1. APPLICABILITY AND DEFINITIONS
|
1. APPLICABILITY AND DEFINITIONS
|
|
|
This License applies to any manual or other work, in any medium,
|
This License applies to any manual or other work, in any medium,
|
that contains a notice placed by the copyright holder saying it
|
that contains a notice placed by the copyright holder saying it
|
can be distributed under the terms of this License. Such a notice
|
can be distributed under the terms of this License. Such a notice
|
grants a world-wide, royalty-free license, unlimited in duration,
|
grants a world-wide, royalty-free license, unlimited in duration,
|
to use that work under the conditions stated herein. The
|
to use that work under the conditions stated herein. The
|
"Document", below, refers to any such manual or work. Any member
|
"Document", below, refers to any such manual or work. Any member
|
of the public is a licensee, and is addressed as "you". You
|
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
|
accept the license if you copy, modify or distribute the work in a
|
way requiring permission under copyright law.
|
way requiring permission under copyright law.
|
|
|
A "Modified Version" of the Document means any work containing the
|
A "Modified Version" of the Document means any work containing the
|
Document or a portion of it, either copied verbatim, or with
|
Document or a portion of it, either copied verbatim, or with
|
modifications and/or translated into another language.
|
modifications and/or translated into another language.
|
|
|
A "Secondary Section" is a named appendix or a front-matter section
|
A "Secondary Section" is a named appendix or a front-matter section
|
of the Document that deals exclusively with the relationship of the
|
of the Document that deals exclusively with the relationship of the
|
publishers or authors of the Document to the Document's overall
|
publishers or authors of the Document to the Document's overall
|
subject (or to related matters) and contains nothing that could
|
subject (or to related matters) and contains nothing that could
|
fall directly within that overall subject. (Thus, if the Document
|
fall directly within that overall subject. (Thus, if the Document
|
is in part a textbook of mathematics, a Secondary Section may not
|
is in part a textbook of mathematics, a Secondary Section may not
|
explain any mathematics.) The relationship could be a matter of
|
explain any mathematics.) The relationship could be a matter of
|
historical connection with the subject or with related matters, or
|
historical connection with the subject or with related matters, or
|
of legal, commercial, philosophical, ethical or political position
|
of legal, commercial, philosophical, ethical or political position
|
regarding them.
|
regarding them.
|
|
|
The "Invariant Sections" are certain Secondary Sections whose
|
The "Invariant Sections" are certain Secondary Sections whose
|
titles are designated, as being those of Invariant Sections, in
|
titles are designated, as being those of Invariant Sections, in
|
the notice that says that the Document is released under this
|
the notice that says that the Document is released under this
|
License. If a section does not fit the above definition of
|
License. If a section does not fit the above definition of
|
Secondary then it is not allowed to be designated as Invariant.
|
Secondary then it is not allowed to be designated as Invariant.
|
The Document may contain zero Invariant Sections. If the Document
|
The Document may contain zero Invariant Sections. If the Document
|
does not identify any Invariant Sections then there are none.
|
does not identify any Invariant Sections then there are none.
|
|
|
The "Cover Texts" are certain short passages of text that are
|
The "Cover Texts" are certain short passages of text that are
|
listed, as Front-Cover Texts or Back-Cover Texts, in the notice
|
listed, as Front-Cover Texts or Back-Cover Texts, in the notice
|
that says that the Document is released under this License. A
|
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
|
Front-Cover Text may be at most 5 words, and a Back-Cover Text may
|
be at most 25 words.
|
be at most 25 words.
|
|
|
A "Transparent" copy of the Document means a machine-readable copy,
|
A "Transparent" copy of the Document means a machine-readable copy,
|
represented in a format whose specification is available to the
|
represented in a format whose specification is available to the
|
general public, that is suitable for revising the document
|
general public, that is suitable for revising the document
|
straightforwardly with generic text editors or (for images
|
straightforwardly with generic text editors or (for images
|
composed of pixels) generic paint programs or (for drawings) some
|
composed of pixels) generic paint programs or (for drawings) some
|
widely available drawing editor, and that is suitable for input to
|
widely available drawing editor, and that is suitable for input to
|
text formatters or for automatic translation to a variety of
|
text formatters or for automatic translation to a variety of
|
formats suitable for input to text formatters. A copy made in an
|
formats suitable for input to text formatters. A copy made in an
|
otherwise Transparent file format whose markup, or absence of
|
otherwise Transparent file format whose markup, or absence of
|
markup, has been arranged to thwart or discourage subsequent
|
markup, has been arranged to thwart or discourage subsequent
|
modification by readers is not Transparent. An image format is
|
modification by readers is not Transparent. An image format is
|
not Transparent if used for any substantial amount of text. A
|
not Transparent if used for any substantial amount of text. A
|
copy that is not "Transparent" is called "Opaque".
|
copy that is not "Transparent" is called "Opaque".
|
|
|
Examples of suitable formats for Transparent copies include plain
|
Examples of suitable formats for Transparent copies include plain
|
ASCII without markup, Texinfo input format, LaTeX input format,
|
ASCII without markup, Texinfo input format, LaTeX input format,
|
SGML or XML using a publicly available DTD, and
|
SGML or XML using a publicly available DTD, and
|
standard-conforming simple HTML, PostScript or PDF designed for
|
standard-conforming simple HTML, PostScript or PDF designed for
|
human modification. Examples of transparent image formats include
|
human modification. Examples of transparent image formats include
|
PNG, XCF and JPG. Opaque formats include proprietary formats that
|
PNG, XCF and JPG. Opaque formats include proprietary formats that
|
can be read and edited only by proprietary word processors, SGML or
|
can be read and edited only by proprietary word processors, SGML or
|
XML for which the DTD and/or processing tools are not generally
|
XML for which the DTD and/or processing tools are not generally
|
available, and the machine-generated HTML, PostScript or PDF
|
available, and the machine-generated HTML, PostScript or PDF
|
produced by some word processors for output purposes only.
|
produced by some word processors for output purposes only.
|
|
|
The "Title Page" means, for a printed book, the title page itself,
|
The "Title Page" means, for a printed book, the title page itself,
|
plus such following pages as are needed to hold, legibly, the
|
plus such following pages as are needed to hold, legibly, the
|
material this License requires to appear in the title page. For
|
material this License requires to appear in the title page. For
|
works in formats which do not have any title page as such, "Title
|
works in formats which do not have any title page as such, "Title
|
Page" means the text near the most prominent appearance of the
|
Page" means the text near the most prominent appearance of the
|
work's title, preceding the beginning of the body of the text.
|
work's title, preceding the beginning of the body of the text.
|
|
|
A section "Entitled XYZ" means a named subunit of the Document
|
A section "Entitled XYZ" means a named subunit of the Document
|
whose title either is precisely XYZ or contains XYZ in parentheses
|
whose title either is precisely XYZ or contains XYZ in parentheses
|
following text that translates XYZ in another language. (Here XYZ
|
following text that translates XYZ in another language. (Here XYZ
|
stands for a specific section name mentioned below, such as
|
stands for a specific section name mentioned below, such as
|
"Acknowledgements", "Dedications", "Endorsements", or "History".)
|
"Acknowledgements", "Dedications", "Endorsements", or "History".)
|
To "Preserve the Title" of such a section when you modify the
|
To "Preserve the Title" of such a section when you modify the
|
Document means that it remains a section "Entitled XYZ" according
|
Document means that it remains a section "Entitled XYZ" according
|
to this definition.
|
to this definition.
|
|
|
The Document may include Warranty Disclaimers next to the notice
|
The Document may include Warranty Disclaimers next to the notice
|
which states that this License applies to the Document. These
|
which states that this License applies to the Document. These
|
Warranty Disclaimers are considered to be included by reference in
|
Warranty Disclaimers are considered to be included by reference in
|
this License, but only as regards disclaiming warranties: any other
|
this License, but only as regards disclaiming warranties: any other
|
implication that these Warranty Disclaimers may have is void and
|
implication that these Warranty Disclaimers may have is void and
|
has no effect on the meaning of this License.
|
has no effect on the meaning of this License.
|
|
|
2. VERBATIM COPYING
|
2. VERBATIM COPYING
|
|
|
You may copy and distribute the Document in any medium, either
|
You may copy and distribute the Document in any medium, either
|
commercially or noncommercially, provided that this License, the
|
commercially or noncommercially, provided that this License, the
|
copyright notices, and the license notice saying this License
|
copyright notices, and the license notice saying this License
|
applies to the Document are reproduced in all copies, and that you
|
applies to the Document are reproduced in all copies, and that you
|
add no other conditions whatsoever to those of this License. You
|
add no other conditions whatsoever to those of this License. You
|
may not use technical measures to obstruct or control the reading
|
may not use technical measures to obstruct or control the reading
|
or further copying of the copies you make or distribute. However,
|
or further copying of the copies you make or distribute. However,
|
you may accept compensation in exchange for copies. If you
|
you may accept compensation in exchange for copies. If you
|
distribute a large enough number of copies you must also follow
|
distribute a large enough number of copies you must also follow
|
the conditions in section 3.
|
the conditions in section 3.
|
|
|
You may also lend copies, under the same conditions stated above,
|
You may also lend copies, under the same conditions stated above,
|
and you may publicly display copies.
|
and you may publicly display copies.
|
|
|
3. COPYING IN QUANTITY
|
3. COPYING IN QUANTITY
|
|
|
If you publish printed copies (or copies in media that commonly
|
If you publish printed copies (or copies in media that commonly
|
have printed covers) of the Document, numbering more than 100, and
|
have printed covers) of the Document, numbering more than 100, and
|
the Document's license notice requires Cover Texts, you must
|
the Document's license notice requires Cover Texts, you must
|
enclose the copies in covers that carry, clearly and legibly, all
|
enclose the copies in covers that carry, clearly and legibly, all
|
these Cover Texts: Front-Cover Texts on the front cover, and
|
these Cover Texts: Front-Cover Texts on the front cover, and
|
Back-Cover Texts on the back cover. Both covers must also clearly
|
Back-Cover Texts on the back cover. Both covers must also clearly
|
and legibly identify you as the publisher of these copies. The
|
and legibly identify you as the publisher of these copies. The
|
front cover must present the full title with all words of the
|
front cover must present the full title with all words of the
|
title equally prominent and visible. You may add other material
|
title equally prominent and visible. You may add other material
|
on the covers in addition. Copying with changes limited to the
|
on the covers in addition. Copying with changes limited to the
|
covers, as long as they preserve the title of the Document and
|
covers, as long as they preserve the title of the Document and
|
satisfy these conditions, can be treated as verbatim copying in
|
satisfy these conditions, can be treated as verbatim copying in
|
other respects.
|
other respects.
|
|
|
If the required texts for either cover are too voluminous to fit
|
If the required texts for either cover are too voluminous to fit
|
legibly, you should put the first ones listed (as many as fit
|
legibly, you should put the first ones listed (as many as fit
|
reasonably) on the actual cover, and continue the rest onto
|
reasonably) on the actual cover, and continue the rest onto
|
adjacent pages.
|
adjacent pages.
|
|
|
If you publish or distribute Opaque copies of the Document
|
If you publish or distribute Opaque copies of the Document
|
numbering more than 100, you must either include a
|
numbering more than 100, you must either include a
|
machine-readable Transparent copy along with each Opaque copy, or
|
machine-readable Transparent copy along with each Opaque copy, or
|
state in or with each Opaque copy a computer-network location from
|
state in or with each Opaque copy a computer-network location from
|
which the general network-using public has access to download
|
which the general network-using public has access to download
|
using public-standard network protocols a complete Transparent
|
using public-standard network protocols a complete Transparent
|
copy of the Document, free of added material. If you use the
|
copy of the Document, free of added material. If you use the
|
latter option, you must take reasonably prudent steps, when you
|
latter option, you must take reasonably prudent steps, when you
|
begin distribution of Opaque copies in quantity, to ensure that
|
begin distribution of Opaque copies in quantity, to ensure that
|
this Transparent copy will remain thus accessible at the stated
|
this Transparent copy will remain thus accessible at the stated
|
location until at least one year after the last time you
|
location until at least one year after the last time you
|
distribute an Opaque copy (directly or through your agents or
|
distribute an Opaque copy (directly or through your agents or
|
retailers) of that edition to the public.
|
retailers) of that edition to the public.
|
|
|
It is requested, but not required, that you contact the authors of
|
It is requested, but not required, that you contact the authors of
|
the Document well before redistributing any large number of
|
the Document well before redistributing any large number of
|
copies, to give them a chance to provide you with an updated
|
copies, to give them a chance to provide you with an updated
|
version of the Document.
|
version of the Document.
|
|
|
4. MODIFICATIONS
|
4. MODIFICATIONS
|
|
|
You may copy and distribute a Modified Version of the Document
|
You may copy and distribute a Modified Version of the Document
|
under the conditions of sections 2 and 3 above, provided that you
|
under the conditions of sections 2 and 3 above, provided that you
|
release the Modified Version under precisely this License, with
|
release the Modified Version under precisely this License, with
|
the Modified Version filling the role of the Document, thus
|
the Modified Version filling the role of the Document, thus
|
licensing distribution and modification of the Modified Version to
|
licensing distribution and modification of the Modified Version to
|
whoever possesses a copy of it. In addition, you must do these
|
whoever possesses a copy of it. In addition, you must do these
|
things in the Modified Version:
|
things in the Modified Version:
|
|
|
A. Use in the Title Page (and on the covers, if any) a title
|
A. Use in the Title Page (and on the covers, if any) a title
|
distinct from that of the Document, and from those of
|
distinct from that of the Document, and from those of
|
previous versions (which should, if there were any, be listed
|
previous versions (which should, if there were any, be listed
|
in the History section of the Document). You may use the
|
in the History section of the Document). You may use the
|
same title as a previous version if the original publisher of
|
same title as a previous version if the original publisher of
|
that version gives permission.
|
that version gives permission.
|
|
|
B. List on the Title Page, as authors, one or more persons or
|
B. List on the Title Page, as authors, one or more persons or
|
entities responsible for authorship of the modifications in
|
entities responsible for authorship of the modifications in
|
the Modified Version, together with at least five of the
|
the Modified Version, together with at least five of the
|
principal authors of the Document (all of its principal
|
principal authors of the Document (all of its principal
|
authors, if it has fewer than five), unless they release you
|
authors, if it has fewer than five), unless they release you
|
from this requirement.
|
from this requirement.
|
|
|
C. State on the Title page the name of the publisher of the
|
C. State on the Title page the name of the publisher of the
|
Modified Version, as the publisher.
|
Modified Version, as the publisher.
|
|
|
D. Preserve all the copyright notices of the Document.
|
D. Preserve all the copyright notices of the Document.
|
|
|
E. Add an appropriate copyright notice for your modifications
|
E. Add an appropriate copyright notice for your modifications
|
adjacent to the other copyright notices.
|
adjacent to the other copyright notices.
|
|
|
F. Include, immediately after the copyright notices, a license
|
F. Include, immediately after the copyright notices, a license
|
notice giving the public permission to use the Modified
|
notice giving the public permission to use the Modified
|
Version under the terms of this License, in the form shown in
|
Version under the terms of this License, in the form shown in
|
the Addendum below.
|
the Addendum below.
|
|
|
G. Preserve in that license notice the full lists of Invariant
|
G. Preserve in that license notice the full lists of Invariant
|
Sections and required Cover Texts given in the Document's
|
Sections and required Cover Texts given in the Document's
|
license notice.
|
license notice.
|
|
|
H. Include an unaltered copy of this License.
|
H. Include an unaltered copy of this License.
|
|
|
I. Preserve the section Entitled "History", Preserve its Title,
|
I. Preserve the section Entitled "History", Preserve its Title,
|
and add to it an item stating at least the title, year, new
|
and add to it an item stating at least the title, year, new
|
authors, and publisher of the Modified Version as given on
|
authors, and publisher of the Modified Version as given on
|
the Title Page. If there is no section Entitled "History" in
|
the Title Page. If there is no section Entitled "History" in
|
the Document, create one stating the title, year, authors,
|
the Document, create one stating the title, year, authors,
|
and publisher of the Document as given on its Title Page,
|
and publisher of the Document as given on its Title Page,
|
then add an item describing the Modified Version as stated in
|
then add an item describing the Modified Version as stated in
|
the previous sentence.
|
the previous sentence.
|
|
|
J. Preserve the network location, if any, given in the Document
|
J. Preserve the network location, if any, given in the Document
|
for public access to a Transparent copy of the Document, and
|
for public access to a Transparent copy of the Document, and
|
likewise the network locations given in the Document for
|
likewise the network locations given in the Document for
|
previous versions it was based on. These may be placed in
|
previous versions it was based on. These may be placed in
|
the "History" section. You may omit a network location for a
|
the "History" section. You may omit a network location for a
|
work that was published at least four years before the
|
work that was published at least four years before the
|
Document itself, or if the original publisher of the version
|
Document itself, or if the original publisher of the version
|
it refers to gives permission.
|
it refers to gives permission.
|
|
|
K. For any section Entitled "Acknowledgements" or "Dedications",
|
K. For any section Entitled "Acknowledgements" or "Dedications",
|
Preserve the Title of the section, and preserve in the
|
Preserve the Title of the section, and preserve in the
|
section all the substance and tone of each of the contributor
|
section all the substance and tone of each of the contributor
|
acknowledgements and/or dedications given therein.
|
acknowledgements and/or dedications given therein.
|
|
|
L. Preserve all the Invariant Sections of the Document,
|
L. Preserve all the Invariant Sections of the Document,
|
unaltered in their text and in their titles. Section numbers
|
unaltered in their text and in their titles. Section numbers
|
or the equivalent are not considered part of the section
|
or the equivalent are not considered part of the section
|
titles.
|
titles.
|
|
|
M. Delete any section Entitled "Endorsements". Such a section
|
M. Delete any section Entitled "Endorsements". Such a section
|
may not be included in the Modified Version.
|
may not be included in the Modified Version.
|
|
|
N. Do not retitle any existing section to be Entitled
|
N. Do not retitle any existing section to be Entitled
|
"Endorsements" or to conflict in title with any Invariant
|
"Endorsements" or to conflict in title with any Invariant
|
Section.
|
Section.
|
|
|
O. Preserve any Warranty Disclaimers.
|
O. Preserve any Warranty Disclaimers.
|
|
|
If the Modified Version includes new front-matter sections or
|
If the Modified Version includes new front-matter sections or
|
appendices that qualify as Secondary Sections and contain no
|
appendices that qualify as Secondary Sections and contain no
|
material copied from the Document, you may at your option
|
material copied from the Document, you may at your option
|
designate some or all of these sections as invariant. To do this,
|
designate some or all of these sections as invariant. To do this,
|
add their titles to the list of Invariant Sections in the Modified
|
add their titles to the list of Invariant Sections in the Modified
|
Version's license notice. These titles must be distinct from any
|
Version's license notice. These titles must be distinct from any
|
other section titles.
|
other section titles.
|
|
|
You may add a section Entitled "Endorsements", provided it contains
|
You may add a section Entitled "Endorsements", provided it contains
|
nothing but endorsements of your Modified Version by various
|
nothing but endorsements of your Modified Version by various
|
parties--for example, statements of peer review or that the text
|
parties--for example, statements of peer review or that the text
|
has been approved by an organization as the authoritative
|
has been approved by an organization as the authoritative
|
definition of a standard.
|
definition of a standard.
|
|
|
You may add a passage of up to five words as a Front-Cover Text,
|
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
|
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
|
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
|
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
|
added by (or through arrangements made by) any one entity. If the
|
Document already includes a cover text for the same cover,
|
Document already includes a cover text for the same cover,
|
previously added by you or by arrangement made by the same entity
|
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
|
you are acting on behalf of, you may not add another; but you may
|
replace the old one, on explicit permission from the previous
|
replace the old one, on explicit permission from the previous
|
publisher that added the old one.
|
publisher that added the old one.
|
|
|
The author(s) and publisher(s) of the Document do not by this
|
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
|
License give permission to use their names for publicity for or to
|
assert or imply endorsement of any Modified Version.
|
assert or imply endorsement of any Modified Version.
|
|
|
5. COMBINING DOCUMENTS
|
5. COMBINING DOCUMENTS
|
|
|
You may combine the Document with other documents released under
|
You may combine the Document with other documents released under
|
this License, under the terms defined in section 4 above for
|
this License, under the terms defined in section 4 above for
|
modified versions, provided that you include in the combination
|
modified versions, provided that you include in the combination
|
all of the Invariant Sections of all of the original documents,
|
all of the Invariant Sections of all of the original documents,
|
unmodified, and list them all as Invariant Sections of your
|
unmodified, and list them all as Invariant Sections of your
|
combined work in its license notice, and that you preserve all
|
combined work in its license notice, and that you preserve all
|
their Warranty Disclaimers.
|
their Warranty Disclaimers.
|
|
|
The combined work need only contain one copy of this License, and
|
The combined work need only contain one copy of this License, and
|
multiple identical Invariant Sections may be replaced with a single
|
multiple identical Invariant Sections may be replaced with a single
|
copy. If there are multiple Invariant Sections with the same name
|
copy. If there are multiple Invariant Sections with the same name
|
but different contents, make the title of each such section unique
|
but different contents, make the title of each such section unique
|
by adding at the end of it, in parentheses, the name of the
|
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
|
original author or publisher of that section if known, or else a
|
unique number. Make the same adjustment to the section titles in
|
unique number. Make the same adjustment to the section titles in
|
the list of Invariant Sections in the license notice of the
|
the list of Invariant Sections in the license notice of the
|
combined work.
|
combined work.
|
|
|
In the combination, you must combine any sections Entitled
|
In the combination, you must combine any sections Entitled
|
"History" in the various original documents, forming one section
|
"History" in the various original documents, forming one section
|
Entitled "History"; likewise combine any sections Entitled
|
Entitled "History"; likewise combine any sections Entitled
|
"Acknowledgements", and any sections Entitled "Dedications". You
|
"Acknowledgements", and any sections Entitled "Dedications". You
|
must delete all sections Entitled "Endorsements."
|
must delete all sections Entitled "Endorsements."
|
|
|
6. COLLECTIONS OF DOCUMENTS
|
6. COLLECTIONS OF DOCUMENTS
|
|
|
You may make a collection consisting of the Document and other
|
You may make a collection consisting of the Document and other
|
documents released under this License, and replace the individual
|
documents released under this License, and replace the individual
|
copies of this License in the various documents with a single copy
|
copies of this License in the various documents with a single copy
|
that is included in the collection, provided that you follow the
|
that is included in the collection, provided that you follow the
|
rules of this License for verbatim copying of each of the
|
rules of this License for verbatim copying of each of the
|
documents in all other respects.
|
documents in all other respects.
|
|
|
You may extract a single document from such a collection, and
|
You may extract a single document from such a collection, and
|
distribute it individually under this License, provided you insert
|
distribute it individually under this License, provided you insert
|
a copy of this License into the extracted document, and follow
|
a copy of this License into the extracted document, and follow
|
this License in all other respects regarding verbatim copying of
|
this License in all other respects regarding verbatim copying of
|
that document.
|
that document.
|
|
|
7. AGGREGATION WITH INDEPENDENT WORKS
|
7. AGGREGATION WITH INDEPENDENT WORKS
|
|
|
A compilation of the Document or its derivatives with other
|
A compilation of the Document or its derivatives with other
|
separate and independent documents or works, in or on a volume of
|
separate and independent documents or works, in or on a volume of
|
a storage or distribution medium, is called an "aggregate" if the
|
a storage or distribution medium, is called an "aggregate" if the
|
copyright resulting from the compilation is not used to limit the
|
copyright resulting from the compilation is not used to limit the
|
legal rights of the compilation's users beyond what the individual
|
legal rights of the compilation's users beyond what the individual
|
works permit. When the Document is included in an aggregate, this
|
works permit. When the Document is included in an aggregate, this
|
License does not apply to the other works in the aggregate which
|
License does not apply to the other works in the aggregate which
|
are not themselves derivative works of the Document.
|
are not themselves derivative works of the Document.
|
|
|
If the Cover Text requirement of section 3 is applicable to these
|
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
|
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
|
of the entire aggregate, the Document's Cover Texts may be placed
|
on covers that bracket the Document within the aggregate, or the
|
on covers that bracket the Document within the aggregate, or the
|
electronic equivalent of covers if the Document is in electronic
|
electronic equivalent of covers if the Document is in electronic
|
form. Otherwise they must appear on printed covers that bracket
|
form. Otherwise they must appear on printed covers that bracket
|
the whole aggregate.
|
the whole aggregate.
|
|
|
8. TRANSLATION
|
8. TRANSLATION
|
|
|
Translation is considered a kind of modification, so you may
|
Translation is considered a kind of modification, so you may
|
distribute translations of the Document under the terms of section
|
distribute translations of the Document under the terms of section
|
4. Replacing Invariant Sections with translations requires special
|
4. Replacing Invariant Sections with translations requires special
|
permission from their copyright holders, but you may include
|
permission from their copyright holders, but you may include
|
translations of some or all Invariant Sections in addition to the
|
translations of some or all Invariant Sections in addition to the
|
original versions of these Invariant Sections. You may include a
|
original versions of these Invariant Sections. You may include a
|
translation of this License, and all the license notices in the
|
translation of this License, and all the license notices in the
|
Document, and any Warranty Disclaimers, provided that you also
|
Document, and any Warranty Disclaimers, provided that you also
|
include the original English version of this License and the
|
include the original English version of this License and the
|
original versions of those notices and disclaimers. In case of a
|
original versions of those notices and disclaimers. In case of a
|
disagreement between the translation and the original version of
|
disagreement between the translation and the original version of
|
this License or a notice or disclaimer, the original version will
|
this License or a notice or disclaimer, the original version will
|
prevail.
|
prevail.
|
|
|
If a section in the Document is Entitled "Acknowledgements",
|
If a section in the Document is Entitled "Acknowledgements",
|
"Dedications", or "History", the requirement (section 4) to
|
"Dedications", or "History", the requirement (section 4) to
|
Preserve its Title (section 1) will typically require changing the
|
Preserve its Title (section 1) will typically require changing the
|
actual title.
|
actual title.
|
|
|
9. TERMINATION
|
9. TERMINATION
|
|
|
You may not copy, modify, sublicense, or distribute the Document
|
You may not copy, modify, sublicense, or distribute the Document
|
except as expressly provided for under this License. Any other
|
except as expressly provided for under this License. Any other
|
attempt to copy, modify, sublicense or distribute the Document is
|
attempt to copy, modify, sublicense or distribute the Document is
|
void, and will automatically terminate your rights under this
|
void, and will automatically terminate your rights under this
|
License. However, parties who have received copies, or rights,
|
License. However, parties who have received copies, or rights,
|
from you under this License will not have their licenses
|
from you under this License will not have their licenses
|
terminated so long as such parties remain in full compliance.
|
terminated so long as such parties remain in full compliance.
|
|
|
10. FUTURE REVISIONS OF THIS LICENSE
|
10. FUTURE REVISIONS OF THIS LICENSE
|
|
|
The Free Software Foundation may publish new, revised versions of
|
The Free Software Foundation may publish new, revised versions of
|
the GNU Free Documentation License from time to time. Such new
|
the GNU Free Documentation License from time to time. Such new
|
versions will be similar in spirit to the present version, but may
|
versions will be similar in spirit to the present version, but may
|
differ in detail to address new problems or concerns. See
|
differ in detail to address new problems or concerns. See
|
`http://www.gnu.org/copyleft/'.
|
`http://www.gnu.org/copyleft/'.
|
|
|
Each version of the License is given a distinguishing version
|
Each version of the License is given a distinguishing version
|
number. If the Document specifies that a particular numbered
|
number. If the Document specifies that a particular numbered
|
version of this License "or any later version" applies to it, you
|
version of this License "or any later version" applies to it, you
|
have the option of following the terms and conditions either of
|
have the option of following the terms and conditions either of
|
that specified version or of any later version that has been
|
that specified version or of any later version that has been
|
published (not as a draft) by the Free Software Foundation. If
|
published (not as a draft) by the Free Software Foundation. If
|
the Document does not specify a version number of this License,
|
the Document does not specify a version number of this License,
|
you may choose any version ever published (not as a draft) by the
|
you may choose any version ever published (not as a draft) by the
|
Free Software Foundation.
|
Free Software Foundation.
|
|
|
ADDENDUM: How to use this License for your documents
|
ADDENDUM: How to use this License for your documents
|
====================================================
|
====================================================
|
|
|
To use this License in a document you have written, include a copy of
|
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
|
the License in the document and put the following copyright and license
|
notices just after the title page:
|
notices just after the title page:
|
|
|
Copyright (C) YEAR YOUR NAME.
|
Copyright (C) YEAR YOUR NAME.
|
Permission is granted to copy, distribute and/or modify this document
|
Permission is granted to copy, distribute and/or modify this document
|
under the terms of the GNU Free Documentation License, Version 1.2
|
under the terms of the GNU Free Documentation License, Version 1.2
|
or any later version published by the Free Software Foundation;
|
or any later version published by the Free Software Foundation;
|
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
|
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
|
Texts. A copy of the license is included in the section entitled ``GNU
|
Free Documentation License''.
|
Free Documentation License''.
|
|
|
If you have Invariant Sections, Front-Cover Texts and Back-Cover
|
If you have Invariant Sections, Front-Cover Texts and Back-Cover
|
Texts, replace the "with...Texts." line with this:
|
Texts, replace the "with...Texts." line with this:
|
|
|
with the Invariant Sections being LIST THEIR TITLES, with
|
with the Invariant Sections being LIST THEIR TITLES, with
|
the Front-Cover Texts being LIST, and with the Back-Cover Texts
|
the Front-Cover Texts being LIST, and with the Back-Cover Texts
|
being LIST.
|
being LIST.
|
|
|
If you have Invariant Sections without Cover Texts, or some other
|
If you have Invariant Sections without Cover Texts, or some other
|
combination of the three, merge those two alternatives to suit the
|
combination of the three, merge those two alternatives to suit the
|
situation.
|
situation.
|
|
|
If your document contains nontrivial examples of program code, we
|
If your document contains nontrivial examples of program code, we
|
recommend releasing these examples in parallel under your choice of
|
recommend releasing these examples in parallel under your choice of
|
free software license, such as the GNU General Public License, to
|
free software license, such as the GNU General Public License, to
|
permit their use in free software.
|
permit their use in free software.
|
|
|
|
|
File: standards.info, Node: Index, Prev: GNU Free Documentation License, Up: Top
|
File: standards.info, Node: Index, Prev: GNU Free Documentation License, Up: Top
|
|
|
Index
|
Index
|
*****
|
*****
|
|
|
[index ]
|
[index ]
|
* Menu:
|
* Menu:
|
|
|
* #endif, commenting: Comments. (line 60)
|
* #endif, commenting: Comments. (line 60)
|
* --help output: --help. (line 6)
|
* --help output: --help. (line 6)
|
* --version output: --version. (line 6)
|
* --version output: --version. (line 6)
|
* -Wall compiler option: Syntactic Conventions.
|
* -Wall compiler option: Syntactic Conventions.
|
(line 10)
|
(line 10)
|
* accepting contributions: Contributions. (line 6)
|
* accepting contributions: Contributions. (line 6)
|
* address for bug reports: --help. (line 11)
|
* address for bug reports: --help. (line 11)
|
* ANSI C standard: Standard C. (line 6)
|
* ANSI C standard: Standard C. (line 6)
|
* arbitrary limits on data: Semantics. (line 6)
|
* arbitrary limits on data: Semantics. (line 6)
|
* ASCII characters: Character Set. (line 6)
|
* ASCII characters: Character Set. (line 6)
|
* autoconf: System Portability. (line 23)
|
* autoconf: System Portability. (line 23)
|
* avoiding proprietary code: Reading Non-Free Code.
|
* avoiding proprietary code: Reading Non-Free Code.
|
(line 6)
|
(line 6)
|
* behavior, dependent on program's name: User Interfaces. (line 6)
|
* behavior, dependent on program's name: User Interfaces. (line 6)
|
* binary packages: Install Command Categories.
|
* binary packages: Install Command Categories.
|
(line 80)
|
(line 80)
|
* bindir: Directory Variables. (line 54)
|
* bindir: Directory Variables. (line 54)
|
* braces, in C source: Formatting. (line 6)
|
* braces, in C source: Formatting. (line 6)
|
* bug reports: --help. (line 11)
|
* bug reports: --help. (line 11)
|
* canonical name of a program: --version. (line 12)
|
* canonical name of a program: --version. (line 12)
|
* casting pointers to integers: CPU Portability. (line 90)
|
* casting pointers to integers: CPU Portability. (line 90)
|
* CGI programs, standard options for: Command-Line Interfaces.
|
* CGI programs, standard options for: Command-Line Interfaces.
|
(line 31)
|
(line 31)
|
* change logs: Change Logs. (line 6)
|
* change logs: Change Logs. (line 6)
|
* change logs, conditional changes: Conditional Changes. (line 6)
|
* change logs, conditional changes: Conditional Changes. (line 6)
|
* change logs, style: Style of Change Logs.
|
* change logs, style: Style of Change Logs.
|
(line 6)
|
(line 6)
|
* character set: Character Set. (line 6)
|
* character set: Character Set. (line 6)
|
* command-line arguments, decoding: Semantics. (line 46)
|
* command-line arguments, decoding: Semantics. (line 46)
|
* command-line interface: Command-Line Interfaces.
|
* command-line interface: Command-Line Interfaces.
|
(line 6)
|
(line 6)
|
* commenting: Comments. (line 6)
|
* commenting: Comments. (line 6)
|
* compatibility with C and POSIX standards: Compatibility. (line 6)
|
* compatibility with C and POSIX standards: Compatibility. (line 6)
|
* compiler warnings: Syntactic Conventions.
|
* compiler warnings: Syntactic Conventions.
|
(line 10)
|
(line 10)
|
* conditional changes, and change logs: Conditional Changes. (line 6)
|
* conditional changes, and change logs: Conditional Changes. (line 6)
|
* conditionals, comments for: Comments. (line 60)
|
* conditionals, comments for: Comments. (line 60)
|
* configure: Configuration. (line 6)
|
* configure: Configuration. (line 6)
|
* control-L: Formatting. (line 118)
|
* control-L: Formatting. (line 118)
|
* conventions for makefiles: Makefile Conventions.
|
* conventions for makefiles: Makefile Conventions.
|
(line 6)
|
(line 6)
|
* corba: Graphical Interfaces.
|
* corba: Graphical Interfaces.
|
(line 16)
|
(line 16)
|
* credits for manuals: Manual Credits. (line 6)
|
* credits for manuals: Manual Credits. (line 6)
|
* data types, and portability: CPU Portability. (line 6)
|
* data types, and portability: CPU Portability. (line 6)
|
* declaration for system functions: System Functions. (line 21)
|
* declaration for system functions: System Functions. (line 21)
|
* DESTDIR: DESTDIR. (line 6)
|
* DESTDIR: DESTDIR. (line 6)
|
* documentation: Documentation. (line 6)
|
* documentation: Documentation. (line 6)
|
* doschk: Names. (line 38)
|
* doschk: Names. (line 38)
|
* downloading this manual: Preface. (line 17)
|
* downloading this manual: Preface. (line 17)
|
* encodings: Character Set. (line 6)
|
* encodings: Character Set. (line 6)
|
* error messages: Semantics. (line 19)
|
* error messages: Semantics. (line 19)
|
* error messages, formatting: Errors. (line 6)
|
* error messages, formatting: Errors. (line 6)
|
* exec_prefix: Directory Variables. (line 36)
|
* exec_prefix: Directory Variables. (line 36)
|
* expressions, splitting: Formatting. (line 81)
|
* expressions, splitting: Formatting. (line 81)
|
* FDL, GNU Free Documentation License: GNU Free Documentation License.
|
* FDL, GNU Free Documentation License: GNU Free Documentation License.
|
(line 6)
|
(line 6)
|
* file usage: File Usage. (line 6)
|
* file usage: File Usage. (line 6)
|
* file-name limitations: Names. (line 38)
|
* file-name limitations: Names. (line 38)
|
* formatting error messages: Errors. (line 6)
|
* formatting error messages: Errors. (line 6)
|
* formatting source code: Formatting. (line 6)
|
* formatting source code: Formatting. (line 6)
|
* formfeed: Formatting. (line 118)
|
* formfeed: Formatting. (line 118)
|
* function argument, declaring: Syntactic Conventions.
|
* function argument, declaring: Syntactic Conventions.
|
(line 6)
|
(line 6)
|
* function prototypes: Standard C. (line 17)
|
* function prototypes: Standard C. (line 17)
|
* getopt: Command-Line Interfaces.
|
* getopt: Command-Line Interfaces.
|
(line 6)
|
(line 6)
|
* gettext: Internationalization.
|
* gettext: Internationalization.
|
(line 6)
|
(line 6)
|
* gnome: Graphical Interfaces.
|
* gnome: Graphical Interfaces.
|
(line 16)
|
(line 16)
|
* graphical user interface: Graphical Interfaces.
|
* graphical user interface: Graphical Interfaces.
|
(line 6)
|
(line 6)
|
* grave accent: Quote Characters. (line 6)
|
* grave accent: Quote Characters. (line 6)
|
* gtk+: Graphical Interfaces.
|
* gtk+: Graphical Interfaces.
|
(line 6)
|
(line 6)
|
* GUILE: Source Language. (line 38)
|
* GUILE: Source Language. (line 38)
|
* implicit int: Syntactic Conventions.
|
* implicit int: Syntactic Conventions.
|
(line 6)
|
(line 6)
|
* impossible conditions: Semantics. (line 70)
|
* impossible conditions: Semantics. (line 70)
|
* installations, staged: DESTDIR. (line 6)
|
* installations, staged: DESTDIR. (line 6)
|
* internationalization: Internationalization.
|
* internationalization: Internationalization.
|
(line 6)
|
(line 6)
|
* left quote: Quote Characters. (line 6)
|
* left quote: Quote Characters. (line 6)
|
* legal aspects: Legal Issues. (line 6)
|
* legal aspects: Legal Issues. (line 6)
|
* legal papers: Contributions. (line 6)
|
* legal papers: Contributions. (line 6)
|
* libexecdir: Directory Variables. (line 67)
|
* libexecdir: Directory Variables. (line 67)
|
* libraries: Libraries. (line 6)
|
* libraries: Libraries. (line 6)
|
* library functions, and portability: System Functions. (line 6)
|
* library functions, and portability: System Functions. (line 6)
|
* license for manuals: License for Manuals. (line 6)
|
* license for manuals: License for Manuals. (line 6)
|
* lint: Syntactic Conventions.
|
* lint: Syntactic Conventions.
|
(line 109)
|
(line 109)
|
* locale-specific quote characters: Quote Characters. (line 6)
|
* locale-specific quote characters: Quote Characters. (line 6)
|
* long option names: Option Table. (line 6)
|
* long option names: Option Table. (line 6)
|
* long-named options: Command-Line Interfaces.
|
* long-named options: Command-Line Interfaces.
|
(line 12)
|
(line 12)
|
* makefile, conventions for: Makefile Conventions.
|
* makefile, conventions for: Makefile Conventions.
|
(line 6)
|
(line 6)
|
* malloc return value: Semantics. (line 25)
|
* malloc return value: Semantics. (line 25)
|
* man pages: Man Pages. (line 6)
|
* man pages: Man Pages. (line 6)
|
* manual structure: Manual Structure Details.
|
* manual structure: Manual Structure Details.
|
(line 6)
|
(line 6)
|
* memory allocation failure: Semantics. (line 25)
|
* memory allocation failure: Semantics. (line 25)
|
* memory usage: Memory Usage. (line 6)
|
* memory usage: Memory Usage. (line 6)
|
* message text, and internationalization: Internationalization.
|
* message text, and internationalization: Internationalization.
|
(line 29)
|
(line 29)
|
* mmap: Mmap. (line 6)
|
* mmap: Mmap. (line 6)
|
* multiple variables in a line: Syntactic Conventions.
|
* multiple variables in a line: Syntactic Conventions.
|
(line 35)
|
(line 35)
|
* names of variables, functions, and files: Names. (line 6)
|
* names of variables, functions, and files: Names. (line 6)
|
* NEWS file: NEWS File. (line 6)
|
* NEWS file: NEWS File. (line 6)
|
* non-ASCII characters: Character Set. (line 6)
|
* non-ASCII characters: Character Set. (line 6)
|
* non-POSIX systems, and portability: System Portability. (line 32)
|
* non-POSIX systems, and portability: System Portability. (line 32)
|
* non-standard extensions: Using Extensions. (line 6)
|
* non-standard extensions: Using Extensions. (line 6)
|
* NUL characters: Semantics. (line 11)
|
* NUL characters: Semantics. (line 11)
|
* open brace: Formatting. (line 6)
|
* open brace: Formatting. (line 6)
|
* optional features, configure-time: Configuration. (line 83)
|
* optional features, configure-time: Configuration. (line 83)
|
* options for compatibility: Compatibility. (line 14)
|
* options for compatibility: Compatibility. (line 14)
|
* options, standard command-line: Command-Line Interfaces.
|
* options, standard command-line: Command-Line Interfaces.
|
(line 31)
|
(line 31)
|
* output device and program's behavior: User Interfaces. (line 13)
|
* output device and program's behavior: User Interfaces. (line 13)
|
* packaging: Releases. (line 6)
|
* packaging: Releases. (line 6)
|
* PATH_INFO, specifying standard options as: Command-Line Interfaces.
|
* PATH_INFO, specifying standard options as: Command-Line Interfaces.
|
(line 31)
|
(line 31)
|
* portability, and data types: CPU Portability. (line 6)
|
* portability, and data types: CPU Portability. (line 6)
|
* portability, and library functions: System Functions. (line 6)
|
* portability, and library functions: System Functions. (line 6)
|
* portability, between system types: System Portability. (line 6)
|
* portability, between system types: System Portability. (line 6)
|
* POSIX compatibility: Compatibility. (line 6)
|
* POSIX compatibility: Compatibility. (line 6)
|
* POSIXLY_CORRECT, environment variable: Compatibility. (line 21)
|
* POSIXLY_CORRECT, environment variable: Compatibility. (line 21)
|
* post-installation commands: Install Command Categories.
|
* post-installation commands: Install Command Categories.
|
(line 6)
|
(line 6)
|
* pre-installation commands: Install Command Categories.
|
* pre-installation commands: Install Command Categories.
|
(line 6)
|
(line 6)
|
* prefix: Directory Variables. (line 26)
|
* prefix: Directory Variables. (line 26)
|
* program configuration: Configuration. (line 6)
|
* program configuration: Configuration. (line 6)
|
* program design: Design Advice. (line 6)
|
* program design: Design Advice. (line 6)
|
* program name and its behavior: User Interfaces. (line 6)
|
* program name and its behavior: User Interfaces. (line 6)
|
* program's canonical name: --version. (line 12)
|
* program's canonical name: --version. (line 12)
|
* programming languages: Source Language. (line 6)
|
* programming languages: Source Language. (line 6)
|
* proprietary programs: Reading Non-Free Code.
|
* proprietary programs: Reading Non-Free Code.
|
(line 6)
|
(line 6)
|
* quote characters: Quote Characters. (line 6)
|
* quote characters: Quote Characters. (line 6)
|
* README file: Releases. (line 21)
|
* README file: Releases. (line 21)
|
* references to non-free material: References. (line 6)
|
* references to non-free material: References. (line 6)
|
* releasing: Managing Releases. (line 6)
|
* releasing: Managing Releases. (line 6)
|
* sbindir: Directory Variables. (line 60)
|
* sbindir: Directory Variables. (line 60)
|
* signal handling: Semantics. (line 59)
|
* signal handling: Semantics. (line 59)
|
* spaces before open-paren: Formatting. (line 75)
|
* spaces before open-paren: Formatting. (line 75)
|
* staged installs: DESTDIR. (line 6)
|
* staged installs: DESTDIR. (line 6)
|
* standard command-line options: Command-Line Interfaces.
|
* standard command-line options: Command-Line Interfaces.
|
(line 31)
|
(line 31)
|
* standards for makefiles: Makefile Conventions.
|
* standards for makefiles: Makefile Conventions.
|
(line 6)
|
(line 6)
|
* string library functions: System Functions. (line 55)
|
* string library functions: System Functions. (line 55)
|
* syntactic conventions: Syntactic Conventions.
|
* syntactic conventions: Syntactic Conventions.
|
(line 6)
|
(line 6)
|
* table of long options: Option Table. (line 6)
|
* table of long options: Option Table. (line 6)
|
* temporary files: Semantics. (line 84)
|
* temporary files: Semantics. (line 84)
|
* temporary variables: Syntactic Conventions.
|
* temporary variables: Syntactic Conventions.
|
(line 23)
|
(line 23)
|
* texinfo.tex, in a distribution: Releases. (line 70)
|
* texinfo.tex, in a distribution: Releases. (line 70)
|
* TMPDIR environment variable: Semantics. (line 84)
|
* TMPDIR environment variable: Semantics. (line 84)
|
* trademarks: Trademarks. (line 6)
|
* trademarks: Trademarks. (line 6)
|
* where to obtain standards.texi: Preface. (line 17)
|
* where to obtain standards.texi: Preface. (line 17)
|
|
|
|
|
|
|
Tag Table:
|
Tag Table:
|
Node: Top797
|
Node: Top797
|
Node: Preface2053
|
Node: Preface2053
|
Node: Legal Issues4168
|
Node: Legal Issues4168
|
Node: Reading Non-Free Code4638
|
Node: Reading Non-Free Code4638
|
Node: Contributions6368
|
Node: Contributions6368
|
Node: Trademarks8606
|
Node: Trademarks8606
|
Node: Design Advice10241
|
Node: Design Advice10241
|
Node: Source Language10833
|
Node: Source Language10833
|
Node: Compatibility12845
|
Node: Compatibility12845
|
Node: Using Extensions14473
|
Node: Using Extensions14473
|
Node: Standard C16049
|
Node: Standard C16049
|
Node: Conditional Compilation18452
|
Node: Conditional Compilation18452
|
Node: Program Behavior19850
|
Node: Program Behavior19850
|
Node: Non-GNU Standards20906
|
Node: Non-GNU Standards20906
|
Node: Semantics23187
|
Node: Semantics23187
|
Node: Libraries27906
|
Node: Libraries27906
|
Node: Errors29151
|
Node: Errors29151
|
Node: User Interfaces31644
|
Node: User Interfaces31644
|
Node: Graphical Interfaces33249
|
Node: Graphical Interfaces33249
|
Node: Command-Line Interfaces34285
|
Node: Command-Line Interfaces34285
|
Node: --version36317
|
Node: --version36317
|
Node: --help42210
|
Node: --help42210
|
Node: Option Table42764
|
Node: Option Table42764
|
Node: Memory Usage57705
|
Node: Memory Usage57705
|
Node: File Usage58736
|
Node: File Usage58736
|
Node: Writing C59486
|
Node: Writing C59486
|
Node: Formatting60458
|
Node: Formatting60458
|
Node: Comments64747
|
Node: Comments64747
|
Node: Syntactic Conventions68299
|
Node: Syntactic Conventions68299
|
Node: Names71761
|
Node: Names71761
|
Node: System Portability73973
|
Node: System Portability73973
|
Node: CPU Portability76863
|
Node: CPU Portability76863
|
Node: System Functions80775
|
Node: System Functions80775
|
Node: Internationalization85972
|
Node: Internationalization85972
|
Node: Character Set89966
|
Node: Character Set89966
|
Node: Quote Characters90779
|
Node: Quote Characters90779
|
Node: Mmap92299
|
Node: Mmap92299
|
Node: Documentation93007
|
Node: Documentation93007
|
Node: GNU Manuals94113
|
Node: GNU Manuals94113
|
Node: Doc Strings and Manuals99851
|
Node: Doc Strings and Manuals99851
|
Node: Manual Structure Details101404
|
Node: Manual Structure Details101404
|
Node: License for Manuals102822
|
Node: License for Manuals102822
|
Node: Manual Credits103796
|
Node: Manual Credits103796
|
Node: Printed Manuals104189
|
Node: Printed Manuals104189
|
Node: NEWS File104875
|
Node: NEWS File104875
|
Node: Change Logs105553
|
Node: Change Logs105553
|
Node: Change Log Concepts106307
|
Node: Change Log Concepts106307
|
Node: Style of Change Logs108396
|
Node: Style of Change Logs108396
|
Node: Simple Changes110896
|
Node: Simple Changes110896
|
Node: Conditional Changes112338
|
Node: Conditional Changes112338
|
Node: Indicating the Part Changed113760
|
Node: Indicating the Part Changed113760
|
Node: Man Pages114287
|
Node: Man Pages114287
|
Node: Reading other Manuals116599
|
Node: Reading other Manuals116599
|
Node: Managing Releases117390
|
Node: Managing Releases117390
|
Node: Configuration118171
|
Node: Configuration118171
|
Node: Makefile Conventions125891
|
Node: Makefile Conventions125891
|
Node: Makefile Basics126773
|
Node: Makefile Basics126773
|
Node: Utilities in Makefiles129947
|
Node: Utilities in Makefiles129947
|
Node: Command Variables132092
|
Node: Command Variables132092
|
Node: DESTDIR135314
|
Node: DESTDIR135314
|
Node: Directory Variables137463
|
Node: Directory Variables137463
|
Node: Standard Targets151956
|
Node: Standard Targets151956
|
Ref: Standard Targets-Footnote-1165471
|
Ref: Standard Targets-Footnote-1165471
|
Node: Install Command Categories165571
|
Node: Install Command Categories165571
|
Node: Releases170104
|
Node: Releases170104
|
Node: References174031
|
Node: References174031
|
Node: GNU Free Documentation License179526
|
Node: GNU Free Documentation License179526
|
Node: Index201958
|
Node: Index201958
|
|
|
End Tag Table
|
End Tag Table
|
|
|
