samien
/
boost
зеркало из https://github.com/boostorg/boost


			
				
					
						
						
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859
							<html>

<head>
<meta http-equiv="Content-Type"
content="text/html; charset=iso-8859-1">
<meta name="Template"
content="C:\PROGRAM FILES\MICROSOFT OFFICE\OFFICE\html.dot">
<meta name="GENERATOR" content="Microsoft FrontPage Express 2.0">
<title></title>
</head>

<body bgcolor="#FFFFFF" link="#0000FF" vlink="#800080">

<h2 align="center">A Proposal for the Boost Directory Structure</h2>

<p align="center">By John Maddock.</p>

<p>The following proposal consists of three sections: A list of
requirements and objectives that the chosen structure must meet,
a set of tools to facilitate working with boost, and an actual
proposal for a structure that meets those requirements. In the
past I have argued vociferously for a &quot;do as little as
possible&quot; approach, however I have somewhat surprised myself
by coming out in favour of a radical reorganisation here. In many
ways though, the proposed directory structure is less important
than its ability to meet the requirements listed below, nor is it
the only structure that could arguably meet these requirements (especially
as some requirements are contradictory). Finally a couple of
caveats: All opinions expressed herein are my own; all ideas
expressed herein belong to over people (especially the good ones!).
Where possible credits are given, but my memory is far from
infallible so speak up if you've been missed out.</p>

<h2 align="center">Requirements</h2>

<h3>Consistency</h3>

<blockquote>
    <p><b>Comment</b>: this should speak for itself.</p>
</blockquote>

<h3>Discoverability</h3>

<p>That is a casual user browsing the directory structure should
be able to immediately tell what belongs where.</p>

<blockquote>
    <p><b>Rationale</b>: some users read the documentation,
    others wander around aimlessly saying: &quot;I wonder what's
    in here?&quot;, speak up if you recognise anyone!</p>
    <p><b>Rationale</b>: automated tools should be able to glean
    most of the information they need direct from the directory
    structure.</p>
    <p><b>Comment</b>: This is probably the most important
    requirement and guides the choice of many others.</p>
</blockquote>

<h3>Boost is a single library</h3>

<blockquote>
    <p>From an end users perspective boost should appear to be a
    single library, with a single integrated build process etc.</p>
    <p><b>Rationale</b>: This makes life much more comfortable
    for end uses.</p>
</blockquote>

<h3>Boost is a collection of separate libraries</h3>

<blockquote>
    <p><b>Rationale</b>: some libraries have an existence of
    their own outside of boost, this should be able to continue.</p>
    <p><b>Rationale</b>: different developers maintain individual
    boost libraries.</p>
    <p><b>Rationale</b>: as boost grows it may be necessary to
    split the library into multiple zip file downloads, each
    download should encapsulate one domain, and provide all the
    files necessary for that domain (that may mean that some
    files appear in more than one zip file).</p>
    <p><b>Rationale</b>: some users will want to split off (and
    maybe freeze) those parts of boost that are being used by a
    particular project. These sub-libraries can then be checked
    into the users own version control system (for example into a
    local cvs repository as a vendor branch), and maintained
    alongside the users own source for that project.</p>
    <p><b>Implication:</b> that there exists some mechanism for
    locating and separating off all the files associated with a
    particular boost library, this should also take into account
    dependencies (both for headers and for binary dependencies).</p>
</blockquote>

<h3>Individual boost libraries can be checked out from the cvs
repository</h3>

