[RFC] Makefile: from a defconfig file, point to the corresponding board/ entry

This is an RFC!

When configuring Buildroot from a defconfig files, soem users complain
it is non-obvious that the corresponding board documentattion is to be
found in the board/ sub-directory.

So, deduce the board name from the defconfig file, look for a similarly
named sub-dir of board (first level only), and if such a directory
exists, print a message stating extra documentation for that board is to
be found there.

This works for only 5 of our 69 defconfig files, because:

  - some boards docs are in sub-sub-dirs (count raises to 11 in that
    case);

  - most boards dirs are not directly named after the defconfig file,
    like:
        board/olimex/imx233_olinuxino/
        configs/olimex_imx233_olinuxino_defconfig

So, we could maybe improve this by renaming and moving our boards docs
so there is a one-to-one mapping from the board directory to the
corresponding defconfig file (but not necessarily the other way around).

Signed-off-by: "Yann E. MORIN" <yann.morin.1998@free.fr>
---
 Makefile | 8 ++++++++
 1 file changed, 8 insertions(+)

Hi Yann,

On Thursday 27 November 2014 00:13:55 Yann E. MORIN wrote:
> This is an RFC!
> 
> When configuring Buildroot from a defconfig files, soem users complain
> it is non-obvious that the corresponding board documentattion is to be
> found in the board/ sub-directory.
> 
> So, deduce the board name from the defconfig file, look for a similarly
> named sub-dir of board (first level only), and if such a directory
> exists, print a message stating extra documentation for that board is to
> be found there.

What about introducing a BR2_BOARD_DIR configuration variable? This variable 
would have two functions:
   - May be used to locate other files (configs, overlays, etc...)
   - If defined, a help message is displayed when this defconfig is loaded.

Hi Yann,

On Thu, Nov 27, 2014 at 12:13 AM, Yann E. MORIN <yann.morin.1998@free.fr> wrote:
> This is an RFC!
>
> When configuring Buildroot from a defconfig files, soem users complain
> it is non-obvious that the corresponding board documentattion is to be
> found in the board/ sub-directory.
>
> So, deduce the board name from the defconfig file, look for a similarly
> named sub-dir of board (first level only), and if such a directory
> exists, print a message stating extra documentation for that board is to
> be found there.
>
> This works for only 5 of our 69 defconfig files, because:
>
>   - some boards docs are in sub-sub-dirs (count raises to 11 in that
>     case);
>
>   - most boards dirs are not directly named after the defconfig file,
>     like:
>         board/olimex/imx233_olinuxino/
>         configs/olimex_imx233_olinuxino_defconfig
>
> So, we could maybe improve this by renaming and moving our boards docs
> so there is a one-to-one mapping from the board directory to the
> corresponding defconfig file (but not necessarily the other way around).


I would like to point out that automatically detecting the board
directory is fragile, because
- the mapping may not be obvious, as you already found
- there may be more than one 'board' directory. For example, a typical
setup when having multiple more-or-less-related projects in a company
is to have several layers of post-build/rootfs-overlay/..., for
example:
board/company/common/...
board/company/project1/...
board/company/project2/...
In the defconfigs of both project1 and project2, the post-build and
rootfs-overlay settings would contain multiple entries, being
common+project1 and common+project2 respectively.
There may even be more levels than that, for example (in my case)
common, architecture-specific, project-family-specific,
board-specific.

Best regards,
Thomas

On 11/27/2014 07:37 AM, Thomas De Schampheleire wrote:

>> So, we could maybe improve this by renaming and moving our boards docs
>> so there is a one-to-one mapping from the board directory to the
>> corresponding defconfig file (but not necessarily the other way around).
> 
> 
> I would like to point out that automatically detecting the board
> directory is fragile, because
> - the mapping may not be obvious, as you already found
> - there may be more than one 'board' directory. For example, a typical
> setup when having multiple more-or-less-related projects in a company
> is to have several layers of post-build/rootfs-overlay/..., for
> example:
> board/company/common/...
> board/company/project1/...
> board/company/project2/...
> In the defconfigs of both project1 and project2, the post-build and
> rootfs-overlay settings would contain multiple entries, being
> common+project1 and common+project2 respectively.
> There may even be more levels than that, for example (in my case)
> common, architecture-specific, project-family-specific,
> board-specific.

