Porting `gawk' to a New Operating System
----------------------------------------
If you want to port `gawk' to a new operating system, there are
several steps to follow:
1. Follow the guidelines in Note:Adding New Features,
concerning coding style, submission of diffs, and so on.
2. When doing a port, bear in mind that your code must co-exist
peacefully with the rest of `gawk' and the other ports. Avoid
gratuitous changes to the system-independent parts of the code. If
at all possible, avoid sprinkling `#ifdef's just for your port
throughout the code.
If the changes needed for a particular system affect too much of
the code, I probably will not accept them. In such a case, you
can, of course, distribute your changes on your own, as long as
you comply with the GPL (*note GNU General Public License:
Copying.).
3. A number of the files that come with `gawk' are maintained by other
people at the Free Software Foundation. Thus, you should not
change them unless it is for a very good reason; i.e., changes are
not out of the question, but changes to these files are
scrutinized extra carefully. The files are `getopt.h', `getopt.c',
`getopt1.c', `regex.h', `regex.c', `dfa.h', `dfa.c', `install-sh',
and `mkinstalldirs'.
4. Be willing to continue to maintain the port. Non-Unix operating
systems are supported by volunteers who maintain the code needed
to compile and run `gawk' on their systems. If noone volunteers to
maintain a port, it becomes unsupported and it may be necessary to
remove it from the distribution.
5. Supply an appropriate `gawkmisc.???' file. Each port has its own
`gawkmisc.???' that implements certain operating system specific
functions. This is cleaner than a plethora of `#ifdef's scattered
throughout the code. The `gawkmisc.c' in the main source
directory includes the appropriate `gawkmisc.???' file from each
subdirectory. Be sure to update it as well.
Each port's `gawkmisc.???' file has a suffix reminiscent of the
machine or operating system for the port--for example,
`pc/gawkmisc.pc' and `vms/gawkmisc.vms'. The use of separate
suffixes, instead of plain `gawkmisc.c', makes it possible to move
files from a port's subdirectory into the main subdirectory,
without accidentally destroying the real `gawkmisc.c' file.
(Currently, this is only an issue for the PC operating system
ports.)
6. Supply a `Makefile' as well as any other C source and header files
that are necessary for your operating system. All your code
should be in a separate subdirectory, with a name that is the same
as, or reminiscent of, either your operating system or the
computer system. If possible, try to structure things so that it
is not necessary to move files out of the subdirectory into the
main source directory. If that is not possible, then be sure to
avoid using names for your files that duplicate the names of files
in the main source directory.
7. Update the documentation. Please write a section (or sections)
for this Info file describing the installation and compilation
steps needed to compile and/or install `gawk' for your system.
8. Be prepared to sign the appropriate paperwork. In order for the
FSF to distribute your code, you must either place your code in
the public domain and submit a signed statement to that effect, or
assign the copyright in your code 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 <gnu@gnu.org>.
Following these steps makes it much easier to integrate your changes
into `gawk' and have them co-exist happily with other operating
systems' code that is already there.
In the code that you supply and maintain, feel free to use a coding
style and brace layout that suits your taste.