gawk: New Ports

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