6
6
* Standards: (standards). GNU coding standards.
9
The GNU coding standards, last updated September 14, 2009.
9
The GNU coding standards, last updated April 12, 2010.
11
11
Copyright (C) 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000,
12
2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software
12
2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 Free Software
15
15
Permission is granted to copy, distribute and/or modify this document
28
The GNU coding standards, last updated September 14, 2009.
28
The GNU coding standards, last updated April 12, 2010.
30
30
Copyright (C) 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000,
31
2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software
31
2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 Free Software
34
34
Permission is granted to copy, distribute and/or modify this document
65
65
even if you write in another programming language. The rules often
66
66
state reasons for writing in a certain way.
68
This release of the GNU Coding Standards was last updated September
71
68
If you did not obtain this file directly from the GNU project and
72
69
recently, please check for a newer version. You can get the GNU Coding
73
70
Standards from the GNU web server in many different formats, including
74
71
the Texinfo source, PDF, HTML, DVI, plain text, and more, at:
75
72
`http://www.gnu.org/prep/standards/'.
77
Corrections or suggestions for this document should be sent to
74
If you are maintaining an official GNU package, in addition to this
75
document, please read and follow the GNU maintainer information (*note
76
Contents: (maintain)Top.).
78
If you want to receive diffs for every change to these GNU documents,
79
join the mailing list `gnustandards-commit@gnu.org', via the web
81
`http://lists.gnu.org/mailman/listinfo/gnustandards-commit'. Archives
82
are also available there.
84
Please send corrections or suggestions for this document to
78
85
<bug-standards@gnu.org>. If you make a suggestion, please include a
79
suggested new wording for it; our time is limited. We prefer a context
80
diff to the `standards.texi' or `make-stds.texi' files, but if you
81
don't have those files, please mail your suggestion anyway.
86
suggested new wording for it, to help us consider the suggestion
87
efficiently. We prefer a context diff to the Texinfo source, but if
88
that's difficult for you, you can make a context diff for some other
89
version of this document, or propose it in any way that makes it clear.
90
The source repository for this document can be found at
91
`http://savannah.gnu.org/projects/gnustandards'.
83
93
These standards cover the minimum of what is important when writing a
84
94
GNU package. Likely, the need for additional standards will come up.
780
793
======================================
782
795
When you write a program that provides a graphical user interface,
783
please make it work with X Windows and the GTK+ toolkit unless the
784
functionality specifically requires some alternative (for example,
785
"displaying jpeg images while in console mode").
796
please make it work with the X Window System and the GTK+ toolkit
797
unless the functionality specifically requires some alternative (for
798
example, "displaying jpeg images while in console mode").
787
800
In addition, please provide a command-line interface to control the
788
801
functionality. (In many cases, the graphical user interface can be a
789
802
separate program which invokes the command-line program.) This is so
790
803
that the same jobs can be done from scripts.
792
Please also consider providing a CORBA interface (for use from
793
GNOME), a library interface (for use from C), and perhaps a
794
keyboard-driven console interface (for use by users from console mode).
795
Once you are doing the work to provide the functionality and the
796
graphical interface, these won't be much extra work.
805
Please also consider providing a D-bus interface for use from other
806
running programs, such as within GNOME. (GNOME used to use CORBA for
807
this, but that is being phased out.) In addition, consider providing a
808
library interface (for use from C), and perhaps a keyboard-driven
809
console interface (for use by users from console mode). Once you are
810
doing the work to provide the functionality and the graphical
811
interface, these won't be much extra work.
799
814
File: standards.info, Node: Command-Line Interfaces, Next: Option Table, Prev: Graphical Interfaces, Up: Program Behavior
3337
3350
command `C-x v a' (`vc-update-change-log') does the job.
3339
3352
There's no need to describe the full purpose of the changes or how
3340
they work together. If you think that a change calls for explanation,
3341
you're probably right. Please do explain it--but please put the
3342
explanation in comments in the code, where people will see it whenever
3343
they see the code. For example, "New function" is enough for the
3344
change log when you add a function, because there should be a comment
3345
before the function definition to explain what it does.
3353
they work together. However, sometimes it is useful to write one line
3354
to describe the overall purpose of a change or a batch of changes. If
3355
you think that a change calls for explanation, you're probably right.
3356
Please do explain it--but please put the full explanation in comments
3357
in the code, where people will see it whenever they see the code. For
3358
example, "New function" is enough for the change log when you add a
3359
function, because there should be a comment before the function
3360
definition to explain what it does.
3347
3362
In the past, we recommended not mentioning changes in non-software
3348
3363
files (manuals, help files, etc.) in change logs. However, we've been
3349
3364
advised that it is a good idea to include them, for the sake of
3350
3365
copyright records.
3352
However, sometimes it is useful to write one line to describe the
3353
overall purpose of a batch of changes.
3355
3367
The easiest way to add an entry to `ChangeLog' is with the Emacs
3356
3368
command `M-x add-change-log-entry'. An entry should have an asterisk,
3357
3369
the name of the changed file, and then in parentheses the name of the
4435
4450
the `install-info' program if it is present. `install-info' is a
4436
4451
program that edits the Info `dir' file to add or update the menu
4437
4452
entry for the given Info file; it is part of the Texinfo package.
4438
Here is a sample rule to install an Info file:
4440
$(DESTDIR)$(infodir)/foo.info: foo.info
4442
# There may be a newer info file in . than in srcdir.
4443
-if test -f foo.info; then d=.; \
4444
else d=$(srcdir); fi; \
4445
$(INSTALL_DATA) $$d/foo.info $(DESTDIR)$@; \
4454
Here is a sample rule to install an Info file that also tries to
4455
handle some additional situations, such as `install-info' not
4458
do-install-info: foo.info installdirs
4460
# Prefer an info file in . to one in srcdir.
4461
if test -f foo.info; then d=.; \
4462
else d="$(srcdir)"; fi; \
4463
$(INSTALL_DATA) $$d/foo.info \
4464
"$(DESTDIR)$(infodir)/foo.info"
4446
4465
# Run install-info only if it exists.
4447
4466
# Use `if' instead of just prepending `-' to the
4448
4467
# line so we notice real errors from install-info.
4449
# We use `$(SHELL) -c' because some shells do not
4468
# Use `$(SHELL) -c' because some shells do not
4450
4469
# fail gracefully when there is an unknown command.
4451
4471
if $(SHELL) -c 'install-info --version' \
4452
4472
>/dev/null 2>&1; then \
4453
install-info --dir-file=$(DESTDIR)$(infodir)/dir \
4454
$(DESTDIR)$(infodir)/foo.info; \
4473
install-info --dir-file="$(DESTDIR)$(infodir)/dir" \
4474
"$(DESTDIR)$(infodir)/foo.info"; \
4457
4477
When writing the `install' target, you must classify all the
4847
4866
So if you do distribute non-source files, always make sure they are up
4848
4867
to date when you make a new distribution.
4850
Make sure that the directory into which the distribution unpacks (as
4851
well as any subdirectories) are all world-writable (octal mode 777).
4852
This is so that old versions of `tar' which preserve the ownership and
4853
permissions of the files from the tar archive will be able to extract
4854
all the files even if the user is unprivileged.
4856
Make sure that all the files in the distribution are world-readable.
4869
Make sure that all the files in the distribution are world-readable,
4870
and that directories are world-readable and world-searchable (octal
4871
mode 755). We used to recommend that all directories in the
4872
distribution also be world-writable (octal mode 777), because ancient
4873
versions of `tar' would otherwise not cope when extracting the archive
4874
as an unprivileged user. That can easily lead to security issues when
4875
creating the archive, however, so now we recommend against that.
4858
4877
Don't include any symbolic links in the distribution itself. If the
4859
4878
tar file contains symbolic links, then people cannot even unpack it on
5522
5542
* control-L: Formatting. (line 118)
5523
5543
* conventions for makefiles: Makefile Conventions.
5525
* corba: Graphical Interfaces.
5545
* CORBA: Graphical Interfaces.
5527
5547
* credits for manuals: Manual Credits. (line 6)
5548
* D-bus: Graphical Interfaces.
5528
5550
* data types, and portability: CPU Portability. (line 6)
5529
5551
* declaration for system functions: System Functions. (line 21)
5530
5552
* DESTDIR: DESTDIR. (line 6)
5553
* directories, creating installation: Directory Variables. (line 20)
5531
5554
* documentation: Documentation. (line 6)
5532
5555
* doschk: Names. (line 38)
5533
* downloading this manual: Preface. (line 17)
5556
* downloading this manual: Preface. (line 14)
5534
5557
* encodings: Character Set. (line 6)
5535
5558
* error messages: Semantics. (line 19)
5536
5559
* error messages, formatting: Errors. (line 6)
5537
* exec_prefix: Directory Variables. (line 36)
5560
* exec_prefix: Directory Variables. (line 39)
5538
5561
* expressions, splitting: Formatting. (line 81)
5539
5562
* FDL, GNU Free Documentation License: GNU Free Documentation License.
5551
5574
* gettext: Internationalization.
5553
* gnome: Graphical Interfaces.
5576
* GNOME: Graphical Interfaces.
5555
5578
* GNOME and Guile: Source Language. (line 38)
5579
* gnustandards project repository: Preface. (line 30)
5580
* gnustandards-commit@gnu.org mailing list: Preface. (line 24)
5556
5581
* graphical user interface: Graphical Interfaces.
5558
5583
* grave accent: Quote Characters. (line 6)
5559
* gtk+: Graphical Interfaces.
5584
* GTK+: Graphical Interfaces.
5561
5586
* Guile: Source Language. (line 38)
5562
5587
* implicit int: Syntactic Conventions.
5564
5589
* impossible conditions: Semantics. (line 70)
5590
* installation directories, creating: Directory Variables. (line 20)
5565
5591
* installations, staged: DESTDIR. (line 6)
5592
* interface styles: Graphical Interfaces.
5566
5594
* internationalization: Internationalization.
5596
* keyboard interface: Graphical Interfaces.
5568
5598
* LDAP: OID Allocations. (line 6)
5569
5599
* left quote: Quote Characters. (line 6)
5570
5600
* legal aspects: Legal Issues. (line 6)
5571
5601
* legal papers: Contributions. (line 6)
5572
* libexecdir: Directory Variables. (line 67)
5602
* libexecdir: Directory Variables. (line 70)
5573
5603
* libraries: Libraries. (line 6)
5574
5604
* library functions, and portability: System Functions. (line 6)
5605
* library interface: Graphical Interfaces.
5575
5607
* license for manuals: License for Manuals. (line 6)
5576
5608
* lint: Syntactic Conventions.
5648
5681
* texinfo.tex, in a distribution: Releases. (line 70)
5649
5682
* TMPDIR environment variable: Semantics. (line 84)
5650
5683
* trademarks: Trademarks. (line 6)
5651
* where to obtain standards.texi: Preface. (line 17)
5684
* user interface styles: Graphical Interfaces.
5686
* where to obtain standards.texi: Preface. (line 14)
5652
5687
* X.509: OID Allocations. (line 6)
5659
Node: Legal Issues4204
5660
Node: Reading Non-Free Code4674
5661
Node: Contributions6404
5662
Node: Trademarks8642
5663
Node: Design Advice10277
5664
Node: Source Language10869
5665
Node: Compatibility12995
5666
Node: Using Extensions14623
5667
Node: Standard C16199
5668
Node: Conditional Compilation18602
5669
Node: Program Behavior20000
5670
Node: Non-GNU Standards21116
5671
Node: Semantics23397
5672
Node: Libraries28116
5674
Node: User Interfaces31854
5675
Node: Graphical Interfaces33459
5676
Node: Command-Line Interfaces34495
5677
Node: --version36527
5679
Node: Option Table43301
5680
Node: OID Allocations58256
5681
Node: Memory Usage60017
5682
Node: File Usage61053
5683
Node: Writing C61803
5684
Node: Formatting62775
5685
Node: Comments67064
5686
Node: Syntactic Conventions70616
5688
Node: System Portability76290
5689
Node: CPU Portability79181
5690
Node: System Functions83082
5691
Node: Internationalization88279
5692
Node: Character Set92273
5693
Node: Quote Characters93086
5695
Node: Documentation95314
5696
Node: GNU Manuals96420
5697
Node: Doc Strings and Manuals102158
5698
Node: Manual Structure Details103711
5699
Node: License for Manuals105129
5700
Node: Manual Credits106103
5701
Node: Printed Manuals106496
5702
Node: NEWS File107182
5703
Node: Change Logs107860
5704
Node: Change Log Concepts108614
5705
Node: Style of Change Logs110703
5706
Node: Simple Changes113203
5707
Node: Conditional Changes114645
5708
Node: Indicating the Part Changed116067
5709
Node: Man Pages116594
5710
Node: Reading other Manuals118800
5711
Node: Managing Releases119591
5712
Node: Configuration120372
5713
Node: Makefile Conventions129037
5714
Node: Makefile Basics130036
5715
Node: Utilities in Makefiles133210
5716
Node: Command Variables135708
5717
Node: DESTDIR138954
5718
Node: Directory Variables141128
5719
Node: Standard Targets155621
5720
Ref: Standard Targets-Footnote-1169234
5721
Node: Install Command Categories169334
5722
Node: Releases173867
5723
Node: References177797
5724
Node: GNU Free Documentation License183644
5694
Node: Legal Issues4801
5695
Node: Reading Non-Free Code5271
5696
Node: Contributions7001
5697
Node: Trademarks9239
5698
Node: Design Advice10874
5699
Node: Source Language11466
5700
Node: Compatibility13592
5701
Node: Using Extensions15220
5702
Node: Standard C16796
5703
Node: Conditional Compilation19199
5704
Node: Program Behavior20597
5705
Node: Non-GNU Standards21713
5706
Node: Semantics23994
5707
Node: Libraries28714
5709
Node: User Interfaces32452
5710
Node: Graphical Interfaces34057
5711
Node: Command-Line Interfaces35241
5712
Node: --version37273
5714
Node: Option Table43883
5715
Node: OID Allocations58838
5716
Node: Memory Usage60635
5717
Node: File Usage61671
5718
Node: Writing C62421
5719
Node: Formatting63393
5720
Node: Comments67682
5721
Node: Syntactic Conventions71234
5723
Node: System Portability76908
5724
Node: CPU Portability79799
5725
Node: System Functions83700
5726
Node: Internationalization88897
5727
Node: Character Set92891
5728
Node: Quote Characters93704
5730
Node: Documentation95932
5731
Node: GNU Manuals97038
5732
Node: Doc Strings and Manuals102776
5733
Node: Manual Structure Details104329
5734
Node: License for Manuals105747
5735
Node: Manual Credits106721
5736
Node: Printed Manuals107114
5737
Node: NEWS File107800
5738
Node: Change Logs108478
5739
Node: Change Log Concepts109232
5740
Node: Style of Change Logs111335
5741
Node: Simple Changes113835
5742
Node: Conditional Changes115277
5743
Node: Indicating the Part Changed116699
5744
Node: Man Pages117226
5745
Node: Reading other Manuals119432
5746
Node: Managing Releases120223
5747
Node: Configuration121004
5748
Node: Makefile Conventions129669
5749
Node: Makefile Basics130668
5750
Node: Utilities in Makefiles133842
5751
Node: Command Variables136347
5752
Node: DESTDIR139593
5753
Node: Directory Variables141767
5754
Node: Standard Targets156389
5755
Ref: Standard Targets-Footnote-1170161
5756
Node: Install Command Categories170261
5757
Node: Releases174794
5758
Node: References178799
5759
Node: GNU Free Documentation License184646