BUILD_HOWTO 5.7 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150
  1. Libreboot Build System
  2. ======================
  3. Entry Point
  4. -----------
  5. The entry point for the Libreboot build system is the main script in the root
  6. directory named "libreboot". Running this script with no argument will show
  7. its general usage.
  8. Configuration
  9. -------------
  10. The build system can be configured with a script named "libreboot.conf" which
  11. must be located in the root directory.
  12. Typical usage of this file is for assigning environment variables. The list
  13. of environment variables is shown in the main script's general usage.
  14. Since this file is sourced by the build system after libraries are loaded it
  15. can also be used to override any of their functions or variables.
  16. Project and Tool Targets
  17. ------------------------
  18. The build system works around the concepts of projects and tools, that define
  19. specific components that can be used to produce either:
  20. * sources
  21. * systems
  22. * images
  23. * tools
  24. Various actions are available for each project and tool targets, many of which
  25. are shown in the main script's general usage. Each project and tool may provide
  26. a usage action that allows to see the specific usage for it. Actions are
  27. executed recursively when no targets are specified.
  28. Each project and tool target has its own directory (either in projects or tools)
  29. that contain a script named after the target and possible a helper script, named
  30. after the script with a "-helper" suffix. The helper script is automatically
  31. included by the build system. Functions in helper scripts are usually prefixed
  32. with the name of the target, where "-" symbols are replaced with "_" symbols.
  33. Each project and tool target's actions are functions defined in the target's
  34. specific script, with names matching the target's actions.
  35. Meta-Targets
  36. ------------
  37. Meta targets are project and tool targets that apply the requested action to
  38. individual targets, allowing to execute an action to many targets at once.
  39. For instance, a meta-target named after the build system with a "-all" suffix
  40. would call other meta-targets, prefixed with "-images", "-tools", etc that would
  41. then perform the requested action to all underlying targets.
  42. Projects Actions
  43. ----------------
  44. Various generic actions allow preparing projects through a series of steps:
  45. * downloading, extracting or updating the project's sources
  46. * building the project to a build directory
  47. * installing the project to an install directory
  48. * releasing the project to a release directory
  49. * cleaning the build, install and release directories
  50. Actions can be checked by a matching project-specific function, named after the
  51. function to check with a "_check" suffix, to determine whether it is necessary
  52. to run them again to follow the steps. An environment variable can force actions
  53. to be executed, by specifying a space-separated list of projects:
  54. PROJECTS_FORCE.
  55. Projects Configuration and Patches
  56. ----------------------------------
  57. Configuration for each project is stored in each project's own directory.
  58. Targets for each project are defined with a "targets" file in each directory
  59. of the "configs" directory. Targets are read recursively, following
  60. sub-directory names for project targets.
  61. Each project's configuration directory can be used to hold target-specific
  62. information and configuration.
  63. An "install" file in each sub-directory indicated which files to grab from the
  64. build files and where to install them in the install directory.
  65. Projects Sources
  66. ----------------
  67. Each project can either download specific sources or use another project's
  68. sources, possibly providing its own revision and patches.
  69. Sources are downloaded with the "download" action or can be extracted from
  70. released sources (after placing the sources in the sources directory) with the
  71. "extract" action.
  72. Projects may also keep their sources in a "sources" directory in their
  73. project-specific directory.
  74. Projects Build
  75. --------------
  76. Each project is built to a build directory, named after the project, with the
  77. list of targets separated by a "-" symbol.
  78. An environment variable allows controlling the number of tasks to run at the
  79. same time: TASKS.
  80. Projects Install
  81. ----------------
  82. Projects are installed from "install" files in the project directory, that
  83. copies the selected built files to the install directory, named after the
  84. project, with the list of targets separated by a "-" symbol. These install files
  85. are read recursively, following sub-directory names for project targets.
  86. Additional files to install can be specified in the "install" directory and
  87. described in an "install" file. These install files are read recursively,
  88. following sub-directory names for project targets.
  89. Projects Release
  90. ----------------
  91. Projects are released to a release directory, named after the project, with the
  92. list of targets separated by a "-" symbol. Each project's install files are
  93. packed into a tarball to the corresponding release directory. A checksum and a
  94. GPG detached signature (if the RELEASE_KEY environment variable is set) are also
  95. generated.
  96. Tarballs are generated reproducibly, from a list of files stored in the
  97. ".tarfiles" file. They may also contain the ".epoch", git ".revision" and
  98. ".version" files.
  99. Tools Actions
  100. -------------
  101. Tools are used for maintaining the build system, for performing routine tasks
  102. that can be automated. They may have specific actions and not implement any of
  103. the generic actions.
  104. Actions can be checked by a matching tool-specific function, named after the
  105. function to check with a "_check" suffix, to determine whether it is necessary
  106. to run them again to follow the steps. An environment variable can force actions
  107. to be executed, by specifying a space-separated list of tasks: TASKS_FORCE.
  108. Tools Sources
  109. -------------
  110. Tools may keep their sources in a "sources" directory in their tool-specific
  111. directory. These sources may be updated with the "update" action.