Re: [boost] [Modularization] A new approach to header modularization

Subject: Re: [boost] [Modularization] A new approach to header modularization
From: Robert Ramey (ramey_at_[hidden])
Date: 2009-05-28 15:02:11

Beman Dawes wrote:
> I've started to put together a wiki page based on our ongoing Header
> Modularization discussions.
>
> See http://svn.boost.org/trac/boost/wiki/HeaderModularization
>
> I listed eight approaches to meeting the Goals/Objectives/Needs/Wants,
> and was about to identify the weaknesses of each approach when I hit
> on approach nine:
>
>      Move (permanently) each library's root/libs/libname contents
>      into root/boost/libname for the library.
>
> In other words, instead of moving the boost/... tree headers to the
> libs/... tree, merge the libs/... tree into the boost/... tree.
>
> For example, Boost.Filesystem is currently organized like this:
>
>   root/
>     boost/
>       filesystem.hpp
>       filesystem/
>         config.hpp
>         convenience.hpp
>         exception.hpp
>         fstream.hpp
>         operations.hpp
>         path.hpp
>     libs/
>       filesystem/
>         build/
>           ...
>         CMakeLists.txt
>         doc/
>           ...
>         example/
>           ...
>         index.html
>           ...
>         module.cmake
>         src/
>           ...
>         test/
>           ...
>
> After the reorganization, filesystem would be organized like this:
>
>   root/
>     boost/
>       filesystem.hpp
>       filesystem/
>         config.hpp
>         convenience.hpp
>         exception.hpp
>         fstream.hpp
>         operations.hpp
>         path.hpp
>         build/
>           ...
>         CMakeLists.txt
>         doc/
>           ...
>         example/
>           ...
>         index.html
>           ...
>         module.cmake
>         src/
>           ...
>         test/
>           ...
>
> In theory, the root/libs/... tree isn't needed anymore. In practice we
> might want to keep a root/libs/libname/index.html entry for each
> library so docs links don't break.
>
> Apologies if someone already suggested this approach. It is so simple
> I can't believe someone didn't already suggest it.
>
> Unless I'm missing something, this is the only approach that appears
> to do fairly well for all of the Goals/Objectives/Needs/Wants, and very
> well for most of them. It would require some rework of scripts and
> other setups that depend on the current organization of libs/..., but
> that seems minor compared to the long-term benefits.
>
> Comments?

This is on the right track!!!  Here's my incremental 2 cents

root/
    boost/
        filesystem.hpp
        filesystem/
            config.hpp
            convenience.hpp - uh-oh looks like this is taken care of by 
../filesystem.hpp
            exception.hpp
            fstream.hpp
            operations.hpp
            path.hpp
            index.html - link to doc/html/index.html
            bjam/
                build/
                    Jamfile.v2
                test/
                    Jamfile.v2
            cmake/
                build/
                    module.cmake
                test/
                    ?....
            vc7ide/  - or whatever
                build/
                    solutions and projects
                test/
                    solutions and projects
            doc/
                html/
                    index.html
                    ... - maybe generated from docbook
                pdf/
                    ?. pdf - maybe gerated from docbook
                    ...
                docbook/
                    ?.xml - maybe generated by qbk
                    ....
                qbk/
                    ...
            libs/  - was src
                filesystem.cpp
                ....
                binaries/
                    libboost.....
                    boost.... / whatever
                    ...
                bjam/
                    Jamfile.v2 - to build library
                    results.html - build by bjam build
                cmake/
                    cmake.module
                vc7ide/ - or whatever
                    solutions and projects
            test/
                test_filesystem.cpp
                ....
                binaries/
                    test_filesystem.exe
                    ...
                bjam/
                    Jamfile.v2 - to build library
                    results.html - build by bjam build
                cmake/
                    cmake.module
                vc7ide/ - or whatever
                    solutions and projects
            example/
                example_filesystem.cpp
                ....
                binaries/
                    example_filesystem.exe
                    ...
                bjam/
                    Jamfile.v2 - to build and run examples
                    results.html - build by bjam build
                cmake/
                    cmake.module
                vc7ide/ - or whatever
            performance/ or whatever
                example_filesystem.cpp
                ....
                binaries/
                    example_filesystem.exe
                    ...
                bjam/
                    Jamfile.v2 - to build library
                    results.html - build by bjam build
                cmake/
                    cmake.module
                vc7ide/ - or whatever

Other points

There should be NO files in root/boost.  All these should be moved to 
root/boost/utilities.
root/boost/utilities would ahve the same structure as if it were any other 
library.  Basically
it is "catch all" library for miscelaneous components that are "too small" 
to rate a whole tree.

To build/run any section - e.g. performance with bjam build

cd root/boost/filesystem/performance/bjam
bjam_build.sh or bjam_build.bat or whatever
#generates results.html

Building anything would invoke builds on it's prerequistes
Building all libaries would just walk all the libraries.  Any thing already
update wouldn't be repeated.

I'm not crazy about using fancy features which are coupled with
some particular tool.  I'm specifically referring to using things
like

svnexternals
hardlinks to "hide" some "real" directory structure behind some
"public" one. and other assorted tricks.  Such "tricks" seem
appealing at the beginning. but they tend to make things hard
to understand when things go (inevitably) wrong.

That's my 2 cents.

BTW - I'm very happy with the current SVN setup.  It has worked
extremely well for me.  I would be extremely reluctant to abandon
somethng that has worked as advertised.

>
> --Beman
>
>
> _______________________________________________
> Unsubscribe & other changes:
> http://lists.boost.org/mailman/listinfo.cgi/boost