|
|
@@ -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 "do as little as
|
|
|
-possible" 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: "I wonder what's
|
|
|
- in here?", 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 "<code>cvs checkout regex</code>"
|
|
|
- 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 "as is"</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 "occasional developers"
|
|
|
- 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 "wrapper compilers"
|
|
|
- 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 "boost-root/src/libname/boost",
|
|
|
- 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 <boost/something.hpp></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 <rw/thread.h> // 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 "non-end user" 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 "numeric" 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 "boost_1_1_9/"
|
|
|
- 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 "<code>boost-root/development/library-name/</code>"
|
|
|
- that internally mirrors the directory structure of <code>boost-root/</code>,
|
|
|
- to contain development code for library "library-name".
|
|
|
- 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 "<code>cvs checkout
|
|
|
- development"</code> instead of "<code>cvs
|
|
|
- checkout boost"</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 "hidden"
|
|
|
- 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
|
|
|
- "headers only", 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 "optimally
|
|
|
-branched"</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 "discoverable"
|
|
|
- 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 "distil" 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%"> </td>
|
|
|
- <td valign="top" width="44%" bgcolor="#008080">Directory</td>
|
|
|
- <td valign="top" width="43%" bgcolor="#008080">Description</td>
|
|
|
- <td valign="top" width="7%"> </td>
|
|
|
- </tr>
|
|
|
- <tr>
|
|
|
- <td valign="top" width="6%"> </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 "library-name.hpp"</td>
|
|
|
- <td valign="top" width="7%"> </td>
|
|
|
- </tr>
|
|
|
- <tr>
|
|
|
- <td valign="top" width="6%"> </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 "expert-user" non-entry
|
|
|
- point headers.</td>
|
|
|
- <td valign="top" width="7%"> </td>
|
|
|
- </tr>
|
|
|
- <tr>
|
|
|
- <td valign="top" width="6%"> </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%"> </td>
|
|
|
- </tr>
|
|
|
- <tr>
|
|
|
- <td valign="top" width="6%"> </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%"> </td>
|
|
|
- </tr>
|
|
|
- <tr>
|
|
|
- <td valign="top" width="6%"> </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%"> </td>
|
|
|
- </tr>
|
|
|
- <tr>
|
|
|
- <td valign="top" width="6%"> </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%"> </td>
|
|
|
- </tr>
|
|
|
- <tr>
|
|
|
- <td valign="top" width="6%"> </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%"> </td>
|
|
|
- </tr>
|
|
|
- <tr>
|
|
|
- <td valign="top" width="6%"> </td>
|
|
|
- <td valign="top" width="44%" bgcolor="#C0C0C0">Boost-root/docs/library-name/</td>
|
|
|
- <td valign="top" width="43%" bgcolor="#C0C0C0">All
|
|
|
- documentation for "library-name"; must include
|
|
|
- an index.htm file.</td>
|
|
|
- <td valign="top" width="7%"> </td>
|
|
|
- </tr>
|
|
|
- <tr>
|
|
|
- <td> </td>
|
|
|
- <td valign="top" bgcolor="#C0C0C0">Boost-root/licence</td>
|
|
|
- <td bgcolor="#C0C0C0">A "generic" 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> </td>
|
|
|
- </tr>
|
|
|
- <tr>
|
|
|
- <td valign="top" width="6%"> </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 "library-name". 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%"> </td>
|
|
|
- </tr>
|
|
|
- <tr>
|
|
|
- <td valign="top" width="6%"> </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 "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>
|
|
|
- <td valign="top" width="7%"> </td>
|
|
|
- </tr>
|
|
|
- <tr>
|
|
|
- <td valign="top" width="6%"> </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%"> </td>
|
|
|
- </tr>
|
|
|
- <tr>
|
|
|
- <td valign="top" width="6%"> </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%"> </td>
|
|
|
- </tr>
|
|
|
-</table>
|
|
|
-
|
|
|
-<p> </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
|
|
|
-"intermingle" 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> </p>
|
|
|
-
|
|
|
-<p>There were a couple of other directory structures that were
|
|
|
-evaluated while preparing this document:</p>
|
|
|
-
|
|
|
-<p><i>The "half way house structure":</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 "skinny root structure":</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 "discoverable" than the one presented here - my
|
|
|
-immediate reaction was "where has everything gone" - 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>
|
Douglas Gregor