machine file: Add @GLOBAL_SOURCE_ROOT@ and @DIRNAME@

2 files changed, 25 insertions, 0 deletions

diff --git a/docs/markdown/Machine-files.md b/docs/markdown/Machine-files.md
index c300769..a3e876d 100644
--- a/docs/markdown/Machine-files.md
+++ b/docs/markdown/Machine-files.md
@@ -128,6 +128,18 @@ b = a + 'World'
 a = 'Hello'
 ```
 
+*Since 1.3.0* Some tokens are replaced in the machine file before parsing it:
+- `@GLOBAL_SOURCE_ROOT@`: the absolute path to the project's source tree
+- `@DIRNAME@`: the absolute path to the machine file's parent directory.
+
+It can be used, for example, to have paths relative to the source directory, or
+relative to toolchain's installation directory.
+```ini
+[binaries]
+c = '@DIRNAME@/toolchain/gcc'
+exe_wrapper = '@GLOBAL_SOURCE_ROOT@' / 'build-aux' / 'my-exe-wrapper.sh'
+```
+
 ### Binaries
 
 The binaries section contains a list of binaries. These can be used
diff --git a/docs/markdown/snippets/machine_file_source_dir.md b/docs/markdown/snippets/machine_file_source_dir.md
new file mode 100644
index 0000000..5af344e
--- /dev/null
+++ b/docs/markdown/snippets/machine_file_source_dir.md
@@ -0,0 +1,13 @@
+## `@GLOBAL_SOURCE_ROOT@` and `@DIRNAME@` in machine files
+
+Some tokens are now replaced in the machine file before parsing it:
+- `@GLOBAL_SOURCE_ROOT@`: the absolute path to the project's source tree
+- `@DIRNAME@`: the absolute path to the machine file's parent directory.
+
+It can be used, for example, to have paths relative to the source directory, or
+relative to toolchain's installation directory.
+```ini
+[binaries]
+c = '@DIRNAME@/toolchain/gcc'
+exe_wrapper = '@GLOBAL_SOURCE_ROOT@' / 'build-aux' / 'my-exe-wrapper.sh'
+```