Mailing-List: contact dev-help@apr.apache.org; run by ezmlm
Date: Wed, 6 Dec 2000 15:33:37 -0800
From: Greg Stein <gstein@lyra.org>
To: dev@apr.apache.org
Subject: src/ directory (was: Re: apr-util comments)x
Message-ID: <20001206153337.D27235@lyra.org>
Mail-Followup-To: dev@apr.apache.org
References: <20001206113221.X27235@lyra.org>
 <Pine.LNX.4.21.0012061225380.18337-100000@koj.rkbloom.net>
Mime-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
User-Agent: Mutt/1.2i
In-Reply-To: <Pine.LNX.4.21.0012061225380.18337-100000@koj.rkbloom.net>;
 from rbb@covalent.net on Wed, Dec 06, 2000 at 12:30:33PM -0800

On Wed, Dec 06, 2000 at 12:30:33PM -0800, rbb@covalent.net wrote:
> 
> > Two reasons:
> > 
> > 1) we locate all the objects to add to the library using "find". it is
> >    easier to find them under "src/" rather than enumerating each source
> >    subdir. We can't use "." because that would pick up "test/".
> 
> This hasn't been an object in APR.  I would prefer to enumerate the
> subdirs to build, because it allows us to specify only those subdirs that
> we want to build.  We don't have this support in apr-utils yet, but it
> will be needed if this is project is going to be very useful outside of
> Apache.  Not everybody will want to use all of apr-util, and not everybody
> will want to require shared libraries.

Two comments:

1) Even if you build the whole thing, only the pieces used will be pulled
   into the application linking against APRUTIL. It is exactly this behavior
   that we're trying to avoid with the whole "exports.c" hack (we're trying
   to force a reference to everything in APR to ensure that it all gets
   linked).

   Therefore, I'm not sure of the utility of complicating apr-util with a
   mechanism to build just a subset.

2) Let's say that people here vote/agree to provide a mechanism to build a
   subset. Then everything is still quite simple: build a subset, and the
   find only finds the .lo files that were built. Nothing needs to change on
   the find. We only change the SUBDIRS line in src/Makefile.in

   I'm not entirely happy with that, however, because we might then miss
   those other subdirectories on "make" targets such as "clean". Last night,
   I axed the "test" target from SUBDIRS in httpd-2.0, but this morning
   realized that was wrong: now we don't clean out the test directory. I'm
   going to put that back and adjust the default targets in the test
   directory. I think a similar problem might exist in APRUTIL because
   "test" isn't in the top-level SUBDIRS line.

> > 2) to keep the top-level cleaner. we have eight groups of functionality in
> >    apr-util/src/. tossing those up a level would make that a bit more
> >    confusing. Currently, the top-level has: build/, docs/, include/, src/,
> >    and test/. Each is obvious in purpose.
> 
> Isn't this clean enough just because each of the directories has a very
> specific purpose?

Unfortunately, no. OtherBill just added a "misc" directory. If that were at
the top level, nothing about it would indicate that it contains source code
for the library. I worry similarly about the others. They are certainly
clearer (e.g. it would be hard to imagine "buckets" as being part of the
documentation :-), but it is *very* obvious that src/ contains the source
for the library.

> Does it buy us anything to have this repository look like APR and
> Apache?

Only to the extent that there is a common group of developers working on
them. Each package has its own set of requirements, so it should be
structured accordingly.

Apache is very complicated because it builds shared libraries, several
executables, has a dynamic/extendable layout for modules, etc.

APR is quite similar, though, so I would agree that making them similar
would be a Good Thing(tm). I believe the src/ structure is a bit clearer and
would apply to APR, too.

> Does SubVersion have a src directory?

Yes (called subversion/; the top level is where APR, Neon, tools, doc, etc
are located). Neon has a src/ directory containing its source.

> We just removed the src directory from Apache itself, why?

src/ contained more than source code. It also contained the build tools,
helper/support programs, test suites, and the different "classes" of source
code.

Today, httpd-2.0 has several top level directories:

  build     build tools/support
  docs      docs
  include   all include files
  modules   source: extension modules
  os        source: OS-specific code
  server    source: main server framework
  srclib    source: packaged/library-ized code
  support   support programs
  test      test programs

Before, everything but docs/ was all shoved into src/, so it didn't make a
lot of sense. Since Apache is so much more complex, dividing the source into
the different classes (modules, OS, server, and the packages) keeps a solid
clarification. Throwing in an extra src/ level wouldn't be all that
advantagious because dropping from four source dirs to one isn't a big deal.

With APR and APRUTIL having 15 and 8 subpackages (respectively), the use of
a src/ directory can be quite helpful.

> do those arguments apply to apr-util as well?

I don't believe so; my thinking is above.

> I have no answers, but those are the questions that I am left wondering
> about, so I wanted to make sure that they were brought out into the open
> so that we had answers when others asked them.

All good questions! And it helps by prodding me to explain the thought
process, as I was the one to initial propose/outline the structure in my
email last week.

I'll include this information in a "project structure" document today. That
will cover info for developers: config/build, layout, etc.

Cheers,
-g

-- 
Greg Stein, http://www.lyra.org/