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 for me to include to your changes.

1. 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. See section Getting the gawk Distribution, for information on getting the latest version of gawk.
2. 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 as part of the Autoconf distribution, from the FSF.)
3. 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 the placement of braces and the use of tabs. In brief, the coding rules for gawk are:
   • Use old style (non-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.
   • The declarations for the function arguments should not be indented.
   • Put spaces around parentheses used in control structures (if, while, for, do, switch and return).
   • 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 in 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 NULL and '\0' in the conditions of if, while and for statements, and in the cases of switch statements, instead of just the plain pointer or character value.
   • Use the TRUE, FALSE, and NULL symbolic constants, and the character constant '\0' where appropriate, instead of 1 and 0.
   • Provide one-line descriptive comments for each function.
   • Do not use `#elif'. Many older Unix C compilers cannot handle it.
   • Do not use the alloca function for allocating memory off the stack. Its use causes more portability trouble than the minor benefit of not having to free the storage. Instead, use malloc and free.
   If I have to reformat your code to follow the coding style used in gawk, I may not bother.
4. 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 (see section Reporting Problems and Bugs), or [email protected].
5. Update the documentation. Along with your new code, please supply new sections and or chapters for this book. 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 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.
6. Submit changes as context diffs or unified diffs. Use `diff -c -r -N' or `diff -u -r -N' to compare the original gawk source tree with your version. (I find context diffs to be more readable, but unified diffs are more compact.) I recommend using the GNU version of diff. Send the output produced by either run of diff to me when you submit your changes. See section Reporting Problems and Bugs, for the electronic mail information. Using this format makes it easy for me to apply your changes to the master version of the gawk source code (using patch). If I have to apply the changes manually, using a text editor, I may not do so, particularly if there are lots of changes.

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, and if it isn't possible for me to do that with a minimum of extra work, then I probably will not.

Go to the first, previous, next, last section, table of contents.