[M] Change in coreboot[main]: Documentation/tutorial/managing_local_additions.md: Add symlink info

[Felix Held (Code Review)]

Felix Held has submitted this change. ( https://review.coreboot.org/c/coreboot/+/84740?usp=email )

Change subject: Documentation/tutorial/managing_local_additions.md: Add symlink info
......................................................................

Documentation/tutorial/managing_local_additions.md: Add symlink info

Add information about how the symlink target can be used
to develop and test additions to the coreboot tree from
site-local.

Change-Id: I75f9e9575005e9ee2f255848a21c5e57c30e9e72
Signed-off-by: Nicolas Kochlowski 
Reviewed-on: https://review.coreboot.org/c/coreboot/+/84740
Tested-by: build bot (Jenkins) 
Reviewed-by: Ana Carolina Cabral
Reviewed-by: Nicholas Chin 
---
M Documentation/tutorial/managing_local_additions.md
1 file changed, 56 insertions(+), 9 deletions(-)

Approvals:
  Nicholas Chin: Looks good to me, approved
  Ana Carolina Cabral: Looks good to me, but someone else must approve
  build bot (Jenkins): Verified

diff --git a/Documentation/tutorial/managing_local_additions.md b/Documentation/tutorial/managing_local_additions.md
index 6ca5971..29ebcb3 100644
--- a/Documentation/tutorial/managing_local_additions.md
+++ b/Documentation/tutorial/managing_local_additions.md
@@ -1,11 +1,9 @@
-Managing local additions
-========================
+# Managing local additions

This section describes the site-local mechanism, what it is good for and
 how it can be used.

-What is site-local?
--------------------
+## What is site-local?
 site-local is the name of a directory that won't ever appear in the
 upstream coreboot repository but is referred to in several key places of its
 configuration and build system. The intent is provide a single location to
@@ -18,15 +16,64 @@
 This optional directory is searched for in the top-level of the coreboot
 repo and is called `site-local`.

-Integration into the configuration system
------------------------------------------
+A common approach for developing and testing internal additions to coreboot
+from the site-local directory is to use `symlink` targets. By replicating
+the coreboot directory structure within site-local and creating a
+`symlink.txt` file that contains the path (relative to the root of the
+coreboot directory), the `symlink` target can recursively scan the
+site-local directory and create symbolic links into the coreboot tree,
+allowing the build process to proceed as if the additions were integrated
+directly into the main coreboot tree. The `symlink.txt` file must be placed
+at the root of the new directory.
+
+The following targets can be used to create/remove the symlinks:
+
+`make symlink` - Creates symbolic links from site-local into coreboot tree
+`make clean-symlink` - Removes symbolic links created by `make symlink`
+`make cleanall-symlink` - Removes all symbolic links in the coreboot tree
+
+### Example symlink usage
+Directory structure with symlink from site-local into coreboot:
+
+```
+coreboot/
+├── src/
+│   └── soc/
+│       ├── amd/
+│       ├── cavium/
+│       ├── example/
+│       ├── ...
+│       └── test-soc-from-site-local -> ../../site-local/src/soc/test-soc-from-site-local/
+└── site-local/
+    ├── Kconfig
+    ├── Makefile.mk
+    └── src/
+        └── soc/
+            └── test-soc-from-site-local/
+                └── symlink.txt
+```
+
+Contents of `symlink.txt`:
+
+```
+src/soc/test-soc-from-site-local
+```
+
+*Note:* To keep the symlinks updated throughout development, the following
+line may be added to `site-local/Makefile.mk` to declare symlink as a
+`site-local-target` dependency, ensuring the symlink target is run anytime
+`make` is executed:
+```
+site-local-target:: symlink
+```
+
+## Integration into the configuration system
 Kconfig includes `site-local/Kconfig` relatively early, so it can be used
 to pre-define some configuration before coreboot's regular ruleset sets
 up defaults.

-Integration into the build system
----------------------------------
-The build system includes, if present, `site-local/Makefile.inc`. The main
+## Integration into the build system
+The build system includes, if present, `site-local/Makefile.mk`. The main
 purpose so far has been to add additional files to a CBFS image. A single
 Makefile.inc can serve multiple boards, for example: