organicmaps/boost
13
Fork 0
mirror of https://github.com/boostorg/boost.git synced 2025-04-11 07:41:06 +00:00
Code Issues 1 Projects Releases Wiki Activity Actions

Move top-level boost directory over to "devel" (temporarily)

Browse source 
[SVN r38327]
This commit is contained in:
Douglas Gregor 2007-07-31 20:32:15 +00:00
parent 4c765d1f2d
commit 0df8db1603
33 changed files with 155 additions and 859 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

124
.gitmodules vendored
View file

@ -250,6 +250,10 @@
path = libs/algorithm
url = ../algorithm.git
fetchRecurseSubmodules = on-demand
[submodule "local_function"]
path = libs/local_function
url = ../local_function.git
fetchRecurseSubmodules = on-demand
[submodule "property_tree"]
path = libs/property_tree
url = ../property_tree.git
@ -330,3 +334,123 @@
path = libs/intrusive
url = ../intrusive.git
fetchRecurseSubmodules = on-demand
[submodule "coroutine"]
path = libs/coroutine
url = ../coroutine.git
fetchRecurseSubmodules = on-demand
[submodule "flyweight"]
path = libs/flyweight
url = ../flyweight.git
fetchRecurseSubmodules = on-demand
[submodule "geometry"]
path = libs/geometry
url = ../geometry.git
fetchRecurseSubmodules = on-demand
[submodule "atomic"]
path = libs/atomic
url = ../atomic.git
fetchRecurseSubmodules = on-demand
[submodule "auto_index"]
path = tools/auto_index
url = ../auto_index.git
fetchRecurseSubmodules = on-demand
[submodule "heap"]
path = libs/heap
url = ../heap.git
fetchRecurseSubmodules = on-demand
[submodule "icl"]
path = libs/icl
url = ../icl.git
fetchRecurseSubmodules = on-demand
[submodule "multiprecision"]
path = libs/multiprecision
url = ../multiprecision.git
fetchRecurseSubmodules = on-demand
[submodule "odeint"]
path = libs/numeric/odeint
url = ../odeint.git
fetchRecurseSubmodules = on-demand
[submodule "locale"]
path = libs/locale
url = ../locale.git
fetchRecurseSubmodules = on-demand
[submodule "lockfree"]
path = libs/lockfree
url = ../lockfree.git
fetchRecurseSubmodules = on-demand
[submodule "move"]
path = libs/move
url = ../move.git
fetchRecurseSubmodules = on-demand
[submodule "msm"]
path = libs/msm
url = ../msm.git
fetchRecurseSubmodules = on-demand
[submodule "tti"]
path = libs/tti
url = ../tti.git
fetchRecurseSubmodules = on-demand
[submodule "type_erasure"]
path = libs/type_erasure
url = ../type_erasure.git
fetchRecurseSubmodules = on-demand
[submodule "phoenix"]
path = libs/phoenix
url = ../phoenix.git
fetchRecurseSubmodules = on-demand
[submodule "polygon"]
path = libs/polygon
url = ../polygon.git
fetchRecurseSubmodules = on-demand
[submodule "predef"]
path = libs/predef
url = ../predef.git
fetchRecurseSubmodules = on-demand
[submodule "proto"]
path = libs/proto
url = ../proto.git
fetchRecurseSubmodules = on-demand
[submodule "ratio"]
path = libs/ratio
url = ../ratio.git
fetchRecurseSubmodules = on-demand
[submodule "scope_exit"]
path = libs/scope_exit
url = ../scope_exit.git
fetchRecurseSubmodules = on-demand
[submodule "signals2"]
path = libs/signals2
url = ../signals2.git
fetchRecurseSubmodules = on-demand
[submodule "sync"]
path = libs/sync
url = ../sync.git
fetchRecurseSubmodules = on-demand
[submodule "units"]
path = libs/units
url = ../units.git
fetchRecurseSubmodules = on-demand
[submodule "unordered"]
path = libs/unordered
url = ../unordered.git
fetchRecurseSubmodules = on-demand
[submodule "uuid"]
path = libs/uuid
url = ../uuid.git
fetchRecurseSubmodules = on-demand
[submodule "chrono"]
path = libs/chrono
url = ../chrono.git
fetchRecurseSubmodules = on-demand
[submodule "container"]
path = libs/container
url = ../container.git
fetchRecurseSubmodules = on-demand
[submodule "context"]
path = libs/context
url = ../context.git
fetchRecurseSubmodules = on-demand
[submodule "accumulators"]
path = libs/accumulators
url = ../accumulators.git
fetchRecurseSubmodules = on-demand

859
development/more/directory-structure.htm
View file

@ -1,859 +0,0 @@
<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>

