erebion/coreboot
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Documentation/tutorial/managing_local_additions.md: Add symlink info

Browse source 
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 <nickkochlowski@gmail.com>
Reviewed-on: https://review.coreboot.org/c/coreboot/+/84740
Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
Reviewed-by: Ana Carolina Cabral
Reviewed-by: Nicholas Chin <nic.c3.14@gmail.com>
This commit is contained in:
Nicolas Kochlowski 2024-10-11 14:32:58 -03:00 • committed by Felix Held
commit 78270ef3f1
1 changed files with 56 additions and 9 deletions
Download patch file Download diff file Expand all files Collapse all files

65
Documentation/tutorial/managing_local_additions.md
View file

@ -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 @@ and any changes made there won't ever conflict with upstream changes.
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: