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