diff --git a/Documentation/tutorial/managing_local_additions.md b/Documentation/tutorial/managing_local_additions.md index 6ca5971164..29ebcb35f6 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 @@ 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: