diff options
Diffstat (limited to 'development/more/directory-structure.htm')
| -rw-r--r-- | development/more/directory-structure.htm | 742 |
1 files changed, 742 insertions, 0 deletions
diff --git a/development/more/directory-structure.htm b/development/more/directory-structure.htm new file mode 100644 index 0000000000..2c9af19a66 --- /dev/null +++ b/development/more/directory-structure.htm @@ -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> |