Re: On Boost and modules

From: Boris Kolpackov (boris_at_[hidden])
Date: 2024-04-11 17:03:31

Rainer Deyke via Boost <boost_at_[hidden]> writes:

> This is the layout I want:
> 
> <project_name>
>   + builds <- not in version control
>     + configuration1
>     + configuration2
>   + source
>     + <super_project_name>
>       + <project_name>
>         + <project>.hpp
>         + <project>.cpp
>   + <build_configurations_files> <- in version control

So similar to the Boost layout of individual libraries but combined
instead of split:

foo/
└── libs/
    └── boost/
        └── foo/
            ├── foo.cpp
            └── foo.hpp

> I find the use of <super_project_name> useful to separate internal libraries
> and external libraries, and to prevent namespace pollution.  I use this
> include style:
> 
>   #include "super_project_name/project_name/project.hpp"

Ok, so this in the Boost analogy:

#include "boost/foo/foo.hpp"

> Double quotes instead of angle brackets because the file I'm including is
> not from the standard library, but always with both super_project and
> project names.

Nothing prevents you from using <>-style inclusion for non-standard
headers, but ok, every C++ developer has their unique style ;-).

> The important bits here that Build2 doesn't seem to like:
>   - Builds go under the main project directory.  One project, one top-level
> directory (with as many subdirectories as needed).

Yes, one of the somewhat "hard" rules in build2 is that you either build
in source, or out of source, not kind-of-out-of-source (i.e., with the
builds/ directory inside your project repository).

The main user-facing reason for this is that build2 is multirepo-first,
meaning that we assume the user will work with multiple repositories
simultaneously and often it will be convenient to share build
configurations between them. As an example, consider another repository
bar that you develop simultaneously and that depends on foo (pretty
much the arrangement of the Boost libraries on GitHub before they are
amalgamated). While you don't have to, it's normally convenient to
initialize them in a shared build configuration. If your build
configuration directories are inside foo/ and bar/, then it becomes
asymmetrical and awkward.

Having said that, there is an escape hatch if you really want to
keep you build directory inside your repository: don't make your
repository root a build2 project/package root, instead pushing it
one directory level deeper (this is also how we support multi-
package repositories).

While it's hard to recreate your structure exactly (because of
another "hard" rule in build2, which is that a project/package
root directory must be the same as the project/package name,
so it cannot be source/ or libs/), but you can get pretty close:

foo/
├── builds/
└── libboost-foo/
    └── boost/
        └── foo/
            ├── foo.cpp
            └── foo.hpp

The bdep-new commands that create this would be:

$ bdep new --type empty foo
$ cd foo
$ bdep new --package --lang c++,cpp --type lib,subdir=boost/foo libboost-foo

$ tree foo
foo/
├── libboost-foo/
│   ├── boost/
│   │   └── foo/
│   │       ├── boost-foo.cpp
│   │       ├── boost-foo.hpp
│   │       ├── buildfile
│   │       ├── export.hpp
│   │       └── version.hpp.in
│   ├── build/
│   │   ├── bootstrap.build
│   │   ├── export.build
│   │   └── root.build
│   ├── tests/
│   │   ├── basics/
│   │   │   ├── buildfile
│   │   │   └── driver.cpp
│   │   ├── build/
│   │   │   ├── bootstrap.build
│   │   │   └── root.build
│   │   └── buildfile
│   ├── buildfile
│   ├── manifest
│   └── README.md
├── buildfile
├── packages.manifest
├── README.md
└── repositories.manifest

>   - Build configurations are versioned.
>
> That's a relief, but the configuration options are stored with the build
> artifacts?  That's awkward if I want the configuration options in version
> control while keeping the build artifacts outside.

There is a mechanism for that: you can save some pre-canned configurations
in the version control and then load them when creating the build
configurations. Continuing with the above example:

$ cat <<EOF >with-warnings.build
config.version = 1

config.cxx.coptions += -Wall -Wextra -Werror
EOF

$ bdep init -C builds/gcc-with-warnings @gccW cc config.cxx=g++ \
  config.config.load=./with-warnings.build

For background on config.config.load (there is also .save), see:

https://build2.org/release/0.12.0.xhtml#config-export-import