C.2.2 Adding New Features
You are free to add any new features you like to gawk.
However, if you want your changes to be incorporated into the gawk
distribution, there are several steps that you need to take in order to
make it possible to include your changes:
- Before building the new feature into gawk itself,
consider writing it as an extension module
(see Dynamic Extensions).
If that's not possible, continue with the rest of the steps in this list.
- Be prepared to sign the appropriate paperwork.
In order for the FSF to distribute your changes, you must either place
those changes in the public domain and submit a signed statement to that
effect, or assign the copyright in your changes to the FSF.
Both of these actions are easy to do and many people have done so
already. If you have questions, please contact me
or “assign at gnu dot org”.
- Get the latest version.
It is much easier for me to integrate changes if they are relative to
the most recent distributed version of gawk. If your version of
gawk is very old, I may not be able to integrate them at all.
for information on getting the latest version of gawk.)
- Follow the GNU Coding Standards.
This document describes how GNU software should be written. If you haven't
read it, please do so, preferably before starting to modify gawk.
(The GNU Coding Standards are available from
the GNU Project's
Texinfo, Info, and DVI versions are also available.)
- Use the gawk coding style.
The C code for gawk follows the instructions in the
GNU Coding Standards, with minor exceptions. The code is formatted
using the traditional “K&R” style, particularly as regards to the placement
of braces and the use of TABs. In brief, the coding rules for gawk
are as follows:
- Use ANSI/ISO style (prototype) function headers when defining functions.
- Put the name of the function at the beginning of its own line.
- Put the return type of the function, even if it is
int, on the
line above the line with the name and arguments of the function.
- Put spaces around parentheses used in control structures
- Do not put spaces in front of parentheses used in function calls.
- Put spaces around all C operators and after commas in function calls.
- Do not use the comma operator to produce multiple side effects, except
for loop initialization and increment parts, and in macro bodies.
- Use real TABs for indenting, not spaces.
- Use the “K&R” brace layout style.
- Use comparisons against
'\0' in the conditions of
for statements, as well as in the
switch statements, instead of just the
plain pointer or character value.
NULL symbolic constant for pointer values,
and the character constant
'\0' where appropriate, instead of
- Provide one-line descriptive comments for each function.
- Do not use the
alloca() function for allocating memory off the
stack. Its use causes more portability trouble than is worth the minor
benefit of not having to free the storage. Instead, use
- Do not use comparisons of the form ‘! strcmp(a, b)’ or similar.
As Henry Spencer once said, “
strcmp() is not a boolean!”
Instead, use ‘strcmp(a, b) == 0’.
- If adding new bit flag values, use explicit hexadecimal constants
0x004, and son on) instead of
shifting one left by successive amounts (‘(1<<0)’, ‘(1<<1)’,
and so on).
NOTE: If I have to reformat your code to follow the coding style used in
gawk, I may not bother to integrate your changes at all.
- Update the documentation.
Along with your new code, please supply new sections and/or chapters
for this Web page. If at all possible, please use real
Texinfo, instead of just supplying unformatted ASCII text (although
even that is better than no documentation at all).
Conventions to be followed in GAWK: Effective AWK Programming are provided
after the ‘@bye’ at the end of the Texinfo source file.
If possible, please update the man page as well.
You will also have to sign paperwork for your documentation changes.
- Submit changes as unified diffs.
Use ‘diff -u -r -N’ to compare
the original gawk source tree with your version.
I recommend using the GNU version of diff, or best of all,
‘git diff’ or ‘git format-patch’.
Send the output produced by diff to me when you
submit your changes.
(See Bugs, for the electronic mail
Using this format makes it easy for me to apply your changes to the
master version of the gawk source code (using
If I have to apply the changes manually, using a text editor, I may
not do so, particularly if there are lots of changes.
- Include an entry for the ChangeLog file with your submission.
This helps further minimize the amount of work I have to do,
making it easier for me to accept patches.
Although this sounds like a lot of work, please remember that while you
may write the new code, I have to maintain it and support it. If it
isn't possible for me to do that with a minimum of extra work, then I
probably will not.