GNU Info

(gawk.info)Adding Code

---

Next: New Ports Prev: Additions Up: Additions

---

Enter node , (file) or (file)node

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 your changes:

  1. Before building the new feature into `gawk' itself, consider
     writing it as an extension module (Note: Adding New Built-in
     Functions to `gawk'.).  If that's not
     possible, continue with the rest of the steps in this list.

  2. 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.  (Note: Getting the `gawk'
     Distribution, for information on getting the latest
     version of `gawk'.)

  3. See Note: (Version)Top standards, 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 `ftp' site, at
     `ftp://gnudist.gnu.org/gnu/GNUInfo/standards.text'.  Texinfo,
     Info, and DVI versions are also available.)

  4. 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
          (`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, as well as in the `case's
          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'.

        * Use the `ISALPHA', `ISDIGIT', etc. macros, instead of the
          traditional lowercase versions; these macros are better
          behaved for non-ASCII character sets.

        * 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 is
          worth the minor benefit of not having to free the storage.
          Instead, use `malloc' and `free'.

     *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.

  5. 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 (Note: Reporting
     Problems and Bugs.), or <gnu@gnu.org>.

  6. Update the documentation.  Along with your new code, please supply
     new sections and/or chapters for this Info file.  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.

  7. 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.  (Note: 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.

  8. 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.