1
libs/accumulators Submodule

@ -0,0 +1 @@
Subproject commit 88da98e37b9539c103ae9e6fc7db1b4e52010585

1
libs/atomic Submodule

@ -0,0 +1 @@
Subproject commit 88da98e37b9539c103ae9e6fc7db1b4e52010585

1
libs/chrono Submodule

@ -0,0 +1 @@
Subproject commit 88da98e37b9539c103ae9e6fc7db1b4e52010585

1
libs/container Submodule

@ -0,0 +1 @@
Subproject commit 88da98e37b9539c103ae9e6fc7db1b4e52010585

1
libs/context Submodule

@ -0,0 +1 @@
Subproject commit 88da98e37b9539c103ae9e6fc7db1b4e52010585

1
libs/coroutine Submodule

@ -0,0 +1 @@
Subproject commit 88da98e37b9539c103ae9e6fc7db1b4e52010585

1
libs/flyweight Submodule

@ -0,0 +1 @@
Subproject commit 88da98e37b9539c103ae9e6fc7db1b4e52010585

1
libs/geometry Submodule

@ -0,0 +1 @@
Subproject commit 88da98e37b9539c103ae9e6fc7db1b4e52010585

1
libs/heap Submodule

@ -0,0 +1 @@
Subproject commit 88da98e37b9539c103ae9e6fc7db1b4e52010585

1
libs/icl Submodule

@ -0,0 +1 @@
Subproject commit 88da98e37b9539c103ae9e6fc7db1b4e52010585

1
libs/local_function Submodule

@ -0,0 +1 @@
Subproject commit 88da98e37b9539c103ae9e6fc7db1b4e52010585

1
libs/locale Submodule

@ -0,0 +1 @@
Subproject commit 88da98e37b9539c103ae9e6fc7db1b4e52010585

1
libs/lockfree Submodule

@ -0,0 +1 @@
Subproject commit 88da98e37b9539c103ae9e6fc7db1b4e52010585

1
libs/move Submodule

@ -0,0 +1 @@
Subproject commit 88da98e37b9539c103ae9e6fc7db1b4e52010585

1
libs/msm Submodule

@ -0,0 +1 @@
Subproject commit 88da98e37b9539c103ae9e6fc7db1b4e52010585

1
libs/multiprecision Submodule

@ -0,0 +1 @@
Subproject commit 88da98e37b9539c103ae9e6fc7db1b4e52010585

1
libs/numeric/odeint Submodule

@ -0,0 +1 @@
Subproject commit 88da98e37b9539c103ae9e6fc7db1b4e52010585

1
libs/phoenix Submodule

@ -0,0 +1 @@
Subproject commit 88da98e37b9539c103ae9e6fc7db1b4e52010585

1
libs/polygon Submodule

@ -0,0 +1 @@
Subproject commit 88da98e37b9539c103ae9e6fc7db1b4e52010585

1
libs/predef Submodule

@ -0,0 +1 @@
Subproject commit 88da98e37b9539c103ae9e6fc7db1b4e52010585

1
libs/proto Submodule

@ -0,0 +1 @@
Subproject commit 88da98e37b9539c103ae9e6fc7db1b4e52010585

1
libs/ratio Submodule

@ -0,0 +1 @@
Subproject commit 88da98e37b9539c103ae9e6fc7db1b4e52010585

1
libs/scope_exit Submodule

@ -0,0 +1 @@
Subproject commit 88da98e37b9539c103ae9e6fc7db1b4e52010585

1
libs/signals2 Submodule

@ -0,0 +1 @@
Subproject commit 88da98e37b9539c103ae9e6fc7db1b4e52010585

1
libs/sync Submodule

@ -0,0 +1 @@
Subproject commit 88da98e37b9539c103ae9e6fc7db1b4e52010585

1
libs/tti Submodule

@ -0,0 +1 @@
Subproject commit 88da98e37b9539c103ae9e6fc7db1b4e52010585

1
libs/type_erasure Submodule

@ -0,0 +1 @@
Subproject commit 88da98e37b9539c103ae9e6fc7db1b4e52010585

1
libs/units Submodule

@ -0,0 +1 @@
Subproject commit 88da98e37b9539c103ae9e6fc7db1b4e52010585

1
libs/unordered Submodule

@ -0,0 +1 @@
Subproject commit 88da98e37b9539c103ae9e6fc7db1b4e52010585

1
libs/uuid Submodule

@ -0,0 +1 @@
Subproject commit 88da98e37b9539c103ae9e6fc7db1b4e52010585

1
tools/auto_index Submodule

@ -0,0 +1 @@
Subproject commit 88da98e37b9539c103ae9e6fc7db1b4e52010585