From 548c03f58b878fe685933e6e4d8209e80d37b8f5 Mon Sep 17 00:00:00 2001 From: devcurmudgeon Date: Mon, 16 Apr 2018 11:10:46 +0000 Subject: Update README.rst with more detail --- README.rst | 84 +++++++++++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 70 insertions(+), 14 deletions(-) (limited to 'README.rst') diff --git a/README.rst b/README.rst index 91a53393f..df1f72f1a 100644 --- a/README.rst +++ b/README.rst @@ -1,22 +1,78 @@ BuildStream -=========== +----------- .. image:: https://gitlab.com/BuildStream/buildstream/badges/master/coverage.svg?job=coverage :target: https://gitlab.com/BuildStream/buildstream/commits/master -BuildStream is a flexible and extensible framework for the modelling of build -pipelines in a declarative YAML format, written in python. +What is BuildStream? +==================== -These pipelines are composed of abstract elements which perform mutations on -on *filesystem data* as input and output, and are related to eachother by their -dependencies. +BuildStream is an Free Software tool for building/integrating software stacks. +It supports multiple build-systems (e.g. autotools, cmake, cpan, distutils, make, +meson, qmake), covers many programming languages, and can create outputs in a +range of packaging formats, for multiple platforms and chipsets. -Basic element types for importing SDKs in the form of tarballs or ostree checkouts, -building software components and exporting SDKs or deploying bootable filesystem images -will be included in BuildStream, but it is expected that projects forge their own custom -elements for doing more elaborate things such as deploying software in special ways. +Why should I use BuildStream? +============================= -Documentation -------------- -Please refer to the `complete documentation `_ -for more information about installing BuildStream, and about the BuildStream YAML format +BuildStream offers the following advantages: + +* **Declarative build instructions/definitions** + + BuildStream provides a a flexible and extensible framework for the modelling + of software build pipelines in a declarative YAML format, which allows you to + manipulate filesystem data in a controlled, reproducible sandboxed environment. + +* **Support for developer and integrator workflows** + + BuildStream provides traceability and reproducibility for integrators handling + stacks of hundreds/thousands of components, as well as workspace features and + shortcuts to minimise cycle-time for developers. + +* **Fast and predictable** + + BuildStream can cache previous builds and track changes to source file content + and build/config commands. BuildStream only rebuilds the things that have changed. + +* **Extensible** + + You can extend BuildStream to support your favourite build-system. + +* **Bootstrap toolchains and bootable systems** + + BuildStream can create full systems and complete toolchains from scratch, for + a range of ISAs including x86_32, x86_64, ARMv7, ARMv8, MIPS. + +How do I use BuildStream? +========================= + +Please refer to the `documentation `_ +for information about installing BuildStream, and about the BuildStream YAML format and plugin options. + +How does BuildStream work? +========================== + +BuildStream operates on a set of YAML files (.bst files), as follows: + +* loads the YAML files which describe the target(s) and all dependencies +* evaluates the version information and build instructions to calculate a build + graph for the target(s) and all dependencies and unique cache-keys for each + element +* retrieves elements from cache if they are already built, or builds them using + the instructions declared in the .bst files +* transforms and/or deploys the resulting target(s) based on the instructions + declared in the .bst files. + +How can I get started? +====================== + +The easiest way to get started is to explore some existing .bst files, for example: + +* https://gitlab.gnome.org/GNOME/gnome-build-meta/ +* https://gitlab.com/freedesktop-sdk/freedesktop-sdk +* https://gitlab.com/baserock/definitions +* https://gitlab.com/BuildStream/buildstream-examples/tree/x86image/build-x86image +* https://gitlab.com/BuildStream/buildstream-examples/tree/master/netsurf-flatpak + +If you have any questions please ask on our `#buildstream `_ channel in `irc.gnome.org `_ + -- cgit v1.2.1