<blockquote>
    <p>For example &quot;<code>cvs checkout regex</code>&quot;
    would check out the regex library alone.</p>
    <p><b>Rationale</b>: This makes maintenance much easier
    especially when working with cvs-branches.</p>
    <p><b>Implication</b>: we could isolate libraries into
    separate directories, however that's only a partial solution
    which takes no account of library dependencies (something
    that's likely to become increasingly important). A better
    solution is to use cvs module-aliases: as a test case I've
    defined the regex library as a module-alias (this seems to
    work very well). In this case I had to specify dependencies
    by hand (an error prone process), much better would be a tool
    that produced a list of library aliases to insert directly
    into the cvs modules file.</p>
</blockquote>

<h3>Boost libraries can have dependencies to other libraries</h3>

<blockquote>
    <p>There are three kinds of dependency possible:</p>
    <ol>
        <li>Libraries may depend upon the headers from other
            boost libraries; these dependencies can be worked out
            automatically.</li>
        <li>Libraries may depend upon binaries from other boost
            libraries; these dependencies can be worked out
            automatically (hint: if library X depends upon header
            H, and header H is from a library Y which has
            mandatory source code associated with it, then there
            is a binary dependency from X to Y).</li>
        <li>Some domain specific libraries may depend upon third
            party libraries (the python library for example).
            These dependencies can not be deduced, and will
            require meta-data to describe.</li>
    </ol>
    <p><b>Rationale: </b>these dependencies already exist in the
    boost library.</p>
</blockquote>

<h3>Usable &quot;as is&quot;</h3>

<blockquote>
    <p>That is the library should be usable directly from the
    checked out cvs tree, or the extracted zip file, without a
    mandatory install process.</p>
    <p><b>Rationale:</b> For single user installations it is
    sufficient and often easier to work directly from the zip/cvs
    structure.</p>
    <p><b>Rationale: </b>For &quot;occasional developers&quot;
    this simplifies their ability to port/debug parts of the
    library, and then submit patches based on changes made,
    without having to get involved with &quot;wrapper compilers&quot;
    and other tools that have been suggested, which may or may
    not function on their platform with their toolset.</p>
    <p><b>Implication:</b> that all header files are located
    together, and not split between multiple library paths.</p>
    <p><b>Comments:</b> during the recent discussion it was
    suggested splitting the header files into separate
    directories under &quot;boost-root/src/libname/boost&quot;,
    however this involves specifying a large number of -I options
    on the command line in order to be able to use boost direct
    from the cvs tree. One suggested workaround was to use a
    wrapper-compiler to pass the long list of includes to the
    compiler semi-automatically. However some compilers are
    integrated with their respective IDE's (this would make boost
    almost impossible to use from that IDE), other platforms/compilers
    have a restricted command line length (mingw32 is a
    particular culprit), the command line in such cases could
    easily become longer than the maximum permitted.</p>
</blockquote>

<h3>Header include mechanism reflects library name</h3>

<blockquote>
    <p>We currently use:</p>
    <p><code>#include &lt;boost/something.hpp&gt;</code></p>
    <p>which immediately informs a casual browser of the code
    that something.hpp is a part of the boost library and
    separates it from:</p>
    <p><code>#include &lt;rw/thread.h&gt; // this is Rogue Wave
    library</code></p>
    <p><b>Rationale</b>: This has worked well up to now and
    should be continued.</p>
    <p><b>Implication</b>: The boost-root/boost/ directory must
    continue to exist (although there are possible arguments in
    favour of making it boost-root/include/boost).</p>
</blockquote>

<h3>Libraries can have &quot;non-end user&quot; header files.</h3>

<blockquote>
    <p>There are several kinds of header that come into this
    category:</p>
    <blockquote>
        <p><b>Power user headers</b>: headers that should only be
        used by experts.</p>
        <p><b>Headers for library reuse</b>: these headers can be
        used by other boost libraries, but should not be used by
        end users.</p>
        <p><b>Domain specific headers</b>: large domain specific
        libraries may have a large number of headers that should
        not make it into the main boost-root/boost/ header
        directory (graph for example).</p>
        <p><b>Implementation headers</b>: libraries may have
        headers that contain implementation code, these headers
        should never be included by anything except other headers
        <i>in this library</i>.</p>
    </blockquote>
    <p><b>Implication: </b>the main header directory may contain
    sub-directories as follows:</p>
    <blockquote>
        <p>boost-root/boost/library-name/ for all non-end user
        headers, including domain specific headers.</p>
        <p>boost-root/boost/library-name/detail/ for all
        implementation detail headers.</p>
    </blockquote>
</blockquote>

