build-system: Allow out of tree BUILD_DIR

- Replace all users of `$(RIOTBASE)/build` with the already present
  `$(BUILD_DIR)` variable
- Replace all users of `$(BUILD_DIR)/pkg` with the already present
  `$(PKGDIRBASE)` variable
- Create a `CACHEDIR.TAG` file in the `$(BUILD_DIR)`

Makefile.include

@@ -56,7 +56,7 @@ BUILD_DIR                       ?= $(RIOTBASE)/build
 APPDIR                          ?= $(CURDIR)
 BINDIRBASE                      ?= $(APPDIR)/bin
 BINDIR                          ?= $(BINDIRBASE)/$(BOARD)
-PKGDIRBASE                      ?= $(RIOTBASE)/build/pkg
+PKGDIRBASE                      ?= $(BUILD_DIR)/pkg
 DLCACHE                         ?= $(RIOTTOOLS)/dlcache/dlcache.sh
 DLCACHE_DIR                     ?= $(RIOTBASE)/.dlcache
 RIOT_VERSION_DUMMY_CODE         ?= RIOT_VERSION_NUM\(2042,5,23,0\)
@@ -707,6 +707,7 @@ BUILDDEPS += $(RIOTBUILD_CONFIG_HEADER_C)
 BUILDDEPS += pkg-prepare
 BUILDDEPS += $(APPDEPS)
 BUILDDEPS += $(MODULE_LIST_DIR)
+BUILDDEPS += $(BUILD_DIR)/CACHEDIR.TAG
 
 # Build dependencies depend on clean (if a make goal), as clean may wipe them.
 # Without them depending on clean parallel builds occasionally fail due to
@@ -767,6 +768,11 @@ $(_SUBMAKE_LIBS): $(APPLICATION_MODULE).module pkg-build
 print-size: $(ELFFILE)
 	$(Q)$(SIZE) $(SIZEFLAGS) $<
 
+$(BUILD_DIR)/CACHEDIR.TAG:
+	$(Q)mkdir -p "$(BUILD_DIR)"
+	$(Q)echo "Signature: 8a477f597d28d172789f06886806bc55" > "$@"
+	$(Q)echo "# This folder contains RIOT's build cache" >> "$@"
+
 %.hex: %.elf
 	$(Q)$(OBJCOPY) $(OFLAGS) -Oihex $< $@
 

cpu/stm32/Makefile.cmsis

@@ -39,7 +39,7 @@ PKG_LICENSE=Apache-2
 
 # Store the cloned repositories under the stm32 directory to prevent downloads
 # for each builds.
-PKG_SOURCE_DIR = $(RIOTBASE)/build/stm32/cmsis/$(CPU_FAM)
+PKG_SOURCE_DIR = $(BUILD_DIR)/stm32/cmsis/$(CPU_FAM)
 PKG_PATCH_DIR = $(RIOTCPU)/stm32/include/vendor/patches/$(CPU_FAM)
 
 include $(RIOTBASE)/pkg/pkg.mk

cpu/stm32/Makefile.include

@@ -80,7 +80,7 @@ CFLAGS += -D__SYSTEM_STM32$(call uppercase,$(CPU_FAM))XX_H
 ifneq (,$(filter STM32F030x4 STM32MP157Cxx,$(CPU_LINE)))
   STM32CMSIS_INCLUDE_DIR = $(RIOTCPU)/stm32/include/vendor/cmsis/$(CPU_FAM)/Include
 else
-  STM32CMSIS_INCLUDE_DIR = $(RIOTBASE)/build/stm32/cmsis/$(CPU_FAM)/Include
+  STM32CMSIS_INCLUDE_DIR = $(BUILD_DIR)/stm32/cmsis/$(CPU_FAM)/Include
   STM32FAM_INCLUDE_FILE = $(STM32CMSIS_INCLUDE_DIR)/stm32$(CPU_FAM)xx.h
   INCLUDES += -I$(STM32CMSIS_INCLUDE_DIR)
 endif

cpu/stm32/dist/kconfig/README.md

@@ -13,7 +13,7 @@ the product selector tab, then click the `Export` button to download the Excel
 sheet (the default filename is `ProductsList.xlsx`).
 
 The available CPU lines are extracted from the
-`${RIOTBASE}/build/stm32/cmsis/<fam>/Include` directory. This means that the
+`${BUILD_DIR}/stm32/cmsis/<fam>/Include` directory. This means that the
 headers of a given family are already fetched here. This can be done with the
 following `make` commands:
 
