blob: 4a4fc4c00a0a7c60bf38c2b5a027311c9978b137 [file] [log] [blame]
  1. This directory contains board and variant overlays. When a board is
  2. configured using "setup_board --board <board>" the following overlays are added
  3. to the make.conf PORTDIR_OVERLAY if they exist:
  4. src/overlays/overlay-<board>
  5. src/private-overlays/overlay-<board>-private
  6. When a board is configured using "setup_board --board <board> --variant
  7. <variant>" or "setup_board --board <board>_<variant>" the following overlays
  8. are added if they exist:
  9. src/overlays/overlay-<board>
  10. src/overlays/overlay-variant-<board>-<variant>
  11. src/private-overlays/overlay-<board>-private
  12. src/private-overlays/overlay-variant-<board>-<variant>-private
  13. If --variant is supplied to setup_board or the <board>_<variant> version
  14. of --board is supplied to setup_board then the primary variant overlay must
  15. exist.
  16. A private board overlay can augment an existing non-private board overlay,
  17. or can serve as the primary board overlay for a board with no non-private board
  18. overlay.
  19. All board overlays (including variants) should contain a make.conf. If
  20. this file exists it will be sourced in the order that the overlays and variants
  21. are listed above.
  22. All board overlays should contain a toolchain.conf, specifying the
  23. toolchains required to build that board. Variants can inherit toolchain.conf
  24. from their primary board overlay.
  25. The board and variant names can not have underscores or spaces in them.
  27. --------
  28. All overlays must contain a profiles directory with a repo_name file
  29. therein. The repo_name file provides a unique name Portage uses to identify
  30. each overlay or variant.
  31. Overlays and variants can also contain named profiles as subdirectories of
  32. the profiles directory. If the board overlay contains a "base" profile,
  33. Portage will use that by default for the board; otherwise, Portage will use a
  34. profile from chromiumos-overlay.
  35. Within a profile, a board overlay will most commonly want to specify
  36. package-specific USE flags via package.use, mask or unmask package versions via
  37. package.mask and package.unmask, or mask or unmask keywords via
  38. package.keywords. See "man portage" in the chroot for full details on those
  39. and other files that can appear in a profile.
  40. Profiles in a board overlay must have a file "parent", containing the full
  41. path of one of the profiles from chromiumos-overlay, as seen from the build
  42. chroot; /usr/local/portage/chromiumos/profiles in the chroot maps to
  43. src/third_party/chromiumos-overlay/profiles in the source tree. The parent
  44. must point to an architecture-appropriate profile, typically
  45. /usr/local/portage/chromiumos/profiles/default/linux/$arch/$version/chromeos.
  46. Profiles can use another profile from the same board as their parent, as long
  47. as the chain of parent profiles eventually leads to an architecture-appropriate
  48. profile from chromiumos-overlay.
  49. Adding a base profile to a board overlay that did not previously have a
  50. profile will require re-running setup_board with --force.
  52. -----------
  53. Overlays should contain a metadata directory with a layout.conf file
  54. therein. The layout.conf file specifies the "masters" list. This is a list of
  55. repository names, taken from the repo_name files in the overlays. This list
  56. disambiguates the selection of ebuilds. When two overlays supply the same
  57. ebuild the overlay whose repo_name is listed later in the masters list will be
  58. used. The masters list also effects the way that portage searches for
  59. eclasses. By having the repo_name "chromiumos" as the last entry in the
  60. masters list portage will correctly find the chromiumos specific eclasses.
  62. -----------------------
  63. A board overlay will typically want to provide additional packages to
  64. install. ChromiumOS builds install the chromeos/chromeos package by default,
  65. whose RDEPEND brings in all the packages installed by default.
  66. chromeos/chromeos RDEPENDs on the virtual package virtual/chromeos-bsp, which
  67. exists for board overlays to override. chromiumos-overlay provides a default
  68. version of virtual/chromeos-bsp which RDEPENDs on the empty package
  69. chromeos-base/chromeos-bsp-null. Board overlays should provide a
  70. virtual/chromeos-bsp package that RDEPENDs on
  71. chromeos-base/chromeos-bsp-boardname, and a
  72. chromeos-base/chromeos-bsp-boardname package that RDEPENDs on any desired
  73. board-specific packages.
  74. A board overlay can also provide additional packages to install in dev
  75. builds only, via similar packages virtual/chromeos-bsp-dev and
  76. chromeos-base/chromeos-bsp-dev-boardname. ChromiumOS dev builds install
  77. chromeos-base/chromeos-dev by default, which RDEPENDs on
  78. virtual/chromeos-bsp-dev.
  79. Note that a board overlay cannot specify package-specific USE flags by
  80. using an RDEPEND with a use flag, such as section/package[useflag]; instead,
  81. add "section/package useflag" to package.use in a profile.
  83. ---------------------
  84. The host (non-cross-compiling) build environment will use the following
  85. overlay if it exists:
  86. src/private-overlays/chromeos-overlay
  87. This overlay contains private packages needed on the host system to compile
  88. target packages used in a private overlay. Packages only needed on the target
  89. system should appear in a private board overlay. The packages in a private
  90. host overlay should typically all appear in the dependency chain of
  91. chromeos-base/hard-host-depends so that the build process will install them on
  92. the host system at the appropriate time. chromeos-base/hard-host-depends
  93. depends on the virtual package virtual/hard-host-depends-bsp to allow a private
  94. host overlay to extend the host dependencies; a private host overlay can
  95. provide a version 2 ebuild for virtual/hard-host-depends-bsp, and list any
  96. additional host dependencies in the RDEPEND of that package.
  97. Like a board overlay, a private host overlay must include a layout.conf
  98. with "masters" set, so that the packages within that host overlay can reference
  99. eclasses from the parent overlays chromiumos-overlay or portage-stable.