httpd-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Paul Sutton <...@hyperreal.org>
Subject cvs commit: apachen/htdocs/manual sourcereorg.html
Date Mon, 11 Aug 1997 10:07:49 GMT
pcs         97/08/11 03:07:49

  Added:       htdocs/manual sourcereorg.html
  Log:
  New configure and re-organised sources documentation
  
  Revision  Changes    Path
  1.1                  apachen/htdocs/manual/sourcereorg.html
  
  Index: sourcereorg.html
  ===================================================================
  <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
  <HTML>
  <HEAD>
  <TITLE>Source Re-organisation</TITLE>
  </HEAD>
  
  <!-- Background white, links blue (unvisited), navy (visited), red (active) -->
  <BODY
   BGCOLOR="#FFFFFF"
   TEXT="#000000"
   LINK="#0000FF"
   VLINK="#000080"
   ALINK="#FF0000"
  >
  <!--#include virtual="header.html" -->
  <h1 ALIGN="CENTER">Source Re-organisation</h1>
  
  As of 1.3, the Apache source directories have been re-organisated. This
  re-organisation is designed to simplify the directory structure,
  make it easier to add additional modules, and to give module authors
  a way of specifying compile time options or distribute binary
  modules.
  
  <h2>Summary of Changes</h2>
  
  The source directory changes are:
  <ul>
   <li>The non-module source files have moved from <CODE>src</CODE> into
       <CODE>src/core</CODE>
   </li>
   <li>The module source files previously in <CODE>src</CODE> have moved
       to <CODE>src/modules/standard</CODE>
   </li>
   <li>The <CODE>support</CODE> directory is now in <CODE>src/support</CODE>
   </li>
  </ul>
  
  In addition, the following enhancements have been made:
  
  <ul>
   <li>OS abstractions can be added in the <CODE>src/os</CODE> directory.
       Currently this contains information for unix, OS/2 and Windows 32
       platforms.
   </li>
   <li><CODE>Configuration</CODE> syntax has been simplified for adding
new
       modules. Users no longer need to enter the module's structure name.
       In addition, new modules can be located anywhere on the
       file system, or typically in new or existing directories under
       <CODE>src/modules</CODE>.
   </li>
   <li>Module authors can give simpler instructions for adding their modules
       to Apache compilation. They can also now provide compile time information
       required by <CODE>Configure</CODE>, such as additional libraries
       required.
   </li>
   <li>Module authors can distribute pre-compiled (.a or .o) versions of their
       modules if required, along with a "module definition file" which
       contains the information required by <CODE>Configure</CODE>.
   </li>
  </ul>
  
  <h2>Adding Modules</h2>
  
  Modules are added to Apache by adding a reference tp them in
  <CODE>src/Configuration</CODE> then running <CODE>Configure</CODE>
and
  <CODE>make</CODE>. In earlier version of Apache before 1.3, the
  line added to Configuration looked like this:
  
  <PRE>
    Module    mod_status.o    status_module
  </PRE>
  
  From 1.3 onwards, the <CODE>AddModule</CODE> line should be used
  instead, and typically looks like this:
  
  <PRE>
    AddModule    modules/standard/mod_status.c
  </PRE>
  
  The argument to AddModule is the path, relative to <CODE>src</CODE>, to
  the module file's source or object file.
  
  <h2>New Facilities for Module Authors</h2>
  
  In previous releases of Apache, new modules were added to the
  <CODE>src</CODE> directory, and if the module required any additional
  compilation options (such as libaries) they would have to be added
  to <CODE>Configuration</CODE>. Also the user would have to be
  told the module's structure name to add on the Module line
  of <CODE>Configuration</CODE>.
  
  <P>
  
  From Apache 1.3 onwards, module authors can make use of these new features:
  
  <ul>
   <li>Simplified <CODE>Configuration</CODE> command AddModule which only
       requires a path to the module source or object file
   </li>
   <li>If the module requires compile time options (such as extra
       libraries) these can be specified in the module file source
       or an external "module definition file". 
   </li>
   <li>If a module is distributed as binary (.o or .a) then an external
       "module definition file" can also be distributed which gives
       the information Configure needs to add the module, such as extra
       libraries and the module's structure name.
   <li>Module can be installed anyway on the file system, although a directory
       under <CODE>src/modules</CODE> is recommended.
   </li>
   <li>If the module is in its own directory, Apache can automatically
       create a Makefile to build the module given a file containing
       the module's dependencies.
   </li>
  </ul>
  
  The rest of this document shows how to package modules for Apache 1.3
  and later and what to tell end-users of the module.
  
  <h3>Building a simple source distibution</h3>
  
  Consider a simple add-on module, distributed as a single file. For
  example, say it is called mod_demo.c. The archive for this module
  should consist of two files, in a suitable directory name. For
  example:
  
  <ul>
   <li>mod_demo/mod_demo.c
   <li>mod_demo/Makefile.tmpl
  </ul>
  
  (Of course end-user instructions, README's etc can also be supplied in
  the archive). The end user should be told to extract this archive in
  the <CODE>src/modules</CODE> directory of their Apache source
  tree. This will create a new directory
  <CODE>src/modules/mod_demo</CODE>. Then they need to add the following
  line to the <CODE>Configuration</CODE> file:
  
  <pre>
    AddModule  modules/mod_demo/mod_demo
  </pre>
  
  then run <CODE>Configure</CODE> and <CODE>make</CODE> as normal.
  
  <P>
  
  The <CODE>mod_demo/Makefile.tmpl</CODE> should contain the dependencies
  of the module source. For example, a simple module which just interfaces to
  some standard Apache module API functions might look this this:
  
  <PRE>
    mod_demo.o: mod_demo.c $(INCDIR)/httpd.h $(INCDIR)/http_protocol.h
  </PRE>
  
  When the user runs <CODE>Configure</CODE> Apache will create a full
  makefile to build this module. If this module also requires
  some additional built-time options to be given, such as libaries,
  see the next section.
  <P>
  
  If the module also comes with header files, these can be added to the
  archive. If the module consists of multiple source files it can be
  built into a library file using a supplied makefile. In this case,
  distribute the makefile as <CODE>mod_demo/Makefile</CODE> and <b>do
  not</b> include a <CODE>mod_demo/Makefile.tmpl</CODE>. If
  <CODE>Configure</CODE> see a <CODE>Makefile.tmpl</CODE> it assmes
it
  is safe to overwrite any existing<CODE>Makefile</CODE>.
  
  <P> 
  
  See the Apache <CODE>src/modules/standard</CODE> for an example of a
  module directory where the makeifle is create automatically from a
  Makefile.tmpl file (note also that this directory also shows how to
  distributed multiple modules in a single directory). See
  <CODE>src/modules/proxy</CODE> and <CODE>src/modules/example</CODE>
  for examples of modules build using custom makefiles (to build a
  library and an object file, respectively).
  
  <h3>Adding Compile time Information</h3>
  
  Apache source files (or module definition files, see below) can
  contain information used by <CODE>Configure</CODE> to add compile-time
  options such as additional libraries. For example, if mod_demo in the
  example above also requires that Apache be linked against a DBM
  library, then the following text could be inserted into the mod_demo.c
  source:
  
  <PRE>
  /*
   * Module definition information - the part between the -START and -END
   * lines below is used by Configure. This could be stored in a separate
   * instead.
   *
   * MODULE-DEFINITION-START
   * Name: demo_module
   * ConfigStart
      LIBS="$LIBS $DBM_LIB"
      if [ "X$DBM_LIB" != "X" ]; then
          echo " + using $DBM_LIB for mod_demo"
      fi
   * ConfigEnd
   * MODULE-DEFINITION-END
   */
  </PRE>
  
  Note that this is contained inside a C language comment to hide it
  from the compiler. Anything between the lines which contains
  <CODE>MODULE-DEFINITION-START</CODE> and
  <CODE>MODULE-DEFINITION-END</CODE> is used by <CODE>Configure</CODE>.
  The <CODE>Name:</CODE> line gives the module's structure name. This is
  not really necessary in this case since if not present
  <CODE>Configure</CODE> will guess at a name based on the filename
  (e.g. given "mod_demo" it will remove the leading "mod_" and append
  "_module" to get a structure name. This works with all modules
  distributed with Apache).
  
  <P>
  
  The lines between <CODE>ConfigStart</CODE> and <CODE>ConfigEnd</CODE>
  as executed by <CODE>Configure</CODE> and can be used to add
  compile-time options and libraries. In this case it adds the DBM
  library (from $DBM_LIB) to the standard compilation libraries ($LIB)
  and displays a message.
  
  <P>
  
  See the default distribution's mod_auth_dbm.c for an example of
  an embedded module definition.
  
  <h3>Module Definition Information for Binary Distribitions</h3>
  
  If the module is to be distributed as binary (object or libary) rather
  than source, it is not possible to add the module definition
  information to the source file. In this case it can be placed in a
  separate file which has the same base name as the object or libary
  file, but with a <CODE>.module</CODE> extension. So, for example, if
  the distributed module object file is mod_demo.o, the module
  definition file should be called mod_demo.module. It contains the same
  information as above, but does not need to be inside a C comment or
  delimited with <CODE>MODULE-DEFINITION-START</CODE> etc. For example:
  
  <PRE>
  Name: demo_module
  ConfigStart
   LIBS="$LIBS $DBM_LIB"
   if [ "X$DBM_LIB" != "X" ]; then
       echo " + using $DBM_LIB for mod_demo"
   fi
  ConfigEnd
  </PRE>
  
  See the default distribution's mod_auth_db.module for an example of
  an separate module definition file.
  
  <!--#include virtual="footer.html" -->
  </BODY>
  </HTML>
  
  
  

Mime
View raw message