<h3>Libraries can be combined into domains</h3>

<blockquote>
    <p>For example we may want to combine multiple math-related
    libraries into a single &quot;numeric&quot; domain. In this
    case each library in the domain would have it's own directory
    under the domain name directory - for example headers for the
    rational library may end up in boost-root/boost/numeric/rational/.</p>
    <p><b>Rationale</b>: the aim here is to prevent the number of
    top level libraries growing to an unmanageable number, and to
    allow a logical group of libraries to be accessed with a
    single name (for cvs checkouts or for building part of boost).</p>
</blockquote>

<h3>Root directory name reflects boost version</h3>

<blockquote>
    <p>That is the name of the root directory in the zip file
    reflects the boost version number &quot;boost_1_1_9/&quot;
    etc, subsequent directories - like the boost header file
    directory - then split off from this.</p>
    <p><b>Rationale: </b>Allows developers to have multiple
    versions coexisting on their machine within a single
    directory structure, developers can switch between versions
    with a by changing their compilers include and library search
    paths only.</p>
</blockquote>

<h3>Consistent handling of development code</h3>

<blockquote>
    <p>If there exists development or non-reviewed code in the
    cvs tree then it should not interfere with release code or
    exist in the same directory tree as the release code. Nor
    should development code appear in zip files.</p>
    <p><b>Rationale</b>: developers will typically work with
    either the latest release code, or the latest development
    code, they should be able to switch between them fairly
    easily.</p>
    <p><b>Rationale</b>: end users don't generally need to see
    development code, it unnecessarily duplicates what's already
    in the library and may lead to confusion as to what's release
    code and what's still in development.</p>
    <p><b>Implication</b>: There are a couple of ways of dealing
    with this.</p>
    <blockquote>
        <p><b>Method 1</b>: provide a subdirectory &quot;<code>boost-root/development/library-name/</code>&quot;
        that internally mirrors the directory structure of <code>boost-root/</code>,
        to contain development code for library &quot;library-name&quot;.
        This has the advantage of being easy to work with, but
        requires setting multiple include and library search
        paths, it also complicates multiple development versions
        of the same library (for example multiple ports to new
        platforms may proceed in parallel).</p>
        <p><b>Method 2</b>: provide a separate top-level CVS
        directory for development code, development code could
        then be checked out with &quot;<code>cvs checkout
        development&quot;</code> instead of &quot;<code>cvs
        checkout boost&quot;</code>, otherwise this method is the
        same as Method 1 above, and has the same pros and cons.</p>
        <p><b>Method 3</b>: use a cvs branch for development work.
        This allows multiple development efforts to proceed in
        parallel, but may be harder to work with and keep in
        synch with the main branch.</p>
    </blockquote>
    <p>Ideally<b> </b>I see no reason why either method 1 or 2
    can't coexist with method 3, depending which method is easier
    for the task in hand. Personally I prefer (2) to (1), but
    that's just personal preference.</p>
</blockquote>

<h3>Mandatory Source code is centrally located</h3>

<blockquote>
    <p>That is that there is some central directory (let's call
    it boost-root/src/) that contains all mandatory source files
    for a particular library in its sub-directories: boost-root/src/library1/,
    boost-root/src/library2/ etc.</p>
    <p><b>Rationale: </b>This ensures that the source is easily
    discoverable by the user; for example if a user suspects that
    there may be a bug in library X, and decides to try and debug
    the problem, they may want to add all the source code for
    library X directly to their project to facilitate debugging.
    (I appreciate that the build process <i>may</i> provide
    debugging versions of the library, but it is still often
    easier to add the source direct to the IDE's project,
    depending upon how well the IDE handles debugging of external
    libraries).</p>
    <p><b>Rationale: </b>some IDE's have search paths for source
    files as well as headers etc, this structure shortens the
    paths to mandatory source files (this is more of a feature
    request than a requirement).</p>
</blockquote>

<h3>Directories containing documentation contain an index.html
file, and nothing but documentation</h3>

