|
|
@@ -0,0 +1,742 @@
|
|
|
+<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> </p>
|
|
|
+
|
|
|
+<p> </p>
|
|
|
+
|
|
|
+<p> </p>
|
|
|
+</body>
|
|
|
+</html>
|
John Maddock