Agreed.
Wouldn't it be easier to define something like
BR2_POST_BUILD_INSTRUCTIONS (with some nicer well-thought out name)
that's shown when a successful build finishes which points to the proper
documentation and does nothing if unset? (a good old conditional 'cat').
Regards.

Jérôme, All,

On 2014-11-27 11:26 +0100, Jérôme Pouiller spake thusly:
> On Thursday 27 November 2014 00:13:55 Yann E. MORIN wrote:
> > This is an RFC!
> > 
> > When configuring Buildroot from a defconfig files, soem users complain
> > it is non-obvious that the corresponding board documentattion is to be
> > found in the board/ sub-directory.
> > 
> > So, deduce the board name from the defconfig file, look for a similarly
> > named sub-dir of board (first level only), and if such a directory
> > exists, print a message stating extra documentation for that board is to
> > be found there.
> 
> What about introducing a BR2_BOARD_DIR configuration variable? This variable 
> would have two functions:
>    - May be used to locate other files (configs, overlays, etc...)
>    - If defined, a help message is displayed when this defconfig is loaded.

The problem with using a Kconfig string variable is that Kconfig strgings
that have no prompt can only take their default value, as defined in
Config.in; if there is no default value, then the string option is not
even stored in the .config file.

If we were to have, for example, a Config.in with:

    config BR2_BOARD_DIR
        string

and we were to seed it with a foo_defconfig file that has:

    BR2_BOARD_DIR="$(TOP_DIR)/board/foo"

then calling "make foo_defconfig" would yield an empty .config file.

So, we can not use a Kconfig string variable.

Regards,
Yann E. MORIN.

Gustavo, All,

On 2014-11-27 07:41 -0300, Gustavo Zacarias spake thusly:
> On 11/27/2014 07:37 AM, Thomas De Schampheleire wrote:
> 
> >> So, we could maybe improve this by renaming and moving our boards docs
> >> so there is a one-to-one mapping from the board directory to the
> >> corresponding defconfig file (but not necessarily the other way around).
> > 
> > 
> > I would like to point out that automatically detecting the board
> > directory is fragile, because
> > - the mapping may not be obvious, as you already found
> > - there may be more than one 'board' directory. For example, a typical
> > setup when having multiple more-or-less-related projects in a company
> > is to have several layers of post-build/rootfs-overlay/..., for
> > example:
> > board/company/common/...
> > board/company/project1/...
> > board/company/project2/...
> > In the defconfigs of both project1 and project2, the post-build and
> > rootfs-overlay settings would contain multiple entries, being
> > common+project1 and common+project2 respectively.
> > There may even be more levels than that, for example (in my case)
> > common, architecture-specific, project-family-specific,
> > board-specific.
> 
> Agreed.
> Wouldn't it be easier to define something like
> BR2_POST_BUILD_INSTRUCTIONS (with some nicer well-thought out name)
> that's shown when a successful build finishes which points to the proper
> documentation and does nothing if unset? (a good old conditional 'cat').

As I explained to Jérôme, it is not possible to use a Kconfig string
option; see:
    http://lists.busybox.net/pipermail/buildroot/2014-November/113189.html

Regards,
Yann E. MORIN.

Thomas, All,

