From e47fea7bf57698116c0c0833bb25ab48b63a86db Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ga=C3=ABtan=20Harter?= <gaetan.harter@fu-berlin.de>
Date: Wed, 5 Dec 2018 15:22:20 +0100
Subject: [PATCH] doc/advanced-build-system-tricks.md: add a doc for new
variables
Add a documentation page for advanced low level tricks.
Document the `RIOT_MAKEFILES_GLOBAL_PRE` and
`RIOT_MAKEFILES_GLOBAL_POST`.
I could not work around to have `$(RIOTBASE)/Makefile.include` in the
doc as the `$()` part was removed, so I kept with `$RIOTBASE` for now.
---
doc/doxygen/riot.doxyfile | 1 +
.../src/advanced-build-system-tricks.md | 40 +++++++++++++++++++
doc/doxygen/src/mainpage.md | 1 +
3 files changed, 42 insertions(+)
create mode 100644 doc/doxygen/src/advanced-build-system-tricks.md
diff --git a/doc/doxygen/riot.doxyfile b/doc/doxygen/riot.doxyfile
index 6ca9d7fd2a..0e07440cd3 100644
--- a/doc/doxygen/riot.doxyfile
+++ b/doc/doxygen/riot.doxyfile
@@ -765,6 +765,7 @@ INPUT = ../../doc.txt \
src/creating-modules.md \
src/creating-an-application.md \
src/getting-started.md \
+ src/advanced-build-system-tricks.md \
src/changelog.md \
../../LOSTANDFOUND.md
diff --git a/doc/doxygen/src/advanced-build-system-tricks.md b/doc/doxygen/src/advanced-build-system-tricks.md
new file mode 100644
index 0000000000..9c3d13c9e0
--- /dev/null
+++ b/doc/doxygen/src/advanced-build-system-tricks.md
@@ -0,0 +1,40 @@
+Advanced build system tricks {#advanced-build-system-tricks}
+============================
+
+[TOC]
+
+Introduction {#introduction}
+============
+
+This page describes some build systems tricks that can help developers but are
+not part of the standard workflow.
+
+They are low level commands that should not be taken as part of a stable API
+but better have a documentation than only having a description in the build
+system code.
+
+
+Customize the build system {#customize-build-system}
+==========================
+
++ `RIOT_MAKEFILES_GLOBAL_PRE`: files parsed before the body of
+ `$RIOTBASE/Makefile.include`
++ `RIOT_MAKEFILES_GLOBAL_POST`: files parsed after the body of
+ `$RIOTBASE/Makefile.include`
+
+The variables are a list of files that will be included by
+`$RIOTBASE/Makefile.include`.
+They will be handled as relative to the application directory if the path is
+relative.
+
+
+Usage
+-----
+
+You can configure your own files that will be parsed by the build system main
+`Makefile.include` file before or after its main body, examples usages can be:
+
+* Globally overwrite a variable, like `TERMPROG`
+* Specify a hard written `PORT` / `DEBUG_ADAPTER_ID` for some BOARD values
+* Define your custom targets
+* Override default targets
diff --git a/doc/doxygen/src/mainpage.md b/doc/doxygen/src/mainpage.md
index a3ae57898f..c2788cbb86 100644
--- a/doc/doxygen/src/mainpage.md
+++ b/doc/doxygen/src/mainpage.md
@@ -235,6 +235,7 @@ Further information {#further-information}
- @ref getting-started
- @ref creating-an-application
- @ref creating-modules
+ - @ref advanced-build-system-tricks
<!--
Idea for this section: just name each of RIOT's main features/concepts and link
--
GitLab