summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authordevcurmudgeon <paul.sherwood@codethink.co.uk>2018-04-16 11:10:46 +0000
committerPaul Sherwood <paul.sherwood@codethink.co.uk>2018-04-16 16:29:44 +0100
commita1ff633c41d0b39912fdf286e11be96bb158121d (patch)
tree4eb07f412624cbe2bbc771d8efc1e6cc6ad70bbd
parenteb0ad4d432ac4ab2680f1f677d28ebc3ed73f63c (diff)
downloadbuildstream-devcurmudgeon/buildstream-ps-update-readme.tar.gz
-rw-r--r--README.rst90
1 files changed, 73 insertions, 17 deletions
diff --git a/README.rst b/README.rst
index f80507d33..8bd3573ca 100644
--- a/README.rst
+++ b/README.rst
@@ -1,19 +1,75 @@
BuildStream
-===========
-BuildStream is a flexible and extensible framework for the modelling of build
-pipelines in a declarative YAML format, written in python.
-
-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.
-
-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.
-
-Documentation
--------------
-Please refer to the `complete documentation <https://buildstream.gitlab.io/buildstream/>`_
-for more information about installing BuildStream, and about the BuildStream YAML format
+-----------
+What is BuildStream?
+====================
+
+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.
+
+Why should I use BuildStream?
+=============================
+
+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 <https://buildstream.gitlab.io/buildstream/>`_
+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/sam/netsurf
+
+If you have any questions please ask on our `#buildstream <irc://irc.gnome.org/buildstream>`_ channel in `irc.gnome.org <irc://irc.gnome.org>`_
+