home *** CD-ROM | disk | FTP | other *** search
/ Big Green CD 8 / BGCD_8_Dev.iso / NEXTSTEP / UNIX / Web / Servers / apache-1.2.4-MIHS / original-source / src / PORTING < prev    next >
Encoding:
Text File  |  1997-06-26  |  8.6 KB  |  258 lines
  1. The Semi-Official Guide to Porting Apache
  2.  
  3. -------------
  4. Introduction:
  5. -------------
  6. Apache has been ported to a wide variety of platforms, from multiple
  7. UNIX varients to OS/2. Nonetheless, there are most likely a few
  8. platforms out there that currently are not "officially" supported
  9. under Apache. Porting Apache to these platforms can be quite simple
  10. depending on the "genericness" of the OS. This doc will provide
  11. some basic guidelines to help the potential porter.
  12.  
  13. -------------
  14. Requirements:
  15. -------------
  16. One of the basic requirements for a potential Apache platform is
  17. a robust TCP/IP implementation. Just about any UNIX out there
  18. nowadays, even some ancient ones, have a TCP/IP stack that will
  19. work. In particular, the UNIX should provide for sockets and the
  20. basic controlling functions for them (like accept(), bind(), etc).
  21.  
  22. The source for Apache is written in ANSI-C, so an ANSI-C compiler
  23. is required. However, Apache does not use or require ANSI-only
  24. functions or options (eg: the "%n" parameter in the scanf()
  25. family); the source basically uses ANSI function prototyping but
  26. no other specific ANSIisms. Thus, an ANSI-to-K&R filter _may_
  27. work, although as far as I know it has not yet been tried. If you
  28. attempt this, let the Apache team know (mailto: new-httpd@hyperreal.com).
  29.  
  30. -------------------
  31. The Starting Point:
  32. -------------------
  33. The first thing to look at is the output of the ./helpers/GuessOS
  34. script. This is a simple script that attempts to determine the
  35. platform and OS you are running on. The output of this script
  36. is used by Configure to set some basic compilation parameters.
  37.  
  38. The output of ./helpers/GuessOS was designed to be GNUconfig.guess
  39. compatible (from GNU/autoconf). The format of the output string
  40. is:
  41.  
  42.    machine-vendor-OS
  43.  
  44. This string is returned to the main Configure script as the
  45. shell variable $PLAT. If Configure is not "aware" of that platform
  46. (or cannot correctly parse it), it will complain and die.
  47.  
  48. ----------------------
  49. Configure cannot Grok:
  50. ----------------------
  51. If this happens to you, then it means that Configure doesn't
  52. know how to configure and compile Apache for your OS. The first
  53. course of action is the easiest: Look in Configure and see if
  54. there are any OSs which is similar to yours.
  55.  
  56. For example, let's say that your OS is similar to HP-UX, but that
  57. GuessOS returns "foobar-intel-hubble". You would then edit
  58. Configure as follows:
  59.  
  60.     *-hp-hpux*|*-*-hubble)
  61.     OS='HP-UX'
  62.     CFLAGS="$CFLAGS -DHPUX"
  63.     ;;
  64.  
  65. The '|*-*-hubble' was added to the switch statement for HP-UX.
  66.  
  67. Another fix may involve editing the GuessOS helper script. Let's
  68. say, for example, that your system is SysV4-based, but that
  69. GuessOS does not return that info. You could then add a switch
  70. to the script that does something like:
  71.  
  72.     *WeirdSystem*)
  73.         echo "${MACHINE}-whatever-sysv4"; exit 0
  74.         ;;
  75.  
  76. In this case, we force GuessOS to return a string that includes
  77. the "sysv4" cookie for Configure to recognize.
  78.  
  79. Unfortunately, unless you are running a very generic BSD or SysV
  80. system, no "supported" OS will be close enough in all aspects to
  81. allow for a clear (and possibly workable) build of Apache. If this
  82. is the case, you will need to port Apache to your OS.
  83.  
  84. -------------------
  85. Porting for Apache:
  86. -------------------
  87. When all else fails, it's time to hack some code. The source itself
  88. is generic enough that most ports are incredibly easy. No matter
  89. what, however, there are 2 source files that need to be updated
  90. for the port:
  91.  
  92.    Configure
  93.    conf.h
  94.  
  95. Configure:
  96. ==========
  97. Configure concerns itself with determining the OS-type for the
  98. build and setting up a few Makefile variables for the build. The
  99. most important is 'OS' and 'CFLAGS'. For example, when Configure
  100. determines a build for A/UX, it runs the following lines:
  101.  
  102.   case "$PLAT" in
  103.     *-apple-aux3*)
  104.     OS='A/UX 3.1.x'
  105.     CFLAGS="$CFLAGS -DAUX -D_POSIX_SOURCE"
  106.     LIBS="$LIBS -lposix -lbsd"
  107.     LFLAGS="$LFLAGS -s"
  108.     DEF_WANTHSREGEX=no
  109.     ;;
  110.  
  111. The 'OS' variable is used to define the system Apache is being built
  112. for. You will also note that 'CFLAGS' defines "-DAUX". In this case,
  113. 'AUX' is a magic cookie used by the Apache code (mainly conf.h [see
  114. below]) to handle OS-specific code. Each code that has and requires
  115. such OS-specific code will require a unique "system cookie" defined
  116. in 'CFLAGS'. You will also note that Configure also goes ahead and
  117. predefines the LIBS and LFLAGS Makefile variables (DEF_WANTHSREGEX is
  118. explained below).
  119.  
  120. conf.h:
  121. =======
  122. The Apache code, specifically in conf.h, uses a variety of #defines to
  123. control how the code is compiled and what options are available for each
  124. supported OS. One of the hardest parts about the porting process is
  125. determining which of the following are applicable for your system and
  126. setup. This time using the example of AIX, we see:
  127.  
  128.    #elif defined(AIX)
  129.    #undef HAVE_GMTOFF
  130.    #undef NO_KILLPG
  131.    #undef NO_SETSID
  132.    #define HAVE_SYS_SELECT_H
  133.    #define JMP_BUF sigjmp_buf
  134.    #define HAVE_MMAP
  135.    typedef int rlim_t;
  136.  
  137. The above lines describe which functions,  capabilities and specifics
  138. are required for Apache to build and run under IBM AIX (the #undefs
  139. are not strictly required, but are a Good Idea anyway).
  140.  
  141. The following several lines provide a list and short description
  142. of these #defines. By correcting #defining the ones you need in conf.h
  143. (wrapped by the above mentioned "system cookie"), you can fine tune the
  144. build for your OS.
  145.  
  146. --
  147.  
  148.  NEED_*:
  149.   If the particular OS doesn't supply the specified function, we use the
  150.   Apache-supplied version (in util.c). 
  151.  
  152.     NEED_STRERROR:
  153.     NEED_STRDUP:
  154.     NEED_STRCASECMP:
  155.     NEED_STRNCASECMP:
  156.     NEED_INITGROUPS:
  157.     NEED_WAITPID:
  158.     NEED_STRERROR:
  159. --
  160.  
  161.  HAVE_*:
  162.   Does this OS have/support this capability?
  163.  
  164.     HAVE_GMTOFF:
  165.       Define if the OS's tm struct has the tm_gmtoff element
  166.  
  167.     HAVE_RESOURCE:
  168.       Define if the OS supports the getrlimit()/setrlimit() functions
  169.  
  170.     HAVE_MMAP:
  171.       Define if the OS supports the BSD mmap() call. This is used by various
  172.       OSs to allow the scoreboard file to be held in shared mmapped-memory
  173.       instead of a real file.
  174.  
  175.     HAVE_SHMGET:
  176.       Define if the OS has the SysV-based shmget() family of shared-memory
  177.       functions. Used to allow the scoreboard to live in a shared-memory
  178.       slot instead of a real file.
  179.  
  180.     HAVE_CRYPT_H:
  181.       Define if the OS has the <crypt.h> header file.
  182.  
  183.     HAVE_SYS_SELECT_H:
  184.       Define if the OS has the <sys/select.h> header file.
  185.  
  186.     HAVE_SYS_RESOURCE_H:
  187.       Define if the OS has and supports the getrlimit/setrlimit
  188.       family. Apache uses this to determine if RLIMIT_CPU|VMEM|DATA|RLIMIT
  189.       is found and used.
  190.  
  191.     HAVE_SNPRINTF:
  192.       Apache makes extensive use of the snprintf() function. many
  193.       platforms do not provide this function. If your platform
  194.       does provide it _and_ it's reliable (most are not) then
  195.       define this to use the OS version. Otherwise, Apache will
  196.       use it's own.
  197. --
  198.  
  199.  USE_*:
  200.   These #defines are used for functions and ability that aren't exactly
  201.   required but should be used.
  202.  
  203.      USE_FCNTL_SERIALIZED_ACCEPT:
  204.       Define if the OS requires a mutex "lock" around the socket accept()
  205.       call. Use fcntl() locking.
  206.  
  207.      USE_FLOCK_SERIALIZED_ACCEPT:
  208.       Define if the OS requires a mutex "lock" around the socket accept()
  209.       call. Use flock() locking (fcntl() is expensive on some OSs, esp.
  210.       when using NFS).
  211.  
  212.      USE_LONGJMP:
  213.       use the longjmp() call instead of siglongjmp()
  214.       (as well as setjmp() instead of sigsetjmp())
  215.  
  216. --
  217.  
  218.   NO_*:
  219.    These are defined if the OS does NOT have the specified function or if
  220.    we should not use it.
  221.  
  222.       NO_UNISTD_H:
  223.       NO_KILLPG:
  224.       NO_SETSID:
  225.       NO_USE_SIGACTION:
  226.        Do not use the sigaction() call, even if we have it.
  227.       NO_LINGCLOSE:
  228.        Do not use Apache's soft, "lingering" close feature to
  229.        terminate connections.
  230.       NO_SLACK:
  231.        Do not use the "slack" fd feature which requires a working fcntl
  232.        F_DUPFD.
  233. --
  234.  
  235.   MISC #DEFINES:
  236.    Various other #defines used in the code.
  237.  
  238.       JMP_BUF:
  239.        The variable-type for siglongjmp() or longjmp() call.
  240.  
  241.       MOVEBREAK:
  242.        Amount to move sbrk() breakpoint, if required, before attaching
  243.        shared-memory segment.
  244.  
  245. -----------
  246. Conclusion:
  247. -----------
  248. The above hints, and a good understanding of your OS and Apache, will
  249. go a LONG way in helping you get Apache built and running on your
  250. OS. If you have a port, PLEASE send Email to 'new-httpd@hyperreal.com'
  251. with the patches so that we may add them to the official version.
  252. If you hit a rough spot in the porting process, you can also try
  253. sending Email to that address as well and, if you are lucky, someone
  254. will respond. Another good source is the 'comp.infosystems.www.servers.unix'
  255. Usenet group as well.
  256.  
  257. Good luck and happy porting!
  258.