README 5.7 KB

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