[build2] How to achive a mini-monorepo project structure

[Boris Kolpackov]

Matt Armstrong via users <users at build2.org> writes:

> I have a small but rapidly changing exploratory project, with a small
> number of libraries and a small number of executables.  It is unlikely
> that anybody else will ever use this code.  For this reason, I keep it
> all in one git repository.
> 
> In other build systems, I have easily expressed this as a kind of
> "mini-monorepo" structure: one version control repository, N libraries,
> N binaries.

Let me state for completeness that in build2 there are two ways to
arrange this: as a project with multiple packages or as a project
with multiple source subdirectories. While the multiple packages
approach has some management overhead (e.g., you have to keep track
of inter-package dependencies in their manifests, etc), it also has
a number of benefits (e.g., you will be able to CI individual packages
and, of course, easily reuse one of the libraries in another "mini-
monorepo").

(Actually, there is also an in-between approach where you have a
number of build system-level subprojects, but let's not complicate
things; you can read more on this[1] if you are interested.)

As I understand it, you are interested in the multiple source sub-
directories approach so below I will focus on that (I believe the 
multiple packages approach is covered sufficiently well in the 
introduction).


> In build2, I have failed to express this project structure after two
> attempts of carefully reading through the tutorial and honestly trying.
> I must be missing something.
>
> [...]
>
> One thing I'll note is that the
> https://build2.org/build2-toolchain/doc/build2-toolchain-intro.xhtml
> does not cover this use case.  I can't find coverage of how one target
> is built from another across directories.  There is great coverage for
> producing and consuming packages, and for working with single-directory
> packages, but multi-directory packages are thin.

Yes, true, this is actually covered in the build system manual[2]. I
think it makes sense to at least add a note in the introduction. Maybe 
I should also add a HOWTO[3] entry on this?


> My repro is similar to the one in that issue, but uses --source instead
> of --project:
> 
> ```
> $ bdep new -l c++ -t bare hello
> $ cd hello
> $ bdep new --source -l c++ -t lib libhello
> $ bdep new --source -l c++ -t exe hello
> $ bdep init -C @gcc cc config.cxx=g++
> ```
> 
> If I instead change `hello/buildfile` to look like this:
> 
> ```
> libs = libhello%lib{hello}
> #import libs += libhello%lib{hello}
> 
> exe{hello}: {hxx ixx txx cxx}{**} $libs testscript
> 
> cxx.poptions =+ "-I$out_root" "-I$src_root"
> ```
> 
> I get the same error.
> 
> How can I teach b that hello/buildfile may use libhello from
> libhello/buildfile?

We use import to get targets from other projects. Within the same
project, we just include the buildfile that declares the target and 
use it directly (see [2] for details):

include ../libhello/ # Include lib{hello}.

exe{hello}: {hxx cxx}{**} ../libhello/lib{hello}

Alternatively, you can use project-local importation discussed in [4].
This can be especially attractive if you have a regular target/directory
naming structure and can implement a generic export stub that doesn't
need to be updated every time you add another library. For example, if
for every library target in the lib{hello} form you know that it resides
in the libhello/ subdirectory of your project, then you can have something
like this for your export.build:

if ($target_type($import.target) == 'lib')
{
  d = [dir_path] $out_root/"lib$name($import.target)"

  $d/
  {
    include ./
  }

  export $d/$import.target
}

[1] https://build2.org/build2/doc/build2-build-system-manual.xhtml#intro-subproj

[2] It is first covered in a note at the end of:

    https://build2.org/build2/doc/build2-build-system-manual.xhtml#intro-dirs-scopes

    And then discussed some more in:

    https://build2.org/build2/doc/build2-build-system-manual.xhtml#intro-import

[3] https://github.com/build2/HOWTO/

[4] https://build2.org/build2/doc/build2-build-system-manual.xhtml#intro-import