On 2014-11-27 11:37 +0100, Thomas De Schampheleire spake thusly:
> On Thu, Nov 27, 2014 at 12:13 AM, Yann E. MORIN <yann.morin.1998@free.fr> wrote:
> > This is an RFC!
> >
> > When configuring Buildroot from a defconfig files, soem users complain
> > it is non-obvious that the corresponding board documentattion is to be
> > found in the board/ sub-directory.
> >
> > So, deduce the board name from the defconfig file, look for a similarly
> > named sub-dir of board (first level only), and if such a directory
> > exists, print a message stating extra documentation for that board is to
> > be found there.
> >
> > This works for only 5 of our 69 defconfig files, because:
> >
> >   - some boards docs are in sub-sub-dirs (count raises to 11 in that
> >     case);
> >
> >   - most boards dirs are not directly named after the defconfig file,
> >     like:
> >         board/olimex/imx233_olinuxino/
> >         configs/olimex_imx233_olinuxino_defconfig
> >
> > So, we could maybe improve this by renaming and moving our boards docs
> > so there is a one-to-one mapping from the board directory to the
> > corresponding defconfig file (but not necessarily the other way around).
> 
> 
> I would like to point out that automatically detecting the board
> directory is fragile, because
> - the mapping may not be obvious, as you already found
> - there may be more than one 'board' directory. For example, a typical
> setup when having multiple more-or-less-related projects in a company
> is to have several layers of post-build/rootfs-overlay/..., for
> example:
> board/company/common/...
> board/company/project1/...
> board/company/project2/...
> In the defconfigs of both project1 and project2, the post-build and
> rootfs-overlay settings would contain multiple entries, being
> common+project1 and common+project2 respectively.
> There may even be more levels than that, for example (in my case)
> common, architecture-specific, project-family-specific,
> board-specific.

Well, I was not even thinking about company-specific stuff (rather, I
did not consider them _on purpose_).

I was mostly trying to addres the newcomer to Buildroot, and help him
find the documentation corresponding to the defconfig he is using.

We could really do better, as someone explained on IRC:

  - the manual does not even hint at running "make foo-defconfig" at
    all (only in the part targeted at the developer), but directly
    instructs to run "make menconfig" in the quick-start section. Adding
    a blurb that says there are pre-defined defconfig files would be
    nice.

  - the documentation for a defconfig file is not ostensibly exposed to
    the user of a defconfig file.

That's what I'm trying to address with this patch. And I think cattering
for company stuff is not a high priority : surely the boards docs are
hosted somewhere else than in the Buildroot (or br2-external) tree; and
if it is, then users (in that company!) know where to find it (or there
is anotgher problem, that is not related to the tool).

Of course, if we can find a way to get it to work for comany stuff
without too much trouble, that's fine. ;-)

Maybe I should have made my intentions clearer in the commit log, my
bad, and the patch was just quickly hacked in just under 5 minutes (and
is broken for br2-exteral anyway).

But anyway, this is just an RFC, and I got what I asked for: comments.
I'll consider these when reworking the patch. Thanks all! :-)

Regards,
Yann E. MORIN.

Hello Yann,

On Thursday 27 November 2014 18:46:28 Yann E. MORIN wrote:
> Jérôme, All,
> 
> On 2014-11-27 11:26 +0100, Jérôme Pouiller spake thusly:
> > On Thursday 27 November 2014 00:13:55 Yann E. MORIN wrote:
> > > This is an RFC!
> > > 
> > > When configuring Buildroot from a defconfig files, soem users complain
> > > it is non-obvious that the corresponding board documentattion is to be
> > > found in the board/ sub-directory.
> > > 
> > > So, deduce the board name from the defconfig file, look for a similarly
> > > named sub-dir of board (first level only), and if such a directory
> > > exists, print a message stating extra documentation for that board is to
> > > be found there.
> > 
> > What about introducing a BR2_BOARD_DIR configuration variable? This
> > variable> 
> > would have two functions:
> >    - May be used to locate other files (configs, overlays, etc...)
> >    - If defined, a help message is displayed when this defconfig is
> >    loaded.
> 
> The problem with using a Kconfig string variable is that Kconfig strgings
> that have no prompt can only take their default value, as defined in
> Config.in; if there is no default value, then the string option is not
> even stored in the .config file.
Why should we hide this configuration variable?