Update README.rst with more detailps-update-readmedevcurmudgeon/buildstream-ps-update-readme

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>`_
+