[riot-notifications] [RIOT-OS/RIOT] Makefile.include: introduce 'BOARDSDIR' for boards directory (#12183)

Gaëtan Harter notifications at github.com
Mon Sep 9 18:27:59 CEST 2019


### Contribution description 
  
Introduce a new variable 'BOARDSDIR' to use when referencing the base
boards directory.

The goal is to replace using 'RIOTBOARD' by 'BOARDSDIR' to define external boards. With this, external boards could still use 'RIOTBOARD' to use, for example, 'RIOT/boards/common' files.


### Help needed

#### Naming

Does the name fit? I tried something that was not prepended by `RIOT` directly to say it is not a RIOT/something directory, but ended up not being namespaced anymore.
I did not use 'external' either, as it should be the one used when refering to boards inside riot too.

I can replace it and update all the commit messages accordingly, it was easier to go with something and test than wait until I find the right name.

#### Documentation

Was there a documentation to say to use `RIOTBOARD` for external boards? a git grep finds nothing.

I can add a documentation in http://doc.riot-os.org/advanced-build-system-tricks.html

#### Does it fit your needs?

Does the wrapping works for you?

It did the choice to not overwrite the variable anymore even if set from the command line (make BOARDSDIR=lala) as it is not a normal make behavior.

The implementation also still does `BOARDSDIR := $(

#### Special for @bergzand 

No currently I do not pass this variable to `riotboot` when building the bootloader as `RIOTBOARD` was not passed either.

### Testing procedure

I added an example in `tests/external_board_native/` that declares an external `native` board. Using `native` name will allow murdock to run the test.


<details><summary><code>make --no-print-directory -C tests/external_board_native/ flash test</code></summary>

```
make --no-print-directory -C tests/external_board_native/ flash test 
Building application "external_board" for "native" with MCU "native".

"make" -C /home/harter/work/git/RIOT/core
"make" -C /home/harter/work/git/RIOT/cpu/native
"make" -C /home/harter/work/git/RIOT/cpu/native/periph
"make" -C /home/harter/work/git/RIOT/cpu/native/vfs
"make" -C /home/harter/work/git/RIOT/drivers
"make" -C /home/harter/work/git/RIOT/drivers/periph_common
"make" -C /home/harter/work/git/RIOT/sys
"make" -C /home/harter/work/git/RIOT/sys/auto_init
"make" -C /home/harter/work/git/RIOT/tests/external_board_native/external_boards/native
"make" -C /home/harter/work/git/RIOT/boards/native
"make" -C /home/harter/work/git/RIOT/boards/native/drivers
   text    data     bss     dec     hex filename
  20410     572   47652   68634   10c1a /home/harter/work/git/RIOT/tests/external_board_native/bin/native/external_board.elf
true 
/home/harter/work/git/RIOT/tests/external_board_native/bin/native/external_board.elf  
RIOT native interrupts/signals initialized.
LED_RED_OFF
LED_GREEN_ON
RIOT native board initialized.
RIOT native hardware initialization complete.

main(): This is RIOT! (Version: 2019.10-devel-693-g7b80d-pr/boardsdir)
Hello World!
You are running RIOT on a(n) native board.
THIS_BOARD_IS external_native
This board is 'An external extended native'
Test successful!!

```
</details>

Listing boards only lists the external boards. It is not a boards path search implementation.

```
make --no-print-directory -C tests/external_board_native/ info-boards
native
```

Building in docker is supported. I implemented it such as the `BOARDSDIR` is always set from the command line (when not `RIOTBOARD`), to allow overwriting any value that could be set in the makefile to an absolute path not depending on build path.

As I am building on an `ubuntu:bionic`, as our docker image, I can even run the native executable locally.

<details><summary><code>BUILD_IN_DOCKER=1 DOCKER="sudo docker" make --no-print-directory -C tests/external_board_native/ flash test </code></summary>

```
BUILD_IN_DOCKER=1 DOCKER="sudo docker" make --no-print-directory -C tests/external_board_native/ flash test 
Launching build container using image "riot/riotbuild:latest".
sudo docker run --rm -t -u "$(id -u)" \
    -v '/usr/share/zoneinfo/Europe/Berlin:/etc/localtime:ro' -v '/home/harter/work/git/RIOT:/data/riotbuild/riotbase' -e 'RIOTBASE=/data/riotbuild/riotbase' -e 'CCACHE_BASEDIR=/data/riotbuild/riotbase' -e 'BUILD_DIR=/data/riotbuild/riotbase/build' -e 'RIOTPROJECT=/data/riotbuild/riotbase' -e 'RIOTCPU=/data/riotbuild/riotbase/cpu' -e 'RIOTBOARD=/data/riotbuild/riotbase/boards' -e 'RIOTMAKE=/data/riotbuild/riotbase/makefiles' -v /home/harter/.gitcache:/data/riotbuild/gitcache -e GIT_CACHE_DIR=/data/riotbuild/gitcache    \
     \
    -w '/data/riotbuild/riotbase/tests/external_board_native/' \
    'riot/riotbuild:latest' make    'BOARDSDIR=/data/riotbuild/riotbase/tests/external_board_native/external_boards'
[sudo] password for harter: 
Building application "external_board" for "native" with MCU "native".

"make" -C /data/riotbuild/riotbase/core
"make" -C /data/riotbuild/riotbase/cpu/native
"make" -C /data/riotbuild/riotbase/cpu/native/periph
"make" -C /data/riotbuild/riotbase/cpu/native/vfs
"make" -C /data/riotbuild/riotbase/drivers
"make" -C /data/riotbuild/riotbase/drivers/periph_common
"make" -C /data/riotbuild/riotbase/sys
"make" -C /data/riotbuild/riotbase/sys/auto_init
"make" -C /data/riotbuild/riotbase/tests/external_board_native/external_boards/native
"make" -C /data/riotbuild/riotbase/boards/native
"make" -C /data/riotbuild/riotbase/boards/native/drivers
   text    data     bss     dec     hex filename
  20410     572   47652   68634   10c1a /data/riotbuild/riotbase/tests/external_board_native/bin/native/external_board.elf
true 
/home/harter/work/git/RIOT/tests/external_board_native/bin/native/external_board.elf  
RIOT native interrupts/signals initialized.
LED_RED_OFF
LED_GREEN_ON
RIOT native board initialized.
RIOT native hardware initialization complete.

main(): This is RIOT! (Version: 2019.10-devel-693-g7b80d-pr/boardsdir)
Hello World!
You are running RIOT on a(n) native board.
THIS_BOARD_IS external_native
This board is 'An external extended native'
Test successful!!

```
</details>

When the directory is not in `RIOT`, the mounting is handled correctly:

<details><summary>Build in docker with out of tree `BOARDSDIR`</summary>

```
cp tests/external_board_native/external_boards/ /tmp -r
```

```
BUILD_IN_DOCKER=1 DOCKER="sudo docker" make --no-print-directory -C tests/external_board_native/ clean flash test  BOARDSDIR=/tmp/external_boards/
Launching build container using image "riot/riotbuild:latest".
sudo docker run --rm -t -u "$(id -u)" \
    -v '/usr/share/zoneinfo/Europe/Berlin:/etc/localtime:ro' -v '/home/harter/work/git/RIOT:/data/riotbuild/riotbase' -e 'RIOTBASE=/data/riotbuild/riotbase' -e 'CCACHE_BASEDIR=/data/riotbuild/riotbase' -e 'BUILD_DIR=/data/riotbuild/riotbase/build' -e 'RIOTPROJECT=/data/riotbuild/riotbase' -e 'RIOTCPU=/data/riotbuild/riotbase/cpu' -e 'RIOTBOARD=/data/riotbuild/riotbase/boards' -e 'RIOTMAKE=/data/riotbuild/riotbase/makefiles' -v /home/harter/.gitcache:/data/riotbuild/gitcache -e GIT_CACHE_DIR=/data/riotbuild/gitcache   -v '/tmp/external_boards:/data/riotbuild/boards'  \
     \
    -w '/data/riotbuild/riotbase/tests/external_board_native/' \
    'riot/riotbuild:latest' make    'BOARDSDIR=/data/riotbuild/boards'
Building application "external_board" for "native" with MCU "native".

"make" -C /data/riotbuild/boards/native
"make" -C /data/riotbuild/riotbase/boards/native
"make" -C /data/riotbuild/riotbase/boards/native/drivers
"make" -C /data/riotbuild/riotbase/core
"make" -C /data/riotbuild/riotbase/cpu/native
"make" -C /data/riotbuild/riotbase/cpu/native/periph
"make" -C /data/riotbuild/riotbase/cpu/native/vfs
"make" -C /data/riotbuild/riotbase/drivers
"make" -C /data/riotbuild/riotbase/drivers/periph_common
"make" -C /data/riotbuild/riotbase/sys
"make" -C /data/riotbuild/riotbase/sys/auto_init
   text    data     bss     dec     hex filename
  20410     572   47652   68634   10c1a /data/riotbuild/riotbase/tests/external_board_native/bin/native/external_board.elf
true
/home/harter/work/git/RIOT/tests/external_board_native/bin/native/external_board.elf
RIOT native interrupts/signals initialized.
LED_RED_OFF
LED_GREEN_ON
RIOT native board initialized.
RIOT native hardware initialization complete.

main(): This is RIOT! (Version: 2019.10-devel-693-g7b80d-pr/boardsdir)
Hello World!
You are running RIOT on a(n) native board.
THIS_BOARD_IS external_native
This board is 'An external extended native'
Test successful!!

```
</details>

<details><summary>Building a normal example does not show any BOARDSDIR handling in docker as it should</summary>

```
BUILD_IN_DOCKER=1 DOCKER="sudo docker" make --no-print-directory -C examples/hello-world/ 
Launching build container using image "riot/riotbuild:latest".
sudo docker run --rm -t -u "$(id -u)" \
    -v '/usr/share/zoneinfo/Europe/Berlin:/etc/localtime:ro' -v '/home/harter/work/git/RIOT:/data/riotbuild/riotbase' -e 'RIOTBASE=/data/riotbuild/riotbase' -e 'CCACHE_BASEDIR=/data/riotbuild/riotbase' -e 'BUILD_DIR=/data/riotbuild/riotbase/build' -e 'RIOTPROJECT=/data/riotbuild/riotbase' -e 'RIOTCPU=/data/riotbuild/riotbase/cpu' -e 'RIOTBOARD=/data/riotbuild/riotbase/boards' -e 'RIOTMAKE=/data/riotbuild/riotbase/makefiles' -v /home/harter/.gitcache:/data/riotbuild/gitcache -e GIT_CACHE_DIR=/data/riotbuild/gitcache    \
     \
    -w '/data/riotbuild/riotbase/examples/hello-world/' \
    'riot/riotbuild:latest' make    
Building application "hello-world" for "native" with MCU "native".
...
```
</details>


### Issues/PRs references

Was referenced as an issue in https://github.com/RIOT-OS/RIOT/issues/11155
Also talked about it with different persons during the RIOT summit.

You can view, comment on, or merge this pull request online at:

  https://github.com/RIOT-OS/RIOT/pull/12183

-- Commit Summary --

  * Makefile.include: allow directories that cannot be overridden
  * Makefile.include: introduce 'BOARDSDIR' for boards directory
  * makefiles: use 'BOARDSDIR' for the boards directory in compilation
  * tools: use 'BOARDSDIR' for the boards directory
  * makefiles/docker: handle mounting 'BOARDSDIR'
  * makefiles/vars.inc.mk: document BOARDSDIR as external boards directory
  * examples: update documentation to use 'BOARDSDIR'
  * makefiles: deprecate 'RIOTBOARD' for 'BOARDSDIR'
  * tests/external_board_native: show an example of external board

-- File Changes --

    M Makefile.dep (2)
    M Makefile.features (2)
    M Makefile.include (35)
    M dist/gdbinit-docker (2)
    M dist/tools/openocd/openocd.sh (4)
    M dist/tools/renode/run-renode.sh (4)
    M examples/default/Makefile (2)
    M examples/riot_and_cpp/Makefile (2)
    M makefiles/application.inc.mk (2)
    M makefiles/boards.inc.mk (6)
    M makefiles/docker.inc.mk (6)
    M makefiles/info.inc.mk (2)
    M makefiles/scan-build.inc.mk (1)
    M makefiles/tools/avrdude.inc.mk (4)
    M makefiles/tools/openocd-adapters/stlink.inc.mk (2)
    M makefiles/tools/uniflash.inc.mk (6)
    M makefiles/vars.inc.mk (3)
    A tests/external_board_native/Makefile (14)
    A tests/external_board_native/README.md (14)
    A tests/external_board_native/external_boards/native/Makefile (6)
    A tests/external_board_native/external_boards/native/Makefile.dep (4)
    A tests/external_board_native/external_boards/native/Makefile.features (1)
    A tests/external_board_native/external_boards/native/Makefile.include (7)
    A tests/external_board_native/external_boards/native/external_native.c (3)
    A tests/external_board_native/external_boards/native/include/external_native.h (36)
    A tests/external_board_native/main.c (34)
    A tests/external_board_native/tests/01-run.py (22)

-- Patch Links --

https://github.com/RIOT-OS/RIOT/pull/12183.patch
https://github.com/RIOT-OS/RIOT/pull/12183.diff

-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/RIOT-OS/RIOT/pull/12183
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.riot-os.org/pipermail/notifications/attachments/20190909/c652f6d4/attachment-0001.htm>


More information about the notifications mailing list