@@ -42,7 +42,7 @@ a given family as follows:
 
 ```
 $ cd $RIOTBASE
-$ ./cpu/stm32/dist/kconfig/gen_kconfig.py ${RIOTBASE}/build/stm32/cmsis/<fam>/Include <cpu_fam> --sheets <path-to-sheet>/ProductsList.xlsx
+$ ./cpu/stm32/dist/kconfig/gen_kconfig.py ${BUILD_DIR}/stm32/cmsis/<fam>/Include <cpu_fam> --sheets <path-to-sheet>/ProductsList.xlsx
 ```
 
 The `--sheets` option can take several files. This allows to handle the L4 case
@@ -51,7 +51,7 @@ the command should be:
 
 ```
 $ cd $RIOTBASE
-$ ./cpu/stm32/dist/kconfig/gen_kconfig.py ${RIOTBASE}/build/stm32/cmsis/l4/Include l4 --sheets <path-to-sheet>/L4ProductsList.xlsx <path-to-sheet>/L4+ProductsList.xlsx
+$ ./cpu/stm32/dist/kconfig/gen_kconfig.py ${BUILD_DIR}/stm32/cmsis/l4/Include l4 --sheets <path-to-sheet>/L4ProductsList.xlsx <path-to-sheet>/L4+ProductsList.xlsx
 ```
 
 By default, if the `Kconfig.lines` and `Kconfig.models` files of a given family

dist/tools/openvisualizer/makefile.openvisualizer.inc.mk

@@ -39,7 +39,7 @@ OPENV_CLIENT_PATH := $(shell which openv-client)
 OPENV_SERIAL_PATH := $(shell which openv-serial)
 
 # Openvisualizer requires to know where openwsn-fw is located
-OPENV_OPENWSN_FW_PATH ?= --fw-path=$(RIOTBASE)/build/pkg/openwsn
+OPENV_OPENWSN_FW_PATH ?= --fw-path=$(PKGDIRBASE)/openwsn
 OPENV_DEFAULT_FLAGS += $(OPENV_OPENWSN_FW_PATH)
 
 OPENV_DEFAULT_FLAGS ?=

doc/doxygen/src/advanced-build-system-tricks.md

@@ -86,3 +86,10 @@ This will compile and link the application for every board available and record
 the result in the Makefile.ci. This requires the toolchain for every target to
 be available. The target supports using docker via the `BUILD_IN_DOCKER=1`
 variable.
+
+Out of Tree Cache Directory                            {#out-of-tree-cache-dir}
+===========================
+
+By exporting the `BUILD_DIR` environment variable, a custom build / clone cache
+directory can be created. This can be particularly useful when working with
+multiple git work trees or clones of the RIOT repository.

pkg/doc.txt

@@ -23,7 +23,7 @@
  * packages is fetched in a global location in:
  *
  * ~~~~~~~~ {.mk}
- * $(RIOTBASE)/build/pkg/$(PKG_NAME)
+ * $(PKGDIRBASE)/$(PKG_NAME)
  * ~~~~~~~~
  *
  * When out-of-source build is not possible (for example because the package

pkg/lvgl/Kconfig

@@ -254,6 +254,6 @@ menu "LVGL RIOT configuration"
 
 endmenu
 
-osource "$(RIOTBASE)/build/pkg/lvgl/Kconfig"
+osource "$(PKGDIRBASE)/lvgl/Kconfig"
 
 endif

tests/sys/fido2_ctap/Makefile

@@ -23,7 +23,7 @@ USB_PID ?= $(USB_PID_TESTING)
 # compiled natively (x86-64). Therefore we need to clear the flags set by e.g.
 # BOARD = nrf52840dk
 fido2-test:
-	env -i PATH=$(PATH) $(MAKE) -C $(RIOTBASE)/build/pkg/fido2_tests
+	env -i PATH=$(PATH) $(MAKE) -C $(PKGDIRBASE)/fido2_tests
 
 # FIDO2 user presence tests.
 #
@@ -33,6 +33,6 @@ fido2-test:
 # compiled natively (x86-64). Therefore we need to clear the flags set by e.g.
 # BOARD = nrf52840dk
 fido2-test-up:
-	env -i PATH=$(PATH) $(MAKE) -C $(RIOTBASE)/build/pkg/fido2_tests up-tests
+	env -i PATH=$(PATH) $(MAKE) -C $(PKGDIRBASE)/fido2_tests up-tests
 
 include $(RIOTBASE)/Makefile.include