<blockquote>
    <p><b>Rationale</b>: Some file browsers (KFM for example)
    will automatically display documentation when they see either
    index.htm or index.html in the current directory. Any other
    files located in that directory effectively become &quot;hidden&quot;
    from the user. Whether this is an annoyance or a great
    feature depends upon your point of view. Separating
    documentation into it's own sub-directory solves this problem
    (it happens to make installation of the documentation easier
    as well).</p>
    <p><b>Footnote</b>: actually KFM is usually quite intelligent
    about displaying documentation, however it does sometimes get
    it wrong.</p>
</blockquote>

<h3>Boost supports an integrated build process</h3>

<blockquote>
    <p><b>Rationale</b>: Currently most boost libraries are
    &quot;headers only&quot;, those that are not have their own
    build processes or none at all. This is confusing for the end
    user, especially as boost is likely to get much larger.</p>
</blockquote>

<h3>Boost supports building of separate sub-libraries</h3>

<blockquote>
    <p><b>Rationale</b>: Building boost as a single monolithic
    library is likely to put end users off - especially as boost
    grows in size - few users will use all of boost in a single
    project (even if they use all of it at some time or another).</p>
    <p><b>Implication</b>: Build each boost library separately
    using a consistent naming scheme incorporating the library
    name and the compiler name: libboost_timer_gcc.so, libboost_regex_gcc.so,
    lib_boost_thread_gcc.so etc. Provide a monolithic version of
    the library as an option for those that want a simple life (this
    is mainly more appropriate for static libraries where unused
    library code doesn't make it into the executable).</p>
</blockquote>

<h3>Boost supports multiple compiler build options.</h3>

<blockquote>
    <p><b>Rationale</b>: some compilers ship with multiple run-time
    libraries. For example the Borland C++ compiler comes with 6
    different runtimes, any third party libraries must be built
    with the same runtime options as the executable to which it
    will be linked, failure to observe this rule leads to hard to
    track down runtime crashes.</p>
    <p><b>Implication</b>: boost libraries must each be built
    multiple times with the same runtime variants that the
    compiler ships with. As before name mangling separates the
    variants: </p>
</blockquote>

<pre>           boost_regex_bc55_cw.lib
           boost_regex_bc55_cwi.lib
           boost_regex_bc55_cwi.dll
           boost_regex_bc55_cwm.lib
           boost_regex_bc55_cwmi.lib
           boost_regex_bc55_cwmi.dll
           boost_regex_bc55_cp.lib
           boost_regex_bc55_cpi.lib
           boost_regex_bc55_cpi.dll</pre>

<blockquote>
    <p>(for non-Borland users the suffixes chosen here reflect
    the names of Borland's own runtime libraries).</p>
</blockquote>

<h3>Boost's build system uses the minimal amount of meta-data
required.</h3>

<blockquote>
    <p><b>Rationale</b>: some meta-data is likely to be required,
    but to reduce maintenance requirements this should be as
    small as possible. Generally speaking the smaller the meta-data
    requirement the more likely it is that the build system is in
    synch with the library. The worst case would be hand-crafted
    makefiles (hard to maintain), the best case no meta-data at
    all; for example the directory structure describes the
    library well enough that makefiles (or their equivalent) can
    be automatically generated.</p>
</blockquote>

<h3>Boost supports installation to a central location</h3>

<blockquote>
    <p><b>Rationale</b>: most unix variants more or less require
    an install step before using third party libraries, this also
    allows network installs (for multiple compilers and/or
    platforms if required), from a single source tree.</p>
</blockquote>

<blockquote>
    <p><b>Implication</b>: Keep the boost directory structure as
    close as possible to the install structure to simplify the
    installation process (strictly speaking this is not an
    absolute requirement, but cross-platform installation is hard
    enough with making it any harder than it needs to be). The
    easiest way is to keep the documentation/header/build trees
    separate.</p>
</blockquote>

<h3>The boost directory structure should be &quot;optimally
branched&quot;</h3>

<blockquote>
    <p>This is a nebulous requirement that is based as much on
    personal preference as anything else.</p>
    <p><b>Rationale</b>: the directory structure is more &quot;discoverable&quot;
    if it branches consistently - that is with no directories
    with a massive number of entries.</p>
    <p><b>Implication</b>: where appropriate combine related
    libraries into domains.</p>
    <p><b>Implication</b>: avoid directories with a single sub-directory
    entry (redundancy).</p>
</blockquote>

<h2 align="center">Proposed tools to aid boost management (build
system)</h2>

<p>While writing the requirements above one theme kept
reoccurring; that of interdependency of boost libraries, and the
need for an automated tool to deal with this problem. In fact
from a code-reuse point of view, we need a library that describes
the boost library and determines library dependencies that can
then be reused in multiple tools. In my view the gains in ease of
management, and automatic generation of makefiles etc, means that
these tools should be developed regardless of the actual
directory structure chosen (although the code will probably be
dependent upon the directory structure chosen).</p>

<h3>Dependency library</h3>

<blockquote>
    <p>This library would define two types:</p>
    <p><b>Library</b>: defines the files that belong to a
    particular library, plus header file dependencies and a list
    of binary dependencies to other boost libraries.</p>
    <p><b>Libraries</b>: a collection of Library objects, also
    maintains a database of which header belongs to which library
    (used to calculate binary dependencies).</p>
    <p>As far as is possible, these types should be able to load
    themselves directly from the boost directory structure, with
    only a minimal amount of meta-data used to describe the
    unusual cases.</p>
</blockquote>

<h3>Paths library</h3>

<p>In order for the dependency library to do it's job it is
necessary to iterate over a directory structure, join and split
path names, and convert path names to/from a platform specific
format. For example to insert relative-paths into makefiles which
may be used on platforms other than the one on which the makefile
is generated. Some, but by no means all, of this functionality is
already covered by Dietmar Kühl's dir_it library.</p>

<h3>Automatic alias generation</h3>

<p>This is a short program that just iterates through a Libraries
collection and prints out the dependencies, so that the result
can be cut and pasted into the cvs modules file.</p>

<h3>Boost distiller</h3>

<p>This is almost the same program as the alias generator, but
copies files to a new location instead of printing them out. Used
to &quot;distil&quot; out a subset of the boost library (including
dependencies). This can be used to: split boost into multiple (domain
specific) zip files for easier download, or split out that subset
of boost that is being used by a particular project (for
integration with the project without getting the whole of boost).</p>

<h3>Build system</h3>

<p>By combining the description of the boost library contained in
a Libraries object with a description of the compiler/platform in
use, it is possible to do one of two things: directly build the
library, or output compiler/platform specific makefiles for
distribution with boost. For brevity I'm going to skip over a
description of this here - my pencil and paper sketch has a list
of around 14 points of variation between compilers, and another
list of 7 options for each compiler configuration (release, debug,
static, dynamic etc). Probably even this fairly long list is not
complete.</p>

<p>I'm assuming that the build system will probably output
makefiles in the first instance; apart from anything else, most
compilers come with some kind of make, using this avoids the need
for the end user to have to build/install any tools that do not
ship with their compiler. Here I'm assuming that the boost
library maintainers periodically generate the makefiles, and then
ship them with the library.</p>

<h2 align="center">The directory structure</h2>

<table border="0" cellpadding="7" cellspacing="1" width="100%">
    <tr>
        <td valign="top" width="6%">&nbsp;</td>
        <td valign="top" width="44%" bgcolor="#008080">Directory</td>
        <td valign="top" width="43%" bgcolor="#008080">Description</td>
        <td valign="top" width="7%">&nbsp;</td>
    </tr>
    <tr>
        <td valign="top" width="6%">&nbsp;</td>
        <td valign="top" width="44%" bgcolor="#C0C0C0">Boost-root/boost/</td>
        <td valign="top" width="43%" bgcolor="#C0C0C0">All entry
        point boost headers, mainly these should be called &quot;library-name.hpp&quot;</td>
        <td valign="top" width="7%">&nbsp;</td>
    </tr>
    <tr>
        <td valign="top" width="6%">&nbsp;</td>
        <td valign="top" width="44%" bgcolor="#C0C0C0">Boost-root/boost/library-name/</td>
        <td valign="top" width="43%" bgcolor="#C0C0C0">All domain
        specific headers, all &quot;expert-user&quot; non-entry
        point headers.</td>
        <td valign="top" width="7%">&nbsp;</td>
    </tr>
    <tr>
        <td valign="top" width="6%">&nbsp;</td>
        <td valign="top" width="44%" bgcolor="#C0C0C0">Boost-root/boost/library-name/detail/</td>
        <td valign="top" width="43%" bgcolor="#C0C0C0">All
        implementation private headers.</td>
        <td valign="top" width="7%">&nbsp;</td>
    </tr>
    <tr>
        <td valign="top" width="6%">&nbsp;</td>
        <td valign="top" width="44%" bgcolor="#C0C0C0">Boost-root/src/library-name/</td>
        <td valign="top" width="43%" bgcolor="#C0C0C0">All
        mandatory source files.</td>
        <td valign="top" width="7%">&nbsp;</td>
    </tr>
    <tr>
        <td valign="top" width="6%">&nbsp;</td>
        <td valign="top" width="44%" bgcolor="#C0C0C0">Boost-root/src/library-name/config/</td>
        <td valign="top" width="43%" bgcolor="#C0C0C0">Any
        private configuration code (for example autoconf scripts),
        if these grow then we could move to an integrated
        configure system in Boost-root/config/ but that isn't
        currently necessary.</td>
        <td valign="top" width="7%">&nbsp;</td>
    </tr>
    <tr>
        <td valign="top" width="6%">&nbsp;</td>
        <td valign="top" width="44%" bgcolor="#C0C0C0">Boost-root/src/library-name/build/</td>
        <td valign="top" width="43%" bgcolor="#C0C0C0">Temporary
        location for private build systems, until the boost-wide
        integrated build comes on line.</td>
        <td valign="top" width="7%">&nbsp;</td>
    </tr>
    <tr>
        <td valign="top" width="6%">&nbsp;</td>
        <td valign="top" width="44%" bgcolor="#C0C0C0">Boost-root/docs/</td>
        <td valign="top" width="43%" bgcolor="#C0C0C0">All common
        documentation.</td>
        <td valign="top" width="7%">&nbsp;</td>
    </tr>
    <tr>
        <td valign="top" width="6%">&nbsp;</td>
        <td valign="top" width="44%" bgcolor="#C0C0C0">Boost-root/docs/library-name/</td>
        <td valign="top" width="43%" bgcolor="#C0C0C0">All
        documentation for &quot;library-name&quot;; must include
        an index.htm file.</td>
        <td valign="top" width="7%">&nbsp;</td>
    </tr>
    <tr>
        <td>&nbsp;</td>
        <td valign="top" bgcolor="#C0C0C0">Boost-root/licence</td>
        <td bgcolor="#C0C0C0">A &quot;generic&quot; boost licence
        that describes the minimal guarantees made by all boost
        libraries (free for commercial use etc), with sub-directories
        for those boost libraries that have their own licences (currently
        just regex and graph, but this number is likely to grow).</td>
        <td>&nbsp;</td>
    </tr>
    <tr>
        <td valign="top" width="6%">&nbsp;</td>
        <td valign="top" width="44%" bgcolor="#C0C0C0">Boost-root/tests/library-name/</td>
        <td valign="top" width="43%" bgcolor="#C0C0C0">All test
        programs for &quot;library-name&quot;. These may be
        either: a single (multi-file) test program, multiple
        single file test programs, or multiple sub-directories (one
        for each test program).</td>
        <td valign="top" width="7%">&nbsp;</td>
    </tr>
    <tr>
        <td valign="top" width="6%">&nbsp;</td>
        <td valign="top" width="44%" bgcolor="#C0C0C0">Boost-root/examples/library-name/</td>
        <td valign="top" width="43%" bgcolor="#C0C0C0">All
        example programs for &quot;library-name&quot;. These may
        be either: a single (multi-file) example program,
        multiple single file example programs, or multiple sub-directories
        (one for each example program).</td>
        <td valign="top" width="7%">&nbsp;</td>
    </tr>
    <tr>
        <td valign="top" width="6%">&nbsp;</td>
        <td valign="top" width="44%" bgcolor="#C0C0C0">Boost-root/tools/tool-name/</td>
        <td valign="top" width="43%" bgcolor="#C0C0C0">Contains
        all files required to build and use the specified tool (makefile
        generators etc).</td>
        <td valign="top" width="7%">&nbsp;</td>
    </tr>
    <tr>
        <td valign="top" width="6%">&nbsp;</td>
        <td valign="top" width="44%" bgcolor="#C0C0C0">Boost-root/build/</td>
        <td valign="top" width="43%" bgcolor="#C0C0C0">The boost
        build system. Consists of a collection of makefiles (one
        for each supported compiler), plus subdirectories: libs/
        for built libraries, bin/ for built dll's (win32 only)
        and obj/ for object files.</td>
        <td valign="top" width="7%">&nbsp;</td>
    </tr>
</table>

<p>&nbsp;</p>

<p>There are a couple of myths surrounding this structure that
need exploding:</p>

<h4>It is hard to check in new libraries to the cvs repository</h4>

<p>Not true: if the submission arrives as a zip file containing
the directory structure described above, then the command:</p>

<p><code>cvs import boost library-name library-name-sub</code></p>

<p>will import the whole of the <i>current</i> directory tree and
&quot;intermingle&quot; it with the existing boost tree in the
repository.</p>

<p>There is one caveat to this however: if the imported source
contains some files that were already in the boost directory tree
(probably not a common situation), then an additional merge and
resolve conflicts step arises:</p>

<p>On the main branch working copy:</p>

<p><code>cvs checkout -jlibrary-name-sub boost</code></p>

<p>Resolve any conflicts, and then:</p>

<p><code>cvs commit</code></p>

<p>The latter two steps should not be necessary in most cases,
and occur whatever directory structure is used (it is probably
easier in most cases to resolve such conflicts manually before
importing the new sources).</p>

<h4>It is hard to checkout or to commit individual boost
libraries.</h4>

<p>By using cvs aliases (defined in the modules file) this
situation does not arise, just specify the module/alias name when
performing a checkout/commit.</p>

<h2 align="center">Migrating to the new structure</h2>

<p>This is probably the hardest and most painful part of the
whole process. I'm going to suggest a migration method as follows:</p>

<ol>
    <li>Instigate a moratorium on cvs commits.</li>
    <li>Copy the files to the new structure and commit the
        changes, leaving the boost-root/libs/ directory in place
        for now.</li>
    <li>Fix html links, and documentation descriptions of file
        locations.</li>
    <li>Fix any library specific scripts/makefiles.</li>
    <li>Publish the new structure (as a zip-file beta
        distribution) and ask boost users/authors to check that
        everything looks OK.</li>
    <li>Delete the boost-root/libs/ directory (actually this is
        quite hard, as cvs has no method for removing whole
        directory trees).</li>
    <li>Lift the moratorium on changes.</li>
    <li>Publish the next boost revision with the new structure.</li>
</ol>

<p>The whole process described above is quite likely to take 1-2
weeks, during which no changes can be committed; this is going to
require a fair amount of co-ordination between developers (actually
this applies to any major change to the directory structure,
irrespective of what the change is).</p>

<p>You will note that I haven't mentioned a time scale for the
associated tools that I have suggested, probably these will need
to be developed after the directory structure changes - although
I believe it is possible to develop a minimal subset (the library
description and alias generator) before making the changes if
that is required.</p>

<p>&nbsp;</p>

<p>There were a couple of other directory structures that were
evaluated while preparing this document:</p>

<p><i>The &quot;half way house structure&quot;:</i></p>

<p>This is the same as the current structure, but moves mandatory
source files to boost-root/src/libname. This is easier to migrate
to from the current structure, but was felt to be neither one
thing nor the other.</p>

<p><i>The &quot;skinny root structure&quot;:</i></p>

<p>This was proposed by John David, and Lois Goldthwaite, and
moves the contents of the current boost-root/libs/ directory into
boost-root/boost/. My main objection to this proposal is that it
is less &quot;discoverable&quot; than the one presented here - my
immediate reaction was &quot;where has everything gone&quot; - I
also dislike mixing headers and non-headers in the same tree.
However I'm prepared to accept that this could just be due to
personal bias.</p>

<h2 align="center">Acknowledgements</h2>

<p>The following people have had their ideas reused,
reconstituted and reformulated :-)</p>

<p>Beman Dawes, Ed Brey, Walter E. Brown, John (EBo) David, Jeff
Garland, Lois Goldthwaite, Jens Maurer, Jeff Squyres, Gary Powell
and Daryle Walker.</p>

<p>
<hr>
<p>

<h2 align="center">An Alternative Directory Structure</h2>

<p align="center">By Jens Maurer</p>

I favor the following structure, which puts different emphasis on the
some of the requirements.

<p>

<table border="1">

<tr>
<th>Directory</th>
<th>Description</th>
</tr>

<tr>
<td>Boost-root/include/boost/</td>
<td>All entry-point boost headers, mainly these should be called
"library-name.hpp".</td>
</tr>

<tr>
<td>Boost-root/include/boost/.../</td>
<td>Domain-specific subdirectory; the "..." can be empty or
arbitrarily nested while observing the "optimally branched"
requirement.</td>
</tr>

<tr>
<td>Boost-root/include/boost/.../library-name/</td>
<td>All domain-specific headers, all "expert-user" non-entry point
headers.</td>
</tr>

<tr>
<td>Boost-root/include/boost/.../library-name/detail/</td>
<td>All implementation private headers.</td>
</tr>

<tr>
<td>Boost-root/libs/.../</td>
<td>Main directory for a given subdomain; the "..." can be empty or
arbitrarily nested while observing the "optimally branched"
requirement.  The "..." must correspond to some "..." in the header
tree.  The directory should contain a "index.html" which links to all
libraries and subdomains contained.</td>
</tr>

<tr>
<td>Boost-root/libs/.../library-name/</td>
<td>Main directory for a given library.</td>
</tr>

<tr>
<td>Boost-root/libs/.../library-name/src/</td>
<td>All mandatory source files for the library.</td>
</tr>

<tr>
<td>Boost-root/libs/.../library-name/build/</td>
<td>Temporary location for private build system, until the boost-wide
integrated build becomes available.</td>
</tr>

<tr>
<td>Boost-root/libs/.../library-name/config/</td>
<td>Any private configuration code (for example, autoconf
scripts).</td>
</tr>

<tr>
<td>Boost-root/libs/.../library-name/doc/</td>
<td>All documentation for the library.</td>
</tr>

<tr>
<td>Boost-root/libs/.../library-name/test/</td>
<td>All regression tests for the library, suitable for the regression
test suite.  Due to test execution time constraints, not all of the tests
may actually be added to "regression.cfg".</td>
</tr>

<tr>
<td>Boost-root/libs/.../library-name/example/</td>
<td>All example programs for "library-name". These may be either: a
single (multi-file) example program, multiple single file example
programs, or multiple sub-directories (one for each example
program).</td>
</tr>

<tr>
<td>Boost-root/tools/tool-name/</td>
<td>Contains all files required to build and use the specified tool
(makefile generators etc).</td>
</tr>

<tr>
<td>Boost-root/build</td>
<td>The boost build system (user front-end; tools go in the "tools"
hierarchy).  Details still hazy.</td>
</tr>

<tr>
<td>Boost-root/more/license.html</td>
<td>A "generic" boost license that describes the minimal guarantee
provided by all boost libraries.  This should get a prominent link on
the main boost page.</td>
</tr>

</table>

<p>
Note that the "include" path component contains only one subdirectory
"boost" and thus violates the "optimally branched" requirement.  It
helps with discoverability, though, because people know what to expect
under any directory named "include", i.e. header files.

</body>
</html>