getting_started.rst: Add Getting started section

Sections added: Motivation, What is BuildStream and Basic Concepts

2 files changed, 52 insertions, 0 deletions

diff --git a/doc/source/getting_started.rst b/doc/source/getting_started.rst
new file mode 100644
index 000000000..db9f9ee30
--- /dev/null
+++ b/doc/source/getting_started.rst
@@ -0,0 +1,51 @@
+
+
+.. _getting_started:
+
+Getting started
+===============
+
+
+Motivation
+----------
+Build tools are used to automate the creation of a software build and the associated processes.
+They are essential in environments where there are many, inter-connected projects as it gets hard
+to keep track of: what needs to be built, in what sequence things need to be built, and what
+*dependencies* (files/packages that are required in order for an application to run) there
+are in the process. Using a build tool allows this process to become more consistent.
+
+In addition to this, large projects are typically built in various ways, which means that the
+project may invoke more than one build tool.
+BuildStream hopes to centralise all of this so that users need only maintain one
+single set of core module metadata in one repository, in the same declarative YAML format.
+
+
+"So, what is BuildStream?"
+--------------------------
+BuildStream is a command line tool that executes software build and integration pipelines - it is
+**NOT** a build tool, rather, an integration tool which can delegate the building of software
+to other build tools.
+Builds are produced in a sandboxed environment which does not allow access to the host OS, this
+guarantees the reproducibility of builds and allows for build results to be shared between multiple
+developers.
+
+
+Basic concepts of BuildStream
+-----------------------------
+The command line executable for BuildStream is: `bst`. We execute this command
+when operating within a **project**, where a project contains **elements**. Elements describe
+*how* we should build a component of the software-stack from its **sources**.
+
+Projects can be of any size and can also depend on other BuildStream projects. It is
+recommended to keep each project in a separate Git repository. 
+
+The top-level directory of the project is marked by a `project.conf` file, which sets the
+project-wide configuration options and is written in YAML format. To reemphasise, `bst`
+commands should be run from this directory.
+
+Elements are typically stored in a project's sub-directory aptly named *elements*. In this
+directory each element is represented by a *.bst* file. *.bst* files use YAML syntax.
+
+Within an element (*.bst* file), there are various attributes (nodes) that authors
+can control. However, it should be noted that BuildStream aims to provide sensible default
+values for attributes that are not explicitly set/declared by the user.
diff --git a/doc/source/main_using.rst b/doc/source/main_using.rst
index c95a4b51d..68812d3f3 100644
--- a/doc/source/main_using.rst
+++ b/doc/source/main_using.rst
@@ -10,5 +10,6 @@ This section details how to use the BuildStream command line interface and work
 .. toctree::
    :maxdepth: 2
 
+   getting_started
    commands
    user_config