File: gawk.info,  Node: New Ports,  Next: Derived Files,  Prev: Adding Code,  Up: Additions

C.2.3 Porting 'gawk' to a New Operating System
----------------------------------------------

If you want to port 'gawk' to a new operating system, there are several
steps:

  1. Follow the guidelines in *note Adding Code::, concerning coding
     style, submission of diffs, and so on.

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

  3. When doing a port, bear in mind that your code must coexist
     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 Copying::).

  4. A number of the files that come with 'gawk' are maintained by other
     people.  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.  These are all the
     files in the 'support' directory within the 'gawk' distribution.
     See there.

  5. A number of other files are provided by the GNU Autotools
     (Autoconf, Automake, and GNU 'gettext').  You should not change
     them either, unless it is for a very good reason.  The files are
     'ABOUT-NLS', 'config.guess', 'config.rpath', 'config.sub',
     'depcomp', 'INSTALL', 'install-sh', 'missing', 'mkinstalldirs', and
     'ylwrap'.

  6. 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 no-one volunteers to
     maintain a port, it becomes unsupported and it may be necessary to
     remove it from the distribution.

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

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

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

   Following these steps makes it much easier to integrate your changes
into 'gawk' and have them coexist 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.