Author: Paul Kocialkowski <email@example.com>
Date: Fri, 23 Dec 2016 15:58:09 +0100
Signed-off-by: Paul Kocialkowski <firstname.lastname@example.org>
|README|| | ||141||+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++|
1 file changed, 141 insertions(+), 0 deletions(-)
diff --git a/README b/README
@@ -0,0 +1,141 @@
+Paper Build System
+The entry point for using the paper build system is the main script in the root
+directory, named after the build system (paper, libreboot, etc).
+Running the main script with no argument will show its general usage.
+The paper build system can be configured with a script named after the build
+system (paper, libreboot, etc) with a ".conf" suffix. It is automatically loaded
+by the build system when running the main script.
+It contains environment variables assigned to the desired values. The list of
+environment variables is shown in the main script's general usage.
+Project and Tool Targets
+The build system works around the concepts of projects and tools, that define
+specific components that can be used to produce either:
+Various actions are available for each project and tool targets, many of which
+are shown in the main script's general usage. Each project and tool may provide
+a usage action that allows to see the specific usage for it. Actions are
+executed recursively when no targets are specified.
+Each project and tool target has its own directory (either in projects or tools)
+that contain a script named after the target and possible a helper script, named
+after the script with a "-helper" suffix. The helper script is automatically
+included by the build system. Functions in helper scripts are usually prefixed
+with the name of the target.
+Meta targets are project and tool targets that apply the requested action to
+individual targets, allowing to execute an action to many targets at once.
+For instance, a meta-target named after the build system with a "-all" suffix
+would call other meta-targets, prefixed with "-images", "-tools", etc that would
+then perform the requested action to all underlying targets.
+Various generic actions allow preparing projects through a series of steps:
+* downloading, extracting or updating the project's sources
+* building the project to a build directory
+* installing the project to an install directory
+* releasing the project to a release directory
+* cleaning the build, install and release directories
+Actions can be checked by a specific project-specific function to determine
+whether it is necessary to run them again to follow the steps. An environment
+variable can force actions to be executed, by specifying a space-separated list
+of projects: PROJECTS_FORCE.
+Projects Configuration and Patches
+Configuration for each project is stored in each project's own directory.
+Targets for each project are defined with a "targets" file in each directory
+of the "configs" directory. Targets are read recursively, following
+sub-directory names for project targets.
+Each project's configuration directory can be used to hold target-specific
+information and configuration.
+An "install" file in each sub-directory indicated which files to grab from the
+build files and where to install them in the install directory.
+Each project can either download specific sources or use another project's
+sources, possibly providing its own revision and patches.
+Sources are downloaded with the "download" action or can be extracted from
+released sources (after placing the sources in the sources directory) with the
+Projects may also keep their sources in a "sources" directory in their
+Each project is built to a build directory, named after the project, with the
+list of targets separated by a "-" symbol.
+An environment variable allows controlling the number of tasks to run at the
+same time: TASKS.
+Projects are installed from "install" files in the project directory, that
+copies the selected built files to the install directory, named after the
+project, with the list of targets separated by a "-" symbol. These install files
+are read recursively, following sub-directory names for project targets.
+Additional files to install can be specified in the "install" directory and
+described in an "install" file. These install files are read recursively,
+following sub-directory names for project targets.
+Projects are released to a release directory, named after the project, with the
+list of targets separated by a "-" symbol. Each project's install files are
+packed into a tarball to the corresponding release directory. A checksum and a
+GPG detached signature (if the RELEASE_KEY environment variable is set) are also
+Tarballs are generated reproducibly, from a list of files stored in the
+".tarfiles" file. They may also contain the ".epoch", git ".revision" and
+Tools are used for maintaining the build system, for performing routine tasks
+that can be automated. They may have specific actions and not implement any of
+the generic actions.
+An environment variable can force actions to be executed, by specifying a
+space-separated list of tasks: TASKS_FORCE.
+Tools may keep their sources in a "sources" directory in their tool-specific
+directory. These sources may be updated with the "update" action.