Documentation/tutorial/managing_local_additions.md

   1 # Managing local additions
   2
   3 This section describes the site-local mechanism, what it is good for and
   4 how it can be used.
   5
   6 ## What is site-local?
   7 site-local is the name of a directory that won't ever appear in the
   8 upstream coreboot repository but is referred to in several key places of its
   9 configuration and build system. The intent is provide a single location to
  10 store local modifications.
  11
  12 By keeping local additions to builds in this place, it can be versioned
  13 independently from upstream (e.g. controlled by git in another repository)
  14 and any changes made there won't ever conflict with upstream changes.
  15
  16 This optional directory is searched for in the top-level of the coreboot
  17 repo and is called `site-local`.
  18
  19 A common approach for developing and testing internal additions to coreboot
  20 from the site-local directory is to use `symlink` targets. By replicating
  21 the coreboot directory structure within site-local and creating a
  22 `symlink.txt` file that contains the path (relative to the root of the
  23 coreboot directory), the `symlink` target can recursively scan the
  24 site-local directory and create symbolic links into the coreboot tree,
  25 allowing the build process to proceed as if the additions were integrated
  26 directly into the main coreboot tree. The `symlink.txt` file must be placed
  27 at the root of the new directory.
  28
  29 The following targets can be used to create/remove the symlinks:
  30
  31 `make symlink` - Creates symbolic links from site-local into coreboot tree
  32 `make clean-symlink` - Removes symbolic links created by `make symlink`
  33 `make cleanall-symlink` - Removes all symbolic links in the coreboot tree
  34
  35 ### Example symlink usage
  36 Directory structure with symlink from site-local into coreboot:
  37
  38 ```
  39 coreboot/
  40 ├── src/
  41 │   └── soc/
  42 │       ├── amd/
  43 │       ├── cavium/
  44 │       ├── example/
  45 │       ├── ...
  46 │       └── test-soc-from-site-local -> ../../site-local/src/soc/test-soc-from-site-local/
  47 └── site-local/
  48     ├── Kconfig
  49     ├── Makefile.mk
  50     └── src/
  51         └── soc/
  52             └── test-soc-from-site-local/
  53                 └── symlink.txt
  54 ```
  55
  56 Contents of `symlink.txt`:
  57
  58 ```
  59 src/soc/test-soc-from-site-local
  60 ```
  61
  62 *Note:* To keep the symlinks updated throughout development, the following
  63 line may be added to `site-local/Makefile.mk` to declare symlink as a
  64 `site-local-target` dependency, ensuring the symlink target is run anytime
  65 `make` is executed:
  66 ```
  67 site-local-target:: symlink
  68 ```
  69
  70 ## Integration into the configuration system
  71 Kconfig includes `site-local/Kconfig` relatively early, so it can be used
  72 to pre-define some configuration before coreboot's regular ruleset sets
  73 up defaults.
  74
  75 ## Integration into the build system
  76 The build system includes, if present, `site-local/Makefile.mk`. The main
  77 purpose so far has been to add additional files to a CBFS image. A single
  78 Makefile.inc can serve multiple boards, for example:
  79
  80     cbfs-files-$(CONFIG_BOARD_INTEL_D945GCLF) += pci8086,2772.rom
  81     pci8086,2772.rom-file := intel_d945gclf/pci8086,2772.rom
  82     pci8086,2772.rom-type := optionrom
  83
  84     cbfs-files-$(CONFIG_BOARD_KONTRON_986LCD_M) += pci8086,27a2.rom
  85     pci8086,27a2.rom-file := kontron_986lcd-m/pci8086,27a2.rom
  86     pci8086,27a2.rom-type := optionrom
  87
  88 This adds the correct Option ROM binary (which are non-redistributable and
  89 therefore can't become part of the coreboot.org repos) to coreboot.rom when
  90 built for intel/d945gclf or kontron/986lcd-m.