Message-ID: <38553553.94A7CA5A@crosstor.com>
Date: Mon, 13 Dec 1999 11:05:07 -0700
From: Tom Harrington <tph@crosstor.com>
Organization: CrosStor Software, Inc.
Mime-Version: 1.0
To: new-httpd@apache.org
Subject: Re: apache design doc...
References: <384EBA63.9E2E74EF@us.ibm.com>
Content-Type: text/plain; charset=us-ascii
Content-Transfer-Encoding: 7bit
Sender: new-httpd-owner@apache.org
Precedence: bulk
Reply-To: new-httpd@apache.org
Status: O

Ovies Brabson wrote:
> 
> > Hi,
> > Sorry if this is OT..but I thought this might be the best list to ask...
> >
> > Where can I find a document that explains the design of httpd.?? I know I
> > should be looking at the source but any doc that willl ease the task will be
> > really appreciated..
> >
> > Thx,
> > Arni
> >
> I recently found a book that might be what you are looking for.  "Apache
> Server, Commentary, In-Depth Code Annotation" by Greg Holden, Nicholas
> Wells, Matthew Keller.  The first half of the book seems to be a print
> out of the apache source code and the second half of the book describes
> what pieces fit together and what they do and refers back to the source
> code.  It may what you are looking for if you are trying to learn the
> code.

Unfortunately the commentary in this book is not nearly as useful as I
had hoped.  It can be helpful in understanding what a specific line does,
in those cases where there's actually a comment for the line in question.
But often there's no comments at all.  For example, standalone_main is
nearly 300 lines long in their printout, yet merits only about a dozen
very short comments that mostly fail to illuminate.  The problem with
the comments is mostly a "can't see the forest for the trees" problem--
describing a single line doesn't help much if you don't understand the
context in which it exists, and the context is generally not covered
in this book.  And it's not even complete-- the "main" portion of the
Apache source has 17 source files, but only 3 are covered by this book.
On the whole the primary advantage of the book is that it's marginally
more convenient than printing your own copy of the source code.

A better reference, IMHO, is _Writing_Apache_Modules_, by Lincoln Stein
and Doug MacEachern (pub. by O'Reilly).  It doesn't get down into the 
details in the same way that _Apache_Server_Commentary_ does, but it
does give a better overview of just what the heck is going on in all
that code.  It also has some gaps in its coverage, but then it's not
really intended as an "in-depth code annotation".  Chapter 3, "The Apache
Module Architecture and API", and chapters 10 and 11, "C API Reference
Guide" parts 1 and 2, are far more useful than the server commentary
book.  The book's web site, with source code examples and a few free
chapters, is at <http://www.modperl.com/>.

Also make sure to check out the Apache API Dictionary, at
<http://dev.apache.org/apidoc/>

Ultimately, though, the best solution is to dig into the source code
yourself.  It's somewhat tedious at first, but it's the only way.  After
a few weeks' work I'm just finally beginning to grok it in fullness.

-- 
Tom Harrington
CrosStor Software, Inc.
tph@crosstor.com