manpagez: man pages & more
info gawk
Home | html | info | man

gawk: Adding Code

 
 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 them:
 
   1. Before building the new feature into 'gawk' itself, consider
      writing it as an extension (⇒Dynamic Extensions).  If that's
      not possible, continue with the rest of the steps in this list.
 
   2. 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 (⇒Bugs), or
      <assign@gnu.org>.
 
   3. 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', or better yet, relative to the latest code in the Git
      repository.  If your version of 'gawk' is very old, I may not be
      able to integrate your changes at all.  (⇒Getting, for
      information on getting the latest version of 'gawk'.)
 
   4. See ⇒(Version, standards, GNU Coding Standards)Top.  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 website (https://www.gnu.org/prep/standards/).
      Texinfo, Info, and DVI versions are also available.)
 
   5. 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.
 
         * Use '#elif' instead of nesting '#if' inside '#else'.
 
         * 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 'true' and 'false' for 'bool' values, the 'NULL' symbolic
           constant for pointer values, and the character constant ''\0''
           where appropriate, instead of '1' and '0'.
 
         * 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 'malloc()' and 'free()'.
 
         * 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 ('0x001', '0x002', '0x004', and so 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.
 
   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 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.  (⇒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.  It is simplest if you just
      make this part of your diff.
 
    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.
 
© manpagez.com 2000-2018
Individual documents may contain additional copyright information.